@basedone/core 0.2.4 → 0.2.6

package/dist/{chunk-NVL2HX2H.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"
    * });
    * 
@@ -851,6 +869,35 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
     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}:`);
+   *     console.log(`  Limit: ${info.limitPerCustomer} per customer`);
+   *     console.log(`  You've purchased: ${info.purchased}`);
+   *     console.log(`  You can buy: ${info.remaining} more`);
+   *   }
+   * });
+   * ```
+   */
+  async getFlashSaleAllowance(params) {
+    const queryString = buildQueryString({ productIds: params.productIds.join(",") });
+    return this.get(`/api/marketplace/flash-sales/allowance${queryString}`);
+  }
   // ============================================================================
   // Merchant Storefront API
   // ============================================================================

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;
 }
 /**
@@ -1754,6 +1772,14 @@ interface ListActiveFlashSalesParams {
     /** Filter by merchant ID */
     merchantId?: string;
 }
+/**
+ * Get flash sale allowance request
+ * Get user's remaining purchase allowance for flash sale items
+ */
+interface GetFlashSaleAllowanceParams {
+    /** Comma-separated list of product IDs */
+    productIds: string[];
+}
 /**
  * Flash sale item input
  */
@@ -2801,6 +2827,34 @@ interface ActiveFlashSalesResponse {
     /** Server time (for client-side sync) */
     serverTime: string;
 }
+/**
+ * Flash sale allowance info for a single product
+ */
+interface FlashSaleAllowanceInfo {
+    /** Flash sale ID */
+    flashSaleId: string;
+    /** Limit per customer (null = no limit) */
+    limitPerCustomer: number | null;
+    /** Quantity already purchased by user */
+    purchased: number;
+    /** Remaining quantity user can purchase (null = no limit) */
+    remaining: number | null;
+    /** Current sale price */
+    salePrice: string;
+    /** Maximum quantity available in flash sale (null = unlimited) */
+    maxQuantity: number | null;
+    /** Remaining quantity in flash sale (null = unlimited) */
+    remainingQuantity: number | null;
+}
+/**
+ * Get flash sale allowance response
+ */
+interface GetFlashSaleAllowanceResponse {
+    /** Allowances by product ID */
+    allowances: Record<string, FlashSaleAllowanceInfo>;
+    /** Whether user is authenticated */
+    authenticated: boolean;
+}
 
 /**
  * Get shipping settings response
@@ -3162,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 },
@@ -3182,6 +3253,7 @@ declare class CustomerEcommerceClient extends BaseEcommerceClient {
      *     postalCode: "10001",
      *     country: "US"
      *   },
+     *   shippingRateId: selectedRateId, // Server validates and calculates cost
      *   couponCode: "SAVE10"
      * });
      *
@@ -3554,6 +3626,32 @@ declare class CustomerEcommerceClient extends BaseEcommerceClient {
      * ```
      */
     getActiveFlashSales(params?: ListActiveFlashSalesParams): Promise<ActiveFlashSalesResponse>;
+    /**
+     * 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}:`);
+     *     console.log(`  Limit: ${info.limitPerCustomer} per customer`);
+     *     console.log(`  You've purchased: ${info.purchased}`);
+     *     console.log(`  You can buy: ${info.remaining} more`);
+     *   }
+     * });
+     * ```
+     */
+    getFlashSaleAllowance(params: GetFlashSaleAllowanceParams): Promise<GetFlashSaleAllowanceResponse>;
     /**
      * Get public merchant profile
      *
@@ -5502,4 +5600,4 @@ declare function calculateDiscountAmount(price: number, discountType: "PERCENTAG
  */
 declare function calculateFinalPrice(price: number, discountType: "PERCENTAGE" | "FIXED_AMOUNT", discountValue: number): number;
 
