Matrix Javascript SDK

This is the Matrix Client-Server v1 SDK for Javascript. This SDK can be run in a browser (using browserify or stand-alone with a suitable request.js) or in Node.js.

Quickstart

In a browser

Host examples/browser (e.g. using python -m SimpleHTTPServer) and check the console to see a working version.

In Node

npm install matrix-js-sdk

var sdk = require("matrix-js-sdk");
var client = sdk.createClient("https://matrix.org");
client.publicRooms(function(err, data) {
  console.log("Public Rooms: %s", JSON.stringify(data));
});

Run examples/node via node app.js to see a working version.

API

Please see the client server API for more information on the HTTP calls.

Matrix Client

MatrixClient is constructed via sdk.createClient(args) where args can be:

• baseUrl (String) : The home server base URL to make requests to.
• credentials (Object) : Consists of a baseUrl (String), a userId (String) and an accessToken (String).
• credentials, config (Object, Object) : As before, but with a config which has the following options:
  • noUserAgent (Boolean: default false) : Set to true to stop setting a User-Agent on requests. This is typically done when using the SDK in a browser which logs errors when trying to clobber the User-Agent.

At any point these values can be modified by accessing matrixClient.credentials and matrixClient.config.

Promises

Promises are supported using Q, but are not enabled by default. To enable them, simply call sdk.usePromises() like so:

var sdk = require("matrix-js-sdk");
sdk.usePromises();
var client = sdk.createClient("https://matrix.org");
client.publicRooms().then(function(data) {
  console.log("Public Rooms: %s", JSON.stringify(data));
});

You will need to npm install q as it is not a hard dependency on this project.

Request

MatrixClient requires a request module in order to function. This is usually done for you when using npm. You can manually inject this by calling sdk.request(<request>). Wrappers around request allow you to easily support different HTTP libraries (such as AngularJS's $http).