dispatch-node-sdk

Dispatch JavaScript SDK

High- and low-level libraries for interacting with the Dispatch API.

Installation

$ npm install --save dispatch-node-sdk

Usage

Client SDK

The client SDK is meant for use on the browser. It assumes that there is only one active bearer token at a time - for server-level use, please use the raw Client.

Instantiation

Create a new instance of the client with your client_id and client_secret.

import Dispatch from 'dispatch-node-sdk';
const dispatchClient = new Dispatch(clientID, clientSecret, 'https://api.dispatch.me');

Authentication

Set the Bearer Token

You can manually set the API bearer token if it came from an external source:

client.setBearerToken(bearerToken, refreshToken);

Log in with username/password

client.loginEmailPassword(email, password).then(() => {
  return client.identifyUser();
}).then(user => {
  console.log('Current user is', user);
}).catch(err => console.error('Failed to log in:', err));

Log in with phone + verification code

client.requestVerificationCode('[phone]').then(() => {
  alert('Verification code will be sent to your phone!');
}).catch(err => alert('Error getting verification code'));

// Later...
client.loginPhoneNumber('[phone]', verificationCode).then(token => {
  alert('Got bearer token: ' + token);
}).catch(err => alert('Error logging in!'));

Login with limited-use auth token

client.loginAuthToken(token).then(() => {
  return client.identifyUser();
}).then(user => {
  console.log('Current user is', user);
}).catch(err => console.error('Failed to log in:', err));

Interacting with Data

Get a list of models

You can use the getCollection method directly, like this:

client.getCollection('/v1/jobs', {
  filter: {
    status_eq: 'unscheduled',
  }
}).then(jobs => {
  jobs.forEach(job => console.log('Got job ID ' + job.get('id')));
}).catch(err => alert('Error loading jobs!'));

Or, use the defined collection, like this:

client.entities.jobs.get({
  filter: {
    status_eq: 'unscheduled',
  }
});

You can also get meta data (such as pagination, etc.) using getCollectionWithMeta:

client.getCollectionWithMeta('/v1/jobs', {
  filter: {
    status_eq: 'unscheduled',
  }
}).then(response => {
  ...
})

where response has the following structure:

response: {
	data: [...],
	meta: {...},
}

if there are more then one sources of data returned from the API that are not meta:

response: {
	data: {
		source1: [...],
		source2: [...],
		...
	},
	meta: {...},
}

Creating a Model

client.entities.jobs.create({
  title: 'New job!',
}).then(...);

Retrieving a single model

Sometimes you may want to just get a single model instead of an entire collection. For example, to retrieve job #1:

client.getModel('/v1/jobs', 1)
.then(job => alert('Job 1 has status: ' + job.status))
.catch(err => alert('Error loading job #1'));

Similarly:

client.entities.jobs.getOne(1).then(...)

Updating a model

Once you have a model, you can modify it and save it:

model.status = 'new status';
client.entities.jobs.update(1, model).then(...);

Entity-specific Functions

Some entities have additional abstracted convenience functions. For example:

client.entities.job(123).addNote('note text').then(...)

Auxiliary Services

The Dispatch client has built-in support for interacting with auxiliary Dispatch APIs such as the Files API or Configuration Service. You should not have to use this directly as there are abstracted functions like uploadFile and configuration.getForEntity that make use of it, but if you need to, you can do the following:

This will make a POST request to https://my-service-name.dispatch.me:

myClient.getAuxiliaryClient('my-service-name').post('/foo', {body}).then(...);

This will do the same POST request but also handle automatic token refreshing if necessary:

myClient.doAuthenticatedRequest('POST', '/foo', {body}, {
  client: 'my-service-name',
}).then(...);

Raw Client

Use the low-level raw client on the server-side for shared-key authentication:

import { RawClient, AUTH_MODE_HMAC } from 'dispatch-node-sdk';

const client = new RawClient({
  authMode: AUTH_MODE_HMAC,
  hmacCredentials: {
    userID: 10,
    userType: 'user',
    secret: '<secret key>',
  },
  host: 'https://api-sandbox.dispatch.me',
});

client.get('/v1/jobs')
.then(jobs => console.log('Got %d jobs', jobs.length))
.catch(err => console.error(err));

Organization-Scope Functions

These functions are available on client.entities.organization(id).

addCustomer

client.entities.organization(5).addCustomer({
  first_name: 'Ron',
  last_name: 'Swanson',
  email: '[e-mail]',
  home_address: {
    street_1: '2475 Mountain Avenue',
    street_2: '',
    postal_code: '50265',
    city: 'West Des Moines',
    state: 'IA',
  },
  phone_number: '[phone]',
  phone_numbers: {
    '[phone]': {
      type: 'Mobile',
      number: '[phone]',
      primary: true,
    },
  },
}).then(result => {
  // result is the created customer object returned from the API
});

dateIsInWorkHours

Checks whether a date falls during an organization's defined work hours. The organization must have a timezone defined for this to work. Otherwise it always returns false.

const date = new Date();
client.entities.organization(5).dateIsInWorkHours(date).then(result => {
  // result is true or false
});

User-Scope Functions

These functions are available on client.entities.user(id).

dateIsInWorkHours

Checks whether a date falls during a user's defined work hours, or during that user's organization's defined work hours if the user does not have work hours defined. Either the user or the organization must have a timezone defined for this to work. Otherwise it always returns false.

const date = new Date();
client.entities.user(5).dateIsInWorkHours(date).then(result => {
  // result is true or false
});