pathao-merchant-sdk 2.3.1 → 3.0.0

package/CHANGELOG.md

@@ -5,6 +5,24 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [3.0.0](https://github.com/Sifat07/pathao-merchant-sdk/compare/pathao-merchant-sdk-v2.3.2...pathao-merchant-sdk-v3.0.0) (2026-10-02)
+
+
+### ⚠ BREAKING CHANGES
+
+* new PathaoApiService(config) no longer reads PATHAO_* environment variables for missing fields or PATHAO_TIMEOUT. Pass every field explicitly, or use PathaoApiService.fromEnv().
+
+### Bug Fixes
+
+* close [#12](https://github.com/Sifat07/pathao-merchant-sdk/issues/12)–[#20](https://github.com/Sifat07/pathao-merchant-sdk/issues/20) (security, retries, webhooks, phones, explicit config, types, CI) ([#21](https://github.com/Sifat07/pathao-merchant-sdk/issues/21)) ([9702f72](https://github.com/Sifat07/pathao-merchant-sdk/commit/9702f724e8bc5fced2ec644d746d29b6242b0baf))
+
+## [2.3.2](https://github.com/Sifat07/pathao-merchant-sdk/compare/pathao-merchant-sdk-v2.3.1...pathao-merchant-sdk-v2.3.2) (2026-09-23)
+
+
+### Bug Fixes
+
+* stop 429s tripping the circuit breaker, document webhook trust ([4861fc7](https://github.com/Sifat07/pathao-merchant-sdk/commit/4861fc7177c1872dfbbeb271c28f832ab82435c1))
+
 ## [2.3.1](https://github.com/Sifat07/pathao-merchant-sdk/compare/pathao-merchant-sdk-v2.3.0...pathao-merchant-sdk-v2.3.1) (2026-09-17)
 
 

package/CONTRIBUTING.md

@@ -10,10 +10,9 @@ Thank you for your interest in contributing to the Pathao Merchant SDK! This doc
    git clone https://github.com/YOUR_USERNAME/pathao-merchant-sdk.git
    cd pathao-merchant-sdk
    ```
-3. **Install dependencies**:
+3. **Install dependencies** (the repo pins pnpm 10 via `packageManager`; `corepack enable` makes `pnpm` use it):
    ```bash
-   npm install
-   # or
+   corepack enable
    pnpm install
    ```
 
@@ -37,9 +36,10 @@ git checkout -b fix/your-bug-fix
 ### 3. Run Tests
 
 ```bash
-npm test
-npm run build
-npm run type-check
+pnpm run lint
+pnpm run type-check
+pnpm test
+pnpm run build
 ```
 
 ### 4. Commit Your Changes
@@ -159,8 +159,8 @@ What should happen
 What actually happens
 
 **Environment**
-- SDK Version: 1.2.0
-- Node Version: 18.0.0
+- SDK Version: 3.0.0
+- Node Version: 22.x
 - OS: macOS/Windows/Linux
 ```
 

package/README.md

@@ -28,6 +28,7 @@ An **unofficial** TypeScript SDK for the [Pathao Courier Merchant API](https://m
 - [Error Handling](#error-handling)
 - [Webhooks](#webhooks)
 - [TypeScript Types](#typescript-types)
+- [Upgrading to 3.0.0](#upgrading-to-300)
 - [Contributing](#contributing)
 - [License](#license)
 - [Changelog](#changelog)
@@ -124,6 +125,8 @@ PATHAO_PASSWORD=your-password
 PATHAO_TIMEOUT=30000
 ```
 
+Only `PathaoApiService.fromEnv()` reads these variables. `new PathaoApiService(config)`, `fromConfig()`, `sandbox()` and `production()` use exactly the config you pass, so a blank field fails validation instead of silently picking up another account's credentials from the environment (important when each tenant brings their own Pathao account).
+
 If you use `dotenv`, load it before initializing the SDK:
 
 ```typescript
@@ -175,6 +178,7 @@ const pathao = new PathaoApiService(config, {
     threshold: 5, // Failures before opening circuit (default: 5)
     timeout: 60_000, // Ms before attempting to close circuit (default: 60000)
   },
+  minRequestIntervalMs: 0, // Min gap between requests, queued (default: 0, off)
 });
 ```
 
@@ -193,7 +197,7 @@ const order = await pathao.createOrder({
   store_id: 12345, // Required — your store ID
   merchant_order_id: "ORDER-001", // Optional — your internal tracking ID
   recipient_name: "John Doe", // Required — 3–100 characters
-  recipient_phone: "01712345678", // Required — 11 digits, starts with 01
+  recipient_phone: "01712345678", // Required — BD mobile; +880… / dashes are normalised before sending
   recipient_secondary_phone: "01812345678", // Optional
   recipient_address: "House 10, Road 5, Dhanmondi, Dhaka", // Required — 10–220 chars
   recipient_city: 1, // Optional — auto-detected if omitted
@@ -338,7 +342,8 @@ All helpers are static and can be used before constructing the SDK:
 ```typescript
 import { PathaoApiService } from "pathao-merchant-sdk";
 
-PathaoApiService.validatePhoneNumber("01712345678"); // true  — 11 digits, starts with 01
+PathaoApiService.validatePhoneNumber("+8801712345678"); // true  — BD mobile, 013–019
+PathaoApiService.normalizePhoneNumber("+880 1712-345678"); // "01712345678" (null if invalid)
 PathaoApiService.validateContactNumber("01712345678"); // true  — same rules
 PathaoApiService.validateAddress("House 10, Road 5, Dhanmondi, Dhaka"); // true — 10–220 chars
 PathaoApiService.validateStoreAddress("House 10, Road 5, Dhanmondi"); // true — 15–120 chars
@@ -347,6 +352,8 @@ PathaoApiService.validateRecipientName("John Doe"); // true  — 3–100 chars
 PathaoApiService.validateStoreName("My Store"); // true  — 3–50 chars
 ```
 
+`createOrder` and `createBulkOrder` run the phone, name, address and weight checks before sending (a bulk failure names the index, e.g. `orders[3]: …`), and send the normalised phone numbers.
+
 ---
 
 ## Error Handling
@@ -360,6 +367,7 @@ try {
   const order = await pathao.createOrder(orderData);
 } catch (err) {
   if (err instanceof PathaoApiError) {
+    console.error("Kind:", err.kind, "retryable:", err.retryable); // e.g. "validation", false
     console.error("HTTP status:", err.status); // e.g. 422
     console.error("Pathao code:", err.code); // Pathao internal error code
     console.error("Type:", err.type); // e.g. "ValidationException"
@@ -370,6 +378,23 @@ try {
 }
 ```
 
+### Error kinds
+
+Branch on `err.kind` instead of matching message text. `err.retryable` is `true` for `unavailable` and `rate_limited`.
+
+| `kind`         | When                                                        |
+| -------------- | ----------------------------------------------------------- |
+| `validation`   | Rejected by the SDK before sending, or HTTP 400/422         |
+| `config`       | Missing/invalid `baseURL` or credentials                    |
+| `auth`         | HTTP 401                                                    |
+| `forbidden`    | HTTP 403                                                    |
+| `not_found`    | HTTP 404                                                    |
+| `rate_limited` | HTTP 429                                                    |
+| `unavailable`  | 5xx, timeout, network failure, circuit breaker open         |
+| `unexpected`   | Anything else; inspect `err.responseData`                   |
+
+A retryable error on `createOrder` / `createBulkOrder` may still have booked the parcel. Look the order up before retrying a create.
+
 ### Common error scenarios
 
 | Status | Cause                                                        |
@@ -377,8 +402,32 @@ try {
 | 400    | Bad request / missing required fields                        |
 | 401    | Invalid or expired credentials                               |
 | 422    | Validation failure — check `err.errors` for field details    |
-| 429    | Rate limited — SDK retries automatically after `Retry-After` |
-| 503    | Circuit breaker open — too many consecutive failures         |
+| 429    | Rate limited — see below                                     |
+| 503    | Circuit breaker open — repeated network, 5xx or 401 failures |
+
+### Rate limits
+
+Pathao doesn't document its limits. Measured against its gateway (Sep 2026): **60 requests per rolling 60 seconds**, and the `429` carries **no `Retry-After` header**. The SDK therefore does not retry a `429` unless the server sends `Retry-After`; it throws `PathaoApiError` with `status: 429` so you can back off. 429s never open the circuit breaker.
+
+For bulk work (e.g. polling `getOrderStatus` for many orders) pass `minRequestIntervalMs: 1500`. The client then queues its requests (token grants and retries included) one every 1.5 s, about 40/min, leaving headroom for webhooks and other callers sharing the same credentials. Spacing is per instance: share one instance across the process.
+
+Both numbers are exported: `PATHAO_RATE_LIMIT_PER_MINUTE` (60) and `PATHAO_STATUS_RETENTION_DAYS` (90, roughly how long `getOrderStatus` finds an order).
+
+### Retries
+
+The SDK retries a `5xx` up to twice, but only for requests that are safe to repeat: GETs, token grants and `calculatePrice`. `createOrder`, `createBulkOrder` and `createStore` are **never** retried, because a `5xx` (e.g. a gateway `504` in front of a slow success) doesn't mean the order wasn't booked. If you retry a create yourself, look the order up first, or you may book the parcel twice.
+
+### Order lifecycle
+
+Webhook events and `order_status_slug` describe the same journey. Despite its name, `order_status_slug` is a display label (`"Pending"`, `"In Transit"`, `"Return"`), and Pathao's own plugin spells the same states differently (`Pickup_Requested`, `At_the_Sorting_HUB`), so the SDK doesn't type it. `toLifecycleStatus` maps any of these spellings, or a webhook event (`order.pickup-requested`), to one of `created`, `picked_up`, `in_transit`, `out_for_delivery`, `delivered`, `partial`, `on_hold`, `returning`, `returned`, `cancelled`, or `unknown`.
+
+```typescript
+import { toLifecycleStatus, isFinalLifecycleStatus } from "pathao-merchant-sdk"; // also exported from /webhooks
+
+toLifecycleStatus("order.return-id-created"); // "returning" — not back yet, don't restock
+toLifecycleStatus(info.data.order_status_slug);
+isFinalLifecycleStatus("delivered"); // true
+```
 
 ---
 
@@ -389,10 +438,13 @@ The webhooks module is a **separate entry point** with zero runtime dependencies
 ### How Pathao webhooks work
 
 1. Pathao sends a POST request with a JSON payload to your URL.
-2. The `X-PATHAO-Signature` header contains your configured webhook secret verbatim.
-3. Your endpoint must respond within 10 seconds with an `X-Pathao-Merchant-Webhook-Integration-Secret` header whose value equals your webhook secret.
+2. The `X-PATHAO-Signature` header contains the webhook secret verbatim.
+3. Your endpoint must respond within 10 seconds with an `X-Pathao-Merchant-Webhook-Integration-Secret` header whose value equals the webhook secret.
 4. The HTTP status code should be 2xx.
 
+> [!WARNING]
+> **Webhooks are not authenticated.** The webhook secret is one fixed value shared by every merchant (it is hardcoded in Pathao's own open-source WooCommerce plugin), so anyone can send a request that looks like it came from Pathao. Never apply status, fee or COD amounts straight from a payload. Use the webhook only as a signal: look up your own order by `consignment_id`, then fetch the real state with `getOrderStatus()` and act on that. An unguessable callback URL (e.g. `/webhooks/pathao/<random-token>`) cuts down junk traffic, since the URL is the one thing only you and Pathao know.
+
 ### Setup requirements
 
 - Your URL must be publicly reachable over HTTPS with a valid SSL certificate.
@@ -443,6 +495,12 @@ handler.on("error", (err) => {
   console.error("Webhook error:", err.message);
 });
 
+// Payloads whose `event` isn't a known PathaoWebhookEvent arrive here, never
+// under their own name (so a forged {"event":"error"} can't fire "error").
+handler.on("unknown", (payload) => {
+  console.warn("Unrecognised Pathao event:", payload.event);
+});
+
 app.post(
   "/webhooks/pathao",
   express.raw({ type: "application/json" }),
@@ -549,6 +607,9 @@ All payloads also include `updated_at` (MySQL datetime) and `timestamp` (ISO 860
 ```typescript
 import type {
   PathaoConfig,
+  PathaoClientOptions,
+  PathaoErrorKind,
+  PathaoLifecycleStatus,
   PathaoOrderRequest,
   PathaoOrderResponse,
   PathaoStoreRequest,
@@ -565,6 +626,7 @@ import type {
   WebhookEventPayloadMap,
   OrderDeliveredPayload,
   OrderReturnIdCreatedPayload,
+  UnknownWebhookPayload,
   PathaoWebhookEvent,
 } from "pathao-merchant-sdk/webhooks";
 
@@ -574,6 +636,61 @@ type PaidPayload = WebhookEventPayloadMap[PathaoWebhookEvent.ORDER_PAID];
 
 ---
 
+## Upgrading to 3.0.0
+
+3.0.0 has **one breaking change**. Most apps need no code changes; check the table below if you catch specific errors or listen for unusual webhook events.
+
+### Required: explicit config no longer reads environment variables
+
+In 2.x, `new PathaoApiService(config)` (and `fromConfig()`, `sandbox()`, `production()`) filled any blank field from `PATHAO_*` environment variables and read `PATHAO_TIMEOUT`. In a multi-tenant app, a tenant with a blank field silently used the platform's own Pathao account. In 3.0.0 those constructors use **exactly** the config you pass. Only `fromEnv()` reads the environment.
+
+**You are affected if** you leave config fields blank or omit them and rely on the environment to fill them in, or set `PATHAO_TIMEOUT` without using `fromEnv()`.
+
+```typescript
+// 2.x — blank fields came from PATHAO_* env vars
+const pathao = new PathaoApiService({ baseURL: "https://api-hermes.pathao.com" } as PathaoConfig);
+const sandbox = PathaoApiService.sandbox({ clientId: "", clientSecret: "", username: "", password: "" });
+
+// 3.0.0 — either read everything from the environment...
+const pathao = PathaoApiService.fromEnv(); // PATHAO_BASE_URL, _CLIENT_ID, _CLIENT_SECRET, _USERNAME, _PASSWORD, _TIMEOUT
+
+// ...or pass every field yourself
+const pathao = new PathaoApiService({
+  baseURL: process.env.PATHAO_BASE_URL!,
+  clientId: process.env.PATHAO_CLIENT_ID!,
+  clientSecret: process.env.PATHAO_CLIENT_SECRET!,
+  username: process.env.PATHAO_USERNAME!,
+  password: process.env.PATHAO_PASSWORD!,
+  timeout: 30_000,
+});
+```
+
+If you already pass every field explicitly, nothing changes. A missing field now fails on the first API call with `PathaoApiError` (`kind: "config"`) instead of quietly using another account.
+
+### Behaviour changes to check
+
+| Change | Affects you if… | What to do |
+| --- | --- | --- |
+| `createOrder`, `createBulkOrder` and `createStore` are no longer auto-retried on `5xx` | You relied on the SDK to retry failed creates | Retry yourself, but look the order up first: a `5xx` may hide a booking that went through. See [Retries](#retries). |
+| `createOrder` / `createBulkOrder` validate the secondary phone, recipient name (3–100) and address (10–220) before sending | You send data Pathao would have rejected with a `422` | Fix the data. The error is `PathaoApiError` with `kind: "validation"`; bulk errors name the order (`orders[2]: …`). |
+| Phone numbers are normalised before sending, and only operator prefixes `013`–`019` are valid | You send `+880…` / `017-…` (now accepted), or `011…` / `012…` (now rejected; BTRC lists these as unused) | Nothing for real customers' numbers |
+| Webhook events not in `PathaoWebhookEvent` are emitted as `'unknown'` | You call `handler.on("some.event")` for a name the SDK doesn't list | Listen on `'unknown'` and check `payload.event`. The `'webhook'` catch-all still fires for every event. |
+| A webhook `event` must be a string | You process malformed payloads | Nothing; they now throw `PathaoWebhookError` |
+| Any `3xx` response is an error (redirects are never followed) | Your `baseURL` points at something that redirects | Use the final URL |
+| Some error messages were reworded (config errors, `formatPhoneNumber`) | You match on `err.message` | Switch to `err.kind` |
+| ESM projects (`moduleResolution: node16`/`nodenext`) get the ESM type declarations | You worked around the old CJS-typed imports | Remove the workaround |
+
+### New in 3.0.0 (optional)
+
+- `err.kind` and `err.retryable` on `PathaoApiError` — see [Error kinds](#error-kinds)
+- `toLifecycleStatus()` / `isFinalLifecycleStatus()` — see [Order lifecycle](#order-lifecycle)
+- `minRequestIntervalMs` option — see [Rate limits](#rate-limits)
+- `PathaoApiService.normalizePhoneNumber()`, `PATHAO_RATE_LIMIT_PER_MINUTE`, `PATHAO_STATUS_RETENTION_DAYS`
+- `order_status` (optional) on order webhook payload types
+- Debug logs no longer include token responses
+
+---
+
 ## Contributing
 
 Contributions are welcome. Please open an issue first for significant changes.
@@ -584,6 +701,8 @@ Contributions are welcome. Please open an issue first for significant changes.
 
 ## Development
 
+The repo pins pnpm 10 via `packageManager`. Run `corepack enable` once so `pnpm` uses it; pnpm 11+ ignores the `pnpm` settings in `package.json` and `pnpm install --frozen-lockfile` fails.
+
 ```bash
 pnpm install
 pnpm run build      # compile CJS + ESM + .d.ts
@@ -604,6 +723,18 @@ Open an issue on [GitHub](https://github.com/sifat07/pathao-merchant-sdk/issues)
 
 ## Changelog
 
+Full history: [CHANGELOG.md](CHANGELOG.md).
+
+### 3.0.0
+
+- **Breaking:** explicit config no longer falls back to `PATHAO_*` env vars; use `fromEnv()` — see [Upgrading to 3.0.0](#upgrading-to-300)
+- Order and store creation are never auto-retried on `5xx` (prevents duplicate consignments)
+- Debug logs redact token responses; redirects are never followed
+- Webhooks: unknown event names go to `'unknown'`, never to reserved EventEmitter events
+- Phones normalised (`+880…` accepted); orders fully validated before sending
+- `PathaoApiError.kind` / `.retryable`, `toLifecycleStatus()`, `minRequestIntervalMs`, rate/retention constants
+- Correct ESM types; `/webhooks` resolves under `node10`; CI on pnpm 10 and Node 18–24
+
 ### 2.3.0 — 2026-04-16
 
 - Replaced broken `pnpm audit` with OSV Scanner (scoped to production dependencies)
@@ -628,7 +759,7 @@ Open an issue on [GitHub](https://github.com/sifat07/pathao-merchant-sdk/issues)
 - Factory methods: `fromEnv()`, `fromConfig()`, `sandbox()`, `production()`
 - Debug logging (`debug` option) — `Authorization` header redacted
 - Configurable circuit breaker (throws `PathaoApiError` code 503 when open)
-- Retry logic: 429 reads `Retry-After`, 5xx exponential backoff (max 2 retries)
+- Retry logic: 429 retried only when the server sends `Retry-After`; 5xx exponential backoff (max 2 retries)
 - Deferred config validation — constructor never throws
 - HTTPS enforcement in `validateConfiguration()`
 - `User-Agent: pathao-merchant-sdk node/<version>` header

package/dist/index.d.mts

@@ -1,11 +1,12 @@
+export { P as PATHAO_RATE_LIMIT_PER_MINUTE, a as PATHAO_STATUS_RETENTION_DAYS, b as PathaoLifecycleStatus, i as isFinalLifecycleStatus, t as toLifecycleStatus } from './status-xIApOisZ.mjs';
+
 /**
  * Pathao Courier API Types
  *
  * Official API Details:
  * - Authentication: OAuth2 with client_id, client_secret, username, password
  * - All endpoints use /aladdin/api/v1/ prefix
- * - Base URL can be set via PATHAO_BASE_URL environment variable or constructor config
- * - Timeout can be set via PATHAO_TIMEOUT environment variable or constructor config
+ * - Config is passed explicitly, or read from PATHAO_* env vars by fromEnv()
  */
 interface PathaoAuthResponse {
     token_type: string;
@@ -206,8 +207,8 @@ interface PathaoBulkOrderResponse {
  * API Details (based on public documentation):
  * - Authentication: OAuth2 with client_id, client_secret, username, password
  * - All endpoints use /aladdin/api/v1/ prefix
- * - Base URL can be set via PATHAO_BASE_URL environment variable or constructor config
- * - Timeout can be set via PATHAO_TIMEOUT environment variable or constructor config
+ * - The constructor reads only the config it is given. Use fromEnv() to read
+ *   PATHAO_* environment variables (including PATHAO_TIMEOUT).
  *
  * Features implemented:
  * - Token-based authentication with refresh token support
@@ -218,7 +219,25 @@ interface PathaoBulkOrderResponse {
  * - City, zone, and area management
  */
 
+type PathaoErrorKind = 
+/** Input rejected, by this SDK before sending or by Pathao (HTTP 400/422). */
+'validation'
+/** Missing or wrong baseURL / credentials, caught before any request. */
+ | 'config'
+/** Rejected credentials or token (HTTP 401). */
+ | 'auth'
+/** HTTP 403. */
+ | 'forbidden'
+/** Unknown consignment, store or resource (HTTP 404). */
+ | 'not_found'
+/** HTTP 429. Back off; see PATHAO_RATE_LIMIT_PER_MINUTE. */
+ | 'rate_limited'
+/** 5xx, timeout, network failure or open circuit breaker. */
+ | 'unavailable'
+/** A response this SDK doesn't understand. Inspect `responseData`. */
+ | 'unexpected';
 declare class PathaoApiError extends Error {
+    kind: PathaoErrorKind;
     status: number | undefined;
     code: number | undefined;
     type: string | undefined;
@@ -232,12 +251,31 @@ declare class PathaoApiError extends Error {
         errors?: Record<string, string[]> | undefined;
         validation?: Record<string, string[]> | undefined;
         responseData?: unknown;
+        kind?: PathaoErrorKind | undefined;
     });
+    /**
+     * True for transient failures (`unavailable`, `rate_limited`). For
+     * createOrder / createBulkOrder a 5xx may hide a booking that went through:
+     * look the order up before retrying a create.
+     */
+    get retryable(): boolean;
 }
 interface CircuitBreakerConfig {
     threshold?: number;
     timeout?: number;
 }
+interface PathaoClientOptions {
+    /** Log requests and responses (tokens and Authorization redacted). */
+    debug?: boolean;
+    circuitBreaker?: CircuitBreakerConfig;
+    /**
+     * Minimum gap between requests from this instance, in ms. Requests queue
+     * instead of tripping Pathao's 60/min limit (PATHAO_RATE_LIMIT_PER_MINUTE).
+     * 1500 keeps one instance near 40/min, leaving headroom for other callers
+     * sharing the credentials. Default 0 (no spacing).
+     */
+    minRequestIntervalMs?: number;
+}
 declare class PathaoApiService {
     private pathaoClient;
     private accessToken;
@@ -248,11 +286,10 @@ declare class PathaoApiService {
     private authPromise;
     private hasValidated;
     private debug;
+    private minRequestIntervalMs;
+    private nextRequestAt;
     private circuitBreaker;
-    constructor(config: PathaoConfig, options?: {
-        debug?: boolean;
-        circuitBreaker?: CircuitBreakerConfig;
-    });
+    constructor(config: PathaoConfig, options?: PathaoClientOptions);
     private validateConfiguration;
     private ensureAuthenticated;
     private performAuthentication;
@@ -261,6 +298,7 @@ declare class PathaoApiService {
     private getErrorMessage;
     private toPathaoApiError;
     private handleCircuitBreaker;
+    private waitForRequestSlot;
     private delay;
     createOrder(orderData: PathaoOrderRequest): Promise<PathaoOrderResponse>;
     createStore(storeData: PathaoStoreRequest): Promise<PathaoStoreCreateResponse>;
@@ -272,6 +310,13 @@ declare class PathaoApiService {
     getAreas(zoneId: number): Promise<PathaoAreaResponse>;
     getOrderStatus(consignmentId: string): Promise<PathaoOrderStatusResponse>;
     createBulkOrder(orders: PathaoOrderRequest[]): Promise<PathaoBulkOrderResponse>;
+    private static prepareOrder;
+    /**
+     * Normalise a Bangladeshi mobile number to 01XXXXXXXXX. Accepts +8801…,
+     * 8801… and 01…, with spaces, dashes, dots or parentheses. Returns null for
+     * anything that isn't a BD mobile number (operator prefixes 013–019).
+     */
+    static normalizePhoneNumber(phone: string): string | null;
     static validatePhoneNumber(phone: string): boolean;
     static formatPhoneNumber(phone: string): string;
     static validateAddress(address: string): boolean;
@@ -282,22 +327,10 @@ declare class PathaoApiService {
     static validateContactNumber(phone: string): boolean;
     static validateStoreAddress(address: string): boolean;
     clearAuth(): void;
-    static fromEnv(options?: {
-        debug?: boolean;
-        circuitBreaker?: CircuitBreakerConfig;
-    }): PathaoApiService;
-    static fromConfig(config: PathaoConfig, options?: {
-        debug?: boolean;
-        circuitBreaker?: CircuitBreakerConfig;
-    }): PathaoApiService;
-    static sandbox(credentials: Omit<PathaoConfig, 'baseURL'>, options?: {
-        debug?: boolean;
-        circuitBreaker?: CircuitBreakerConfig;
-    }): PathaoApiService;
-    static production(credentials: Omit<PathaoConfig, 'baseURL'>, options?: {
-        debug?: boolean;
-        circuitBreaker?: CircuitBreakerConfig;
-    }): PathaoApiService;
+    static fromEnv(options?: PathaoClientOptions): PathaoApiService;
+    static fromConfig(config: PathaoConfig, options?: PathaoClientOptions): PathaoApiService;
+    static sandbox(credentials: Omit<PathaoConfig, 'baseURL'>, options?: PathaoClientOptions): PathaoApiService;
+    static production(credentials: Omit<PathaoConfig, 'baseURL'>, options?: PathaoClientOptions): PathaoApiService;
 }
 
-export { type CircuitBreakerConfig, DeliveryType, ItemType, PathaoApiError, PathaoApiService, type PathaoAreaResponse, type PathaoAuthResponse, type PathaoBulkOrderResponse, type PathaoCityResponse, type PathaoConfig, type PathaoError, type PathaoOrderRequest, type PathaoOrderResponse, type PathaoOrderStatusResponse, type PathaoPriceRequest, type PathaoPriceResponse, type PathaoStore, type PathaoStoreCreateResponse, type PathaoStoreListResponse, type PathaoStoreRequest, type PathaoZoneResponse };
+export { type CircuitBreakerConfig, DeliveryType, ItemType, PathaoApiError, PathaoApiService, type PathaoAreaResponse, type PathaoAuthResponse, type PathaoBulkOrderResponse, type PathaoCityResponse, type PathaoClientOptions, type PathaoConfig, type PathaoError, type PathaoErrorKind, type PathaoOrderRequest, type PathaoOrderResponse, type PathaoOrderStatusResponse, type PathaoPriceRequest, type PathaoPriceResponse, type PathaoStore, type PathaoStoreCreateResponse, type PathaoStoreListResponse, type PathaoStoreRequest, type PathaoZoneResponse };

package/dist/index.d.ts

@@ -1,11 +1,12 @@
+export { P as PATHAO_RATE_LIMIT_PER_MINUTE, a as PATHAO_STATUS_RETENTION_DAYS, b as PathaoLifecycleStatus, i as isFinalLifecycleStatus, t as toLifecycleStatus } from './status-xIApOisZ.js';
+
 /**
  * Pathao Courier API Types
  *
  * Official API Details:
  * - Authentication: OAuth2 with client_id, client_secret, username, password
  * - All endpoints use /aladdin/api/v1/ prefix
- * - Base URL can be set via PATHAO_BASE_URL environment variable or constructor config
- * - Timeout can be set via PATHAO_TIMEOUT environment variable or constructor config
+ * - Config is passed explicitly, or read from PATHAO_* env vars by fromEnv()
  */
 interface PathaoAuthResponse {
     token_type: string;
@@ -206,8 +207,8 @@ interface PathaoBulkOrderResponse {
  * API Details (based on public documentation):
  * - Authentication: OAuth2 with client_id, client_secret, username, password
  * - All endpoints use /aladdin/api/v1/ prefix
- * - Base URL can be set via PATHAO_BASE_URL environment variable or constructor config
- * - Timeout can be set via PATHAO_TIMEOUT environment variable or constructor config
+ * - The constructor reads only the config it is given. Use fromEnv() to read
+ *   PATHAO_* environment variables (including PATHAO_TIMEOUT).
  *
  * Features implemented:
  * - Token-based authentication with refresh token support
@@ -218,7 +219,25 @@ interface PathaoBulkOrderResponse {
  * - City, zone, and area management
  */
 
+type PathaoErrorKind = 
+/** Input rejected, by this SDK before sending or by Pathao (HTTP 400/422). */
+'validation'
+/** Missing or wrong baseURL / credentials, caught before any request. */
+ | 'config'
+/** Rejected credentials or token (HTTP 401). */
+ | 'auth'
+/** HTTP 403. */
+ | 'forbidden'
+/** Unknown consignment, store or resource (HTTP 404). */
+ | 'not_found'
+/** HTTP 429. Back off; see PATHAO_RATE_LIMIT_PER_MINUTE. */
+ | 'rate_limited'
+/** 5xx, timeout, network failure or open circuit breaker. */
+ | 'unavailable'
+/** A response this SDK doesn't understand. Inspect `responseData`. */
+ | 'unexpected';
 declare class PathaoApiError extends Error {
+    kind: PathaoErrorKind;
     status: number | undefined;
     code: number | undefined;
     type: string | undefined;
@@ -232,12 +251,31 @@ declare class PathaoApiError extends Error {
         errors?: Record<string, string[]> | undefined;
         validation?: Record<string, string[]> | undefined;
         responseData?: unknown;
+        kind?: PathaoErrorKind | undefined;
     });
+    /**
+     * True for transient failures (`unavailable`, `rate_limited`). For
+     * createOrder / createBulkOrder a 5xx may hide a booking that went through:
+     * look the order up before retrying a create.
+     */
+    get retryable(): boolean;
 }
 interface CircuitBreakerConfig {
     threshold?: number;
     timeout?: number;
 }
+interface PathaoClientOptions {
+    /** Log requests and responses (tokens and Authorization redacted). */
+    debug?: boolean;
+    circuitBreaker?: CircuitBreakerConfig;
+    /**
+     * Minimum gap between requests from this instance, in ms. Requests queue
+     * instead of tripping Pathao's 60/min limit (PATHAO_RATE_LIMIT_PER_MINUTE).
+     * 1500 keeps one instance near 40/min, leaving headroom for other callers
+     * sharing the credentials. Default 0 (no spacing).
+     */
+    minRequestIntervalMs?: number;
+}
 declare class PathaoApiService {
     private pathaoClient;
     private accessToken;
@@ -248,11 +286,10 @@ declare class PathaoApiService {
     private authPromise;
     private hasValidated;
     private debug;
+    private minRequestIntervalMs;
+    private nextRequestAt;
     private circuitBreaker;
-    constructor(config: PathaoConfig, options?: {
-        debug?: boolean;
-        circuitBreaker?: CircuitBreakerConfig;
-    });
+    constructor(config: PathaoConfig, options?: PathaoClientOptions);
     private validateConfiguration;
     private ensureAuthenticated;
     private performAuthentication;
@@ -261,6 +298,7 @@ declare class PathaoApiService {
     private getErrorMessage;
     private toPathaoApiError;
     private handleCircuitBreaker;
+    private waitForRequestSlot;
     private delay;
     createOrder(orderData: PathaoOrderRequest): Promise<PathaoOrderResponse>;
     createStore(storeData: PathaoStoreRequest): Promise<PathaoStoreCreateResponse>;
@@ -272,6 +310,13 @@ declare class PathaoApiService {
     getAreas(zoneId: number): Promise<PathaoAreaResponse>;
     getOrderStatus(consignmentId: string): Promise<PathaoOrderStatusResponse>;
     createBulkOrder(orders: PathaoOrderRequest[]): Promise<PathaoBulkOrderResponse>;
+    private static prepareOrder;
+    /**
+     * Normalise a Bangladeshi mobile number to 01XXXXXXXXX. Accepts +8801…,
+     * 8801… and 01…, with spaces, dashes, dots or parentheses. Returns null for
+     * anything that isn't a BD mobile number (operator prefixes 013–019).
+     */
+    static normalizePhoneNumber(phone: string): string | null;
     static validatePhoneNumber(phone: string): boolean;
     static formatPhoneNumber(phone: string): string;
     static validateAddress(address: string): boolean;
@@ -282,22 +327,10 @@ declare class PathaoApiService {
     static validateContactNumber(phone: string): boolean;
     static validateStoreAddress(address: string): boolean;
     clearAuth(): void;
-    static fromEnv(options?: {
-        debug?: boolean;
-        circuitBreaker?: CircuitBreakerConfig;
-    }): PathaoApiService;
-    static fromConfig(config: PathaoConfig, options?: {
-        debug?: boolean;
-        circuitBreaker?: CircuitBreakerConfig;
-    }): PathaoApiService;
-    static sandbox(credentials: Omit<PathaoConfig, 'baseURL'>, options?: {
-        debug?: boolean;
-        circuitBreaker?: CircuitBreakerConfig;
-    }): PathaoApiService;
-    static production(credentials: Omit<PathaoConfig, 'baseURL'>, options?: {
-        debug?: boolean;
-        circuitBreaker?: CircuitBreakerConfig;
-    }): PathaoApiService;
+    static fromEnv(options?: PathaoClientOptions): PathaoApiService;
+    static fromConfig(config: PathaoConfig, options?: PathaoClientOptions): PathaoApiService;
+    static sandbox(credentials: Omit<PathaoConfig, 'baseURL'>, options?: PathaoClientOptions): PathaoApiService;
+    static production(credentials: Omit<PathaoConfig, 'baseURL'>, options?: PathaoClientOptions): PathaoApiService;
 }
 
-export { type CircuitBreakerConfig, DeliveryType, ItemType, PathaoApiError, PathaoApiService, type PathaoAreaResponse, type PathaoAuthResponse, type PathaoBulkOrderResponse, type PathaoCityResponse, type PathaoConfig, type PathaoError, type PathaoOrderRequest, type PathaoOrderResponse, type PathaoOrderStatusResponse, type PathaoPriceRequest, type PathaoPriceResponse, type PathaoStore, type PathaoStoreCreateResponse, type PathaoStoreListResponse, type PathaoStoreRequest, type PathaoZoneResponse };
+export { type CircuitBreakerConfig, DeliveryType, ItemType, PathaoApiError, PathaoApiService, type PathaoAreaResponse, type PathaoAuthResponse, type PathaoBulkOrderResponse, type PathaoCityResponse, type PathaoClientOptions, type PathaoConfig, type PathaoError, type PathaoErrorKind, type PathaoOrderRequest, type PathaoOrderResponse, type PathaoOrderStatusResponse, type PathaoPriceRequest, type PathaoPriceResponse, type PathaoStore, type PathaoStoreCreateResponse, type PathaoStoreListResponse, type PathaoStoreRequest, type PathaoZoneResponse };