@serianshipkit/sdk

Official Node.js SDK for the Serian ShipKit shipping API.
Minimal, dependency-free, written in TypeScript.

Install

npm install @serianshipkit/sdk

Requires Node.js 18+ (uses native fetch).

Quick Start

import SerianLogistics from "@serianshipkit/sdk";

const sl = new SerianLogistics({
  apiKey: process.env.SERIAN_API_KEY!,
  // baseUrl: "http://localhost:3000",  // for local dev
});

// 1. Get rates
const { rates } = await sl.rates.list({
  shipper:   { name: "Acme", street1: "1 Main", city: "Accra", state: "GA", zip: "00233", country: "GH" },
  recipient: { name: "Jane", street1: "1 Oak",  city: "Lagos", state: "LA", zip: "100001", country: "NG" },
  parcels:   [{ length: 20, width: 15, height: 10, weight: 1, dimension_unit: "CM", weight_unit: "KG" }],
});

// 2. Create a shipment
const shipment = await sl.shipments.create(
  { rate_id: rates[0].rate_id, reference: "order-123" },
  /* idempotencyKey */ "order-123"
);

console.log(shipment.tracking_number, shipment.label_url);

Configuration

| Option | Type | Default | Description | | --------- | -------- | ------------------------------------- | ---------------------------------- | | apiKey | string | — | Your Serian API key (required) | | baseUrl | string | https://api.serianshipkit.com | API base URL | | retries | number | 3 | Auto-retry on 429/5xx with backoff |

Error Handling

import { SerianLogisticsError } from "@serianshipkit/sdk";

try {
  await sl.shipments.create(payload);
} catch (err) {
  if (err instanceof SerianLogisticsError) {
    console.error(err.status, err.code, err.requestId);
  }
}

License

MIT — Full API reference at https://serianshipkit.com/docs