@basedone/core 0.1.10 → 0.2.1

package/dist/ecommerce.js

@@ -0,0 +1,2135 @@
+'use strict';
+
+var axios = require('axios');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var axios__default = /*#__PURE__*/_interopDefault(axios);
+
+// lib/ecommerce/client/base.ts
+
+// lib/ecommerce/utils/errors.ts
+var EcommerceApiError = class _EcommerceApiError extends Error {
+  constructor(message, statusCode, data, isNetworkError = false, isTimeoutError = false) {
+    super(message);
+    this.name = "EcommerceApiError";
+    this.statusCode = statusCode;
+    this.data = data;
+    this.isNetworkError = isNetworkError;
+    this.isTimeoutError = isTimeoutError;
+    this.isAuthError = statusCode === 401 || statusCode === 403;
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, _EcommerceApiError);
+    }
+  }
+};
+function parseError(error) {
+  if (error.code === "ECONNABORTED" || error.code === "ETIMEDOUT") {
+    return new EcommerceApiError(
+      "Request timeout",
+      void 0,
+      void 0,
+      false,
+      true
+    );
+  }
+  if (error.code === "ERR_NETWORK" || !error.response) {
+    return new EcommerceApiError(
+      error.message || "Network error",
+      void 0,
+      void 0,
+      true,
+      false
+    );
+  }
+  const response = error.response;
+  const statusCode = response?.status;
+  const data = response?.data;
+  const message = data?.error || data?.message || error.message || `API error (${statusCode})`;
+  return new EcommerceApiError(message, statusCode, data);
+}
+function isRetryableError(error) {
+  if (error.isNetworkError) {
+    return true;
+  }
+  if (error.isTimeoutError) {
+    return true;
+  }
+  if (error.statusCode && error.statusCode >= 500) {
+    return true;
+  }
+  if (error.statusCode === 429) {
+    return true;
+  }
+  return false;
+}
+
+// lib/ecommerce/utils/helpers.ts
+function buildQueryString(params) {
+  const searchParams = new URLSearchParams();
+  Object.entries(params).forEach(([key, value]) => {
+    if (value !== void 0 && value !== null) {
+      if (Array.isArray(value)) {
+        searchParams.append(key, value.join(","));
+      } else {
+        searchParams.append(key, String(value));
+      }
+    }
+  });
+  const queryString = searchParams.toString();
+  return queryString ? `?${queryString}` : "";
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function getBackoffDelay(attempt, baseDelay = 1e3) {
+  return Math.min(baseDelay * Math.pow(2, attempt), 3e4);
+}
+async function retryWithBackoff(fn, maxRetries = 3, baseDelay = 1e3, shouldRetry) {
+  let lastError;
+  for (let attempt = 0; attempt <= maxRetries; attempt++) {
+    try {
+      return await fn();
+    } catch (error) {
+      lastError = error;
+      if (attempt < maxRetries && (!shouldRetry || shouldRetry(error))) {
+        const delay = getBackoffDelay(attempt, baseDelay);
+        await sleep(delay);
+        continue;
+      }
+      throw error;
+    }
+  }
+  throw lastError;
+}
+function formatPrice(price, decimals = 2) {
+  const num = typeof price === "string" ? parseFloat(price) : price;
+  return num.toFixed(decimals);
+}
+function isValidEmail(email) {
+  const emailRegex = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
+  return emailRegex.test(email);
+}
+function isValidAddress(address) {
+  return /^0x[a-fA-F0-9]{40}$/.test(address);
+}
+function truncateAddress(address, start = 6, end = 4) {
+  if (!address || address.length < start + end) {
+    return address;
+  }
+  return `${address.slice(0, start)}...${address.slice(-end)}`;
+}
+function calculateDiscountAmount(price, discountType, discountValue) {
+  if (discountType === "PERCENTAGE") {
+    return price * discountValue / 100;
+  }
+  return Math.min(discountValue, price);
+}
+function calculateFinalPrice(price, discountType, discountValue) {
+  const discountAmount = calculateDiscountAmount(price, discountType, discountValue);
+  return Math.max(0, price - discountAmount);
+}
+
+// lib/ecommerce/client/base.ts
+var BaseEcommerceClient = class {
+  constructor(config) {
+    this.config = {
+      baseURL: config.baseURL,
+      authToken: config.authToken,
+      timeout: config.timeout || 3e4,
+      maxRetries: config.maxRetries || 3,
+      retryBaseDelay: config.retryBaseDelay || 1e3,
+      headers: config.headers,
+      enableRetry: config.enableRetry !== false
+    };
+    this.axiosInstance = axios__default.default.create({
+      baseURL: this.config.baseURL,
+      timeout: this.config.timeout,
+      headers: {
+        "Content-Type": "application/json",
+        ...this.config.headers
+      }
+    });
+    this.axiosInstance.interceptors.request.use(
+      (config2) => {
+        if (this.config.authToken) {
+          config2.headers.Authorization = `Bearer ${this.config.authToken}`;
+        }
+        return config2;
+      },
+      (error) => Promise.reject(error)
+    );
+    this.axiosInstance.interceptors.response.use(
+      (response) => response,
+      (error) => Promise.reject(parseError(error))
+    );
+  }
+  /**
+   * Update authentication token
+   * 
+   * @param token - New authentication token
+   * 
+   * @example
+   * ```typescript
+   * client.setAuthToken("new-auth-token");
+   * ```
+   */
+  setAuthToken(token) {
+    this.config.authToken = token;
+  }
+  /**
+   * Clear authentication token
+   * 
+   * @example
+   * ```typescript
+   * client.clearAuthToken();
+   * ```
+   */
+  clearAuthToken() {
+    this.config.authToken = void 0;
+  }
+  /**
+   * 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 }
+   * });
+   * ```
+   */
+  async get(url, config) {
+    return this.request({ ...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"
+   * });
+   * ```
+   */
+  async post(url, data, config) {
+    return this.request({ ...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"
+   * });
+   * ```
+   */
+  async put(url, data, config) {
+    return this.request({ ...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" }
+   * });
+   * ```
+   */
+  async patch(url, data, config) {
+    return this.request({ ...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");
+   * ```
+   */
+  async delete(url, config) {
+    return this.request({ ...config, method: "DELETE", url });
+  }
+  /**
+   * Make a request with retry logic
+   * 
+   * @param config - Axios request config
+   * @returns Response data
+   */
+  async request(config) {
+    const makeRequest = async () => {
+      return this.axiosInstance.request(config);
+    };
+    if (this.config.enableRetry) {
+      const response = await retryWithBackoff(
+        makeRequest,
+        this.config.maxRetries,
+        this.config.retryBaseDelay,
+        (error) => 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
+   * ```
+   */
+  getAxiosInstance() {
+    return this.axiosInstance;
+  }
+};
+
+// lib/ecommerce/client/customer.ts
+var CustomerEcommerceClient = class extends BaseEcommerceClient {
+  // ============================================================================
+  // Products API
+  // ============================================================================
+  /**
+   * List products with filtering and pagination
+   * 
+   * @param params - Query parameters for filtering
+   * @returns Paginated list of products
+   * 
+   * @example
+   * ```typescript
+   * const products = await client.listProducts({
+   *   limit: 20,
+   *   offset: 0,
+   *   category: "electronics",
+   *   search: "laptop",
+   *   minPrice: 500,
+   *   maxPrice: 2000,
+   *   sortBy: "price_asc"
+   * });
+   * ```
+   */
+  async listProducts(params) {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/products${queryString}`);
+  }
+  /**
+   * Get product details by ID
+   * 
+   * @param productId - Product ID
+   * @returns Product details with merchant info, variants, and reviews
+   * 
+   * @example
+   * ```typescript
+   * const product = await client.getProduct("prod_123");
+   * console.log(product.title, product.priceUSDC);
+   * ```
+   */
+  async getProduct(productId) {
+    return this.get(`/api/marketplace/products/${productId}`);
+  }
+  /**
+   * Track product view (increment view count)
+   * 
+   * @param productId - Product ID
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.trackProductView("prod_123");
+   * ```
+   */
+  async trackProductView(productId) {
+    return this.post(`/api/marketplace/products/${productId}/view`);
+  }
+  /**
+   * Get active automatic discounts for a product
+   * 
+   * @param productId - Product ID
+   * @returns List of applicable discounts
+   * 
+   * @example
+   * ```typescript
+   * const discounts = await client.getProductDiscounts("prod_123");
+   * discounts.discounts.forEach(d => console.log(d.description));
+   * ```
+   */
+  async getProductDiscounts(productId) {
+    return this.get(`/api/marketplace/products/${productId}/discounts`);
+  }
+  // ============================================================================
+  // Orders API
+  // ============================================================================
+  /**
+   * Create order from cart checkout
+   * 
+   * Supports multi-merchant checkout - automatically splits orders by merchant.
+   * 
+   * @param request - Order creation request
+   * @returns Created order(s) with payment instructions
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.createOrder({
+   *   items: [
+   *     { productId: "prod_123", quantity: 2 },
+   *     { productId: "prod_456", quantity: 1, variantId: "var_789" }
+   *   ],
+   *   paymentMethod: "USDC_ESCROW",
+   *   shippingAddress: {
+   *     fullName: "John Doe",
+   *     phone: "+1234567890",
+   *     addressLine1: "123 Main St",
+   *     city: "New York",
+   *     stateProvince: "NY",
+   *     postalCode: "10001",
+   *     country: "US"
+   *   },
+   *   couponCode: "SAVE10"
+   * });
+   * 
+   * // For USDC escrow, deposit to the escrow address
+   * if (result.escrow) {
+   *   console.log("Deposit", result.escrow.amountUSDC, "USDC to", result.escrow.address);
+   * }
+   * ```
+   */
+  async createOrder(request) {
+    return this.post("/api/marketplace/orders", request);
+  }
+  /**
+   * List user's orders
+   * 
+   * @param params - Query parameters for filtering
+   * @returns Paginated list of orders
+   * 
+   * @example
+   * ```typescript
+   * const orders = await client.listOrders({
+   *   limit: 10,
+   *   offset: 0,
+   *   status: "SHIPPED"
+   * });
+   * ```
+   */
+  async listOrders(params) {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/orders${queryString}`);
+  }
+  /**
+   * Get order details by ID
+   * 
+   * @param orderId - Order ID
+   * @returns Order details with items, payment, and shipment info
+   * 
+   * @example
+   * ```typescript
+   * const order = await client.getOrder("ord_123");
+   * console.log(order.order.status, order.order.totalUSDC);
+   * ```
+   */
+  async getOrder(orderId) {
+    return this.get(`/api/marketplace/orders/${orderId}`);
+  }
+  /**
+   * Confirm USDC escrow deposit for order payment
+   * 
+   * Verifies the Hyperliquid transaction and updates order status.
+   * 
+   * @param orderId - Order ID
+   * @returns Confirmation response with transaction hash
+   * 
+   * @example
+   * ```typescript
+   * // After depositing USDC to escrow address
+   * const result = await client.confirmEscrowDeposit("ord_123");
+   * console.log("Payment confirmed:", result.depositTxHash);
+   * ```
+   */
+  async confirmEscrowDeposit(orderId) {
+    return this.post(`/api/marketplace/orders/${orderId}/confirm-escrow-deposit`);
+  }
+  /**
+   * Get order receipt
+   * 
+   * @param orderId - Order ID
+   * @returns Order receipt for download/display
+   * 
+   * @example
+   * ```typescript
+   * const receipt = await client.getOrderReceipt("ord_123");
+   * console.log("Order #", receipt.receipt.orderNumber);
+   * ```
+   */
+  async getOrderReceipt(orderId) {
+    return this.get(`/api/marketplace/orders/${orderId}/receipt`);
+  }
+  // ============================================================================
+  // Reviews API
+  // ============================================================================
+  /**
+   * List reviews for a product
+   * 
+   * @param productId - Product ID
+   * @param params - Query parameters
+   * @returns Paginated list of reviews
+   * 
+   * @example
+   * ```typescript
+   * const reviews = await client.listProductReviews("prod_123", {
+   *   limit: 10,
+   *   sortBy: "highest"
+   * });
+   * ```
+   */
+  async listProductReviews(productId, params) {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/products/${productId}/reviews${queryString}`);
+  }
+  /**
+   * Create a product review
+   * 
+   * Requires authenticated user who has purchased the product.
+   * 
+   * @param productId - Product ID
+   * @param request - Review creation request
+   * @returns Created review
+   * 
+   * @example
+   * ```typescript
+   * const review = await client.createReview("prod_123", {
+   *   rating: 5,
+   *   title: "Great product!",
+   *   comment: "Exactly what I needed. Fast shipping too!"
+   * });
+   * ```
+   */
+  async createReview(productId, request) {
+    return this.post(`/api/marketplace/products/${productId}/reviews`, request);
+  }
+  // ============================================================================
+  // Shipping Addresses API
+  // ============================================================================
+  /**
+   * List saved shipping addresses
+   * 
+   * @returns List of user's saved shipping addresses
+   * 
+   * @example
+   * ```typescript
+   * const addresses = await client.listShippingAddresses();
+   * const defaultAddress = addresses.addresses.find(a => a.isDefault);
+   * ```
+   */
+  async listShippingAddresses() {
+    return this.get("/api/user/shipping-addresses");
+  }
+  /**
+   * Create a new shipping address
+   * 
+   * @param request - Shipping address data
+   * @returns Created address
+   * 
+   * @example
+   * ```typescript
+   * const address = await client.createShippingAddress({
+   *   fullName: "John Doe",
+   *   phone: "+1234567890",
+   *   addressLine1: "123 Main St",
+   *   city: "New York",
+   *   stateProvince: "NY",
+   *   postalCode: "10001",
+   *   country: "US",
+   *   isDefault: true,
+   *   label: "Home"
+   * });
+   * ```
+   */
+  async createShippingAddress(request) {
+    return this.post("/api/user/shipping-addresses", request);
+  }
+  /**
+   * Update a shipping address
+   * 
+   * @param addressId - Address ID
+   * @param request - Updated address data
+   * @returns Updated address
+   * 
+   * @example
+   * ```typescript
+   * const address = await client.updateShippingAddress("addr_123", {
+   *   phone: "+0987654321"
+   * });
+   * ```
+   */
+  async updateShippingAddress(addressId, request) {
+    return this.patch(`/api/user/shipping-addresses/${addressId}`, request);
+  }
+  /**
+   * Delete a shipping address
+   * 
+   * @param addressId - Address ID
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.deleteShippingAddress("addr_123");
+   * ```
+   */
+  async deleteShippingAddress(addressId) {
+    return this.delete(`/api/user/shipping-addresses/${addressId}`);
+  }
+  // ============================================================================
+  // Cart & Discounts API
+  // ============================================================================
+  /**
+   * Calculate automatic discounts for cart items
+   * 
+   * @param request - Cart items
+   * @returns Calculated discounts and totals
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.calculateCartDiscounts({
+   *   items: [
+   *     { productId: "prod_123", quantity: 2 },
+   *     { productId: "prod_456", quantity: 1 }
+   *   ]
+   * });
+   * console.log("Subtotal:", result.subtotal);
+   * console.log("Discount:", result.discountAmount);
+   * console.log("Total:", result.total);
+   * ```
+   */
+  async calculateCartDiscounts(request) {
+    return this.post("/api/marketplace/cart/discounts", request);
+  }
+  /**
+   * Validate a discount code for cart items
+   * 
+   * @param request - Discount code and cart items
+   * @returns Validation result with discount details
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.validateDiscountCode({
+   *   code: "SAVE10",
+   *   items: [
+   *     { productId: "prod_123", quantity: 2 }
+   *   ]
+   * });
+   * 
+   * if (result.valid) {
+   *   console.log("Discount:", result.discount?.discountAmount);
+   * } else {
+   *   console.log("Error:", result.error);
+   * }
+   * ```
+   */
+  async validateDiscountCode(request) {
+    return this.post("/api/marketplace/discounts/validate", request);
+  }
+  // ============================================================================
+  // Tax Calculation API
+  // ============================================================================
+  /**
+   * Calculate tax for cart items based on shipping address
+   * 
+   * @param request - Cart items and shipping address
+   * @returns Tax calculation with breakdown
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.calculateTax({
+   *   items: [
+   *     { productId: "prod_123", quantity: 2 }
+   *   ],
+   *   shippingAddress: {
+   *     country: "US",
+   *     region: "NY",
+   *     postalCode: "10001"
+   *   }
+   * });
+   * console.log("Tax:", result.taxAmount);
+   * console.log("Total:", result.total);
+   * ```
+   */
+  async calculateTax(request) {
+    return this.post("/api/marketplace/tax/calculate", request);
+  }
+  // ============================================================================
+  // Banners API
+  // ============================================================================
+  /**
+   * Get active promotional banners
+   * 
+   * @param params - Query parameters
+   * @returns List of active banners
+   * 
+   * @example
+   * ```typescript
+   * const banners = await client.getActiveBanners({
+   *   type: "HERO",
+   *   merchantId: "merchant_123"
+   * });
+   * ```
+   */
+  async getActiveBanners(params) {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/banners/active${queryString}`);
+  }
+  /**
+   * Track banner impression or click
+   * 
+   * @param bannerId - Banner ID
+   * @param request - Track action (impression or click)
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * // Track impression
+   * await client.trackBanner("banner_123", { action: "impression" });
+   * 
+   * // Track click
+   * await client.trackBanner("banner_123", { action: "click" });
+   * ```
+   */
+  async trackBanner(bannerId, request) {
+    return this.post(`/api/marketplace/banners/${bannerId}/track`, request);
+  }
+  // ============================================================================
+  // Messages API
+  // ============================================================================
+  /**
+   * List messages for customer
+   * 
+   * Returns all conversations grouped by order, where each order represents
+   * a conversation with a merchant.
+   * 
+   * @returns List of conversations with messages and stats
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.listMessages();
+   * console.log("Unread:", result.stats.unread);
+   * result.conversations.forEach(conv => {
+   *   console.log(`Order ${conv.orderNumber}: ${conv.unreadCount} unread`);
+   * });
+   * ```
+   */
+  async listMessages() {
+    return this.get("/api/marketplace/messages");
+  }
+  /**
+   * Get message stats (unread count)
+   * 
+   * Lightweight endpoint for notification badges.
+   * 
+   * @returns Unread message count
+   * 
+   * @example
+   * ```typescript
+   * const stats = await client.getMessageStats();
+   * console.log("Unread messages:", stats.unread);
+   * ```
+   */
+  async getMessageStats() {
+    return this.get("/api/marketplace/messages/stats");
+  }
+  /**
+   * Send a message to a merchant about an order
+   * 
+   * @param request - Message data including orderId, recipientId (merchant user ID), and message
+   * @returns Sent message
+   * 
+   * @example
+   * ```typescript
+   * await client.sendMessage({
+   *   orderId: "ord_123",
+   *   recipientId: "user_merchant_456",
+   *   message: "When will my order ship?"
+   * });
+   * ```
+   */
+  async sendMessage(request) {
+    return this.post("/api/marketplace/messages/send", request);
+  }
+  /**
+   * Mark a message as read
+   * 
+   * @param messageId - Message ID
+   * @returns Updated message
+   * 
+   * @example
+   * ```typescript
+   * await client.markMessageAsRead("msg_123");
+   * ```
+   */
+  async markMessageAsRead(messageId) {
+    return this.patch(`/api/marketplace/messages/${messageId}/read`, {});
+  }
+  // ============================================================================
+  // Flash Sales API
+  // ============================================================================
+  /**
+   * Get active flash sales
+   * 
+   * Returns currently running flash sales with their discounted products.
+   * Includes countdown timer information for UI display.
+   * 
+   * @param params - Query parameters
+   * @returns List of active flash sales with time remaining
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.getActiveFlashSales({ limit: 5 });
+   * 
+   * result.flashSales.forEach(sale => {
+   *   console.log(`${sale.name} - ends at ${sale.endsAt}`);
+   *   sale.items.forEach(item => {
+   *     console.log(`  ${item.product.title}: $${item.salePrice} (${item.discountPercent}% off)`);
+   *   });
+   * });
+   * 
+   * // Use timeRemaining for countdown UI
+   * if (result.timeRemaining) {
+   *   console.log(`Featured sale ends in ${result.timeRemaining.remainingSeconds} seconds`);
+   * }
+   * ```
+   */
+  async getActiveFlashSales(params) {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/flash-sales/active${queryString}`);
+  }
+};
+
+// lib/ecommerce/client/merchant.ts
+var MerchantEcommerceClient = class extends BaseEcommerceClient {
+  // ============================================================================
+  // Profile Management
+  // ============================================================================
+  /**
+   * Get merchant profile
+   * 
+   * @returns Merchant profile
+   * 
+   * @example
+   * ```typescript
+   * const profile = await client.getMerchantProfile();
+   * console.log(profile.merchant.name);
+   * ```
+   */
+  async getMerchantProfile() {
+    return this.get("/api/marketplace/merchant/profile");
+  }
+  /**
+   * Get merchant profile (alias for getMerchantProfile)
+   * 
+   * @returns Merchant profile
+   * 
+   * @example
+   * ```typescript
+   * const profile = await client.getProfile();
+   * console.log(profile.merchant.name);
+   * ```
+   */
+  async getProfile() {
+    return this.getMerchantProfile();
+  }
+  /**
+   * Create or update merchant profile
+   * 
+   * @param request - Profile data
+   * @returns Updated merchant profile
+   * 
+   * @example
+   * ```typescript
+   * const profile = await client.upsertMerchantProfile({
+   *   name: "My Store",
+   *   description: "We sell great products",
+   *   payoutAddress: "0x1234..."
+   * });
+   * ```
+   */
+  async upsertMerchantProfile(request) {
+    return this.post("/api/marketplace/merchant/profile", request);
+  }
+  // ============================================================================
+  // Products Management
+  // ============================================================================
+  /**
+   * List merchant's products
+   * 
+   * @param params - Query parameters
+   * @returns Paginated list of products
+   * 
+   * @example
+   * ```typescript
+   * const products = await client.listMerchantProducts({ limit: 20, offset: 0 });
+   * ```
+   */
+  async listMerchantProducts(params) {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/merchant/products${queryString}`);
+  }
+  /**
+   * Get a single product by ID
+   * 
+   * @param productId - Product ID
+   * @returns Product details
+   * 
+   * @example
+   * ```typescript
+   * const product = await client.getProduct("prod_123");
+   * console.log(product.product?.title, product.product?.priceUSDC);
+   * ```
+   */
+  async getProduct(productId) {
+    return this.get(`/api/marketplace/products/${productId}`);
+  }
+  /**
+   * Create a new product
+   * 
+   * @param request - Product data
+   * @returns Created product
+   * 
+   * @example
+   * ```typescript
+   * const product = await client.createProduct({
+   *   title: "Awesome Product",
+   *   images: ["https://..."],
+   *   priceUSDC: 49.99,
+   *   inventory: 50,
+   *   category: "electronics",
+   *   moq: 1
+   * });
+   * ```
+   */
+  async createProduct(request) {
+    return this.post("/api/marketplace/merchant/products", request);
+  }
+  /**
+   * Update a product
+   * 
+   * @param productId - Product ID
+   * @param request - Updated product data
+   * @returns Updated product
+   * 
+   * @example
+   * ```typescript
+   * const product = await client.updateProduct("prod_123", {
+   *   priceUSDC: 39.99,
+   *   inventory: 75
+   * });
+   * ```
+   */
+  async updateProduct(productId, request) {
+    return this.put(`/api/marketplace/products/${productId}`, request);
+  }
+  /**
+   * Delete a product
+   * 
+   * @param productId - Product ID
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.deleteProduct("prod_123");
+   * ```
+   */
+  async deleteProduct(productId) {
+    return this.delete(`/api/marketplace/products/${productId}`);
+  }
+  /**
+   * Toggle product featured status
+   * 
+   * @param productId - Product ID
+   * @param featured - Featured status
+   * @returns Updated product
+   * 
+   * @example
+   * ```typescript
+   * await client.setProductFeatured("prod_123", true);
+   * ```
+   */
+  async setProductFeatured(productId, featured) {
+    return this.patch(`/api/marketplace/merchant/products/${productId}/featured`, { featured });
+  }
+  /**
+   * List product variants
+   * 
+   * @param productId - Product ID
+   * @returns List of variants
+   * 
+   * @example
+   * ```typescript
+   * const variants = await client.listProductVariants("prod_123");
+   * ```
+   */
+  async listProductVariants(productId) {
+    return this.get(`/api/marketplace/merchant/products/${productId}/variants`);
+  }
+  /**
+   * Create a product variant
+   * 
+   * @param productId - Product ID
+   * @param request - Variant data
+   * @returns Created variant
+   * 
+   * @example
+   * ```typescript
+   * const variant = await client.createProductVariant("prod_123", {
+   *   name: "Large / Red",
+   *   attributes: { size: "L", color: "Red" },
+   *   priceUSDC: 54.99,
+   *   inventory: 20
+   * });
+   * ```
+   */
+  async createProductVariant(productId, request) {
+    return this.post(`/api/marketplace/merchant/products/${productId}/variants`, request);
+  }
+  /**
+   * Get a product variant
+   * 
+   * @param productId - Product ID
+   * @param variantId - Variant ID
+   * @returns Variant details
+   * 
+   * @example
+   * ```typescript
+   * const variant = await client.getProductVariant("prod_123", "var_456");
+   * ```
+   */
+  async getProductVariant(productId, variantId) {
+    return this.get(`/api/marketplace/merchant/products/${productId}/variants/${variantId}`);
+  }
+  /**
+   * Update a product variant
+   * 
+   * @param productId - Product ID
+   * @param variantId - Variant ID
+   * @param request - Updated variant data
+   * @returns Updated variant
+   * 
+   * @example
+   * ```typescript
+   * const variant = await client.updateProductVariant("prod_123", "var_456", {
+   *   inventory: 30
+   * });
+   * ```
+   */
+  async updateProductVariant(productId, variantId, request) {
+    return this.put(`/api/marketplace/merchant/products/${productId}/variants/${variantId}`, request);
+  }
+  /**
+   * Delete a product variant
+   * 
+   * @param productId - Product ID
+   * @param variantId - Variant ID
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.deleteProductVariant("prod_123", "var_456");
+   * ```
+   */
+  async deleteProductVariant(productId, variantId) {
+    return this.delete(`/api/marketplace/merchant/products/${productId}/variants/${variantId}`);
+  }
+  /**
+   * Get product metrics
+   * 
+   * @returns Product performance metrics
+   * 
+   * @example
+   * ```typescript
+   * const metrics = await client.getProductMetrics();
+   * console.log("Total revenue:", metrics.summary.totalRevenue);
+   * ```
+   */
+  async getProductMetrics() {
+    return this.get("/api/marketplace/merchant/products/metrics");
+  }
+  // ============================================================================
+  // Orders Management
+  // ============================================================================
+  /**
+   * List merchant's orders
+   * 
+   * @param params - Query parameters
+   * @returns Paginated list of orders
+   * 
+   * @example
+   * ```typescript
+   * const orders = await client.listMerchantOrders({ limit: 20, offset: 0 });
+   * ```
+   */
+  async listMerchantOrders(params) {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/merchant/orders${queryString}`);
+  }
+  /**
+   * Get order details
+   * 
+   * @param orderId - Order ID
+   * @returns Order details with full information
+   * 
+   * @example
+   * ```typescript
+   * const order = await client.getMerchantOrder("ord_123");
+   * console.log(order.order.status, order.order.items);
+   * ```
+   */
+  async getMerchantOrder(orderId) {
+    return this.get(`/api/marketplace/merchant/orders/${orderId}`);
+  }
+  /**
+   * Update order status
+   * 
+   * @param orderId - Order ID
+   * @param request - Status update request
+   * @returns Updated order
+   * 
+   * @example
+   * ```typescript
+   * // Accept order
+   * await client.updateOrderStatus("ord_123", {
+   *   status: "MERCHANT_ACCEPTED"
+   * });
+   * 
+   * // Mark as shipped
+   * await client.updateOrderStatus("ord_123", {
+   *   status: "SHIPPED",
+   *   tracking: {
+   *     trackingNumber: "1Z999AA10123456784",
+   *     carrier: "UPS"
+   *   }
+   * });
+   * ```
+   */
+  async updateOrderStatus(orderId, request) {
+    return this.patch(`/api/marketplace/merchant/orders/${orderId}`, request);
+  }
+  /**
+   * Create a custom order event
+   * 
+   * @param orderId - Order ID
+   * @param request - Event data
+   * @returns Created event
+   * 
+   * @example
+   * ```typescript
+   * await client.createOrderEvent("ord_123", {
+   *   eventType: "CUSTOM",
+   *   title: "Package delayed",
+   *   description: "Shipment delayed due to weather"
+   * });
+   * ```
+   */
+  async createOrderEvent(orderId, request) {
+    return this.post(`/api/marketplace/merchant/orders/${orderId}/events`, request);
+  }
+  // ============================================================================
+  // Customers Management
+  // ============================================================================
+  /**
+   * List customers with order history and stats
+   * 
+   * @param params - Query parameters
+   * @returns Paginated list of customers
+   * 
+   * @example
+   * ```typescript
+   * const customers = await client.listCustomers({ limit: 50, offset: 0 });
+   * customers.items.forEach(c => {
+   *   console.log(c.username, "Total spent:", c.totalSpent);
+   * });
+   * ```
+   */
+  async listCustomers(params) {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/merchant/customers${queryString}`);
+  }
+  // ============================================================================
+  // Coupons & Discounts Management
+  // ============================================================================
+  /**
+   * List merchant's coupons
+   * 
+   * @returns List of coupons with stats
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.listCoupons();
+   * console.log("Total coupons:", result.stats.total);
+   * console.log("Active:", result.stats.active);
+   * ```
+   */
+  async listCoupons() {
+    return this.get("/api/marketplace/merchant/coupons");
+  }
+  /**
+   * Create a coupon
+   * 
+   * @param request - Coupon data
+   * @returns Created coupon
+   * 
+   * @example
+   * ```typescript
+   * const coupon = await client.createCoupon({
+   *   code: "SAVE20",
+   *   discountType: "PERCENTAGE",
+   *   discountValue: 20,
+   *   startsAt: "2025-01-01T00:00:00Z",
+   *   expiresAt: "2025-12-31T23:59:59Z",
+   *   maxUses: 100
+   * });
+   * ```
+   */
+  async createCoupon(request) {
+    return this.post("/api/marketplace/merchant/coupons", request);
+  }
+  /**
+   * Get coupon details with usage history
+   * 
+   * @param couponId - Coupon ID
+   * @returns Coupon with usages
+   * 
+   * @example
+   * ```typescript
+   * const coupon = await client.getCoupon("coupon_123");
+   * console.log("Used", coupon.coupon.usedCount, "times");
+   * ```
+   */
+  async getCoupon(couponId) {
+    return this.get(`/api/marketplace/merchant/coupons/${couponId}`);
+  }
+  /**
+   * Update a coupon
+   * 
+   * @param couponId - Coupon ID
+   * @param request - Updated coupon data
+   * @returns Updated coupon
+   * 
+   * @example
+   * ```typescript
+   * await client.updateCoupon("coupon_123", {
+   *   isActive: false
+   * });
+   * ```
+   */
+  async updateCoupon(couponId, request) {
+    return this.put(`/api/marketplace/merchant/coupons/${couponId}`, request);
+  }
+  /**
+   * Delete a coupon
+   * 
+   * @param couponId - Coupon ID
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.deleteCoupon("coupon_123");
+   * ```
+   */
+  async deleteCoupon(couponId) {
+    return this.delete(`/api/marketplace/merchant/coupons/${couponId}`);
+  }
+  // ============================================================================
+  // Shipping & Fulfillment
+  // ============================================================================
+  /**
+   * List shipping methods
+   * 
+   * @returns List of shipping methods
+   * 
+   * @example
+   * ```typescript
+   * const methods = await client.listShippingMethods();
+   * ```
+   */
+  async listShippingMethods() {
+    return this.get("/api/marketplace/merchant/shipping/methods");
+  }
+  /**
+   * Create a shipping method
+   * 
+   * @param request - Shipping method data
+   * @returns Created method
+   * 
+   * @example
+   * ```typescript
+   * const method = await client.createShippingMethod({
+   *   name: "Standard Shipping",
+   *   carrier: "USPS",
+   *   estimatedDays: "3-5 business days",
+   *   flatRate: 5.99
+   * });
+   * ```
+   */
+  async createShippingMethod(request) {
+    return this.post("/api/marketplace/merchant/shipping/methods", request);
+  }
+  /**
+   * Update a shipping method
+   * 
+   * @param methodId - Method ID
+   * @param request - Updated method data
+   * @returns Updated method
+   * 
+   * @example
+   * ```typescript
+   * await client.updateShippingMethod("method_123", {
+   *   flatRate: 6.99
+   * });
+   * ```
+   */
+  async updateShippingMethod(methodId, request) {
+    return this.put(`/api/marketplace/merchant/shipping/methods/${methodId}`, request);
+  }
+  /**
+   * Delete a shipping method
+   * 
+   * @param methodId - Method ID
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.deleteShippingMethod("method_123");
+   * ```
+   */
+  async deleteShippingMethod(methodId) {
+    return this.delete(`/api/marketplace/merchant/shipping/methods/${methodId}`);
+  }
+  /**
+   * List shipments
+   * 
+   * @returns List of shipments for merchant's orders
+   * 
+   * @example
+   * ```typescript
+   * const shipments = await client.listShipments();
+   * ```
+   */
+  async listShipments() {
+    return this.get("/api/marketplace/merchant/shipping/shipments");
+  }
+  /**
+   * Update shipment status and tracking
+   * 
+   * @param shipmentId - Shipment ID
+   * @param request - Updated shipment data
+   * @returns Updated shipment
+   * 
+   * @example
+   * ```typescript
+   * await client.updateShipment("ship_123", {
+   *   status: "SHIPPED",
+   *   trackingNumber: "1Z999AA10123456784",
+   *   carrier: "UPS"
+   * });
+   * ```
+   */
+  async updateShipment(shipmentId, request) {
+    return this.patch(`/api/marketplace/merchant/shipping/shipments/${shipmentId}`, request);
+  }
+  // ============================================================================
+  // Returns & Refunds
+  // ============================================================================
+  /**
+   * List returns
+   * 
+   * @returns List of returns for merchant's orders
+   * 
+   * @example
+   * ```typescript
+   * const returns = await client.listReturns();
+   * ```
+   */
+  async listReturns() {
+    return this.get("/api/marketplace/merchant/returns");
+  }
+  /**
+   * Approve a return request
+   * 
+   * @param returnId - Return ID
+   * @returns Updated return
+   * 
+   * @example
+   * ```typescript
+   * await client.approveReturn("return_123");
+   * ```
+   */
+  async approveReturn(returnId) {
+    return this.post(`/api/marketplace/merchant/returns/${returnId}/approve`);
+  }
+  /**
+   * Reject a return request
+   * 
+   * @param returnId - Return ID
+   * @returns Updated return
+   * 
+   * @example
+   * ```typescript
+   * await client.rejectReturn("return_123");
+   * ```
+   */
+  async rejectReturn(returnId) {
+    return this.post(`/api/marketplace/merchant/returns/${returnId}/reject`);
+  }
+  /**
+   * Mark return as received
+   * 
+   * @param returnId - Return ID
+   * @returns Updated return
+   * 
+   * @example
+   * ```typescript
+   * await client.markReturnReceived("return_123");
+   * ```
+   */
+  async markReturnReceived(returnId) {
+    return this.post(`/api/marketplace/merchant/returns/${returnId}/received`);
+  }
+  /**
+   * Process refund for return
+   * 
+   * @param returnId - Return ID
+   * @returns Updated return
+   * 
+   * @example
+   * ```typescript
+   * await client.processRefund("return_123");
+   * ```
+   */
+  async processRefund(returnId) {
+    return this.post(`/api/marketplace/merchant/returns/${returnId}/refunded`);
+  }
+  // ============================================================================
+  // Reviews Management
+  // ============================================================================
+  /**
+   * List reviews for merchant's products
+   * 
+   * @returns List of reviews
+   * 
+   * @example
+   * ```typescript
+   * const reviews = await client.listMerchantReviews();
+   * ```
+   */
+  async listMerchantReviews() {
+    return this.get("/api/marketplace/merchant/reviews");
+  }
+  /**
+   * Respond to a review
+   * 
+   * @param reviewId - Review ID
+   * @param request - Response data
+   * @returns Updated review
+   * 
+   * @example
+   * ```typescript
+   * await client.respondToReview("review_123", {
+   *   merchantResponse: "Thank you for your feedback!"
+   * });
+   * ```
+   */
+  async respondToReview(reviewId, request) {
+    return this.post(`/api/marketplace/merchant/reviews/${reviewId}/respond`, request);
+  }
+  /**
+   * Flag a review as inappropriate
+   * 
+   * @param reviewId - Review ID
+   * @returns Updated review
+   * 
+   * @example
+   * ```typescript
+   * await client.flagReview("review_123");
+   * ```
+   */
+  async flagReview(reviewId) {
+    return this.post(`/api/marketplace/merchant/reviews/${reviewId}/flag`);
+  }
+  // ============================================================================
+  // Messages
+  // ============================================================================
+  /**
+   * List messages/conversations
+   * 
+   * @returns List of conversations grouped by order
+   * 
+   * @example
+   * ```typescript
+   * const messages = await client.listMessages();
+   * console.log("Unread:", messages.stats.unread);
+   * ```
+   */
+  async listMessages() {
+    return this.get("/api/marketplace/merchant/messages");
+  }
+  /**
+   * Send a message to customer
+   * 
+   * @param request - Message data
+   * @returns Sent message
+   * 
+   * @example
+   * ```typescript
+   * await client.sendMessage({
+   *   orderId: "ord_123",
+   *   recipientId: "user_456",
+   *   message: "Your order has been shipped!"
+   * });
+   * ```
+   */
+  async sendMessage(request) {
+    return this.post("/api/marketplace/merchant/messages/send", request);
+  }
+  /**
+   * Mark message as read
+   * 
+   * @param messageId - Message ID
+   * @returns Updated message
+   * 
+   * @example
+   * ```typescript
+   * await client.markMessageRead("msg_123");
+   * ```
+   */
+  async markMessageRead(messageId) {
+    return this.patch(`/api/marketplace/merchant/messages/${messageId}/read`);
+  }
+  // ============================================================================
+  // Media Library
+  // ============================================================================
+  /**
+   * List media assets
+   * 
+   * @param params - Query parameters
+   * @returns Paginated list of media assets
+   * 
+   * @example
+   * ```typescript
+   * const media = await client.listMediaAssets({ limit: 50, offset: 0 });
+   * ```
+   */
+  async listMediaAssets(params) {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/merchant/media${queryString}`);
+  }
+  /**
+   * Upload a media asset
+   * 
+   * @param file - File to upload (max 10MB, images only)
+   * @returns Uploaded asset
+   * 
+   * @example
+   * ```typescript
+   * const formData = new FormData();
+   * formData.append("file", imageFile);
+   * 
+   * const asset = await client.uploadMediaAsset(formData);
+   * console.log("Uploaded:", asset.asset.blobUrl);
+   * ```
+   */
+  async uploadMediaAsset(formData) {
+    return this.post("/api/marketplace/merchant/media/upload", formData, {
+      headers: { "Content-Type": "multipart/form-data" }
+    });
+  }
+  /**
+   * Delete a media asset
+   * 
+   * @param assetId - Asset ID
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.deleteMediaAsset("asset_123");
+   * ```
+   */
+  async deleteMediaAsset(assetId) {
+    return this.delete(`/api/marketplace/merchant/media?id=${assetId}`);
+  }
+  // ============================================================================
+  // Banners
+  // ============================================================================
+  /**
+   * List merchant's banners
+   * 
+   * @returns List of banners
+   * 
+   * @example
+   * ```typescript
+   * const banners = await client.listMerchantBanners();
+   * ```
+   */
+  async listMerchantBanners() {
+    return this.get("/api/marketplace/merchant/banners");
+  }
+  /**
+   * Create a promotional banner
+   * 
+   * @param request - Banner data
+   * @returns Created banner
+   * 
+   * @example
+   * ```typescript
+   * const banner = await client.createBanner({
+   *   title: "Summer Sale",
+   *   imageUrl: "https://...",
+   *   linkUrl: "/products?category=summer",
+   *   ctaText: "Shop Now",
+   *   priority: 10
+   * });
+   * ```
+   */
+  async createBanner(request) {
+    return this.post("/api/marketplace/merchant/banners", request);
+  }
+  /**
+   * Get banner details
+   * 
+   * @param bannerId - Banner ID
+   * @returns Banner details
+   * 
+   * @example
+   * ```typescript
+   * const banner = await client.getBanner("banner_123");
+   * ```
+   */
+  async getBanner(bannerId) {
+    return this.get(`/api/marketplace/merchant/banners/${bannerId}`);
+  }
+  /**
+   * Update a banner
+   * 
+   * @param bannerId - Banner ID
+   * @param request - Updated banner data
+   * @returns Updated banner
+   * 
+   * @example
+   * ```typescript
+   * await client.updateBanner("banner_123", {
+   *   isActive: false
+   * });
+   * ```
+   */
+  async updateBanner(bannerId, request) {
+    return this.put(`/api/marketplace/merchant/banners/${bannerId}`, request);
+  }
+  /**
+   * Delete a banner
+   * 
+   * @param bannerId - Banner ID
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.deleteBanner("banner_123");
+   * ```
+   */
+  async deleteBanner(bannerId) {
+    return this.delete(`/api/marketplace/merchant/banners/${bannerId}`);
+  }
+  // ============================================================================
+  // Analytics
+  // ============================================================================
+  /**
+   * Get merchant analytics
+   * 
+   * @param params - Query parameters
+   * @returns Analytics data with overview, charts, and insights
+   * 
+   * @example
+   * ```typescript
+   * const analytics = await client.getAnalytics({ range: "30days" });
+   * console.log("Revenue:", analytics.overview.totalRevenue);
+   * console.log("Orders:", analytics.overview.totalOrders);
+   * ```
+   */
+  async getAnalytics(params) {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/merchant/analytics${queryString}`);
+  }
+  // ============================================================================
+  // Inventory
+  // ============================================================================
+  /**
+   * Get inventory audit log
+   * 
+   * @returns Recent inventory audit entries (last 500)
+   * 
+   * @example
+   * ```typescript
+   * const audit = await client.getInventoryAudit();
+   * audit.entries.forEach(e => {
+   *   console.log(e.action, e.product.title, e.changeAmount);
+   * });
+   * ```
+   */
+  async getInventoryAudit() {
+    return this.get("/api/marketplace/merchant/inventory/audit");
+  }
+  // ============================================================================
+  // Tax Management
+  // ============================================================================
+  /**
+   * Get tax settings
+   * 
+   * @returns Tax settings
+   * 
+   * @example
+   * ```typescript
+   * const settings = await client.getTaxSettings();
+   * console.log("Tax enabled:", settings.settings.taxEnabled);
+   * ```
+   */
+  async getTaxSettings() {
+    return this.get("/api/marketplace/merchant/tax-settings");
+  }
+  /**
+   * Update tax settings
+   * 
+   * @param request - Updated settings
+   * @returns Updated tax settings
+   * 
+   * @example
+   * ```typescript
+   * await client.updateTaxSettings({
+   *   taxEnabled: true,
+   *   pricesIncludeTax: false,
+   *   defaultTaxBehavior: "CHARGE"
+   * });
+   * ```
+   */
+  async updateTaxSettings(request) {
+    return this.put("/api/marketplace/merchant/tax-settings", request);
+  }
+  /**
+   * List tax rules
+   * 
+   * @returns List of tax rules
+   * 
+   * @example
+   * ```typescript
+   * const rules = await client.listTaxRules();
+   * ```
+   */
+  async listTaxRules() {
+    return this.get("/api/marketplace/merchant/tax-rules");
+  }
+  /**
+   * Create a tax rule
+   * 
+   * @param request - Tax rule data
+   * @returns Created tax rule
+   * 
+   * @example
+   * ```typescript
+   * const rule = await client.createTaxRule({
+   *   country: "US",
+   *   region: "NY",
+   *   taxType: "SALES_TAX",
+   *   taxName: "NY Sales Tax",
+   *   taxRate: 8.875
+   * });
+   * ```
+   */
+  async createTaxRule(request) {
+    return this.post("/api/marketplace/merchant/tax-rules", request);
+  }
+  /**
+   * Get tax rule details
+   * 
+   * @param ruleId - Rule ID
+   * @returns Tax rule details
+   * 
+   * @example
+   * ```typescript
+   * const rule = await client.getTaxRule("rule_123");
+   * ```
+   */
+  async getTaxRule(ruleId) {
+    return this.get(`/api/marketplace/merchant/tax-rules/${ruleId}`);
+  }
+  /**
+   * Update a tax rule
+   * 
+   * @param ruleId - Rule ID
+   * @param request - Updated rule data
+   * @returns Updated tax rule
+   * 
+   * @example
+   * ```typescript
+   * await client.updateTaxRule("rule_123", {
+   *   taxRate: 9.0
+   * });
+   * ```
+   */
+  async updateTaxRule(ruleId, request) {
+    return this.put(`/api/marketplace/merchant/tax-rules/${ruleId}`, request);
+  }
+  /**
+   * Delete a tax rule
+   * 
+   * @param ruleId - Rule ID
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.deleteTaxRule("rule_123");
+   * ```
+   */
+  async deleteTaxRule(ruleId) {
+    return this.delete(`/api/marketplace/merchant/tax-rules/${ruleId}`);
+  }
+  /**
+   * List tax nexus locations
+   * 
+   * @returns List of nexus locations
+   * 
+   * @example
+   * ```typescript
+   * const nexus = await client.listTaxNexus();
+   * ```
+   */
+  async listTaxNexus() {
+    return this.get("/api/marketplace/merchant/tax-nexus");
+  }
+  /**
+   * Add a tax nexus location
+   * 
+   * @param request - Nexus data
+   * @returns Created nexus
+   * 
+   * @example
+   * ```typescript
+   * const nexus = await client.createTaxNexus({
+   *   country: "US",
+   *   region: "CA",
+   *   registrationId: "123456789"
+   * });
+   * ```
+   */
+  async createTaxNexus(request) {
+    return this.post("/api/marketplace/merchant/tax-nexus", request);
+  }
+  /**
+   * Update a tax nexus location
+   * 
+   * @param nexusId - Nexus ID
+   * @param request - Updated nexus data
+   * @returns Updated nexus
+   * 
+   * @example
+   * ```typescript
+   * await client.updateTaxNexus("nexus_123", {
+   *   registrationId: "987654321"
+   * });
+   * ```
+   */
+  async updateTaxNexus(nexusId, request) {
+    return this.put(`/api/marketplace/merchant/tax-nexus/${nexusId}`, request);
+  }
+  /**
+   * Delete a tax nexus location
+   * 
+   * @param nexusId - Nexus ID
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.deleteTaxNexus("nexus_123");
+   * ```
+   */
+  async deleteTaxNexus(nexusId) {
+    return this.delete(`/api/marketplace/merchant/tax-nexus/${nexusId}`);
+  }
+  /**
+   * List tax reports
+   * 
+   * @param params - Query parameters
+   * @returns Paginated list of tax reports
+   * 
+   * @example
+   * ```typescript
+   * const reports = await client.listTaxReports({ limit: 20, offset: 0 });
+   * 
+   * // Get summary for a specific year
+   * const summary = await client.listTaxReports({ year: 2025 });
+   * ```
+   */
+  async listTaxReports(params) {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/merchant/tax-reports${queryString}`);
+  }
+  /**
+   * Generate a tax report
+   * 
+   * @param request - Report generation request
+   * @returns Generated report
+   * 
+   * @example
+   * ```typescript
+   * const report = await client.generateTaxReport({
+   *   periodType: "MONTHLY",
+   *   year: 2025,
+   *   period: 1  // January
+   * });
+   * ```
+   */
+  async generateTaxReport(request) {
+    return this.post("/api/marketplace/merchant/tax-reports/generate", request);
+  }
+  /**
+   * Get tax report details
+   * 
+   * @param reportId - Report ID
+   * @returns Report with detailed records
+   * 
+   * @example
+   * ```typescript
+   * const report = await client.getTaxReport("report_123");
+   * console.log("Total tax:", report.report.totalTax);
+   * ```
+   */
+  async getTaxReport(reportId) {
+    return this.get(`/api/marketplace/merchant/tax-reports/${reportId}`);
+  }
+  /**
+   * Update tax report status
+   * 
+   * @param reportId - Report ID
+   * @param request - Status update
+   * @returns Updated report
+   * 
+   * @example
+   * ```typescript
+   * await client.updateTaxReportStatus("report_123", {
+   *   status: "FINALIZED"
+   * });
+   * ```
+   */
+  async updateTaxReportStatus(reportId, request) {
+    return this.put(`/api/marketplace/merchant/tax-reports/${reportId}`, request);
+  }
+  /**
+   * Export tax report as CSV
+   * 
+   * @param reportId - Report ID
+   * @returns CSV file data
+   * 
+   * @example
+   * ```typescript
+   * const csv = await client.exportTaxReport("report_123");
+   * // Save or download the CSV
+   * ```
+   */
+  async exportTaxReport(reportId) {
+    return this.get(`/api/marketplace/merchant/tax-reports/${reportId}/export`);
+  }
+};
+
+// lib/ecommerce/types/enums.ts
+var OrderStatus = /* @__PURE__ */ ((OrderStatus2) => {
+  OrderStatus2["CREATED"] = "CREATED";
+  OrderStatus2["AWAITING_DEPOSIT"] = "AWAITING_DEPOSIT";
+  OrderStatus2["PAYMENT_RESERVED"] = "PAYMENT_RESERVED";
+  OrderStatus2["MERCHANT_ACCEPTED"] = "MERCHANT_ACCEPTED";
+  OrderStatus2["SHIPPED"] = "SHIPPED";
+  OrderStatus2["DELIVERED"] = "DELIVERED";
+  OrderStatus2["CANCELLED"] = "CANCELLED";
+  OrderStatus2["CONFIRMED"] = "CONFIRMED";
+  OrderStatus2["COMPLETED"] = "COMPLETED";
+  return OrderStatus2;
+})(OrderStatus || {});
+var PaymentMethod = /* @__PURE__ */ ((PaymentMethod2) => {
+  PaymentMethod2["USDC_ESCROW"] = "USDC_ESCROW";
+  PaymentMethod2["POINTS"] = "POINTS";
+  return PaymentMethod2;
+})(PaymentMethod || {});
+var PaymentStatus = /* @__PURE__ */ ((PaymentStatus2) => {
+  PaymentStatus2["PENDING"] = "PENDING";
+  PaymentStatus2["RESERVED"] = "RESERVED";
+  PaymentStatus2["COMPLETED"] = "COMPLETED";
+  PaymentStatus2["FAILED"] = "FAILED";
+  PaymentStatus2["REFUNDED"] = "REFUNDED";
+  return PaymentStatus2;
+})(PaymentStatus || {});
+var MerchantStatus = /* @__PURE__ */ ((MerchantStatus2) => {
+  MerchantStatus2["ACTIVE"] = "ACTIVE";
+  MerchantStatus2["SUSPENDED"] = "SUSPENDED";
+  MerchantStatus2["PENDING"] = "PENDING";
+  return MerchantStatus2;
+})(MerchantStatus || {});
+var ShipmentStatus = /* @__PURE__ */ ((ShipmentStatus2) => {
+  ShipmentStatus2["PENDING"] = "PENDING";
+  ShipmentStatus2["SHIPPED"] = "SHIPPED";
+  ShipmentStatus2["DELIVERED"] = "DELIVERED";
+  ShipmentStatus2["FAILED"] = "FAILED";
+  return ShipmentStatus2;
+})(ShipmentStatus || {});
+var ReturnStatus = /* @__PURE__ */ ((ReturnStatus2) => {
+  ReturnStatus2["REQUESTED"] = "REQUESTED";
+  ReturnStatus2["APPROVED"] = "APPROVED";
+  ReturnStatus2["REJECTED"] = "REJECTED";
+  ReturnStatus2["SHIPPED_BACK"] = "SHIPPED_BACK";
+  ReturnStatus2["RECEIVED"] = "RECEIVED";
+  ReturnStatus2["REFUNDED"] = "REFUNDED";
+  return ReturnStatus2;
+})(ReturnStatus || {});
+var ReviewStatus = /* @__PURE__ */ ((ReviewStatus2) => {
+  ReviewStatus2["PENDING"] = "PENDING";
+  ReviewStatus2["RESPONDED"] = "RESPONDED";
+  ReviewStatus2["FLAGGED"] = "FLAGGED";
+  return ReviewStatus2;
+})(ReviewStatus || {});
+var DiscountType = /* @__PURE__ */ ((DiscountType2) => {
+  DiscountType2["PERCENTAGE"] = "PERCENTAGE";
+  DiscountType2["FIXED_AMOUNT"] = "FIXED_AMOUNT";
+  DiscountType2["BUY_X_GET_Y"] = "BUY_X_GET_Y";
+  DiscountType2["FREE_SHIPPING"] = "FREE_SHIPPING";
+  return DiscountType2;
+})(DiscountType || {});
+var DiscountMethod = /* @__PURE__ */ ((DiscountMethod2) => {
+  DiscountMethod2["CODE"] = "CODE";
+  DiscountMethod2["AUTOMATIC"] = "AUTOMATIC";
+  return DiscountMethod2;
+})(DiscountMethod || {});
+var DiscountScope = /* @__PURE__ */ ((DiscountScope2) => {
+  DiscountScope2["ORDER"] = "ORDER";
+  DiscountScope2["PRODUCT"] = "PRODUCT";
+  DiscountScope2["CATEGORY"] = "CATEGORY";
+  DiscountScope2["SHIPPING"] = "SHIPPING";
+  return DiscountScope2;
+})(DiscountScope || {});
+var BannerType = /* @__PURE__ */ ((BannerType2) => {
+  BannerType2["HERO"] = "HERO";
+  BannerType2["PROMO"] = "PROMO";
+  BannerType2["FEATURED"] = "FEATURED";
+  return BannerType2;
+})(BannerType || {});
+var TaxType = /* @__PURE__ */ ((TaxType2) => {
+  TaxType2["SALES_TAX"] = "SALES_TAX";
+  TaxType2["VAT"] = "VAT";
+  TaxType2["GST"] = "GST";
+  TaxType2["PST"] = "PST";
+  TaxType2["HST"] = "HST";
+  return TaxType2;
+})(TaxType || {});
+var TaxBehavior = /* @__PURE__ */ ((TaxBehavior2) => {
+  TaxBehavior2["CHARGE"] = "CHARGE";
+  TaxBehavior2["INCLUSIVE"] = "INCLUSIVE";
+  TaxBehavior2["EXEMPT"] = "EXEMPT";
+  return TaxBehavior2;
+})(TaxBehavior || {});
+var TaxReportPeriodType = /* @__PURE__ */ ((TaxReportPeriodType2) => {
+  TaxReportPeriodType2["MONTHLY"] = "MONTHLY";
+  TaxReportPeriodType2["QUARTERLY"] = "QUARTERLY";
+  TaxReportPeriodType2["YEARLY"] = "YEARLY";
+  return TaxReportPeriodType2;
+})(TaxReportPeriodType || {});
+var TaxReportStatus = /* @__PURE__ */ ((TaxReportStatus2) => {
+  TaxReportStatus2["DRAFT"] = "DRAFT";
+  TaxReportStatus2["FINALIZED"] = "FINALIZED";
+  TaxReportStatus2["FILED"] = "FILED";
+  return TaxReportStatus2;
+})(TaxReportStatus || {});
+var InventoryAuditAction = /* @__PURE__ */ ((InventoryAuditAction2) => {
+  InventoryAuditAction2["CREATED"] = "CREATED";
+  InventoryAuditAction2["UPDATED"] = "UPDATED";
+  InventoryAuditAction2["RESERVED"] = "RESERVED";
+  InventoryAuditAction2["DEDUCTED"] = "DEDUCTED";
+  InventoryAuditAction2["RESTORED"] = "RESTORED";
+  return InventoryAuditAction2;
+})(InventoryAuditAction || {});
+var SortOrder = /* @__PURE__ */ ((SortOrder2) => {
+  SortOrder2["ASC"] = "asc";
+  SortOrder2["DESC"] = "desc";
+  return SortOrder2;
+})(SortOrder || {});
+var ProductSortBy = /* @__PURE__ */ ((ProductSortBy2) => {
+  ProductSortBy2["DATE_DESC"] = "date_desc";
+  ProductSortBy2["DATE_ASC"] = "date_asc";
+  ProductSortBy2["PRICE_ASC"] = "price_asc";
+  ProductSortBy2["PRICE_DESC"] = "price_desc";
+  ProductSortBy2["POPULAR"] = "popular";
+  ProductSortBy2["FEATURED"] = "featured";
+  return ProductSortBy2;
+})(ProductSortBy || {});
+var ReviewSortBy = /* @__PURE__ */ ((ReviewSortBy2) => {
+  ReviewSortBy2["NEWEST"] = "newest";
+  ReviewSortBy2["HIGHEST"] = "highest";
+  ReviewSortBy2["LOWEST"] = "lowest";
+  return ReviewSortBy2;
+})(ReviewSortBy || {});
+
+exports.BannerType = BannerType;
+exports.BaseEcommerceClient = BaseEcommerceClient;
+exports.CustomerEcommerceClient = CustomerEcommerceClient;
+exports.DiscountMethod = DiscountMethod;
+exports.DiscountScope = DiscountScope;
+exports.DiscountType = DiscountType;
+exports.EcommerceApiError = EcommerceApiError;
+exports.InventoryAuditAction = InventoryAuditAction;
+exports.MerchantEcommerceClient = MerchantEcommerceClient;
+exports.MerchantStatus = MerchantStatus;
+exports.OrderStatus = OrderStatus;
+exports.PaymentMethod = PaymentMethod;
+exports.PaymentStatus = PaymentStatus;
+exports.ProductSortBy = ProductSortBy;
+exports.ReturnStatus = ReturnStatus;
+exports.ReviewSortBy = ReviewSortBy;
+exports.ReviewStatus = ReviewStatus;
+exports.ShipmentStatus = ShipmentStatus;
+exports.SortOrder = SortOrder;
+exports.TaxBehavior = TaxBehavior;
+exports.TaxReportPeriodType = TaxReportPeriodType;
+exports.TaxReportStatus = TaxReportStatus;
+exports.TaxType = TaxType;
+exports.buildQueryString = buildQueryString;
+exports.calculateDiscountAmount = calculateDiscountAmount;
+exports.calculateFinalPrice = calculateFinalPrice;
+exports.formatPrice = formatPrice;
+exports.getBackoffDelay = getBackoffDelay;
+exports.isRetryableError = isRetryableError;
+exports.isValidAddress = isValidAddress;
+exports.isValidEmail = isValidEmail;
+exports.parseError = parseError;
+exports.retryWithBackoff = retryWithBackoff;
+exports.sleep = sleep;
+exports.truncateAddress = truncateAddress;