-export { type ActiveFlashSalesResponse, type AnalyticsOverview, type ApiResponse, type AppliedDiscount, type Banner, type BannerResponse, BannerType, BaseEcommerceClient, type BaseEntity, type BrowsingLocation, type CalculateCartDiscountsRequest, type CalculateCartDiscountsResponse, type CalculateShippingRequest, type CalculateShippingResponse, type CalculateTaxRequest, type CalculateTaxResponse, type CartItem, type ConfirmEscrowDepositResponse, type Coupon, type CouponResponse, type CouponUsage, type CreateBannerRequest, type CreateCouponRequest, type CreateFlashSaleRequest, type CreateOrderEventRequest, type CreateOrderEventResponse, type CreateOrderRequest, type CreateOrderResponse, type CreateProductRequest, type CreateProductVariantRequest, type CreateReviewRequest, type CreateShippingMethodRequest, type CreateShippingRateRequest, type CreateShippingZoneRequest, type CreateTaxNexusRequest, type CreateTaxRuleRequest, CustomerEcommerceClient, type CustomerMessagesResponse, type CustomerSummary, type DeleteBrowsingLocationResponse, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, type EcommerceClientConfig, type ExpiringGemBatch, type FlashSale, type FlashSaleItem, type FlashSaleItemInput, type FollowActionResponse, type FollowStatusResponse, type FollowedMerchantSummary, type GemHistoryItem, type GemHistoryType, type GemHistoryTypeFilter, type GemSource, type GenerateTaxReportRequest, type GetAnalyticsParams, type GetAnalyticsResponse, type GetBrowsingLocationResponse, type GetCouponResponse, type GetExpiringGemsParams, type GetExpiringGemsResponse, type GetGemBalanceResponse, type GetGemHistoryParams, type GetGemHistoryResponse, type GetOrderResponse, type GetPaymentMethodsResponse, type GetProductMetricsResponse, type GetProductResponse, type GetTaxReportResponse, InventoryAuditAction, type InventoryAuditEntry, type ListActiveBannersParams, type ListActiveFlashSalesParams, type ListBannersResponse, type ListCouponsResponse, type ListCustomersParams, type ListCustomersResponse, type ListFollowingParams, type ListFollowingResponse, type ListInventoryAuditResponse, type ListMediaAssetsResponse, type ListMerchantProductsParams, type ListMessagesResponse, type ListOrdersParams, type ListOrdersResponse, type ListProductVariantsResponse, type ListProductsParams, type ListProductsResponse, type ListReturnsResponse, type ListReviewsParams, type ListReviewsResponse, type ListShipmentsResponse, type ListShippingAddressesResponse, type ListShippingMethodsResponse, type ListShippingRatesResponse, type ListShippingZonesResponse, type ListTaxNexusResponse, type ListTaxReportsParams, type ListTaxReportsResponse, type ListTaxRulesResponse, type MediaAsset, type MediaAssetResponse, type Merchant, MerchantEcommerceClient, type MerchantProductsResponse, type MerchantProfileRequest, type MerchantProfileResponse, type MerchantShippingSettings, MerchantStatus, type Message, type MessageResponse, type MessageStatsResponse, type Order, type OrderEvent, type OrderItem, type OrderReceiptResponse, OrderStatus, type OrdersByStatus, type PaginatedResponse, type PaginationParams, type Payment, PaymentMethod, type PaymentMethodInfo, PaymentStatus, type ProcessPaymentRequest, type ProcessPaymentResponse, type Product, type ProductDimensions, type ProductDiscountsResponse, type ProductMetrics, type ProductResponse, type ProductReview, ProductSortBy, type ProductVariant, type ProductVariantResponse, type PublicMerchantProfile, type PublicMerchantProfileResponse, type RecentOrderSummary, type RespondToReviewRequest, type Return, type ReturnItem, type ReturnResponse, ReturnStatus, type RevenueByDay, type ReviewResponse, ReviewSortBy, ReviewStatus, type SaveBrowsingLocationRequest, type SaveBrowsingLocationResponse, type SendMessageRequest, type Settlement, type Shipment, type ShipmentResponse, ShipmentStatus, type ShippingAddress$1 as ShippingAddress, type ShippingAddressRequest, type ShippingAddressResponse, type ShippingMethod, type ShippingMethodResponse, type ShippingOption, type ShippingRate, type ShippingRateResponse, type ShippingSettingsResponse, type ShippingZone, type ShippingZoneResponse, SortOrder, type SuccessResponse, TaxBehavior, type TaxBreakdownItem, type TaxNexus, type TaxNexusResponse, type TaxReport, type TaxReportDetails, TaxReportPeriodType, type TaxReportResponse, TaxReportStatus, type TaxRule, type TaxRuleResponse, type TaxSettings, type TaxSettingsResponse, TaxType, type TopProduct, type TrackBannerRequest, type UpdateBannerRequest, type UpdateCouponRequest, type UpdateFlashSaleRequest, type UpdateOrderResponse, type UpdateOrderStatusRequest, type UpdateProductRequest, type UpdateProductVariantRequest, type UpdateShipmentRequest, type UpdateShippingMethodRequest, type UpdateShippingRateRequest, type UpdateShippingSettingsRequest, type UpdateShippingZoneRequest, type UpdateTaxNexusRequest, type UpdateTaxReportStatusRequest, type UpdateTaxRuleRequest, type UpdateTaxSettingsRequest, type UserShippingAddress, type ValidateDiscountRequest, type ValidateDiscountResponse, buildQueryString, calculateDiscountAmount, calculateFinalPrice, formatPrice, getBackoffDelay, isRetryableError, isValidAddress, isValidEmail, parseError, retryWithBackoff, sleep, truncateAddress };
+export { type ActiveFlashSalesResponse, type AnalyticsOverview, type ApiResponse, type AppliedDiscount, type Banner, type BannerResponse, BannerType, BaseEcommerceClient, type BaseEntity, type BrowsingLocation, type CalculateCartDiscountsRequest, type CalculateCartDiscountsResponse, type CalculateShippingRequest, type CalculateShippingResponse, type CalculateTaxRequest, type CalculateTaxResponse, type CartItem, type ConfirmEscrowDepositResponse, type Coupon, type CouponResponse, type CouponUsage, type CreateBannerRequest, type CreateCouponRequest, type CreateFlashSaleRequest, type CreateOrderEventRequest, type CreateOrderEventResponse, type CreateOrderRequest, type CreateOrderResponse, type CreateProductRequest, type CreateProductVariantRequest, type CreateReviewRequest, type CreateShippingMethodRequest, type CreateShippingRateRequest, type CreateShippingZoneRequest, type CreateTaxNexusRequest, type CreateTaxRuleRequest, CustomerEcommerceClient, type CustomerMessagesResponse, type CustomerSummary, type DeleteBrowsingLocationResponse, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, type EcommerceClientConfig, type ExpiringGemBatch, type FlashSale, type FlashSaleAllowanceInfo, type FlashSaleItem, type FlashSaleItemInput, type FollowActionResponse, type FollowStatusResponse, type FollowedMerchantSummary, type GemHistoryItem, type GemHistoryType, type GemHistoryTypeFilter, type GemSource, type GenerateTaxReportRequest, type GetAnalyticsParams, type GetAnalyticsResponse, type GetBrowsingLocationResponse, type GetCouponResponse, type GetExpiringGemsParams, type GetExpiringGemsResponse, type GetFlashSaleAllowanceParams, type GetFlashSaleAllowanceResponse, type GetGemBalanceResponse, type GetGemHistoryParams, type GetGemHistoryResponse, type GetOrderResponse, type GetPaymentMethodsResponse, type GetProductMetricsResponse, type GetProductResponse, type GetTaxReportResponse, InventoryAuditAction, type InventoryAuditEntry, type ListActiveBannersParams, type ListActiveFlashSalesParams, type ListBannersResponse, type ListCouponsResponse, type ListCustomersParams, type ListCustomersResponse, type ListFollowingParams, type ListFollowingResponse, type ListInventoryAuditResponse, type ListMediaAssetsResponse, type ListMerchantProductsParams, type ListMessagesResponse, type ListOrdersParams, type ListOrdersResponse, type ListProductVariantsResponse, type ListProductsParams, type ListProductsResponse, type ListReturnsResponse, type ListReviewsParams, type ListReviewsResponse, type ListShipmentsResponse, type ListShippingAddressesResponse, type ListShippingMethodsResponse, type ListShippingRatesResponse, type ListShippingZonesResponse, type ListTaxNexusResponse, type ListTaxReportsParams, type ListTaxReportsResponse, type ListTaxRulesResponse, type MediaAsset, type MediaAssetResponse, type Merchant, MerchantEcommerceClient, type MerchantProductsResponse, type MerchantProfileRequest, type MerchantProfileResponse, type MerchantShippingSettings, MerchantStatus, type Message, type MessageResponse, type MessageStatsResponse, type Order, type OrderEvent, type OrderItem, type OrderReceiptResponse, OrderStatus, type OrdersByStatus, type PaginatedResponse, type PaginationParams, type Payment, PaymentMethod, type PaymentMethodInfo, PaymentStatus, type ProcessPaymentRequest, type ProcessPaymentResponse, type Product, type ProductDimensions, type ProductDiscountsResponse, type ProductMetrics, type ProductResponse, type ProductReview, ProductSortBy, type ProductVariant, type ProductVariantResponse, type PublicMerchantProfile, type PublicMerchantProfileResponse, type RecentOrderSummary, type RespondToReviewRequest, type Return, type ReturnItem, type ReturnResponse, ReturnStatus, type RevenueByDay, type ReviewResponse, ReviewSortBy, ReviewStatus, type SaveBrowsingLocationRequest, type SaveBrowsingLocationResponse, type SendMessageRequest, type Settlement, type Shipment, type ShipmentResponse, ShipmentStatus, type ShippingAddress$1 as ShippingAddress, type ShippingAddressRequest, type ShippingAddressResponse, type ShippingMethod, type ShippingMethodResponse, type ShippingOption, type ShippingRate, type ShippingRateResponse, type ShippingSettingsResponse, type ShippingZone, type ShippingZoneResponse, SortOrder, type SuccessResponse, TaxBehavior, type TaxBreakdownItem, type TaxNexus, type TaxNexusResponse, type TaxReport, type TaxReportDetails, TaxReportPeriodType, type TaxReportResponse, TaxReportStatus, type TaxRule, type TaxRuleResponse, type TaxSettings, type TaxSettingsResponse, TaxType, type TopProduct, type TrackBannerRequest, type UpdateBannerRequest, type UpdateCouponRequest, type UpdateFlashSaleRequest, type UpdateOrderResponse, type UpdateOrderStatusRequest, type UpdateProductRequest, type UpdateProductVariantRequest, type UpdateShipmentRequest, type UpdateShippingMethodRequest, type UpdateShippingRateRequest, type UpdateShippingSettingsRequest, type UpdateShippingZoneRequest, type UpdateTaxNexusRequest, type UpdateTaxReportStatusRequest, type UpdateTaxRuleRequest, type UpdateTaxSettingsRequest, type UserShippingAddress, type ValidateDiscountRequest, type ValidateDiscountResponse, buildQueryString, calculateDiscountAmount, calculateFinalPrice, formatPrice, getBackoffDelay, isRetryableError, isValidAddress, isValidEmail, parseError, retryWithBackoff, sleep, truncateAddress };

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;
 }
 /**
@@ -1754,6 +1772,14 @@ interface ListActiveFlashSalesParams {
     /** Filter by merchant ID */
     merchantId?: string;
 }
