@basedone/core 0.2.5 → 0.2.7

package/lib/ecommerce/client/customer.ts

@@ -1,6 +1,6 @@
 /**
  * Customer/End-User Ecommerce API Client
- * 
+ *
  * This module provides methods for customer-facing ecommerce operations including
  * browsing products, placing orders, managing reviews, and more.
  */
@@ -29,7 +29,7 @@ import type {
   GetGemHistoryParams,
   GetExpiringGemsParams,
   SaveBrowsingLocationRequest,
-  
+
   // Response types
   ListProductsResponse,
   GetProductResponse,
@@ -66,24 +66,26 @@ import type {
   DeleteBrowsingLocationResponse,
   GetGemHistoryResponse,
   GetExpiringGemsResponse,
+  CashAccountBalanceResponse,
+  DeliveryAddressResponse,
 } 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 }],
@@ -93,17 +95,16 @@ import type {
  * ```
  */
 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({
@@ -117,17 +118,19 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
    * });
    * ```
    */
-  async listProducts(params?: ListProductsParams): Promise<ListProductsResponse> {
+  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");
@@ -137,13 +140,13 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
   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");
@@ -152,37 +155,56 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
   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> {
+  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.
-   * 
+   *
+   * **IMPORTANT: Shipping Cost Security**
+   * - Use `shippingRateId` to specify the selected shipping rate
+   * - The server calculates shipping cost from the rate ID (never trust frontend costs)
+   * - Get available rates from `calculateShippingOptions()` first
+   *
    * @param request - Order creation request
    * @returns Created order(s) with payment instructions
-   * 
+   *
    * @example
    * ```typescript
+   * // Step 1: Calculate available shipping options
+   * const shippingOptions = await client.calculateShippingOptions({
+   *   merchantId: "merchant_123",
+   *   destinationCountry: "US",
+   *   cartItems: [{ productId: "prod_123", quantity: 2, priceUSDC: 29.99 }],
+   *   orderSubtotal: 59.98
+   * });
+   *
+   * // Step 2: Let user select a shipping option, get the rateId
+   * const selectedRateId = shippingOptions.shippingOptions[0].rateId;
+   *
+   * // Step 3: Create order with shippingRateId (server validates and calculates cost)
    * const result = await client.createOrder({
    *   items: [
    *     { productId: "prod_123", quantity: 2 },
@@ -198,9 +220,10 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
    *     postalCode: "10001",
    *     country: "US"
    *   },
+   *   shippingRateId: selectedRateId, // Server validates and calculates cost
    *   couponCode: "SAVE10"
    * });
-   * 
+   *
    * // For USDC escrow, deposit to the escrow address
    * if (result.escrow) {
    *   console.log("Deposit", result.escrow.amountUSDC, "USDC to", result.escrow.address);
@@ -210,13 +233,13 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
   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({
@@ -230,13 +253,13 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
     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");
@@ -246,15 +269,15 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
   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
@@ -262,16 +285,20 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
    * console.log("Payment confirmed:", result.depositTxHash);
    * ```
    */
-  async confirmEscrowDeposit(orderId: string): Promise<ConfirmEscrowDepositResponse> {
-    return this.post(`/api/marketplace/orders/${orderId}/confirm-escrow-deposit`);
+  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");
@@ -281,18 +308,18 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
   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", {
@@ -303,21 +330,23 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
    */
   async listProductReviews(
     productId: string,
-    params?: ListReviewsParams
+    params?: ListReviewsParams,
   ): Promise<ListReviewsResponse> {
     const queryString = params ? buildQueryString(params) : "";
-    return this.get(`/api/marketplace/products/${productId}/reviews${queryString}`);
+    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", {
@@ -329,20 +358,20 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
    */
   async createReview(
     productId: string,
-    request: CreateReviewRequest
+    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();
@@ -352,13 +381,13 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
   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({
@@ -375,18 +404,18 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
    * ```
    */
   async createShippingAddress(
-    request: ShippingAddressRequest
+    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", {
@@ -396,17 +425,17 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
    */
   async updateShippingAddress(
     addressId: string,
-    request: Partial<ShippingAddressRequest>
+    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");
@@ -415,17 +444,17 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
   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({
@@ -440,17 +469,17 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
    * ```
    */
   async calculateCartDiscounts(
-    request: CalculateCartDiscountsRequest
+    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({
@@ -459,7 +488,7 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
    *     { productId: "prod_123", quantity: 2 }
    *   ]
    * });
-   * 
+   *
    * if (result.valid) {
    *   console.log("Discount:", result.discount?.discountAmount);
    * } else {
@@ -468,21 +497,21 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
    * ```
    */
   async validateDiscountCode(
-    request: ValidateDiscountRequest
+    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({
@@ -499,7 +528,9 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
    * console.log("Total:", result.total);
    * ```
    */
-  async calculateTax(request: CalculateTaxRequest): Promise<CalculateTaxResponse> {
+  async calculateTax(
+    request: CalculateTaxRequest,
+  ): Promise<CalculateTaxResponse> {
     return this.post("/api/marketplace/tax/calculate", request);
   }
 
@@ -509,10 +540,10 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
 
   /**
    * Calculate shipping options for cart items
-   * 
+   *
    * @param request - Cart items, merchant, and destination
    * @returns Available shipping options with costs
-   * 
+   *
    * @example
    * ```typescript
    * const result = await client.calculateShippingOptions({
@@ -523,26 +554,28 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
    *   destinationCountry: "US",
    *   orderSubtotal: 99.99
    * });
-   * 
+   *
    * result.shippingOptions.forEach(opt => {
    *   console.log(opt.name, opt.cost, opt.estimatedDelivery);
    * });
    * ```
    */
-  async calculateShippingOptions(request: CalculateShippingRequest): Promise<CalculateShippingResponse> {
+  async calculateShippingOptions(
+    request: CalculateShippingRequest,
+  ): Promise<CalculateShippingResponse> {
     return this.post("/api/marketplace/shipping/calculate", request);
   }
-  
+
   // ============================================================================
   // Banners API
   // ============================================================================
-  
+
   /**
    * Get active promotional banners
-   * 
+   *
    * @param params - Query parameters
    * @returns List of active banners
-   * 
+   *
    * @example
    * ```typescript
    * const banners = await client.getActiveBanners({
@@ -551,43 +584,48 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
    * });
    * ```
    */
-  async getActiveBanners(params?: ListActiveBannersParams): Promise<ListBannersResponse> {
+  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> {
+  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();
@@ -600,14 +638,14 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
   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();
@@ -617,13 +655,13 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
   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({
@@ -636,13 +674,13 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
   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");
@@ -651,57 +689,59 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
   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> {
+  async getActiveFlashSales(
+    params?: ListActiveFlashSalesParams,
+  ): Promise<ActiveFlashSalesResponse> {
     const queryString = params ? buildQueryString(params) : "";
     return this.get(`/api/marketplace/flash-sales/active${queryString}`);
   }
 
   /**
    * Get flash sale allowance
-   * 
+   *
    * Fetches user's remaining purchase allowance for flash sale items.
    * Used to enforce per-customer purchase limits.
-   * 
+   *
    * @param params - Request params with product IDs
    * @returns Allowance info for each product
-   * 
+   *
    * @example
    * ```typescript
    * const result = await client.getFlashSaleAllowance({
    *   productIds: ["prod_123", "prod_456"]
    * });
-   * 
+   *
    * Object.entries(result.allowances).forEach(([productId, info]) => {
    *   if (info.limitPerCustomer !== null) {
    *     console.log(`Product ${productId}:`);
@@ -712,42 +752,48 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
    * });
    * ```
    */
-  async getFlashSaleAllowance(params: GetFlashSaleAllowanceParams): Promise<GetFlashSaleAllowanceResponse> {
-    const queryString = buildQueryString({ productIds: params.productIds.join(",") });
+  async getFlashSaleAllowance(
+    params: GetFlashSaleAllowanceParams,
+  ): Promise<GetFlashSaleAllowanceResponse> {
+    const queryString = buildQueryString({
+      productIds: params.productIds.join(","),
+    });
     return this.get(`/api/marketplace/flash-sales/allowance${queryString}`);
   }
-  
+
   // ============================================================================
   // Merchant Storefront API
   // ============================================================================
-  
+
   /**
    * Get public merchant profile
-   * 
+   *
    * Fetches public information about a merchant for the storefront page.
-   * 
+   *
    * @param merchantId - Merchant ID
    * @returns Public merchant profile with stats
-   * 
+   *
    * @example
    * ```typescript
    * const result = await client.getMerchantProfile("merchant_123");
    * console.log(result.merchant.name, result.merchant.productCount);
    * ```
    */
-  async getMerchantProfile(merchantId: string): Promise<PublicMerchantProfileResponse> {
+  async getMerchantProfile(
+    merchantId: string,
+  ): Promise<PublicMerchantProfileResponse> {
     return this.get(`/api/marketplace/merchants/${merchantId}`);
   }
-  
+
   /**
    * List merchant products
-   * 
+   *
    * Fetches products for a specific merchant with search, filter, and sort options.
-   * 
+   *
    * @param merchantId - Merchant ID
    * @param params - Query parameters for filtering and pagination
    * @returns Paginated list of products
-   * 
+   *
    * @example
    * ```typescript
    * const result = await client.getMerchantProducts("merchant_123", {
@@ -755,7 +801,7 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
    *   sortBy: "popular",
    *   limit: 20,
    * });
-   * 
+   *
    * result.items.forEach(product => {
    *   console.log(product.title, product.priceUSDC);
    * });
@@ -763,22 +809,24 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
    */
   async getMerchantProducts(
     merchantId: string,
-    params?: ListMerchantProductsParams
+    params?: ListMerchantProductsParams,
   ): Promise<MerchantProductsResponse> {
     const queryString = params ? buildQueryString(params) : "";
-    return this.get(`/api/marketplace/merchants/${merchantId}/products${queryString}`);
+    return this.get(
+      `/api/marketplace/merchants/${merchantId}/products${queryString}`,
+    );
   }
-  
+
   // ============================================================================
   // Shop Following API
   // ============================================================================
-  
+
   /**
    * Check if following a merchant
-   * 
+   *
    * @param merchantId - Merchant ID
    * @returns Follow status with follow date if applicable
-   * 
+   *
    * @example
    * ```typescript
    * const status = await client.isFollowingMerchant("merchant_123");
@@ -790,13 +838,13 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
   async isFollowingMerchant(merchantId: string): Promise<FollowStatusResponse> {
     return this.get(`/api/marketplace/merchants/${merchantId}/follow`);
   }
-  
+
   /**
    * Follow a merchant
-   * 
+   *
    * @param merchantId - Merchant ID to follow
    * @returns Follow action result
-   * 
+   *
    * @example
    * ```typescript
    * const result = await client.followMerchant("merchant_123");
@@ -806,13 +854,13 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
   async followMerchant(merchantId: string): Promise<FollowActionResponse> {
     return this.post(`/api/marketplace/merchants/${merchantId}/follow`);
   }
-  
+
   /**
    * Unfollow a merchant
-   * 
+   *
    * @param merchantId - Merchant ID to unfollow
    * @returns Unfollow action result
-   * 
+   *
    * @example
    * ```typescript
    * const result = await client.unfollowMerchant("merchant_123");
@@ -822,13 +870,13 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
   async unfollowMerchant(merchantId: string): Promise<FollowActionResponse> {
     return this.delete(`/api/marketplace/merchants/${merchantId}/follow`);
   }
-  
+
   /**
    * Get list of followed merchants
-   * 
+   *
    * @param params - Query parameters for pagination and sorting
    * @returns Paginated list of followed merchants with their info
-   * 
+   *
    * @example
    * ```typescript
    * const result = await client.getFollowedMerchants({ limit: 20, sortBy: "recent" });
@@ -837,7 +885,9 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
    * });
    * ```
    */
-  async getFollowedMerchants(params?: ListFollowingParams): Promise<ListFollowingResponse> {
+  async getFollowedMerchants(
+    params?: ListFollowingParams,
+  ): Promise<ListFollowingResponse> {
     const queryString = params ? buildQueryString(params) : "";
     return this.get(`/api/marketplace/following${queryString}`);
   }
@@ -848,11 +898,11 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
 
   /**
    * Get available payment methods
-   * 
+   *
    * Returns the list of enabled payment methods that can be used during checkout.
-   * 
+   *
    * @returns List of available payment methods with display info
-   * 
+   *
    * @example
    * ```typescript
    * const result = await client.getPaymentMethods();
@@ -873,12 +923,12 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
 
   /**
    * Get user's gem balance
-   * 
+   *
    * Returns the current gem balance including total gems, available gems,
    * and gems expiring soon. Gems are earned at 100 per $1 of revenue.
-   * 
+   *
    * @returns Current gem balance with USD equivalent
-   * 
+   *
    * @example
    * ```typescript
    * const balance = await client.getGemBalance();
@@ -892,51 +942,53 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
 
   /**
    * Get gem transaction history
-   * 
+   *
    * Returns paginated history of gem transactions including earning,
    * spending, and expiration events.
-   * 
+   *
    * @param params - Query parameters for filtering and pagination
    * @returns Paginated gem history
-   * 
+   *
    * @example
    * ```typescript
    * // Get all history
    * const history = await client.getGemHistory({ limit: 20, offset: 0 });
-   * 
+   *
    * // Get only earned gems
    * const earned = await client.getGemHistory({ type: "earn", limit: 10 });
-   * 
+   *
    * // Get only spent gems
    * const spent = await client.getGemHistory({ type: "spend", limit: 10 });
-   * 
+   *
    * history.items.forEach(item => {
    *   console.log(`${item.type}: ${item.amount} gems - ${item.createdAt}`);
    * });
    * ```
    */
-  async getGemHistory(params?: GetGemHistoryParams): Promise<GetGemHistoryResponse> {
+  async getGemHistory(
+    params?: GetGemHistoryParams,
+  ): Promise<GetGemHistoryResponse> {
     const queryString = params ? buildQueryString(params) : "";
     return this.get(`/api/gems/history${queryString}`);
   }
 
   /**
    * Get gems that are expiring soon
-   * 
+   *
    * Returns gem batches that will expire within the specified number of days.
    * Useful for prompting users to spend gems before they expire.
-   * 
+   *
    * @param params - Query parameters (days: default 30, max 180)
    * @returns Expiring gem batches with countdown info
-   * 
+   *
    * @example
    * ```typescript
    * // Get gems expiring in next 30 days (default)
    * const expiring = await client.getExpiringGems();
-   * 
+   *
    * // Get gems expiring in next 7 days
    * const urgent = await client.getExpiringGems({ days: 7 });
-   * 
+   *
    * if (expiring.totalExpiring > 0) {
    *   console.log(`${expiring.totalExpiring} gems expiring soon!`);
    *   expiring.batches.forEach(batch => {
@@ -945,7 +997,9 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
    * }
    * ```
    */
-  async getExpiringGems(params?: GetExpiringGemsParams): Promise<GetExpiringGemsResponse> {
+  async getExpiringGems(
+    params?: GetExpiringGemsParams,
+  ): Promise<GetExpiringGemsResponse> {
     const queryString = params ? buildQueryString(params) : "";
     return this.get(`/api/gems/expiring${queryString}`);
   }
@@ -956,12 +1010,12 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
 
   /**
    * Get user's browsing location
-   * 
+   *
    * Returns the user's saved delivery location for geo-based product filtering.
    * This location is used to show products from merchants that ship to the area.
-   * 
+   *
    * @returns Current browsing location or null if not set
-   * 
+   *
    * @example
    * ```typescript
    * const result = await client.getBrowsingLocation();
@@ -976,13 +1030,13 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
 
   /**
    * Save user's browsing location
-   * 
+   *
    * Sets the user's delivery location for geo-based product filtering.
    * Products will be filtered to show only items from merchants that ship to this location.
-   * 
+   *
    * @param request - Location data from Google Places or manual input
    * @returns The saved location
-   * 
+   *
    * @example
    * ```typescript
    * const result = await client.saveBrowsingLocation({
@@ -995,18 +1049,20 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
    * console.log(`Location saved: ${result.location.formattedAddress}`);
    * ```
    */
-  async saveBrowsingLocation(request: SaveBrowsingLocationRequest): Promise<SaveBrowsingLocationResponse> {
+  async saveBrowsingLocation(
+    request: SaveBrowsingLocationRequest,
+  ): Promise<SaveBrowsingLocationResponse> {
     return this.post("/api/user/browsing-location", request);
   }
 
   /**
    * Clear user's browsing location
-   * 
+   *
    * Removes the user's saved delivery location. Products will no longer
    * be filtered by shipping destination.
-   * 
+   *
    * @returns Success response
-   * 
+   *
    * @example
    * ```typescript
    * await client.clearBrowsingLocation();
@@ -1016,5 +1072,42 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
   async clearBrowsingLocation(): Promise<DeleteBrowsingLocationResponse> {
     return this.delete("/api/user/browsing-location");
   }
-}
 
+  // ============================================================================
+  // BasedPay Cash Account API
+  // ============================================================================
+
+  /**
+   * Get user's cash account balance for BASEDPAY
+   *
+   * Returns the current balance in the user's BasedPay cash account.
+   *
+   * @returns Cash account balance with currency
+   *
+   * @example
+   * ```typescript
+   * const balance = await client.getCashAccountBalance();
+   * console.log(`Balance: ${balance.balance} ${balance.currency}`);
+   * ```
+   */
+  async getCashAccountBalance(): Promise<CashAccountBalanceResponse> {
+    return this.get("/api/basedpay/balance");
+  }
+
+  /**
+   * Get user's delivery address for BASEDPAY
+   *
+   * Returns the user's delivery address for BASEDPAY.
+   *
+   * @returns Delivery address
+   *
+   * @example
+   * ```typescript
+   * const address = await client.getDeliveryAddress();
+   * console.log(`Address: ${address.address}`);
+   * ```
+   */
+  async getDeliveryAddress(): Promise<DeliveryAddressResponse> {
+    return this.get("/api/basedpay/delivery-address");
+  }
+}