skype-http 0.1.0

[demurgos]

I'll use this issue for the roadmap of the library until 0.1.0.

First of all, thanks for all the people using this library and reporting issues/sending PRs. I started the library about two years ago and since then the library was mostly maintained only to ensure that it keeps working, but this was not enough to move it beyond the prototype state.

Goals:

• Abstract the network layer: HTTP requests (hosts, path, query strings and post body) and endpoint events (polling, websockets)
• Offer safety guarantees for the return values and actionable errors
• Provide enough features to potentially recreate a client with as many features as the the official client, minus audio/video.

Non-goals:

• Provide a high-level interface hiding the peculiarities of Skype

Challenges:

• We have no control about the API: the official Skype API may change at any moment.

Roadmap:

• Remove the formatting layer trans translating the JSON responses sent by Skype's servers to a higher-level API (it can be seen with the two directories native-api and api). This kind of higher-level abstraction should be handled by other libraries.
• Provide easier access for manual session management. A class automatically keeping track of the session could still be provided for ease of use, but it should be possible to pass the session state to method calls. The intent is to allow the API to be used in a REST server without having to keep track of active Api instances: you should be able to create a Skype session, save it to your storage layer and then reuse it when needed. skype-http currently offers a getState method to export the Skype session and endpoint state, but you then have to recreate a new instance (involving some reconnections) to use it.
• Separate the Skype session from the endpoint state. The Skype session is used to work with contacts and conversation metadata. The endpoint is used to send and receive messages. Currently, both are created simultaneously and mostly kept in sync. The issue is that the endpoint tends to expire more quickly and require a different approach since it is oriented to deal with events.
• Add support for websocket endpoints. We're currently using long-polling (every 1sec). Having the option to chose between websockets and polling would be nice (relies on the previous point: isolating the endpoint creation).
• Improve detection of API changes. Most the library currently assumed some shape for the responses and crashed or returned inconsistent results in case of errors: this complicates handling of breaking API changes. To help with this, I wrote two libraries: Incident (stable) and Kryo (still moving). The goal of the first library is to easily create errors with unique names, corresponding data and track causality. Regarding skype-http, the goal would be to have any potential error defined in src/errors so you can then catch the errors, switch on the name and handle them with the available data. For example an unexpected Skype responses should result in an UnexpectedResponseBody error with a body and request data so you can implement a quickfix until a patch is merged into the library. The second library (Kryo) offers a mostly declarative API to build runtime representations of types. This allows to test if a value matches a given type and help with serialization. For example it's intermediate model is richer than JSON so it can deal with Date objects out of the box. It also supports renames between JS keys and serialized keys. These runtime types were introduced in Use contacts API v2 #70 for contacts and Type check conversations and events #87 introduces it for conversations/messages/events. An idea to track Skype's non-breaking changes would be to generate two representations for each resource: a strict one rejecting objects with extra keys and using strong assumptions, and a weaker-one that ignore extra keys and has weaker checks. Then, the objects would be first parsed with strict representation: if it fails but succeeds with the weak one a warning is issued; if it also fails with the weak one it means there was a breaking change in the Skype API and an error is thrown as described above.
• Add additional features: contact & conversation management, help with sending files
• Drop dependency on request: its automagic cookie management makes it hard to keep track of the API state, it also complicates abstracting the HTTP layer to mock it.
• Write some documentation: since the goal is to have a lower level lib, putting more time to write examples and document the API is needed. There is a tslint rule to help with documentation, it may help to enable it.
• Add more tests: we recently enabled Codecov but the results are pretty bad. We should at least get to 80 or 90% of coverage.