+/**
+ * Get flash sale allowance request
+ * Get user's remaining purchase allowance for flash sale items
+ */
+interface GetFlashSaleAllowanceParams {
+    /** Comma-separated list of product IDs */
+    productIds: string[];
+}
 /**
  * Flash sale item input
  */
@@ -2801,6 +2827,34 @@ interface ActiveFlashSalesResponse {
     /** Server time (for client-side sync) */
     serverTime: string;
 }
+/**
+ * Flash sale allowance info for a single product
+ */
+interface FlashSaleAllowanceInfo {
+    /** Flash sale ID */
+    flashSaleId: string;
+    /** Limit per customer (null = no limit) */
+    limitPerCustomer: number | null;
+    /** Quantity already purchased by user */
+    purchased: number;
+    /** Remaining quantity user can purchase (null = no limit) */
+    remaining: number | null;
+    /** Current sale price */
+    salePrice: string;
+    /** Maximum quantity available in flash sale (null = unlimited) */
+    maxQuantity: number | null;
+    /** Remaining quantity in flash sale (null = unlimited) */
+    remainingQuantity: number | null;
+}
+/**
+ * Get flash sale allowance response
+ */
+interface GetFlashSaleAllowanceResponse {
+    /** Allowances by product ID */
+    allowances: Record<string, FlashSaleAllowanceInfo>;
+    /** Whether user is authenticated */
+    authenticated: boolean;
+}
 
 /**
  * Get shipping settings response
@@ -3162,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 },
@@ -3182,6 +3253,7 @@ declare class CustomerEcommerceClient extends BaseEcommerceClient {
      *     postalCode: "10001",
      *     country: "US"
      *   },
+     *   shippingRateId: selectedRateId, // Server validates and calculates cost
      *   couponCode: "SAVE10"
      * });
      *
@@ -3554,6 +3626,32 @@ declare class CustomerEcommerceClient extends BaseEcommerceClient {
      * ```
      */
     getActiveFlashSales(params?: ListActiveFlashSalesParams): Promise<ActiveFlashSalesResponse>;
+    /**
+     * 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}:`);
+     *     console.log(`  Limit: ${info.limitPerCustomer} per customer`);
+     *     console.log(`  You've purchased: ${info.purchased}`);
+     *     console.log(`  You can buy: ${info.remaining} more`);
+     *   }
+     * });
+     * ```
+     */
+    getFlashSaleAllowance(params: GetFlashSaleAllowanceParams): Promise<GetFlashSaleAllowanceResponse>;
     /**
      * Get public merchant profile
      *
@@ -5502,4 +5600,4 @@ declare function calculateDiscountAmount(price: number, discountType: "PERCENTAG
  */
 declare function calculateFinalPrice(price: number, discountType: "PERCENTAGE" | "FIXED_AMOUNT", discountValue: number): number;
 
