@basedone/core 0.2.8 → 0.3.0

package/dist/{chunk-NKSQEISP.mjs → chunk-35WGIB5F.mjs}

@@ -1220,6 +1220,38 @@ var CustomerEcommerceClient = class extends BaseEcommerceClient {
   async getDeliveryAddress() {
     return this.get("/api/basedpay/delivery-address");
   }
+  /**
+   * Get user's Hyperliquid USDC balance (perp withdrawable)
+   *
+   * Returns the USDC balance available for escrow deposits via usdSend.
+   *
+   * @returns Balance response with amount and currency
+   */
+  async getUsdcBalance() {
+    return this.get("/api/marketplace/usdc-balance");
+  }
+  // ============================================================================
+  // Notifications API
+  // ============================================================================
+  /**
+   * List notifications for the authenticated customer
+   *
+   * @param params - Query parameters for filtering and pagination
+   * @returns Paginated list of notifications with unread count
+   */
+  async listNotifications(params) {
+    const queryString = params ? buildQueryString(params) : "";
+    return this.get(`/api/marketplace/notifications${queryString}`);
+  }
+  /**
+   * Mark notifications as read
+   *
+   * @param ids - Specific notification IDs to mark as read. If omitted, marks all as read.
+   * @returns Count of updated notifications
+   */
+  async markNotificationsAsRead(ids) {
+    return this.patch("/api/marketplace/notifications/read", { ids });
+  }
 };
 
 // lib/ecommerce/client/merchant.ts
