lhkbob / eve-swagger-js Goto Github PK

Several APIs take a "page" and it would be nice if there's an easy way to just fetch all pages, or fetch until a dynamic stopping criteria is met (upon which the merged results are returned).

There is also the maxID style pagination that at least the kill mail API uses for character's recent kills, and that could also be wrapped up in this manner.

Try and use type system to declare which route a function uses instead of having a custom doc tag.

This should include:

• Get constellations of a region
• Get solar systems in constellation
• Get stargates in solar system
• Get stations in solar system (although I'm not sure this is made available efficiently yet)
• Get planets in solar system
• Get moons around a planet

Tout fluent api, promise-driven, static + documented API, unit-tested, and has support for easier pagination, and normalization of different resources.

When given multiple ids, it will automatically map the individual function to the array and return the result of all of them.

For token-requiring end points, the token can also be an array (in which case its assumed to parallel the ids array).

TypeDoc gets us most of the way there but it's styling sucks. Maybe have it export json and then format manually. Also need to determine how to handle the generated esi comments etc.

The default Object.toString() returns the same string for everything, so many calls that store arguments in the opts object appear to have the same key when an option is changed.

Switch to using JSON.stringify() for args and opts to get a deep text representation of the values.

At the moment promises can make an exception raised by the internal agent a little disconnected from the stack that triggered the request, which is a pretty important piece of debugging info.

Await may help here.

At the very least, I can include more details about the request in the thrown VError so that the exact request can be reproduced externally.

Describes query, path, and body types for every route, or is undefined if the route doesn't take any parameters.

With the removal of swagger-codegen code, I don't feel like I have to inherit the original Apache 2.0 license that went with the generated code.

Everything should be lower case. Additionally, rename the Api class to API.

Based on this latest post: https://developers.eveonline.com/blog/article/breaking-changes-and-you it's probably best to allow the selection of alt routes. Perhaps this is something that gets done as part of the swagger-codegen, or at least at the same time. Then the clients wouldn't have to select the route versions they care about, but the code would be still be tied to routes that this library was aware of.

Main one is remove vs del (leaning towards del at the moment). Also shows up in add vs create, and update vs. a more specific action. With regards to the update option, in many cases the specific action reflects ESI's current supported behavior but update is future proof if they allow for more changes in the same end point in the future.

So that CCP can get in touch when we break something...

Some route responses need a human-written type definition for the final, client-side API. One such example is the response for the /universe/names route, which removes the category field. Similarly, the /search route must be updated. Many of the POST routes that return object ids wrapped by a single object will also be overridden to have a type of number.

This could be part of unit tests to confirm that the reported ESI version of the service matches what was used to generate this code. Or continuous integration is set up, so that it will fail when a new ESI version is released.

While this library does call specific route versions, it does not expose headers of the responses. ESI includes a special header if the route has been deprecated. This can be useful if a developer should be updating to a new version of this library that points to the updated route already.

To expose the deprecation, there should be a configuration setting to say be silent, print a warning to the console, or throw an exception.

Should switch name to be eve-swagger-js in package.json. Would be nice to have it hosted on npm now that things are a bit more stable with the new superagent project.

Some evidence suggests that this wrapper has a memory leak dealing with objects held onto, outside of the JS heap. This becomes a problem when using the new location services that have a very low cache time and are polled frequently in many applications. There are two likely possibilities:

1. The node cache objects themselves aren't being cleaned up properly. Since each access token gets a new cache, prolonged application life time could cause a large accumulation of stale cache instances. Specifically, the internal node-cache might be using setInterval, and never cleans these up.
2. http objects are being held onto. While the cached responses shouldn't have references back to the http objects, perhaps they are being captured by promises unexpectedly. Or I am mistaken about that previous assertion.

Is already implemented in superagent branch.

When calling ESI.universe.getType with an id it returns the correct group_id and icon_id, however all other, non number, values are returned as undefined.

ESI.universe.getType(3329, ac).then(function (type) { console.log(type); }).catch(function (error) { console.error(error); });

returns:

exports {
category_id: undefined,
group_id: 257,
type_description: undefined,
type_name: undefined,
icon_id: 33 }

• Make sure that updates/deletes return just an empty object.
• Make sure that posts return an integer, or empty object (for UI actions only)
• Make sure responses that have filtered/remapped keys are correct

There is no real point to converting to a lower node level or other target environment as a library.

Applications that need such a transformation most likely already have something like webpack that processes and combines all dependencies. Our babel step is just one extra step that is mostly meaningless and could introduce compatibility problems.

Lastly, it'll conflict with any future update to typescript which has its own, necessary compilation. But in that case we can have it target the latest JS standard.

The swagger codegen backend generated code is pretty heavy handed. Many of its model objects needlessly complicate a simple json parse.

Additionally they hardcore the expected fields in the response model so it's more difficult to use an old version of this wrapper if the ESI interface updates underneath it. Over time it's become clear that ccp most frequently changes the response types or status codes, but rarely changes the request contract.

Moving to a model-less approach that parses and returns the response without validation will survive incremental ESI changes more easily.

For this:

      esi.corporations(1).info().then(result => {
  console.log(result);
}).catch(error => {
  console.error(error);
});

I get this:

modules.js?hash=c2f08ee…:118450 Unhandled rejection esi:Error: Error contacting ESI service for https://esi.tech.ccp.is/v4/characters/1/: Cannot read property 'indexOf' of undefined
    at getExceptionFromAgentError (http://localhost:3000/packages/modules.js?hash=c2f08eef8e8d7f965119d7e48560ac92e2151e66:97349:17)
    at http://localhost:3000/packages/modules.js?hash=c2f08eef8e8d7f965119d7e48560ac92e2151e66:97504:22
    at Request.callback (http://localhost:3000/packages/modules.js?hash=c2f08eef8e8d7f965119d7e48560ac92e2151e66:107906:12)
    at Request.end (http://localhost:3000/packages/modules.js?hash=c2f08eef8e8d7f965119d7e48560ac92e2151e66:107975:17)
    at http://localhost:3000/packages/modules.js?hash=c2f08eef8e8d7f965119d7e48560ac92e2151e66:97500:19
    at http://localhost:3000/packages/modules.js?hash=c2f08eef8e8d7f965119d7e48560ac92e2151e66:97499:16
From previous event:
    at ESIRequestHandler._request (http://localhost:3000/packages/modules.js?hash=c2f08eef8e8d7f965119d7e48560ac92e2151e66:97480:25)
    at Object.<anonymous> (http://localhost:3000/packages/modules.js?hash=c2f08eef8e8d7f965119d7e48560ac92e2151e66:97446:26)
    at Object.wrapped (http://localhost:3000/packages/modules.js?hash=c2f08eef8e8d7f965119d7e48560ac92e2151e66:116610:22)
    at http://localhost:3000/packages/modules.js?hash=c2f08eef8e8d7f965119d7e48560ac92e2151e66:116550:34

Documentation of the function takes an array of ids, which is consistent with other end points. However, the actual ESI endpoint requires an object with an "ids" parameter storing the array. This should be built automatically before calling the ESI generated function.

See https://developers.eveonline.com/blog/article/error-limiting-imminent, should not be handled by higher level since this wrapper does not expose headers and already handles caching.

This might be a problem because of an outdated node js version on aws lambda (4.3.2)

SyntaxError: Block-scoped declarations (let, const, function, class) not yet supported outside strict mode
at exports.runInThisContext (vm.js:53:16)
at Module._compile (module.js:373:25)
at Object.Module._extensions..js (module.js:416:10)
at Module.load (module.js:343:32)
at Function.Module._load (module.js:300:12)
at Module.require (module.js:353:17)
at require (internal/module.js:12:17)
at Object. (/var/task/node_modules/eve_swagger_interface/src/index.js:1:75)
at Module._compile (module.js:409:26)
at Object.Module._extensions..js (module.js:416:10)

There should be a raw version and a cleaned version that incorporates the filtered types that some responses need to use. The raw version is still useful for properly typing the internal api. While it the wrapper type will never be instantiated, its definition will allow us to do static lookup of keys to the type for the route.

• Option to completely disable response caching
• Option to set the max and min times in the cache (clamping whatever time is reported by ESI)

Currently there are fail conditions if requests are specifically incorrect, out of order, or too many are made. There is no check to confirm that a certain number of requests are made once the test is made.

Challenges:

1. Numerous end points require an SSO token for a character, but the character ID and the token should not be committed to the repository.
2. The requests are all asynchronous with promises, not sure how this will affect unit test library execution.
3. Ignoring the SSO token issue, some end points require the character to be logged in.

This suggests some form of mock is necessary, to confirm that the generated APIs are invoked with the arguments as expected.

Convert to camel case, shirt, human-like instead of just using the route ids or names stored in the spec.

getAll() and getKillmails() both take a page optional parameter.

Once outer functions are moved to classes, each instance can have its own created-once Api instances instead of creating a new one for each request.

Or provide generated typings definitions while staying in JS