pathao-merchant-sdk 2.0.0 → 2.0.2

package/CHANGELOG.md

@@ -13,6 +13,38 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.0.2] - 2025-12-08
+
+### Added
+- **Factory methods**: `PathaoApiService.fromEnv()` and `PathaoApiService.fromConfig()` for convenient initialization patterns
+- **Debug logging**: Optional `debug` flag in constructor options to log all HTTP requests and responses
+- **Configurable circuit breaker**: `circuitBreaker` option to customize failure threshold and timeout
+- **Comprehensive error handling examples** in README with `PathaoApiError` usage patterns
+- **Advanced options documentation** for factory methods and configuration
+
+### Changed
+- **Breaking**: Deferred configuration validation to first API call instead of constructor throw. SDK now initializes successfully even without credentials, and throws `PathaoApiError` when attempting an API call with missing config.
+- Removed config duplication in constructor (axios create config now uses resolved config values).
+- Constructor now accepts optional `options` parameter: `new PathaoApiService(config, { debug?, circuitBreaker? })`
+- Constructor no longer throws upfront, allowing graceful error handling at first API usage.
+
+### Fixed
+- `ResolvedPathaoConfig` internal type ensures `timeout` is always a number.
+- Tests updated to reflect deferred validation behavior.
+- Circuit breaker now properly resets on successful requests and maintains configurable thresholds.
+
+### Verified
+- `npm test` passes with 22/22 tests.
+- Build succeeds (CJS/ESM/DTS).
+
+## [2.0.1] - 2025-12-05
+
+### Changed
+- Added `PathaoApiError` with structured fields (`status`, `code`, `type`, `errors`, `validation`, `responseData`) and updated all SDK methods to throw it.
+
+### Verified
+- `npm test` (jest) passes.
+
 ## [1.2.0] - 2024-12-05
 
 ### Fixed

package/README.md

@@ -164,6 +164,56 @@ const pathao = new PathaoApiService({
 });
 ```
 
+#### Factory Methods
+
+The SDK provides convenient factory methods for common initialization patterns:
+
+```typescript
+// Create from environment variables
+const pathao = PathaoApiService.fromEnv();
+
+// Create from environment with additional options
+const pathao = PathaoApiService.fromEnv({
+  debug: true, // Enable debug logging
+  circuitBreaker: {
+    threshold: 10,    // Number of failures before opening circuit (default: 5)
+    timeout: 120000   // Timeout before attempting to close circuit (default: 60000ms)
+  }
+});
+
+// Create from explicit config
+const pathao = PathaoApiService.fromConfig({
+  baseURL: 'https://api-hermes.pathao.com',
+  clientId: 'client-id',
+  clientSecret: 'client-secret',
+  username: 'username',
+  password: 'password',
+  timeout: 5000
+}, {
+  debug: true,
+  circuitBreaker: { threshold: 8 }
+});
+```
+
+#### Advanced Options
+
+```typescript
+const pathao = new PathaoApiService(config, {
+  debug: false,           // Enable detailed debug logging (default: false)
+  circuitBreaker: {
+    threshold: 5,         // Failures before opening circuit (default: 5)
+    timeout: 60000        // Wait time before retry (default: 60000ms = 1 min)
+  }
+});
+```
+
+When `debug` is enabled, the SDK logs all HTTP requests and responses:
+
+```
+[Pathao SDK] GET /aladdin/api/v1/stores { headers: {...}, data: {...} }
+[Pathao SDK] Response 200 { url: '...', data: {...} }
+```
+
 ### Order Management
 
 #### Create Order
@@ -297,17 +347,61 @@ enum ItemType {
 
 ## Error Handling
 
-The SDK provides comprehensive error handling with detailed error messages:
+The SDK provides comprehensive error handling through the `PathaoApiError` class, which extends Error with additional properties for detailed error information:
 
 ```typescript
