aftership-sdk-node

node.js SDK for AfterShip API

Installation

npm install aftership

Quick Start

const Aftership = require('aftership')('YOUR_API_KEY');

Aftership.call('GET', '/couriers/all', function (err, result) {
	if (err) {
		console.log(err);
	} else {
		console.log(result);
	}
});

// Or do it with promise 

Aftership.call('GET', '/couriers/all').then(function (result) {
	console.log(result);
}).catch(function (err) {
	console.log(err);
});

/** Console
{ meta: { code: 200 },
  data:
   { total: 335,
     couriers:
      [ ... ]
   }
}
*/

Test

mocha --recursive

Constructor(api_key, options)
call(method, path, options, callback)
Proxy Method
Rate Limiter
Retry policy
Error Handling
Examples

Constructor(api_key, options)

Create AfterShip instance with options

api_key - Require - your Aftership API key
options - Optional - object of request options
- endpoint - string, AfterShip endpoint, default 'https://api.aftership.com/v4'
- proxy - string, proxy, default is null
- retry - boolean, retry if fail? default is true, see Retry policy
- rate - boolean, retry if response with 429 Too Many request error see Rate Limiter

Example:

// Construct with options
const Aftership = require('aftership')('YOUR_API_KEY', {
	endpoint: 'https://api.aftership.com/OLDER_VERSION',
	proxy: 'http://username:[email protected]',
	retry: false
});

// Make your call
Aftership.call('GET', '/couriers/all', function (err, result) {
	// ...
});

call(method, path, options, callback)

Make request with option

method - Require - Either get, post, put or delete, case insensitive
path - Require string, start with /, see available path here
options - Optional - object of request options
- api_key - string, AfterShip API key, override default api_key if set
- body - object, POST body
- query - object, query object
- retry - boolean, retry if fail? override default retry if set, see Retry policy
- raw - boolean, if true, return result as string, else return as object, default is false
callback - the callback to handle error and result, the result is the response body of the request

Proxy Method (GET, POST, PUT, DELETE)

There are also interface GET, POST, PUT, DELETE which are proxy to Aftership.call(...)

Aftership.call('GET', '/path', options, callback);
// is equivalent to
Aftership.GET('/path', options, callback);

// So as `POST`, `PUT` and `DELETE`

Rate Limiter

To understand AfterShip rate limit policy, please see limit session in https://www.aftership.com/docs/api/4

You can get the recent rate limit by aftership.rate_limit. Initially all value are null.

const Aftership = require('aftership')('YOUR_API_KEY');
console.log(Aftership.rate_limit);

// console output
// { 'YOUR_API-KEY' : { reset: null, limit: null, remaining: null } }

After making an API call, it will be set.

Aftership.call('GET', '/couriers', function (err, result) {
	console.log(Aftership.rate_limit);
});

// console output
// { 'YOUR_API-KEY' : { limit: 600, remaining: 599, reset: 1453281417 } }

When the API response with 429 Too Many request error

if rate is true, it wont throw, will delay the job, retry when the rate limit is reset.
if rate is false, it will return 429 Too Many request error to the callback

Retry policy

To understand error of AfterShip, please see https://www.aftership.com/docs/api/4/errors

For this SDK, errors below are retriable.

HTTP status code == [500, 502, 503, 504] from API
ETIMEDOUT/ECONNRESET/ECONNREFUSED from node.js

You can set the retry flag

in constructor as default retry flag
specify in options of call() method

When an retriable error comes,

if retry is true,
- if retry_count < 5, use the same payload to retry after 1 second
- if retry_count == 5, return the error to the callback, with retry_count
if retry is false, return the error to the callback

Error Handling

There are 3 kinds of error

SDK Error
Request Error
API Error

Error object of this SDK contain fields:

type - Require - type of the error, please handle each error by this field
message - Optional - detail message of the error
data - Optional - data lead to the error
code - Optional - error code for API Error
response_body - Optional - response body of API Error
retry_count - Optional - number of retry, if the error is retriable

Please handle each error by its type, since it is a require field

SDK Error

Error return by the SDK instance, mostly invalid param type when calling constructor or call function
error.type is one of error_enum
Throw by the SDK instance

const Aftership = require('aftership')('YOUR_API_KEY');

try {
	Aftership.call('INVALID_METHOD', '/couriers/all', function (err, result) {
		// ...
	});
} catch (e) {
	console.log(e);
}

/*
{ [Error: HandlerError: Invalid Method value]
  type: 'HandlerError',
  message: 'HandlerError: Invalid Method value',
  data: 'INVALID_METHOD' 
  ... }
*/

Request Error

