Respoke for Node

Setup

Install using npm.

npm install --save respoke-admin

For more details on the node-respoke API see the project documentation. For more on the Respoke service and how it works see the full documentation.

Debugging

This library uses the debug npm module. To enable debugging output, use the following environment variable:

DEBUG=respoke-client

Error handling

A respoke client inherits from EventEmitter.

client.on('error', function (err) { console.error(err); });

If you fail to listen for the error event, errors will be thrown so they are not buried.

Testing

Before you can run the functional tests you will need to complete the following steps.

• create a test app in the your admin portal at [respoke.io][respoke]
• turn off dev mode
• create a new blank role (name value is not important)
• cp spec/helpers.example.js spec/helpers.js
• fill in the information in the spec/helpers.js file

There are several commands to run the tests.

# run all tests
npm test

# run all tests with extra debug output
npm run debug-test

# run only unit tests
npm run unit

# run only functional tests
npm run functional

Building and viewing the source documentation

npm run docs

Respoke Authentication

There are multiple levels of authentication to Respoke, depending on your use case. In general, the hierarchy of credentials is as follows:

1. "Admin-Token" (full account administrator)

2. "App-Secret" (app level administration)

3. "App-Token" (endpoint / end user)

Examples

Instantiate a client with an App-Secret

 var Respoke = require('respoke-admin');
 var admin = new Respoke({
     // from the Respoke developer console under one of your apps
     appId: "XXXX-XXX-XXXXX-XXXX",
     'App-Secret': 'XXXX-XXXXX-XXX-XXXXXXXX',
     // if the respoke socket is lost, keep trying to reconnect automatically
     autoreconnect: true
 });

 // connect to respoke
 // provide an `endpointId` for receiving messages
 admin.auth.connect({ endpointId: "superWombat"});
 admin.on('connect', function () {
     console.log('admin is connected to respoke');
 });
 admin.on('message', function (message) {
     if (message.endpointId === 'billy') {
         console.log('message from billy', message);
     }
 });

Obtain a session token for an endpoint

 admin.auth.endpoint({
     endpointId: "billy",
     roleId: "XXXX-XXX-XXXXX-XXXX"
 }, function (err, authData) {
     if (err) { console.error(err); return; }

     // Now we have a token for an end user to authenticate as an endpoint.
     console.log(authData.tokenId); // "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
     var billy = new Respoke({ appId: 'XXXX-XXXXX-XXXX-XXX' });

     billy.auth.sessionToken({ tokenId: authData.tokenId }, function (err, sessionData) {
         if (err) { console.error(err); return; }

         // Now we have a session token from `sessionData.token`.
         // However, for our purposes, there is no need to do anything with it because
         // the library caches it automatically at `billy.tokens['App-Token']`, and
         // uses it when it needs it.
         billy.auth.connect();

         // Respoke is an EventEmitter
         billy.on('connect', function () {
             console.log('connected to respoke!');
             billy.messages.send({
                 to: 'superWombat',
                 message: 'Hi wombat'
             });
         });

     });
 });

Container object for header tokens. These are used when performing REST or web socket requests to Respoke.

Header Admin-Token

Header App-Secret

Header App-Token

App id

If connected, this is the web socket connection ID with Respoke.

If connected, this is the endpointId. Stored endpointId for use when connecting with App-Secret via web socket (when not a specific endpoint).

The base respoke api to use. In most circumstances there is no reason to change this.

It should include the API version with no trailing /.

https://api.respoke.io/v1

The web socket connection instance from socket.io. It is recommended that you do not access this directly.

General purpose method for doing a REST call to Respoke.

Make a general purpose web socket call over the active .socket.

Namespace object. The methods at respoke.auth are used for obtaining auth credentials and connecting with Respoke.

As an admin (with respoke.tokens['App-Token'] or respoke.tokens['App-Secret']), obtain a tokenId which can be used to authenticate to Respoke as an endpoint.

 respoke.auth.endpoint({
     endpointId: "user-billy",
     roleId: "XXXX-XXX-XXXXX-XXXX"
 }, function (err, authData) {
     if (err) { console.error(err); return; }

     console.log(authData.tokenId); // "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX"
 });

As an endpoint, obtain an app auth session. This creates a session for the user to connect to your Respoke app.

Upon successful authentication, it sets the property respoke.tokens['App-Token'] which will be used during HTTP requests, or to establish a web socket. { token: 'XXXX-XXX-XXXXX-XXXX' }

In most cases, you will immediately call .connect() to initiate the web socket.

Connect as a web socket client using the highest authentication token currently available.

After calling this, attach event listeners such as respoke.on('connect') and respoke.on('error').

Authenticate with full admin privileges. This is not a recommended auth strategy and should only be used in rare circustances when App-Secret auth is not enough.

Upon successful authentication, it sets the property respoke.tokens['Admin-Token'] which will be used during HTTP requests or to establish a web socket. { token: 'XXXX-XXX-XXXXX-XX' }

Delete the app auth session, disconnect the web socket, and remove all listeners.

Namespace object. Methods for interacting with presence indication.

Register as an observer of presence for the specified endpoint ids.

Set your own presence.

Namespace object. Messaging.

Send a message to an endpoint or specific connection of an endpoint.

Namespace object. Groups.

Send a message to a group. When authenticated as an admin via App-Secret or Admin-Token, you can pass messages for any endpointId.

Get the members of a group.

Join a group.

Leave a group.

Namespace object. For full admin only.

Get an app by opts.appId, or get all apps when opts.appId is not supplied.

Namespace object. For full admin only.

Retrieve a security role

Create a security role.

The callback data object contains the id of the created role, which can be used for authenticating endpoints.

Remove a security role.