JavaScript SDK

Official JavaScript SDK to connect to the MyParcel API via Node.js or browser.

# Installation

Install @myparcel/sdk with your package manager:

npm install @myparcel/sdk

# Usage examples

# Basic usage

The client is Promise-based, so you can use async/await, or Promise.then.

First, instantiate an SDK and pass the endpoints you want to use.

import {createPrivateSdk, FetchClient, PostShipments} from '@myparcel/sdk';

const clientConfig = {
  headers: {
    Authorization: 'bearer ' + MY_BASE_64_ENCODED_API_KEY,
  },
};

const sdk = createPrivateSdk(new FetchClient(clientConfig), [
  new PostShipments(),
]);

Then call the endpoint. There are constants available in our SDK for data like carriers, package types, delivery types and more. See constants.

const result = await sdk.postShipments({
  body: [
    {
      carrier: 1,
      options: {
        package_type: 1,
      },
      recipient: {
        cc: 'NL',
        city: 'Hoofddorp',
        person: 'Ms. Parcel',
        street: 'Antareslaan 31',
      },
    },
  ],
});

console.log(result); // [ 123456 ] (The ID of the shipment that was just created)

# Creating a new endpoint

To create a new endpoint, you can extend either AbstractPrivateEndpoint or AbstractPublicEndpoint and fill in the derived class as needed.

Feel free to add open a pull request to add it to our repository! See contributing.

# Creating a new client

In this example we're creating an Axios client.

class AxiosClient extends AbstractClient {
  async request(endpoint, options) {
    try {
      const response = await axios.request({
        method: endpoint.method,
        url: this.createUrl(endpoint, options),
        headers: {
          ...this.getHeaders(),
          ...endpoint.getHeaders(),
        },
      });

      return response.data;
    } catch (e) {
      return e.response.data;
    }
  }
}

Now use the new client with an SDK instance:

const sdk = createPublicSdk(new AxiosClient(), [new GetCarriers()]);

const carriers = await sdk.getCarriers();

console.log(carriers); // [ { "id": 1, "name": "postnl", (etc...)

# Using constants

Install @myparcel/constants to be able to use lots of pre-defined constants needed throughout our entire ecosystem, like carrier and package type IDs, country codes and names of delivery options.

npm install @myparcel/constants

# Carriers

import {CarrierId, CarrierName} from '@myparcel/constants';

CarrierName.PostNL; // "postnl"
CarrierId.Dhl; // 6

# Package types

import {PackageTypeId, PackageTypeName} from '@myparcel/constants';

PackageTypeName.DigitalStamp; // "digital_stamp"
PackageTypeId.Package; // 1
// etc

# Delivery types

import {DeliveryTypeId, DeliveryTypeName} from '@myparcel/constants';

DeliveryTypeName.Standard; // "standard"
DeliveryTypeId.Pickup; // 4
// etc

# Countries

Contains constants for all countries, by name

import {
  NETHERLANDS,
  GERMANY,
  EU_COUNTRIES,
} from '@myparcel/constants/countries';

NETHERLANDS; // "NL"
GERMANY; // "DE"
EU_COUNTRIES; // ["AT", "BE", ...]

# States

import {GEORGIA, STATES_US, STATES_CANADA} from '@myparcelnl/constants/states';

GEORGIA; // "GA"
STATES_US; // ["AL", "AK", ...]
STATES_CANADA; // ["AB", "BC", ...]

# Endpoints

# Public

Public endpoints do not require authorization and are safe to use in a browser.

• Delivery options
  • GetDeliveryOptions
• Pickup locations
  • GetPickupLocations
• Carriers
  • GetCarriers
  • GetCarrier

# Private

Private endpoints require an Authorization header. This should be a base64 encoded MyParcel API key. You can create one in the shop settings in our [backoffice]. See [Authorization] in the API documentation for more information.

• Shipments
  • GetShipment
  • GetShipments
  • PostShipments

# Contributing

# Requirements

• Node 16
• Yarn

# Basics

• Fork this repository and clone it to your machine
• Install dependencies using Yarn:

  yarn
  

# Make your changes

• Try to conform to our code style. Make sure to enable ESLint in your editor.
• You should make only one change in each branch.

# Add or update tests

Run tests with the following command:

yarn run test:coverage

• Coverage % needs to be equal to or greater than that of the previous commit.
• If you added a new file, the corresponding test(s) should go inside <filename>.spec.ts in the same directory.

# Commit

Make as many commits as you'd like. We use Conventional Commits and semantic-release to simplify the process of releasing updates by automating release notes and changelogs based on the rules of @commitlint/config-conventional.

Your branch will be squashed into one single valid commit before merging.

# Create a pull request

• Keep your pull requests focused on single subjects
• Please explain what you changed and why
• We will review your code and thoroughly test it before squashing and merging your pull request