@basedone/core 0.2.5 → 0.2.7

package/dist/ecommerce.js

@@ -324,10 +324,10 @@ var CustomerEcommerceClient = class 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({
@@ -347,10 +347,10 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   }
   /**
    * 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");
@@ -362,10 +362,10 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   }
   /**
    * Track product view (increment view count)
-   * 
+   *
    * @param productId - Product ID
    * @returns Success response
-   * 
+   *
    * @example
    * ```typescript
    * await client.trackProductView("prod_123");
@@ -376,10 +376,10 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   }
   /**
    * 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");
@@ -394,14 +394,31 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   // ============================================================================
   /**
    * 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 },
@@ -417,9 +434,10 @@ var CustomerEcommerceClient = class 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);
@@ -431,10 +449,10 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   }
   /**
    * List user's orders
-   * 
+   *
    * @param params - Query parameters for filtering
    * @returns Paginated list of orders
-   * 
+   *
    * @example
    * ```typescript
    * const orders = await client.listOrders({
@@ -450,10 +468,10 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   }
   /**
    * 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");
@@ -465,12 +483,12 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   }
   /**
    * 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
@@ -479,14 +497,16 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
    * ```
    */
   async confirmEscrowDeposit(orderId) {
-    return this.post(`/api/marketplace/orders/${orderId}/confirm-escrow-deposit`);
+    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");
@@ -501,11 +521,11 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   // ============================================================================
   /**
    * 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", {
@@ -516,17 +536,19 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
    */
   async listProductReviews(productId, params) {
     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", {
@@ -544,9 +566,9 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   // ============================================================================
   /**
    * List saved shipping addresses
-   * 
+   *
    * @returns List of user's saved shipping addresses
-   * 
+   *
    * @example
    * ```typescript
    * const addresses = await client.listShippingAddresses();
@@ -558,10 +580,10 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   }
   /**
    * Create a new shipping address
-   * 
+   *
    * @param request - Shipping address data
    * @returns Created address
-   * 
+   *
    * @example
    * ```typescript
    * const address = await client.createShippingAddress({
@@ -582,11 +604,11 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   }
   /**
    * 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", {
@@ -599,10 +621,10 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   }
   /**
    * Delete a shipping address
-   * 
+   *
    * @param addressId - Address ID
    * @returns Success response
-   * 
+   *
    * @example
    * ```typescript
    * await client.deleteShippingAddress("addr_123");
@@ -616,10 +638,10 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   // ============================================================================
   /**
    * Calculate automatic discounts for cart items
-   * 
+   *
    * @param request - Cart items
    * @returns Calculated discounts and totals
-   * 
+   *
    * @example
    * ```typescript
    * const result = await client.calculateCartDiscounts({
@@ -638,10 +660,10 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   }
   /**
    * 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({
@@ -650,7 +672,7 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
    *     { productId: "prod_123", quantity: 2 }
    *   ]
    * });
-   * 
+   *
    * if (result.valid) {
    *   console.log("Discount:", result.discount?.discountAmount);
    * } else {
@@ -666,10 +688,10 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   // ============================================================================
   /**
    * 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({
@@ -694,10 +716,10 @@ var CustomerEcommerceClient = class 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({
@@ -708,7 +730,7 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
    *   destinationCountry: "US",
    *   orderSubtotal: 99.99
    * });
-   * 
+   *
    * result.shippingOptions.forEach(opt => {
    *   console.log(opt.name, opt.cost, opt.estimatedDelivery);
    * });
@@ -722,10 +744,10 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   // ============================================================================
   /**
    * Get active promotional banners
-   * 
+   *
    * @param params - Query parameters
    * @returns List of active banners
-   * 
+   *
    * @example
    * ```typescript
    * const banners = await client.getActiveBanners({
@@ -740,16 +762,16 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   }
   /**
    * 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" });
    * ```
@@ -762,12 +784,12 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   // ============================================================================
   /**
    * 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();
@@ -782,11 +804,11 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   }
   /**
    * Get message stats (unread count)
-   * 
+   *
    * Lightweight endpoint for notification badges.
-   * 
+   *
    * @returns Unread message count
-   * 
+   *
    * @example
    * ```typescript
    * const stats = await client.getMessageStats();
@@ -798,10 +820,10 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   }
   /**
    * 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({
@@ -816,10 +838,10 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   }
   /**
    * Mark a message as read
-   * 
+   *
    * @param messageId - Message ID
    * @returns Updated message
-   * 
+   *
    * @example
    * ```typescript
    * await client.markMessageAsRead("msg_123");
@@ -833,24 +855,24 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   // ============================================================================
   /**
    * 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`);
@@ -863,19 +885,19 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   }
   /**
    * 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}:`);
@@ -887,7 +909,9 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
    * ```
    */
   async getFlashSaleAllowance(params) {
-    const queryString = buildQueryString({ productIds: params.productIds.join(",") });
+    const queryString = buildQueryString({
+      productIds: params.productIds.join(",")
+    });
     return this.get(`/api/marketplace/flash-sales/allowance${queryString}`);
   }
   // ============================================================================
@@ -895,12 +919,12 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   // ============================================================================
   /**
    * 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");
@@ -912,13 +936,13 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   }
   /**
    * 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", {
@@ -926,7 +950,7 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
    *   sortBy: "popular",
    *   limit: 20,
    * });
-   * 
+   *
    * result.items.forEach(product => {
    *   console.log(product.title, product.priceUSDC);
    * });
@@ -934,17 +958,19 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
    */
   async getMerchantProducts(merchantId, params) {
     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");
@@ -958,10 +984,10 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   }
   /**
    * Follow a merchant
-   * 
+   *
    * @param merchantId - Merchant ID to follow
    * @returns Follow action result
-   * 
+   *
    * @example
    * ```typescript
    * const result = await client.followMerchant("merchant_123");
@@ -973,10 +999,10 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   }
   /**
    * Unfollow a merchant
-   * 
+   *
    * @param merchantId - Merchant ID to unfollow
    * @returns Unfollow action result
-   * 
+   *
    * @example
    * ```typescript
    * const result = await client.unfollowMerchant("merchant_123");
@@ -988,10 +1014,10 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   }
   /**
    * 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" });
@@ -1009,11 +1035,11 @@ var CustomerEcommerceClient = class 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();
@@ -1032,12 +1058,12 @@ var CustomerEcommerceClient = class 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();
@@ -1050,24 +1076,24 @@ var CustomerEcommerceClient = class 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}`);
    * });
@@ -1079,21 +1105,21 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   }
   /**
    * 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 => {
@@ -1111,12 +1137,12 @@ var CustomerEcommerceClient = class 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();
@@ -1130,13 +1156,13 @@ var CustomerEcommerceClient = class 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({
@@ -1154,12 +1180,12 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   }
   /**
    * 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();
@@ -1169,6 +1195,41 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   async clearBrowsingLocation() {
     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() {
+    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() {
+    return this.get("/api/basedpay/delivery-address");
+  }
 };
 
 // lib/ecommerce/client/merchant.ts