-export { type ActiveFlashSalesResponse, type AnalyticsOverview, type ApiResponse, type AppliedDiscount, type Banner, type BannerResponse, BannerType, BaseEcommerceClient, type BaseEntity, type BrowsingLocation, type CalculateCartDiscountsRequest, type CalculateCartDiscountsResponse, type CalculateShippingRequest, type CalculateShippingResponse, type CalculateTaxRequest, type CalculateTaxResponse, type CartItem, type ConfirmEscrowDepositResponse, type Coupon, type CouponResponse, type CouponUsage, type CreateBannerRequest, type CreateCouponRequest, type CreateFlashSaleRequest, type CreateOrderEventRequest, type CreateOrderEventResponse, type CreateOrderRequest, type CreateOrderResponse, type CreateProductRequest, type CreateProductVariantRequest, type CreateReviewRequest, type CreateShippingMethodRequest, type CreateShippingRateRequest, type CreateShippingZoneRequest, type CreateTaxNexusRequest, type CreateTaxRuleRequest, CustomerEcommerceClient, type CustomerMessagesResponse, type CustomerSummary, type DeleteBrowsingLocationResponse, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, type EcommerceClientConfig, type ExpiringGemBatch, type FlashSale, type FlashSaleItem, type FlashSaleItemInput, type FollowActionResponse, type FollowStatusResponse, type FollowedMerchantSummary, type GemHistoryItem, type GemHistoryType, type GemHistoryTypeFilter, type GemSource, type GenerateTaxReportRequest, type GetAnalyticsParams, type GetAnalyticsResponse, type GetBrowsingLocationResponse, type GetCouponResponse, type GetExpiringGemsParams, type GetExpiringGemsResponse, type GetGemBalanceResponse, type GetGemHistoryParams, type GetGemHistoryResponse, type GetOrderResponse, type GetPaymentMethodsResponse, type GetProductMetricsResponse, type GetProductResponse, type GetTaxReportResponse, InventoryAuditAction, type InventoryAuditEntry, type ListActiveBannersParams, type ListActiveFlashSalesParams, type ListBannersResponse, type ListCouponsResponse, type ListCustomersParams, type ListCustomersResponse, type ListFollowingParams, type ListFollowingResponse, type ListInventoryAuditResponse, type ListMediaAssetsResponse, type ListMerchantProductsParams, type ListMessagesResponse, type ListOrdersParams, type ListOrdersResponse, type ListProductVariantsResponse, type ListProductsParams, type ListProductsResponse, type ListReturnsResponse, type ListReviewsParams, type ListReviewsResponse, type ListShipmentsResponse, type ListShippingAddressesResponse, type ListShippingMethodsResponse, type ListShippingRatesResponse, type ListShippingZonesResponse, type ListTaxNexusResponse, type ListTaxReportsParams, type ListTaxReportsResponse, type ListTaxRulesResponse, type MediaAsset, type MediaAssetResponse, type Merchant, MerchantEcommerceClient, type MerchantProductsResponse, type MerchantProfileRequest, type MerchantProfileResponse, type MerchantShippingSettings, MerchantStatus, type Message, type MessageResponse, type MessageStatsResponse, type Order, type OrderEvent, type OrderItem, type OrderReceiptResponse, OrderStatus, type OrdersByStatus, type PaginatedResponse, type PaginationParams, type Payment, PaymentMethod, type PaymentMethodInfo, PaymentStatus, type ProcessPaymentRequest, type ProcessPaymentResponse, type Product, type ProductDimensions, type ProductDiscountsResponse, type ProductMetrics, type ProductResponse, type ProductReview, ProductSortBy, type ProductVariant, type ProductVariantResponse, type PublicMerchantProfile, type PublicMerchantProfileResponse, type RecentOrderSummary, type RespondToReviewRequest, type Return, type ReturnItem, type ReturnResponse, ReturnStatus, type RevenueByDay, type ReviewResponse, ReviewSortBy, ReviewStatus, type SaveBrowsingLocationRequest, type SaveBrowsingLocationResponse, type SendMessageRequest, type Settlement, type Shipment, type ShipmentResponse, ShipmentStatus, type ShippingAddress$1 as ShippingAddress, type ShippingAddressRequest, type ShippingAddressResponse, type ShippingMethod, type ShippingMethodResponse, type ShippingOption, type ShippingRate, type ShippingRateResponse, type ShippingSettingsResponse, type ShippingZone, type ShippingZoneResponse, SortOrder, type SuccessResponse, TaxBehavior, type TaxBreakdownItem, type TaxNexus, type TaxNexusResponse, type TaxReport, type TaxReportDetails, TaxReportPeriodType, type TaxReportResponse, TaxReportStatus, type TaxRule, type TaxRuleResponse, type TaxSettings, type TaxSettingsResponse, TaxType, type TopProduct, type TrackBannerRequest, type UpdateBannerRequest, type UpdateCouponRequest, type UpdateFlashSaleRequest, type UpdateOrderResponse, type UpdateOrderStatusRequest, type UpdateProductRequest, type UpdateProductVariantRequest, type UpdateShipmentRequest, type UpdateShippingMethodRequest, type UpdateShippingRateRequest, type UpdateShippingSettingsRequest, type UpdateShippingZoneRequest, type UpdateTaxNexusRequest, type UpdateTaxReportStatusRequest, type UpdateTaxRuleRequest, type UpdateTaxSettingsRequest, type UserShippingAddress, type ValidateDiscountRequest, type ValidateDiscountResponse, buildQueryString, calculateDiscountAmount, calculateFinalPrice, formatPrice, getBackoffDelay, isRetryableError, isValidAddress, isValidEmail, parseError, retryWithBackoff, sleep, truncateAddress };
+export { type ActiveFlashSalesResponse, type AnalyticsOverview, type ApiResponse, type AppliedDiscount, type Banner, type BannerResponse, BannerType, BaseEcommerceClient, type BaseEntity, type BrowsingLocation, type CalculateCartDiscountsRequest, type CalculateCartDiscountsResponse, type CalculateShippingRequest, type CalculateShippingResponse, type CalculateTaxRequest, type CalculateTaxResponse, type CartItem, type ConfirmEscrowDepositResponse, type Coupon, type CouponResponse, type CouponUsage, type CreateBannerRequest, type CreateCouponRequest, type CreateFlashSaleRequest, type CreateOrderEventRequest, type CreateOrderEventResponse, type CreateOrderRequest, type CreateOrderResponse, type CreateProductRequest, type CreateProductVariantRequest, type CreateReviewRequest, type CreateShippingMethodRequest, type CreateShippingRateRequest, type CreateShippingZoneRequest, type CreateTaxNexusRequest, type CreateTaxRuleRequest, CustomerEcommerceClient, type CustomerMessagesResponse, type CustomerSummary, type DeleteBrowsingLocationResponse, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, type EcommerceClientConfig, type ExpiringGemBatch, type FlashSale, type FlashSaleAllowanceInfo, type FlashSaleItem, type FlashSaleItemInput, type FollowActionResponse, type FollowStatusResponse, type FollowedMerchantSummary, type GemHistoryItem, type GemHistoryType, type GemHistoryTypeFilter, type GemSource, type GenerateTaxReportRequest, type GetAnalyticsParams, type GetAnalyticsResponse, type GetBrowsingLocationResponse, type GetCouponResponse, type GetExpiringGemsParams, type GetExpiringGemsResponse, type GetFlashSaleAllowanceParams, type GetFlashSaleAllowanceResponse, type GetGemBalanceResponse, type GetGemHistoryParams, type GetGemHistoryResponse, type GetOrderResponse, type GetPaymentMethodsResponse, type GetProductMetricsResponse, type GetProductResponse, type GetTaxReportResponse, InventoryAuditAction, type InventoryAuditEntry, type ListActiveBannersParams, type ListActiveFlashSalesParams, type ListBannersResponse, type ListCouponsResponse, type ListCustomersParams, type ListCustomersResponse, type ListFollowingParams, type ListFollowingResponse, type ListInventoryAuditResponse, type ListMediaAssetsResponse, type ListMerchantProductsParams, type ListMessagesResponse, type ListOrdersParams, type ListOrdersResponse, type ListProductVariantsResponse, type ListProductsParams, type ListProductsResponse, type ListReturnsResponse, type ListReviewsParams, type ListReviewsResponse, type ListShipmentsResponse, type ListShippingAddressesResponse, type ListShippingMethodsResponse, type ListShippingRatesResponse, type ListShippingZonesResponse, type ListTaxNexusResponse, type ListTaxReportsParams, type ListTaxReportsResponse, type ListTaxRulesResponse, type MediaAsset, type MediaAssetResponse, type Merchant, MerchantEcommerceClient, type MerchantProductsResponse, type MerchantProfileRequest, type MerchantProfileResponse, type MerchantShippingSettings, MerchantStatus, type Message, type MessageResponse, type MessageStatsResponse, type Order, type OrderEvent, type OrderItem, type OrderReceiptResponse, OrderStatus, type OrdersByStatus, type PaginatedResponse, type PaginationParams, type Payment, PaymentMethod, type PaymentMethodInfo, PaymentStatus, type ProcessPaymentRequest, type ProcessPaymentResponse, type Product, type ProductDimensions, type ProductDiscountsResponse, type ProductMetrics, type ProductResponse, type ProductReview, ProductSortBy, type ProductVariant, type ProductVariantResponse, type PublicMerchantProfile, type PublicMerchantProfileResponse, type RecentOrderSummary, type RespondToReviewRequest, type Return, type ReturnItem, type ReturnResponse, ReturnStatus, type RevenueByDay, type ReviewResponse, ReviewSortBy, ReviewStatus, type SaveBrowsingLocationRequest, type SaveBrowsingLocationResponse, type SendMessageRequest, type Settlement, type Shipment, type ShipmentResponse, ShipmentStatus, type ShippingAddress$1 as ShippingAddress, type ShippingAddressRequest, type ShippingAddressResponse, type ShippingMethod, type ShippingMethodResponse, type ShippingOption, type ShippingRate, type ShippingRateResponse, type ShippingSettingsResponse, type ShippingZone, type ShippingZoneResponse, SortOrder, type SuccessResponse, TaxBehavior, type TaxBreakdownItem, type TaxNexus, type TaxNexusResponse, type TaxReport, type TaxReportDetails, TaxReportPeriodType, type TaxReportResponse, TaxReportStatus, type TaxRule, type TaxRuleResponse, type TaxSettings, type TaxSettingsResponse, TaxType, type TopProduct, type TrackBannerRequest, type UpdateBannerRequest, type UpdateCouponRequest, type UpdateFlashSaleRequest, type UpdateOrderResponse, type UpdateOrderStatusRequest, type UpdateProductRequest, type UpdateProductVariantRequest, type UpdateShipmentRequest, type UpdateShippingMethodRequest, type UpdateShippingRateRequest, type UpdateShippingSettingsRequest, type UpdateShippingZoneRequest, type UpdateTaxNexusRequest, type UpdateTaxReportStatusRequest, type UpdateTaxRuleRequest, type UpdateTaxSettingsRequest, type UserShippingAddress, type ValidateDiscountRequest, type ValidateDiscountResponse, buildQueryString, calculateDiscountAmount, calculateFinalPrice, formatPrice, getBackoffDelay, isRetryableError, isValidAddress, isValidEmail, parseError, retryWithBackoff, sleep, truncateAddress };

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"
    * });
    * 
