{"id":15625846,"url":"https://github.com/postmen/postmen-sdk-js","last_synced_at":"2026-01-03T15:13:10.256Z","repository":{"id":34655095,"uuid":"38624725","full_name":"postmen/postmen-sdk-js","owner":"postmen","description":"AfterShip Shipping (Postmen) API Client Library for JS (USPS, FedEx, UPS, DHL and more)","archived":false,"fork":false,"pushed_at":"2023-03-09T12:57:58.000Z","size":95,"stargazers_count":14,"open_issues_count":2,"forks_count":6,"subscribers_count":5,"default_branch":"master","last_synced_at":"2024-04-28T08:56:27.782Z","etag":null,"topics":["aftership","api","postmen","sdk","shipping","shipping-api"],"latest_commit_sha":null,"homepage":"https://www.aftership.com/postmen","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/postmen.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2015-07-06T14:41:18.000Z","updated_at":"2023-03-09T07:45:08.000Z","dependencies_parsed_at":"2022-09-07T16:32:23.745Z","dependency_job_id":"e1e97cb5-525b-4e41-a906-d351e9c98063","html_url":"https://github.com/postmen/postmen-sdk-js","commit_stats":null,"previous_names":["postmen/sdk-js"],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postmen%2Fpostmen-sdk-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postmen%2Fpostmen-sdk-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postmen%2Fpostmen-sdk-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/postmen%2Fpostmen-sdk-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/postmen","download_url":"https://codeload.github.com/postmen/postmen-sdk-js/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":242524113,"owners_count":20143628,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aftership","api","postmen","sdk","shipping","shipping-api"],"created_at":"2024-10-03T10:06:38.073Z","updated_at":"2026-01-03T15:13:10.211Z","avatar_url":"https://github.com/postmen.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# postmen\n\n[![Build Status](https://travis-ci.org/postmen/postmen-sdk-js.svg?branch=master)](https://travis-ci.org/postmen/postmen-sdk-js)\n[![codecov](https://codecov.io/gh/postmen/postmen-sdk-js/branch/master/graph/badge.svg)](https://codecov.io/gh/postmen/postmen-sdk-js)\n[![Dependency Status](https://gemnasium.com/badges/github.com/postmen/postmen-sdk-js.svg)](https://gemnasium.com/github.com/postmen/postmen-sdk-js)\n\n[![node](https://img.shields.io/node/v/postmen.svg)]()\n[![npm](https://img.shields.io/npm/v/postmen.svg)]()\n[![npm](https://img.shields.io/npm/dm/postmen.svg)]()\n[![npm](https://img.shields.io/npm/l/postmen.svg)]()\n\n![codecov.io](https://codecov.io/gh/postmen/postmen-sdk-js/branch/master/graphs/commits.svg)\n\n## Introduction\nNode.js SDK for [Postmen API](https://www.aftership.com/docs/shipping/quickstart/api-quick-start).\nFor problems and suggestions please open [GitHub issue](https://github.com/postmen/postmen-sdk-js/issues)\n\n\u003c!-- START doctoc generated TOC please keep comment here to allow auto update --\u003e\n\u003c!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE --\u003e\n**Table of Contents**\n\n- [Installation](#installation)\n    - [NPM Installation](#npm-installation)\n- [Quick Start](#quick-start)\n- [class Postmen](#class-postmen)\n    - [Postmen(api_key, region, config](#postmenapi_key-region-config--array)\n    - [create(path, input, config, callback)](#createpath-config-callback)\n    - [get(path, input, config, callback)](#getpath-payload-config--callback)\n    - [Proxy methods of GET,POST,PUT,DELETE](#proxy-method-get-post-put-delete)\n    - [Chainable Function](#chainable-function)\n- [Promise](#promise)\n- [Rate Limiter](#rate-limiter)\n- [Retry Policy](#retry-policy)\n- [Examples](#examples)\n    - [Full list](#full-list)\n    - [How to run](#how-to-run)\n    - [Navigation table](#navigation-table)\n- [Testing](#testing)\n- [License](#license)\n\n\u003c!-- END doctoc generated TOC please keep comment here to allow auto update --\u003e\n\n## Installation\n\n#### NPM installation\n\n```\nnpm install postmen\n```\n\n## Quick Start\n\nIn order to get API key refer to the [documentation](https://www.aftership.com/docs/shipping/quickstart/api-quick-start#2-get-the-api-key).\n\n```javascript\n'use strict';\n\nconst Postmen = require('postmen');\n// TODO key of the Postmen instance\nlet api_key = 'api-key',\n// TODO region of the Postmen instance\nlet region = 'sandbox';\n\nlet postmen = Postmen(api_key, region);\n\n// get all labels by using callback\npostmen.get('/labels', function (err, result) {\n\tif (err) {\n\t\tconsole.log(err);\n\t} else {\n\t\tconsole.log(result);\n\t}\n});\n\n// get all labels by using promise\npostmen.get('/labels').then(function (result) {\n\t\tconsole.log(result);\n}).catch(function (err) {\n    console.log(err);\n});\n\n// get all labels by using promise with chainable function\npostmen.useApiKey('ANOTHER_API_KEY').setRetry(false).get('/labels').then(function (result) {\n    console.log(result);\n}).catch(function (err) {\n    console.log(err);\n});\n\n// get a particular  labels\npostmen.get('/rates/put-your-label-id-here', function (err, result) {\n\tif (err) {\n\t\tconsole.log(err);\n\t} else {\n\t\tconsole.log(result);\n\t}\n});\n\n```\n\n## class Postmen\n\n#### Postmen(api_key, region, config)\n\nInitiate Postmen SDK object.\nIn order to get API key and choose a region refer to the [documentation](https://docs.postmen.com/overview.html).\n\n| Argument             | Required | Type    | Default | Description                                                        |\n|----------------------|----------|---------|---------|--------------------------------------------------------------------|\n| `api_key`            | YES      | string  | N/A     | API key                                                            |\n| `region`             | YES      | string  | N/A     | API region (`sandbox`, `production`)                               |\n| `config`             | NO       | object  | null    | Options                                                            |\n| `config['endpoint']` | —        | string  | null    | Custom URL API endpoint                                            |\n| `config['retry']`    | —        | boolean | `true`  | override `default retry` if set, see [Retry policy](#retry-policy) |\n| `config['rate']`     | —        | boolean | `true`  | Wait before API call if rate limit exceeded or retry on 429 error  |\n| `config['raw']`      | —        | boolean | `false` | To return API response as a raw string                             |\n| `config['proxy']`    | —        | string  | null    | Proxy credentials                                                  |\n\n#### create(path, input, config, callback)\nCreates postmen api object\n\n| Argument          | Required | Type     | Default | Description                                                                             |\n|-------------------|----------|----------|---------|-----------------------------------------------------------------------------------------|\n| `path`            | YES      | string   | N/A     | start with `/`, see available path [here](https://docs.postmen.com/index.html) key      |\n| `input`           | YES      | object   | `null`  | object of request config                                                                |\n| `input['body']`   | YES      | string   | `null`  | `POST` body                                                                             |\n| `input['query']`  | NO       | object   | `null`  | `query` object                                                                          |\n| `config`          | NO       | object   | `null`  | object of request config                                                                |\n| `config['retry']` | NO       | boolean  | `true`  | override `default retry` if set, see [Retry policy](#retry-policy)                      |\n| `config['raw']`   | NO       | boolean  | `false` | if `true`, return result as `string`, else return as `object`                           |\n| `callback`        | NO       | function | N/A     | the callback to handle error and result, the result is the response body of the request |\n\n**API Docs:**\n- [POST /rates](https://docs.postmen.com/#rates-calculate-rates)\n- [POST /labels](https://docs.postmen.com/#labels-create-a-label)\n- [POST /manifests](https://docs.postmen.com/#manifests-create-a-manifest)\n- [POST /cancel-labels](https://docs.postmen.com/#cancel-labels-cancel-a-label)\n- [POST /address-validations](https://docs.postmen.com/#address-validations)\n\n**Examples:**\n- [rates_create.js](https://github.com/postmen/postmen-sdk-js/blob/master/examples/rates_create.js)\n- [labels_create.js](https://github.com/postmen/postmen-sdk-js/blob/master/examples/labels_create.js)\n- [manifests_create.js](https://github.com/postmen/postmen-sdk-js/blob/master/examples/manifests_create.js)\n- [cancel_labels_create.js](https://github.com/postmen/postmen-sdk-js/blob/master/examples/cancel_labels_create.js)\n- [address_validation_create.js](https://github.com/postmen/postmen-sdk-js/blob/master/examples/address_validation_create.js)\n\n#### get(path, input, config,callback)\nGet Postmen API  objects (list or a single objects).\n\n| Argument          | Required | Type     | Default | Description                                                                             |\n|-------------------|----------|----------|---------|-----------------------------------------------------------------------------------------|\n| `path`            | YES      | string   | N/A     | start with `/`, see available path [here](https://docs.postmen.com/index.html) key      |\n| `input`           | NO       | object   | `null`  | object of request config                                                                |\n| `input['body']`   | NO       | string   | `null`  | `POST` body                                                                             |\n| `input['query']`  | NO       | object   | `null`  | `query` object or string                                                                |\n| `config`          | NO       | object   | `null`  | object of request config                                                                |\n| `config['retry']` | NO       | boolean  | `true`  | override `default retry` if set, see [Retry policy](#retry-policy)                      |\n| `config['raw']`   | NO       | boolean  | `false` | if `true`, return result as `string`, else return as `object`                           |\n| `callback`        | NO       | function | N/A     | the callback to handle error and result, the result is the response body of the request |\n\n```javascript\npostmen.get( '/path/label-id', callback);\n// is equivalent to\npostmen.call('GET', '/path/label-id', input, config, callback);\n\npostmen.get( '/path', input, config, callback);\n// is equivalent to\npostmen.call('GET', '/path', input, config, callback);\n```\n**API Docs:**\n- [GET /rates](https://docs.postmen.com/#rates-list-all-rates)\n- [GET /rates/:id](https://docs.postmen.com/#rates-retrieve-rates)\n- [GET /labels](https://docs.postmen.com/#labels-list-all-labels)\n- [GET /labels/:id](https://docs.postmen.com/#labels-retrieve-a-label)\n- [GET /manifests](https://docs.postmen.com/#manifests-list-all-manifests)\n- [GET /manifests/:id](https://docs.postmen.com/#manifests-retrieve-a-manifest)\n- [GET /cancel-labels](https://docs.postmen.com/#cancel-labels-list-all-cancel-labels)\n- [GET /cancel-labels/:id](https://docs.postmen.com/#cancel-labels-retrieve-a-cancel-label)\n\n\n**Examples:**\n- [rates_retrieve.js](https://github.com/postmen/postmen-sdk-js/blob/master/examples/rates_retrieve.js)\n- [labels_retrieve.js](https://github.com/postmen/postmen-sdk-js/blob/master/examples/labels_retrieve.js)\n- [manifests_retrieve.js](https://github.com/postmen/postmen-sdk-js/blob/master/examples/manifests_retrieve.js)\n- [cancel_labels_retrieve.js](https://github.com/postmen/postmen-sdk-js/blob/master/examples/cancel_labels_retrieve.js)\n#### Proxy Method (GET, POST, PUT, DELETE)\n\nThere are also interface `GET`, `POST`, `PUT`, `DELETE` which are proxy to `Postmen.call(...)`\n\n```javascript\npostmen.call('GET', '/path', input, config, callback);\n// is equivalent to\npostmen.GET('/path', input, config, callback);\n\n// So as `POST`, `PUT` and `DELETE`\n```\n\n#### Chainable Function\nUsing chainable function to config now is accepted. Now postmen instance has these chainable function:\n- ```useApiKey()``` temporarily use an api_key to make request\n- ```setProxy()```  overwrite postmen proxy property\n- ```setRetry()``` overwrite postmen retry property\n- ```setRaw()```  overwrite postmen raw property\n\n```javascript\npostmen.useApiKey('ANOTHER_API_KEY').get('labels').then();\n// is equivalent to\nlet input = {};\nlet config = {\n\tapi_key: 'ANOTHER_API_KEY'\n}\npostmen.get('labels', input, config).then();\n```\n\n## Promise:\nOnly [create(path, config, callback)](#createpath-config-callback) and [get(path, config, callback)](#getpath-configcallback) function support promise.\n- [create example](https://github.com/postmen/postmen-sdk-js/blob/master/examples/labels_create.js)\n- [get example](https://github.com/postmen/postmen-sdk-js/blob/master/examples/labels_retrieve.js).\n\n## Rate Limiter:\n\nTo understand Postmen rate limit policy, please see `limit` session in https://docs.postmen.com/ratelimit.html\n\nYou can get the recent rate limit by `postmen.rate_limit`. Initially all value is `{}`.\n```javascript\nlet postmen = Postmen('YOUR_API_KEY', 'region');\nconsole.log(postmen.rate_limit);\n\n// console output\n// {}\n```\nAfter making an API call, it will be set.\n```javascript\npostmen.get('/labels', function (err, result) {\n\tconsole.log(postmen.rate_limit);\n});\n\n// console output\n// { 'YOUR_API-KEY' : { limit: 600, remaining: 599, reset: 1453281417 } }\n```\n\nWhen the API response with `429 Too Many request error`\n- if `rate` is `true`, it wont throw, will delay the job, retry when the rate limit is reset.\n- if `rate` is `false`, it will return `429 Too Many request error` to the callback\n\n## Retry policy\n\nIf API error is retryable, SDK will wait for delay and retry. Delay starts from 1 second. After each try, delay time is doubled. Maximum number of attempts is 5.\n\nYou can set the `retry` flag\n- in constructor as default `retry` flag\n- specify in `config` of `get()` or `create()` method\n\n\n## Examples\n\n#### Full list\nAll examples avalible listed in the table below.\n\n| File                                                                                                             | Description                        |\n|------------------------------------------------------------------------------------------------------------------|------------------------------------|\n| [rates\\_create.js](https://github.com/postmen/postmen-sdk-js/blob/master/examples/rates_create.js)                    | `rates` object creation            |\n| [rates\\_retrieve.js](https://github.com/postmen/postmen-sdk-js/blob/master/examples/rates_retrieve.js)                | `rates` object(s) retrieve         |\n| [labels_create.js](https://github.com/postmen/postmen-sdk-js/blob/master/examples/labels_create.js)                   | `labels` object creation           |\n| [labels_retrieve.js](https://github.com/postmen/postmen-sdk-js/blob/master/examples/labels_retrieve.js)               | `labels` object(s) retrieve        |\n| [manifests_create.js](https://github.com/postmen/postmen-sdk-js/blob/master/examples/manifests_create.js)             | `manifests` object creation        |\n| [manifests_retrieve.js](https://github.com/postmen/postmen-sdk-js/blob/master/examples/manifests_retrieve.js)         | `manifests` object(s) retrieve     |\n| [cancel_labels_create.js](https://github.com/postmen/postmen-sdk-js/blob/master/examples/cancel_labels_create.js)     | `cancel-labels` object creation    |\n| [cancel_labels_retrieve.js](https://github.com/postmen/postmen-sdk-js/blob/master/examples/cancel_labels_retrieve.js) | `cancel-labels` object(s) retrieve |\n| [address_validation_create.js](https://github.com/postmen/postmen-sdk-js/blob/master/examples/address_validation_create.js) | `address_validation` object(s) creation |\n| [proxy.js](https://github.com/postmen/postmen-sdk-js/blob/master/examples/proxy.js)                                   | Proxy usage                        |\n| [error.js](https://github.com/postmen/postmen-sdk-js/blob/master/examples/error.js)                                   | Avalible ways to catch/get errors  |\n| [response.js](https://github.com/postmen/postmen-sdk-js/blob/master/examples/response.js)                             | Avalible output types              |\n\n#### How to run\n\nDownload the source code, go to `examples` directory.\n\nPut your API key and region to [credentials.js](https://github.com/postmen/postmen-sdk-js/blob/master/examples/credentials.js)\n\nCheck the file you want to run before run. Some require you to set additional variables.\n\n#### Navigation table\n\nFor each API method SDK provides Node.js wrapper. Use the table below to find SDK method and example that match your need.\n\n| Model \\ Action | create                                                                                                                                               | get all                                                                                                                                                | get by id                                                                                                                                                                     |\n|----------------|------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n| rates          | \u003csub\u003e[`.create('/rates', input, config, callback)`](https://github.com/postmen/postmen-sdk-js/blob/master/examples/rates_create.js#L78)\u003c/sub\u003e             | \u003csub\u003e[`.get('/rates', input, config, callback)`](https://github.com/postmen/postmen-sdk-js/blob/master/examples/rates_retrieve.js#L9)\u003c/sub\u003e                 | \u003csub\u003e[`.get('rates/rate-id-here', input, config, callback)`](https://github.com/postmen/postmen-sdk-js/blob/master/examples/rates_retrieve.js#L18)\u003c/sub\u003e                           |\n| labels         | \u003csub\u003e[`.create('/labels', input, config, callback)`](https://github.com/postmen/postmen-sdk-js/blob/master/examples/labels_create.js#L98)\u003c/sub\u003e           | \u003csub\u003e[`.get('/labels', input, config, callback))`](https://github.com/postmen/postmen-sdk-js/blob/master/examples/labels_retrieve.js#L9)\u003c/sub\u003e              | \u003csub\u003e[`.get('/labels/label-id-here', input, config, callback))`](https://github.com/postmen/postmen-sdk-js/blob/master/examples/labels_retrieve.js#L18)\u003c/sub\u003e                      |\n| manifest       | \u003csub\u003e[`.create('/manifest', input, config, callback)`](https://github.com/postmen/postmen-sdk-js/blob/master/examples/manifests_create.js)\u003c/sub\u003e          | \u003csub\u003e[`.get('/manifest', input, config, callback)`](https://github.com/postmen/postmen-sdk-js/blob/master/examples/manifests_retrieve.js#L9)\u003c/sub\u003e          | \u003csub\u003e[`.get('/manifest/manifest-id-here', input, config, callback)`](https://github.com/postmen/postmen-sdk-js/blob/master/examples/manifests_retrieve.js#L19)\u003c/sub\u003e               |\n| cancel-labels  | \u003csub\u003e[`.create('/cancel-labels', input, config, callback)`](https://github.com/postmen/postmen-sdk-js/blob/master/examples/cancel_labels_create.js)\u003c/sub\u003e | \u003csub\u003e[`.get('/cancel-labels', input, config, callback)`](https://github.com/postmen/postmen-sdk-js/blob/master/examples/cancel_labels_retrieve.js#L9)\u003c/sub\u003e | \u003csub\u003e[`.get('/cancel-labels/cancel-labels-id-here', input, config, callback)`](https://github.com/postmen/postmen-sdk-js/blob/master/examples/cancel_labels_retrieve.js#L18)\u003c/sub\u003e |\n| address-validations| \u003csub\u003e[`.create('/address-validations', input, config, callback)`](https://github.com/postmen/postmen-sdk-js/blob/master/examples/address-validations.js)\u003c/sub\u003e | |\n## Testing\n```\nmocha --recursive\n```\n## License\nReleased under the MIT license. See the LICENSE file for details.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpostmen%2Fpostmen-sdk-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpostmen%2Fpostmen-sdk-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpostmen%2Fpostmen-sdk-js/lists"}