ShipFlow

Unified Shipping SDK for MENA region carriers. A single API to create shipments, track packages, manage labels, handle webhooks, and more — across Aymakan, SMSA Express, Aramex, and future carriers.

Think EasyPost / Shippo, but purpose-built for Saudi Arabia and the GCC.

Features

• Unified types — one CreateShipmentInput, one TrackingResult, one WebhookEvent, regardless of carrier
• Tree-shakeable — only the carriers you import are bundled
• Auto-validation — Valibot schemas validate every createShipment() call before it hits the network
• Webhook parsing — normalize incoming carrier webhooks into a single event format
• Smart retries — dependency-free retry with jittered backoff that honors carrier Retry-After on 429/503, surfacing a RateLimitError when the wait is too long to absorb inline
• Minimal dependencies — only Valibot for validation; uses the runtime's global fetch (Node 20+, Deno, Bun, edge/workers), no axios/node-fetch
• TypeScript-first — strict types, no any

Installation

bun add shipflow

Quick Start

import { ShipFlow } from "shipflow";
import { AymakanAdapter, AymakanService } from "shipflow/carriers/aymakan";
import { SMSAExpressAdapter, SMSAService } from "shipflow/carriers/smsaexpress";
import { AramexAdapter } from "shipflow/carriers/aramex";

const client = new ShipFlow({
  adapters: [
    new AymakanAdapter({
      mode: "sandbox",
      credentials: { apiKey: process.env.AYMAKAN_API_KEY! },
    }),
    new SMSAExpressAdapter({
      mode: "sandbox",
      credentials: { apiKey: process.env.SMSA_API_KEY! },
    }),
    // Aramex auth is a ClientInfo object sent in every request body (no API key)
    new AramexAdapter({
      mode: "sandbox",
      credentials: {
        userName: process.env.ARAMEX_USERNAME!,
        password: process.env.ARAMEX_PASSWORD!,
        accountNumber: process.env.ARAMEX_ACCOUNT_NUMBER!,
        accountPin: process.env.ARAMEX_ACCOUNT_PIN!,
        accountEntity: process.env.ARAMEX_ACCOUNT_ENTITY!, // e.g. "RUH"
        accountCountryCode: process.env.ARAMEX_ACCOUNT_COUNTRY_CODE!, // e.g. "SA"
      },
    }),
  ],
});

// Create a shipment (auto-validated)
const shipment = await client.carrier("aymakan").createShipment({
  shipper: {
    name: "My Store",
    phone: "966500000000",
    line1: "123 Main St",
    city: "Riyadh",
    countryCode: "SA",
  },
  consignee: {
    name: "Customer",
    phone: "966500000001",
    line1: "456 Side St",
    city: "Jeddah",
    countryCode: "SA",
  },
  parcels: [{ weight: { value: 2, unit: "kg" }, pieces: 1 }],
  serviceType: AymakanService.ECOMMERCE,
  cod: { enabled: true, amount: 150, currency: "SAR" },
});

console.log(shipment.trackingNumber); // "AY..."

API Reference

ShipFlow Client

const client = new ShipFlow({ adapters: [...] });

client.carrier('aymakan')           // Get a specific carrier adapter
client.carriers                      // List configured carrier names
client.hasCarrier('smsaexpress')     // Check if a carrier is configured
await client.getRatesFromAll(input)  // Fetch rates from all carriers in parallel
await client.trackAcrossCarriers(tn) // Try all carriers to find tracking info

Carrier Operations

Every carrier adapter implements these required methods:

Method	Description
createShipment(input)	Create a single shipment (auto-validated)
cancelShipment(trackingNumber)	Cancel a shipment
track(trackingNumber)	Track a single shipment
trackMultiple(trackingNumbers)	Track multiple shipments
getLabel(trackingNumber, format?)	Get label URL or data URI

Plus these optional methods (availability varies by carrier):

