Respoke for Node

NPM version Build Status Dependency Status devDependency Status

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'
             });
         });

     });
 });


Constructor

new Respoke(options)


Arguments
options
object
Optional

options.appId
string
Optional

options['Admin-Token']
string
Optional header, if you already authenticated

options['App-Secret']
string
Optional header, from Respoke dev console

options['App-Token']
string
Optional header, if you already authenticated

options.endpointId
string
Optional endpointId to use when connecting via web socket using auth scheme which does not imply an endpointId (i.e. App-Secret)

options.autoreconnect=false
boolean
Optional flag to automatically reconnect to respoke if a web socket connection becomes active, then is lost. This will throw an error when attempting to reconnect if specified without an App-Secret.

options.baseURL=https://api.respoke.io/v1
string
Optional

options.socket
object
Optional, overrides the default socket.io client



Properties and Methods


object respoke.tokens

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




string respoke.tokens['Admin-Token']

Header Admin-Token




string respoke.tokens['App-Secret']

Header App-Secret




string respoke.tokens['App-Token']

Header App-Token




string respoke.appId

App id




string respoke.connectionId

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




string respoke.endpointId

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




string respoke.baseURL

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




SocketObject respoke.socket

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




respoke.request(params, callback)

General purpose method for doing a REST call to Respoke.


Arguments
params
object

params.body
object

params.json=true
boolean

params.headers=self.tokens
object

callback
function
(err, body)




respoke.wsCall(httpMethod, urlPath, data)

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


Arguments
httpMethod
string

urlPath
string
Relative to `baseUrl`

data
object
Optional; to be sent over web socket

[data.headers]
object
Optional WS header object




object respoke.auth

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




respoke.auth.endpoint(opts, callback)

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"
 });

Arguments
opts
object

opts.appId
object
required

opts.endpointId
object
required

opts.roleId
object
required unless app is in development mode

opts.ttl=86400
object
optional seconds time-to-live

opts.headers['App-Secret']
object
optional; override cached token

opts.headers['Admin-Token']
object
optional; override cached token

callback
function
(err, clientAuthData)




respoke.auth.sessionToken(opts, callback)

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.


Arguments
opts
object
required

[opts.tokenId]
string
required

callback
function
(err, body)




respoke.auth.connect(opts)

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').


Arguments
opts
object
optional

opts.endpointId
string
required if not connecting using App-Token

opts['Admin-Token']
string
optional

opts['App-Secret']
string
optional

opts['App-Token']
string
optional

opts.connectParams
object
optional Socket.io connection parameters




respoke.auth.admin(opts, callback)

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' }


Arguments
opts
object
Required

opts.username
string

opts.password
string

callback
function
(err, body)




respoke.close(callback)

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


Arguments
callback
function
(err)




object respoke.presence

Namespace object. Methods for interacting with presence indication.




respoke.presence.observe(endpoints, callback)

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


Arguments
endpoints
array<string>

callback
function




respoke.presence.set(params, callback)

Set your own presence.


Arguments
params
object

params.presence
string, number, object, array
Your presence object. Format varies, depending on how your application decides to implement presence.

params.status
string
Human readable status message.

callback
function




object respoke.messages

Namespace object. Messaging.




respoke.messages.send(params, callback)

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


Arguments
params
object

params.to
string
endpointId

params.connectionId
string
optional

params.message
string
required

params.type='message'
string
optional

params.ccSelf=true
string
optional

params.endpointId
string
optional

callback
function




object respoke.groups

Namespace object. Groups.




respoke.groups.publish(params, callback)

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


Arguments
params
object

params.groupId
string

params.message
string

params.endpointId=self.endpointId
string

callback
function




respoke.groups.getSubscribers(params, callback)

Get the members of a group.


Arguments
params
object

params.groupId
string

callback
function




respoke.groups.join(params, callback)

Join a group.


Arguments
params
object

params.groupId
string

callback
function




respoke.groups.leave(params, callback)

Leave a group.


Arguments
params
object

params.groupId
string

params.endpointId
string
optional

callback
function




object respoke.apps

Namespace object. For full admin only.




respoke.apps.get(opts, callback)

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


Arguments
opts
object
optional

[opts.appId]
string
optional

[opts.headers]
object
optional

callback
function
(err, app)




object respoke.roles

Namespace object. For full admin only.




respoke.roles.get(options, callback(err,)

Retrieve a security role


Arguments
options
object
required

[options.appId]
string
required

[options.roleId]
string
optional

callback(err,
function
role)




respoke.roles.create(role, opts, callback(err,)

Create a security role.

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


Arguments
role
object
the role to create required

[role.appId]
string
required

[role.name]
string
required

opts
object
optional request opts

[opts.headers]
object
optional

callback(err,
function
createdRole)




respoke.roles.delete(opts, callback(err))

Remove a security role.


Arguments
opts
object
required

[opts.roleId]
string
required

[opts.headers]
object
optional

callback(err)
function






Events

Listen for events on an instance of this class.

respoke.on('event-name', function (arg) {
 
});

event connect

Connected to respoke.



event disconnect

Disconnected from respoke.



event reconnect

Reconnected with respoke.


Callback Arguments

num
number



event reconnecting

Reconnecting with respoke.


Callback Arguments

num
number



event error

An error occurred.


Callback Arguments

err
error



event message

There is an incoming private message, from an endpoint.


Callback Arguments

msg
object



event presence

Presence for an endpoint has changed or is now available.


Callback Arguments

res
object



event join

An endpoint (which can include this client) has joined a group.


Callback Arguments

res
object



event leave

An endpoint (which can include this client) has left a group.


Callback Arguments

res
object



event pubsub

A group message has been received.


Callback Arguments

res
object