Error return by the request module
error.type could be ETIMEDOUT, ECONNRESET, etc.
Catch by promise or Pass through the first param of callback

const Aftership = require('aftership')('YOUR_API_KEY');

Aftership.call('GET', '/couriers/all', function (err, result) {
	if (err) {
		console.log(err);
	}
});
/*
{ [Error]
  code: 'ECONNRESET',
  type: 'ECONNRESET' 
  ... }
*/

API Error

Error return by the Aftership API
error.type shuold be same as https://www.aftership.com/docs/api/4/errors
Catch by promise or Pass through the first param of callback

const Aftership = require('aftership')('INVALID_API_KEY');

Aftership.call('GET', '/couriers/all', function (err, result) {
	if (err) {
		console.log(err);
	}
});
/*
{ [Error: Invalid API key.]
  type: 'Unauthorized',
  message: 'Invalid API key.',
  code: 401,
  data: {},
  response_body: '{"meta":{"code":401,"message":"Invalid API key.","type":"Unauthorized"},"data":{}}' }
*/

Examples

/couriers

GET /couriers

Aftership.call('GET', '/couriers', function (err, result) {
	// Your code here
});

GET /couriers/all

Aftership.call('GET', '/couriers/all', function (err, result) {
	// Your code here
});

POST /couriers/detect

let body = {
	'tracking': {
		'tracking_number': '906587618687',
		'tracking_postal_code': 'DA15BU',
		'tracking_ship_date': '20131231',
		'tracking_account_number': '1234567890',
		'slug': ['dhl', 'ups', 'fedex']
	}
};
Aftership.call('POST', '/couriers', {
	body: body
}, function (err, result) {
	// Your code here
});

/trackings

POST /trackings

let body = {
    'tracking': {
        'slug': 'dhl',
        'tracking_number': '123456789',
        'title': 'Title Name',
        'smses': [
            '+18555072509',
            '+18555072501'
        ],
        'emails': [
            '[email protected]',
            '[email protected]'
        ],
        'order_id': 'ID 1234',
        'order_id_path': 'http://www.aftership.com/order_id=1234',
        'custom_fields': {
            'product_name': 'iPhone Case',
            'product_price': 'USD19.99'
        }
    }
};
Aftership.call('POST', '/trackings', {
	body: body
}, function (err, result) {
	// Your code here
});

DELETE /trackings/:slug/:tracking_number

Aftership.call('DELETE', '/trackings/ups/1234567890', function (err, result) {
	// Your code here
});

GET /trackings

let query = {
	slug: 'dhl,ups,usps'
};
Aftership.call('GET', '/trackings', {
	query: query
}, function (err, result) {
	// Your code here
});

GET /trackings/exports

Aftership.call('GET', '/trackings/exports', function (err, result) {
	// Your code here
});

GET /trackings/:slug/:tracking_number

Aftership.call('GET', '/trackings/ups/1234567890', function (err, result) {
	// Your code here
});

GET /trackings/:slug/:tracking_number

let body = {
	'tracking': {
		'title': 'New Title'
	}
};
Aftership.call('PUT', '/trackings/ups/1234567890', {
	body: body
}, function (err, result) {
	// Your code here
});

POST /trackings/:slug/:tracking_number/retrack

Aftership.call('POST', '/trackings/ups/1234567890/retrack', function (err, result) {
	// Your code here
});

/last_checkpoint

GET /last_checkpoint/:slug/:tracking_number

Aftership.call('GET', '/last_checkpoint/ups/1234567890', function (err, result) {
	// Your code here
});

/notifications

GET /notifications/:slug/:tracking_number

Aftership.call('GET', '/notifications/ups/1234567890', function (err, result) {
	// Your code here
});

POST /notifications/:slug/:tracking_number/add

let body = {
	'notification': {
		'emails': ['[email protected]','[email protected]','invalid EMail @ Gmail. com'],
		'smses': ['+85291239123', '+85261236123', 'Invalid Mobile Phone Number']
	}
};
Aftership.call('POST', '/notifications/ups/1234567890/add', {
	body: body
}, function (err, result) {
	// Your code here
});

POST /notifications/:slug/:tracking_number/remove

let body = {
	'notification': {
		'emails': ['[email protected]','[email protected]','invalid EMail @ Gmail. com'],
		'smses': ['+85291239123', '+85261236123', 'Invalid Mobile Phone Number']
	}
};
Aftership.call('POST', '/notifications/ups/1234567890/remove', {
	body: body
}, function (err, result) {
	// Your code here
});

License

Licensed under the MIT license.

freewing-jp / aftership-sdk-nodejs Goto Github PK