@basedone/core 0.1.8 → 0.2.0

package/lib/ecommerce/client/base.ts

@@ -0,0 +1,272 @@
+/**
+ * Base Ecommerce API Client
+ * 
+ * This module provides the base HTTP client for the ecommerce API with
+ * authentication, error handling, and retry logic.
+ */
+
+import axios, { AxiosInstance, AxiosRequestConfig, AxiosResponse } from "axios";
+import { parseError, isRetryableError, EcommerceApiError } from "../utils/errors";
+import { retryWithBackoff } from "../utils/helpers";
+
+/**
+ * Client configuration options
+ */
+export interface EcommerceClientConfig {
+  /** Base API URL */
+  baseURL: string;
+  
+  /** Authentication token (Bearer token) */
+  authToken?: string;
+  
+  /** Request timeout in milliseconds */
+  timeout?: number;
+  
+  /** Maximum number of retries for failed requests */
+  maxRetries?: number;
+  
+  /** Base delay for exponential backoff (ms) */
+  retryBaseDelay?: number;
+  
+  /** Custom headers */
+  headers?: Record<string, string>;
+  
+  /** Enable automatic retry on retryable errors */
+  enableRetry?: boolean;
+}
+
+/**
+ * Base ecommerce API client class
+ * 
+ * Provides HTTP methods with authentication, error handling, and retry logic.
+ * 
+ * @example
+ * ```typescript
+ * const client = new BaseEcommerceClient({
+ *   baseURL: "https://api.example.com",
+ *   authToken: "your-auth-token",
+ *   timeout: 30000,
+ *   maxRetries: 3,
+ * });
+ * 
+ * // Make authenticated request
+ * const products = await client.get("/api/marketplace/products");
+ * ```
+ */
+export class BaseEcommerceClient {
+  private axiosInstance: AxiosInstance;
+  private config: Required<Omit<EcommerceClientConfig, "authToken" | "headers">> & {
+    authToken?: string;
+    headers?: Record<string, string>;
+  };
+
+  constructor(config: EcommerceClientConfig) {
+    this.config = {
+      baseURL: config.baseURL,
+      authToken: config.authToken,
+      timeout: config.timeout || 30000,
+      maxRetries: config.maxRetries || 3,
+      retryBaseDelay: config.retryBaseDelay || 1000,
+      headers: config.headers,
+      enableRetry: config.enableRetry !== false,
+    };
+
+    this.axiosInstance = axios.create({
+      baseURL: this.config.baseURL,
+      timeout: this.config.timeout,
+      headers: {
+        "Content-Type": "application/json",
+        ...this.config.headers,
+      },
+    });
+
+    // Request interceptor for authentication
+    this.axiosInstance.interceptors.request.use(
+      (config: any) => {
+        if (this.config.authToken) {
+          config.headers.Authorization = `Bearer ${this.config.authToken}`;
+        }
+        return config;
+      },
+      (error: any) => Promise.reject(error)
+    );
+
+    // Response interceptor for error handling
+    this.axiosInstance.interceptors.response.use(
+      (response: any) => response,
+      (error: any) => Promise.reject(parseError(error))
+    );
+  }
+
+  /**
+   * Update authentication token
+   * 
+   * @param token - New authentication token
+   * 
+   * @example
+   * ```typescript
+   * client.setAuthToken("new-auth-token");
+   * ```
+   */
+  public setAuthToken(token: string): void {
+    this.config.authToken = token;
+  }
+
+  /**
+   * Clear authentication token
+   * 
+   * @example
+   * ```typescript
+   * client.clearAuthToken();
+   * ```
+   */
+  public clearAuthToken(): void {
+    this.config.authToken = undefined;
+  }
+
+  /**
+   * Make a GET request
+   * 
+   * @param url - Request URL
+   * @param config - Axios request config
+   * @returns Response data
+   * 
+   * @example
+   * ```typescript
+   * const products = await client.get("/api/marketplace/products", {
+   *   params: { limit: 20, offset: 0 }
+   * });
+   * ```
+   */
+  public async get<T = any>(url: string, config?: AxiosRequestConfig): Promise<T> {
+    return this.request<T>({ ...config, method: "GET", url });
+  }
+
+  /**
+   * Make a POST request
+   * 
+   * @param url - Request URL
+   * @param data - Request body data
+   * @param config - Axios request config
+   * @returns Response data
+   * 
+   * @example
+   * ```typescript
+   * const order = await client.post("/api/marketplace/orders", {
+   *   items: [{ productId: "123", quantity: 1 }],
+   *   paymentMethod: "USDC_ESCROW"
+   * });
+   * ```
+   */
+  public async post<T = any>(
+    url: string,
+    data?: any,
+    config?: AxiosRequestConfig
+  ): Promise<T> {
+    return this.request<T>({ ...config, method: "POST", url, data });
+  }
+
+  /**
+   * Make a PUT request
+   * 
+   * @param url - Request URL
+   * @param data - Request body data
+   * @param config - Axios request config
+   * @returns Response data
+   * 
+   * @example
+   * ```typescript
+   * const product = await client.put("/api/marketplace/products/123", {
+   *   title: "Updated Product"
+   * });
+   * ```
+   */
+  public async put<T = any>(
+    url: string,
+    data?: any,
+    config?: AxiosRequestConfig
+  ): Promise<T> {
+    return this.request<T>({ ...config, method: "PUT", url, data });
+  }
+
+  /**
+   * Make a PATCH request
+   * 
+   * @param url - Request URL
+   * @param data - Request body data
+   * @param config - Axios request config
+   * @returns Response data
+   * 
+   * @example
+   * ```typescript
+   * const order = await client.patch("/api/marketplace/merchant/orders/123", {
+   *   status: "SHIPPED",
+   *   tracking: { trackingNumber: "123456", carrier: "UPS" }
+   * });
+   * ```
+   */
+  public async patch<T = any>(
+    url: string,
+    data?: any,
+    config?: AxiosRequestConfig
+  ): Promise<T> {
+    return this.request<T>({ ...config, method: "PATCH", url, data });
+  }
+
+  /**
+   * Make a DELETE request
+   * 
+   * @param url - Request URL
+   * @param config - Axios request config
+   * @returns Response data
+   * 
+   * @example
+   * ```typescript
+   * await client.delete("/api/marketplace/products/123");
+   * ```
+   */
+  public async delete<T = any>(url: string, config?: AxiosRequestConfig): Promise<T> {
+    return this.request<T>({ ...config, method: "DELETE", url });
+  }
+
+  /**
+   * Make a request with retry logic
+   * 
+   * @param config - Axios request config
+   * @returns Response data
+   */
+  private async request<T = any>(config: AxiosRequestConfig): Promise<T> {
+    const makeRequest = async (): Promise<AxiosResponse<T>> => {
+      return this.axiosInstance.request<T>(config);
+    };
+
+    if (this.config.enableRetry) {
+      const response = await retryWithBackoff(
+        makeRequest,
+        this.config.maxRetries,
+        this.config.retryBaseDelay,
+        (error: EcommerceApiError) => isRetryableError(error)
+      );
+      return response.data;
+    } else {
+      const response = await makeRequest();
+      return response.data;
+    }
+  }
+
+  /**
+   * Get the underlying axios instance
+   * 
+   * @returns Axios instance
+   * 
+   * @example
+   * ```typescript
+   * const axios = client.getAxiosInstance();
+   * // Use axios directly for advanced use cases
+   * ```
+   */
+  public getAxiosInstance(): AxiosInstance {
+    return this.axiosInstance;
+  }
+}
+