Method	Aymakan	SMSA	Aramex
createBulkShipments(inputs)	✅	—	✅
cancelByReference(ref)	✅	—	—
updateDeliveryAddress(tn, address)	✅	—	—
trackByReference(ref)	✅	✅	✅
getBulkLabels(trackingNumbers)	✅	—	—
getPickupCities()	✅	—	—
getTimeSlots(city, date)	✅	—	—
createPickup(input)	✅	—	✅
cancelPickup(id)	✅	—	✅
getPickupRequests()	✅	—	—
getCities()	✅	✅	✅
getDropoffLocations()	✅	✅	✅
createCustomerAddress(addr)	✅	—	—
getCustomerAddresses()	✅	—	—
updateCustomerAddress(id, addr)	✅	—	—
deleteCustomerAddress(id)	✅	—	—
getRates(input)	—	—	✅
parseWebhook(payload, options)	✅	✅	—

SMSA-specific methods:

Method	Description
create2WayShipment(input)	Create forward + return shipment
sendInvoice(request)	Submit invoice for a shipment
validateShortAddress(shortCode)	Resolve Saudi national address
pushIdDetails(request)	Submit identity documents for KYC
parseWebhookBatch(payload, options)	Parse batch webhook (array of shipments)

Carrier Support

Feature	Aymakan	SMSA Express	Aramex
Countries	SA, AE, BH, KW, OM, QA	SA, AE, BH, EG, KW, OM, QA, JO	SA, AE, BH, KW, OM, QA, JO, EG, LB, IQ
Service types	10 (ONP, SDD, RVP, EXH, ...)	3 (EDDL, EDEL, EDCR)	10 product types (OND, PPX, EPX, ...)
Shipment creation	Single + Bulk	B2C + C2B + 2-Way	Single + Bulk (native batch)
COD	✅	✅ (B2C only)	✅
Cancellation	By tracking # or reference	C2B only	Pickups only (no shipment cancel API)
Tracking	Single, bulk, by reference	Single, bulk, by reference	Single, bulk, by reference
Labels	PDF/PNG, single + bulk	PDF/ZPL	URL (HTML/PDF)
Pickups	Full lifecycle	—	Create + cancel
Webhooks	✅ (with auth verification)	✅ (batch, with auth verification)	— (poll via tracking)
City resolution	Arabic ↔ English smart matching	Code-based lookup	Name list (FetchCities / FetchOffices)
Rates	❌	❌	✅ (CalculateRate)

Aramex

Aramex is integrated via the JSON flavor of the classic ShippingAPI.V2 services. A few things make it different from the other carriers:

• Auth is a ClientInfo object in every request body (no API key / header, no token exchange). Pass userName, password, accountNumber, accountPin, accountEntity (the 3-letter origin office, e.g. RUH/DXB/AMM) and accountCountryCode.
• Four independent services on separate hosts — Shipping, Tracking, RateCalculator, and Location. The adapter holds one HTTP client per service and routes automatically. If your account provisions the Location service on a different host (some WSDLs use anfe02.aramex.com), set locationBaseUrl on the config.
• "Fake 200 OK" errors — Aramex returns HTTP 200 even on logical failures, with HasErrors: true + Notifications[]. ShipFlow surfaces these as APIError, including per-shipment errors inside an otherwise-clean CreateShipments batch. Throttling notifications in that envelope are surfaced as RateLimitError so retries back off.
• Rates are supported (getRates → CalculateRate), unlike Aymakan/SMSA.
• cancelShipment is unsupported (the classic API has no shipment-cancel operation) and throws UnsupportedOperationError. Pickups can be cancelled via cancelPickup.
• Labels resolve to a URL — the format argument of getLabel can't be honored.

import { AramexAdapter, AramexProductType } from "shipflow/carriers/aramex";

const aramex = client.carrier("aramex");

// Create a domestic COD shipment (freight prepaid, cash collected on delivery)
const shipment = await aramex.createShipment({
  shipper: {
    name: "My Store",
    company: "ShipFlow",
    phone: "966500000000",
    line1: "King Fahd Road",
    city: "Riyadh",
    countryCode: "SA",
  },
  consignee: {
    name: "Customer",
    phone: "966500000001",
    line1: "Prince Sultan Road",
    city: "Jeddah",
    countryCode: "SA",
  },
  parcels: [{ weight: { value: 1, unit: "kg" }, pieces: 1 }],
  cod: { enabled: true, amount: 150, currency: "SAR" },
});

