@harveys-software/speedy-fulfil-client

TypeScript client for the Speedy-Fulfil shipping & fulfilment API. Supports OAuth2 authentication, order creation, consignment cancellation, postage label retrieval, and shipment tracking.

Installation

npm install @harveys-software/speedy-fulfil-client

Quick start

import SpeedyFulfilClient from "@harveys-software/speedy-fulfil-client";

const client = new SpeedyFulfilClient(
  "https://speedyfulfil-m2m-account-prod.auth.eu-west-2.amazoncognito.com", // auth URL
  "https://api.speedyfulfil.com",                                           // API URL
  "your-client-id",
  "your-client-secret",
);

// Token is automatically cached and refreshed before expiry.
const order = await client.createOrder(129, {
  clientIntegrationId: 114,
  orders: [
    {
      salesChannelId: 1,
      shippingPrice: 0,
      discount: 0,
      orderCurrency: "GBP",
      orderDate: new Date().toISOString(),
      salesChannelOrderRef: "order-ref-001",
      salesChannelShippingOption: "Economy",
      billingFirstname: "Jane",
      billingLastname: "Doe",
      billingAddress1: "Flat 3, Piccadilly Point, 23 Berry Street",
      billingAddress2: "Manchester",
      billingCity: "Manchester",
      billingCountryCode: "GB",
      billingPostcode: "M1 2AD",
      deliveryFirstname: "Jane",
      deliveryLastname: "Doe",
      deliveryAddress1: "Flat 3, Piccadilly Point, 23 Berry Street",
      deliveryAddress2: "Manchester",
      deliveryCity: "Manchester",
      deliveryCountryCode: "GB",
      deliveryPostcode: "M1 2AD",
      orderRef: "order-ref-001",
      emailAddress: "[email protected]",
      orderLines: [
        {
          qty: 1,
          speedyFreightReference: "SF00001",
          dimensions: {
            weight: "0.25",
            length: "15",
            height: "5",
            width: "10",
          },
        },
      ],
    },
  ],
});

console.log(order.orderId);

API

new SpeedyFulfilClient(authUrl, apiUrl, clientId, clientSecret, options?)

Creates a client that handles OAuth2 token management automatically. The token is cached and refreshed 60 seconds before expiry.

By default, tokens are stored in-memory (one per client instance). For serverless or multi-process environments, provide a custom TokenStore implementation backed by Redis, a database, or the filesystem.

// Default — in-memory token caching (existing behaviour)
const client = new SpeedyFulfilClient(authUrl, apiUrl, clientId, clientSecret);

Custom token store

Implement the TokenStore interface to persist tokens across cold starts or processes:

import { type TokenStore } from "@harveys-software/speedy-fulfil-client";

// Example: Redis-backed token store
class RedisTokenStore implements TokenStore {
  constructor(private redis: Redis) {}

  async get(): Promise<string | null> {
    return this.redis.get("speedy-fulfil:token");
  }

  async set(token: string, expiresIn: number): Promise<void> {
    // Set with a TTL slightly shorter than the token's actual expiry
    await this.redis.set("speedy-fulfil:token", token, "EX", expiresIn - 60);
  }
}

const client = new SpeedyFulfilClient(
  authUrl, apiUrl, clientId, clientSecret,
  new RedisTokenStore(redis),
);

The built-in MemoryTokenStore is also exported if you want to extend it:

import { MemoryTokenStore } from "@harveys-software/speedy-fulfil-client";

client.createOrder(clientId, body, international?)

Creates one or more orders for a client. Set international to true for non-UK shipments.

const order = await client.createOrder(129, {
  clientIntegrationId: 114,
  orders: [/* ... */],
});
// => { orderId: "12345" }

client.cancelCourier(clientId, consignmentId, body)

Cancels a consignment.

const result = await client.cancelCourier(32, 101, { reasonCodeId: 1 });
// => { consignmentRef: "31231231" }

client.getPostageLabels(clientId, warehouseId, consignmentId)

Fetches postage labels (PDF, PNG, or ZPL) for a consignment.

const labels = await client.getPostageLabels(32, 1, 12345);
// => { postageBookingMethod: "ship_theory", postageLabels: ["base64pdf..."] }

client.getTracking(clientId, body)

Fetches tracking information for one or more barcodes.

const tracking = await client.getTracking(32, {
  trackingBarCodes: ["9001817919022"],
});
// => { response: { message: "OK", statusCode: 201, data: { ... } } }

client.getToken()

Returns the raw OAuth2 token response. Normally handled automatically — use this only if you need the token for custom integrations.

const token = await client.getToken();
// => { access_token: "...", expires_in: 3600, token_type: "Bearer" }

Error handling

All API errors are thrown as typed error classes (AuthError, OrderError, ConsignmentError, LabelsError, TrackingError). Each carries the HTTP status code and error string:

import { OrderError } from "@harveys-software/speedy-fulfil-client";

try {
  await client.createOrder(129, { clientIntegrationId: 114, orders: [] });
} catch (err) {
  if (err instanceof OrderError) {
    console.log(err.code);   // 400
    console.log(err.error);  // "Invalid request"
  }
}

Environment URLs

| Environment | Auth URL | API URL | |---|---|---| | Dev | https://speedyfulfil-m2m-account-np.auth.eu-west-2.amazoncognito.com | https://api.dev.speedyfulfil.com | | UAT | https://speedyfulfil-m2m-account-np.auth.eu-west-2.amazoncognito.com | https://api.uat.speedyfulfil.com | | Prod | https://speedyfulfil-m2m-harveys-prod.auth.eu-west-2.amazoncognito.com | https://api.speedyfulfil.com |

License

ISC