@basedone/core 0.2.5 → 0.2.6

package/dist/{chunk-P5C65GIG.mjs → chunk-CAU4QLVH.mjs}

@@ -387,11 +387,28 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
    * 
    * 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 },
@@ -407,6 +424,7 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
    *     postalCode: "10001",
    *     country: "US"
    *   },
+   *   shippingRateId: selectedRateId, // Server validates and calculates cost
    *   couponCode: "SAVE10"
    * });
    * 

package/dist/ecommerce.d.mts

@@ -1241,18 +1241,30 @@ interface ShippingRate extends BaseEntity {
 }
 /**
  * Shipping option (calculated for checkout)
+ *
+ * Use `rateId` when creating orders - the server will validate and calculate cost.
  */
 interface ShippingOption {
-    /** Rate ID */
-    id: string;
-    /** Rate name */
-    name: string;
-    /** Calculated cost in USDC */
-    cost: number;
-    /** Estimated delivery string */
-    estimatedDelivery: string;
+    /** Rate ID - use this when creating orders */
+    rateId: string;
     /** Zone name */
     zoneName: string;
+    /** Rate name (e.g., "Standard", "Express") */
+    rateName: string;
+    /** Base rate in USDC */
+    baseRate: number;
+    /** Per-kg rate in USDC */
+    perKgRate: number;
+    /** Calculated total cost in USDC (for display only - server recalculates) */
+    calculatedCost: number;
+    /** Whether free shipping applies */
+    isFree: boolean;
+    /** Estimated delivery string (e.g., "5-7 business days") */
+    estimatedDelivery: string | null;
+    /** Minimum delivery days */
+    minDeliveryDays: number | null;
+    /** Maximum delivery days */
+    maxDeliveryDays: number | null;
 }
 
 /**
@@ -1386,13 +1398,19 @@ interface CreateOrderRequest {
     couponCode?: string;
     /** Idempotency key */
     idempotencyKey?: string;
-    /** Selected shipping method name (e.g., "Standard", "Express") */
+    /**
+     * Selected shipping rate ID (from shipping calculator)
+     * The server will validate this rate and calculate the cost server-side.
+     * SECURITY: The cost is never trusted from the frontend.
+     */
+    shippingRateId?: string;
+    /** @deprecated Use shippingRateId instead. This value is ignored by the server. */
     shippingMethod?: string;
-    /** Calculated shipping cost in USDC */
+    /** @deprecated Use shippingRateId instead. This value is ignored by the server. */
     shippingCost?: number;
-    /** Shipping zone name for reference */
+    /** @deprecated Use shippingRateId instead. This value is ignored by the server. */
     shippingZone?: string;
-    /** Estimated delivery time (e.g., "5-7 business days") */
+    /** @deprecated Use shippingRateId instead. This value is ignored by the server. */
     estimatedDelivery?: string;
 }
 /**
@@ -3198,11 +3216,28 @@ declare class CustomerEcommerceClient extends BaseEcommerceClient {
      *
      * 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 },
@@ -3218,6 +3253,7 @@ declare class CustomerEcommerceClient extends BaseEcommerceClient {
      *     postalCode: "10001",
      *     country: "US"
      *   },
+     *   shippingRateId: selectedRateId, // Server validates and calculates cost
      *   couponCode: "SAVE10"
      * });
      *

package/dist/ecommerce.d.ts

@@ -1241,18 +1241,30 @@ interface ShippingRate extends BaseEntity {
 }
 /**
  * Shipping option (calculated for checkout)
+ *
+ * Use `rateId` when creating orders - the server will validate and calculate cost.
  */
 interface ShippingOption {
-    /** Rate ID */
-    id: string;
-    /** Rate name */
-    name: string;
-    /** Calculated cost in USDC */
-    cost: number;
-    /** Estimated delivery string */
-    estimatedDelivery: string;
+    /** Rate ID - use this when creating orders */
+    rateId: string;
     /** Zone name */
     zoneName: string;
+    /** Rate name (e.g., "Standard", "Express") */
+    rateName: string;
+    /** Base rate in USDC */
+    baseRate: number;
+    /** Per-kg rate in USDC */
+    perKgRate: number;
+    /** Calculated total cost in USDC (for display only - server recalculates) */
+    calculatedCost: number;
+    /** Whether free shipping applies */
+    isFree: boolean;
+    /** Estimated delivery string (e.g., "5-7 business days") */
+    estimatedDelivery: string | null;
+    /** Minimum delivery days */
+    minDeliveryDays: number | null;
+    /** Maximum delivery days */
+    maxDeliveryDays: number | null;
 }
 
 /**
@@ -1386,13 +1398,19 @@ interface CreateOrderRequest {
     couponCode?: string;
     /** Idempotency key */
     idempotencyKey?: string;
