eveswag - EVE Swagger Interface

Originally developed for LittleUFO as a swagger-client replacement, but departed to be stand-alone, this module offers:

• No limits in tokens
  Aimed towards big projects with lots of users, every auth-protected call can take its own auth token and scopes list.
• Scopes
  Every auth-protected call is checked against provided list of scopes, so you don't have to worry about it.
• Endpoints status
  You can always view status of the endpoints without delay.
• Error tolerance
  It can avoid many known errors often happening on ESI by making multiple attempts where it is safe (bad gateway, timeout, etc), and presents errors in a readable format.
• Avoidance of endpoints with yellow/red status
  As an optional feature, it helps you to deal with problematic endpoints.
• Endpoint upgrade notifications
  When some endpoint will soon be upgraded or deprecated, module notify about it in a log.
• Async
  Say goodbye to callback hell.
• Lightweight
  One file, one prerequisite.

And, as it was said before, this module is a part of a big active project, so it will receive a constant updates.

Installation

Install with
npm install eveswag --production (to skip development dependencies)

For development purposes:
npm install eveswag

See usage example in a constructor description.

Reference

eveswag

Kind: global class
Author: Shyaltii (in-EVE)
License: MIT

• eveswag
  • new eveswag(cfg)
  • instance
    • .log : function
    • .report : function
    • .userAgent : string
    • .proxy : string | boolean
    • .host : string
    • .version : string
    • .datasource : string
    • .language : string
    • .allowYellow : boolean
    • .allowRed : boolean
    • .statusRefresh : boolean
    • .lockuntil : null | number
    • .info : Object.<string, any>
    • .list : Object.<string, Object.<string, tListOperation>>
    • .apis : Object.<string, Object.<string, fCallOperation>>
    • .loadFile(file)
    • .loadRemote()
    • .loadScheme(scheme)
    • .health([op]) ⇒ 0 | 1 | 2
  • static
    • .fCallOperation ⇒ Promise.<Object>
    • .tListOperation : Object
    • .tError : Object

new eveswag(cfg)

EVE Swagger Interface

After new instance is created, call either loadFile(file), loadRemote() or loadScheme(scheme), and then use apis.Category.operation_name() to call an endpoint, list to see all endpoints mapping along with their required scopes and status, and info to see the scheme information.

Useful links: https://esi.evetech.net/ https://docs.esi.evetech.net/

| Param | Type | Default | Description | | --- | --- | --- | --- | | cfg | Object | | Configuration | | cfg.userAgent | string | | ESI-compliant user agent | | [cfg.allowYellow] | boolean | true | Allow calling an endpoint when its status is yellow | | [cfg.allowRed] | boolean | false | Allow calling an endpoint when its status is red | | [cfg.statusRefresh] | number | 300 | Specifies status refresh interval | | [cfg.host] | string | "https://esi.evetech.net" | Host to download specs from, that will be replaced by specs and used for requests | | [cfg.version] | string | "latest" | ESI specs version | | [cfg.datasource] | string | "tranquility" | Datasource | | [cfg.language] | string | "en-us" | Language | | [cfg.proxy] | string | boolean | false | String ("http://127.0.0.1:3080") or boolean (true - to use environment, false - to disable) | | [cfg.log] | function | fallback to console.log | console.log-like function with first parameter meaning the type of a message - "info" or "warning" | | [cfg.report] | function | stub | Function to report calls into: report("direct", "get_status") or report("error", "get_status"), because this class has a fallback mechanism and may retry some failed calls |

Example

const eveswag = require("eveswag");

// Create an instance with your project and your own name, as ESI recommends
const esi = new eveswag({
    userAgent: "My awesome EVE project (by EveName)"
});

// Load current specifications from a server
await esi.loadRemote();

// Get status and display online players count
let resp = await esi.apis.Status.get_status();
console.log("Pilots online:", resp.body.players);

~.log : function

console.log-like function with first parameter meaning the type of a message - "info" or "warning"

Kind: instance property of eveswag
Default: console.log fallback
Access: public

~.report : function

Function to report calls into: report("direct", "get_status") or report("error", "get_status"), because this class has a fallback mechanism and may retry some failed calls

Kind: instance property of eveswag
Default: stub
Access: public

~.userAgent : string

ESI-compliant user agent

Kind: instance property of eveswag
Access: public

~.proxy : string | boolean

String ("http://127.0.0.1:3080") or boolean (true - to use environment, false - to disable)

Kind: instance property of eveswag
Default: "false"
Access: public

~.host : string

Host to download specs from, that will be replaced by specs and used for requests

Kind: instance property of eveswag
Default: "https://esi.evetech.net"
Access: public

~.version : string

ESI specs version.

Kind: instance property of eveswag
Default: "latest"
Access: public

~.datasource : string

Datasource.

