button-client-node

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.

Supported runtimes

• Node 6, 8, 10

Dependencies

• None

Usage

npm install @button/button-client-node

To create a client capable of making network requests, invoke button-client-node with your API key.

constclient=require('@button/button-client-node')('sk-XXX');

You can optionally supply a config argument with your API key:

constclient=require('@button/button-client-node')('sk-XXX',{timeout: 3000,// network requests will time out at 3 secondshostname: 'api.usebutton.com'// default hostname for api requests});

Config

• timeout: The time in ms for network requests to abort. Defaults to false.
• hostname: Defaults to api.usebutton.com
• port: Defaults to 443 if config.secure, else defaults to 80.
• 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.

Promise

button-client-node uses native Promises for all requests:

constclient=require('@button/button-client-node')('sk-XXX',{timeout: 3000});client.orders.get('btnorder-XXX').then(handleResult).catch(handleError);

The returned promise will either reject with an Error or resolve with the API response object.

Responses

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.

meta

• 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.

Resources

We currently expose the following resources to manage:

• Accounts
• Merchants
• Orders
• Transactions

Accounts

All

constclient=require('@button/button-client-node')('sk-XXX');client.accounts.all().then(handleResult).catch(handleError);

Transactions

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:

options

• cursor: An API cursor to fetch a specific set of results
• start: An ISO-8601 datetime string to filter only transactions after start
• end: An ISO-8601 datetime string to filter only transactions before end
• time_field: Which time field start and end filter on.

constclient=require('@button/button-client-node')('sk-XXX');// without options argument//client.accounts.transactions('acc-1').then(handleSuccess).catch(handleError);// with options argument//client.accounts.transactions('acc-1',{cursor: 'cXw',start: '2015-01-01T00:00:00Z',end: '2016-01-01T00:00:00Z',time_field: 'modified_date'}).then(handleResult).catch(handleError);

Merchants

All

options

• status: Partnership status to filter by. One of ('approved', 'pending', or 'available')
• currency: ISO-4217 currency code to filter returned rates by

constclient=require('@button/button-client-node')('sk-XXX');// without options argument//client.merchants.all().then().catch();// with options argument//client.merchants.all({status: 'pending',currency: 'USD'}).then(handleResult).catch(handleError);

Orders

Create

constcrypto=require('crypto');constclient=require('@button/button-client-node')('sk-XXX');consthashedEmail=crypto.createHash('sha256').update('user@example.com'.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}}).then(handleResult).catch(handleError);

Get

constclient=require('@button/button-client-node')('sk-XXX');client.orders.get('btnorder-XXX').then(handleResult).catch(handleError);

Get by Button Ref

constclient=require('@button/button-client-node')('sk-XXX');client.orders.getByBtnRef('srctok-XXX').then(handleResult).catch(handleError);

Update

constclient=require('@button/button-client-node')('sk-XXX');client.orders.update('btnorder-XXX',{total: 60}).then(handleResult).catch(handleError);

Delete

constclient=require('@button/button-client-node')('sk-XXX');client.orders.del('btnorder-XXX').then(handleResult).catch(handleError);

Customers

Create

constcrypto=require('crypto');constclient=require('@button/button-client-node')('sk-XXX');consthashedEmail=crypto.createHash('sha256').update('user@example.com'.toLowerCase().trim()).digest('hex');client.customers.create({id: 'customer-1234',email_sha256: hashedEmail}).then(handleResult).catch(handleError);

Get

constclient=require('@button/button-client-node')('sk-XXX');client.customers.get('customer-1234').then(handleResult).catch(handleError);

Links

Create

client.links.create({url: "https://www.jet.com",experience: {btn_pub_ref: "my-pub-ref",btn_pub_user: "user-id"}}).then(handleResult).catch(handleError);

Get Info

client.links.getInfo({url: "https://www.jet.com"}).then(handleSuccess).catch(handleError);

Transactions

All

Transactions are a paged resource. The response object will contain properties meta.next and meta.previous which can be supplied to subsequent invocations of #all to fetch additional results.

Unlike the accounts.transaction resource, which only queries a single account's transactions, the transactions.all resource queries all of an organizations transactions.

#all accepts an optional second parameter, options which may define the follow keys to narrow results:

options

• cursor: An API cursor to fetch a specific set of results
• start: An ISO-8601 datetime string to filter only transactions after start
• end: An ISO-8601 datetime string to filter only transactions before end
• time_field: Which time field start and end filter on.

constclient=require('@button/button-client-node')('sk-XXX');// without options argument//client.transactions.all().then(handleSuccess).catch(handleError);// with options argument//client.transactions.all({cursor: 'cXw',start: '2015-01-01T00:00:00Z',end: '2016-01-01T00:00:00Z',time_field: 'modified_date'}).then(handleResult).catch(handleError);

Utils

Utils houses generic helpers useful in a Button Integration.

#isWebhookAuthentic

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

constexpress=require('express');constbodyParser=require('body-parser');constutils=require('@button/button-client-node').utilsconstapp=express();functionverify(req,res,buf,encoding){constisAuthentic=utils.isWebhookAuthentic(process.env['WEBHOOK_SECRET'],buf,req.headers['X-Button-Signature']);if(!isAuthentic){thrownewError('Invalid Webhook Signature');}}app.use(bodyParser.json({verify: verify,type: 'application/json'}));

Contributing

• Installing development dependencies: npm install
• Running tests: npm test
• Running lint: npm run lint