-    /** Selected shipping method name (e.g., "Standard", "Express") */
+    /**
+     * Selected shipping rate ID (from shipping calculator)
+     * The server will validate this rate and calculate the cost server-side.
+     * SECURITY: The cost is never trusted from the frontend.
+     */
+    shippingRateId?: string;
+    /** @deprecated Use shippingRateId instead. This value is ignored by the server. */
     shippingMethod?: string;
-    /** Calculated shipping cost in USDC */
+    /** @deprecated Use shippingRateId instead. This value is ignored by the server. */
     shippingCost?: number;
-    /** Shipping zone name for reference */
+    /** @deprecated Use shippingRateId instead. This value is ignored by the server. */
     shippingZone?: string;
-    /** Estimated delivery time (e.g., "5-7 business days") */
+    /** @deprecated Use shippingRateId instead. This value is ignored by the server. */
     estimatedDelivery?: string;
 }
 /**
@@ -3198,11 +3216,28 @@ declare class CustomerEcommerceClient extends BaseEcommerceClient {
      *
      * 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 },
@@ -3218,6 +3253,7 @@ declare class CustomerEcommerceClient extends BaseEcommerceClient {
      *     postalCode: "10001",
      *     country: "US"
      *   },
+     *   shippingRateId: selectedRateId, // Server validates and calculates cost
      *   couponCode: "SAVE10"
      * });
      *

package/dist/ecommerce.js

@@ -397,11 +397,28 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
    * 
    * 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,6 +434,7 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
    *     postalCode: "10001",
    *     country: "US"
    *   },
+   *   shippingRateId: selectedRateId, // Server validates and calculates cost
    *   couponCode: "SAVE10"
    * });
    * 

package/dist/ecommerce.mjs

@@ -1,2 +1,2 @@
-export { BannerType, BaseEcommerceClient, CustomerEcommerceClient, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, InventoryAuditAction, MerchantEcommerceClient, MerchantStatus, OrderStatus, PaymentMethod, PaymentStatus, ProductSortBy, ReturnStatus, ReviewSortBy, ReviewStatus, ShipmentStatus, SortOrder, TaxBehavior, TaxReportPeriodType, TaxReportStatus, TaxType, buildQueryString, calculateDiscountAmount, calculateFinalPrice, formatPrice, getBackoffDelay, isRetryableError, isValidAddress, isValidEmail, parseError, retryWithBackoff, sleep, truncateAddress } from './chunk-P5C65GIG.mjs';
+export { BannerType, BaseEcommerceClient, CustomerEcommerceClient, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, InventoryAuditAction, MerchantEcommerceClient, MerchantStatus, OrderStatus, PaymentMethod, PaymentStatus, ProductSortBy, ReturnStatus, ReviewSortBy, ReviewStatus, ShipmentStatus, SortOrder, TaxBehavior, TaxReportPeriodType, TaxReportStatus, TaxType, buildQueryString, calculateDiscountAmount, calculateFinalPrice, formatPrice, getBackoffDelay, isRetryableError, isValidAddress, isValidEmail, parseError, retryWithBackoff, sleep, truncateAddress } from './chunk-CAU4QLVH.mjs';
 import './chunk-4UEJOM6W.mjs';

package/dist/index.js

@@ -42723,11 +42723,28 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
    * 
    * 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 },
@@ -42743,6 +42760,7 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
    *     postalCode: "10001",
    *     country: "US"
    *   },
+   *   shippingRateId: selectedRateId, // Server validates and calculates cost
    *   couponCode: "SAVE10"
    * });
    * 

package/dist/index.mjs

@@ -1,4 +1,4 @@
-export { BannerType, BaseEcommerceClient, CustomerEcommerceClient, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, InventoryAuditAction, MerchantEcommerceClient, MerchantStatus, OrderStatus, PaymentMethod, PaymentStatus, ProductSortBy, ReturnStatus, ReviewSortBy, ReviewStatus, ShipmentStatus, SortOrder, TaxBehavior, TaxReportPeriodType, TaxReportStatus, TaxType, buildQueryString, calculateDiscountAmount, calculateFinalPrice, formatPrice, getBackoffDelay, isRetryableError, isValidAddress, isValidEmail, parseError, retryWithBackoff, sleep, truncateAddress } from './chunk-P5C65GIG.mjs';
+export { BannerType, BaseEcommerceClient, CustomerEcommerceClient, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, InventoryAuditAction, MerchantEcommerceClient, MerchantStatus, OrderStatus, PaymentMethod, PaymentStatus, ProductSortBy, ReturnStatus, ReviewSortBy, ReviewStatus, ShipmentStatus, SortOrder, TaxBehavior, TaxReportPeriodType, TaxReportStatus, TaxType, buildQueryString, calculateDiscountAmount, calculateFinalPrice, formatPrice, getBackoffDelay, isRetryableError, isValidAddress, isValidEmail, parseError, retryWithBackoff, sleep, truncateAddress } from './chunk-CAU4QLVH.mjs';
 export { AssetIdUtils, InstrumentClient } from './chunk-VBC6EQ7Q.mjs';
 import { __glob } from './chunk-4UEJOM6W.mjs';
 import Decimal, { Decimal as Decimal$1 } from 'decimal.js';

package/lib/ecommerce/client/customer.ts

@@ -178,11 +178,28 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
    * 
    * 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,6 +215,7 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
    *     postalCode: "10001",
    *     country: "US"
    *   },
+   *   shippingRateId: selectedRateId, // Server validates and calculates cost
    *   couponCode: "SAVE10"
    * });
    * 

package/lib/ecommerce/types/entities.ts

@@ -869,17 +869,29 @@ export interface ShippingRate extends BaseEntity {
 
 /**
  * Shipping option (calculated for checkout)
+ * 
+ * Use `rateId` when creating orders - the server will validate and calculate cost.
  */
 export interface ShippingOption {
-  /** Rate ID */
-  id: string;
-  /** Rate name */
-  name: string;
-  /** Calculated cost in USDC */
-  cost: number;
-  /** Estimated delivery string */
-  estimatedDelivery: string;
+  /** Rate ID - use this when creating orders */
+  rateId: string;
   /** Zone name */
   zoneName: string;
+  /** Rate name (e.g., "Standard", "Express") */
+  rateName: string;
+  /** Base rate in USDC */
+  baseRate: number;
+  /** Per-kg rate in USDC */
+  perKgRate: number;
+  /** Calculated total cost in USDC (for display only - server recalculates) */
+  calculatedCost: number;
+  /** Whether free shipping applies */
+  isFree: boolean;
+  /** Estimated delivery string (e.g., "5-7 business days") */
+  estimatedDelivery: string | null;
+  /** Minimum delivery days */
+  minDeliveryDays: number | null;
+  /** Maximum delivery days */
+  maxDeliveryDays: number | null;
 }
 

