eveswag

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

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.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 ♥

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
.eslintrc.json		.eslintrc.json
.gitignore		.gitignore
LICENSE		LICENSE
README.hbs		README.hbs
README.md		README.md
eveswag.js		eveswag.js
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

eveswag - EVE Swagger Interface

Installation

Reference

eveswag

new eveswag(cfg)

~.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

eveswag.fCallOperation ⇒ Promise.<Object>

eveswag.tListOperation : Object

eveswag.tError : Object

Changelog

0.2.1

0.2.0

0.1.2

0.1.1

0.1.0

TODO

Contacts

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Uh oh!

Contributors

Uh oh!

Languages

~.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>>`

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

eveswag.fCallOperation ⇒ `Promise.<Object>`

eveswag.tListOperation : `Object`

eveswag.tError : `Object`

Packages