shipflow 0.1.0

package/README.md

@@ -0,0 +1,328 @@
+# 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
+
+```bash
+bun add shipflow
+```
+
+## Quick Start
+
+```typescript
+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
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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
+
+```typescript
+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:
+
+```typescript
+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:
+
+```typescript
+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.):
+
+```typescript
+import {
+  AddressSchema,
+  ParcelSchema,
+  CreateShipmentInputSchema,
+  PickupRequestSchema,
+} from "shipflow";
+```
+
+## Error Handling
+
+All errors extend `ShipFlowError` for easy catch-all handling:
+
+```typescript
+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`:
+
+```typescript
+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
+
+```bash
+bun install
+bun test           # Run all tests
+bun test --watch   # Watch mode
+bun run typecheck  # TypeScript check
+```
+
+## License
+
+MIT

package/dist/carriers/aymakan/adapter.d.ts

@@ -0,0 +1,87 @@
+/**
+ * Aymakan Carrier Adapter
+ * Full implementation of the CarrierAdapter interface for Aymakan API.
+ */
+import type { Address, CarrierConfig, City, CreateShipmentInput, CustomerAddress, Pickup, PickupRequest, Shipment, TimeSlot, TrackingResult, WebhookConfig, WebhookEvent } from "../../core/types.js";
+import { BaseCarrierAdapter } from "../base.js";
+export interface AymakanConfig extends CarrierConfig {
+    credentials: {
+        apiKey: string;
+    };
+}
+export declare class AymakanAdapter extends BaseCarrierAdapter {
+    readonly name = "aymakan";
+    readonly supportedCountries: string[];
+    private http;
+    /** Cached Aymakan cities list for city name resolution */
+    private citiesCache;
+    private citiesCacheTime;
+    /** Cache TTL: 1 hour */
+    private static readonly CITIES_CACHE_TTL;
+    constructor(config: AymakanConfig);
+    protected getBaseUrl(): string;
+    /**
+     * Load cities list from Aymakan API and cache it.
+     * Silently falls back to empty list on failure so shipments can still be attempted.
+     */
+    private ensureCitiesLoaded;
+    /**
+     * Normalize Arabic text for comparison:
+     * - Strip diacritics (tashkeel)
+     * - Normalize alef variants (أ إ آ → ا)
+     * - Normalize taa marbuta (ة → ه)
+     * - Trim whitespace
+     */
+    private static normalizeArabic;
+    /**
+     * Resolve a user-input city name to the valid Aymakan English city name.
+     *
+     * Matching strategy (first match wins):
+     * 1. Exact match on English name (case-insensitive)
+     * 2. Exact match on Arabic name
+     * 3. Normalized Arabic match (handles tashkeel, alef variants, taa marbuta)
+     * 4. Match after stripping "ال" prefix from Arabic input
+     * 5. Substring/contains match on English name (case-insensitive)
+     *
+     * Falls back to the original input if no match is found.
+     */
+    private resolveCity;
+    /**
+     * Resolve city names in a CreateShipmentInput to valid Aymakan city names.
+     */
+    private resolveCitiesInInput;
+    protected executeCreateShipment(input: CreateShipmentInput): Promise<Shipment>;
+    createBulkShipments(inputs: CreateShipmentInput[]): Promise<Shipment[]>;
+    cancelShipment(trackingNumber: string): Promise<boolean>;
+    cancelByReference(reference: string): Promise<boolean>;
+    updateDeliveryAddress(trackingNumber: string, address: Address): Promise<boolean>;
+    track(trackingNumber: string): Promise<TrackingResult>;
+    trackMultiple(trackingNumbers: string[]): Promise<TrackingResult[]>;
+    trackByReference(reference: string): Promise<TrackingResult>;
+    getLabel(trackingNumber: string, format?: "PDF" | "PNG"): Promise<string>;
+    getBulkLabels(trackingNumbers: string[]): Promise<string>;
+    getPickupCities(): Promise<City[]>;
+    getTimeSlots(_city: string, date: string): Promise<TimeSlot[]>;
+    createPickup(input: PickupRequest): Promise<Pickup>;
+    cancelPickup(pickupId: string | number): Promise<boolean>;
+    getPickupRequests(): Promise<Pickup[]>;
+    getCities(): Promise<City[]>;
+    getDropoffLocations(): Promise<{
+        id: string;
+        name: string;
+        nameAr?: string;
+        address?: string;
+        city?: string;
+    }[]>;
+    createCustomerAddress(address: CustomerAddress): Promise<CustomerAddress>;
+    getCustomerAddresses(): Promise<CustomerAddress[]>;
+    updateCustomerAddress(id: number, address: Partial<CustomerAddress>): Promise<CustomerAddress>;
+    deleteCustomerAddress(id: number): Promise<boolean>;
+    parseWebhook(payload: unknown, options?: {
+        headers?: Record<string, string>;
+        queryParams?: Record<string, string>;
+        config?: WebhookConfig;
+    }): WebhookEvent;
+    getRates(): Promise<never>;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/carriers/aymakan/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/carriers/aymakan/adapter.ts"],"names":[],"mappings":"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"}

package/dist/carriers/aymakan/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Aymakan Carrier Exports
+ * Import from 'shipflow/carriers/aymakan' for tree-shaking.
+ */
+export { AymakanAdapter, type AymakanConfig } from './adapter.js';
+export { AymakanService, AymakanStatusCodes, type AymakanServiceType } from './services.js';
+export { parseAymakanWebhook, mapAymakanStatus } from './mappers.js';
+export type { AymakanCreateShipmentRequest, AymakanShipmentResponse, AymakanTrackingEvent, AymakanWebhookPayload, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/carriers/aymakan/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/carriers/aymakan/index.ts"],"names":[],"mappings":"AACA;;;GAGG;AAGH,OAAO,EAAE,cAAc,EAAE,KAAK,aAAa,EAAE,MAAM,WAAW,CAAC;AAG/D,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE,KAAK,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGzF,OAAO,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAGlE,YAAY,EACR,4BAA4B,EAC5B,uBAAuB,EACvB,oBAAoB,EACpB,qBAAqB,GACxB,MAAM,SAAS,CAAC"}