@@ -861,6 +879,35 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
     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}:`);
+   *     console.log(`  Limit: ${info.limitPerCustomer} per customer`);
+   *     console.log(`  You've purchased: ${info.purchased}`);
+   *     console.log(`  You can buy: ${info.remaining} more`);
+   *   }
+   * });
+   * ```
+   */
+  async getFlashSaleAllowance(params) {
+    const queryString = buildQueryString({ productIds: params.productIds.join(",") });
+    return this.get(`/api/marketplace/flash-sales/allowance${queryString}`);
+  }
   // ============================================================================
   // Merchant Storefront API
   // ============================================================================

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-NVL2HX2H.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.d.mts

@@ -1,7 +1,7 @@
 import { SpotToken, MarginTables, PerpsAssetCtx, SpotMeta, ExchangeClient, SuccessResponse, InfoClient } from '@nktkas/hyperliquid';
 import { Hex } from '@nktkas/hyperliquid/types';
 export { A as AllPerpsMeta, d as AssetIdUtils, B as BaseInstrument, I as InstrumentClient, M as MarketInstrument, c as PerpsInstrument, P as PerpsMeta, a as PerpsMetaAndAssetCtxs, b as PerpsUniverse, S as SpotInstrument, g as getAllPerpsMeta } from './client-CgmiTuEX.mjs';
-export { ActiveFlashSalesResponse, AnalyticsOverview, ApiResponse, AppliedDiscount, Banner, BannerResponse, BannerType, BaseEcommerceClient, BaseEntity, BrowsingLocation, CalculateCartDiscountsRequest, CalculateCartDiscountsResponse, CalculateShippingRequest, CalculateShippingResponse, CalculateTaxRequest, CalculateTaxResponse, CartItem, ConfirmEscrowDepositResponse, Coupon, CouponResponse, CouponUsage, CreateBannerRequest, CreateCouponRequest, CreateFlashSaleRequest, CreateOrderEventRequest, CreateOrderEventResponse, CreateOrderRequest, CreateOrderResponse, CreateProductRequest, CreateProductVariantRequest, CreateReviewRequest, CreateShippingMethodRequest, CreateShippingRateRequest, CreateShippingZoneRequest, CreateTaxNexusRequest, CreateTaxRuleRequest, CustomerEcommerceClient, CustomerMessagesResponse, CustomerSummary, DeleteBrowsingLocationResponse, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, EcommerceClientConfig, ExpiringGemBatch, FlashSale, FlashSaleItem, FlashSaleItemInput, FollowActionResponse, FollowStatusResponse, FollowedMerchantSummary, GemHistoryItem, GemHistoryType, GemHistoryTypeFilter, GemSource, GenerateTaxReportRequest, GetAnalyticsParams, GetAnalyticsResponse, GetBrowsingLocationResponse, GetCouponResponse, GetExpiringGemsParams, GetExpiringGemsResponse, GetGemBalanceResponse, GetGemHistoryParams, GetGemHistoryResponse, GetOrderResponse, GetPaymentMethodsResponse, GetProductMetricsResponse, GetProductResponse, GetTaxReportResponse, InventoryAuditAction, InventoryAuditEntry, ListActiveBannersParams, ListActiveFlashSalesParams, ListBannersResponse, ListCouponsResponse, ListCustomersParams, ListCustomersResponse, ListFollowingParams, ListFollowingResponse, ListInventoryAuditResponse, ListMediaAssetsResponse, ListMerchantProductsParams, ListMessagesResponse, ListOrdersParams, ListOrdersResponse, ListProductVariantsResponse, ListProductsParams, ListProductsResponse, ListReturnsResponse, ListReviewsParams, ListReviewsResponse, ListShipmentsResponse, ListShippingAddressesResponse, ListShippingMethodsResponse, ListShippingRatesResponse, ListShippingZonesResponse, ListTaxNexusResponse, ListTaxReportsParams, ListTaxReportsResponse, ListTaxRulesResponse, MediaAsset, MediaAssetResponse, Merchant, MerchantEcommerceClient, MerchantProductsResponse, MerchantProfileRequest, MerchantProfileResponse, MerchantShippingSettings, MerchantStatus, Message, MessageResponse, MessageStatsResponse, Order, OrderEvent, OrderItem, OrderReceiptResponse, OrderStatus, OrdersByStatus, PaginatedResponse, PaginationParams, Payment, PaymentMethod, PaymentMethodInfo, PaymentStatus, ProcessPaymentRequest, ProcessPaymentResponse, Product, ProductDimensions, ProductDiscountsResponse, ProductMetrics, ProductResponse, ProductReview, ProductSortBy, ProductVariant, ProductVariantResponse, PublicMerchantProfile, PublicMerchantProfileResponse, RecentOrderSummary, RespondToReviewRequest, Return, ReturnItem, ReturnResponse, ReturnStatus, RevenueByDay, ReviewResponse, ReviewSortBy, ReviewStatus, SaveBrowsingLocationRequest, SaveBrowsingLocationResponse, SendMessageRequest, Settlement, Shipment, ShipmentResponse, ShipmentStatus, ShippingAddress, ShippingAddressRequest, ShippingAddressResponse, ShippingMethod, ShippingMethodResponse, ShippingOption, ShippingRate, ShippingRateResponse, ShippingSettingsResponse, ShippingZone, ShippingZoneResponse, SortOrder, SuccessResponse, TaxBehavior, TaxBreakdownItem, TaxNexus, TaxNexusResponse, TaxReport, TaxReportDetails, TaxReportPeriodType, TaxReportResponse, TaxReportStatus, TaxRule, TaxRuleResponse, TaxSettings, TaxSettingsResponse, TaxType, TopProduct, TrackBannerRequest, UpdateBannerRequest, UpdateCouponRequest, UpdateFlashSaleRequest, UpdateOrderResponse, UpdateOrderStatusRequest, UpdateProductRequest, UpdateProductVariantRequest, UpdateShipmentRequest, UpdateShippingMethodRequest, UpdateShippingRateRequest, UpdateShippingSettingsRequest, UpdateShippingZoneRequest, UpdateTaxNexusRequest, UpdateTaxReportStatusRequest, UpdateTaxRuleRequest, UpdateTaxSettingsRequest, UserShippingAddress, ValidateDiscountRequest, ValidateDiscountResponse, buildQueryString, calculateDiscountAmount, calculateFinalPrice, formatPrice, getBackoffDelay, isRetryableError, isValidAddress, isValidEmail, parseError, retryWithBackoff, sleep, truncateAddress } from './ecommerce.mjs';
+export { ActiveFlashSalesResponse, AnalyticsOverview, ApiResponse, AppliedDiscount, Banner, BannerResponse, BannerType, BaseEcommerceClient, BaseEntity, BrowsingLocation, CalculateCartDiscountsRequest, CalculateCartDiscountsResponse, CalculateShippingRequest, CalculateShippingResponse, CalculateTaxRequest, CalculateTaxResponse, CartItem, ConfirmEscrowDepositResponse, Coupon, CouponResponse, CouponUsage, CreateBannerRequest, CreateCouponRequest, CreateFlashSaleRequest, CreateOrderEventRequest, CreateOrderEventResponse, CreateOrderRequest, CreateOrderResponse, CreateProductRequest, CreateProductVariantRequest, CreateReviewRequest, CreateShippingMethodRequest, CreateShippingRateRequest, CreateShippingZoneRequest, CreateTaxNexusRequest, CreateTaxRuleRequest, CustomerEcommerceClient, CustomerMessagesResponse, CustomerSummary, DeleteBrowsingLocationResponse, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, EcommerceClientConfig, ExpiringGemBatch, FlashSale, FlashSaleAllowanceInfo, FlashSaleItem, FlashSaleItemInput, FollowActionResponse, FollowStatusResponse, FollowedMerchantSummary, GemHistoryItem, GemHistoryType, GemHistoryTypeFilter, GemSource, GenerateTaxReportRequest, GetAnalyticsParams, GetAnalyticsResponse, GetBrowsingLocationResponse, GetCouponResponse, GetExpiringGemsParams, GetExpiringGemsResponse, GetFlashSaleAllowanceParams, GetFlashSaleAllowanceResponse, GetGemBalanceResponse, GetGemHistoryParams, GetGemHistoryResponse, GetOrderResponse, GetPaymentMethodsResponse, GetProductMetricsResponse, GetProductResponse, GetTaxReportResponse, InventoryAuditAction, InventoryAuditEntry, ListActiveBannersParams, ListActiveFlashSalesParams, ListBannersResponse, ListCouponsResponse, ListCustomersParams, ListCustomersResponse, ListFollowingParams, ListFollowingResponse, ListInventoryAuditResponse, ListMediaAssetsResponse, ListMerchantProductsParams, ListMessagesResponse, ListOrdersParams, ListOrdersResponse, ListProductVariantsResponse, ListProductsParams, ListProductsResponse, ListReturnsResponse, ListReviewsParams, ListReviewsResponse, ListShipmentsResponse, ListShippingAddressesResponse, ListShippingMethodsResponse, ListShippingRatesResponse, ListShippingZonesResponse, ListTaxNexusResponse, ListTaxReportsParams, ListTaxReportsResponse, ListTaxRulesResponse, MediaAsset, MediaAssetResponse, Merchant, MerchantEcommerceClient, MerchantProductsResponse, MerchantProfileRequest, MerchantProfileResponse, MerchantShippingSettings, MerchantStatus, Message, MessageResponse, MessageStatsResponse, Order, OrderEvent, OrderItem, OrderReceiptResponse, OrderStatus, OrdersByStatus, PaginatedResponse, PaginationParams, Payment, PaymentMethod, PaymentMethodInfo, PaymentStatus, ProcessPaymentRequest, ProcessPaymentResponse, Product, ProductDimensions, ProductDiscountsResponse, ProductMetrics, ProductResponse, ProductReview, ProductSortBy, ProductVariant, ProductVariantResponse, PublicMerchantProfile, PublicMerchantProfileResponse, RecentOrderSummary, RespondToReviewRequest, Return, ReturnItem, ReturnResponse, ReturnStatus, RevenueByDay, ReviewResponse, ReviewSortBy, ReviewStatus, SaveBrowsingLocationRequest, SaveBrowsingLocationResponse, SendMessageRequest, Settlement, Shipment, ShipmentResponse, ShipmentStatus, ShippingAddress, ShippingAddressRequest, ShippingAddressResponse, ShippingMethod, ShippingMethodResponse, ShippingOption, ShippingRate, ShippingRateResponse, ShippingSettingsResponse, ShippingZone, ShippingZoneResponse, SortOrder, SuccessResponse, TaxBehavior, TaxBreakdownItem, TaxNexus, TaxNexusResponse, TaxReport, TaxReportDetails, TaxReportPeriodType, TaxReportResponse, TaxReportStatus, TaxRule, TaxRuleResponse, TaxSettings, TaxSettingsResponse, TaxType, TopProduct, TrackBannerRequest, UpdateBannerRequest, UpdateCouponRequest, UpdateFlashSaleRequest, UpdateOrderResponse, UpdateOrderStatusRequest, UpdateProductRequest, UpdateProductVariantRequest, UpdateShipmentRequest, UpdateShippingMethodRequest, UpdateShippingRateRequest, UpdateShippingSettingsRequest, UpdateShippingZoneRequest, UpdateTaxNexusRequest, UpdateTaxReportStatusRequest, UpdateTaxRuleRequest, UpdateTaxSettingsRequest, UserShippingAddress, ValidateDiscountRequest, ValidateDiscountResponse, buildQueryString, calculateDiscountAmount, calculateFinalPrice, formatPrice, getBackoffDelay, isRetryableError, isValidAddress, isValidEmail, parseError, retryWithBackoff, sleep, truncateAddress } from './ecommerce.mjs';
 import 'axios';
 
 declare function encodeSlug(slug: string): bigint;

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import { SpotToken, MarginTables, PerpsAssetCtx, SpotMeta, ExchangeClient, SuccessResponse, InfoClient } from '@nktkas/hyperliquid';
 import { Hex } from '@nktkas/hyperliquid/types';
 export { A as AllPerpsMeta, d as AssetIdUtils, B as BaseInstrument, I as InstrumentClient, M as MarketInstrument, c as PerpsInstrument, P as PerpsMeta, a as PerpsMetaAndAssetCtxs, b as PerpsUniverse, S as SpotInstrument, g as getAllPerpsMeta } from './client-CgmiTuEX.js';
-export { ActiveFlashSalesResponse, AnalyticsOverview, ApiResponse, AppliedDiscount, Banner, BannerResponse, BannerType, BaseEcommerceClient, BaseEntity, BrowsingLocation, CalculateCartDiscountsRequest, CalculateCartDiscountsResponse, CalculateShippingRequest, CalculateShippingResponse, CalculateTaxRequest, CalculateTaxResponse, CartItem, ConfirmEscrowDepositResponse, Coupon, CouponResponse, CouponUsage, CreateBannerRequest, CreateCouponRequest, CreateFlashSaleRequest, CreateOrderEventRequest, CreateOrderEventResponse, CreateOrderRequest, CreateOrderResponse, CreateProductRequest, CreateProductVariantRequest, CreateReviewRequest, CreateShippingMethodRequest, CreateShippingRateRequest, CreateShippingZoneRequest, CreateTaxNexusRequest, CreateTaxRuleRequest, CustomerEcommerceClient, CustomerMessagesResponse, CustomerSummary, DeleteBrowsingLocationResponse, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, EcommerceClientConfig, ExpiringGemBatch, FlashSale, FlashSaleItem, FlashSaleItemInput, FollowActionResponse, FollowStatusResponse, FollowedMerchantSummary, GemHistoryItem, GemHistoryType, GemHistoryTypeFilter, GemSource, GenerateTaxReportRequest, GetAnalyticsParams, GetAnalyticsResponse, GetBrowsingLocationResponse, GetCouponResponse, GetExpiringGemsParams, GetExpiringGemsResponse, GetGemBalanceResponse, GetGemHistoryParams, GetGemHistoryResponse, GetOrderResponse, GetPaymentMethodsResponse, GetProductMetricsResponse, GetProductResponse, GetTaxReportResponse, InventoryAuditAction, InventoryAuditEntry, ListActiveBannersParams, ListActiveFlashSalesParams, ListBannersResponse, ListCouponsResponse, ListCustomersParams, ListCustomersResponse, ListFollowingParams, ListFollowingResponse, ListInventoryAuditResponse, ListMediaAssetsResponse, ListMerchantProductsParams, ListMessagesResponse, ListOrdersParams, ListOrdersResponse, ListProductVariantsResponse, ListProductsParams, ListProductsResponse, ListReturnsResponse, ListReviewsParams, ListReviewsResponse, ListShipmentsResponse, ListShippingAddressesResponse, ListShippingMethodsResponse, ListShippingRatesResponse, ListShippingZonesResponse, ListTaxNexusResponse, ListTaxReportsParams, ListTaxReportsResponse, ListTaxRulesResponse, MediaAsset, MediaAssetResponse, Merchant, MerchantEcommerceClient, MerchantProductsResponse, MerchantProfileRequest, MerchantProfileResponse, MerchantShippingSettings, MerchantStatus, Message, MessageResponse, MessageStatsResponse, Order, OrderEvent, OrderItem, OrderReceiptResponse, OrderStatus, OrdersByStatus, PaginatedResponse, PaginationParams, Payment, PaymentMethod, PaymentMethodInfo, PaymentStatus, ProcessPaymentRequest, ProcessPaymentResponse, Product, ProductDimensions, ProductDiscountsResponse, ProductMetrics, ProductResponse, ProductReview, ProductSortBy, ProductVariant, ProductVariantResponse, PublicMerchantProfile, PublicMerchantProfileResponse, RecentOrderSummary, RespondToReviewRequest, Return, ReturnItem, ReturnResponse, ReturnStatus, RevenueByDay, ReviewResponse, ReviewSortBy, ReviewStatus, SaveBrowsingLocationRequest, SaveBrowsingLocationResponse, SendMessageRequest, Settlement, Shipment, ShipmentResponse, ShipmentStatus, ShippingAddress, ShippingAddressRequest, ShippingAddressResponse, ShippingMethod, ShippingMethodResponse, ShippingOption, ShippingRate, ShippingRateResponse, ShippingSettingsResponse, ShippingZone, ShippingZoneResponse, SortOrder, SuccessResponse, TaxBehavior, TaxBreakdownItem, TaxNexus, TaxNexusResponse, TaxReport, TaxReportDetails, TaxReportPeriodType, TaxReportResponse, TaxReportStatus, TaxRule, TaxRuleResponse, TaxSettings, TaxSettingsResponse, TaxType, TopProduct, TrackBannerRequest, UpdateBannerRequest, UpdateCouponRequest, UpdateFlashSaleRequest, UpdateOrderResponse, UpdateOrderStatusRequest, UpdateProductRequest, UpdateProductVariantRequest, UpdateShipmentRequest, UpdateShippingMethodRequest, UpdateShippingRateRequest, UpdateShippingSettingsRequest, UpdateShippingZoneRequest, UpdateTaxNexusRequest, UpdateTaxReportStatusRequest, UpdateTaxRuleRequest, UpdateTaxSettingsRequest, UserShippingAddress, ValidateDiscountRequest, ValidateDiscountResponse, buildQueryString, calculateDiscountAmount, calculateFinalPrice, formatPrice, getBackoffDelay, isRetryableError, isValidAddress, isValidEmail, parseError, retryWithBackoff, sleep, truncateAddress } from './ecommerce.js';
+export { ActiveFlashSalesResponse, AnalyticsOverview, ApiResponse, AppliedDiscount, Banner, BannerResponse, BannerType, BaseEcommerceClient, BaseEntity, BrowsingLocation, CalculateCartDiscountsRequest, CalculateCartDiscountsResponse, CalculateShippingRequest, CalculateShippingResponse, CalculateTaxRequest, CalculateTaxResponse, CartItem, ConfirmEscrowDepositResponse, Coupon, CouponResponse, CouponUsage, CreateBannerRequest, CreateCouponRequest, CreateFlashSaleRequest, CreateOrderEventRequest, CreateOrderEventResponse, CreateOrderRequest, CreateOrderResponse, CreateProductRequest, CreateProductVariantRequest, CreateReviewRequest, CreateShippingMethodRequest, CreateShippingRateRequest, CreateShippingZoneRequest, CreateTaxNexusRequest, CreateTaxRuleRequest, CustomerEcommerceClient, CustomerMessagesResponse, CustomerSummary, DeleteBrowsingLocationResponse, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, EcommerceClientConfig, ExpiringGemBatch, FlashSale, FlashSaleAllowanceInfo, FlashSaleItem, FlashSaleItemInput, FollowActionResponse, FollowStatusResponse, FollowedMerchantSummary, GemHistoryItem, GemHistoryType, GemHistoryTypeFilter, GemSource, GenerateTaxReportRequest, GetAnalyticsParams, GetAnalyticsResponse, GetBrowsingLocationResponse, GetCouponResponse, GetExpiringGemsParams, GetExpiringGemsResponse, GetFlashSaleAllowanceParams, GetFlashSaleAllowanceResponse, GetGemBalanceResponse, GetGemHistoryParams, GetGemHistoryResponse, GetOrderResponse, GetPaymentMethodsResponse, GetProductMetricsResponse, GetProductResponse, GetTaxReportResponse, InventoryAuditAction, InventoryAuditEntry, ListActiveBannersParams, ListActiveFlashSalesParams, ListBannersResponse, ListCouponsResponse, ListCustomersParams, ListCustomersResponse, ListFollowingParams, ListFollowingResponse, ListInventoryAuditResponse, ListMediaAssetsResponse, ListMerchantProductsParams, ListMessagesResponse, ListOrdersParams, ListOrdersResponse, ListProductVariantsResponse, ListProductsParams, ListProductsResponse, ListReturnsResponse, ListReviewsParams, ListReviewsResponse, ListShipmentsResponse, ListShippingAddressesResponse, ListShippingMethodsResponse, ListShippingRatesResponse, ListShippingZonesResponse, ListTaxNexusResponse, ListTaxReportsParams, ListTaxReportsResponse, ListTaxRulesResponse, MediaAsset, MediaAssetResponse, Merchant, MerchantEcommerceClient, MerchantProductsResponse, MerchantProfileRequest, MerchantProfileResponse, MerchantShippingSettings, MerchantStatus, Message, MessageResponse, MessageStatsResponse, Order, OrderEvent, OrderItem, OrderReceiptResponse, OrderStatus, OrdersByStatus, PaginatedResponse, PaginationParams, Payment, PaymentMethod, PaymentMethodInfo, PaymentStatus, ProcessPaymentRequest, ProcessPaymentResponse, Product, ProductDimensions, ProductDiscountsResponse, ProductMetrics, ProductResponse, ProductReview, ProductSortBy, ProductVariant, ProductVariantResponse, PublicMerchantProfile, PublicMerchantProfileResponse, RecentOrderSummary, RespondToReviewRequest, Return, ReturnItem, ReturnResponse, ReturnStatus, RevenueByDay, ReviewResponse, ReviewSortBy, ReviewStatus, SaveBrowsingLocationRequest, SaveBrowsingLocationResponse, SendMessageRequest, Settlement, Shipment, ShipmentResponse, ShipmentStatus, ShippingAddress, ShippingAddressRequest, ShippingAddressResponse, ShippingMethod, ShippingMethodResponse, ShippingOption, ShippingRate, ShippingRateResponse, ShippingSettingsResponse, ShippingZone, ShippingZoneResponse, SortOrder, SuccessResponse, TaxBehavior, TaxBreakdownItem, TaxNexus, TaxNexusResponse, TaxReport, TaxReportDetails, TaxReportPeriodType, TaxReportResponse, TaxReportStatus, TaxRule, TaxRuleResponse, TaxSettings, TaxSettingsResponse, TaxType, TopProduct, TrackBannerRequest, UpdateBannerRequest, UpdateCouponRequest, UpdateFlashSaleRequest, UpdateOrderResponse, UpdateOrderStatusRequest, UpdateProductRequest, UpdateProductVariantRequest, UpdateShipmentRequest, UpdateShippingMethodRequest, UpdateShippingRateRequest, UpdateShippingSettingsRequest, UpdateShippingZoneRequest, UpdateTaxNexusRequest, UpdateTaxReportStatusRequest, UpdateTaxRuleRequest, UpdateTaxSettingsRequest, UserShippingAddress, ValidateDiscountRequest, ValidateDiscountResponse, buildQueryString, calculateDiscountAmount, calculateFinalPrice, formatPrice, getBackoffDelay, isRetryableError, isValidAddress, isValidEmail, parseError, retryWithBackoff, sleep, truncateAddress } from './ecommerce.js';
 import 'axios';
 
 declare function encodeSlug(slug: string): bigint;

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"
    * });
    * 
@@ -43187,6 +43205,35 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
     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}:`);