Kind: instance property of eveswag
Default: "tranquility"
Access: public

~.language : string

Language.

Kind: instance property of eveswag
Default: "en-us"
Access: public

~.allowYellow : boolean

Allow calling an endpoint when its status is yellow.

Kind: instance property of eveswag
Default: true
Access: public

~.allowRed : boolean

Allow calling an endpoint when its status is red.

Kind: instance property of eveswag
Default: false
Access: public

~.statusRefresh : boolean

Specifies status refresh interval.

Kind: instance property of eveswag
Default: 300
Access: public

~.lockuntil : null | number

If specified, we're softlocked by ESI until this time in epoch. You may reset this property to null to force new calls earlier.

Kind: instance property of eveswag
Default: null

~.info : Object.<string, any>

Object with scheme information.

Kind: instance property of eveswag
Access: public
Read only: true

~.list : Object.<string, Object.<string, tListOperation>>

Categorised API list with scopes and their current status. (Categories are defined for every operation by ESI tags.)

Structure:

{
    "Category": {
        "operation_id": {
            "scope": "esi.scope-name.v1" | null,
            "status": "unknown" | "green" | "yellow" | "red"
        },
        ...
    },
    ...
}

Kind: instance property of eveswag
Access: public
Read only: true
See: tListOperation

~.apis : Object.<string, Object.<string, fCallOperation>>

Categorised API list to call to. (Categories are defined for every operation by ESI tags.)

Call with:

await eveswag.apis.Category.operation_id([params: Object], [token: string], [scopes: string | string[]])
// params = object { character_id: 978869108 }
// token = access token
// scopes = list of scopes for this token: whitespace separated list or an array

Structure:

{
    "Category": {
        "operation_id": async function(),
        ...
    },
    ...
}

Kind: instance property of eveswag
Access: public
Read only: true
See: fCallOperation

~.loadFile(file)

Loads specs from a file.

Kind: instance method of eveswag

| Param | Type | Description | | --- | --- | --- | | file | string | Path to a scheme file |

~.loadRemote()

Downloads specs from web and calls this.load with them.

Kind: instance method of eveswag

~.loadScheme(scheme)

Generates all of the available endpoints and creates this.apis and this.list. It also triggers refresh of status list.

Kind: instance method of eveswag

| Param | Type | Description | | --- | --- | --- | | scheme | Object | string | EVE Swagger Interface specs |

~.health([op]) ⇒ 0 | 1 | 2

Checks health of an endpoint.

This function gets called on every API call as well.
And it will refresh ESI status if the time has come. To view a delayed status, use list instead

Kind: instance method of eveswag
Returns: 0 | 1 | 2 - -1 = unknown, 0 = green, 1 = yellow, 2 = red

| Param | Type | Description | | --- | --- | --- | | [op] | string | Operation ID |

eveswag.fCallOperation ⇒ Promise.<Object>

Operation call function inside eveswag.apis.

Kind: static property of eveswag
Returns: Promise.<Object> - Promise with full response object, flavoured with tError parameters if any.
Most likely you will receive something like this:

{
    headers: { headers object },
    body: { json reponse },
    ...and some more things
}

| Param | Type | Description | | --- | --- | --- | | [params] | Object | Requested parameters | | [token] | string | Auth token | | [scopes] | string | Array.<string> | Token scopes in an array or a string list |

eveswag.tListOperation : Object

Operation details inside eveswag.list

Kind: static abstract typedef of eveswag
Properties

| Name | Type | Description | | --- | --- | --- | | scope | null | string | Scope used by this endpoint. | | status | "unknown" | "green" | "yellow" | "red" | Current status of this endpoint. |

eveswag.tError : Object

Thrown error

Kind: static abstract typedef of eveswag
Properties

| Name | Type | Description | | --- | --- | --- | | err | "error" | "server" | "esi_status" | "scope_missing" | Short error name | | error | string | Error description |

Changelog

0.2.2

Scopes detection from access_token if scopes paremeter is missing.

0.2.1

Scopes detection mistake fix.

0.2.0

Refactoring, consistency, jsDoc.

New:

• cfg.allowYellow
• cfg.statusRefresh

Breaking changes:

• cfg.useragent renamed to cfg.userAgent
• cfg.allowred renamed to cfg.allowRed
• loadFromRemote renamed to loadRemote
• log is no longer object but a function

0.1.2

Improved error detection and implemented ESI error reader with a softlock.

0.1.1

On requests, scopes can take an array.

0.1.0

Initial release.

TODO

• Option to flatten apis and list (w/o categories, only operation ids)

Transfer from LittleUFO:

• Cache handling
• Notifications parser to natively present a baked json instead of yaml
• SSO pipeline maybe?

Contacts

Discord: Rainicorn#4886
EVE: Shyaltii
ISK donations appreciated ♥