shipengine
v1.0.7
Published
The official ShipEngine JavaScript SDK for Node.js
Downloads
11,821
Readme
ShipEngine JavaScript SDK
The official ShipEngine JavaScript SDK for Node.js
Quick Start
Install ShipEngine JavaScript SDK via npm.
npm install shipengine
The only configuration requirement is an API key.
const ShipEngine = require("shipengine");
const shipengine = new ShipEngine("___YOUR_API_KEY_HERE__");
Configuring the ShipEngine SDK
- Be sure to configure the SDK if you would like to update things like
retries
,timeouts
, andpage sizes
using theShipEngine Config
interface. Alternatively, you can simply pass in your ShipEngine API Key and use the default configuration.
export interface ShipEngineConfig {
/**
* Your ShipEngine API key.
*
* This can be a production or sandbox key. Sandbox keys start with "TEST_".
*/
apiKey: string;
/**
* ShipEngine child account API key (partner API)
*
* This can be a production or sandbox key. Sandbox keys start with "TEST_".
*/
onBehalfOf?: string;
/**
* The URL of the ShipEngine API. You can usually leave this unset and it will
* default to our public API.
*/
baseURL?: string | URL;
/**
* Some ShipEngine API endpoints return paged data. This lets you control the
* number of items returned per request. Larger numbers will use more memory
* but will require fewer HTTP requests.
*
* Defaults to 50.
*/
pageSize?: number;
/**
* If the ShipEngine client receives a rate limit error it can automatically
* retry the request after a few seconds. This setting lets you control how
* many times it will retry before giving up.
*
* Defaults to 1, which means up to 2 attempts will be made (the original
* attempt, plus one retry).
*/
retries?: number;
/**
* The maximum amount of time (in milliseconds) to wait for a response from
* the ShipEngine server.
*
* Defaults to 60000 (60 seconds).
*/
timeout?: number;
}
Methods
createLabelFromRate
- When retrieving rates for shipments using thegetRatesWithShipmentDetails
method, the returned information contains arateId
property that can be used to purchase a label without having to refill in the shipment information repeatedly.createLabelFromShipmentDetails
- Purchase and print a label for shipment.getRatesWithShipmentDetails
- Given some shipment details and rate options, this method returns a list of rate quotes.listCarriers
- Returns a list of carrier accounts that have been connected through the ShipEngine dashboard.trackUsingLabelId
- Track a package by its associated label ID.trackUsingCarrierCodeAndTrackingNumber
- Track a package for a given carrier and tracking number.validateAddresses
- Indicates whether the provided addresses are valid. If the addresses are valid, the method returns a normalized version based on the standards of the country in which the address resides. If an address cannot be normalized, an error is returned.voidLabelWithLabelId
- Void a label with its Label ID.
Contributing
Contributions, enhancements, and bug-fixes are welcome! Open an issue on GitHub and submit a pull request.
Building
To build the project locally on your computer:
Clone this repo
git clone https://github.com/ShipEngine/shipengine-js.git
Install dependencies
npm install
Build the code
npm run build
Or you can usenpm run watch
to automatically re-build whenever source files change.Lint the code
npm run lint
Or you can usenpm run lint:fix
to automatically fix most linting errors.Run the tests
npm test
This runs tests in both Node.js and web browsers. Usenpm run test:node
to only run Node.js tests, ornpm run test:browser
to only run browser tests.
Committing
This project adheres to the Conventional Commits specification.
Publishing
Publishing new versions of the SDK to NPM is handled on GitHub via the Release Please GitHub Actions workflow. Learn more about about Release PRs, updating the changelog, and commit messages here.