@@ -2765,6 +2797,7 @@ var OrderStatus = /* @__PURE__ */ ((OrderStatus2) => {
   OrderStatus2["SHIPPED"] = "SHIPPED";
   OrderStatus2["DELIVERED"] = "DELIVERED";
   OrderStatus2["CANCELLED"] = "CANCELLED";
+  OrderStatus2["SETTLED"] = "SETTLED";
   OrderStatus2["CONFIRMED"] = "CONFIRMED";
   OrderStatus2["COMPLETED"] = "COMPLETED";
   return OrderStatus2;
@@ -2898,6 +2931,7 @@ var ProductSortBy = /* @__PURE__ */ ((ProductSortBy2) => {
   ProductSortBy2["PRICE_ASC"] = "price_asc";
   ProductSortBy2["PRICE_DESC"] = "price_desc";
   ProductSortBy2["POPULAR"] = "popular";
+  ProductSortBy2["BEST_SELLING"] = "best_selling";
   ProductSortBy2["FEATURED"] = "featured";
   ProductSortBy2["NEARBY"] = "nearby";
   return ProductSortBy2;
@@ -2909,4 +2943,118 @@ var ReviewSortBy = /* @__PURE__ */ ((ReviewSortBy2) => {
   return ReviewSortBy2;
 })(ReviewSortBy || {});
 
-export { BannerType, BaseEcommerceClient, CustomerEcommerceClient, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, InventoryAuditAction, MerchantBusinessType, MerchantEcommerceClient, MerchantReturnPolicyType, 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 };
+// lib/ecommerce/utils/orderStateMachine.ts
+function isPickupOrder(shippingMethod, shippingRateId) {
+  if (shippingRateId && shippingRateId.trim().toUpperCase() === "PICKUP") {
+    return true;
+  }
+  if (!shippingMethod) return false;
+  const normalized = shippingMethod.trim().toLowerCase().replace(/[\s-]+/g, " ");
+  return normalized === "pickup" || normalized === "on site collection" || normalized === "onsite collection";
+}
+var ORDER_STATUS_TRANSITIONS = {
+  ["CREATED" /* CREATED */]: [
+    "PAYMENT_RESERVED" /* PAYMENT_RESERVED */,
+    "MERCHANT_ACCEPTED" /* MERCHANT_ACCEPTED */,
+    "CANCELLED" /* CANCELLED */
+  ],
+  ["PAYMENT_RESERVED" /* PAYMENT_RESERVED */]: [
+    "MERCHANT_ACCEPTED" /* MERCHANT_ACCEPTED */,
+    "CANCELLED" /* CANCELLED */
+  ],
+  ["MERCHANT_ACCEPTED" /* MERCHANT_ACCEPTED */]: [
+    "SHIPPED" /* SHIPPED */,
+    "CANCELLED" /* CANCELLED */
+  ],
+  // Backward compat for existing SETTLED orders created before escrow change
+  // Note: CANCELLED removed — settled orders have funds paid out, no clawback mechanism
+  ["SETTLED" /* SETTLED */]: ["SHIPPED" /* SHIPPED */],
+  ["SHIPPED" /* SHIPPED */]: ["DELIVERED" /* DELIVERED */, "CANCELLED" /* CANCELLED */],
+  // Settlement triggered on delivery (buyer-protected escrow)
+  ["DELIVERED" /* DELIVERED */]: ["SETTLED" /* SETTLED */],
+  // Terminal states
+  ["CANCELLED" /* CANCELLED */]: []
+};
+function validateStatusTransition(currentStatus, newStatus, options) {
+  if (isPickupOrder(options?.shippingMethod, options?.shippingRateId) && (currentStatus === "MERCHANT_ACCEPTED" /* MERCHANT_ACCEPTED */ || currentStatus === "SETTLED" /* SETTLED */) && newStatus === "DELIVERED" /* DELIVERED */) {
+    return { valid: true };
+  }
+  const allowed = ORDER_STATUS_TRANSITIONS[currentStatus] ?? [];
+  if (!allowed.includes(newStatus)) {
+    if (allowed.length === 0) {
+      return {
+        valid: false,
+        error: `Cannot change status from ${currentStatus} \u2014 this is a final state`
+      };
+    }
+    return {
+      valid: false,
+      error: `Cannot transition from ${currentStatus} to ${newStatus}. Allowed: ${allowed.join(", ")}`
+    };
+  }
+  return { valid: true };
+}
+function getNextStatuses(currentStatus, options) {
+  const base = [
+    ...ORDER_STATUS_TRANSITIONS[currentStatus] ?? []
+  ];
+  if (isPickupOrder(options?.shippingMethod, options?.shippingRateId) && (currentStatus === "MERCHANT_ACCEPTED" /* MERCHANT_ACCEPTED */ || currentStatus === "SETTLED" /* SETTLED */) && !base.includes("DELIVERED" /* DELIVERED */)) {
+    base.push("DELIVERED" /* DELIVERED */);
+  }
+  return base;
+}
+function getStatusLabel(status) {
+  const labels = {
+    CREATED: "Created",
+    PAYMENT_RESERVED: "Payment Reserved",
+    MERCHANT_ACCEPTED: "Accepted",
+    SETTLED: "Completed (Paid)",
+    SHIPPED: "Shipped",
+    DELIVERED: "Delivered",
+    CANCELLED: "Cancelled"
+  };
+  return labels[status] || status;
+}
+function getStatusColor(status) {
+  const colors = {
+    CREATED: "gray",
+    PAYMENT_RESERVED: "blue",
+    MERCHANT_ACCEPTED: "purple",
+    SETTLED: "indigo",
+    SHIPPED: "yellow",
+    DELIVERED: "green",
+    CANCELLED: "red"
+  };
+  return colors[status] || "gray";
+}
+function canCancelOrder(currentStatus) {
+  return ORDER_STATUS_TRANSITIONS[currentStatus]?.includes(
+    "CANCELLED" /* CANCELLED */
+  ) ?? false;
+}
+function requiresTrackingInfo(newStatus, options) {
+  if (newStatus !== "SHIPPED" /* SHIPPED */) return false;
+  return !isPickupOrder(options?.shippingMethod, options?.shippingRateId);
+}
+function shouldNotifyCustomer(newStatus) {
+  return [
+    "MERCHANT_ACCEPTED" /* MERCHANT_ACCEPTED */,
+    "SHIPPED" /* SHIPPED */,
+    "DELIVERED" /* DELIVERED */,
+    "CANCELLED" /* CANCELLED */
+  ].includes(newStatus);
+}
+function getStatusProgress(status) {
+  const progressMap = {
+    CREATED: 10,
+    PAYMENT_RESERVED: 25,
+    MERCHANT_ACCEPTED: 40,
+    SETTLED: 50,
+    SHIPPED: 75,
+    DELIVERED: 100,
+    CANCELLED: 0
+  };
+  return progressMap[status] || 0;
+}
+
+export { BannerType, BaseEcommerceClient, CustomerEcommerceClient, DiscountMethod, DiscountScope, DiscountType, EcommerceApiError, InventoryAuditAction, MerchantBusinessType, MerchantEcommerceClient, MerchantReturnPolicyType, MerchantStatus, ORDER_STATUS_TRANSITIONS, OrderStatus, PaymentMethod, PaymentStatus, ProductSortBy, ReturnStatus, ReviewSortBy, ReviewStatus, ShipmentStatus, SortOrder, TaxBehavior, TaxReportPeriodType, TaxReportStatus, TaxType, buildQueryString, calculateDiscountAmount, calculateFinalPrice, canCancelOrder, formatPrice, getBackoffDelay, getNextStatuses, getStatusColor, getStatusLabel, getStatusProgress, isPickupOrder, isRetryableError, isValidAddress, isValidEmail, parseError, requiresTrackingInfo, retryWithBackoff, shouldNotifyCustomer, sleep, truncateAddress, validateStatusTransition };

package/dist/{client-DMVXX1Gw.d.mts → client-BQzYwHDY.d.mts}

@@ -1,4 +1,4 @@
-import { MarginTables, PerpsAssetCtx, PerpDex as PerpDex$1, InfoClient, SpotToken, SpotMeta } from '@nktkas/hyperliquid';
+import { MarginTables, PerpDex as PerpDex$1, PerpsAssetCtx, InfoClient, SpotMeta, SpotToken } from '@nktkas/hyperliquid';
 
 interface PerpsMeta {
     collateralToken: number;
@@ -179,4 +179,4 @@ declare class InstrumentClient {
     private extractDexNameFromMeta;
 }
 
-export { type AllPerpsMeta as A, type BaseInstrument as B, InstrumentClient as I, type MarketInstrument as M, type PerpsMeta as P, type SpotInstrument as S, type PerpsMetaAndAssetCtxs as a, type PerpsUniverse as b, type PerpDex as c, type PerpsInstrument as d, AssetIdUtils as e, getAllPerpsMeta as g };
+export { type AllPerpsMeta as A, type BaseInstrument as B, InstrumentClient as I, type MarketInstrument as M, type PerpDex as P, type SpotInstrument as S, AssetIdUtils as a, type PerpsInstrument as b, type PerpsMeta as c, type PerpsMetaAndAssetCtxs as d, type PerpsUniverse as e, getAllPerpsMeta as g };

package/dist/{client-DMVXX1Gw.d.ts → client-BQzYwHDY.d.ts}

@@ -1,4 +1,4 @@
-import { MarginTables, PerpsAssetCtx, PerpDex as PerpDex$1, InfoClient, SpotToken, SpotMeta } from '@nktkas/hyperliquid';
+import { MarginTables, PerpDex as PerpDex$1, PerpsAssetCtx, InfoClient, SpotMeta, SpotToken } from '@nktkas/hyperliquid';
 
 interface PerpsMeta {
     collateralToken: number;
@@ -179,4 +179,4 @@ declare class InstrumentClient {
     private extractDexNameFromMeta;
 }
 
-export { type AllPerpsMeta as A, type BaseInstrument as B, InstrumentClient as I, type MarketInstrument as M, type PerpsMeta as P, type SpotInstrument as S, type PerpsMetaAndAssetCtxs as a, type PerpsUniverse as b, type PerpDex as c, type PerpsInstrument as d, AssetIdUtils as e, getAllPerpsMeta as g };
+export { type AllPerpsMeta as A, type BaseInstrument as B, InstrumentClient as I, type MarketInstrument as M, type PerpDex as P, type SpotInstrument as S, AssetIdUtils as a, type PerpsInstrument as b, type PerpsMeta as c, type PerpsMetaAndAssetCtxs as d, type PerpsUniverse as e, getAllPerpsMeta as g };

package/dist/ecommerce.d.mts

@@ -192,6 +192,8 @@ declare enum OrderStatus {
     DELIVERED = "DELIVERED",
     /** Order has been cancelled */
     CANCELLED = "CANCELLED",
+    /** Payment settled / escrow released to merchant */
+    SETTLED = "SETTLED",
     /** Order is confirmed (legacy status) */
     CONFIRMED = "CONFIRMED",
     /** Order is completed (legacy status) */
@@ -437,8 +439,10 @@ declare enum ProductSortBy {
     PRICE_ASC = "price_asc",
     /** Sort by price (high to low) */
     PRICE_DESC = "price_desc",
-    /** Sort by popularity */
+    /** Sort by popularity (views) */
     POPULAR = "popular",
+    /** Sort by best selling (sold quantity) */
+    BEST_SELLING = "best_selling",
     /** Sort by featured status */
     FEATURED = "featured",
     /** Sort by proximity to user location (requires lat/lng) */
@@ -770,6 +774,20 @@ interface Order extends BaseEntity {
     };
     /** Order events */
     events?: OrderEvent[];
+    /** Expected ship date */
+    expectedShipDate?: string | null;
+    /** Estimated delivery date */
+    estimatedDeliveryDate?: string | null;
+    /** Estimated delivery days */
+    estimatedDeliveryDays?: number | null;
+    /** Auto-complete deadline */
+    autoCompleteDeadline?: string | null;
+    /** Customer confirmed receipt timestamp */
+    customerConfirmedAt?: string | null;
+    /** Auto-completed timestamp */
+    autoCompletedAt?: string | null;
+    /** Status transition timestamps */
+    statusTransitions?: Record<string, string> | null;
 }
 /**
  * Order event entity
@@ -2288,6 +2306,10 @@ interface ValidateDiscountResponse {
         /** Discount amount */
         discountAmount: number;
     };
+    /** Merchant ID the discount belongs to */
+    merchantId?: string;
+    /** Merchant name the discount belongs to */
+    merchantName?: string | null;
     /** Subtotal */
     subtotal?: number;
     /** Total */
@@ -3207,6 +3229,30 @@ interface CashAccountBalanceResponse {
     /** Currency code (e.g., "USD") */
     currency: string;
 }
+interface CustomerNotification {
+    id: string;
+    type: string;
+    title: string;
+    message: string;
+    metadata: Record<string, any> | null;
+    isRead: boolean;
+    createdAt: string;
+}
+interface CustomerNotificationsResponse {
+    notifications: CustomerNotification[];
+    stats: {
+        unread: number;
+    };
+    pagination: {
+        total: number;
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+    };
+}
+interface MarkNotificationsReadResponse {
+    updated: number;
+}
 interface DeliveryAddressResponse {
     name: string;
     phoneNumber: string;
@@ -4013,6 +4059,32 @@ declare class CustomerEcommerceClient extends BaseEcommerceClient {
      * ```
      */
     getDeliveryAddress(): Promise<DeliveryAddressResponse>;
+    /**
+     * Get user's Hyperliquid USDC balance (perp withdrawable)
+     *
+     * Returns the USDC balance available for escrow deposits via usdSend.
+     *
+     * @returns Balance response with amount and currency
+     */
+    getUsdcBalance(): Promise<CashAccountBalanceResponse>;
+    /**
+     * List notifications for the authenticated customer
+     *
+     * @param params - Query parameters for filtering and pagination
+     * @returns Paginated list of notifications with unread count
+     */
+    listNotifications(params?: {
+        limit?: number;
+        offset?: number;
+        unreadOnly?: boolean;
+    }): Promise<CustomerNotificationsResponse>;
+    /**
+     * Mark notifications as read
+     *
+     * @param ids - Specific notification IDs to mark as read. If omitted, marks all as read.
+     * @returns Count of updated notifications
+     */
+    markNotificationsAsRead(ids?: string[]): Promise<MarkNotificationsReadResponse>;
 }
 
 /**
@@ -5727,4 +5799,52 @@ 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 CashAccountBalanceResponse, 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, type DeliveryAddressResponse, 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, MerchantBusinessType, MerchantEcommerceClient, type MerchantProductsResponse, type MerchantProfileRequest, type MerchantProfileResponse, MerchantReturnPolicyType, type MerchantShippingSettings, type MerchantSocialLinks, 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 };
+/** Detect pickup / on-site-collection shipping methods (normalised matching) */
+declare function isPickupOrder(shippingMethod?: string | null, shippingRateId?: string | null): boolean;
+/**
+ * Canonical order status transitions.
+ *
+ * Buyer-protected escrow flow:
+ *   CREATED → PAYMENT_RESERVED → MERCHANT_ACCEPTED → SHIPPED → DELIVERED → SETTLED
+ *
+ * Cancellation is allowed from any non-terminal state except DELIVERED (already in settlement).
+ */
+declare const ORDER_STATUS_TRANSITIONS: Partial<Record<OrderStatus, OrderStatus[]>>;
+/**
+ * Validate whether transitioning from `currentStatus` to `newStatus` is allowed.
+ *
+ * For pickup / on-site-collection orders, MERCHANT_ACCEPTED → DELIVERED and
+ * SETTLED → DELIVERED are permitted (skipping SHIPPED).
+ */
+declare function validateStatusTransition(currentStatus: string, newStatus: string, options?: {
+    shippingMethod?: string | null;
+    shippingRateId?: string | null;
+}): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Return the list of statuses reachable from `currentStatus`.
+ * For pickup orders, DELIVERED is added when on MERCHANT_ACCEPTED or SETTLED.
+ */
+declare function getNextStatuses(currentStatus: string, options?: {
+    shippingMethod?: string | null;
+    shippingRateId?: string | null;
+}): string[];
+/** Human-readable label for a status. */
+declare function getStatusLabel(status: string): string;
+/** UI colour key for a status. */
+declare function getStatusColor(status: string): string;
+/** Whether the order can be cancelled from its current status. */
+declare function canCancelOrder(currentStatus: string): boolean;
+/** Whether tracking info is required for a status change. */
+declare function requiresTrackingInfo(newStatus: string, options?: {
+    shippingMethod?: string | null;
+    shippingRateId?: string | null;
+}): boolean;
+/** Whether a status change should trigger customer notification. */
+declare function shouldNotifyCustomer(newStatus: string): boolean;
+/** Status progression percentage (for progress bars). */
+declare function getStatusProgress(status: string): 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 CashAccountBalanceResponse, 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 CustomerNotification, type CustomerNotificationsResponse, type CustomerSummary, type DeleteBrowsingLocationResponse, type DeliveryAddressResponse, 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 MarkNotificationsReadResponse, type MediaAsset, type MediaAssetResponse, type Merchant, MerchantBusinessType, MerchantEcommerceClient, type MerchantProductsResponse, type MerchantProfileRequest, type MerchantProfileResponse, MerchantReturnPolicyType, type MerchantShippingSettings, type MerchantSocialLinks, MerchantStatus, type Message, type MessageResponse, type MessageStatsResponse, ORDER_STATUS_TRANSITIONS, 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, canCancelOrder, formatPrice, getBackoffDelay, getNextStatuses, getStatusColor, getStatusLabel, getStatusProgress, isPickupOrder, isRetryableError, isValidAddress, isValidEmail, parseError, requiresTrackingInfo, retryWithBackoff, shouldNotifyCustomer, sleep, truncateAddress, validateStatusTransition };

package/dist/ecommerce.d.ts

@@ -192,6 +192,8 @@ declare enum OrderStatus {
     DELIVERED = "DELIVERED",
     /** Order has been cancelled */
     CANCELLED = "CANCELLED",
+    /** Payment settled / escrow released to merchant */
+    SETTLED = "SETTLED",
     /** Order is confirmed (legacy status) */
     CONFIRMED = "CONFIRMED",
     /** Order is completed (legacy status) */
@@ -437,8 +439,10 @@ declare enum ProductSortBy {
     PRICE_ASC = "price_asc",
     /** Sort by price (high to low) */
     PRICE_DESC = "price_desc",
-    /** Sort by popularity */
+    /** Sort by popularity (views) */
     POPULAR = "popular",
+    /** Sort by best selling (sold quantity) */
+    BEST_SELLING = "best_selling",
     /** Sort by featured status */
     FEATURED = "featured",
     /** Sort by proximity to user location (requires lat/lng) */
@@ -770,6 +774,20 @@ interface Order extends BaseEntity {
     };
     /** Order events */
     events?: OrderEvent[];
+    /** Expected ship date */
+    expectedShipDate?: string | null;
+    /** Estimated delivery date */
+    estimatedDeliveryDate?: string | null;
+    /** Estimated delivery days */
+    estimatedDeliveryDays?: number | null;
+    /** Auto-complete deadline */
+    autoCompleteDeadline?: string | null;
+    /** Customer confirmed receipt timestamp */
+    customerConfirmedAt?: string | null;
+    /** Auto-completed timestamp */
+    autoCompletedAt?: string | null;
+    /** Status transition timestamps */
+    statusTransitions?: Record<string, string> | null;
 }
 /**
  * Order event entity
@@ -2288,6 +2306,10 @@ interface ValidateDiscountResponse {
         /** Discount amount */
         discountAmount: number;
     };
+    /** Merchant ID the discount belongs to */
+    merchantId?: string;
+    /** Merchant name the discount belongs to */
+    merchantName?: string | null;
     /** Subtotal */
     subtotal?: number;
     /** Total */
@@ -3207,6 +3229,30 @@ interface CashAccountBalanceResponse {
     /** Currency code (e.g., "USD") */
     currency: string;
 }
+interface CustomerNotification {
+    id: string;
+    type: string;
+    title: string;
+    message: string;
+    metadata: Record<string, any> | null;
+    isRead: boolean;
+    createdAt: string;
+}
+interface CustomerNotificationsResponse {
+    notifications: CustomerNotification[];
+    stats: {
+        unread: number;
+    };
+    pagination: {
+        total: number;
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+    };
+}
+interface MarkNotificationsReadResponse {
+    updated: number;
+}
 interface DeliveryAddressResponse {
     name: string;
     phoneNumber: string;
@@ -4013,6 +4059,32 @@ declare class CustomerEcommerceClient extends BaseEcommerceClient {
      * ```
      */
     getDeliveryAddress(): Promise<DeliveryAddressResponse>;
+    /**
+     * Get user's Hyperliquid USDC balance (perp withdrawable)
+     *
+     * Returns the USDC balance available for escrow deposits via usdSend.
+     *
+     * @returns Balance response with amount and currency
+     */
+    getUsdcBalance(): Promise<CashAccountBalanceResponse>;
+    /**
+     * List notifications for the authenticated customer
+     *
+     * @param params - Query parameters for filtering and pagination
+     * @returns Paginated list of notifications with unread count
+     */
+    listNotifications(params?: {
+        limit?: number;
+        offset?: number;
+        unreadOnly?: boolean;
+    }): Promise<CustomerNotificationsResponse>;
+    /**
+     * Mark notifications as read
+     *
+     * @param ids - Specific notification IDs to mark as read. If omitted, marks all as read.
+     * @returns Count of updated notifications
+     */
+    markNotificationsAsRead(ids?: string[]): Promise<MarkNotificationsReadResponse>;
 }
 
 /**
@@ -5727,4 +5799,52 @@ 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 CashAccountBalanceResponse, 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, type DeliveryAddressResponse, 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, MerchantBusinessType, MerchantEcommerceClient, type MerchantProductsResponse, type MerchantProfileRequest, type MerchantProfileResponse, MerchantReturnPolicyType, type MerchantShippingSettings, type MerchantSocialLinks, 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 };
+/** Detect pickup / on-site-collection shipping methods (normalised matching) */
+declare function isPickupOrder(shippingMethod?: string | null, shippingRateId?: string | null): boolean;
+/**
+ * Canonical order status transitions.
+ *
+ * Buyer-protected escrow flow:
+ *   CREATED → PAYMENT_RESERVED → MERCHANT_ACCEPTED → SHIPPED → DELIVERED → SETTLED
+ *
+ * Cancellation is allowed from any non-terminal state except DELIVERED (already in settlement).
+ */
+declare const ORDER_STATUS_TRANSITIONS: Partial<Record<OrderStatus, OrderStatus[]>>;
+/**
+ * Validate whether transitioning from `currentStatus` to `newStatus` is allowed.
+ *
+ * For pickup / on-site-collection orders, MERCHANT_ACCEPTED → DELIVERED and
+ * SETTLED → DELIVERED are permitted (skipping SHIPPED).
+ */
+declare function validateStatusTransition(currentStatus: string, newStatus: string, options?: {
+    shippingMethod?: string | null;
+    shippingRateId?: string | null;
+}): {
+    valid: boolean;
+    error?: string;
+};
+/**
+ * Return the list of statuses reachable from `currentStatus`.
+ * For pickup orders, DELIVERED is added when on MERCHANT_ACCEPTED or SETTLED.
+ */
+declare function getNextStatuses(currentStatus: string, options?: {
+    shippingMethod?: string | null;
+    shippingRateId?: string | null;
+}): string[];
+/** Human-readable label for a status. */
+declare function getStatusLabel(status: string): string;
+/** UI colour key for a status. */
+declare function getStatusColor(status: string): string;
+/** Whether the order can be cancelled from its current status. */
+declare function canCancelOrder(currentStatus: string): boolean;
+/** Whether tracking info is required for a status change. */
+declare function requiresTrackingInfo(newStatus: string, options?: {
+    shippingMethod?: string | null;
+    shippingRateId?: string | null;
+}): boolean;
+/** Whether a status change should trigger customer notification. */
+declare function shouldNotifyCustomer(newStatus: string): boolean;
+/** Status progression percentage (for progress bars). */
+declare function getStatusProgress(status: string): 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 CashAccountBalanceResponse, 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 CustomerNotification, type CustomerNotificationsResponse, type CustomerSummary, type DeleteBrowsingLocationResponse, type DeliveryAddressResponse, 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 MarkNotificationsReadResponse, type MediaAsset, type MediaAssetResponse, type Merchant, MerchantBusinessType, MerchantEcommerceClient, type MerchantProductsResponse, type MerchantProfileRequest, type MerchantProfileResponse, MerchantReturnPolicyType, type MerchantShippingSettings, type MerchantSocialLinks, MerchantStatus, type Message, type MessageResponse, type MessageStatsResponse, ORDER_STATUS_TRANSITIONS, 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, canCancelOrder, formatPrice, getBackoffDelay, getNextStatuses, getStatusColor, getStatusLabel, getStatusProgress, isPickupOrder, isRetryableError, isValidAddress, isValidEmail, parseError, requiresTrackingInfo, retryWithBackoff, shouldNotifyCustomer, sleep, truncateAddress, validateStatusTransition };