// Quote a rate, then track
const rates = await aramex.getRates!(input);
const result = await aramex.track(shipment.trackingNumber);

Product group / type & payment — ShipFlow infers DOM (domestic) when shipper and consignee share a country, else EXP, and picks a sensible default product type (OND for domestic, EPX for express). Override with serviceType (a valid Aramex code) or options.metadata.productGroup / productType.

The freight PaymentType — who pays the shipping cost — defaults to P and is independent of COD: enabling COD adds the CODS service and the cash amount to collect from the consignee, but does not charge them freight. Override the freight payer with options.metadata.paymentType:

Value	Freight billed to	When to use
"P" (default)	Shipper's Aramex account (prepaid)	Standard KSA/GCC e-commerce — merchant pays shipping, even with COD
"C"	Consignee, collected at delivery	Customer pays shipping on top of any COD
"3"	A third-party account	Freight billed to someone other than shipper/consignee

// Default: COD shipment with prepaid freight (PaymentType "P")
await aramex.createShipment({
  ...input,
  cod: { enabled: true, amount: 150, currency: "SAR" }, // freight stays "P"
});

// Override: charge the customer freight at the door (PaymentType "C")
await aramex.createShipment({
  ...input,
  cod: { enabled: true, amount: 150, currency: "SAR" },
  options: { metadata: { paymentType: "C" } },
});

// Override: bill freight to a third party (PaymentType "3")
await aramex.createShipment({
  ...input,
  options: { metadata: { paymentType: "3" } },
});

Aramex does not push webhooks — poll track() / trackMultiple() for status updates. Tracking UpdateCodes vary by region and aren't fully published, so ShipFlow maps known codes and falls back to a description-keyword heuristic (then "unknown") — an unmapped code never breaks tracking.

Webhook Handling

Aymakan

Aymakan sends a single shipment status update per webhook call:

const event = client.carrier("aymakan").parseWebhook!(requestBody, {
  headers: req.headers,
  config: {
    authHeader: "X-Aymakan-Auth",
    authValue: process.env.AYMAKAN_WEBHOOK_SECRET!,
  },
});

console.log(event.trackingNumber); // "AY..."
console.log(event.status); // "delivered"
console.log(event.statusCode); // "AY-0005"

SMSA Express

SMSA sends an array of shipment updates per webhook call:

const adapter = client.carrier("smsaexpress") as SMSAExpressAdapter;

// Parse all shipments in the batch
const events = adapter.parseWebhookBatch(requestBody, {
  queryParams: { key: req.query.key },
  config: {
    authQueryParam: "key",
    authQueryValue: process.env.SMSA_WEBHOOK_KEY!,
  },
});

for (const event of events) {
  console.log(event.trackingNumber); // "231200021000"
  console.log(event.status); // "delivered" | "out_for_delivery" | ...
}

// Or parse only the first item (CarrierAdapter interface compatible)
const single = adapter.parseWebhook(requestBody);

WebhookEvent Shape

interface WebhookEvent {
  carrier: string;
  eventType: "status_update" | "weight_update";
  trackingNumber: string;
  reference?: string;
  status: ShipmentStatus;
  statusCode: string;
  statusLabel: string;
  reasonCode?: string; // Aymakan: reason for failed delivery
  reasonLabel?: string;
  timestamp: Date;
  raw: unknown; // Original carrier payload
}

Input Validation

All createShipment() calls are automatically validated using Valibot schemas before hitting the carrier API. Invalid input throws a ValidationError with field-level details:

