sparkpay node client

Node.js-based client wrapper for SparkPay REST API

Installation

npm install sparkpay --save

Initialization

Each client instance is initialized using the init(config) method. This allows multiple client instance for different storefronts and/or with unique API tokens for accessing different scopes of the API. The config should be an object with at least the required domain and token properties.

var sparkpay = require('sparkpay').init({
  domain: 'example.com', // Your store's URL
  token: 'abcdefghijklmnopqrstuvwxyz123456' // API access token
});

Config

{
  // the url of the storefront you want this instance to access
  domain: 'example.com',

  // an API token with the scope permissions you want this instance to access
  token: 'abcdefghijklmnopqrstuvwxyz123456'
}

Making Requests

Requests are made by specifying the method and the resource, as well as optional paramenters. Resource methods are named using snake_case to parallel the official designations as used in request URLs.

• You can find a list of resources in the official documentation.

For example, to request all the gift certificates issued in your store:

sparkpay.gift_certificates.get();

Requests are Promise-based using mzabriskie/axios which implements stefanpenner/es6-promise (a subset of rsvp.js).

For example, to log a list of order ID's and their order dates to the console:

sparkpay.orders.get()
  .then(function(response) {
    // log the total count of orders to console
    console.log(response.total_count);
    // log each individual order id and order data to console
    response.orders.forEach(function(order) {
      console.log(order.id);
      console.log(order.ordered_at);
    });
  }).catch(function(error) {
    // log any error response
    console.log(error);
  });

For details about how to use promises, see the JavaScript Promises HTML5Rocks article.

Optional Request Parameters

Requests can include optional parameters based on the common usage and query syntax described in the official documentation.

id

The id parameter requests a specific object from a resource rather than returning an array of matching objects.

So calling sparkpay.orders.get() may result in a response like:

{
  total_count: 1,
  orders: [
    {
      id: 1,
      ordered_at: '2016-04-20T16:20:00-05:00'
      ...
    }
  ]
}

This is the equivalent of an API request to /api/v1/orders

Whereas calling sparkpay.orders.get( { id: 1 } ) will result in a response like:

{
  id: 1,
  ordered_at: '2016-04-20T16:20:00-05:00'
  ...
}

This is the equivalent of an API request to /api/v1/orders/1

fields

The fields parameter can be used to include in the response, as described under common usage in the official documentation.

If you want multiple fields, it should be an array:

sparkpay.products.get({
  fields: [ 'id', 'item_name', 'item_number', 'price', 'categories' ]
})

This is the equivalent of an API request to /api/v1/products?fields=id,item_name,item_number,price,categories

If you only want a single field included, it can be a string:

sparkpay.products.get({
  fields: 'item_name'
})

This is the equivalent of an API request to /api/v1/products?fields=item_name

For a list of available fields for the resource you are requesting, check the official documentation.

query

The query parameter should be an object with property names matching the field you want to query. The value can be a string or number if you simply want to search for matches.

For example, to search for orders with a status ID of 2:

sparkpay.orders.get({
  query: {
    order_status_id: 2
  }
})

This is the equivalent of a query using the eq comparison operator.

Comparison Operators

Alternatively, you may specify comparison operators as described in the official documentation.

eq

Returns results where a field is equal to the supplied value.

sparkpay.products.get({
  query: {
    item_name: { op: 'eq', value: 'test' }
  }
})

This is the equivalent of an API request to /api/v1/products?item_name=test

not

Returns results where a field is not equal to the supplied value.

sparkpay.products.get({
  query: {
    item_name: { op: 'not', value: 'test' }
  }
})

This is the equivalent of an API request to /api/v1/products?item_name=not:test

like

Returns results where a field contains the supplied value.

sparkpay.products.get({
  query: {
    item_name: { op: 'like', value: 'test' }
  }
})

This is the equivalent of an API request to /api/v1/products?item_name=like:test

gt

Returns results where a field is greater than the supplied value.

