matrix
/
matrix.org
mirror of https://github.com/matrix-org/matrix.org.git
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity
matrix.org/content/blog/2015/06/2015-06-12-introducing-all-...

5.4 KiB
Raw Permalink Blame History

+++ title = "Introducing all new matrix-js-sdk v0.1.0" path = "/blog/2015/06/12/introducing-all-new-matrix-js-sdk-v0-1-0"

[taxonomies] author = ["Matthew Hodgson"] category = ["Tech"] +++

Hi all,

If things seem a bit quiet here at the moment it's because most of the Matrix team is in the 'build' phase across the board on a bunch of major new projects - including the long-awaited reusable UI component library for the Web, end-to-end encryption support, stable VoIP on mobile and a few other surprises. The first wave of all this new work landed today in the form of a new major version release (0.1.0) of matrix-js-sdk: our javascript SDK library.

The history of JS client support on Matrix is that in the original rush to get a PoC webclient out the door back in September, we jumped straight to talking to the Matrix HTTP API from Angular controllers in 'syweb'. This then got split into an Angular SDK (matrix-angular-sdk) containing a bunch of services for handling the Matrix client state with the actual webapp sitting alongside as an example of the SDK. This then in turn got split into a basic matrix-js-sdk (wrapping the Matrix client-server HTTP API) and matrix-angular-sdk (handling the clientside state and exposing it as Angular services) - and this is how the current demo Angular webapp works at http://matrix.org/beta.

However, this poses a major problem if you want a richer client SDK but don't want to use Angular - e.g. if you prefer another framework (or no framework at all), or are using the SDK in an Application Service or similar. So, this has prompted a major upgrade to the matrix-js-sdk in order to extend it to act both as a simple wrapper of the Matrix Client-Server HTTP API, but also expose a full object and event model to describe the state of a Matrix client together with all the higher level functions to drive it. To quote from the README:

This SDK provides a full object model around the Matrix Client-Server API and emits events for incoming data and state changes. Aside from wrapping the HTTP API, it:

  • Handles syncing (via /initialSync and /events)
  • Handles the generation of "friendly" room and member names.
  • Handles historical RoomMember information (e.g. display names).
  • Manages room member state across multiple events (e.g. it handles typing, power levels and membership changes).
  • Exposes high-level objects like Rooms, RoomState, RoomMembers and Users which can be listened to for things like name changes, new messages, membership changes, presence changes, and more.

Later versions of the SDK will:

  • Automatically retry requests to send messages due to network errors.
  • Automatically retry requests to send messages due to rate limiting errors.
  • Mark events' sent status (e.g. 'not sent').
  • Handle "local echo" of messages sent.
  • Handle queueing of messages.
  • Handle pagination.
  • Expose a RoomSummary which would be suitable for a recents page.
  • Provide different pluggable storage layers (e.g. local storage, database-backed)

It also is designed to provide an API that abstracts both version 1 of the client-server API and the upcoming version 2 (which fixes various thinkos we've discovered along the way in v1).

This is incredibly exciting stuff as it now gives a really robust yet lightweight API for client-side and application-service development in JavaScript. Predictably enough we're using it to develop our new reusable web UI components, and I suspect we'll see new Node-based application services making use of in the near future. Meanwhile, it's more than topical as it should run straight on top of the Tessel JavaScript hardware modules we're giving away this weekend as our prize for the best hack built on Matrix at TADHack - letting the little Tessel ARM system-on-a-chip speak a very rich and native Matrix dialect!

The new matrix-js-sdk comes with comprehensive jsdoc detailing the new API which you can find at http://matrix-org.github.io/matrix-js-sdk/global.html. There are also some basic examples available, including a new simple node-powered command-line client designed for testing the SDK. Finally, if you're interested in reading the design process by which we've converged on the current API, all the details may be found in JIRA on SYJS-5.

So: if you've been itching to get your hands on a much more powerful pure-JS Matrix SDK, now's your chance! It's very early days for the new API so we expect to see a few incompatible changes on the horizon, but we encourage you to have a play and tell us what you think!.

To find out more, go check out the project at http://github.com/matrix-org/matrix-js-sdk, or if you're feeling daring just grab the library with npm install matrix-js-sdk and get hacking!