aftership-sdk-nodejs - GitLite

KO | EN

gitlite — search

#hacktoberfest #ai #typescript #llm #go #golang #machine-learning #deep-learning #linux #docker #nodejs #awesome #kubernetes #ios

aftership-sdk-nodejs

(★ 62)

The node.js SDK of AfterShip API

파일 탐색기

최종 버전 다운로드 (.zip)

- .gitignore
- e2e.test.js
- test_aftership.js
- test_courier.js
- test_estimated_delivery_date.js
- test_last_checkpoint.js
- test_notification.js
- test_tracking.js
- test_util.js
- courier.js
- last_checkpoint.js
- notification.js
- tracking.js
- - run.sh
  - setup.sh
- - courier_endpoint.ts
  - estimated_delivery_date_endpoint.ts
  - last_checkpoint_endpoint.ts
  - notification_endpoint.ts
  - tracking_endpoint.ts
- - error.ts
  - error_enum.ts
- - courier.ts
  - estimated_delivery_date.ts
  - last_checkpoint.ts
  - notification.ts
  - tracking.ts
- - api_request.ts
  - auth_enum.ts
  - signature.ts
  - util.ts
  - version.ts
- - aftership_option.ts
  - aftership_response.ts
  - rate_limit.ts
- index.ts
.editorconfig
.gitignore
.npmignore
.publishignore
CHANGELOG.md
CONTRIBUTING.md
jest.config.js
LICENSE
package.json
README.md
tsconfig.json
tslint.json
yarn.lock

# 설치 가이드

1. 코드 내려받기

git clone https://github.com/AfterShip/aftership-sdk-nodejs

깃허브에서 프로젝트 코드 전체를 내 컴퓨터로 내려받습니다.

cd aftership-sdk-nodejs

방금 내려받은 프로젝트 폴더 안으로 이동합니다.

2. Node.js

쉬움 추천

사전 준비물

Git GitHub에서 프로젝트 코드를 내려받으려면 필요합니다.
Node.js npm 명령어를 쓰려면 Node.js가 설치되어 있어야 합니다. LTS(장기지원) 버전을 추천합니다.

npm install aftership

package.json에 명시된 라이브러리들을 내려받아 설치합니다.

npm run test

이 명령어를 터미널에 그대로 입력해 실행하세요.

