Delighted API Node Client
Official Node.js client for the Delighted API.
Note: This is intended for server-side use only and does not support client-side JavaScript.
Run npm install delighted --save to install.
To get started, you need to require the client and configure it with your secret API key. You can require, configure and initialize the client in one go:
``javascript`
var delighted = require('delighted')('YOUR_API_KEY');
For further options, read the advanced configuration section.
Note: Your API key is secret, and you should treat it like a password. You can find your API key in your Delighted account, under Settings > API.
All resources can be accessed directly off of the delighted instance we created above. All actions immediately return a promise. In this initial example we'll create a person and log out their attributes when the promise resolves (finishes):
`javascript
var params = {
email: 'jony@appleseed.com',
name: 'Jony Appleseed',
delay: 86400,
properties: { plan: 'basic' } // an object to pass properties for segmentation
};
delighted.person.create(params).then(function(person) {
console.log(person);
});
`
Previously subscribed people can be unsubscribed:
`javascript`
delighted.unsubscribe.create({ person_email: 'jony@appleseed.com' });
Listing all people:
`javascriptperson
// List all people, auto pagination
// Note: this method automatically handles rate limits asynchronously
delighted.person
.list()
.autoPagingEach((person) => {
// Do something with
})
.then(() => {
console.log('Done iterating.');
}, (error) => {});
// If you wish to stop the pagination at any point, just return false
var count = 0;
delighted.person
.list()
.autoPagingEach((person) => {
// Do something with person
count++;
if (count >= 2) {
// Autopagination will stop after 2 interations
return false;
}
})
.then(() => {
// After stopping, this will still get executed
console.log('Done iterating.');
}, (error) => {});
// You can limit the numbers of max successive retries during auto rate limits handling
delighted.person
.list()
.autoPagingEach((person) => {
// Do something with person
},
{ auto_handle_rate_limits_max_retries: 12 }
)
.then(() => {
console.log('Done iterating.');
}, (error) => {});
// You can also handle rate limits and other errors yourself
delighted.person
.list()
.autoPagingEach((person) => {
// Do something with person
}, { auto_handle_rate_limits: false })
.then(() => {
console.log('Done iterating.');
}, (error) => {
if (error.type == 'TooManyRequestsError') {
// Indicates how long to wait (in seconds) before making this request again
console.log(error.retryAfter);
} else if (error.type == 'PaginationError') {
// General pagination error
console.log(error.message);
}
});
Get a paginated list of people who have unsubscribed:
`javascript`
delighted.unsubscribe.all({ page: 2}).then(function(responses) {
responses.length; // => 20
});
Get a paginated list of people whose emails have bounced:
`javascript`
delighted.bounce.all({ page: 2}).then(function(responses) {
responses.length; // => 20
});
Deleting a person and all of the data associated with them:
`javascript`
// Delete by person id
delighted.person.delete({ id: 42 })
// Delete by email address (must be E.164 format)
delighted.person.delete({ email: "test@example.com" })
// Delete by phone number
delighted.person.delete({ phone_number: "+14155551212" })
Pending survey requests can be deleted:
`javascript`
delighted.surveyRequest.deletePending({ person_email: 'jony@appleseed.com' });
Responses can be created for somebody using their id. Note that the id is not the same as their email:
`javascript`
delighted.surveyResponse.create({ person: person.id, score: 10 });
Get a paginated list of all responses:
`javascript`
delighted.surveyResponse.all({ page: 2 }).then(function(responses) {
responses.length; // => 20
});
Retrieve summary metrics of all responses:
`javascript`
delighted.metrics.retrieve();
Retrieve existing autopilot configuration for a platform:
`javascript`
delighted.autopilotConfiguration.retrieve('email');
delighted.autopilotConfiguration.retrieve('sms');
To interact with the autopilot person api, configure the autopilotMembership instance with the platform. You can list all people imported to Autopilot, add a new person, or delete an existing person:
`javascript
// List all people in Autopilot
delighted.autopilotMembership.forEmail().list().autoPagingEach((person) => {
console.log(person);
}, { auto_handle_rate_limits: true });
delighted.autopilotMembership.forSms().list().autoPagingEach((person) => {
console.log(person);
}, { auto_handle_rate_limits: true });
// Create a new person
delighted.autopilotMembership.forEmail().create({ person_email: 'email@example.com' });
delighted.autopilotMembership.forSms().create({ phone_number: '+15556667777' });
// Remove a person
delighted.autopilotMembership.forEmail().delete({ person_email: 'email@example.com' });
delighted.autopilotMembership.forSms().delete( {phone_number: '+15556667777' });
`
If a request is rate limited, a DelightedError error is raised with a type of TooManyRequestsError. You can handle that error to implement exponential backoff or retry strategies. The error object provides a .retry_after property to tell you how many seconds you should wait before retrying. For example:
`js`
instance.metrics.retrieve().then(
function(metrics) { ... },
function(error) {
if (error.type === 'TooManyRequestsError') { // rate limited
var retryAfterSeconds = error.retryAfter;
// wait for retryAfterSeconds before retrying
// add your retry strategy here ...
} else {
// some other type of error
}
}
);
All of the connection details can be configured through the delighted constructor, primarily for testing purposes. The available configuration options are:
* host – defaults to api.delighted.com
* – defaults to 443
* – defaults to /v1
* – defaults to specifying application/json for Accept and Content-Type and sets User-Agent to identify the Delighted API Node Client and version.scheme
* – defaults to https
Testing with real requests against a mock server is the easiest way to integration test your application. For convenience, and our own testing, a test server is provided with the delighted package. Below is an example of testing the person resource within an application:
`javascript
var delighted = require('delighted');
var mockServer = require('delighted/server');
var instance = delighted('DUMMY_API_KEY', {
host: 'localhost',
port: 5678,
base: '',
scheme: 'http'
});
var mapping = {
'POST /v1/people': {
status: 201,
body: { id: "1", email: 'foo@example.com', name: null, survey_scheduled_at: 1490298348 }
}
};
var server = mockServer(5678, mapping);
`
Setting up the server only requires a port and a mapping. The mapping should match an exact endpoint and will send back a JSON body with the specified status code. With the server running you can then make a request:
`javascript`
instance.person.create({ email: 'foo@example.com' }).then(
function(person) {
console.log(person.survey_scheduled_at); //=> 1490298348
},
function(error) {
console.log(error.type); //=> ResourceValidationError
}
);
When you are done reading responses from the server, be sure to close it.
`javascript`
server.close();
1. Fork it
2. Create your feature branch (git checkout -b my-new-feature)npm run-script test
3. Run the tests ()git commit -am 'Add some feature'
4. Commit your changes ()git push origin my-new-feature
5. Push to the branch ()
6. Create new Pull Request
1. Decide on the new version number (let's call it x).CHANGELOG.md
2. Update with notes about the new version's changes.lib/Delighted.js
3. Update the version number in and package.json and create a git tag for the version number (use git tag -l to check the format).npm publish --tag next
4. Commit your changes to git and push the tag.
5. Run to upload a pre-release to the NPM package registry, use npm publish --tag latest` to upload the final release
Originally by Sean McGary. Graciously transfered and now officially maintained by Delighted.