This module is a thin client for interacting with Button's API.
Please see the full API Docs for more information. For help, check out our Support page or get in touch.
- Node
0.10
,0.11
,0.12
,4
,5
,6
- None
npm install @button/button-client-node
To create a client capable of making network requests, invoke button-client-node
with your API key.
var client = require('@button/button-client-node')('sk-XXX');
You can optionally supply a config
argument with your API key:
var Q = require('q');
var client = require('@button/button-client-node')('sk-XXX', {
timeout: 3000, // network requests will time out at 3 seconds
promise: function(resolver) { return Q.Promise(resolver); }
});
timeout
: The time in ms for network requests to abort. Defaults to false.promise
: A function which accepts a resolver function and returns a promise. Used to integrate with the promise library of your choice (i.e. es6 Promises, Bluebird, Q, etc). Ifpromise
is supplied and is a function, all API functions will ignore any passed callbacks and instead return a promise.hostname
: Defaults toapi.usebutton.com
port
: Defaults to443
ifconfig.secure
, else defaults to80
.secure
: Whether or not to use HTTPS. Defaults to true. N.B: Button's API is only exposed through HTTPS. This option is provided purely as a convenience for testing and development.
button-client-node
supports standard node-style callbacks. To make a standard call, supply a callback
function as the last argument to any API function and omit promise
from your config
.
var client = require('@button/button-client-node')('sk-XXX');
client.orders.get('btnorder-XXX', function(err, res) {
// ...
});
All callbacks will be invoked with two arguments. err
will be an Error
object if an error occurred and null
otherwise. res
will be the API response if the request succeeded or null
otherwise.
If an Error
is returned after the client receives a response, such as for an upstream HTTP error, the Error.response
property will be set to the NodeJS response
object.
button-client-node
supports a promise interface. To make a promise-based request, supply a function that accepts a single resolver function and returns a new promise on the promise
key of your config
. Additionally, you must omit the callback from your API function call.
var Promise = require('bluebird');
var client = require('@button/button-client-node')('sk-XXX', {
promise: function(resolver) { return new Promise(resolver); }
});
client.orders.get('btnorder-XXX').then(function(result) {
// ...
}, function(reason) {
// ...
});
A resolver function has the signature function(resolve, reject) { ... }
and is supported by many promise implementations:
If your promise library of choice doesn't support such a function, you can always roll your own as long as your library supports resolving and rejecting a promise you create:
promiseCreator(resolver) {
var promise = SpecialPromise();
resolver(function(result) {
promise.resolve(result);
}, function(reason) {
promise.reject(reason);
});
return promise;
}
The returned promise will either reject with an Error
or resolve with the API response object.
All responses will assume the following shape:
{
data,
meta: {
next,
previous
}
}
The data
key will contain any resource data received from the API and the meta
key will contain high-order information pertaining to the request.
next
: For any paged resource,next
will be a cursor to supply for the next page of results.previous
: For any paged resource,previous
will be a cursor to supply for the previous page of results.
We currently expose the following resources to manage:
var client = require('@button/button-client-node')('sk-XXX');
client.accounts.all(function(err, res) {
// ...
});
Transactions are a paged resource. The response object will contain properties meta.next
and meta.previous
which can be supplied to subsequent invocations of #transactions
to fetch additional results.
#transactions
accepts an optional second parameter, options
which may define the follow keys to narrow results:
cursor
: An API cursor to fetch a specific set of resultsstart
: An ISO-8601 datetime string to filter only transactions afterstart
end
: An ISO-8601 datetime string to filter only transactions beforeend
var client = require('@button/button-client-node')('sk-XXX');
// without options argument
//
client.accounts.transactions('acc-1', function(err, res) {
// ...
});
// with options argument
//
client.accounts.transactions('acc-1', {
cursor: 'cXw',
start: '2015-01-01T00:00:00Z',
end: '2016-01-01T00:00:00Z'
}, function(err, res) {
// ...
});
status
: Partnership status to filter by. One of ('approved', 'pending', or 'available')currency
: ISO-4217 currency code to filter returned rates by
var client = require('@button/button-client-node')('sk-XXX');
// without options argument
//
client.merchants.all(function(err, res) {
// ...
});
// with options argument
//
client.merchants.all({
status: 'pending',
currency: 'USD'
}, function(err, res) {
// ...
});
var crypto = require('crypto');
var client = require('@button/button-client-node')('sk-XXX');
var hashedEmail = crypto.createHash('sha256')
.update('[email protected]'.toLowerCase().trim())
.digest('hex');
client.orders.create({
total: 50,
currency: 'USD',
order_id: '1989',
purchase_date: '2017-07-25T08:23:52Z',
finalization_date: '2017-08-02T19:26:08Z',
btn_ref: 'srctok-XXX',
customer: {
id: 'mycustomer-1234',
email_sha256: hashedEmail
}
}, function(err, res) {
// ...
});
var client = require('@button/button-client-node')('sk-XXX');
client.orders.get('btnorder-XXX', function(err, res) {
// ...
});
var client = require('@button/button-client-node')('sk-XXX');
client.orders.getByBtnRef('srctok-XXX', function (err, res) {
// ...
});
var client = require('@button/button-client-node')('sk-XXX');
client.orders.update('btnorder-XXX', { total: 60 }, function(err, res) {
// ...
});
var client = require('@button/button-client-node')('sk-XXX');
client.orders.del('btnorder-XXX', function(err, res) {
// ...
});
var crypto = require('crypto');
var client = require('@button/button-client-node')('sk-XXX');
var hashedEmail = crypto.createHash('sha256')
.update('[email protected]'.toLowerCase().trim())
.digest('hex');
client.customers.create({
id: 'customer-1234',
email_sha256: hashedEmail
}, function(err, res) {
// ...
});
var client = require('@button/button-client-node')('sk-XXX');
client.customers.get('customer-1234', function(err, res) {
// ...
});
client.links.create({
url: "https://www.jet.com",
experience: {
btn_pub_ref: "my-pub-ref",
btn_pub_user: "user-id"
}
}, function(err, res) {
// ...
});
client.links.getInfo({
url: "https://www.jet.com"
}, function(err, res) {
// ...
});
Utils houses generic helpers useful in a Button Integration.
Used to verify that requests sent to a webhook endpoint are from Button and that their payload can be trusted. Returns true
if a webhook request body matches the sent signature and false
otherwise. See Webhook Security for more details.
Example usage with body-parser
var express = require('express');
var bodyParser = require('body-parser');
var utils = require('@button/button-client-node').utils
var app = express();
function verify(req, res, buf, encoding) {
var isAuthentic = utils.isWebhookAuthentic(
process.env['WEBHOOK_SECRET'],
buf,
req.headers['X-Button-Signature']
);
if (!isAuthentic) {
throw new Error('Invalid Webhook Signature');
}
}
app.use(bodyParser.json({ verify: verify, type: 'application/json' }));
- Installing development dependencies:
npm install
- Running tests:
npm test
- Running lint:
npm run lint