@basedone/core 0.2.7 → 0.3.0

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) */
@@ -236,6 +238,36 @@ declare enum MerchantStatus {
     /** Merchant is pending approval */
     PENDING = "PENDING"
 }
+/**
+ * Merchant business type enum
+ */
+declare enum MerchantBusinessType {
+    /** Individual seller */
+    INDIVIDUAL = "INDIVIDUAL",
+    /** Registered company */
+    COMPANY = "COMPANY",
+    /** Partnership */
+    PARTNERSHIP = "PARTNERSHIP",
+    /** Non-profit organization */
+    NON_PROFIT = "NON_PROFIT"
+}
+/**
+ * Merchant return policy type enum
+ */
+declare enum MerchantReturnPolicyType {
+    /** No returns accepted */
+    NO_RETURNS = "NO_RETURNS",
+    /** Exchange for same/similar item only */
+    EXCHANGE_ONLY = "EXCHANGE_ONLY",
+    /** Refund as store credit only */
+    STORE_CREDIT = "STORE_CREDIT",
+    /** Full refund available */
+    FULL_REFUND = "FULL_REFUND",
+    /** Partial refund (restocking fee may apply) */
+    PARTIAL_REFUND = "PARTIAL_REFUND",
+    /** Handled on a case-by-case basis */
+    CASE_BY_CASE = "CASE_BY_CASE"
+}
 /**
  * Shipment status enum
  */
@@ -407,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) */
@@ -532,6 +566,21 @@ interface ProductVariant extends BaseEntity {
     /** Sort order */
     sortOrder: number;
 }
+/**
+ * Social links for merchant profile
+ */
+interface MerchantSocialLinks {
+    /** Twitter/X profile URL */
+    twitter?: string | null;
+    /** Instagram profile URL */
+    instagram?: string | null;
+    /** Facebook page URL */
+    facebook?: string | null;
+    /** Discord server invite URL */
+    discord?: string | null;
+    /** Telegram channel/group URL */
+    telegram?: string | null;
+}
 /**
  * Merchant entity
  */
@@ -546,6 +595,32 @@ interface Merchant extends BaseEntity {
     payoutAddress: string;
     /** Merchant status */
     status: MerchantStatus;
+    /** Contact email for notifications and customer inquiries */
+    email?: string | null;
+    /** Contact phone number */
+    phone?: string | null;
+    /** Store website URL */
+    website?: string | null;
+    /** Business type (individual, company, etc.) */
+    businessType?: MerchantBusinessType;
+    /** Store logo/avatar URL */
+    logoUrl?: string | null;
+    /** Store banner image URL */
+    bannerUrl?: string | null;
+    /** Social media links */
+    socialLinks?: MerchantSocialLinks | null;
+    /** Return policy type */
+    returnPolicyType?: MerchantReturnPolicyType;
+    /** Custom return policy details/text */
+    returnPolicyDetails?: string | null;
+    /** Return window in days (e.g., 30) */
+    returnWindowDays?: number | null;
+    /** ISO 2-letter country code (for tax/shipping) */
+    country?: string | null;
+    /** City name */
+    city?: string | null;
+    /** Street address */
+    addressLine1?: string | null;
 }
 /**
  * Shipping address
@@ -699,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
@@ -1424,6 +1513,8 @@ interface CreateOrderRequest {
 interface ListOrdersParams extends PaginationParams {
     /** Filter by status */
     status?: OrderStatus;
+    /** Filter by merchant ID (for godview access) */
+    merchantId?: string;
 }
 /**
  * Update order status request
@@ -2215,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 */
@@ -3134,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;
@@ -3940,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>;
 }
 
 /**
@@ -5654,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, 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 };
+/** 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.js

@@ -1230,6 +1230,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
@@ -2775,6 +2807,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;
@@ -2800,6 +2833,22 @@ var MerchantStatus = /* @__PURE__ */ ((MerchantStatus2) => {
   MerchantStatus2["PENDING"] = "PENDING";
   return MerchantStatus2;
 })(MerchantStatus || {});
