@basedone/core 0.1.10 → 0.2.0

package/lib/ecommerce/client/merchant.ts

@@ -0,0 +1,1341 @@
+/**
+ * Merchant Ecommerce API Client
+ * 
+ * This module provides methods for merchant operations including product management,
+ * order fulfillment, customer management, analytics, and more.
+ */
+
+import { BaseEcommerceClient } from "./base";
+import { buildQueryString } from "../utils/helpers";
+import type {
+  // Request types
+  MerchantProfileRequest,
+  CreateProductRequest,
+  UpdateProductRequest,
+  CreateProductVariantRequest,
+  UpdateProductVariantRequest,
+  ListOrdersParams,
+  UpdateOrderStatusRequest,
+  CreateOrderEventRequest,
+  ListCustomersParams,
+  CreateCouponRequest,
+  UpdateCouponRequest,
+  CreateShippingMethodRequest,
+  UpdateShippingMethodRequest,
+  UpdateShipmentRequest,
+  CreateBannerRequest,
+  UpdateBannerRequest,
+  SendMessageRequest,
+  UpdateTaxSettingsRequest,
+  CreateTaxRuleRequest,
+  UpdateTaxRuleRequest,
+  CreateTaxNexusRequest,
+  UpdateTaxNexusRequest,
+  GenerateTaxReportRequest,
+  UpdateTaxReportStatusRequest,
+  ListTaxReportsParams,
+  GetAnalyticsParams,
+  RespondToReviewRequest,
+  PaginationParams,
+  
+  // Response types
+  MerchantProfileResponse,
+  ListProductsResponse,
+  ProductResponse,
+  GetProductResponse,
+  ListProductVariantsResponse,
+  ProductVariantResponse,
+  ListOrdersResponse,
+  GetOrderResponse,
+  UpdateOrderResponse,
+  CreateOrderEventResponse,
+  ListCustomersResponse,
+  ListCouponsResponse,
+  CouponResponse,
+  GetCouponResponse,
+  ListShippingMethodsResponse,
+  ShippingMethodResponse,
+  ListShipmentsResponse,
+  ShipmentResponse,
+  ListReturnsResponse,
+  ReturnResponse,
+  ListReviewsResponse,
+  ReviewResponse,
+  ListBannersResponse,
+  BannerResponse,
+  ListMediaAssetsResponse,
+  MediaAssetResponse,
+  ListMessagesResponse,
+  MessageResponse,
+  GetAnalyticsResponse,
+  GetProductMetricsResponse,
+  ListInventoryAuditResponse,
+  TaxSettingsResponse,
+  ListTaxRulesResponse,
+  TaxRuleResponse,
+  ListTaxNexusResponse,
+  TaxNexusResponse,
+  ListTaxReportsResponse,
+  GetTaxReportResponse,
+  TaxReportResponse,
+  SuccessResponse,
+} from "../types";
+
+/**
+ * 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" });
+ * ```
+ */
+export class MerchantEcommerceClient extends BaseEcommerceClient {
+  
+  // ============================================================================
+  // Profile Management
+  // ============================================================================
+  
+  /**
+   * Get merchant profile
+   * 
+   * @returns Merchant profile
+   * 
+   * @example
+   * ```typescript
+   * const profile = await client.getMerchantProfile();
+   * console.log(profile.merchant.name);
+   * ```
+   */
+  async getMerchantProfile(): Promise<MerchantProfileResponse> {
+    return this.get("/api/marketplace/merchant/profile");
+  }
+  
+  /**
+   * Get merchant profile (alias for getMerchantProfile)
+   * 
+   * @returns Merchant profile
+   * 
+   * @example
+   * ```typescript
+   * const profile = await client.getProfile();
+   * console.log(profile.merchant.name);
+   * ```
+   */
+  async getProfile(): Promise<MerchantProfileResponse> {
+    return this.getMerchantProfile();
+  }
+  
+  /**
+   * Create or update merchant profile
+   * 
+   * @param request - Profile data
+   * @returns Updated merchant profile
+   * 
+   * @example
+   * ```typescript
+   * const profile = await client.upsertMerchantProfile({
+   *   name: "My Store",
+   *   description: "We sell great products",
+   *   payoutAddress: "0x1234..."
+   * });
+   * ```
+   */
+  async upsertMerchantProfile(request: MerchantProfileRequest): Promise<MerchantProfileResponse> {
+    return this.post("/api/marketplace/merchant/profile", request);
+  }
+  
+  // ============================================================================
+  // Products Management
+  // ============================================================================
+  
+  /**
+   * List merchant's products
+   * 
+   * @param params - Query parameters
+   * @returns Paginated list of products
+   * 
+   * @example
+   * ```typescript
+   * const products = await client.listMerchantProducts({ limit: 20, offset: 0 });
+   * ```
+   */
+  async listMerchantProducts(params?: PaginationParams): Promise<ListProductsResponse> {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/merchant/products${queryString}`);
+  }
+  
+  /**
+   * Get a single product by ID
+   * 
+   * @param productId - Product ID
+   * @returns Product details
+   * 
+   * @example
+   * ```typescript
+   * const product = await client.getProduct("prod_123");
+   * console.log(product.product?.title, product.product?.priceUSDC);
+   * ```
+   */
+  async getProduct(productId: string): Promise<GetProductResponse> {
+    return this.get(`/api/marketplace/products/${productId}`);
+  }
+  
+  /**
+   * Create a new product
+   * 
+   * @param request - Product data
+   * @returns Created product
+   * 
+   * @example
+   * ```typescript
+   * const product = await client.createProduct({
+   *   title: "Awesome Product",
+   *   images: ["https://..."],
+   *   priceUSDC: 49.99,
+   *   inventory: 50,
+   *   category: "electronics",
+   *   moq: 1
+   * });
+   * ```
+   */
+  async createProduct(request: CreateProductRequest): Promise<ProductResponse> {
+    return this.post("/api/marketplace/merchant/products", request);
+  }
+  
+  /**
+   * Update a product
+   * 
+   * @param productId - Product ID
+   * @param request - Updated product data
+   * @returns Updated product
+   * 
+   * @example
+   * ```typescript
+   * const product = await client.updateProduct("prod_123", {
+   *   priceUSDC: 39.99,
+   *   inventory: 75
+   * });
+   * ```
+   */
+  async updateProduct(productId: string, request: UpdateProductRequest): Promise<ProductResponse> {
+    return this.put(`/api/marketplace/products/${productId}`, request);
+  }
+  
+  /**
+   * Delete a product
+   * 
+   * @param productId - Product ID
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.deleteProduct("prod_123");
+   * ```
+   */
+  async deleteProduct(productId: string): Promise<SuccessResponse> {
+    return this.delete(`/api/marketplace/products/${productId}`);
+  }
+  
+  /**
+   * Toggle product featured status
+   * 
+   * @param productId - Product ID
+   * @param featured - Featured status
+   * @returns Updated product
+   * 
+   * @example
+   * ```typescript
+   * await client.setProductFeatured("prod_123", true);
+   * ```
+   */
+  async setProductFeatured(productId: string, featured: boolean): Promise<ProductResponse> {
+    return this.patch(`/api/marketplace/merchant/products/${productId}/featured`, { featured });
+  }
+  
+  /**
+   * List product variants
+   * 
+   * @param productId - Product ID
+   * @returns List of variants
+   * 
+   * @example
+   * ```typescript
+   * const variants = await client.listProductVariants("prod_123");
+   * ```
+   */
+  async listProductVariants(productId: string): Promise<ListProductVariantsResponse> {
+    return this.get(`/api/marketplace/merchant/products/${productId}/variants`);
+  }
+  
+  /**
+   * Create a product variant
+   * 
+   * @param productId - Product ID
+   * @param request - Variant data
+   * @returns Created variant
+   * 
+   * @example
+   * ```typescript
+   * const variant = await client.createProductVariant("prod_123", {
+   *   name: "Large / Red",
+   *   attributes: { size: "L", color: "Red" },
+   *   priceUSDC: 54.99,
+   *   inventory: 20
+   * });
+   * ```
+   */
+  async createProductVariant(
+    productId: string,
+    request: CreateProductVariantRequest
+  ): Promise<ProductVariantResponse> {
+    return this.post(`/api/marketplace/merchant/products/${productId}/variants`, request);
+  }
+  
+  /**
+   * Get a product variant
+   * 
+   * @param productId - Product ID
+   * @param variantId - Variant ID
+   * @returns Variant details
+   * 
+   * @example
+   * ```typescript
+   * const variant = await client.getProductVariant("prod_123", "var_456");
+   * ```
+   */
+  async getProductVariant(productId: string, variantId: string): Promise<ProductVariantResponse> {
+    return this.get(`/api/marketplace/merchant/products/${productId}/variants/${variantId}`);
+  }
+  
+  /**
+   * Update a product variant
+   * 
+   * @param productId - Product ID
+   * @param variantId - Variant ID
+   * @param request - Updated variant data
+   * @returns Updated variant
+   * 
+   * @example
+   * ```typescript
+   * const variant = await client.updateProductVariant("prod_123", "var_456", {
+   *   inventory: 30
+   * });
+   * ```
+   */
+  async updateProductVariant(
+    productId: string,
+    variantId: string,
+    request: UpdateProductVariantRequest
+  ): Promise<ProductVariantResponse> {
+    return this.put(`/api/marketplace/merchant/products/${productId}/variants/${variantId}`, request);
+  }
+  
+  /**
+   * Delete a product variant
+   * 
+   * @param productId - Product ID
+   * @param variantId - Variant ID
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.deleteProductVariant("prod_123", "var_456");
+   * ```
+   */
+  async deleteProductVariant(productId: string, variantId: string): Promise<SuccessResponse> {
+    return this.delete(`/api/marketplace/merchant/products/${productId}/variants/${variantId}`);
+  }
+  
+  /**
+   * Get product metrics
+   * 
+   * @returns Product performance metrics
+   * 
+   * @example
+   * ```typescript
+   * const metrics = await client.getProductMetrics();
+   * console.log("Total revenue:", metrics.summary.totalRevenue);
+   * ```
+   */
+  async getProductMetrics(): Promise<GetProductMetricsResponse> {
+    return this.get("/api/marketplace/merchant/products/metrics");
+  }
+  
+  // ============================================================================
+  // Orders Management
+  // ============================================================================
+  
+  /**
+   * List merchant's orders
+   * 
+   * @param params - Query parameters
+   * @returns Paginated list of orders
+   * 
+   * @example
+   * ```typescript
+   * const orders = await client.listMerchantOrders({ limit: 20, offset: 0 });
+   * ```
+   */
+  async listMerchantOrders(params?: ListOrdersParams): Promise<ListOrdersResponse> {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/merchant/orders${queryString}`);
+  }
+  
+  /**
+   * Get order details
+   * 
+   * @param orderId - Order ID
+   * @returns Order details with full information
+   * 
+   * @example
+   * ```typescript
+   * const order = await client.getMerchantOrder("ord_123");
+   * console.log(order.order.status, order.order.items);
+   * ```
+   */
+  async getMerchantOrder(orderId: string): Promise<GetOrderResponse> {
+    return this.get(`/api/marketplace/merchant/orders/${orderId}`);
+  }
+  
+  /**
+   * Update order status
+   * 
+   * @param orderId - Order ID
+   * @param request - Status update request
+   * @returns Updated order
+   * 
+   * @example
+   * ```typescript
+   * // Accept order
+   * await client.updateOrderStatus("ord_123", {
+   *   status: "MERCHANT_ACCEPTED"
+   * });
+   * 
+   * // Mark as shipped
+   * await client.updateOrderStatus("ord_123", {
+   *   status: "SHIPPED",
+   *   tracking: {
+   *     trackingNumber: "1Z999AA10123456784",
+   *     carrier: "UPS"
+   *   }
+   * });
+   * ```
+   */
+  async updateOrderStatus(
+    orderId: string,
+    request: UpdateOrderStatusRequest
+  ): Promise<UpdateOrderResponse> {
+    return this.patch(`/api/marketplace/merchant/orders/${orderId}`, request);
+  }
+  
+  /**
+   * Create a custom order event
+   * 
+   * @param orderId - Order ID
+   * @param request - Event data
+   * @returns Created event
+   * 
+   * @example
+   * ```typescript
+   * await client.createOrderEvent("ord_123", {
+   *   eventType: "CUSTOM",
+   *   title: "Package delayed",
+   *   description: "Shipment delayed due to weather"
+   * });
+   * ```
+   */
+  async createOrderEvent(
+    orderId: string,
+    request: CreateOrderEventRequest
+  ): Promise<CreateOrderEventResponse> {
+    return this.post(`/api/marketplace/merchant/orders/${orderId}/events`, request);
+  }
+  
+  // ============================================================================
+  // Customers Management
+  // ============================================================================
+  
+  /**
+   * List customers with order history and stats
+   * 
+   * @param params - Query parameters
+   * @returns Paginated list of customers
+   * 
+   * @example
+   * ```typescript
+   * const customers = await client.listCustomers({ limit: 50, offset: 0 });
+   * customers.items.forEach(c => {
+   *   console.log(c.username, "Total spent:", c.totalSpent);
+   * });
+   * ```
+   */
+  async listCustomers(params?: ListCustomersParams): Promise<ListCustomersResponse> {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/merchant/customers${queryString}`);
+  }
+  
+  // ============================================================================
+  // Coupons & Discounts Management
+  // ============================================================================
+  
+  /**
+   * List merchant's coupons
+   * 
+   * @returns List of coupons with stats
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.listCoupons();
+   * console.log("Total coupons:", result.stats.total);
+   * console.log("Active:", result.stats.active);
+   * ```
+   */
+  async listCoupons(): Promise<ListCouponsResponse> {
+    return this.get("/api/marketplace/merchant/coupons");
+  }
+  
+  /**
+   * Create a coupon
+   * 
+   * @param request - Coupon data
+   * @returns Created coupon
+   * 
+   * @example
+   * ```typescript
+   * const coupon = await client.createCoupon({
+   *   code: "SAVE20",
+   *   discountType: "PERCENTAGE",
+   *   discountValue: 20,
+   *   startsAt: "2025-01-01T00:00:00Z",
+   *   expiresAt: "2025-12-31T23:59:59Z",
+   *   maxUses: 100
+   * });
+   * ```
+   */
+  async createCoupon(request: CreateCouponRequest): Promise<CouponResponse> {
+    return this.post("/api/marketplace/merchant/coupons", request);
+  }
+  
+  /**
+   * Get coupon details with usage history
+   * 
+   * @param couponId - Coupon ID
+   * @returns Coupon with usages
+   * 
+   * @example
+   * ```typescript
+   * const coupon = await client.getCoupon("coupon_123");
+   * console.log("Used", coupon.coupon.usedCount, "times");
+   * ```
+   */
+  async getCoupon(couponId: string): Promise<GetCouponResponse> {
+    return this.get(`/api/marketplace/merchant/coupons/${couponId}`);
+  }
+  
+  /**
+   * Update a coupon
+   * 
+   * @param couponId - Coupon ID
+   * @param request - Updated coupon data
+   * @returns Updated coupon
+   * 
+   * @example
+   * ```typescript
+   * await client.updateCoupon("coupon_123", {
+   *   isActive: false
+   * });
+   * ```
+   */
+  async updateCoupon(couponId: string, request: UpdateCouponRequest): Promise<CouponResponse> {
+    return this.put(`/api/marketplace/merchant/coupons/${couponId}`, request);
+  }
+  
+  /**
+   * Delete a coupon
+   * 
+   * @param couponId - Coupon ID
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.deleteCoupon("coupon_123");
+   * ```
+   */
+  async deleteCoupon(couponId: string): Promise<SuccessResponse> {
+    return this.delete(`/api/marketplace/merchant/coupons/${couponId}`);
+  }
+  
+  // ============================================================================
+  // Shipping & Fulfillment
+  // ============================================================================
+  
+  /**
+   * List shipping methods
+   * 
+   * @returns List of shipping methods
+   * 
+   * @example
+   * ```typescript
+   * const methods = await client.listShippingMethods();
+   * ```
+   */
+  async listShippingMethods(): Promise<ListShippingMethodsResponse> {
+    return this.get("/api/marketplace/merchant/shipping/methods");
+  }
+  
+  /**
+   * Create a shipping method
+   * 
+   * @param request - Shipping method data
+   * @returns Created method
+   * 
+   * @example
+   * ```typescript
+   * const method = await client.createShippingMethod({
+   *   name: "Standard Shipping",
+   *   carrier: "USPS",
+   *   estimatedDays: "3-5 business days",
+   *   flatRate: 5.99
+   * });
+   * ```
+   */
+  async createShippingMethod(
+    request: CreateShippingMethodRequest
+  ): Promise<ShippingMethodResponse> {
+    return this.post("/api/marketplace/merchant/shipping/methods", request);
+  }
+  
+  /**
+   * Update a shipping method
+   * 
+   * @param methodId - Method ID
+   * @param request - Updated method data
+   * @returns Updated method
+   * 
+   * @example
+   * ```typescript
+   * await client.updateShippingMethod("method_123", {
+   *   flatRate: 6.99
+   * });
+   * ```
+   */
+  async updateShippingMethod(
+    methodId: string,
+    request: UpdateShippingMethodRequest
+  ): Promise<ShippingMethodResponse> {
+    return this.put(`/api/marketplace/merchant/shipping/methods/${methodId}`, request);
+  }
+  
+  /**
+   * Delete a shipping method
+   * 
+   * @param methodId - Method ID
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.deleteShippingMethod("method_123");
+   * ```
+   */
+  async deleteShippingMethod(methodId: string): Promise<SuccessResponse> {
+    return this.delete(`/api/marketplace/merchant/shipping/methods/${methodId}`);
+  }
+  
+  /**
+   * List shipments
+   * 
+   * @returns List of shipments for merchant's orders
+   * 
+   * @example
+   * ```typescript
+   * const shipments = await client.listShipments();
+   * ```
+   */
+  async listShipments(): Promise<ListShipmentsResponse> {
+    return this.get("/api/marketplace/merchant/shipping/shipments");
+  }
+  
+  /**
+   * Update shipment status and tracking
+   * 
+   * @param shipmentId - Shipment ID
+   * @param request - Updated shipment data
+   * @returns Updated shipment
+   * 
+   * @example
+   * ```typescript
+   * await client.updateShipment("ship_123", {
+   *   status: "SHIPPED",
+   *   trackingNumber: "1Z999AA10123456784",
+   *   carrier: "UPS"
+   * });
+   * ```
+   */
+  async updateShipment(shipmentId: string, request: UpdateShipmentRequest): Promise<ShipmentResponse> {
+    return this.patch(`/api/marketplace/merchant/shipping/shipments/${shipmentId}`, request);
+  }
+  
+  // ============================================================================
+  // Returns & Refunds
+  // ============================================================================
+  
+  /**
+   * List returns
+   * 
+   * @returns List of returns for merchant's orders
+   * 
+   * @example
+   * ```typescript
+   * const returns = await client.listReturns();
+   * ```
+   */
+  async listReturns(): Promise<ListReturnsResponse> {
+    return this.get("/api/marketplace/merchant/returns");
+  }
+  
+  /**
+   * Approve a return request
+   * 
+   * @param returnId - Return ID
+   * @returns Updated return
+   * 
+   * @example
+   * ```typescript
+   * await client.approveReturn("return_123");
+   * ```
+   */
+  async approveReturn(returnId: string): Promise<ReturnResponse> {
+    return this.post(`/api/marketplace/merchant/returns/${returnId}/approve`);
+  }
+  
+  /**
+   * Reject a return request
+   * 
+   * @param returnId - Return ID
+   * @returns Updated return
+   * 
+   * @example
+   * ```typescript
+   * await client.rejectReturn("return_123");
+   * ```
+   */
+  async rejectReturn(returnId: string): Promise<ReturnResponse> {
+    return this.post(`/api/marketplace/merchant/returns/${returnId}/reject`);
+  }
+  
+  /**
+   * Mark return as received
+   * 
+   * @param returnId - Return ID
+   * @returns Updated return
+   * 
+   * @example
+   * ```typescript
+   * await client.markReturnReceived("return_123");
+   * ```
+   */
+  async markReturnReceived(returnId: string): Promise<ReturnResponse> {
+    return this.post(`/api/marketplace/merchant/returns/${returnId}/received`);
+  }
+  
+  /**
+   * Process refund for return
+   * 
+   * @param returnId - Return ID
+   * @returns Updated return
+   * 
+   * @example
+   * ```typescript
+   * await client.processRefund("return_123");
+   * ```
+   */
+  async processRefund(returnId: string): Promise<ReturnResponse> {
+    return this.post(`/api/marketplace/merchant/returns/${returnId}/refunded`);
+  }
+  
+  // ============================================================================
+  // Reviews Management
+  // ============================================================================
+  
+  /**
+   * List reviews for merchant's products
+   * 
+   * @returns List of reviews
+   * 
+   * @example
+   * ```typescript
+   * const reviews = await client.listMerchantReviews();
+   * ```
+   */
+  async listMerchantReviews(): Promise<ListReviewsResponse> {
+    return this.get("/api/marketplace/merchant/reviews");
+  }
+  
+  /**
+   * Respond to a review
+   * 
+   * @param reviewId - Review ID
+   * @param request - Response data
+   * @returns Updated review
+   * 
+   * @example
+   * ```typescript
+   * await client.respondToReview("review_123", {
+   *   merchantResponse: "Thank you for your feedback!"
+   * });
+   * ```
+   */
+  async respondToReview(reviewId: string, request: RespondToReviewRequest): Promise<ReviewResponse> {
+    return this.post(`/api/marketplace/merchant/reviews/${reviewId}/respond`, request);
+  }
+  
+  /**
+   * Flag a review as inappropriate
+   * 
+   * @param reviewId - Review ID
+   * @returns Updated review
+   * 
+   * @example
+   * ```typescript
+   * await client.flagReview("review_123");
+   * ```
+   */
+  async flagReview(reviewId: string): Promise<ReviewResponse> {
+    return this.post(`/api/marketplace/merchant/reviews/${reviewId}/flag`);
+  }
+  
+  // ============================================================================
+  // Messages
+  // ============================================================================
+  
+  /**
+   * List messages/conversations
+   * 
+   * @returns List of conversations grouped by order
+   * 
+   * @example
+   * ```typescript
+   * const messages = await client.listMessages();
+   * console.log("Unread:", messages.stats.unread);
+   * ```
+   */
+  async listMessages(): Promise<ListMessagesResponse> {
+    return this.get("/api/marketplace/merchant/messages");
+  }
+  
+  /**
+   * Send a message to customer
+   * 
+   * @param request - Message data
+   * @returns Sent message
+   * 
+   * @example
+   * ```typescript
+   * await client.sendMessage({
+   *   orderId: "ord_123",
+   *   recipientId: "user_456",
+   *   message: "Your order has been shipped!"
+   * });
+   * ```
+   */
+  async sendMessage(request: SendMessageRequest): Promise<MessageResponse> {
+    return this.post("/api/marketplace/merchant/messages/send", request);
+  }
+  
+  /**
+   * Mark message as read
+   * 
+   * @param messageId - Message ID
+   * @returns Updated message
+   * 
+   * @example
+   * ```typescript
+   * await client.markMessageRead("msg_123");
+   * ```
+   */
+  async markMessageRead(messageId: string): Promise<MessageResponse> {
+    return this.patch(`/api/marketplace/merchant/messages/${messageId}/read`);
+  }
+  
+  // ============================================================================
+  // Media Library
+  // ============================================================================
+  
+  /**
+   * List media assets
+   * 
+   * @param params - Query parameters
+   * @returns Paginated list of media assets
+   * 
+   * @example
+   * ```typescript
+   * const media = await client.listMediaAssets({ limit: 50, offset: 0 });
+   * ```
+   */
+  async listMediaAssets(params?: PaginationParams): Promise<ListMediaAssetsResponse> {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/merchant/media${queryString}`);
+  }
+  
+  /**
+   * Upload a media asset
+   * 
+   * @param file - File to upload (max 10MB, images only)
+   * @returns Uploaded asset
+   * 
+   * @example
+   * ```typescript
+   * const formData = new FormData();
+   * formData.append("file", imageFile);
+   * 
+   * const asset = await client.uploadMediaAsset(formData);
+   * console.log("Uploaded:", asset.asset.blobUrl);
+   * ```
+   */
+  async uploadMediaAsset(formData: FormData): Promise<MediaAssetResponse> {
+    return this.post("/api/marketplace/merchant/media/upload", formData, {
+      headers: { "Content-Type": "multipart/form-data" },
+    });
+  }
+  
+  /**
+   * Delete a media asset
+   * 
+   * @param assetId - Asset ID
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.deleteMediaAsset("asset_123");
+   * ```
+   */
+  async deleteMediaAsset(assetId: string): Promise<SuccessResponse> {
+    return this.delete(`/api/marketplace/merchant/media?id=${assetId}`);
+  }
+  
+  // ============================================================================
+  // Banners
+  // ============================================================================
+  
+  /**
+   * List merchant's banners
+   * 
+   * @returns List of banners
+   * 
+   * @example
+   * ```typescript
+   * const banners = await client.listMerchantBanners();
+   * ```
+   */
+  async listMerchantBanners(): Promise<ListBannersResponse> {
+    return this.get("/api/marketplace/merchant/banners");
+  }
+  
+  /**
+   * Create a promotional banner
+   * 
+   * @param request - Banner data
+   * @returns Created banner
+   * 
+   * @example
+   * ```typescript
+   * const banner = await client.createBanner({
+   *   title: "Summer Sale",
+   *   imageUrl: "https://...",
+   *   linkUrl: "/products?category=summer",
+   *   ctaText: "Shop Now",
+   *   priority: 10
+   * });
+   * ```
+   */
+  async createBanner(request: CreateBannerRequest): Promise<BannerResponse> {
+    return this.post("/api/marketplace/merchant/banners", request);
+  }
+  
+  /**
+   * Get banner details
+   * 
+   * @param bannerId - Banner ID
+   * @returns Banner details
+   * 
+   * @example
+   * ```typescript
+   * const banner = await client.getBanner("banner_123");
+   * ```
+   */
+  async getBanner(bannerId: string): Promise<BannerResponse> {
+    return this.get(`/api/marketplace/merchant/banners/${bannerId}`);
+  }
+  
+  /**
+   * Update a banner
+   * 
+   * @param bannerId - Banner ID
+   * @param request - Updated banner data
+   * @returns Updated banner
+   * 
+   * @example
+   * ```typescript
+   * await client.updateBanner("banner_123", {
+   *   isActive: false
+   * });
+   * ```
+   */
+  async updateBanner(bannerId: string, request: UpdateBannerRequest): Promise<BannerResponse> {
+    return this.put(`/api/marketplace/merchant/banners/${bannerId}`, request);
+  }
+  
+  /**
+   * Delete a banner
+   * 
+   * @param bannerId - Banner ID
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.deleteBanner("banner_123");
+   * ```
+   */
+  async deleteBanner(bannerId: string): Promise<SuccessResponse> {
+    return this.delete(`/api/marketplace/merchant/banners/${bannerId}`);
+  }
+  
+  // ============================================================================
+  // Analytics
+  // ============================================================================
+  
+  /**
+   * Get merchant analytics
+   * 
+   * @param params - Query parameters
+   * @returns Analytics data with overview, charts, and insights
+   * 
+   * @example
+   * ```typescript
+   * const analytics = await client.getAnalytics({ range: "30days" });
+   * console.log("Revenue:", analytics.overview.totalRevenue);
+   * console.log("Orders:", analytics.overview.totalOrders);
+   * ```
+   */
+  async getAnalytics(params?: GetAnalyticsParams): Promise<GetAnalyticsResponse> {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/merchant/analytics${queryString}`);
+  }
+  
+  // ============================================================================
+  // Inventory
+  // ============================================================================
+  
+  /**
+   * Get inventory audit log
+   * 
+   * @returns Recent inventory audit entries (last 500)
+   * 
+   * @example
+   * ```typescript
+   * const audit = await client.getInventoryAudit();
+   * audit.entries.forEach(e => {
+   *   console.log(e.action, e.product.title, e.changeAmount);
+   * });
+   * ```
+   */
+  async getInventoryAudit(): Promise<ListInventoryAuditResponse> {
+    return this.get("/api/marketplace/merchant/inventory/audit");
+  }
+  
+  // ============================================================================
+  // Tax Management
+  // ============================================================================
+  
+  /**
+   * Get tax settings
+   * 
+   * @returns Tax settings
+   * 
+   * @example
+   * ```typescript
+   * const settings = await client.getTaxSettings();
+   * console.log("Tax enabled:", settings.settings.taxEnabled);
+   * ```
+   */
+  async getTaxSettings(): Promise<TaxSettingsResponse> {
+    return this.get("/api/marketplace/merchant/tax-settings");
+  }
+  
+  /**
+   * Update tax settings
+   * 
+   * @param request - Updated settings
+   * @returns Updated tax settings
+   * 
+   * @example
+   * ```typescript
+   * await client.updateTaxSettings({
+   *   taxEnabled: true,
+   *   pricesIncludeTax: false,
+   *   defaultTaxBehavior: "CHARGE"
+   * });
+   * ```
+   */
+  async updateTaxSettings(request: UpdateTaxSettingsRequest): Promise<TaxSettingsResponse> {
+    return this.put("/api/marketplace/merchant/tax-settings", request);
+  }
+  
+  /**
+   * List tax rules
+   * 
+   * @returns List of tax rules
+   * 
+   * @example
+   * ```typescript
+   * const rules = await client.listTaxRules();
+   * ```
+   */
+  async listTaxRules(): Promise<ListTaxRulesResponse> {
+    return this.get("/api/marketplace/merchant/tax-rules");
+  }
+  
+  /**
+   * Create a tax rule
+   * 
+   * @param request - Tax rule data
+   * @returns Created tax rule
+   * 
+   * @example
+   * ```typescript
+   * const rule = await client.createTaxRule({
+   *   country: "US",
+   *   region: "NY",
+   *   taxType: "SALES_TAX",
+   *   taxName: "NY Sales Tax",
+   *   taxRate: 8.875
+   * });
+   * ```
+   */
+  async createTaxRule(request: CreateTaxRuleRequest): Promise<TaxRuleResponse> {
+    return this.post("/api/marketplace/merchant/tax-rules", request);
+  }
+  
+  /**
+   * Get tax rule details
+   * 
+   * @param ruleId - Rule ID
+   * @returns Tax rule details
+   * 
+   * @example
+   * ```typescript
+   * const rule = await client.getTaxRule("rule_123");
+   * ```
+   */
+  async getTaxRule(ruleId: string): Promise<TaxRuleResponse> {
+    return this.get(`/api/marketplace/merchant/tax-rules/${ruleId}`);
+  }
+  
+  /**
+   * Update a tax rule
+   * 
+   * @param ruleId - Rule ID
+   * @param request - Updated rule data
+   * @returns Updated tax rule
+   * 
+   * @example
+   * ```typescript
+   * await client.updateTaxRule("rule_123", {
+   *   taxRate: 9.0
+   * });
+   * ```
+   */
+  async updateTaxRule(ruleId: string, request: UpdateTaxRuleRequest): Promise<TaxRuleResponse> {
+    return this.put(`/api/marketplace/merchant/tax-rules/${ruleId}`, request);
+  }
+  
+  /**
+   * Delete a tax rule
+   * 
+   * @param ruleId - Rule ID
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.deleteTaxRule("rule_123");
+   * ```
+   */
+  async deleteTaxRule(ruleId: string): Promise<SuccessResponse> {
+    return this.delete(`/api/marketplace/merchant/tax-rules/${ruleId}`);
+  }
+  
+  /**
+   * List tax nexus locations
+   * 
+   * @returns List of nexus locations
+   * 
+   * @example
+   * ```typescript
+   * const nexus = await client.listTaxNexus();
+   * ```
+   */
+  async listTaxNexus(): Promise<ListTaxNexusResponse> {
+    return this.get("/api/marketplace/merchant/tax-nexus");
+  }
+  
+  /**
+   * Add a tax nexus location
+   * 
+   * @param request - Nexus data
+   * @returns Created nexus
+   * 
+   * @example
+   * ```typescript
+   * const nexus = await client.createTaxNexus({
+   *   country: "US",
+   *   region: "CA",
+   *   registrationId: "123456789"
+   * });
+   * ```
+   */
+  async createTaxNexus(request: CreateTaxNexusRequest): Promise<TaxNexusResponse> {
+    return this.post("/api/marketplace/merchant/tax-nexus", request);
+  }
+  
+  /**
+   * Update a tax nexus location
+   * 
+   * @param nexusId - Nexus ID
+   * @param request - Updated nexus data
+   * @returns Updated nexus
+   * 
+   * @example
+   * ```typescript
+   * await client.updateTaxNexus("nexus_123", {
+   *   registrationId: "987654321"
+   * });
+   * ```
+   */
+  async updateTaxNexus(nexusId: string, request: UpdateTaxNexusRequest): Promise<TaxNexusResponse> {
+    return this.put(`/api/marketplace/merchant/tax-nexus/${nexusId}`, request);
+  }
+  
+  /**
+   * Delete a tax nexus location
+   * 
+   * @param nexusId - Nexus ID
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.deleteTaxNexus("nexus_123");
+   * ```
+   */
+  async deleteTaxNexus(nexusId: string): Promise<SuccessResponse> {
+    return this.delete(`/api/marketplace/merchant/tax-nexus/${nexusId}`);
+  }
+  
+  /**
+   * List tax reports
+   * 
+   * @param params - Query parameters
+   * @returns Paginated list of tax reports
+   * 
+   * @example
+   * ```typescript
+   * const reports = await client.listTaxReports({ limit: 20, offset: 0 });
+   * 
+   * // Get summary for a specific year
+   * const summary = await client.listTaxReports({ year: 2025 });
+   * ```
+   */
+  async listTaxReports(params?: ListTaxReportsParams): Promise<ListTaxReportsResponse> {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/merchant/tax-reports${queryString}`);
+  }
+  
+  /**
+   * Generate a tax report
+   * 
+   * @param request - Report generation request
+   * @returns Generated report
+   * 
+   * @example
+   * ```typescript
+   * const report = await client.generateTaxReport({
+   *   periodType: "MONTHLY",
+   *   year: 2025,
+   *   period: 1  // January
+   * });
+   * ```
+   */
+  async generateTaxReport(request: GenerateTaxReportRequest): Promise<TaxReportResponse> {
+    return this.post("/api/marketplace/merchant/tax-reports/generate", request);
+  }
+  
+  /**
+   * Get tax report details
+   * 
+   * @param reportId - Report ID
+   * @returns Report with detailed records
+   * 
+   * @example
+   * ```typescript
+   * const report = await client.getTaxReport("report_123");
+   * console.log("Total tax:", report.report.totalTax);
+   * ```
+   */
+  async getTaxReport(reportId: string): Promise<GetTaxReportResponse> {
+    return this.get(`/api/marketplace/merchant/tax-reports/${reportId}`);
+  }
+  
+  /**
+   * Update tax report status
+   * 
+   * @param reportId - Report ID
+   * @param request - Status update
+   * @returns Updated report
+   * 
+   * @example
+   * ```typescript
+   * await client.updateTaxReportStatus("report_123", {
+   *   status: "FINALIZED"
+   * });
+   * ```
+   */
+  async updateTaxReportStatus(
+    reportId: string,
+    request: UpdateTaxReportStatusRequest
+  ): Promise<TaxReportResponse> {
+    return this.put(`/api/marketplace/merchant/tax-reports/${reportId}`, request);
+  }
+  
+  /**
+   * Export tax report as CSV
+   * 
+   * @param reportId - Report ID
+   * @returns CSV file data
+   * 
+   * @example
+   * ```typescript
+   * const csv = await client.exportTaxReport("report_123");
+   * // Save or download the CSV
+   * ```
+   */
+  async exportTaxReport(reportId: string): Promise<string> {
+    return this.get(`/api/marketplace/merchant/tax-reports/${reportId}/export`);
+  }
+}
+