package/lib/ecommerce/types/requests.ts

@@ -150,13 +150,26 @@ export interface CreateOrderRequest {
   couponCode?: string;
   /** Idempotency key */
   idempotencyKey?: string;
-  /** Selected shipping method name (e.g., "Standard", "Express") */
+  /**
+   * Selected shipping rate ID (from shipping calculator)
+   * The server will validate this rate and calculate the cost server-side.
+   * SECURITY: The cost is never trusted from the frontend.
+   */
+  shippingRateId?: string;
+  
+  // =====================================================
+  // DEPRECATED FIELDS - Do not use
+  // These fields are ignored by the server for security reasons.
+  // Shipping cost must be calculated server-side using shippingRateId.
+  // =====================================================
+  
+  /** @deprecated Use shippingRateId instead. This value is ignored by the server. */
   shippingMethod?: string;
-  /** Calculated shipping cost in USDC */
+  /** @deprecated Use shippingRateId instead. This value is ignored by the server. */
   shippingCost?: number;
-  /** Shipping zone name for reference */
+  /** @deprecated Use shippingRateId instead. This value is ignored by the server. */
   shippingZone?: string;
-  /** Estimated delivery time (e.g., "5-7 business days") */
+  /** @deprecated Use shippingRateId instead. This value is ignored by the server. */
   estimatedDelivery?: string;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@basedone/core",
-  "version": "0.2.5",
+  "version": "0.2.6",
   "description": "Core utilities for Based One",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",