+var MerchantBusinessType = /* @__PURE__ */ ((MerchantBusinessType2) => {
+  MerchantBusinessType2["INDIVIDUAL"] = "INDIVIDUAL";
+  MerchantBusinessType2["COMPANY"] = "COMPANY";
+  MerchantBusinessType2["PARTNERSHIP"] = "PARTNERSHIP";
+  MerchantBusinessType2["NON_PROFIT"] = "NON_PROFIT";
+  return MerchantBusinessType2;
+})(MerchantBusinessType || {});
+var MerchantReturnPolicyType = /* @__PURE__ */ ((MerchantReturnPolicyType2) => {
+  MerchantReturnPolicyType2["NO_RETURNS"] = "NO_RETURNS";
+  MerchantReturnPolicyType2["EXCHANGE_ONLY"] = "EXCHANGE_ONLY";
+  MerchantReturnPolicyType2["STORE_CREDIT"] = "STORE_CREDIT";
+  MerchantReturnPolicyType2["FULL_REFUND"] = "FULL_REFUND";
+  MerchantReturnPolicyType2["PARTIAL_REFUND"] = "PARTIAL_REFUND";
+  MerchantReturnPolicyType2["CASE_BY_CASE"] = "CASE_BY_CASE";
+  return MerchantReturnPolicyType2;
+})(MerchantReturnPolicyType || {});
 var ShipmentStatus = /* @__PURE__ */ ((ShipmentStatus2) => {
   ShipmentStatus2["PENDING"] = "PENDING";
   ShipmentStatus2["SHIPPED"] = "SHIPPED";
@@ -2892,6 +2941,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;
@@ -2903,6 +2953,120 @@ var ReviewSortBy = /* @__PURE__ */ ((ReviewSortBy2) => {
   return ReviewSortBy2;
 })(ReviewSortBy || {});
 
+// 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;
+}
+
 exports.BannerType = BannerType;
 exports.BaseEcommerceClient = BaseEcommerceClient;
 exports.CustomerEcommerceClient = CustomerEcommerceClient;
@@ -2911,8 +3075,11 @@ exports.DiscountScope = DiscountScope;
 exports.DiscountType = DiscountType;
 exports.EcommerceApiError = EcommerceApiError;
 exports.InventoryAuditAction = InventoryAuditAction;
+exports.MerchantBusinessType = MerchantBusinessType;
 exports.MerchantEcommerceClient = MerchantEcommerceClient;
+exports.MerchantReturnPolicyType = MerchantReturnPolicyType;
 exports.MerchantStatus = MerchantStatus;
+exports.ORDER_STATUS_TRANSITIONS = ORDER_STATUS_TRANSITIONS;
 exports.OrderStatus = OrderStatus;
 exports.PaymentMethod = PaymentMethod;
 exports.PaymentStatus = PaymentStatus;
@@ -2929,12 +3096,21 @@ exports.TaxType = TaxType;
 exports.buildQueryString = buildQueryString;
 exports.calculateDiscountAmount = calculateDiscountAmount;
 exports.calculateFinalPrice = calculateFinalPrice;
+exports.canCancelOrder = canCancelOrder;
 exports.formatPrice = formatPrice;
 exports.getBackoffDelay = getBackoffDelay;
+exports.getNextStatuses = getNextStatuses;
+exports.getStatusColor = getStatusColor;
+exports.getStatusLabel = getStatusLabel;
+exports.getStatusProgress = getStatusProgress;
+exports.isPickupOrder = isPickupOrder;
 exports.isRetryableError = isRetryableError;
 exports.isValidAddress = isValidAddress;
 exports.isValidEmail = isValidEmail;
 exports.parseError = parseError;
+exports.requiresTrackingInfo = requiresTrackingInfo;
 exports.retryWithBackoff = retryWithBackoff;
+exports.shouldNotifyCustomer = shouldNotifyCustomer;
 exports.sleep = sleep;
 exports.truncateAddress = truncateAddress;
+exports.validateStatusTransition = validateStatusTransition;

package/dist/ecommerce.mjs

@@ -1,2 +1 @@
-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-L63E7FZC.mjs';
-import './chunk-4UEJOM6W.mjs';
+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 } from './chunk-35WGIB5F.mjs';