✅ 명령어 실행 후 터미널에 나타나는 주소(보통 http://localhost:3000 형태)를 브라우저에서 열어보세요.

이 레포의 README에 적힌 실제 명령어를 그대로 가져왔습니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Deprecation notice: New Version Available

This version of the SDK has been deprecated and replaced with the newly reconstructed SDK.

For the latest API features and improved integration, please visit our updated repository at https://github.com/AfterShip/tracking-sdk-nodejs and follow the provided instructions.

# aftership-sdk-node

[![node](https://img.shields.io/node/v/aftership.svg)](https://nodejs.org/en/)
[![npm](https://img.shields.io/npm/v/aftership.svg)](https://www.npmjs.com/package/aftership)
[![npm](https://img.shields.io/npm/dm/aftership.svg)](https://www.npmjs.com/package/aftership)
[![npm](https://img.shields.io/npm/l/aftership.svg)](https://www.npmjs.com/package/aftership)

node.js SDK for AfterShip API

## Key features

- The SDK is now isomorphic, you can use it on both client and server side.
- Support IntelliSense in IDE
- Support TypeScript

## Installation
```
npm install aftership
```

## Quick Start

```javascript
const { AfterShip } = require('aftership');
const aftership = new AfterShip('YOUR_API_KEY');

aftership.courier.listAllCouriers()
  .then(result => console.log(result))
  .catch(err => console.log(err));

/** Console
  { total: 335,
    couriers:
     [ ... ]
  }
*/
```

## Test
```
npm run test
```

## Table of contents

- [Constructor(api_key[, options])](#constructorapi_key-options)
- [Endpoints](#endpoints)
- [Rate Limiter](#rate-limiter)
- [Error Handling](#error-handling)
- [Examples](#examples)
	- [/couriers](#couriers)
	- [/trackings](#trackings)
	- [/last_checkpoint](#last_checkpoint)
	- [/notifications](#notifications)
- [Migrations](#migrations)
- [Help](#help)
- [Contributing](#contributing)

## 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/tracking/2023-10'
	- `user_agent_prefix` - *string*, prefix of User-Agent in headers, default 'aftership-sdk-nodejs'
  - `auth_type` -number, if authentication type is AES, use `AuthType.Aes`, default `AuthType.ApiKey`.
  - `api_secret` -string, if authentication type is AES, it is required.

Example:
```javascript
// Construct with options
const aftership = new AfterShip('YOUR_API_KEY', {
  auth_type: AuthType.Aes, api_secret:'YOUR_API_SECRET'
});
```

## Endpoints

The AfterShip instance has the following properties which are exactly the same as the API endpoins:

- `courier` - Get a list of our supported couriers.
- `tracking` - Create trackings, update trackings, and get tracking results.
- `last_checkpoint` - Get tracking information of the last checkpoint of a tracking.
- `notification` - Get, add or remove contacts (sms or email) to be notified when the status of a tracking has changed.

Make request in a specific endpoint

```javascript
// GET /trackings/:slug/:tracking_number
aftership.tracking
  .getTracking({
    slug: "ups",
    tracking_number: "1234567890",
  })
  .then(result => console.log(result))
  .catch(err => console.log(err));
```

## Rate Limiter

See the [Rate Limit](https://www.aftership.com/docs/aftership/quickstart/rate-limit) to understand the AfterShip rate limit policy.

You can get the recent rate limit by `aftership.rate_limit`. Initially all value are `null`.
```javascript
const { AfterShip } = require('aftership');
const aftership = new AfterShip('YOUR_API_KEY');

console.log(aftership.rate_limit);

// console output
// { reset: null, limit: null, remaining: null }
```
After making an API call, it will be set.
```javascript
aftership.courier.listCouriers()
  .then(result => {
    console.log(result);
    console.log(aftership.rate_limit);
  })
  .catch(err => console.log(err));

// console output
// { limit: 600, remaining: 599, reset: 1453281417 }
```

## 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

> 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 `endpoint method`  
`error.type` is one of [error_enum](https://github.com/AfterShip/aftership-sdk-nodejs/blob/master/src/error/error_enum.js)  
**Throw** by the SDK instance

```js
const { AfterShip } = require('aftership');
const aftership = new AfterShip('YOUR_API_KEY');

// GET /notifications/:slug/:tracking_number
aftership.notification.getNotification()
  .then(result => console.log(result))
  .catch(err => console.log(err));

/*
{ Error: HandlerError: You must specify the id or slug and tracking number
  type: 'HandlerError',
  code: '',
  data: undefined,
  responseBody: '' }
*/
```

### Request Error

Error return by the `request` module  
`error.type` could be `ETIMEDOUT`, `ECONNRESET`, etc.  
**Catch** by promise

```js
const { AfterShip } = require('aftership');
const aftership = new AfterShip('YOUR_API_KEY');

aftership.courier.listCouriers()
  .then(result => console.log(result))
  .catch(err => console.log(err));
/*
{ Error: getaddrinfo ENOTFOUND api.aftership.com api.aftership.com:443
  type: 'ENOTFOUND',
  code: 'ENOTFOUND',
  ... }
*/
```

### API Error

Error return by the Aftership API  
`error.type` should be same as [request error](https://www.aftership.com/docs/aftership/quickstart/request-errors#http-status-code-summary).
**Catch** by promise

```js
const { AfterShip } = require('aftership');
const aftership = new AfterShip('INVALID_API_KEY');

aftership.courier.listCouriers()
  .then(result => console.log(result))
  .catch(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

```javascript
aftership.courier.listCouriers()
  .then(result => console.log(result))
  .catch(e => console.log(e));
```

**GET** /couriers/all

```javascript
aftership.courier.listAllCouriers()
  .then(result => console.log(result))
  .catch(e => console.log(e));
```

**POST** /couriers/detect

```javascript
const payload = {
  'tracking': {
    'tracking_number': '906587618687',
    'tracking_postal_code': 'DA15BU',
    'tracking_ship_date': '20131231',
    'tracking_account_number': '1234567890',
    'slug': ['dhl', 'ups', 'fedex']
  }
};
aftership.courier.detectCouriers(payload)
  .then(result => console.log(result))
  .catch(e => console.log(e));
```

### /trackings

**POST** /trackings

```javascript
const payload = {
    'tracking': {
        'slug': 'dhl',
        'tracking_number': '123456789',
        'title': 'Title Name',
        'smses': [
            '+18555072509',
            '+18555072501'
        ],
        'emails': [
            'email@yourdomain.com',
            'another_email@yourdomain.com'
        ],
        '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.tracking
  .createTracking(payload)
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

**DELETE** /trackings/:slug/:tracking_number

```javascript
aftership.tracking
  .deleteTracking({
    slug: "ups",
    tracking_number: "1234567890",
  })
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

**GET** /trackings

```javascript
const query = {
  slug: 'dhl,ups,usps'
};
aftership.tracking
  .listTrackings(query)
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

**GET** /trackings/:slug/:tracking_number

```javascript
aftership.tracking
  .getTracking({
    slug: "ups",
    tracking_number: "1234567890",
  })
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

Tip: You can also add `optional_parameters` to `/:slug/:tracking_number`

```javascript
// GET /trackings/:slug/:tracking_number?tracking_postal_code=:postal_code&tracking_ship_date=:ship_date
aftership.tracking
  .getTracking({
    slug: "ups",
    tracking_number: "1234567890",
    optional_parameters: {
      tracking_postal_code: "1234",
      tracking_ship_date: "20200423",
    }
  })
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

> Pro Tip: You can always use /:id to replace /:slug/:tracking_number.
```javascript
// GET /trackings/:id
aftership.tracking
  .getTracking({
    id: "1234567890",
  })
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

**PUT** /trackings/:slug/:tracking_number

```javascript
const payload = {
  tracking: {
    title: "New Title",
  },
};
aftership.tracking
  .updateTracking({
    slug: "ups",
    tracking_number: "1234567890",
  }, payload)
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

**POST** /trackings/:slug/:tracking_number/retrack

```javascript
aftership.tracking
  .retrack({
    slug: "ups",
    tracking_number: "1234567890",
  })
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

**POST** /trackings/:slug/:tracking_number/mark-as-completed

```javascript
aftership.tracking
  .markAsCompleted({
    slug: "ups",
    tracking_number: "1234567890",
  }, {
    reason: "DELIVERED"
  })
  .then((result) => console.log(result))
  .catch((e) => console.log(e));
```

### /last_checkpoint

**GET** /last_checkpoint/:slug/:tracking_number

```javascript
aftership.last_checkpoint.getLastCheckpoint({
    slug: 'ups',
    tracking_number: '1234567890',
  })
  .then(result => console.log(result))
  .catch(e => console.log(e));
```

### /notifications

**GET** /notifications/:slug/:tracking_number

```javascript
aftership.notification.getNotification({
    slug: 'ups',
    tracking_number: '1234567890',
  })
  .then(result => console.log(result))
  .catch(e => console.log(e));
```

**POST** /notifications/:slug/:tracking_number/add

```javascript
const payload = {
  'notification': {
    'emails': ['user1@gmail.com','user2@gmail.com','invalid EMail @ Gmail. com'],
    'smses': ['+85291239123', '+85261236123', 'Invalid Mobile Phone Number']
  }
};
aftership.notification.addNotification({
    slug: 'ups',
    tracking_number: '1234567890',
  }, payload)
  .then(result => console.log(result))
  .catch(e => console.log(e));
```

**POST** /notifications/:slug/:tracking_number/remove

```javascript
const payload = {
  'notification': {
    'emails': ['user1@gmail.com','user2@gmail.com','invalid EMail @ Gmail. com'],
    'smses': ['+85291239123', '+85261236123', 'Invalid Mobile Phone Number']
  }
};
aftership.notification.removeNotification({
    slug: 'ups',
    tracking_number: '1234567890',
  }, payload)
  .then(result => console.log(result))
  .catch(e => console.log(e));
```

## Migrations
```javascript
// v5 (old version)
const Aftership = require('aftership')('YOUR_API_KEY');

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

// v6 (new version)
const { AfterShip } = require('aftership');
const aftership = new AfterShip('YOUR_API_KEY');

aftership.courier.listAllCouriers()
  .then(result => console.log(result))
  .catch(err => console.log(err));
```

## Help
If you get stuck, we're here to help. The following are the best ways to get assistance working through your issue:

- [Issue Tracker](https://github.com/AfterShip/aftership-sdk-nodejs/issues) for questions, feature requests, bug reports and general discussion related to this package. Try searching before you create a new issue.
- [Slack AfterShip-SDKs](https://aftership-sdk-slackin.herokuapp.com/): a Slack community, you can find the maintainers and users of this package in #aftership-sdks.

## Contributing
For details on contributing to this repository, see the [contributing guide](https://github.com/AfterShip/aftership-sdk-nodejs/blob/master/CONTRIBUTING.md).

## License
Copyright (c) 2016-2020 AfterShip

Licensed under the MIT license.

[![FOSSA Status](https://app.fossa.com/api/projects/git%2Bgithub.com%2FAfterShip%2Faftership-sdk-nodejs.svg?type=large)](https://app.fossa.com/projects/git%2Bgithub.com%2FAfterShip%2Faftership-sdk-nodejs?ref=badge_large)