@basedone/core 0.1.10 → 0.2.1

package/dist/ecommerce.d.ts

@@ -0,0 +1,3986 @@
+import { AxiosRequestConfig, AxiosInstance } from 'axios';
+
+/**
+ * Base Ecommerce API Client
+ *
+ * This module provides the base HTTP client for the ecommerce API with
+ * authentication, error handling, and retry logic.
+ */
+
+/**
+ * Client configuration options
+ */
+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");
+ * ```
+ */
+declare class BaseEcommerceClient {
+    private axiosInstance;
+    private config;
+    constructor(config: EcommerceClientConfig);
+    /**
+     * Update authentication token
+     *
+     * @param token - New authentication token
+     *
+     * @example
+     * ```typescript
+     * client.setAuthToken("new-auth-token");
+     * ```
+     */
+    setAuthToken(token: string): void;
+    /**
+     * Clear authentication token
+     *
+     * @example
+     * ```typescript
+     * client.clearAuthToken();
+     * ```
+     */
+    clearAuthToken(): void;
+    /**
+     * 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 }
+     * });
+     * ```
+     */
+    get<T = any>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * 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"
+     * });
+     * ```
+     */
+    post<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * 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"
+     * });
+     * ```
+     */
+    put<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * 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" }
+     * });
+     * ```
+     */
+    patch<T = any>(url: string, data?: any, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * 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");
+     * ```
+     */
+    delete<T = any>(url: string, config?: AxiosRequestConfig): Promise<T>;
+    /**
+     * Make a request with retry logic
+     *
+     * @param config - Axios request config
+     * @returns Response data
+     */
+    private request;
+    /**
+     * Get the underlying axios instance
+     *
+     * @returns Axios instance
+     *
+     * @example
+     * ```typescript
+     * const axios = client.getAxiosInstance();
+     * // Use axios directly for advanced use cases
+     * ```
+     */
+    getAxiosInstance(): AxiosInstance;
+}
+
+/**
+ * Ecommerce Type Enums
+ *
+ * This module contains all enum types used in the ecommerce API.
+ */
+/**
+ * Order status enum representing the lifecycle of an order
+ */
+declare enum OrderStatus {
+    /** Order created but payment not initiated */
+    CREATED = "CREATED",
+    /** Awaiting escrow deposit from customer */
+    AWAITING_DEPOSIT = "AWAITING_DEPOSIT",
+    /** Payment reserved in escrow */
+    PAYMENT_RESERVED = "PAYMENT_RESERVED",
+    /** Merchant has accepted the order */
+    MERCHANT_ACCEPTED = "MERCHANT_ACCEPTED",
+    /** Order has been shipped */
+    SHIPPED = "SHIPPED",
+    /** Order has been delivered */
+    DELIVERED = "DELIVERED",
+    /** Order has been cancelled */
+    CANCELLED = "CANCELLED",
+    /** Order is confirmed (legacy status) */
+    CONFIRMED = "CONFIRMED",
+    /** Order is completed (legacy status) */
+    COMPLETED = "COMPLETED"
+}
+/**
+ * Payment method enum
+ */
+declare enum PaymentMethod {
+    /** USDC payment via Hyperliquid escrow */
+    USDC_ESCROW = "USDC_ESCROW",
+    /** Points-based payment */
+    POINTS = "POINTS"
+}
+/**
+ * Payment status enum
+ */
+declare enum PaymentStatus {
+    /** Payment is pending */
+    PENDING = "PENDING",
+    /** Payment is reserved in escrow */
+    RESERVED = "RESERVED",
+    /** Payment is completed */
+    COMPLETED = "COMPLETED",
+    /** Payment failed */
+    FAILED = "FAILED",
+    /** Payment was refunded */
+    REFUNDED = "REFUNDED"
+}
+/**
+ * Merchant status enum
+ */
+declare enum MerchantStatus {
+    /** Merchant is active */
+    ACTIVE = "ACTIVE",
+    /** Merchant is suspended */
+    SUSPENDED = "SUSPENDED",
+    /** Merchant is pending approval */
+    PENDING = "PENDING"
+}
+/**
+ * Shipment status enum
+ */
+declare enum ShipmentStatus {
+    /** Shipment is pending */
+    PENDING = "PENDING",
+    /** Shipment is in transit */
+    SHIPPED = "SHIPPED",
+    /** Shipment is delivered */
+    DELIVERED = "DELIVERED",
+    /** Shipment failed */
+    FAILED = "FAILED"
+}
+/**
+ * Return status enum
+ */
+declare enum ReturnStatus {
+    /** Return requested by customer */
+    REQUESTED = "REQUESTED",
+    /** Return approved by merchant */
+    APPROVED = "APPROVED",
+    /** Return rejected by merchant */
+    REJECTED = "REJECTED",
+    /** Return item shipped back */
+    SHIPPED_BACK = "SHIPPED_BACK",
+    /** Return item received by merchant */
+    RECEIVED = "RECEIVED",
+    /** Refund processed */
+    REFUNDED = "REFUNDED"
+}
+/**
+ * Review status enum
+ */
+declare enum ReviewStatus {
+    /** Review is pending */
+    PENDING = "PENDING",
+    /** Review has been responded to */
+    RESPONDED = "RESPONDED",
+    /** Review has been flagged */
+    FLAGGED = "FLAGGED"
+}
+/**
+ * Discount type enum
+ */
+declare enum DiscountType {
+    /** Percentage discount */
+    PERCENTAGE = "PERCENTAGE",
+    /** Fixed amount discount */
+    FIXED_AMOUNT = "FIXED_AMOUNT",
+    /** Buy X get Y discount */
+    BUY_X_GET_Y = "BUY_X_GET_Y",
+    /** Free shipping */
+    FREE_SHIPPING = "FREE_SHIPPING"
+}
+/**
+ * Discount method enum
+ */
+declare enum DiscountMethod {
+    /** Code-based discount (coupon) */
+    CODE = "CODE",
+    /** Automatic discount */
+    AUTOMATIC = "AUTOMATIC"
+}
+/**
+ * Discount scope enum
+ */
+declare enum DiscountScope {
+    /** Applies to entire order */
+    ORDER = "ORDER",
+    /** Applies to specific products */
+    PRODUCT = "PRODUCT",
+    /** Applies to specific categories */
+    CATEGORY = "CATEGORY",
+    /** Applies to shipping */
+    SHIPPING = "SHIPPING"
+}
+/**
+ * Banner type enum
+ */
+declare enum BannerType {
+    /** Hero banner */
+    HERO = "HERO",
+    /** Promotional banner */
+    PROMO = "PROMO",
+    /** Featured banner */
+    FEATURED = "FEATURED"
+}
+/**
+ * Tax type enum
+ */
+declare enum TaxType {
+    /** Sales tax */
+    SALES_TAX = "SALES_TAX",
+    /** Value-added tax */
+    VAT = "VAT",
+    /** Goods and services tax */
+    GST = "GST",
+    /** Provincial sales tax */
+    PST = "PST",
+    /** Harmonized sales tax */
+    HST = "HST"
+}
+/**
+ * Tax behavior enum
+ */
+declare enum TaxBehavior {
+    /** Charge tax on top of price */
+    CHARGE = "CHARGE",
+    /** Tax is included in price */
+    INCLUSIVE = "INCLUSIVE",
+    /** No tax */
+    EXEMPT = "EXEMPT"
+}
+/**
+ * Tax report period type enum
+ */
+declare enum TaxReportPeriodType {
+    /** Monthly report */
+    MONTHLY = "MONTHLY",
+    /** Quarterly report */
+    QUARTERLY = "QUARTERLY",
+    /** Yearly report */
+    YEARLY = "YEARLY"
+}
+/**
+ * Tax report status enum
+ */
+declare enum TaxReportStatus {
+    /** Report is in draft */
+    DRAFT = "DRAFT",
+    /** Report is finalized */
+    FINALIZED = "FINALIZED",
+    /** Report has been filed */
+    FILED = "FILED"
+}
+/**
+ * Inventory audit action enum
+ */
+declare enum InventoryAuditAction {
+    /** Inventory created */
+    CREATED = "CREATED",
+    /** Inventory updated */
+    UPDATED = "UPDATED",
+    /** Inventory reserved */
+    RESERVED = "RESERVED",
+    /** Inventory deducted */
+    DEDUCTED = "DEDUCTED",
+    /** Inventory restored */
+    RESTORED = "RESTORED"
+}
+/**
+ * Sort order enum
+ */
+declare enum SortOrder {
+    /** Ascending order */
+    ASC = "asc",
+    /** Descending order */
+    DESC = "desc"
+}
+/**
+ * Product sort by enum
+ */
+declare enum ProductSortBy {
+    /** Sort by date (newest first) */
+    DATE_DESC = "date_desc",
+    /** Sort by date (oldest first) */
+    DATE_ASC = "date_asc",
+    /** Sort by price (low to high) */
+    PRICE_ASC = "price_asc",
+    /** Sort by price (high to low) */
+    PRICE_DESC = "price_desc",
+    /** Sort by popularity */
+    POPULAR = "popular",
+    /** Sort by featured status */
+    FEATURED = "featured"
+}
+/**
+ * Review sort by enum
+ */
+declare enum ReviewSortBy {
+    /** Sort by newest */
+    NEWEST = "newest",
+    /** Sort by highest rating */
+    HIGHEST = "highest",
+    /** Sort by lowest rating */
+    LOWEST = "lowest"
+}
+
+/**
+ * Ecommerce Entity Interfaces
+ *
+ * This module contains all core entity interfaces used in the ecommerce API.
+ */
+
+/**
+ * Base entity interface with common fields
+ */
+interface BaseEntity {
+    /** Unique identifier */
+    id: string;
+    /** Creation timestamp */
+    createdAt: string;
+    /** Last update timestamp */
+    updatedAt: string;
+    /** Tenant ID for multi-tenancy */
+    tenantId?: string | null;
+}
+/**
+ * Product dimensions
+ */
+interface ProductDimensions {
+    /** Length in cm */
+    length?: number;
+    /** Width in cm */
+    width?: number;
+    /** Height in cm */
+    height?: number;
+}
+/**
+ * Product entity
+ */
+interface Product extends BaseEntity {
+    /** Merchant ID */
+    merchantId: string;
+    /** Product title */
+    title: string;
+    /** Product description (plain text) */
+    description?: string | null;
+    /** Rich description (HTML) */
+    richDescription?: string | null;
+    /** Product images URLs */
+    images: string[];
+    /** Legacy single image URL (for backward compatibility) */
+    imageUrl?: string | null;
+    /** Price in USDC */
+    priceUSDC: string;
+    /** Compare at price (original price for discount display) */
+    compareAtPrice?: string | null;
+    /** Stock keeping unit */
+    sku?: string | null;
+    /** Inventory count */
+    inventory?: number | null;
+    /** Minimum order quantity */
+    moq: number;
+    /** Product category slug */
+    category?: string | null;
+    /** Category ID */
+    categoryId?: string | null;
+    /** Product tags */
+    tags?: string[];
+    /** Weight in kg */
+    weight?: string | null;
+    /** Product dimensions */
+    dimensions?: ProductDimensions | null;
+    /** Is product active */
+    isActive: boolean;
+    /** Is product featured */
+    featured: boolean;
+    /** View count */
+    viewCount: number;
+    /** Sold count */
+    soldCount: number;
+    /** Average rating (computed from reviews) */
+    averageRating?: number | null;
+    /** Review count */
+    reviewCount?: number;
+    /** Merchant information */
+    merchant?: Merchant;
+    /** Product variants */
+    variants?: ProductVariant[];
+    /** Product reviews */
+    reviews?: ProductReview[];
+}
+/**
+ * Product variant entity
+ */
+interface ProductVariant extends BaseEntity {
+    /** Product ID */
+    productId: string;
+    /** Variant name */
+    name: string;
+    /** SKU */
+    sku?: string | null;
+    /** Price override (if different from base product) */
+    priceUSDC?: string | null;
+    /** Inventory count */
+    inventory?: number | null;
+    /** Variant attributes (e.g., {color: "red", size: "L"}) */
+    attributes: Record<string, string>;
+    /** Is variant active */
+    isActive: boolean;
+    /** Sort order */
+    sortOrder: number;
+}
+/**
+ * Merchant entity
+ */
+interface Merchant extends BaseEntity {
+    /** Owner user ID */
+    ownerUserId: string;
+    /** Merchant name */
+    name: string;
+    /** Merchant description */
+    description?: string | null;
+    /** Payout address (wallet) */
+    payoutAddress: string;
+    /** Merchant status */
+    status: MerchantStatus;
+}
+/**
+ * Shipping address
+ */
+interface ShippingAddress {
+    /** Full name */
+    fullName: string;
+    /** Phone number */
+    phone: string;
+    /** Email address */
+    email?: string | null;
+    /** Address line 1 */
+    addressLine1: string;
+    /** Address line 2 */
+    addressLine2?: string | null;
+    /** City */
+    city: string;
+    /** State or province */
+    stateProvince: string;
+    /** Postal code */
+    postalCode: string;
+    /** Country */
+    country: string;
+    /** Delivery instructions */
+    deliveryInstructions?: string | null;
+}
+/**
+ * User shipping address entity (saved addresses)
+ */
+interface UserShippingAddress extends BaseEntity, ShippingAddress {
+    /** User ID */
+    userId: string;
+    /** Is default address */
+    isDefault: boolean;
+    /** Address label (e.g., "Home", "Work") */
+    label?: string | null;
+}
+/**
+ * Order item
+ */
+interface OrderItem extends BaseEntity {
+    /** Order ID */
+    orderId: string;
+    /** Product ID */
+    productId: string;
+    /** Variant ID */
+    variantId?: string | null;
+    /** Quantity */
+    quantity: number;
+    /** Unit price in USDC (snapshot at order time) */
+    unitPriceUSDC: string;
+    /** Product title snapshot */
+    titleSnapshot: string;
+    /** Product details (for display) */
+    product?: Product;
+    /** Variant details (for display) */
+    variant?: ProductVariant;
+}
+/**
+ * Payment entity
+ */
+interface Payment extends BaseEntity {
+    /** Order ID */
+    orderId: string;
+    /** Payment method */
+    method: PaymentMethod;
+    /** Payment status */
+    status: PaymentStatus;
+    /** Amount in USDC */
+    amountUSDC: string;
+    /** Deposit transaction hash */
+    depositTxHash?: string | null;
+    /** Settlement transaction hash */
+    settlementTxHash?: string | null;
+}
+/**
+ * Settlement entity
+ */
+interface Settlement extends BaseEntity {
+    /** Order ID */
+    orderId: string;
+    /** Merchant ID */
+    merchantId: string;
+    /** Merchant payout address */
+    merchantPayoutAddress: string;
+    /** Amount in USDC */
+    amountUSDC: string;
+    /** Settlement status */
+    status: string;
+    /** Transaction hash */
+    txHash?: string | null;
+    /** Next attempt timestamp */
+    nextAttemptAt?: string | null;
+    /** Attempt count */
+    attemptCount: number;
+    /** Last error */
+    lastError?: string | null;
+}
+/**
+ * Shipment entity
+ */
+interface Shipment extends BaseEntity {
+    /** Order ID */
+    orderId: string;
+    /** Shipment status */
+    status: ShipmentStatus;
+    /** Carrier name */
+    carrier?: string | null;
+    /** Tracking number */
+    trackingNumber?: string | null;
+    /** Shipping label URL */
+    shippingLabel?: string | null;
+    /** Shipped timestamp */
+    shippedAt?: string | null;
+    /** Delivered timestamp */
+    deliveredAt?: string | null;
+}
+/**
+ * Order entity
+ */
+interface Order extends BaseEntity {
+    /** User ID (customer) */
+    userId: string;
+    /** Merchant ID */
+    merchantId: string;
+    /** Order status */
+    status: OrderStatus;
+    /** Total amount in USDC */
+    totalUSDC: string;
+    /** Payment method */
+    paymentMethod: PaymentMethod;
+    /** Shipping address */
+    shippingAddress: ShippingAddress;
+    /** Customer notes */
+    customerNotes?: string | null;
+    /** Order items */
+    items: OrderItem[];
+    /** Payment information */
+    payment?: Payment;
+    /** Settlement information */
+    settlement?: Settlement;
+    /** Shipment information */
+    shipment?: Shipment;
+    /** Merchant information */
+    merchant?: Merchant;
+    /** Customer information */
+    user?: {
+        id: string;
+        username?: string;
+        email?: string;
+    };
+    /** Order events */
+    events?: OrderEvent[];
+}
+/**
+ * Order event entity
+ */
+interface OrderEvent extends BaseEntity {
+    /** Order ID */
+    orderId: string;
+    /** Event type */
+    eventType: string;
+    /** Event title */
+    title: string;
+    /** Event description */
+    description?: string | null;
+    /** Event metadata */
+    metadata?: Record<string, any> | null;
+    /** Performer user ID */
+    performedBy?: string | null;
+    /** Performer information */
+    performer?: {
+        id: string;
+        username?: string;
+    };
+}
+/**
+ * Product review entity
+ */
+interface ProductReview extends BaseEntity {
+    /** Product ID */
+    productId: string;
+    /** User ID */
+    userId: string;
+    /** Order ID (for verified purchase) */
+    orderId?: string | null;
+    /** Rating (1-5) */
+    rating: number;
+    /** Review title */
+    title?: string | null;
+    /** Review comment */
+    comment?: string | null;
+    /** Review images */
+    images?: string[];
+    /** Merchant response */
+    merchantResponse?: string | null;
+    /** Merchant responded timestamp */
+    merchantRespondedAt?: string | null;
+    /** Is verified purchase */
+    isVerifiedPurchase: boolean;
+    /** Is visible */
+    isVisible: boolean;
+    /** Review status */
+    status: ReviewStatus;
+    /** Helpfulness count (thumbs up) */
+    helpfulCount: number;
+    /** User information */
+    user?: {
+        id: string;
+        address: string;
+    };
+    /** Product information */
+    product?: Product;
+}
+/**
+ * Return entity
+ */
+interface Return extends BaseEntity {
+    /** Order ID */
+    orderId: string;
+    /** User ID */
+    userId: string;
+    /** Merchant ID */
+    merchantId: string;
+    /** Return status */
+    status: ReturnStatus;
+    /** Return reason */
+    reason?: string | null;
+    /** Requested timestamp */
+    requestedAt: string;
+    /** Approved timestamp */
+    approvedAt?: string | null;
+    /** Rejected timestamp */
+    rejectedAt?: string | null;
+    /** Received timestamp */
+    receivedAt?: string | null;
+    /** Completed timestamp */
+    completedAt?: string | null;
+    /** Return items */
+    items: ReturnItem[];
+}
+/**
+ * Return item
+ */
+interface ReturnItem {
+    /** Item ID */
+    id: string;
+    /** Product ID */
+    productId: string;
+    /** Quantity */
+    quantity: number;
+    /** Reason */
+    reason?: string | null;
+    /** Product information */
+    product?: Product;
+}
+/**
+ * Coupon entity
+ */
+interface Coupon extends BaseEntity {
+    /** Merchant ID */
+    merchantId: string;
+    /** Coupon code */
+    code: string;
+    /** Coupon title */
+    title?: string | null;
+    /** Discount method */
+    discountMethod: DiscountMethod;
+    /** Discount type */
+    discountType: DiscountType;
+    /** Discount scope */
+    discountScope: DiscountScope;
+    /** Discount value */
+    discountValue: number;
+    /** Minimum purchase amount */
+    minPurchase?: number | null;
+    /** Minimum quantity */
+    minQuantity?: number | null;
+    /** Buy quantity (for BUY_X_GET_Y) */
+    buyQuantity?: number | null;
+    /** Get quantity (for BUY_X_GET_Y) */
+    getQuantity?: number | null;
+    /** Get discount value (for BUY_X_GET_Y) */
+    getDiscountValue?: number | null;
+    /** Maximum uses */
+    maxUses?: number | null;
+    /** Uses per customer */
+    usesPerCustomer?: number | null;
+    /** Used count */
+    usedCount: number;
+    /** Applicable product IDs */
+    applicableProducts: string[];
+    /** Applicable category IDs */
+    applicableCategories: string[];
+    /** Can be combined with other discounts */
+    combinable: boolean;
+    /** Start timestamp */
+    startsAt: string;
+    /** Expiry timestamp */
+    expiresAt: string;
+    /** Is active */
+    isActive: boolean;
+    /** Coupon usages */
+    usages?: CouponUsage[];
+}
+/**
+ * Coupon usage entity
+ */
+interface CouponUsage extends BaseEntity {
+    /** Coupon ID */
+    couponId: string;
+    /** User ID */
+    userId: string;
+    /** Order ID */
+    orderId: string;
+    /** Discount amount */
+    discount: string;
+    /** Used timestamp */
+    usedAt: string;
+    /** User information */
+    user?: {
+        username?: string;
+    };
+}
+/**
+ * Shipping method entity
+ */
+interface ShippingMethod extends BaseEntity {
+    /** Merchant ID */
+    merchantId: string;
+    /** Method name */
+    name: string;
+    /** Carrier */
+    carrier?: string | null;
+    /** Estimated delivery days */
+    estimatedDays?: string | null;
+    /** Flat rate */
+    flatRate?: number | null;
+    /** Is weight-based */
+    weightBased: boolean;
+    /** Free shipping threshold */
+    freeThreshold?: number | null;
+    /** Is active */
+    isActive: boolean;
+}
+/**
+ * Banner entity
+ */
+interface Banner extends BaseEntity {
+    /** Merchant ID (null for admin banners) */
+    merchantId?: string | null;
+    /** Banner type */
+    type: BannerType;
+    /** Title */
+    title: string;
+    /** Subtitle */
+    subtitle?: string | null;
+    /** Image URL */
+    imageUrl: string;
+    /** Link URL */
+    linkUrl?: string | null;
+    /** Call-to-action text */
+    ctaText?: string | null;
+    /** Start date */
+    startDate?: string | null;
+    /** End date */
+    endDate?: string | null;
+    /** Priority (higher = shown first) */
+    priority: number;
+    /** Is active */
+    isActive: boolean;
+    /** Impressions count */
+    impressions: number;
+    /** Clicks count */
+    clicks: number;
+    /** Merchant information */
+    merchant?: {
+        id: string;
+        name: string;
+    };
+}
+/**
+ * Media asset entity
+ */
+interface MediaAsset extends BaseEntity {
+    /** Merchant ID */
+    merchantId: string;
+    /** Blob URL */
+    blobUrl: string;
+    /** Blob pathname */
+    blobPathname: string;
+    /** Download URL */
+    downloadUrl: string;
+    /** Filename */
+    filename: string;
+    /** Content type */
+    contentType: string;
+    /** File size in bytes */
+    size: number;
+}
+/**
+ * Message entity
+ */
+interface Message extends BaseEntity {
+    /** Order ID */
+    orderId: string;
+    /** Sender user ID */
+    senderId: string;
+    /** Recipient user ID */
+    recipientId: string;
+    /** Message text */
+    message: string;
+    /** Is read */
+    isRead: boolean;
+    /** Sender information */
+    sender?: {
+        id: string;
+        username?: string;
+    };
+    /** Recipient information */
+    recipient?: {
+        id: string;
+        username?: string;
+    };
+    /** Order information */
+    order?: Order;
+}
+/**
+ * Tax settings entity
+ */
+interface TaxSettings extends BaseEntity {
+    /** Merchant ID */
+    merchantId: string;
+    /** Is tax enabled */
+    taxEnabled: boolean;
+    /** Prices include tax */
+    pricesIncludeTax: boolean;
+    /** Default tax behavior */
+    defaultTaxBehavior: TaxBehavior;
+    /** Tax registration number */
+    taxRegistrationNumber?: string | null;
+    /** Registration country */
+    registrationCountry?: string | null;
+}
+/**
+ * Tax rule entity
+ */
+interface TaxRule extends BaseEntity {
+    /** Merchant ID */
+    merchantId: string;
+    /** Country */
+    country: string;
+    /** Region/state */
+    region?: string | null;
+    /** Postal code from */
+    postalCodeFrom?: string | null;
+    /** Postal code to */
+    postalCodeTo?: string | null;
+    /** Tax type */
+    taxType: TaxType;
+    /** Tax name */
+    taxName: string;
+    /** Tax rate (percentage) */
+    taxRate: number;
+    /** Priority (higher = applied first) */
+    priority: number;
+    /** Is compound tax */
+    isCompound: boolean;
+    /** Is active */
+    isActive: boolean;
+}
+/**
+ * Tax nexus entity
+ */
+interface TaxNexus extends BaseEntity {
+    /** Merchant ID */
+    merchantId: string;
+    /** Country */
+    country: string;
+    /** Region/state */
+    region?: string | null;
+    /** Registration ID */
+    registrationId?: string | null;
+    /** Is active */
+    isActive: boolean;
+}
+/**
+ * Tax report entity
+ */
+interface TaxReport extends BaseEntity {
+    /** Merchant ID */
+    merchantId: string;
+    /** Period type */
+    periodType: TaxReportPeriodType;
+    /** Period start */
+    periodStart: string;
+    /** Period end */
+    periodEnd: string;
+    /** Total taxable amount */
+    totalTaxable: string;
+    /** Total tax amount */
+    totalTax: string;
+    /** Report status */
+    status: TaxReportStatus;
+    /** Exported timestamp */
+    exportedAt?: string | null;
+}
+/**
+ * Inventory audit entry
+ */
+interface InventoryAuditEntry extends BaseEntity {
+    /** Product ID */
+    productId: string;
+    /** Variant ID */
+    variantId?: string | null;
+    /** Action */
+    action: InventoryAuditAction;
+    /** Previous quantity */
+    previousQuantity?: number | null;
+    /** New quantity */
+    newQuantity?: number | null;
+    /** Change amount */
+    changeAmount: number;
+    /** Reason */
+    reason?: string | null;
+    /** Reference ID (e.g., order ID) */
+    referenceId?: string | null;
+    /** Product information */
+    product?: Product;
+    /** Variant information */
+    variant?: ProductVariant;
+}
+/**
+ * Customer summary (for merchant view)
+ */
+interface CustomerSummary {
+    /** Customer user ID */
+    id: string;
+    /** Username */
+    username?: string;
+    /** Email */
+    email?: string;
+    /** Wallet address */
+    address?: string;
+    /** Total orders */
+    totalOrders: number;
+    /** Total spent */
+    totalSpent: string;
+    /** Average order value */
+    averageOrderValue: string;
+    /** Last order date */
+    lastOrderDate?: string;
+    /** First order date */
+    firstOrderDate?: string;
+}
+/**
+ * Flash sale item entity
+ */
+interface FlashSaleItem {
+    /** Item ID */
+    id: string;
+    /** Product ID */
+    productId: string;
+    /** Sale price in USDC */
+    salePrice: string;
+    /** Original price in USDC */
+    originalPrice: string;
+    /** Discount percentage */
+    discountPercent: number;
+    /** Maximum quantity available at this price */
+    maxQuantity: number | null;
+    /** Quantity sold at flash price */
+    soldQuantity: number;
+    /** Remaining quantity */
+    remainingQuantity: number | null;
+    /** Limit per customer */
+    limitPerCustomer: number | null;
+    /** Product details */
+    product: {
+        id: string;
+        title: string;
+        description?: string | null;
+        images: string[];
+        priceUSDC: string;
+        inventory: number | null;
+        soldCount: number;
+        averageRating: number | null;
+        reviewCount: number;
+        merchant?: {
+            id: string;
+            name: string;
+        };
+    };
+}
+/**
+ * Flash sale entity
+ */
+interface FlashSale {
+    /** Flash sale ID */
+    id: string;
+    /** Sale name */
+    name: string;
+    /** Description */
+    description?: string | null;
+    /** Start timestamp */
+    startsAt: string;
+    /** End timestamp */
+    endsAt: string;
+    /** Badge text (e.g., "Mall", "Hot Deal") */
+    badgeText?: string | null;
+    /** Badge color (hex) */
+    badgeColor?: string | null;
+    /** Priority (higher = shown first) */
+    priority: number;
+    /** Merchant information */
+    merchant?: {
+        id: string;
+        name: string;
+    } | null;
+    /** Flash sale items */
+    items: FlashSaleItem[];
+}
+
+/**
+ * Ecommerce API Request Types
+ *
+ * This module contains all request types for the ecommerce API.
+ */
+
+/**
+ * Pagination parameters
+ */
+interface PaginationParams {
+    /** Number of items to return */
+    limit?: number;
+    /** Number of items to skip */
+    offset?: number;
+}
+/**
+ * List products request parameters
+ */
+interface ListProductsParams extends PaginationParams {
+    /** Filter by specific product IDs */
+    ids?: string[];
+    /** Filter by merchant ID */
+    merchantId?: string;
+    /** Filter by category slug */
+    category?: string;
+    /** Search query */
+    search?: string;
+    /** Filter by tags */
+    tags?: string[];
+    /** Minimum price */
+    minPrice?: number;
+    /** Maximum price */
+    maxPrice?: number;
+    /** Filter by featured status */
+    featured?: boolean;
+    /** Sort by */
+    sortBy?: ProductSortBy;
+    /** Filter by active status */
+    isActive?: boolean;
+}
+/**
+ * Create product request
+ */
+interface CreateProductRequest {
+    /** Product title */
+    title: string;
+    /** Product images URLs (from media library) */
+    images: string[];
+    /** Price in USDC */
+    priceUSDC: number;
+    /** Compare at price */
+    compareAtPrice?: number | null;
+    /** Inventory count */
+    inventory?: number | null;
+    /** SKU */
+    sku?: string | null;
+    /** Minimum order quantity */
+    moq?: number;
+    /** Category slug */
+    category?: string | null;
+    /** Rich description (HTML) */
+    richDescription?: string | null;
+    /** Weight in kg */
+    weight?: number | null;
+    /** Dimensions */
+    dimensions?: ProductDimensions | null;
+    /** Is active */
+    isActive?: boolean;
+}
+/**
+ * Update product request
+ */
+interface UpdateProductRequest extends Partial<CreateProductRequest> {
+}
+/**
+ * Create product variant request
+ */
+interface CreateProductVariantRequest {
+    /** Variant name */
+    name: string;
+    /** SKU */
+    sku?: string | null;
+    /** Price override */
+    priceUSDC?: number | null;
+    /** Inventory count */
+    inventory?: number | null;
+    /** Variant attributes */
+    attributes: Record<string, string>;
+    /** Is active */
+    isActive?: boolean;
+    /** Sort order */
+    sortOrder?: number;
+}
+/**
+ * Update product variant request
+ */
+interface UpdateProductVariantRequest extends Partial<CreateProductVariantRequest> {
+}
+/**
+ * Cart item
+ */
+interface CartItem {
+    /** Product ID */
+    productId: string;
+    /** Quantity */
+    quantity: number;
+    /** Variant ID (optional) */
+    variantId?: string;
+}
+/**
+ * Create order request
+ */
+interface CreateOrderRequest {
+    /** Cart items */
+    items: CartItem[];
+    /** Payment method */
+    paymentMethod: PaymentMethod;
+    /** Shipping address */
+    shippingAddress: ShippingAddress;
+    /** Customer notes */
+    customerNotes?: string;
+    /** Coupon code */
+    couponCode?: string;
+    /** Idempotency key */
+    idempotencyKey?: string;
+}
+/**
+ * List orders request parameters
+ */
+interface ListOrdersParams extends PaginationParams {
+    /** Filter by status */
+    status?: OrderStatus;
+}
+/**
+ * Update order status request
+ */
+interface UpdateOrderStatusRequest {
+    /** New status */
+    status: OrderStatus;
+    /** Tracking information (required for SHIPPED status) */
+    tracking?: {
+        trackingNumber: string;
+        carrier: string;
+    };
+}
+/**
+ * Create order event request
+ */
+interface CreateOrderEventRequest {
+    /** Event type */
+    eventType: string;
+    /** Event title */
+    title: string;
+    /** Event description */
+    description?: string;
+    /** Event metadata */
+    metadata?: Record<string, any>;
+}
+/**
+ * Create review request
+ */
+interface CreateReviewRequest {
+    /** Rating (1-5) */
+    rating: number;
+    /** Review title */
+    title?: string;
+    /** Review comment */
+    comment?: string;
+}
+/**
+ * List reviews request parameters
+ */
+interface ListReviewsParams extends PaginationParams {
+    /** Sort by */
+    sortBy?: ReviewSortBy;
+}
+/**
+ * Respond to review request
+ */
+interface RespondToReviewRequest {
+    /** Merchant response */
+    merchantResponse: string;
+}
+/**
+ * Create/update shipping address request
+ */
+interface ShippingAddressRequest extends ShippingAddress {
+    /** Is default address */
+    isDefault?: boolean;
+    /** Address label */
+    label?: string | null;
+}
+/**
+ * Calculate cart discounts request
+ */
+interface CalculateCartDiscountsRequest {
+    /** Cart items */
+    items: CartItem[];
+}
+/**
+ * Validate discount code request
+ */
+interface ValidateDiscountRequest {
+    /** Discount code */
+    code: string;
+    /** Cart items */
+    items: CartItem[];
+}
+/**
+ * Calculate tax request
+ */
+interface CalculateTaxRequest {
+    /** Cart items */
+    items: CartItem[];
+    /** Shipping address */
+    shippingAddress: {
+        country: string;
+        region?: string;
+        postalCode?: string;
+    };
+}
+/**
+ * Create/update merchant profile request
+ */
+interface MerchantProfileRequest {
+    /** Merchant name */
+    name: string;
+    /** Description */
+    description?: string | null;
+    /** Payout address (wallet) */
+    payoutAddress: string;
+}
+/**
+ * Create coupon request
+ */
+interface CreateCouponRequest {
+    /** Coupon code */
+    code?: string;
+    /** Title */
+    title?: string | null;
+    /** Discount method */
+    discountMethod?: DiscountMethod;
+    /** Discount type */
+    discountType: DiscountType;
+    /** Discount scope */
+    discountScope?: DiscountScope;
+    /** Discount value */
+    discountValue: number;
+    /** Minimum purchase */
+    minPurchase?: number | null;
+    /** Minimum quantity */
+    minQuantity?: number | null;
+    /** Buy quantity */
+    buyQuantity?: number | null;
+    /** Get quantity */
+    getQuantity?: number | null;
+    /** Get discount value */
+    getDiscountValue?: number | null;
+    /** Maximum uses */
+    maxUses?: number | null;
+    /** Uses per customer */
+    usesPerCustomer?: number | null;
+    /** Applicable products */
+    applicableProducts?: string[];
+    /** Applicable categories */
+    applicableCategories?: string[];
+    /** Combinable */
+    combinable?: boolean;
+    /** Start date */
+    startsAt: string;
+    /** Expiry date */
+    expiresAt: string;
+    /** Is active */
+    isActive?: boolean;
+}
+/**
+ * Update coupon request
+ */
+interface UpdateCouponRequest extends Partial<CreateCouponRequest> {
+}
+/**
+ * Create shipping method request
+ */
+interface CreateShippingMethodRequest {
+    /** Method name */
+    name: string;
+    /** Carrier */
+    carrier?: string | null;
+    /** Estimated delivery days */
+    estimatedDays?: string | null;
+    /** Flat rate */
+    flatRate?: number | null;
+    /** Weight-based */
+    weightBased?: boolean;
+    /** Free threshold */
+    freeThreshold?: number | null;
+    /** Is active */
+    isActive?: boolean;
+}
+/**
+ * Update shipping method request
+ */
+interface UpdateShippingMethodRequest extends Partial<CreateShippingMethodRequest> {
+}
+/**
+ * Update shipment request
+ */
+interface UpdateShipmentRequest {
+    /** Shipment status */
+    status?: ShipmentStatus;
+    /** Tracking number */
+    trackingNumber?: string | null;
+    /** Carrier */
+    carrier?: string | null;
+    /** Shipping label URL */
+    shippingLabel?: string | null;
+}
+/**
+ * Create banner request
+ */
+interface CreateBannerRequest {
+    /** Banner type */
+    type?: BannerType;
+    /** Title */
+    title: string;
+    /** Subtitle */
+    subtitle?: string | null;
+    /** Image URL */
+    imageUrl: string;
+    /** Link URL */
+    linkUrl?: string | null;
+    /** CTA text */
+    ctaText?: string | null;
+    /** Start date */
+    startDate?: string | null;
+    /** End date */
+    endDate?: string | null;
+    /** Priority */
+    priority?: number;
+    /** Is active */
+    isActive?: boolean;
+}
+/**
+ * Update banner request
+ */
+interface UpdateBannerRequest extends Partial<CreateBannerRequest> {
+}
+/**
+ * Track banner request
+ */
+interface TrackBannerRequest {
+    /** Action type */
+    action: "impression" | "click";
+}
+/**
+ * Send message request
+ */
+interface SendMessageRequest {
+    /** Order ID */
+    orderId: string;
+    /** Recipient user ID */
+    recipientId: string;
+    /** Message text */
+    message: string;
+}
+/**
+ * Update tax settings request
+ */
+interface UpdateTaxSettingsRequest {
+    /** Tax enabled */
+    taxEnabled?: boolean;
+    /** Prices include tax */
+    pricesIncludeTax?: boolean;
+    /** Default tax behavior */
+    defaultTaxBehavior?: TaxBehavior;
+    /** Tax registration number */
+    taxRegistrationNumber?: string | null;
+    /** Registration country */
+    registrationCountry?: string | null;
+}
+/**
+ * Create tax rule request
+ */
+interface CreateTaxRuleRequest {
+    /** Country */
+    country: string;
+    /** Region */
+    region?: string | null;
+    /** Postal code from */
+    postalCodeFrom?: string | null;
+    /** Postal code to */
+    postalCodeTo?: string | null;
+    /** Tax type */
+    taxType: TaxType;
+    /** Tax name */
+    taxName: string;
+    /** Tax rate */
+    taxRate: number;
+    /** Priority */
+    priority?: number;
+    /** Is compound */
+    isCompound?: boolean;
+}
+/**
+ * Update tax rule request
+ */
+interface UpdateTaxRuleRequest extends Partial<CreateTaxRuleRequest> {
+    /** Is active */
+    isActive?: boolean;
+}
+/**
+ * Create tax nexus request
+ */
+interface CreateTaxNexusRequest {
+    /** Country */
+    country: string;
+    /** Region */
+    region?: string | null;
+    /** Registration ID */
+    registrationId?: string | null;
+}
+/**
+ * Update tax nexus request
+ */
+interface UpdateTaxNexusRequest {
+    /** Registration ID */
+    registrationId?: string | null;
+    /** Is active */
+    isActive?: boolean;
+}
+/**
+ * Generate tax report request
+ */
+interface GenerateTaxReportRequest {
+    /** Period type */
+    periodType: TaxReportPeriodType;
+    /** Year */
+    year: number;
+    /** Period (1-12 for monthly, 1-4 for quarterly, 1 for yearly) */
+    period: number;
+}
+/**
+ * Update tax report status request
+ */
+interface UpdateTaxReportStatusRequest {
+    /** Report status */
+    status: "DRAFT" | "FINALIZED" | "FILED";
+}
+/**
+ * List tax reports params
+ */
+interface ListTaxReportsParams extends PaginationParams {
+    /** Filter by year (for summary) */
+    year?: number;
+}
+/**
+ * Get analytics params
+ */
+interface GetAnalyticsParams {
+    /** Date range */
+    range?: "7days" | "30days" | "90days" | "1year";
+}
+/**
+ * List customers params
+ */
+interface ListCustomersParams extends PaginationParams {
+}
+/**
+ * List active banners params
+ */
+interface ListActiveBannersParams {
+    /** Filter by type */
+    type?: BannerType;
+    /** Filter by merchant ID */
+    merchantId?: string;
+}
+/**
+ * List active flash sales params
+ */
+interface ListActiveFlashSalesParams {
+    /** Maximum number of flash sales to return */
+    limit?: number;
+    /** Filter by merchant ID */
+    merchantId?: string;
+}
+/**
+ * Flash sale item input
+ */
+interface FlashSaleItemInput {
+    /** Product ID */
+    productId: string;
+    /** Sale price in USDC */
+    salePrice: number;
+    /** Maximum quantity available */
+    maxQuantity?: number | null;
+    /** Limit per customer */
+    limitPerCustomer?: number;
+    /** Sort order */
+    sortOrder?: number;
+}
+/**
+ * Create flash sale request
+ */
+interface CreateFlashSaleRequest {
+    /** Sale name */
+    name: string;
+    /** Description */
+    description?: string | null;
+    /** Start timestamp */
+    startsAt: string;
+    /** End timestamp */
+    endsAt: string;
+    /** Badge text */
+    badgeText?: string;
+    /** Badge color (hex) */
+    badgeColor?: string;
+    /** Priority (higher = shown first) */
+    priority?: number;
+    /** Is active */
+    isActive?: boolean;
+    /** Flash sale items */
+    items?: FlashSaleItemInput[];
+}
+/**
+ * Update flash sale request
+ */
+interface UpdateFlashSaleRequest extends Partial<CreateFlashSaleRequest> {
+}
+
+/**
+ * Ecommerce API Response Types
+ *
+ * This module contains all response types for the ecommerce API.
+ */
+
+/**
+ * Base API response
+ */
+interface ApiResponse<T = any> {
+    /** Response data */
+    data?: T;
+    /** Error message */
+    error?: string;
+    /** Success flag */
+    success?: boolean;
+}
+/**
+ * Paginated response
+ */
+interface PaginatedResponse<T> {
+    /** Items */
+    items: T[];
+    /** Total count */
+    total: number;
+    /** Limit */
+    limit: number;
+    /** Offset */
+    offset: number;
+}
+/**
+ * List products response
+ */
+interface ListProductsResponse extends PaginatedResponse<Product> {
+}
+/**
+ * Get product response
+ *
+ * Note: The API returns the product object directly, not wrapped in a `product` field.
+ * This type extends Product to be compatible with the actual API response.
+ */
+type GetProductResponse = Product;
+/**
+ * Create/Update product response
+ */
+interface ProductResponse {
+    /** Product */
+    product: Product;
+}
+/**
+ * List product variants response
+ */
+interface ListProductVariantsResponse {
+    /** Variants */
+    variants: ProductVariant[];
+}
+/**
+ * Product variant response
+ */
+interface ProductVariantResponse {
+    /** Variant */
+    variant: ProductVariant;
+}
+/**
+ * List orders response
+ */
+interface ListOrdersResponse extends PaginatedResponse<Order> {
+    /** Merchant information (for merchant endpoints) */
+    merchant?: Merchant;
+}
+/**
+ * Get order response
+ */
+interface GetOrderResponse {
+    /** Order */
+    order: Order;
+}
+/**
+ * Create order response
+ */
+interface CreateOrderResponse {
+    /** Created orders (array for multi-merchant checkout) */
+    orders: Order[];
+    /** Summary */
+    summary: {
+        /** Total amount */
+        totalAmount: string;
+        /** Order count */
+        orderCount: number;
+        /** Merchant names */
+        merchantNames: string[];
+    };
+    /** Escrow payment instructions (for USDC_ESCROW) */
+    escrow?: {
+        /** Escrow address */
+        address: string;
+        /** Amount in USDC */
+        amountUSDC: string;
+    };
+    /** Test mode flag */
+    testMode?: boolean;
+}
+/**
+ * Update order response
+ */
+interface UpdateOrderResponse {
+    /** Updated order */
+    order: Order;
+}
+/**
+ * Confirm escrow deposit response
+ */
+interface ConfirmEscrowDepositResponse {
+    /** Success flag */
+    ok: boolean;
+    /** Order ID */
+    orderId: string;
+    /** Order status */
+    status: string;
+    /** Deposit transaction hash */
+    depositTxHash: string | null;
+}
+/**
+ * Order receipt response
+ */
+interface OrderReceiptResponse {
+    /** Receipt */
+    receipt: {
+        /** Order number */
+        orderNumber: string;
+        /** Order ID */
+        orderId: string;
+        /** Order date */
+        orderDate: string;
+        /** Status */
+        status: string;
+        /** Customer */
+        customer: {
+            name: string;
+            email?: string;
+        };
+        /** Merchant */
+        merchant: {
+            name: string;
+        };
+        /** Shipping address */
+        shippingAddress: any;
+        /** Items */
+        items: Array<{
+            title: string;
+            quantity: number;
+            unitPrice: string;
+            totalPrice: string;
+        }>;
+        /** Subtotal */
+        subtotal: string;
+        /** Tax */
+        tax: string;
+        /** Shipping */
+        shipping: string;
+        /** Total */
+        total: string;
+        /** Payment */
+        payment: {
+            method: string;
+            status?: string;
+            transactionHash?: string | null;
+        };
+    };
+}
+/**
+ * List reviews response
+ */
+interface ListReviewsResponse extends PaginatedResponse<ProductReview> {
+}
+/**
+ * Create/Update review response
+ */
+interface ReviewResponse {
+    /** Review */
+    review: ProductReview;
+}
+/**
+ * List shipping addresses response
+ */
+interface ListShippingAddressesResponse {
+    /** Addresses */
+    addresses: UserShippingAddress[];
+}
+/**
+ * Shipping address response
+ */
+interface ShippingAddressResponse {
+    /** Address */
+    address: UserShippingAddress;
+}
+/**
+ * Applied discount
+ */
+interface AppliedDiscount {
+    /** Coupon/discount ID */
+    id: string;
+    /** Code */
+    code: string;
+    /** Title */
+    title?: string | null;
+    /** Discount type */
+    discountType: string;
+    /** Discount amount */
+    discountAmount: number;
+    /** Description */
+    description?: string;
+}
+/**
+ * Calculate cart discounts response
+ */
+interface CalculateCartDiscountsResponse {
+    /** Subtotal */
+    subtotal: number;
+    /** Discount amount */
+    discountAmount: number;
+    /** Total */
+    total: number;
+    /** Applied discounts */
+    appliedDiscounts: AppliedDiscount[];
+}
+/**
+ * Validate discount response
+ */
+interface ValidateDiscountResponse {
+    /** Is valid */
+    valid: boolean;
+    /** Error message */
+    error?: string;
+    /** Discount */
+    discount?: {
+        /** Coupon ID */
+        id: string;
+        /** Code */
+        code: string;
+        /** Title */
+        title?: string | null;
+        /** Discount type */
+        discountType: string;
+        /** Discount amount */
+        discountAmount: number;
+    };
+    /** Subtotal */
+    subtotal?: number;
+    /** Total */
+    total?: number;
+}
+/**
+ * Tax breakdown item
+ */
+interface TaxBreakdownItem {
+    /** Tax type */
+    taxType: string;
+    /** Tax name */
+    taxName: string;
+    /** Tax rate */
+    taxRate: number;
+    /** Tax amount */
+    taxAmount: number;
+    /** Country */
+    country: string;
+    /** Region */
+    region?: string;
+}
+/**
+ * Calculate tax response
+ */
+interface CalculateTaxResponse {
+    /** Subtotal */
+    subtotal: number;
+    /** Tax amount */
+    taxAmount: number;
+    /** Total */
+    total: number;
+    /** Tax breakdown */
+    breakdown: TaxBreakdownItem[];
+    /** Merchant tax details (for multi-merchant) */
+    merchantTaxDetails?: Array<{
+        merchantId: string;
+        subtotal: number;
+        taxAmount: number;
+        hasNexus: boolean;
+        breakdown: TaxBreakdownItem[];
+    }>;
+}
+/**
+ * Merchant profile response
+ */
+interface MerchantProfileResponse {
+    /** Merchant */
+    merchant: Merchant;
+}
+/**
+ * List coupons response
+ */
+interface ListCouponsResponse {
+    /** Coupons */
+    coupons: Coupon[];
+    /** Stats */
+    stats: {
+        total: number;
+        active: number;
+        totalUsages: number;
+        totalDiscount: number;
+    };
+}
+/**
+ * Coupon response
+ */
+interface CouponResponse {
+    /** Coupon */
+    coupon: Coupon;
+}
+/**
+ * Get coupon with usages response
+ */
+interface GetCouponResponse {
+    /** Coupon with usages */
+    coupon: Coupon & {
+        usages: Array<CouponUsage & {
+            user: {
+                username?: string;
+            };
+        }>;
+    };
+}
+/**
+ * List shipping methods response
+ */
+interface ListShippingMethodsResponse {
+    /** Methods */
+    methods: ShippingMethod[];
+}
+/**
+ * Shipping method response
+ */
+interface ShippingMethodResponse {
+    /** Method */
+    method: ShippingMethod;
+}
+/**
+ * List shipments response
+ */
+interface ListShipmentsResponse {
+    /** Shipments */
+    shipments: Array<Shipment & {
+        order: {
+            id: string;
+            totalUSDC: string;
+            shippingAddress: any;
+            user: {
+                id: string;
+                username?: string;
+            };
+        };
+    }>;
+}
+/**
+ * Shipment response
+ */
+interface ShipmentResponse {
+    /** Shipment */
+    shipment: Shipment;
+}
+/**
+ * List returns response
+ */
+interface ListReturnsResponse {
+    /** Returns */
+    returns: Array<Return & {
+        user: {
+            id: string;
+            username?: string;
+        };
+        order: {
+            id: string;
+            totalUSDC: string;
+        };
+    }>;
+}
+/**
+ * Return response
+ */
+interface ReturnResponse {
+    /** Return */
+    return: Return;
+}
+/**
+ * List banners response
+ */
+interface ListBannersResponse {
+    /** Banners */
+    banners: Banner[];
+}
+/**
+ * Banner response
+ */
+interface BannerResponse {
+    /** Banner */
+    banner: Banner;
+}
+/**
+ * List media assets response
+ */
+interface ListMediaAssetsResponse extends PaginatedResponse<MediaAsset> {
+}
+/**
+ * Media asset response
+ */
+interface MediaAssetResponse {
+    /** Asset */
+    asset: MediaAsset;
+}
+/**
+ * List messages response
+ */
+interface ListMessagesResponse {
+    /** Conversations */
+    conversations: Array<{
+        orderId: string;
+        orderNumber: string;
+        customer: {
+            id: string;
+            name?: string;
+            username?: string;
+        };
+        lastMessage: Message;
+        unreadCount: number;
+        messages: Message[];
+    }>;
+    /** Stats */
+    stats: {
+        total: number;
+        unread: number;
+    };
+}
+/**
+ * Message response
+ */
+interface MessageResponse {
+    /** Message */
+    message: Message;
+}
+/**
+ * Customer messages response (for retail users)
+ *
+ * Groups messages by order, where each order represents a conversation with a merchant.
+ */
+interface CustomerMessagesResponse {
+    /** Conversations grouped by order */
+    conversations: Array<{
+        orderId: string;
+        orderNumber: string;
+        merchant: {
+            id: string;
+            name: string;
+            ownerUserId: string;
+        };
+        lastMessage: Message;
+        unreadCount: number;
+        messages: Message[];
+    }>;
+    /** Stats */
+    stats: {
+        total: number;
+        unread: number;
+    };
+}
+/**
+ * Message stats response (for notification badges)
+ */
+interface MessageStatsResponse {
+    /** Unread message count */
+    unread: number;
+}
+/**
+ * Analytics overview
+ */
+interface AnalyticsOverview {
+    /** Total revenue */
+    totalRevenue: number;
+    /** Revenue change percentage */
+    revenueChange: number;
+    /** Total orders */
+    totalOrders: number;
+    /** Orders change percentage */
+    ordersChange: number;
+    /** Average order value */
+    averageOrderValue: number;
+    /** AOV change percentage */
+    aovChange: number;
+    /** Total customers */
+    totalCustomers: number;
+    /** Customers change percentage */
+    customersChange: number;
+}
+/**
+ * Revenue by day
+ */
+interface RevenueByDay {
+    /** Date */
+    date: string;
+    /** Revenue */
+    revenue: number;
+    /** Orders */
+    orders: number;
+}
+/**
+ * Top product
+ */
+interface TopProduct {
+    /** Product ID */
+    id: string;
+    /** Name */
+    name: string;
+    /** Image */
+    image: string | null;
+    /** Sold count */
+    soldCount: number;
+    /** Revenue */
+    revenue: number;
+    /** View count */
+    viewCount: number;
+}
+/**
+ * Orders by status
+ */
+interface OrdersByStatus {
+    /** Status */
+    status: string;
+    /** Count */
+    count: number;
+    /** Percentage */
+    percentage: number;
+}
+/**
+ * Recent order summary
+ */
+interface RecentOrderSummary {
+    /** Order ID */
+    id: string;
+    /** Order number */
+    orderNumber: string;
+    /** Total amount */
+    totalAmount: number;
+    /** Status */
+    status: string;
+    /** Created at */
+    createdAt: string;
+    /** Buyer */
+    buyer: {
+        username?: string;
+    };
+}
+/**
+ * Get analytics response
+ */
+interface GetAnalyticsResponse {
+    /** Overview */
+    overview: AnalyticsOverview;
+    /** Revenue by day */
+    revenueByDay: RevenueByDay[];
+    /** Top products */
+    topProducts: TopProduct[];
+    /** Orders by status */
+    ordersByStatus: OrdersByStatus[];
+    /** Recent orders */
+    recentOrders: RecentOrderSummary[];
+}
+/**
+ * Product metrics
+ */
+interface ProductMetrics {
+    /** Product ID */
+    id: string;
+    /** Name */
+    name: string;
+    /** Images */
+    images: string[];
+    /** View count */
+    viewCount: number;
+    /** Sold count */
+    soldCount: number;
+    /** Revenue */
+    revenue: number;
+    /** Average rating */
+    averageRating: number;
+    /** Review count */
+    reviewCount: number;
+    /** Wishlist count */
+    wishlistCount: number;
+    /** Conversion rate */
+    conversionRate: number;
+    /** Stock */
+    stock: number;
+    /** Is active */
+    isActive: boolean;
+    /** Featured */
+    featured: boolean;
+    /** Created at */
+    createdAt: string;
+}
+/**
+ * Get product metrics response
+ */
+interface GetProductMetricsResponse {
+    /** Products */
+    products: ProductMetrics[];
+    /** Summary */
+    summary: {
+        totalProducts: number;
+        totalViews: number;
+        totalSales: number;
+        totalRevenue: number;
+        averageConversion: number;
+    };
+}
+/**
+ * List inventory audit response
+ */
+interface ListInventoryAuditResponse {
+    /** Entries */
+    entries: Array<InventoryAuditEntry & {
+        product: {
+            id: string;
+            title: string;
+            images: string[];
+        };
+        variant?: {
+            id: string;
+            name: string;
+        };
+    }>;
+}
+/**
+ * List customers response
+ */
+interface ListCustomersResponse extends PaginatedResponse<CustomerSummary> {
+}
+/**
+ * Tax settings response
+ */
+interface TaxSettingsResponse {
+    /** Settings */
+    settings: TaxSettings;
+}
+/**
+ * List tax rules response
+ */
+interface ListTaxRulesResponse {
+    /** Rules */
+    rules: TaxRule[];
+}
+/**
+ * Tax rule response
+ */
+interface TaxRuleResponse {
+    /** Rule */
+    rule: TaxRule;
+}
+/**
+ * List tax nexus response
+ */
+interface ListTaxNexusResponse {
+    /** Nexus */
+    nexus: TaxNexus[];
+}
+/**
+ * Tax nexus response
+ */
+interface TaxNexusResponse {
+    /** Nexus */
+    nexus: TaxNexus;
+}
+/**
+ * List tax reports response
+ */
+interface ListTaxReportsResponse extends PaginatedResponse<TaxReport> {
+    /** Summary (if year filter is provided) */
+    summary?: {
+        year: number;
+        totalTaxable: string;
+        totalTax: string;
+        reportCount: number;
+    };
+}
+/**
+ * Tax report details
+ */
+interface TaxReportDetails {
+    /** Order ID */
+    orderId: string;
+    /** Order date */
+    orderDate: string;
+    /** Customer */
+    customer: string;
+    /** Subtotal */
+    subtotal: string;
+    /** Tax amount */
+    taxAmount: string;
+    /** Total */
+    total: string;
+    /** Tax breakdown */
+    breakdown: TaxBreakdownItem[];
+}
+/**
+ * Get tax report response
+ */
+interface GetTaxReportResponse {
+    /** Report */
+    report: TaxReport;
+    /** Details */
+    details: TaxReportDetails[];
+}
+/**
+ * Tax report response
+ */
+interface TaxReportResponse {
+    /** Report */
+    report: TaxReport;
+}
+/**
+ * Success response
+ */
+interface SuccessResponse {
+    /** Success flag */
+    success: boolean;
+}
+/**
+ * Product discounts response
+ */
+interface ProductDiscountsResponse {
+    /** Discounts */
+    discounts: Array<{
+        id: string;
+        title: string;
+        description: string;
+        badge: string;
+        discountType: string;
+        discountValue: number;
+        discountAmount: number;
+        minPurchase: number | null;
+        minQuantity: number | null;
+        expiresAt: string;
+    }>;
+}
+/**
+ * Create order event response
+ */
+interface CreateOrderEventResponse {
+    /** Event */
+    event: any;
+}
+/**
+ * Active flash sales response
+ */
+interface ActiveFlashSalesResponse {
+    /** Flash sales */
+    flashSales: FlashSale[];
+    /** Time remaining for the featured/first sale */
+    timeRemaining: {
+        /** End timestamp */
+        endsAt: string;
+        /** Remaining seconds */
+        remainingSeconds: number;
+    } | null;
+    /** Server time (for client-side sync) */
+    serverTime: string;
+}
+
+/**
+ * Customer/End-User Ecommerce API Client
+ *
+ * This module provides methods for customer-facing ecommerce operations including
+ * browsing products, placing orders, managing reviews, and more.
+ */
+
+/**
+ * Customer API client for end-user ecommerce operations
+ *
+ * Provides methods for browsing products, placing orders, managing reviews,
+ * and other customer-facing operations.
+ *
+ * @example
+ * ```typescript
+ * const client = new CustomerEcommerceClient({
+ *   baseURL: "https://api.example.com",
+ *   authToken: "user-auth-token"
+ * });
+ *
+ * // Browse products
+ * const products = await client.listProducts({ limit: 20, category: "electronics" });
+ *
+ * // Place an order
+ * const order = await client.createOrder({
+ *   items: [{ productId: "123", quantity: 1 }],
+ *   paymentMethod: "USDC_ESCROW",
+ *   shippingAddress: { ... }
+ * });
+ * ```
+ */
+declare class CustomerEcommerceClient extends BaseEcommerceClient {
+    /**
+     * 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"
+     * });
+     * ```
+     */
+    listProducts(params?: ListProductsParams): Promise<ListProductsResponse>;
+    /**
+     * 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);
+     * ```
+     */
+    getProduct(productId: string): Promise<GetProductResponse>;
+    /**
+     * Track product view (increment view count)
+     *
+     * @param productId - Product ID
+     * @returns Success response
+     *
+     * @example
+     * ```typescript
+     * await client.trackProductView("prod_123");
+     * ```
+     */
+    trackProductView(productId: string): Promise<SuccessResponse>;
+    /**
+     * 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));
+     * ```
+     */
+    getProductDiscounts(productId: string): Promise<ProductDiscountsResponse>;
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    createOrder(request: CreateOrderRequest): Promise<CreateOrderResponse>;
+    /**
+     * 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"
+     * });
+     * ```
+     */
+    listOrders(params?: ListOrdersParams): Promise<ListOrdersResponse>;
+    /**
+     * 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);
+     * ```
+     */
+    getOrder(orderId: string): Promise<GetOrderResponse>;
+    /**
+     * 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);
+     * ```
+     */
+    confirmEscrowDeposit(orderId: string): Promise<ConfirmEscrowDepositResponse>;
+    /**
+     * 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);
+     * ```
+     */
+    getOrderReceipt(orderId: string): Promise<OrderReceiptResponse>;
+    /**
+     * 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"
+     * });
+     * ```
+     */
+    listProductReviews(productId: string, params?: ListReviewsParams): Promise<ListReviewsResponse>;
+    /**
+     * 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!"
+     * });
+     * ```
+     */
+    createReview(productId: string, request: CreateReviewRequest): Promise<ReviewResponse>;
+    /**
+     * 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);
+     * ```
+     */
+    listShippingAddresses(): Promise<ListShippingAddressesResponse>;
+    /**
+     * 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"
+     * });
+     * ```
+     */
+    createShippingAddress(request: ShippingAddressRequest): Promise<ShippingAddressResponse>;
+    /**
+     * 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"
+     * });
+     * ```
+     */
+    updateShippingAddress(addressId: string, request: Partial<ShippingAddressRequest>): Promise<ShippingAddressResponse>;
+    /**
+     * Delete a shipping address
+     *
+     * @param addressId - Address ID
+     * @returns Success response
+     *
+     * @example
+     * ```typescript
+     * await client.deleteShippingAddress("addr_123");
+     * ```
+     */
+    deleteShippingAddress(addressId: string): Promise<SuccessResponse>;
+    /**
+     * 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);
+     * ```
+     */
+    calculateCartDiscounts(request: CalculateCartDiscountsRequest): Promise<CalculateCartDiscountsResponse>;
+    /**
+     * 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);
+     * }
+     * ```
+     */
+    validateDiscountCode(request: ValidateDiscountRequest): Promise<ValidateDiscountResponse>;
+    /**
+     * 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);
+     * ```
+     */
+    calculateTax(request: CalculateTaxRequest): Promise<CalculateTaxResponse>;
+    /**
+     * 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"
+     * });
+     * ```
+     */
+    getActiveBanners(params?: ListActiveBannersParams): Promise<ListBannersResponse>;
+    /**
+     * 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" });
+     * ```
+     */
+    trackBanner(bannerId: string, request: TrackBannerRequest): Promise<SuccessResponse>;
+    /**
+     * 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`);
+     * });
+     * ```
+     */
+    listMessages(): Promise<CustomerMessagesResponse>;
+    /**
+     * 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);
+     * ```
+     */
+    getMessageStats(): Promise<MessageStatsResponse>;
+    /**
+     * 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?"
+     * });
+     * ```
+     */
+    sendMessage(request: SendMessageRequest): Promise<MessageResponse>;
+    /**
+     * Mark a message as read
+     *
+     * @param messageId - Message ID
+     * @returns Updated message
+     *
+     * @example
+     * ```typescript
+     * await client.markMessageAsRead("msg_123");
+     * ```
+     */
+    markMessageAsRead(messageId: string): Promise<MessageResponse>;
+    /**
+     * 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`);
+     * }
+     * ```
+     */
+    getActiveFlashSales(params?: ListActiveFlashSalesParams): Promise<ActiveFlashSalesResponse>;
+}
+
+/**
+ * Merchant Ecommerce API Client
+ *
+ * This module provides methods for merchant operations including product management,
+ * order fulfillment, customer management, analytics, and more.
+ */
+
+/**
+ * Merchant API client for merchant operations
+ *
+ * Provides comprehensive methods for managing products, orders, customers,
+ * shipping, returns, reviews, analytics, and more.
+ *
+ * @example
+ * ```typescript
+ * const client = new MerchantEcommerceClient({
+ *   baseURL: "https://api.example.com",
+ *   authToken: "merchant-auth-token"
+ * });
+ *
+ * // Create a product
+ * const product = await client.createProduct({
+ *   title: "New Product",
+ *   images: ["https://..."],
+ *   priceUSDC: 99.99,
+ *   inventory: 100
+ * });
+ *
+ * // Get analytics
+ * const analytics = await client.getAnalytics({ range: "30days" });
+ * ```
+ */
+declare class MerchantEcommerceClient extends BaseEcommerceClient {
+    /**
+     * Get merchant profile
+     *
+     * @returns Merchant profile
+     *
+     * @example
+     * ```typescript
+     * const profile = await client.getMerchantProfile();
+     * console.log(profile.merchant.name);
+     * ```
+     */
+    getMerchantProfile(): Promise<MerchantProfileResponse>;
+    /**
+     * Get merchant profile (alias for getMerchantProfile)
+     *
+     * @returns Merchant profile
+     *
+     * @example
+     * ```typescript
+     * const profile = await client.getProfile();
+     * console.log(profile.merchant.name);
+     * ```
+     */
+    getProfile(): Promise<MerchantProfileResponse>;
+    /**
+     * 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..."
+     * });
+     * ```
+     */
+    upsertMerchantProfile(request: MerchantProfileRequest): Promise<MerchantProfileResponse>;
+    /**
+     * List merchant's products
+     *
+     * @param params - Query parameters
+     * @returns Paginated list of products
+     *
+     * @example
+     * ```typescript
+     * const products = await client.listMerchantProducts({ limit: 20, offset: 0 });
+     * ```
+     */
+    listMerchantProducts(params?: PaginationParams): Promise<ListProductsResponse>;
+    /**
+     * 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);
+     * ```
+     */
+    getProduct(productId: string): Promise<GetProductResponse>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    createProduct(request: CreateProductRequest): Promise<ProductResponse>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    updateProduct(productId: string, request: UpdateProductRequest): Promise<ProductResponse>;
+    /**
+     * Delete a product
+     *
+     * @param productId - Product ID
+     * @returns Success response
+     *
+     * @example
+     * ```typescript
+     * await client.deleteProduct("prod_123");
+     * ```
+     */
+    deleteProduct(productId: string): Promise<SuccessResponse>;
+    /**
+     * Toggle product featured status
+     *
+     * @param productId - Product ID
+     * @param featured - Featured status
+     * @returns Updated product
+     *
+     * @example
+     * ```typescript
+     * await client.setProductFeatured("prod_123", true);
+     * ```
+     */
+    setProductFeatured(productId: string, featured: boolean): Promise<ProductResponse>;
+    /**
+     * List product variants
+     *
+     * @param productId - Product ID
+     * @returns List of variants
+     *
+     * @example
+     * ```typescript
+     * const variants = await client.listProductVariants("prod_123");
+     * ```
+     */
+    listProductVariants(productId: string): Promise<ListProductVariantsResponse>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    createProductVariant(productId: string, request: CreateProductVariantRequest): Promise<ProductVariantResponse>;
+    /**
+     * 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");
+     * ```
+     */
+    getProductVariant(productId: string, variantId: string): Promise<ProductVariantResponse>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    updateProductVariant(productId: string, variantId: string, request: UpdateProductVariantRequest): Promise<ProductVariantResponse>;
+    /**
+     * Delete a product variant
+     *
+     * @param productId - Product ID
+     * @param variantId - Variant ID
+     * @returns Success response
+     *
+     * @example
+     * ```typescript
+     * await client.deleteProductVariant("prod_123", "var_456");
+     * ```
+     */
+    deleteProductVariant(productId: string, variantId: string): Promise<SuccessResponse>;
+    /**
+     * Get product metrics
+     *
+     * @returns Product performance metrics
+     *
+     * @example
+     * ```typescript
+     * const metrics = await client.getProductMetrics();
+     * console.log("Total revenue:", metrics.summary.totalRevenue);
+     * ```
+     */
+    getProductMetrics(): Promise<GetProductMetricsResponse>;
+    /**
+     * List merchant's orders
+     *
+     * @param params - Query parameters
+     * @returns Paginated list of orders
+     *
+     * @example
+     * ```typescript
+     * const orders = await client.listMerchantOrders({ limit: 20, offset: 0 });
+     * ```
+     */
+    listMerchantOrders(params?: ListOrdersParams): Promise<ListOrdersResponse>;
+    /**
+     * 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);
+     * ```
+     */
+    getMerchantOrder(orderId: string): Promise<GetOrderResponse>;
+    /**
+     * 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"
+     *   }
+     * });
+     * ```
+     */
+    updateOrderStatus(orderId: string, request: UpdateOrderStatusRequest): Promise<UpdateOrderResponse>;
+    /**
+     * 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"
+     * });
+     * ```
+     */
+    createOrderEvent(orderId: string, request: CreateOrderEventRequest): Promise<CreateOrderEventResponse>;
+    /**
+     * 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);
+     * });
+     * ```
+     */
+    listCustomers(params?: ListCustomersParams): Promise<ListCustomersResponse>;
+    /**
+     * 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);
+     * ```
+     */
+    listCoupons(): Promise<ListCouponsResponse>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    createCoupon(request: CreateCouponRequest): Promise<CouponResponse>;
+    /**
+     * 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");
+     * ```
+     */
+    getCoupon(couponId: string): Promise<GetCouponResponse>;
+    /**
+     * Update a coupon
+     *
+     * @param couponId - Coupon ID
+     * @param request - Updated coupon data
+     * @returns Updated coupon
+     *
+     * @example
+     * ```typescript
+     * await client.updateCoupon("coupon_123", {
+     *   isActive: false
+     * });
+     * ```
+     */
+    updateCoupon(couponId: string, request: UpdateCouponRequest): Promise<CouponResponse>;
+    /**
+     * Delete a coupon
+     *
+     * @param couponId - Coupon ID
+     * @returns Success response
+     *
+     * @example
+     * ```typescript
+     * await client.deleteCoupon("coupon_123");
+     * ```
+     */
+    deleteCoupon(couponId: string): Promise<SuccessResponse>;
+    /**
+     * List shipping methods
+     *
+     * @returns List of shipping methods
+     *
+     * @example
+     * ```typescript
+     * const methods = await client.listShippingMethods();
+     * ```
+     */
+    listShippingMethods(): Promise<ListShippingMethodsResponse>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    createShippingMethod(request: CreateShippingMethodRequest): Promise<ShippingMethodResponse>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    updateShippingMethod(methodId: string, request: UpdateShippingMethodRequest): Promise<ShippingMethodResponse>;
+    /**
+     * Delete a shipping method
+     *
+     * @param methodId - Method ID
+     * @returns Success response
+     *
+     * @example
+     * ```typescript
+     * await client.deleteShippingMethod("method_123");
+     * ```
+     */
+    deleteShippingMethod(methodId: string): Promise<SuccessResponse>;
+    /**
+     * List shipments
+     *
+     * @returns List of shipments for merchant's orders
+     *
+     * @example
+     * ```typescript
+     * const shipments = await client.listShipments();
+     * ```
+     */
+    listShipments(): Promise<ListShipmentsResponse>;
+    /**
+     * 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"
+     * });
+     * ```
+     */
+    updateShipment(shipmentId: string, request: UpdateShipmentRequest): Promise<ShipmentResponse>;
+    /**
+     * List returns
+     *
+     * @returns List of returns for merchant's orders
+     *
+     * @example
+     * ```typescript
+     * const returns = await client.listReturns();
+     * ```
+     */
+    listReturns(): Promise<ListReturnsResponse>;
+    /**
+     * Approve a return request
+     *
+     * @param returnId - Return ID
+     * @returns Updated return
+     *
+     * @example
+     * ```typescript
+     * await client.approveReturn("return_123");
+     * ```
+     */
+    approveReturn(returnId: string): Promise<ReturnResponse>;
+    /**
+     * Reject a return request
+     *
+     * @param returnId - Return ID
+     * @returns Updated return
+     *
+     * @example
+     * ```typescript
+     * await client.rejectReturn("return_123");
+     * ```
+     */
+    rejectReturn(returnId: string): Promise<ReturnResponse>;
+    /**
+     * Mark return as received
+     *
+     * @param returnId - Return ID
+     * @returns Updated return
+     *
+     * @example
+     * ```typescript
+     * await client.markReturnReceived("return_123");
+     * ```
+     */
+    markReturnReceived(returnId: string): Promise<ReturnResponse>;
+    /**
+     * Process refund for return
+     *
+     * @param returnId - Return ID
+     * @returns Updated return
+     *
+     * @example
+     * ```typescript
+     * await client.processRefund("return_123");
+     * ```
+     */
+    processRefund(returnId: string): Promise<ReturnResponse>;
+    /**
+     * List reviews for merchant's products
+     *
+     * @returns List of reviews
+     *
+     * @example
+     * ```typescript
+     * const reviews = await client.listMerchantReviews();
+     * ```
+     */
+    listMerchantReviews(): Promise<ListReviewsResponse>;
+    /**
+     * 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!"
+     * });
+     * ```
+     */
+    respondToReview(reviewId: string, request: RespondToReviewRequest): Promise<ReviewResponse>;
+    /**
+     * Flag a review as inappropriate
+     *
+     * @param reviewId - Review ID
+     * @returns Updated review
+     *
+     * @example
+     * ```typescript
+     * await client.flagReview("review_123");
+     * ```
+     */
+    flagReview(reviewId: string): Promise<ReviewResponse>;
+    /**
+     * List messages/conversations
+     *
+     * @returns List of conversations grouped by order
+     *
+     * @example
+     * ```typescript
+     * const messages = await client.listMessages();
+     * console.log("Unread:", messages.stats.unread);
+     * ```
+     */
+    listMessages(): Promise<ListMessagesResponse>;
+    /**
+     * 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!"
+     * });
+     * ```
+     */
+    sendMessage(request: SendMessageRequest): Promise<MessageResponse>;
+    /**
+     * Mark message as read
+     *
+     * @param messageId - Message ID
+     * @returns Updated message
+     *
+     * @example
+     * ```typescript
+     * await client.markMessageRead("msg_123");
+     * ```
+     */
+    markMessageRead(messageId: string): Promise<MessageResponse>;
+    /**
+     * List media assets
+     *
+     * @param params - Query parameters
+     * @returns Paginated list of media assets
+     *
+     * @example
+     * ```typescript
+     * const media = await client.listMediaAssets({ limit: 50, offset: 0 });
+     * ```
+     */
+    listMediaAssets(params?: PaginationParams): Promise<ListMediaAssetsResponse>;
+    /**
+     * 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);
+     * ```
+     */
+    uploadMediaAsset(formData: FormData): Promise<MediaAssetResponse>;
+    /**
+     * Delete a media asset
+     *
+     * @param assetId - Asset ID
+     * @returns Success response
+     *
+     * @example
+     * ```typescript
+     * await client.deleteMediaAsset("asset_123");
+     * ```
+     */
+    deleteMediaAsset(assetId: string): Promise<SuccessResponse>;
+    /**
+     * List merchant's banners
+     *
+     * @returns List of banners
+     *
+     * @example
+     * ```typescript
+     * const banners = await client.listMerchantBanners();
+     * ```
+     */
+    listMerchantBanners(): Promise<ListBannersResponse>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    createBanner(request: CreateBannerRequest): Promise<BannerResponse>;
+    /**
+     * Get banner details
+     *
+     * @param bannerId - Banner ID
+     * @returns Banner details
+     *
+     * @example
+     * ```typescript
+     * const banner = await client.getBanner("banner_123");
+     * ```
+     */
+    getBanner(bannerId: string): Promise<BannerResponse>;
+    /**
+     * Update a banner
+     *
+     * @param bannerId - Banner ID
+     * @param request - Updated banner data
+     * @returns Updated banner
+     *
+     * @example
+     * ```typescript
+     * await client.updateBanner("banner_123", {
+     *   isActive: false
+     * });
+     * ```
+     */
+    updateBanner(bannerId: string, request: UpdateBannerRequest): Promise<BannerResponse>;
+    /**
+     * Delete a banner
+     *
+     * @param bannerId - Banner ID
+     * @returns Success response
+     *
+     * @example
+     * ```typescript
+     * await client.deleteBanner("banner_123");
+     * ```
+     */
+    deleteBanner(bannerId: string): Promise<SuccessResponse>;
+    /**
+     * 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);
+     * ```
+     */
+    getAnalytics(params?: GetAnalyticsParams): Promise<GetAnalyticsResponse>;
+    /**
+     * 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);
+     * });
+     * ```
+     */
+    getInventoryAudit(): Promise<ListInventoryAuditResponse>;
+    /**
+     * Get tax settings
+     *
+     * @returns Tax settings
+     *
+     * @example
+     * ```typescript
+     * const settings = await client.getTaxSettings();
+     * console.log("Tax enabled:", settings.settings.taxEnabled);
+     * ```
+     */
+    getTaxSettings(): Promise<TaxSettingsResponse>;
+    /**
+     * Update tax settings
+     *
+     * @param request - Updated settings
+     * @returns Updated tax settings
+     *
+     * @example
+     * ```typescript
+     * await client.updateTaxSettings({
+     *   taxEnabled: true,
+     *   pricesIncludeTax: false,
+     *   defaultTaxBehavior: "CHARGE"
+     * });
+     * ```
+     */
+    updateTaxSettings(request: UpdateTaxSettingsRequest): Promise<TaxSettingsResponse>;
+    /**
+     * List tax rules
+     *
+     * @returns List of tax rules
+     *
+     * @example
+     * ```typescript
+     * const rules = await client.listTaxRules();
+     * ```
+     */
+    listTaxRules(): Promise<ListTaxRulesResponse>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    createTaxRule(request: CreateTaxRuleRequest): Promise<TaxRuleResponse>;
+    /**
+     * Get tax rule details
+     *
+     * @param ruleId - Rule ID
+     * @returns Tax rule details
+     *
+     * @example
+     * ```typescript
+     * const rule = await client.getTaxRule("rule_123");
+     * ```
+     */
+    getTaxRule(ruleId: string): Promise<TaxRuleResponse>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    updateTaxRule(ruleId: string, request: UpdateTaxRuleRequest): Promise<TaxRuleResponse>;
+    /**
+     * Delete a tax rule
+     *
+     * @param ruleId - Rule ID
+     * @returns Success response
+     *
+     * @example
+     * ```typescript
+     * await client.deleteTaxRule("rule_123");
+     * ```
+     */
+    deleteTaxRule(ruleId: string): Promise<SuccessResponse>;
+    /**
+     * List tax nexus locations
+     *
+     * @returns List of nexus locations
+     *
+     * @example
+     * ```typescript
+     * const nexus = await client.listTaxNexus();
+     * ```
+     */
+    listTaxNexus(): Promise<ListTaxNexusResponse>;
+    /**
+     * 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"
+     * });
+     * ```
+     */
+    createTaxNexus(request: CreateTaxNexusRequest): Promise<TaxNexusResponse>;
+    /**
+     * 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"
+     * });
+     * ```
+     */
+    updateTaxNexus(nexusId: string, request: UpdateTaxNexusRequest): Promise<TaxNexusResponse>;
+    /**
+     * Delete a tax nexus location
+     *
+     * @param nexusId - Nexus ID
+     * @returns Success response
+     *
+     * @example
+     * ```typescript
+     * await client.deleteTaxNexus("nexus_123");
+     * ```
+     */
+    deleteTaxNexus(nexusId: string): Promise<SuccessResponse>;
+    /**
+     * 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 });
+     * ```
+     */
+    listTaxReports(params?: ListTaxReportsParams): Promise<ListTaxReportsResponse>;
+    /**
+     * 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
+     * });
+     * ```
+     */
+    generateTaxReport(request: GenerateTaxReportRequest): Promise<TaxReportResponse>;
+    /**
+     * 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);
+     * ```
+     */
+    getTaxReport(reportId: string): Promise<GetTaxReportResponse>;
+    /**
+     * Update tax report status
+     *
+     * @param reportId - Report ID
+     * @param request - Status update
+     * @returns Updated report
+     *
+     * @example
+     * ```typescript
+     * await client.updateTaxReportStatus("report_123", {
+     *   status: "FINALIZED"
+     * });
+     * ```
+     */
+    updateTaxReportStatus(reportId: string, request: UpdateTaxReportStatusRequest): Promise<TaxReportResponse>;
+    /**
+     * 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
+     * ```
+     */
+    exportTaxReport(reportId: string): Promise<string>;
+}
+
+/**
+ * Ecommerce API Error Utilities
+ *
+ * This module contains error handling utilities for the ecommerce API.
+ */
+/**
+ * Ecommerce API error class
+ */
+declare class EcommerceApiError extends Error {
+    /** HTTP status code */
+    statusCode?: number;
+    /** Response data */
+    data?: any;
+    /** Is network error */
+    isNetworkError: boolean;
+    /** Is timeout error */
+    isTimeoutError: boolean;
+    /** Is authentication error */
+    isAuthError: boolean;
+    constructor(message: string, statusCode?: number, data?: any, isNetworkError?: boolean, isTimeoutError?: boolean);
+}
+/**
+ * Parse error from axios error or API response
+ */
+declare function parseError(error: any): EcommerceApiError;
+/**
+ * Check if error is retryable
+ */
+declare function isRetryableError(error: EcommerceApiError): boolean;
+
+/**
+ * Ecommerce API Helper Utilities
+ *
+ * This module contains helper functions for the ecommerce API.
+ */
+/**
+ * Build query string from params object
+ */
+declare function buildQueryString(params: Record<string, any>): string;
+/**
+ * Sleep for specified milliseconds
+ */
+declare function sleep(ms: number): Promise<void>;
+/**
+ * Calculate exponential backoff delay
+ */
+declare function getBackoffDelay(attempt: number, baseDelay?: number): number;
+/**
+ * Retry function with exponential backoff
+ */
+declare function retryWithBackoff<T>(fn: () => Promise<T>, maxRetries?: number, baseDelay?: number, shouldRetry?: (error: any) => boolean): Promise<T>;
+/**
+ * Format price for display
+ */
+declare function formatPrice(price: string | number, decimals?: number): string;
+/**
+ * Validate email address
+ */
+declare function isValidEmail(email: string): boolean;
+/**
+ * Validate Ethereum address
+ */
+declare function isValidAddress(address: string): boolean;
+/**
+ * Truncate address for display
+ */
+declare function truncateAddress(address: string, start?: number, end?: number): string;
+/**
+ * Calculate discount amount
+ */
+declare function calculateDiscountAmount(price: number, discountType: "PERCENTAGE" | "FIXED_AMOUNT", discountValue: number): number;
+/**
+ * Calculate final price after discount
+ */
+declare function calculateFinalPrice(price: number, discountType: "PERCENTAGE" | "FIXED_AMOUNT", discountValue: number): number;
+
+export { type ActiveFlashSalesResponse, type AnalyticsOverview, type ApiResponse, type AppliedDiscount, type Banner, type BannerResponse, BannerType, BaseEcommerceClient, type BaseEntity, type CalculateCartDiscountsRequest, type CalculateCartDiscountsResponse, type CalculateTaxRequest, type CalculateTaxResponse, type CartItem, type ConfirmEscrowDepositResponse, type Coupon, type CouponResponse, type CouponUsage, type CreateBannerRequest, type CreateCouponRequest, type CreateFlashSaleRequest, type CreateOrderEventRequest, type CreateOrderEventResponse, type CreateOrderRequest, type CreateOrderResponse, type CreateProductRequest, type CreateProductVariantRequest, type CreateReviewRequest, type CreateShippingMethodRequest, type CreateTaxNexusRequest, type CreateTaxRuleRequest, CustomerEcommerceClient, type CustomerMessagesResponse, type CustomerSummary, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, type EcommerceClientConfig, type FlashSale, type FlashSaleItem, type FlashSaleItemInput, type GenerateTaxReportRequest, type GetAnalyticsParams, type GetAnalyticsResponse, type GetCouponResponse, type GetOrderResponse, type GetProductMetricsResponse, type GetProductResponse, type GetTaxReportResponse, InventoryAuditAction, type InventoryAuditEntry, type ListActiveBannersParams, type ListActiveFlashSalesParams, type ListBannersResponse, type ListCouponsResponse, type ListCustomersParams, type ListCustomersResponse, type ListInventoryAuditResponse, type ListMediaAssetsResponse, type ListMessagesResponse, type ListOrdersParams, type ListOrdersResponse, type ListProductVariantsResponse, type ListProductsParams, type ListProductsResponse, type ListReturnsResponse, type ListReviewsParams, type ListReviewsResponse, type ListShipmentsResponse, type ListShippingAddressesResponse, type ListShippingMethodsResponse, type ListTaxNexusResponse, type ListTaxReportsParams, type ListTaxReportsResponse, type ListTaxRulesResponse, type MediaAsset, type MediaAssetResponse, type Merchant, MerchantEcommerceClient, type MerchantProfileRequest, type MerchantProfileResponse, MerchantStatus, type Message, type MessageResponse, type MessageStatsResponse, type Order, type OrderEvent, type OrderItem, type OrderReceiptResponse, OrderStatus, type OrdersByStatus, type PaginatedResponse, type PaginationParams, type Payment, PaymentMethod, PaymentStatus, type Product, type ProductDimensions, type ProductDiscountsResponse, type ProductMetrics, type ProductResponse, type ProductReview, ProductSortBy, type ProductVariant, type ProductVariantResponse, type RecentOrderSummary, type RespondToReviewRequest, type Return, type ReturnItem, type ReturnResponse, ReturnStatus, type RevenueByDay, type ReviewResponse, ReviewSortBy, ReviewStatus, type SendMessageRequest, type Settlement, type Shipment, type ShipmentResponse, ShipmentStatus, type ShippingAddress, type ShippingAddressRequest, type ShippingAddressResponse, type ShippingMethod, type ShippingMethodResponse, SortOrder, type SuccessResponse, TaxBehavior, type TaxBreakdownItem, type TaxNexus, type TaxNexusResponse, type TaxReport, type TaxReportDetails, TaxReportPeriodType, type TaxReportResponse, TaxReportStatus, type TaxRule, type TaxRuleResponse, type TaxSettings, type TaxSettingsResponse, TaxType, type TopProduct, type TrackBannerRequest, type UpdateBannerRequest, type UpdateCouponRequest, type UpdateFlashSaleRequest, type UpdateOrderResponse, type UpdateOrderStatusRequest, type UpdateProductRequest, type UpdateProductVariantRequest, type UpdateShipmentRequest, type UpdateShippingMethodRequest, type UpdateTaxNexusRequest, type UpdateTaxReportStatusRequest, type UpdateTaxRuleRequest, type UpdateTaxSettingsRequest, type UserShippingAddress, type ValidateDiscountRequest, type ValidateDiscountResponse, buildQueryString, calculateDiscountAmount, calculateFinalPrice, formatPrice, getBackoffDelay, isRetryableError, isValidAddress, isValidEmail, parseError, retryWithBackoff, sleep, truncateAddress };