pathao-merchant-sdk 2.0.2 → 2.1.0

package/README.md

@@ -21,6 +21,7 @@ An **unofficial** TypeScript SDK for integrating with the Pathao Merchant API. T
 - [API Reference](#api-reference)
 - [Examples](#examples)
 - [Error Handling](#error-handling)
+- [Webhooks](#webhooks)
 - [Authentication](#authentication)
 - [Official Documentation](#official-documentation)
 - [Contributing](#contributing)
@@ -37,6 +38,8 @@ An **unofficial** TypeScript SDK for integrating with the Pathao Merchant API. T
 - 🏪 **Store Management** - Create and manage pickup/service points
 - 💰 **Price Calculation** - Get accurate delivery charges before creating orders
 - 🌍 **Location Services** - Access cities, zones, and areas data
+- 🔔 **Webhook Support** - Verify and handle inbound Pathao webhook events
+- ♻️ **Retry & Circuit Breaker** - Automatic retry with backoff, circuit breaker for resilience
 - ⚡ **Built with Axios** - Reliable HTTP client with request/response interceptors
 - 🛡️ **Error Handling** - Comprehensive error handling with detailed error messages
 - 📚 **Well Documented** - Extensive documentation and examples
@@ -406,6 +409,166 @@ try {
 }
 ```
 
+## Webhooks
+
+The `pathao-merchant-sdk/webhooks` sub-module handles inbound Pathao webhook events. It has **zero extra runtime dependencies** — only Node.js built-ins (`crypto`, `events`).
+
+> **Note:** Pathao has no official webhook documentation. This implementation is based on reverse-engineering the [`pathao-courier`](https://www.npmjs.com/package/pathao-courier) package. The signature scheme is plain shared-secret equality (no HMAC) via constant-time comparison.
+
+### Installation
+
+The webhooks module is a separate entry point. Import it explicitly:
+
+```typescript
+import {
+  PathaoWebhookHandler,
+  constructEvent,
+  verifySignature,
+  PathaoWebhookEvent,
+} from 'pathao-merchant-sdk/webhooks';
+```
+
+```javascript
+// CommonJS
+const { PathaoWebhookHandler } = require('pathao-merchant-sdk/webhooks');
+```
+
+### Quick verification
+
+```typescript
+import { verifySignature } from 'pathao-merchant-sdk/webhooks';
+
+const isValid = verifySignature(
+  req.headers['x-pathao-signature'],
+  process.env.PATHAO_WEBHOOK_SECRET!,
+);
+```
+
+### Verify + parse in one call
+
+```typescript
+import { constructEvent, PathaoWebhookError } from 'pathao-merchant-sdk/webhooks';
+
+app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
+  try {
+    const payload = constructEvent(
+      req.body,                               // raw Buffer — do NOT pre-parse
+      req.headers,
+      process.env.PATHAO_WEBHOOK_SECRET!,
+    );
+    console.log('Event:', payload.event, payload.data);
+    res.sendStatus(200);
+  } catch (err) {
+    if (err instanceof PathaoWebhookError) {
+      res.status(400).send(err.message);
+    } else {
+      res.sendStatus(500);
+    }
+  }
+});
+```
+
+### Express middleware
+
+```typescript
+import { PathaoWebhookHandler, PathaoWebhookEvent } from 'pathao-merchant-sdk/webhooks';
+
+const handler = new PathaoWebhookHandler(process.env.PATHAO_WEBHOOK_SECRET!);
+
+// Listen for specific events (fully typed payload)
+handler.on(PathaoWebhookEvent.ORDER_DELIVERED, (payload) => {
+  console.log('Delivered:', payload.consignment_id);
+});
+
+handler.on(PathaoWebhookEvent.ORDER_CANCELLED, (payload) => {
+  console.log('Cancelled:', payload.consignment_id, payload.reason);
+});
+
+// Catch all events
+handler.on('webhook', (payload) => {
+  console.log('Any event:', payload.event, payload.data);
+});
+
+// Handle errors (invalid signature, bad JSON, etc.)
+handler.on('error', (err) => {
+  console.error('Webhook error:', err.message);
+});
+
+// Mount — must use express.raw() BEFORE this middleware
+app.post(
+  '/webhook/pathao',
+  express.raw({ type: 'application/json' }),
+  handler.expressMiddleware(),
+);
+
+// Access the parsed payload downstream
+app.post('/webhook/pathao', express.raw({ type: 'application/json' }), handler.expressMiddleware(), (req, res) => {
+  console.log(req.pathaoWebhook); // typed PathaoWebhookPayload
+  res.sendStatus(200);
+});
+```
+
+### Generic (non-Express) middleware
+
+```typescript
+const handler = new PathaoWebhookHandler(process.env.PATHAO_WEBHOOK_SECRET!);
+const middleware = handler.middleware();
+
+// Returns { payload, error } — never rejects
+const { payload, error } = await middleware(rawBody, headers);
+if (error) {
+  console.error('Bad webhook:', error.message);
+} else {
+  console.log('Event:', payload!.event);
+}
+```
+
+### Supported event types
+
+| Event constant | Event string |
+|---|---|
+| `ORDER_CREATED` | `order.created` |
+| `ORDER_ACCEPTED` | `order.accepted` |
+| `ORDER_PICKUP_REQUESTED` | `order.pickup_requested` |
+| `ORDER_PICKED` | `order.picked` |
+| `ORDER_IN_TRANSIT` | `order.in_transit` |
+| `ORDER_DELIVERED` | `order.delivered` |
+| `ORDER_CANCELLED` | `order.cancelled` |
+| `ORDER_HOLD` | `order.hold` |
+| `ORDER_RETURN_REQUESTED` | `order.return_requested` |
+| `ORDER_RETURN_PICKUP_REQUESTED` | `order.return_pickup_requested` |
+| `ORDER_RETURN_PICKED` | `order.return_picked` |
+| `ORDER_RETURN_IN_TRANSIT` | `order.return_in_transit` |
+| `ORDER_PARTIAL_DELIVERED` | `order.partial_delivered` |
+| `ORDER_DELIVERY_FAILED` | `order.delivery_failed` |
+| `ORDER_ON_HOLD` | `order.on_hold` |
+| `ORDER_PAID` | `order.paid` |
+| `ORDER_PAID_RETURN` | `order.paid_return` |
+| `ORDER_RETURNED` | `order.returned` |
+| `ORDER_EXCHANGED` | `order.exchanged` |
+| `STORE_CREATED` | `store.created` |
+| `STORE_UPDATED` | `store.updated` |
+
+### TypeScript types
+
+All event payloads are fully typed. Access them via `WebhookEventPayloadMap`:
+
+```typescript
+import type {
+  WebhookEventPayloadMap,
+  PathaoWebhookEvent,
+  OrderDeliveredPayload,
+} from 'pathao-merchant-sdk/webhooks';
+
+// Explicit payload type
+const handler = (payload: OrderDeliveredPayload) => {
+  console.log(payload.consignment_id, payload.amount_to_collect);
+};
+
+// Via mapped type
+type DeliveredPayload = WebhookEventPayloadMap[PathaoWebhookEvent.ORDER_DELIVERED];
+```
+
 ## Authentication
 
 The SDK automatically handles OAuth2 authentication and token refresh. You only need to provide your credentials once during initialization:
@@ -511,6 +674,28 @@ This is an **unofficial** SDK and is not affiliated with or endorsed by Pathao.
 
 ## Changelog
 
+### 2.1.0
+- Added webhook support via `pathao-merchant-sdk/webhooks` sub-path
+- `PathaoWebhookHandler` — EventEmitter with typed `on()` overloads for all 21 event types
+- `constructEvent()` and `verifySignature()` standalone helpers
+- Express middleware and generic async middleware
+- Constant-time signature comparison via `crypto.timingSafeEqual`
+- Fixed case-insensitive header lookup for `X-PATHAO-Signature`
+
+### 2.0.x
+- Added retry logic: 429 reads `Retry-After`, 5xx exponential backoff (max 2 retries)
+- Added circuit breaker: throws `PathaoApiError` (code 503) when open
+- Added `sandbox()` and `production()` named constructors
+- Deferred config validation to first API call
+- HTTPS-only enforcement in `validateConfiguration()`
+- Auth token redacted as `Bearer [REDACTED]` in debug logs
+- Added `User-Agent: pathao-merchant-sdk node/<version>` header
+- `getStores()` accepts optional `page` parameter
+- `validateContactNumber` requires `startsWith('01')`
+- `is_active` and `cod_enabled` typed as `0 | 1`
+- Fixed shell injection in `scripts/release.js` (replaced `execSync` with `spawnSync`)
+- CI/CD: replaced deprecated actions, added version-existence check before publish
+
 ### 1.0.0
 - Initial release
 - Complete Pathao API integration

package/dist/index.d.mts

@@ -65,7 +65,7 @@ interface PathaoStore {
     store_id: number;
     store_name: string;
     store_address: string;
-    is_active: number;
+    is_active: 0 | 1;
     city_id: number;
     zone_id: number;
     hub_id: number;
@@ -107,7 +107,7 @@ interface PathaoPriceResponse {
         discount: number;
         promo_discount: number;
         plan_id: number;
-        cod_enabled: number;
+        cod_enabled: 0 | 1;
         cod_percentage: number;
         additional_charge: number;
         final_price: number;
@@ -176,14 +176,27 @@ interface PathaoError {
     errors?: Record<string, string[]>;
     validation?: Record<string, string[]>;
 }
+/**
+ * Delivery type codes defined by the Pathao API.
+ * Values correspond to Pathao's internal delivery_type IDs.
+ * @see https://developers.pathao.com - Order Creation endpoint
+ */
 declare enum DeliveryType {
+    /** Standard delivery (API value: 48) */
     NORMAL = 48,
+    /** Same-day on-demand delivery (API value: 12) */
     ON_DEMAND = 12
 }
 declare enum ItemType {
     DOCUMENT = 1,
     PARCEL = 2
 }
+interface PathaoBulkOrderResponse {
+    message: string;
+    type: string;
+    code: number;
+    data: boolean;
+}
 
 /**
  * Pathao Merchant API Service (Unofficial SDK)
@@ -233,7 +246,6 @@ declare class PathaoApiService {
     private config;
     private isAuthenticating;
     private authPromise;
-    private requestQueue;
     private hasValidated;
     private debug;
     private circuitBreaker;
@@ -244,26 +256,21 @@ declare class PathaoApiService {
     private validateConfiguration;
     private ensureAuthenticated;
     private performAuthentication;
-    private processRequestQueue;
     private authenticate;
     private refreshAccessToken;
     private getErrorMessage;
     private toPathaoApiError;
     private handleCircuitBreaker;
+    private delay;
     createOrder(orderData: PathaoOrderRequest): Promise<PathaoOrderResponse>;
     createStore(storeData: PathaoStoreRequest): Promise<PathaoStoreCreateResponse>;
-    getStores(): Promise<PathaoStoreListResponse>;
+    getStores(page?: number): Promise<PathaoStoreListResponse>;
     calculatePrice(priceData: PathaoPriceRequest): Promise<PathaoPriceResponse>;
     getCities(): Promise<PathaoCityResponse>;
     getZones(cityId: number): Promise<PathaoZoneResponse>;
     getAreas(zoneId: number): Promise<PathaoAreaResponse>;
     getOrderStatus(consignmentId: string): Promise<PathaoOrderStatusResponse>;
-    createBulkOrder(orders: PathaoOrderRequest[]): Promise<{
-        message: string;
-        type: string;
-        code: number;
-        data: boolean;
-    }>;
+    createBulkOrder(orders: PathaoOrderRequest[]): Promise<PathaoBulkOrderResponse>;
     static validatePhoneNumber(phone: string): boolean;
     static formatPhoneNumber(phone: string): string;
     static validateAddress(address: string): boolean;
@@ -282,6 +289,14 @@ declare class PathaoApiService {
         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;
 }
 
-export { DeliveryType, ItemType, PathaoApiError, PathaoApiService, type PathaoAreaResponse, type PathaoAuthResponse, 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 PathaoConfig, type PathaoError, 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

@@ -65,7 +65,7 @@ interface PathaoStore {
     store_id: number;
     store_name: string;
     store_address: string;
-    is_active: number;
+    is_active: 0 | 1;
     city_id: number;
     zone_id: number;
     hub_id: number;
@@ -107,7 +107,7 @@ interface PathaoPriceResponse {
         discount: number;
         promo_discount: number;
         plan_id: number;
-        cod_enabled: number;
+        cod_enabled: 0 | 1;
         cod_percentage: number;
         additional_charge: number;
         final_price: number;
@@ -176,14 +176,27 @@ interface PathaoError {
     errors?: Record<string, string[]>;
     validation?: Record<string, string[]>;
 }
+/**
+ * Delivery type codes defined by the Pathao API.
+ * Values correspond to Pathao's internal delivery_type IDs.
+ * @see https://developers.pathao.com - Order Creation endpoint
+ */
 declare enum DeliveryType {
+    /** Standard delivery (API value: 48) */
     NORMAL = 48,
+    /** Same-day on-demand delivery (API value: 12) */
     ON_DEMAND = 12
 }
 declare enum ItemType {
     DOCUMENT = 1,
     PARCEL = 2
 }
+interface PathaoBulkOrderResponse {
+    message: string;
+    type: string;
+    code: number;
+    data: boolean;
+}
 
 /**
  * Pathao Merchant API Service (Unofficial SDK)
@@ -233,7 +246,6 @@ declare class PathaoApiService {
     private config;
     private isAuthenticating;
     private authPromise;
-    private requestQueue;
     private hasValidated;
     private debug;
     private circuitBreaker;
@@ -244,26 +256,21 @@ declare class PathaoApiService {
     private validateConfiguration;
     private ensureAuthenticated;
     private performAuthentication;
-    private processRequestQueue;
     private authenticate;
     private refreshAccessToken;
     private getErrorMessage;
     private toPathaoApiError;
     private handleCircuitBreaker;
+    private delay;
     createOrder(orderData: PathaoOrderRequest): Promise<PathaoOrderResponse>;
     createStore(storeData: PathaoStoreRequest): Promise<PathaoStoreCreateResponse>;
-    getStores(): Promise<PathaoStoreListResponse>;
+    getStores(page?: number): Promise<PathaoStoreListResponse>;
     calculatePrice(priceData: PathaoPriceRequest): Promise<PathaoPriceResponse>;
     getCities(): Promise<PathaoCityResponse>;
     getZones(cityId: number): Promise<PathaoZoneResponse>;
     getAreas(zoneId: number): Promise<PathaoAreaResponse>;
     getOrderStatus(consignmentId: string): Promise<PathaoOrderStatusResponse>;
-    createBulkOrder(orders: PathaoOrderRequest[]): Promise<{
-        message: string;
-        type: string;
-        code: number;
-        data: boolean;
-    }>;
+    createBulkOrder(orders: PathaoOrderRequest[]): Promise<PathaoBulkOrderResponse>;
     static validatePhoneNumber(phone: string): boolean;
     static formatPhoneNumber(phone: string): string;
     static validateAddress(address: string): boolean;
@@ -282,6 +289,14 @@ declare class PathaoApiService {
         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;
 }
 
-export { DeliveryType, ItemType, PathaoApiError, PathaoApiService, type PathaoAreaResponse, type PathaoAuthResponse, 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 PathaoConfig, type PathaoError, type PathaoOrderRequest, type PathaoOrderResponse, type PathaoOrderStatusResponse, type PathaoPriceRequest, type PathaoPriceResponse, type PathaoStore, type PathaoStoreCreateResponse, type PathaoStoreListResponse, type PathaoStoreRequest, type PathaoZoneResponse };

package/dist/index.js

@@ -26,10 +26,11 @@ var PathaoApiService = class _PathaoApiService {
     this.tokenExpiry = null;
     this.isAuthenticating = false;
     this.authPromise = null;
-    this.requestQueue = [];
     this.hasValidated = false;
     this.debug = false;
-    const timeout = config.timeout || parseInt(process.env.PATHAO_TIMEOUT || "30000", 10);
+    const parsedTimeout = parseInt(process.env.PATHAO_TIMEOUT || "", 10);
+    const envTimeout = Number.isNaN(parsedTimeout) || parsedTimeout <= 0 ? 3e4 : parsedTimeout;
+    const timeout = config.timeout ?? envTimeout;
     this.config = {
       baseURL: config.baseURL || process.env.PATHAO_BASE_URL || "",
       timeout,
@@ -51,7 +52,8 @@ var PathaoApiService = class _PathaoApiService {
       timeout: this.config.timeout,
       headers: {
         "Content-Type": "application/json",
-        Accept: "application/json"
+        Accept: "application/json",
+        "User-Agent": `pathao-merchant-sdk node/${process.version}`
       }
     });
     this.pathaoClient.interceptors.request.use(async (config2) => {
@@ -64,8 +66,10 @@ var PathaoApiService = class _PathaoApiService {
         config2.headers.Authorization = `Bearer ${this.accessToken}`;
       }
       if (this.debug) {
+        const safeHeaders = { ...config2.headers };
+        if (safeHeaders["Authorization"]) safeHeaders["Authorization"] = "Bearer [REDACTED]";
         console.log(`[Pathao SDK] ${config2.method?.toUpperCase()} ${config2.url}`, {
-          headers: config2.headers,
+          headers: safeHeaders,
           data: config2.data
         });
       }
@@ -97,6 +101,22 @@ var PathaoApiService = class _PathaoApiService {
             return this.pathaoClient.request(error.config);
           }
         }
+        if (error.response?.status === 429 && error.config && !error.config._rateLimitRetry) {
+          error.config._rateLimitRetry = true;
+          const retryAfterHeader = error.response.headers["retry-after"];
+          const delayMs = retryAfterHeader ? parseInt(retryAfterHeader, 10) * 1e3 : 1e3;
+          await this.delay(delayMs);
+          return this.pathaoClient.request(error.config);
+        }
+        const status = error.response?.status;
+        if (status !== void 0 && status >= 500 && error.config) {
+          const retryCount = error.config._retryCount ?? 0;
+          if (retryCount < 2) {
+            error.config._retryCount = retryCount + 1;
+            await this.delay(Math.min(500 * 2 ** retryCount, 4e3));
+            return this.pathaoClient.request(error.config);
+          }
+        }
         this.handleCircuitBreaker();
         return Promise.reject(error);
       }
@@ -114,6 +134,12 @@ var PathaoApiService = class _PathaoApiService {
         "Configuration validation failed"
       );
     }
+    if (!this.config.baseURL.startsWith("https://")) {
+      throw this.toPathaoApiError(
+        new Error("Pathao API baseURL must use HTTPS (https://)"),
+        "Configuration validation failed"
+      );
+    }
     if (!this.config.clientId || !this.config.clientSecret || !this.config.username || !this.config.password) {
       throw this.toPathaoApiError(
         new Error(
@@ -130,8 +156,9 @@ var PathaoApiService = class _PathaoApiService {
         this.circuitBreaker.isOpen = false;
         this.circuitBreaker.failures = 0;
       } else {
-        throw new Error(
-          "Circuit breaker is open. Too many authentication failures."
+        throw new PathaoApiError(
+          "Circuit breaker is open. Too many authentication failures. Try again later.",
+          { code: 503 }
         );
       }
     }
@@ -148,7 +175,6 @@ var PathaoApiService = class _PathaoApiService {
     } finally {
       this.isAuthenticating = false;
       this.authPromise = null;
-      this.processRequestQueue();
     }
   }
   async performAuthentication() {
@@ -162,16 +188,6 @@ var PathaoApiService = class _PathaoApiService {
     }
     await this.authenticate();
   }
-  processRequestQueue() {
-    const queue = [...this.requestQueue];
-    this.requestQueue = [];
-    queue.forEach(({ resolve }) => {
-      try {
-        resolve();
-      } catch (error) {
-      }
-    });
-  }
   async authenticate() {
     try {
       const response = await this.pathaoClient.post(
@@ -195,9 +211,6 @@ var PathaoApiService = class _PathaoApiService {
     }
   }
   async refreshAccessToken() {
-    if (!this.refreshToken) {
-      throw new Error("No refresh token available");
-    }
     try {
       const response = await this.pathaoClient.post(
         "/aladdin/api/v1/issue-token",
@@ -226,14 +239,16 @@ var PathaoApiService = class _PathaoApiService {
       }
       return error.message;
     }
-    return error.message || "Unknown error";
+    if (error instanceof Error) return error.message;
+    return "Unknown error";
   }
   toPathaoApiError(error, context) {
     if (error instanceof PathaoApiError) {
       return error;
     }
     const messageFallback = this.getErrorMessage(error);
-    const axiosLike = error instanceof axios.AxiosError ? error : typeof error === "object" && error && "response" in error ? error : null;
+    const hasResponse = (e) => typeof e === "object" && e !== null && "response" in e;
+    const axiosLike = error instanceof axios.AxiosError ? error : hasResponse(error) ? error : null;
     if (axiosLike) {
       const pathaoError = axiosLike.response?.data;
       return new PathaoApiError(
@@ -257,6 +272,9 @@ var PathaoApiService = class _PathaoApiService {
       this.circuitBreaker.isOpen = true;
     }
   }
+  delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
   // Official Pathao API: Create Order
   async createOrder(orderData) {
     try {
@@ -282,10 +300,11 @@ var PathaoApiService = class _PathaoApiService {
     }
   }
   // Official Pathao API: Get Store List
-  async getStores() {
+  async getStores(page) {
     try {
       const response = await this.pathaoClient.get(
-        "/aladdin/api/v1/stores"
+        "/aladdin/api/v1/stores",
+        page !== void 0 ? { params: { page } } : void 0
       );
       return response.data;
     } catch (error) {
@@ -341,7 +360,7 @@ var PathaoApiService = class _PathaoApiService {
   async getOrderStatus(consignmentId) {
     try {
       const response = await this.pathaoClient.get(
-        `/aladdin/api/v1/orders/${consignmentId}/info`
+        `/aladdin/api/v1/orders/${encodeURIComponent(consignmentId)}/info`
       );
       return response.data;
     } catch (error) {
@@ -351,7 +370,10 @@ var PathaoApiService = class _PathaoApiService {
   // Official Pathao API: Create Bulk Order
   async createBulkOrder(orders) {
     try {
-      const response = await this.pathaoClient.post("/aladdin/api/v1/orders/bulk", { orders });
+      const response = await this.pathaoClient.post(
+        "/aladdin/api/v1/orders/bulk",
+        { orders }
+      );
       return response.data;
     } catch (error) {
       throw this.toPathaoApiError(error, "Failed to create bulk Pathao orders");
@@ -399,7 +421,7 @@ var PathaoApiService = class _PathaoApiService {
   // Helper method to validate contact number
   static validateContactNumber(phone) {
     const cleanPhone = phone.replace(/\D/g, "");
-    return cleanPhone.length === 11;
+    return cleanPhone.length === 11 && cleanPhone.startsWith("01");
   }
   // Helper method to validate store address
   static validateStoreAddress(address) {
@@ -413,7 +435,6 @@ var PathaoApiService = class _PathaoApiService {
     this.tokenExpiry = null;
     this.isAuthenticating = false;
     this.authPromise = null;
-    this.requestQueue = [];
     this.circuitBreaker.failures = 0;
     this.circuitBreaker.isOpen = false;
     this.circuitBreaker.lastFailureTime = 0;
@@ -433,6 +454,20 @@ var PathaoApiService = class _PathaoApiService {
   static fromConfig(config, options) {
     return new _PathaoApiService(config, options);
   }
+  // Named constructor for sandbox environment
+  static sandbox(credentials, options) {
+    return new _PathaoApiService(
+      { ...credentials, baseURL: "https://courier-api-sandbox.pathao.com" },
+      options
+    );
+  }
+  // Named constructor for production environment
+  static production(credentials, options) {
+    return new _PathaoApiService(
+      { ...credentials, baseURL: "https://api-hermes.pathao.com" },
+      options
+    );
+  }
 };
 
 // src/types.ts