sparkpay.products.get({
  query: {
    price: { op: 'gt', value: 5.00 }
  }
})

This is the equivalent of an API request to /api/v1/products?price=gt:5.00

gte

Returns results where a field is greater than or equal to the supplied value.

sparkpay.products.get({
  query: {
    price: { op: 'gte', value: 5.00 }
  }
})

This is the equivalent of an API request to /api/v1/products?price=gte:5.00

lt

Returns results where a field is less than the supplied value.

sparkpay.products.get({
  query: {
    price: { op: 'lt', value: 25.00 }
  }
})

This is the equivalent of an API request to /api/v1/products?price=lt:25.00

lte

Returns results where a field is less than or equal to the supplied value.

sparkpay.products.get({
  query: {
    price: { op: 'lte', value: 25.00 }
  }
})

This is the equivalent of an API request to /api/v1/products?price=lte:25.00

Conjunction Operators

You may join comparison operators in a query using conjunction operators as described in the official documentation.

AND

This is the default when multiple fields are specified in a query.

sparkpay.products.get({
  query: {
    item_name: 'test',
    price: { op: 'gt', value: 5.00 }
  }
})

This is the equivalent of an API request to /api/v1/products?item_name=test&price=gt:5.00

The AND conjunction operator can also be used to specify multiple comparison values for a single field by assigning a value property which is an array of the comparison operator queries you want to join together.

sparkpay.products.get({
  query: {
    price: {
      op: 'AND',
      value: [
        { op: 'gt', value: 5.00 },
        { op: 'lte', value: 25.00 }
      ]
    }
  }
})

This is the equivalent of an API request to /api/v1/products?price=gt:5.00+AND+lte:25.00

OR

Can be used to override the default AND behavior when multiple fields are specified in a query by assigning a single query to the value property.

sparkpay.products.get({
  query: {
    item_name: { op: 'like', value: 'test' },
    price: {
      op: 'OR',
      value: { op: 'lte', value: 25.00 }
    }
  }
})

This is the equivalent of an API request to /api/v1/products?item_name=like:test&price=OR+lte:25.00

The OR conjunction operator can also be used to specify multiple comparison values for a single field by assigning a value property which is an array of the comparison operator queries you want to join together.

sparkpay.products.get({
  item_name: {
    op: 'OR',
    value: [
      { op: 'like', value: 'doge' },
      { op: 'like', value: 'wow' }
    ]
  }
})

This is the equivalent of an API request to /api/v1/products?item_name=like:doge+OR+like:wow

expand

The expand parameter can be used to specify a list of nested resources to be added to the response.

If you want to expand multiple nested resources, it should be an array:

sparkpay.products.get({
  expand: [ 'categories' ,'attributes' ]
})

This is the equivalent of an API request to api/v1/products?expand=categories,attributes

If you only want a single nest resource filled, it can be a string:

sparkpay.products.get({
  expand: 'categories'
})

This is the equivalent of an API request to api/v1/products?expand=categories

noCache

The noCache parameter can be used to include a Cache-Control: no-cache header in the request.

sparkpay.products.get({
  query: { item_name: 'test' },
  noCache: true
})

See Caching in the official documentation for details.

Collection

The collect method will make a recursive tail call whenever a response includes a next_page value.

Calling sparkpay.orders.collect() will collect all orders in the store and return them concatenated into a single array.

Collection can also be invoked by adding collect: true to a get method's request parameters. Calling sparkpay.orders.get({ collect: true }) is the same as calling sparkpay.orders.collect().

Resource responses from SparkPay are limited to 100 per request. So if your store has 450 orders, it will take five separate HTTP requests to collect them all. Be careful with the collect method; if your store has a lot of data, it could take quite some time to collect all of the responses.

Timeouts

SparkPay stores are restricted to 50 requests per 10 seconds. If your request is rate limited, it will automatically be queued and retried after the time specified in the Retry-After header included in the response.