+import { PathaoApiService, PathaoApiError } from 'pathao-merchant-sdk';
+
+const pathao = new PathaoApiService({
+  clientId: process.env.PATHAO_CLIENT_ID,
+  clientSecret: process.env.PATHAO_CLIENT_SECRET,
+  username: process.env.PATHAO_USERNAME,
+  password: process.env.PATHAO_PASSWORD
+});
+
 try {
   const order = await pathao.createOrder(orderData);
+  console.log('Order created:', order.data.consignment_id);
+} catch (error) {
+  // Check if it's a PathaoApiError (structured error from Pathao API)
+  if (error instanceof PathaoApiError) {
+    console.error('Pathao API Error:', {
+      status: error.status,        // HTTP status code
+      code: error.code,            // Pathao error code
+      type: error.type,            // Error type (e.g., 'ValidationException')
+      message: error.message,      // Error message
+      errors: error.errors,        // Field-level errors
+      validation: error.validation // Validation errors
+    });
+  } else {
+    console.error('Unexpected error:', error.message);
+  }
+}
+```
+
+### Error Properties
+
+- **status**: HTTP status code (e.g., 400, 401, 422)
+- **code**: Pathao API error code for programmatic handling
+- **type**: Error type string (e.g., 'ValidationException', 'AuthenticationException')
+- **errors**: Object with field-level error messages
+- **validation**: Object with validation error messages
+- **message**: Human-readable error message
+
+### Configuration Validation
+
+Configuration validation is deferred until the first API call to allow gradual setup:
+
+```typescript
+// This won't throw immediately
+const pathao = new PathaoApiService({});
+
+// This will throw PathaoApiError if credentials are missing
+try {
+  await pathao.getStores();
 } catch (error) {
-  console.error('Order creation failed:', error.message);
-  
-  // Check if it's a Pathao API error
-  if (error.response?.data) {
-    console.error('API Error:', error.response.data);
+  if (error instanceof PathaoApiError) {
+    console.error('Configuration error:', error.validation);
   }
 }
 ```

package/dist/index.d.mts

@@ -205,6 +205,26 @@ declare enum ItemType {
  * - City, zone, and area management
  */
 
+declare class PathaoApiError extends Error {
+    status: number | undefined;
+    code: number | undefined;
+    type: string | undefined;
+    errors: Record<string, string[]> | undefined;
+    validation: Record<string, string[]> | undefined;
+    responseData: unknown;
+    constructor(message: string, options?: {
+        status?: number | undefined;
+        code?: number | undefined;
+        type?: string | undefined;
+        errors?: Record<string, string[]> | undefined;
+        validation?: Record<string, string[]> | undefined;
+        responseData?: unknown;
+    });
+}
+interface CircuitBreakerConfig {
+    threshold?: number;
+    timeout?: number;
+}
 declare class PathaoApiService {
     private pathaoClient;
     private accessToken;
@@ -214,14 +234,21 @@ declare class PathaoApiService {
     private isAuthenticating;
     private authPromise;
     private requestQueue;
+    private hasValidated;
+    private debug;
     private circuitBreaker;
-    constructor(config: PathaoConfig);
+    constructor(config: PathaoConfig, options?: {
+        debug?: boolean;
+        circuitBreaker?: CircuitBreakerConfig;
+    });
+    private validateConfiguration;
     private ensureAuthenticated;
     private performAuthentication;
     private processRequestQueue;
     private authenticate;
     private refreshAccessToken;
     private getErrorMessage;
+    private toPathaoApiError;
     private handleCircuitBreaker;
     createOrder(orderData: PathaoOrderRequest): Promise<PathaoOrderResponse>;
     createStore(storeData: PathaoStoreRequest): Promise<PathaoStoreCreateResponse>;
@@ -247,6 +274,14 @@ 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;
 }
 
-export { DeliveryType, ItemType, 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 { 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 };

package/dist/index.d.ts

@@ -205,6 +205,26 @@ declare enum ItemType {
  * - City, zone, and area management
  */
 
+declare class PathaoApiError extends Error {
+    status: number | undefined;
+    code: number | undefined;
+    type: string | undefined;
+    errors: Record<string, string[]> | undefined;
+    validation: Record<string, string[]> | undefined;
+    responseData: unknown;
+    constructor(message: string, options?: {
+        status?: number | undefined;
+        code?: number | undefined;
+        type?: string | undefined;
+        errors?: Record<string, string[]> | undefined;
+        validation?: Record<string, string[]> | undefined;
+        responseData?: unknown;
+    });
+}
+interface CircuitBreakerConfig {
+    threshold?: number;
+    timeout?: number;
+}
 declare class PathaoApiService {
     private pathaoClient;
     private accessToken;
@@ -214,14 +234,21 @@ declare class PathaoApiService {
     private isAuthenticating;
     private authPromise;
     private requestQueue;
+    private hasValidated;
+    private debug;
     private circuitBreaker;
-    constructor(config: PathaoConfig);
+    constructor(config: PathaoConfig, options?: {
+        debug?: boolean;
+        circuitBreaker?: CircuitBreakerConfig;
+    });
+    private validateConfiguration;
     private ensureAuthenticated;
     private performAuthentication;
     private processRequestQueue;
     private authenticate;
     private refreshAccessToken;
     private getErrorMessage;
+    private toPathaoApiError;
     private handleCircuitBreaker;
     createOrder(orderData: PathaoOrderRequest): Promise<PathaoOrderResponse>;
     createStore(storeData: PathaoStoreRequest): Promise<PathaoStoreCreateResponse>;
@@ -247,6 +274,14 @@ 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;
 }
 
-export { DeliveryType, ItemType, 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 { 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 };