+   *     console.log(`  Limit: ${info.limitPerCustomer} per customer`);
+   *     console.log(`  You've purchased: ${info.purchased}`);
+   *     console.log(`  You can buy: ${info.remaining} more`);
+   *   }
+   * });
+   * ```
+   */
+  async getFlashSaleAllowance(params) {
+    const queryString = buildQueryString({ productIds: params.productIds.join(",") });
+    return this.get(`/api/marketplace/flash-sales/allowance${queryString}`);
+  }
   // ============================================================================
   // Merchant Storefront API
   // ============================================================================

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-NVL2HX2H.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

@@ -22,6 +22,7 @@ import type {
   TrackBannerRequest,
   SendMessageRequest,
   ListActiveFlashSalesParams,
+  GetFlashSaleAllowanceParams,
   ListMerchantProductsParams,
   ListFollowingParams,
   CalculateShippingRequest,
@@ -51,6 +52,7 @@ import type {
   MessageStatsResponse,
   MessageResponse,
   ActiveFlashSalesResponse,
+  GetFlashSaleAllowanceResponse,
   GetPaymentMethodsResponse,
   PublicMerchantProfileResponse,
   MerchantProductsResponse,
@@ -176,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 },
@@ -196,6 +215,7 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
    *     postalCode: "10001",
    *     country: "US"
    *   },
+   *   shippingRateId: selectedRateId, // Server validates and calculates cost
    *   couponCode: "SAVE10"
    * });
    * 
@@ -684,6 +704,36 @@ export class CustomerEcommerceClient extends BaseEcommerceClient {
     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}:`);