try {
  await client.carrier("aymakan").createShipment({
    shipper: { name: "", phone: "", line1: "", city: "", countryCode: "X" },
    consignee: { name: "", phone: "", line1: "", city: "", countryCode: "" },
    parcels: [],
    serviceType: "",
  });
} catch (error) {
  if (error instanceof ValidationError) {
    console.log(error.issues);
    // [
    //   { path: "shipper.name", message: "Name is required" },
    //   { path: "shipper.countryCode", message: "Country code must be ISO 3166-1 alpha-2 (2 characters)" },
    //   { path: "parcels", message: "At least one parcel is required" },
    //   ...
    // ]
  }
}

You can also validate manually before calling the API:

import { validateCreateShipmentInput, validatePickupRequest } from "shipflow";

validateCreateShipmentInput(input); // throws ValidationError or returns validated input
validatePickupRequest(pickupInput); // same pattern

Exported Valibot schemas for advanced use (custom refinements, partial validation, etc.):

import {
  AddressSchema,
  ParcelSchema,
  CreateShipmentInputSchema,
  PickupRequestSchema,
} from "shipflow";

Error Handling

All errors extend ShipFlowError for easy catch-all handling:

import {
  ShipFlowError,
  NetworkError,
  RateLimitError,
  APIError,
  ValidationError,
  AuthenticationError,
  WebhookVerificationError,
  UnsupportedOperationError,
} from "shipflow";

try {
  await client.carrier("aymakan").createShipment(input);
} catch (error) {
  if (error instanceof ValidationError) {
    // Bad input — check error.issues
  } else if (error instanceof AuthenticationError) {
    // Invalid API key
  } else if (error instanceof RateLimitError) {
    // Rate limited — check error.retryAfterMs (ms to wait), reschedule if set
  } else if (error instanceof APIError) {
    // Carrier returned an error — check error.statusCode, error.errors
  } else if (error instanceof NetworkError) {
    // Timeout, DNS, connection refused
  }
}

RateLimitError extends APIError, so check it before APIError in your if/else chain (a plain catch (e) { if (e instanceof APIError) } still catches it).

Retries & rate limiting

Safe, idempotent requests (GETs, plus tracking endpoints opted in by the adapters) are retried automatically with jittered exponential backoff. Mutating requests (create/cancel) are not retried by default, so a timed-out createShipment never risks a duplicate on the carrier.

When a carrier replies 429/503 with a Retry-After header, ShipFlow:

• honors it inline if the wait is within the inline cap (15s by default), sleeping out the window (plus a little jitter) before retrying; otherwise
• stops and throws RateLimitError carrying retryAfterMs, so a durable queue/worker can reschedule instead of blocking the request for minutes.

try {
  await client.carrier("aymakan").track(trackingNumber);
} catch (error) {
  if (error instanceof RateLimitError && error.retryAfterMs != null) {
    await scheduleRetryIn(error.retryAfterMs); // your queue/worker
  }
}

Aramex reports throttling inside its "fake 200" envelope rather than via HTTP 429; ShipFlow detects that and raises the same RateLimitError.

Custom Adapters

Implement the CarrierAdapter interface or extend BaseCarrierAdapter:

import { BaseCarrierAdapter } from "shipflow";
import type { CreateShipmentInput, Shipment, TrackingResult } from "shipflow";

class MyCarrierAdapter extends BaseCarrierAdapter {
  readonly name = "mycarrier";
  readonly supportedCountries = ["SA"];

  protected getBaseUrl() {
    return this.config.mode === "production"
      ? "https://api.mycarrier.com"
      : "https://sandbox.mycarrier.com";
  }

  protected async executeCreateShipment(
    input: CreateShipmentInput,
  ): Promise<Shipment> {
    // Your implementation — input is already validated by BaseCarrierAdapter
  }

  async cancelShipment(trackingNumber: string): Promise<boolean> {
    /* ... */
  }
  async track(trackingNumber: string): Promise<TrackingResult> {
    /* ... */
  }
  async trackMultiple(trackingNumbers: string[]): Promise<TrackingResult[]> {
    /* ... */
  }
  async getLabel(trackingNumber: string): Promise<string> {
    /* ... */
  }
}

Development

bun install
bun test           # Run all tests
bun test --watch   # Watch mode
bun run typecheck  # TypeScript check

License

MIT