shipflow 0.1.0 → 0.2.1

package/README.md

@@ -1,6 +1,6 @@
 # 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.
+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.
 
@@ -25,6 +25,7 @@ bun add shipflow
 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: [
@@ -36,6 +37,18 @@ const client = new ShipFlow({
       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"
+      },
+    }),
   ],
 });
 
@@ -91,25 +104,26 @@ Every carrier adapter implements these **required** methods:
 
 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)`     | ✅      | ✅   |
+| 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:
 
@@ -123,19 +137,111 @@ SMSA-specific methods:
 
 ## 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             | ❌                              | ❌                                 |
+| 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.
+- **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.
+
+```typescript
+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 |
+
+```typescript
+// 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 `UpdateCode`s 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
 

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

@@ -0,0 +1,82 @@
+/**
+ * Aramex Carrier Adapter
+ * Implementation of the CarrierAdapter interface for the Aramex JSON Shipping
+ * Services API v2.
+ *
+ * Key differences from the other carriers:
+ * - Auth is a `ClientInfo` object sent in EVERY request body (not headers).
+ * - The four Aramex services (Shipping, Tracking, RateCalculator, Location)
+ *   live on different base URLs, so the adapter holds one HttpClient per service.
+ * - Errors use the "Fake 200 OK" pattern (HTTP 200 + `HasErrors`/`Notifications`),
+ *   surfaced via the shared HttpClient's `errorExtractor` hook on every call.
+ */
+import type { CarrierConfig, City, CreateShipmentInput, Location, Pickup, PickupRequest, Rate, Shipment, TrackingResult } from "../../core/types.js";
+import { BaseCarrierAdapter } from "../base.js";
+export interface AramexConfig extends CarrierConfig {
+    credentials: {
+        userName: string;
+        password: string;
+        accountNumber: string;
+        accountPin: string;
+        accountEntity: string;
+        accountCountryCode: string;
+    };
+    /** API source channel (default 24). */
+    source?: number;
+    /** ClientInfo version (default "v1.0"). */
+    version?: string;
+    /** Company name used when an address has no company set. */
+    companyName?: string;
+    /**
+     * Optional override for the Location service base URL. Live Aramex WSDLs
+     * disagree on the production Location host (ws.aramex.net vs anfe02.aramex.com);
+     * set this if your account is provisioned on a different host.
+     */
+    locationBaseUrl?: string;
+}
+export declare class AramexAdapter extends BaseCarrierAdapter {
+    readonly name = "aramex";
+    readonly supportedCountries: string[];
+    private shippingHttp;
+    private trackingHttp;
+    private rateHttp;
+    private locationHttp;
+    constructor(config: AramexConfig);
+    protected getBaseUrl(): string;
+    /** Derive a sibling service base URL by swapping the `/Shipping/` segment. */
+    private serviceBase;
+    private get aramexConfig();
+    private buildClientInfo;
+    /**
+     * Extracts the Aramex "Fake 200 OK" error (envelope-level `HasErrors` +
+     * `Notifications`). Passed to every request so the HttpClient raises APIError.
+     */
+    private static aramexErrorExtractor;
+    private static notificationsToErrors;
+    protected executeCreateShipment(input: CreateShipmentInput): Promise<Shipment>;
+    /**
+     * Create multiple shipments in a single request. Aramex's `CreateShipments`
+     * operation is natively batch — it takes a `Shipments` array and returns one
+     * processed result per shipment, in request order.
+     *
+     * Fails loud: if ANY shipment in the batch errors, an `APIError` is thrown
+     * whose `raw` holds the full response, so already-created AWBs remain
+     * recoverable (the unified `Shipment` type has no per-item error channel).
+     */
+    createBulkShipments(inputs: CreateShipmentInput[]): Promise<Shipment[]>;
+    /**
+     * Aramex's classic Shipping Services API has no shipment-cancellation
+     * endpoint, so this is unsupported. (Pickups can be cancelled via cancelPickup.)
+     */
+    cancelShipment(_trackingNumber: string): Promise<boolean>;
+    getLabel(trackingNumber: string, _format?: "PDF" | "ZPL" | "PNG"): Promise<string>;
+    track(trackingNumber: string): Promise<TrackingResult>;
+    trackMultiple(trackingNumbers: string[]): Promise<TrackingResult[]>;
+    trackByReference(reference: string): Promise<TrackingResult>;
+    getRates(input: CreateShipmentInput): Promise<Rate[]>;
+    createPickup(input: PickupRequest): Promise<Pickup>;
+    cancelPickup(pickupId: string | number): Promise<boolean>;
+    getCities(countryCode?: string): Promise<City[]>;
+    getDropoffLocations(countryCode?: string): Promise<Location[]>;
+}
+//# sourceMappingURL=adapter.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../src/carriers/aramex/adapter.ts"],"names":[],"mappings":"AACA;;;;;;;;;;;GAWG;AAYH,OAAO,KAAK,EACV,aAAa,EACb,IAAI,EACJ,mBAAmB,EACnB,QAAQ,EACR,MAAM,EACN,aAAa,EACb,IAAI,EACJ,QAAQ,EACR,cAAc,EACf,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AAsD7C,MAAM,WAAW,YAAa,SAAQ,aAAa;IACjD,WAAW,EAAE;QACX,QAAQ,EAAE,MAAM,CAAC;QACjB,QAAQ,EAAE,MAAM,CAAC;QACjB,aAAa,EAAE,MAAM,CAAC;QACtB,UAAU,EAAE,MAAM,CAAC;QACnB,aAAa,EAAE,MAAM,CAAC;QACtB,kBAAkB,EAAE,MAAM,CAAC;KAC5B,CAAC;IACF,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,4DAA4D;IAC5D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,aAAc,SAAQ,kBAAkB;IACnD,QAAQ,CAAC,IAAI,YAAY;IACzB,QAAQ,CAAC,kBAAkB,WAWzB;IAEF,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,YAAY,CAAa;IACjC,OAAO,CAAC,QAAQ,CAAa;IAC7B,OAAO,CAAC,YAAY,CAAa;gBAErB,MAAM,EAAE,YAAY;IAuBhC,SAAS,CAAC,UAAU,IAAI,MAAM;IAM9B,8EAA8E;IAC9E,OAAO,CAAC,WAAW;IAInB,OAAO,KAAK,YAAY,GAEvB;IAED,OAAO,CAAC,eAAe;IAQvB;;;OAGG;IACH,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAyBnC,OAAO,CAAC,MAAM,CAAC,qBAAqB;cAcpB,qBAAqB,CACnC,KAAK,EAAE,mBAAmB,GACzB,OAAO,CAAC,QAAQ,CAAC;IA6CpB;;;;;;;;OAQG;IACG,mBAAmB,CACvB,MAAM,EAAE,mBAAmB,EAAE,GAC5B,OAAO,CAAC,QAAQ,EAAE,CAAC;IAwDtB;;;OAGG;IACH,cAAc,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAQnD,QAAQ,CACZ,cAAc,EAAE,MAAM,EACtB,OAAO,CAAC,EAAE,KAAK,GAAG,KAAK,GAAG,KAAK,GAC9B,OAAO,CAAC,MAAM,CAAC;IA8BZ,KAAK,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAetD,aAAa,CAAC,eAAe,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IA4BnE,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAU5D,QAAQ,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IA4BrD,YAAY,CAAC,KAAK,EAAE,aAAa,GAAG,OAAO,CAAC,MAAM,CAAC;IAyDnD,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAoBzD,SAAS,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,EAAE,CAAC;IAehD,mBAAmB,CAAC,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,EAAE,CAAC;CAcrE"}

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

@@ -0,0 +1,9 @@
+/**
+ * Aramex Carrier Exports
+ * Import from 'shipflow/carriers/aramex' for tree-shaking.
+ */
+export { AramexAdapter, type AramexConfig } from "./adapter.js";
+export { AramexProductGroup, AramexProductType, AramexPaymentType, AramexService, AramexStatusCodes, type AramexProductGroupType, type AramexProductTypeCode, type AramexPaymentTypeCode, } from "./services.js";
+export { buildClientInfo, mapAramexStatus, statusFromDescription, parseAramexDate, type AramexCredentials, } from "./mappers.js";
+export type { AramexClientInfo, AramexCreateShipmentsRequest, AramexCreateShipmentsResponse, AramexProcessedShipment, AramexShipmentLabel, AramexPrintLabelResponse, AramexTrackShipmentsRequest, AramexTrackShipmentsResponse, AramexTrackingResult, AramexCalculateRateRequest, AramexCalculateRateResponse, AramexCreatePickupRequest, AramexCreatePickupResponse, AramexCancelPickupRequest, AramexFetchCitiesResponse, AramexFetchOfficesResponse, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/carriers/aramex/index.ts"],"names":[],"mappings":"AACA;;;GAGG;AAGH,OAAO,EAAE,aAAa,EAAE,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAG7D,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,iBAAiB,EACjB,aAAa,EACb,iBAAiB,EACjB,KAAK,sBAAsB,EAC3B,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,GAC3B,MAAM,YAAY,CAAC;AAGpB,OAAO,EACL,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,eAAe,EACf,KAAK,iBAAiB,GACvB,MAAM,WAAW,CAAC;AAGnB,YAAY,EACV,gBAAgB,EAChB,4BAA4B,EAC5B,6BAA6B,EAC7B,uBAAuB,EACvB,mBAAmB,EACnB,wBAAwB,EACxB,2BAA2B,EAC3B,4BAA4B,EAC5B,oBAAoB,EACpB,0BAA0B,EAC1B,2BAA2B,EAC3B,yBAAyB,EACzB,0BAA0B,EAC1B,yBAAyB,EACzB,yBAAyB,EACzB,0BAA0B,GAC3B,MAAM,SAAS,CAAC"}