@basedone/core 0.1.10 → 0.2.1

package/lib/ecommerce/client/customer.ts

@@ -0,0 +1,639 @@
+/**
+ * Customer/End-User Ecommerce API Client
+ * 
+ * This module provides methods for customer-facing ecommerce operations including
+ * browsing products, placing orders, managing reviews, and more.
+ */
+
+import { BaseEcommerceClient } from "./base";
+import { buildQueryString } from "../utils/helpers";
+import type {
+  // Request types
+  ListProductsParams,
+  CreateOrderRequest,
+  ListOrdersParams,
+  CreateReviewRequest,
+  ListReviewsParams,
+  ShippingAddressRequest,
+  CalculateCartDiscountsRequest,
+  ValidateDiscountRequest,
+  CalculateTaxRequest,
+  ListActiveBannersParams,
+  TrackBannerRequest,
+  SendMessageRequest,
+  ListActiveFlashSalesParams,
+  
+  // Response types
+  ListProductsResponse,
+  GetProductResponse,
+  CreateOrderResponse,
+  ListOrdersResponse,
+  GetOrderResponse,
+  ConfirmEscrowDepositResponse,
+  OrderReceiptResponse,
+  ListReviewsResponse,
+  ReviewResponse,
+  ListShippingAddressesResponse,
+  ShippingAddressResponse,
+  CalculateCartDiscountsResponse,
+  ValidateDiscountResponse,
+  CalculateTaxResponse,
+  ListBannersResponse,
+  SuccessResponse,
+  ProductDiscountsResponse,
+  CustomerMessagesResponse,
+  MessageStatsResponse,
+  MessageResponse,
+  ActiveFlashSalesResponse,
+} from "../types";
+
+/**
+ * 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: { ... }
+ * });
+ * ```
+ */
+export class CustomerEcommerceClient extends BaseEcommerceClient {
+  
+  // ============================================================================
+  // Products API
+  // ============================================================================
+  
+  /**
+   * List products with filtering and pagination
+   * 
+   * @param params - Query parameters for filtering
+   * @returns Paginated list of products
+   * 
+   * @example
+   * ```typescript
+   * const products = await client.listProducts({
+   *   limit: 20,
+   *   offset: 0,
+   *   category: "electronics",
+   *   search: "laptop",
+   *   minPrice: 500,
+   *   maxPrice: 2000,
+   *   sortBy: "price_asc"
+   * });
+   * ```
+   */
+  async listProducts(params?: ListProductsParams): Promise<ListProductsResponse> {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/products${queryString}`);
+  }
+  
+  /**
+   * Get product details by ID
+   * 
+   * @param productId - Product ID
+   * @returns Product details with merchant info, variants, and reviews
+   * 
+   * @example
+   * ```typescript
+   * const product = await client.getProduct("prod_123");
+   * console.log(product.title, product.priceUSDC);
+   * ```
+   */
+  async getProduct(productId: string): Promise<GetProductResponse> {
+    return this.get(`/api/marketplace/products/${productId}`);
+  }
+  
+  /**
+   * Track product view (increment view count)
+   * 
+   * @param productId - Product ID
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.trackProductView("prod_123");
+   * ```
+   */
+  async trackProductView(productId: string): Promise<SuccessResponse> {
+    return this.post(`/api/marketplace/products/${productId}/view`);
+  }
+  
+  /**
+   * Get active automatic discounts for a product
+   * 
+   * @param productId - Product ID
+   * @returns List of applicable discounts
+   * 
+   * @example
+   * ```typescript
+   * const discounts = await client.getProductDiscounts("prod_123");
+   * discounts.discounts.forEach(d => console.log(d.description));
+   * ```
+   */
+  async getProductDiscounts(productId: string): Promise<ProductDiscountsResponse> {
+    return this.get(`/api/marketplace/products/${productId}/discounts`);
+  }
+  
+  // ============================================================================
+  // Orders API
+  // ============================================================================
+  
+  /**
+   * Create order from cart checkout
+   * 
+   * Supports multi-merchant checkout - automatically splits orders by merchant.
+   * 
+   * @param request - Order creation request
+   * @returns Created order(s) with payment instructions
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.createOrder({
+   *   items: [
+   *     { productId: "prod_123", quantity: 2 },
+   *     { productId: "prod_456", quantity: 1, variantId: "var_789" }
+   *   ],
+   *   paymentMethod: "USDC_ESCROW",
+   *   shippingAddress: {
+   *     fullName: "John Doe",
+   *     phone: "+1234567890",
+   *     addressLine1: "123 Main St",
+   *     city: "New York",
+   *     stateProvince: "NY",
+   *     postalCode: "10001",
+   *     country: "US"
+   *   },
+   *   couponCode: "SAVE10"
+   * });
+   * 
+   * // For USDC escrow, deposit to the escrow address
+   * if (result.escrow) {
+   *   console.log("Deposit", result.escrow.amountUSDC, "USDC to", result.escrow.address);
+   * }
+   * ```
+   */
+  async createOrder(request: CreateOrderRequest): Promise<CreateOrderResponse> {
+    return this.post("/api/marketplace/orders", request);
+  }
+  
+  /**
+   * List user's orders
+   * 
+   * @param params - Query parameters for filtering
+   * @returns Paginated list of orders
+   * 
+   * @example
+   * ```typescript
+   * const orders = await client.listOrders({
+   *   limit: 10,
+   *   offset: 0,
+   *   status: "SHIPPED"
+   * });
+   * ```
+   */
+  async listOrders(params?: ListOrdersParams): Promise<ListOrdersResponse> {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/orders${queryString}`);
+  }
+  
+  /**
+   * Get order details by ID
+   * 
+   * @param orderId - Order ID
+   * @returns Order details with items, payment, and shipment info
+   * 
+   * @example
+   * ```typescript
+   * const order = await client.getOrder("ord_123");
+   * console.log(order.order.status, order.order.totalUSDC);
+   * ```
+   */
+  async getOrder(orderId: string): Promise<GetOrderResponse> {
+    return this.get(`/api/marketplace/orders/${orderId}`);
+  }
+  
+  /**
+   * Confirm USDC escrow deposit for order payment
+   * 
+   * Verifies the Hyperliquid transaction and updates order status.
+   * 
+   * @param orderId - Order ID
+   * @returns Confirmation response with transaction hash
+   * 
+   * @example
+   * ```typescript
+   * // After depositing USDC to escrow address
+   * const result = await client.confirmEscrowDeposit("ord_123");
+   * console.log("Payment confirmed:", result.depositTxHash);
+   * ```
+   */
+  async confirmEscrowDeposit(orderId: string): Promise<ConfirmEscrowDepositResponse> {
+    return this.post(`/api/marketplace/orders/${orderId}/confirm-escrow-deposit`);
+  }
+  
+  /**
+   * Get order receipt
+   * 
+   * @param orderId - Order ID
+   * @returns Order receipt for download/display
+   * 
+   * @example
+   * ```typescript
+   * const receipt = await client.getOrderReceipt("ord_123");
+   * console.log("Order #", receipt.receipt.orderNumber);
+   * ```
+   */
+  async getOrderReceipt(orderId: string): Promise<OrderReceiptResponse> {
+    return this.get(`/api/marketplace/orders/${orderId}/receipt`);
+  }
+  
+  // ============================================================================
+  // Reviews API
+  // ============================================================================
+  
+  /**
+   * List reviews for a product
+   * 
+   * @param productId - Product ID
+   * @param params - Query parameters
+   * @returns Paginated list of reviews
+   * 
+   * @example
+   * ```typescript
+   * const reviews = await client.listProductReviews("prod_123", {
+   *   limit: 10,
+   *   sortBy: "highest"
+   * });
+   * ```
+   */
+  async listProductReviews(
+    productId: string,
+    params?: ListReviewsParams
+  ): Promise<ListReviewsResponse> {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/products/${productId}/reviews${queryString}`);
+  }
+  
+  /**
+   * Create a product review
+   * 
+   * Requires authenticated user who has purchased the product.
+   * 
+   * @param productId - Product ID
+   * @param request - Review creation request
+   * @returns Created review
+   * 
+   * @example
+   * ```typescript
+   * const review = await client.createReview("prod_123", {
+   *   rating: 5,
+   *   title: "Great product!",
+   *   comment: "Exactly what I needed. Fast shipping too!"
+   * });
+   * ```
+   */
+  async createReview(
+    productId: string,
+    request: CreateReviewRequest
+  ): Promise<ReviewResponse> {
+    return this.post(`/api/marketplace/products/${productId}/reviews`, request);
+  }
+  
+  // ============================================================================
+  // Shipping Addresses API
+  // ============================================================================
+  
+  /**
+   * List saved shipping addresses
+   * 
+   * @returns List of user's saved shipping addresses
+   * 
+   * @example
+   * ```typescript
+   * const addresses = await client.listShippingAddresses();
+   * const defaultAddress = addresses.addresses.find(a => a.isDefault);
+   * ```
+   */
+  async listShippingAddresses(): Promise<ListShippingAddressesResponse> {
+    return this.get("/api/user/shipping-addresses");
+  }
+  
+  /**
+   * Create a new shipping address
+   * 
+   * @param request - Shipping address data
+   * @returns Created address
+   * 
+   * @example
+   * ```typescript
+   * const address = await client.createShippingAddress({
+   *   fullName: "John Doe",
+   *   phone: "+1234567890",
+   *   addressLine1: "123 Main St",
+   *   city: "New York",
+   *   stateProvince: "NY",
+   *   postalCode: "10001",
+   *   country: "US",
+   *   isDefault: true,
+   *   label: "Home"
+   * });
+   * ```
+   */
+  async createShippingAddress(
+    request: ShippingAddressRequest
+  ): Promise<ShippingAddressResponse> {
+    return this.post("/api/user/shipping-addresses", request);
+  }
+  
+  /**
+   * Update a shipping address
+   * 
+   * @param addressId - Address ID
+   * @param request - Updated address data
+   * @returns Updated address
+   * 
+   * @example
+   * ```typescript
+   * const address = await client.updateShippingAddress("addr_123", {
+   *   phone: "+0987654321"
+   * });
+   * ```
+   */
+  async updateShippingAddress(
+    addressId: string,
+    request: Partial<ShippingAddressRequest>
+  ): Promise<ShippingAddressResponse> {
+    return this.patch(`/api/user/shipping-addresses/${addressId}`, request);
+  }
+  
+  /**
+   * Delete a shipping address
+   * 
+   * @param addressId - Address ID
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * await client.deleteShippingAddress("addr_123");
+   * ```
+   */
+  async deleteShippingAddress(addressId: string): Promise<SuccessResponse> {
+    return this.delete(`/api/user/shipping-addresses/${addressId}`);
+  }
+  
+  // ============================================================================
+  // Cart & Discounts API
+  // ============================================================================
+  
+  /**
+   * Calculate automatic discounts for cart items
+   * 
+   * @param request - Cart items
+   * @returns Calculated discounts and totals
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.calculateCartDiscounts({
+   *   items: [
+   *     { productId: "prod_123", quantity: 2 },
+   *     { productId: "prod_456", quantity: 1 }
+   *   ]
+   * });
+   * console.log("Subtotal:", result.subtotal);
+   * console.log("Discount:", result.discountAmount);
+   * console.log("Total:", result.total);
+   * ```
+   */
+  async calculateCartDiscounts(
+    request: CalculateCartDiscountsRequest
+  ): Promise<CalculateCartDiscountsResponse> {
+    return this.post("/api/marketplace/cart/discounts", request);
+  }
+  
+  /**
+   * Validate a discount code for cart items
+   * 
+   * @param request - Discount code and cart items
+   * @returns Validation result with discount details
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.validateDiscountCode({
+   *   code: "SAVE10",
+   *   items: [
+   *     { productId: "prod_123", quantity: 2 }
+   *   ]
+   * });
+   * 
+   * if (result.valid) {
+   *   console.log("Discount:", result.discount?.discountAmount);
+   * } else {
+   *   console.log("Error:", result.error);
+   * }
+   * ```
+   */
+  async validateDiscountCode(
+    request: ValidateDiscountRequest
+  ): Promise<ValidateDiscountResponse> {
+    return this.post("/api/marketplace/discounts/validate", request);
+  }
+  
+  // ============================================================================
+  // Tax Calculation API
+  // ============================================================================
+  
+  /**
+   * Calculate tax for cart items based on shipping address
+   * 
+   * @param request - Cart items and shipping address
+   * @returns Tax calculation with breakdown
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.calculateTax({
+   *   items: [
+   *     { productId: "prod_123", quantity: 2 }
+   *   ],
+   *   shippingAddress: {
+   *     country: "US",
+   *     region: "NY",
+   *     postalCode: "10001"
+   *   }
+   * });
+   * console.log("Tax:", result.taxAmount);
+   * console.log("Total:", result.total);
+   * ```
+   */
+  async calculateTax(request: CalculateTaxRequest): Promise<CalculateTaxResponse> {
+    return this.post("/api/marketplace/tax/calculate", request);
+  }
+  
+  // ============================================================================
+  // Banners API
+  // ============================================================================
+  
+  /**
+   * Get active promotional banners
+   * 
+   * @param params - Query parameters
+   * @returns List of active banners
+   * 
+   * @example
+   * ```typescript
+   * const banners = await client.getActiveBanners({
+   *   type: "HERO",
+   *   merchantId: "merchant_123"
+   * });
+   * ```
+   */
+  async getActiveBanners(params?: ListActiveBannersParams): Promise<ListBannersResponse> {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/banners/active${queryString}`);
+  }
+  
+  /**
+   * Track banner impression or click
+   * 
+   * @param bannerId - Banner ID
+   * @param request - Track action (impression or click)
+   * @returns Success response
+   * 
+   * @example
+   * ```typescript
+   * // Track impression
+   * await client.trackBanner("banner_123", { action: "impression" });
+   * 
+   * // Track click
+   * await client.trackBanner("banner_123", { action: "click" });
+   * ```
+   */
+  async trackBanner(bannerId: string, request: TrackBannerRequest): Promise<SuccessResponse> {
+    return this.post(`/api/marketplace/banners/${bannerId}/track`, request);
+  }
+  
+  // ============================================================================
+  // Messages API
+  // ============================================================================
+  
+  /**
+   * List messages for customer
+   * 
+   * Returns all conversations grouped by order, where each order represents
+   * a conversation with a merchant.
+   * 
+   * @returns List of conversations with messages and stats
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.listMessages();
+   * console.log("Unread:", result.stats.unread);
+   * result.conversations.forEach(conv => {
+   *   console.log(`Order ${conv.orderNumber}: ${conv.unreadCount} unread`);
+   * });
+   * ```
+   */
+  async listMessages(): Promise<CustomerMessagesResponse> {
+    return this.get("/api/marketplace/messages");
+  }
+  
+  /**
+   * Get message stats (unread count)
+   * 
+   * Lightweight endpoint for notification badges.
+   * 
+   * @returns Unread message count
+   * 
+   * @example
+   * ```typescript
+   * const stats = await client.getMessageStats();
+   * console.log("Unread messages:", stats.unread);
+   * ```
+   */
+  async getMessageStats(): Promise<MessageStatsResponse> {
+    return this.get("/api/marketplace/messages/stats");
+  }
+  
+  /**
+   * Send a message to a merchant about an order
+   * 
+   * @param request - Message data including orderId, recipientId (merchant user ID), and message
+   * @returns Sent message
+   * 
+   * @example
+   * ```typescript
+   * await client.sendMessage({
+   *   orderId: "ord_123",
+   *   recipientId: "user_merchant_456",
+   *   message: "When will my order ship?"
+   * });
+   * ```
+   */
+  async sendMessage(request: SendMessageRequest): Promise<MessageResponse> {
+    return this.post("/api/marketplace/messages/send", request);
+  }
+  
+  /**
+   * Mark a message as read
+   * 
+   * @param messageId - Message ID
+   * @returns Updated message
+   * 
+   * @example
+   * ```typescript
+   * await client.markMessageAsRead("msg_123");
+   * ```
+   */
+  async markMessageAsRead(messageId: string): Promise<MessageResponse> {
+    return this.patch(`/api/marketplace/messages/${messageId}/read`, {});
+  }
+  
+  // ============================================================================
+  // Flash Sales API
+  // ============================================================================
+  
+  /**
+   * Get active flash sales
+   * 
+   * Returns currently running flash sales with their discounted products.
+   * Includes countdown timer information for UI display.
+   * 
+   * @param params - Query parameters
+   * @returns List of active flash sales with time remaining
+   * 
+   * @example
+   * ```typescript
+   * const result = await client.getActiveFlashSales({ limit: 5 });
+   * 
+   * result.flashSales.forEach(sale => {
+   *   console.log(`${sale.name} - ends at ${sale.endsAt}`);
+   *   sale.items.forEach(item => {
+   *     console.log(`  ${item.product.title}: $${item.salePrice} (${item.discountPercent}% off)`);
+   *   });
+   * });
+   * 
+   * // Use timeRemaining for countdown UI
+   * if (result.timeRemaining) {
+   *   console.log(`Featured sale ends in ${result.timeRemaining.remainingSeconds} seconds`);
+   * }
+   * ```
+   */
+  async getActiveFlashSales(params?: ListActiveFlashSalesParams): Promise<ActiveFlashSalesResponse> {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/flash-sales/active${queryString}`);
+  }
+}
+