+   *     console.log(`  Limit: ${info.limitPerCustomer} per customer`);
+   *     console.log(`  You've purchased: ${info.purchased}`);
+   *     console.log(`  You can buy: ${info.remaining} more`);
+   *   }
+   * });
+   * ```
+   */
+  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

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;
 }
 
@@ -547,6 +560,15 @@ export interface ListActiveFlashSalesParams {
   merchantId?: string;
 }
 
+/**
+ * Get flash sale allowance request
+ * Get user's remaining purchase allowance for flash sale items
+ */
+export interface GetFlashSaleAllowanceParams {
+  /** Comma-separated list of product IDs */
+  productIds: string[];
+}
+
 /**
  * Flash sale item input
  */

package/lib/ecommerce/types/responses.ts

@@ -951,6 +951,36 @@ export interface ActiveFlashSalesResponse {
   serverTime: string;
 }
 
+/**
+ * Flash sale allowance info for a single product
+ */
+export interface FlashSaleAllowanceInfo {
+  /** Flash sale ID */
+  flashSaleId: string;
+  /** Limit per customer (null = no limit) */
+  limitPerCustomer: number | null;
+  /** Quantity already purchased by user */
+  purchased: number;
+  /** Remaining quantity user can purchase (null = no limit) */
+  remaining: number | null;
+  /** Current sale price */
+  salePrice: string;
+  /** Maximum quantity available in flash sale (null = unlimited) */
+  maxQuantity: number | null;
+  /** Remaining quantity in flash sale (null = unlimited) */
+  remainingQuantity: number | null;
+}
+
+/**
+ * Get flash sale allowance response
+ */
+export interface GetFlashSaleAllowanceResponse {
+  /** Allowances by product ID */
+  allowances: Record<string, FlashSaleAllowanceInfo>;
+  /** Whether user is authenticated */
+  authenticated: boolean;
+}
+
 // ============================================
 // SHIPPING RESPONSES
 // ============================================

package/package.json

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