shipflow 0.1.1 → 0.3.0

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.
 
@@ -8,9 +8,10 @@ Think EasyPost / Shippo, but purpose-built for Saudi Arabia and the GCC.
 
 - **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
+- **Auto-validation** — Valibot 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
+- **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](https://github.com/fabian-hiller/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
@@ -25,6 +26,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 +38,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 +105,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 +138,112 @@ 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. 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.
+
+```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
 
@@ -202,7 +310,7 @@ interface WebhookEvent {
 
 ## 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:
+All `createShipment()` calls are **automatically validated** using Valibot schemas before hitting the carrier API. Invalid input throws a `ValidationError` with field-level details:
 
 ```typescript
 try {
@@ -234,7 +342,7 @@ validateCreateShipmentInput(input); // throws ValidationError or returns validat
 validatePickupRequest(pickupInput); // same pattern
 ```
 
-Exported Zod schemas for advanced use (custom refinements, partial validation, etc.):
+Exported Valibot schemas for advanced use (custom refinements, partial validation, etc.):
 
 ```typescript
 import {
@@ -253,6 +361,7 @@ All errors extend `ShipFlowError` for easy catch-all handling:
 import {
   ShipFlowError,
   NetworkError,
+  RateLimitError,
   APIError,
   ValidationError,
   AuthenticationError,
@@ -267,6 +376,8 @@ try {
     // 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) {
@@ -275,6 +386,37 @@ try {
 }
 ```
 
+> `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.
+
+```typescript
+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`:

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

@@ -51,6 +51,13 @@ export declare class AramexAdapter extends BaseCarrierAdapter {
      * Extracts the Aramex "Fake 200 OK" error (envelope-level `HasErrors` +
      * `Notifications`). Passed to every request so the HttpClient raises APIError.
      */
+    /**
+     * Aramex reports throttling inside its "fake 200" envelope (and sometimes on a
+     * non-429 status) rather than via HTTP 429, so status-code detection misses it.
+     * Match the rate-limit wording in the notifications and flag it so the
+     * HttpClient raises a retryable `RateLimitError` instead of a plain APIError.
+     */
+    private static readonly RATE_LIMIT_PATTERN;
     private static aramexErrorExtractor;
     private static notificationsToErrors;
     protected executeCreateShipment(input: CreateShipmentInput): Promise<Shipment>;

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

@@ -1 +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;AAqD7C,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;IA4BZ,KAAK,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;IAYtD,aAAa,CAAC,eAAe,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAkBnE,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;IAgCnD,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"}
+{"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;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CACe;IAEzD,OAAO,CAAC,MAAM,CAAC,oBAAoB;IA4BnC,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.js

@@ -6,7 +6,7 @@ import {
   ValidationError,
   validateCreateShipmentInput,
   validatePickupRequest
-} from "../../index-qjtxhwzv.js";
+} from "../../index-qnxj8bct.js";
 
 // src/carriers/aramex/services.ts
 var AramexProductGroup = {
@@ -119,7 +119,7 @@ function resolvePaymentType(input) {
   const meta = getMeta(input, "paymentType");
   if (meta === "P" || meta === "C" || meta === "3")
     return meta;
-  return input.cod?.enabled ? "C" : "P";
+  return "P";
 }
 function aggregateWeight(input) {
   const allLb = input.parcels.every((p) => p.weight.unit === "lb");
@@ -141,19 +141,31 @@ function mapDimensions(dims) {
     Unit: "CM"
   };
 }
-function mapAddress(addr) {
+function buildPartyAddress(fields) {
   return {
-    Line1: addr.line1,
-    Line2: addr.line2 ?? "",
-    Line3: addr.neighbourhood ?? "",
-    City: addr.city,
-    StateOrProvinceCode: addr.state,
-    PostCode: addr.postalCode ?? "",
-    CountryCode: addr.countryCode,
-    Longitude: addr.coordinates?.longitude,
-    Latitude: addr.coordinates?.latitude
+    Line1: fields.line1,
+    Line2: fields.line2 ?? "",
+    Line3: fields.line3 ?? "",
+    City: fields.city,
+    StateOrProvinceCode: fields.state,
+    PostCode: fields.postCode ?? "",
+    CountryCode: fields.countryCode,
+    Longitude: fields.coordinates?.longitude,
+    Latitude: fields.coordinates?.latitude
   };
 }
+function mapAddress(addr) {
+  return buildPartyAddress({
+    line1: addr.line1,
+    line2: addr.line2,
+    line3: addr.neighbourhood,
+    city: addr.city,
+    state: addr.state,
+    postCode: addr.postalCode,
+    countryCode: addr.countryCode,
+    coordinates: addr.coordinates
+  });
+}
 function buildContact(opts) {
   return {
     Department: "",
@@ -257,11 +269,11 @@ function mapPickupRequest(input, ctx) {
   const closing = new Date(`${input.date}T17:00:00`);
   return {
     Reference1: input.trackingNumbers?.[0],
-    PickupAddress: {
-      Line1: input.address,
-      City: input.city,
-      CountryCode: ctx.countryCode
-    },
+    PickupAddress: buildPartyAddress({
+      line1: input.address,
+      city: input.city,
+      countryCode: ctx.countryCode
+    }),
     PickupContact: buildContact({
       personName: input.contactName,
       companyName: ctx.companyName ?? input.contactName,
@@ -347,6 +359,16 @@ function normalizeTrackingResults(raw) {
   }
   return raw;
 }
+function mapNonExistingWaybill(waybill) {
+  return {
+    trackingNumber: waybill,
+    carrier: "aramex",
+    status: "unknown",
+    statusLabel: "Waybill not found",
+    events: [],
+    raw: { nonExisting: true, waybill }
+  };
+}
 function mapRate(response, input) {
   const { productType } = resolveProductGroupAndType(input);
   return {
@@ -459,6 +481,7 @@ class AramexAdapter extends BaseCarrierAdapter {
       version: cfg.version
     });
   }
+  static RATE_LIMIT_PATTERN = /rate.?limit|too many request|throttl|quota exceeded/i;
   static aramexErrorExtractor(json) {
     const obj = json;
     const notifications = obj?.Notifications ?? [];
@@ -467,7 +490,8 @@ class AramexAdapter extends BaseCarrierAdapter {
     return {
       hasError,
       message,
-      errors: notifications.length ? AramexAdapter.notificationsToErrors(notifications) : undefined
+      errors: notifications.length ? AramexAdapter.notificationsToErrors(notifications) : undefined,
+      rateLimited: hasError && AramexAdapter.RATE_LIMIT_PATTERN.test(message ?? "")
     };
   }
   static notificationsToErrors(notifications) {
@@ -548,7 +572,7 @@ class AramexAdapter extends BaseCarrierAdapter {
       Transaction: EMPTY_TRANSACTION,
       ShipmentNumber: trackingNumber,
       LabelInfo: DEFAULT_LABEL_INFO
-    }, { errorExtractor: AramexAdapter.aramexErrorExtractor });
+    }, { retry: true, errorExtractor: AramexAdapter.aramexErrorExtractor });
     const url = response.ShipmentLabel?.LabelURL;
     if (!url) {
       throw new APIError("Failed to get label", {
@@ -561,10 +585,10 @@ class AramexAdapter extends BaseCarrierAdapter {
   async track(trackingNumber) {
     const results = await this.trackMultiple([trackingNumber]);
     const result = results[0];
-    if (!result) {
+    if (!result || result.status === "unknown" && result.events.length === 0) {
       throw new APIError("Shipment not found", {
         carrier: "aramex",
-        raw: { trackingNumber }
+        raw: result?.raw ?? { trackingNumber }
       });
     }
     return result;
@@ -577,7 +601,9 @@ class AramexAdapter extends BaseCarrierAdapter {
       GetLastTrackingUpdateOnly: false
     }, { retry: true, errorExtractor: AramexAdapter.aramexErrorExtractor });
     const map = normalizeTrackingResults(response.TrackingResults);
-    return Object.entries(map).map(([waybill, results]) => mapTrackingResult(waybill, results));
+    const found = Object.entries(map).map(([waybill, results]) => mapTrackingResult(waybill, results));
+    const nonExisting = (response.NonExistingWaybills ?? []).map(mapNonExistingWaybill);
+    return [...found, ...nonExisting];
   }
   async trackByReference(reference) {
     const result = await this.track(reference);
@@ -618,6 +644,15 @@ class AramexAdapter extends BaseCarrierAdapter {
         raw: response
       });
     }
+    const failedShipments = (processed.ProcessedShipments ?? []).filter((s) => s.HasErrors);
+    if (failedShipments.length > 0) {
+      const notifications = failedShipments.flatMap((s) => s.Notifications ?? []);
+      throw new APIError(notifications.map((n) => n.Message).filter(Boolean).join("; ") || `Pickup created but ${failedShipments.length} shipment(s) failed`, {
+        carrier: "aramex",
+        errors: AramexAdapter.notificationsToErrors(notifications),
+        raw: response
+      });
+    }
     return mapPickupResponse(processed, input);
   }
   async cancelPickup(pickupId) {
@@ -658,4 +693,4 @@ export {
   AramexAdapter
 };
 
-//# debugId=F2518B67CA4397C364756E2164756E21
+//# debugId=A6EBA2B597BA645F64756E2164756E21