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('+15555555555').then(() => {
alert('Verification code will be sent to your phone!');
}).catch(err => alert('Error getting verification code'));
client.loginPhoneNumber('+15555555555', 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: 'rswan@pr.com',
home_address: {
street_1: '2475 Mountain Avenue',
street_2: '',
postal_code: '50265',
city: 'West Des Moines',
state: 'IA',
},
phone_number: '+17069203204',
phone_numbers: {
'+17069203204': {
type: 'Mobile',
number: '+17069203204',
primary: true,
},
},
}).then(result => {
});
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 => {
});
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 => {
});