dispatch-node-sdk

Dispatch JavaScript SDK

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

Versioning

There are now two maintained versions of Dispatch Javascript SDK. All versions will be remained publish, but our goal is two have at most 2 maintained versions at a time. The versions are version 1 and version 2 and can be found on the branches trunk/1.X.X and trunk/2.X.X respectively. When making changes to a version, please branch off of the proper trunk and then submit a PR into that trunk. If the change needs to go into both versions, please submit a PR for each version and then each version will be incremented and published separately.

Key Differences:

Version 1

All API endpoints point to the v1 endpoints of the Dispatch API.

Version 2

All API endpoints point to the v1 endpoints of the Dispatch API with the exception of the jobs endpoint. The jobs endpoint now points to the v2 endpoint. Also, the endpoints for job offers and hybdrid jobs have been removed.

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

Entities

customers

Get one customer by id:

client.entities.customer(:id)

Update one customer by id and properties:

client.entities.customer(:id).update(: properties)

Get all attachments for a customer by id:

client.entities.customer(:id).getAttachments()

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