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, 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 — Zod schemas validate every createShipment() call before it hits the network
• Webhook parsing — normalize incoming carrier webhooks into a single event format
• Zero runtime dependencies — Bun-native fetch, 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";

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! },
    }),
  ],
});

// 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 | | ------------------------------------ | ------- | ---- | | 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) | ✅ | — | | 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 | | ----------------- | ------------------------------- | ---------------------------------- | | Countries | SA, AE, BH, KW, OM, QA | SA, AE, BH, EG, KW, OM, QA, JO | | Service types | 10 (ONP, SDD, RVP, EXH, ...) | 3 (EDDL, EDEL, EDCR) | | Shipment creation | Single + Bulk | B2C + C2B + 2-Way | | COD | ✅ | ✅ (B2C only) | | Cancellation | By tracking # or reference | C2B only | | Tracking | Single, bulk, by reference | Single, bulk, by reference | | Labels | PDF/PNG, single + bulk | PDF/ZPL | | Pickups | Full lifecycle | — | | Webhooks | ✅ (with auth verification) | ✅ (batch, with auth verification) | | City resolution | Arabic ↔ English smart matching | Code-based lookup | | Rates | ❌ | ❌ |

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 Zod 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 Zod 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,
  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 APIError) {
    // Carrier returned an error — check error.statusCode, error.errors
  } else if (error instanceof NetworkError) {
    // Timeout, DNS, connection refused
  }
}

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