Batch.com SDK for Node

This project is a NodeJS client wrapper for the Batch.com notifications server API.

Prerequisites

Every methods in this library in Promise-based using the native object. Moreover, since we're using some of the ES2015+ operators (i.e. const, arrow functions, etc), you'll need at least node 6.

Installation

# npm
$ npm install --save batch-notifications
# yarn
$ yarn install batch-notifications

Usage

Options

Before doing anything, you must pass your API keys created for your app in batch:

const opts = {
    restKey: "YOUR_REST_API_KEY",
    // you must pass at least one the following API key
    devKey: "YOUR_DEV_API_KEY",
    liveKey: "YOUR_LIVE_API_KEY",
    // optional
    // by default a bunyan instance will be created
    logger: new MyCustomLogger()
};

The client will always favor the liveKey if present otherwise it will take the devKey.

API

The following sections are presenting the API methods.

Campaigns

See the available parameters in the batch documentation.

create

For example, by taking the minimal payload example, we can create a new campaign like the following:

// see `opts` structure above
const batch = require("batch-notifications")(opts);

const payload = {
    name: "Test Campaign",
    push_time: "now",
    live: false,
    messages: [
        {
            language: "en",
            title: "Hello!",
            body: "How's it going?"
        }
    ]
};

batch.campaign.create(payload)
.then(function (campaignToken) {
    // created campaign referenced by the `campaignToken`
});

update

Updating a campaign is somewhat similar as create a new one except that you'll have some restrictions:

const batch = require("batch-notifications")(opts);

const payload = {
    push_time: "2038-01-19T03:14:07"
};

// token was taken from the previous `create` method
batch.campaign.update(token, payload)
.then(function () {
    // campaign updated
});

remove

Removing a campaign is done like this:

const batch = require("batch-notifications")(opts);

// token was taken from the previous `create` method
batch.campaign.remove(token)
.then(function () {
    // campaign removed
});

stats

Stats can only be fetched if the campaign token was created using the live key and that the campaign is already launched:

// see `opts` structure above
const batch = require("batch-notifications")(opts);

// token was taken from the previous `create` method
batch.campaign.stats(token)
.then(function (detail) {
    // ...
});

The detail object will contain the following properties:

• date: Date
• sent: Number
• direct_open: Number
• influenced_open: Number
• open_rate: Number
• reengaged: Number
• errors: Number

See the docs for more infos about those variables.

get

Retrieve details about one campaign:

// see `opts` structure above
const batch = require("batch-notifications")(opts);

// token was taken from the previous `create` method
batch.campaign.get(token)
.then(function (details) {
    // ...
});

The details object will contain at least the following properties:

• campaign_token: String
• from_api: Boolean
• dev_only: Boolean
• created_date: Date
• name: String
• live: Boolean
• push_time: Date

list

Get a paginated list of pushed campaigns:

// see `opts` structure above
const batch = require("batch-notifications")(opts);

// by default, it will fetch at most 10 campaigns
batch.campaign.list()
.then(function (detailsList) {
    // ...
});

The detailsList array is composed of objects which contain the same properties as get.

has

To verify that a token is present for a certain app:

// see `opts` structure above
const batch = require("batch-notifications")(opts);

// token was taken from the previous `create` method
batch.campaign.has(token)
.then(function (hasToken) {
    // ...
});

hasToken is a boolean which is true only if the token is present for the specific API key.

enable

To ensure that a campaign is enabled:

// see `opts` structure above
const batch = require("batch-notifications")(opts);

// token was taken from the previous `create` method
batch.campaign.enable(token)
.then(function () {
    // campaign is enabled
});

disable

To ensure that a campaign is disabled:

// see `opts` structure above
const batch = require("batch-notifications")(opts);

// token was taken from the previous `create` method
batch.campaign.disable(token)
.then(function () {
    // campaign is disabled
});

Transactional

See the available parameters in the batch documentation.

post

For example, by taking the minimal payload example, we can create a new transactional notification like the following:

// see `opts` structure above
const batch = require("batch-notifications")(opts);

const payload = {
    "group_id": "welcome",
    "recipients": {
        "tokens": ["USER_PUSH_TOKEN"]
    },
    "message": {
        "title": "Hello!",
        "body": "How's it going?"
    }
};

batch.transactional.post(payload)
.then(function (token) {
    // created transactional referenced by the `token`
});

Custom Data

save

To set custom data to a specific user (you need their id):

// see `opts` structure above
const batch = require("batch-notifications")(opts);

const payload = {
    "overwrite": false,
    "values":
    {
        "u.nickname": "The Rock",
        "u.force": 42,
        "ut.hobbies": ["Lifting", "Wrestling", "Acting"],
        "u.is_subscribed": null,
        "date(u.last_subscription)": "2016-01-10T10:00:00.000",
        "date(u.last_purchase)": 1472656161,
        "ut.locations": { "$add": ["Paris"], "$remove": ["Berlin"] }
    }
};

// userId (String) is the Id of the user to whom you want to set custom data
batch.customData.save(userId, payload)
.then(function (token) {
    // the `token` represents the transaction
});

saveBulk

To set custom data to several users:

// see `opts` structure above
const batch = require("batch-notifications")(opts);

const payload = [
    {
        "id": "Vincent",
        "update":
        {
            "values":
            {
                "u.nickname": "Vincent",
                "u.age": 55
            }
        }
    },
    {
        "id": "Johnny",
        "update":
        {
            "overwrite": true,
            "values":
            {
                "u.nickname": "BeGood",
                "u.age": 30
            }
        }
    }
];

batch.customData.saveBulk(payload)
.then(function (token) {
    // the `token` represents the transaction
});

delete

To delete custom data of a specific user (you need their id):

// see `opts` structure above
const batch = require("batch-notifications")(opts);

// userId (String) is the Id of the user to whom you want to delete custom data
// this method does not require a payload
batch.customData.delete(userId)
.then(function (token) {
    // the `token` represents the transaction
});

deleteBulk

To delete custom data of an array of users:

// see `opts` structure above
const batch = require("batch-notifications")(opts);

const payload = [
    "user1",
    "user2",
    "user3"
];

batch.customData.deleteBulk(payload)
.then(function (token) {
    // the `token` represents the transaction
});

Contributing

First, install the dependencies using yarn:

$ yarn install --pure-lockfile

Verify that your project is configured correctly by launching tests:

$ yarn test

Before you start coding make sure that you've read our CONTRIBUTING guide!