@shoppexio/storefront 1.0.57 → 1.0.59

package/dist/index.d.ts

@@ -1,49 +1,1857 @@
-import { isInitialized, getConfig } from './core/config';
-import { getTypedClient } from './core/typed-client';
-import { ShoppexInitOptions } from './types';
-import { getStore, getStorefront, getStoreLogoUrl, getStoreBannerUrl, resolveStoreByDomain } from './modules/store';
-import { getProducts, getProduct, getCategories, getStorefrontProductsPage } from './modules/products';
-import { getCart, getCartItemCount, getCartCoupon, getCartCouponSource, setCartCoupon, clearCartCoupon, addToCart, setCartItem, updateCartItem, removeFromCart, clearCart, createCartBackup, restoreCartFromBackup, mergeBaskets, moveBasketItem, getCartStats, validateCartIntegrity, quoteCart, resolveCartLineId } from './modules/cart';
-import { checkout, buildCheckoutUrl, buildCheckoutUrlSync } from './modules/checkout';
-import { applyAffiliateCode, captureAffiliateFromUrl, getAffiliateCode, setAffiliateCode, clearAffiliateCode, validateAffiliateCode } from './modules/affiliates';
-import { validateCoupon } from './modules/coupons';
-import { getShopReviews, getShopReviewsPage } from './modules/reviews';
-import { requestOtp, verifyOtp, logout, me, dashboard, orders, order, loyalty, redeemLoyaltyPoints, warranties, claimWarranty, resetLicenseHwid, subscriptionBillingHistory, cancelSubscription, pauseSubscription, resumeSubscription, favorites, addFavorite, removeFavorite, affiliate, createTicket, ticket, replyToTicket, updateProfile, updateAvatar, removeAvatar, emailPreferences, updateEmailPreferences, sessions, revokeSession, revokeAllSessions, reseller, applyForReseller, enrollAsReseller, acceptResellerInvite, resellerCatalog, quoteResellerOrder, resellerOrders, resellerOrder, resellerWallet, resellerApiKeys } from './modules/customer';
-import { searchProducts, searchCatalogItems } from './modules/search';
-import { getInvoice, getInvoiceStatus } from './modules/invoices';
-import { getPages, getPage } from './modules/pages';
-import { getMenus, getMenu, getMenuBySlot, getMenuByTitle, getMenuSlotTitles } from './modules/navigation';
-import { trackPageView } from './modules/analytics';
-import { getStorefrontOnlineUsers, getStorefrontRecentSales, touchStorefrontPresence } from './modules/presence';
-import { createFormatter, formatPrice } from './utils/format';
-import { clearCache, invalidateCache, getCacheStats } from './core/cache';
-import { fetchPublishedBuilderSettings, fetchPublishedThemeSettings, resolveDefaults, mergeSettings } from './modules/theme';
-export * from './types';
-export * from './core/errors';
-export { buildStorefrontCustomFieldPayload, isStorefrontCheckboxCustomFieldValueChecked, normalizeStorefrontCustomFields, validateStorefrontCustomFieldValue, } from './utils/storefront-custom-fields';
-export type { StorefrontCustomField } from './utils/storefront-custom-fields';
-export { isProductInStock, isProductOutOfStock, isVariantOutOfStock, resolveDisplayStock, resolveVariantStockValue, } from './utils/storefront-stock';
-export { buildStorefrontProductLookup, getMergedStorefrontProducts, getStorefrontGroupProducts, } from './utils/storefront-catalog';
-export { stripHtmlFromText, normalizeSearchQuery, collectProductSearchHaystack, productMatchesSearchQuery, groupMatchesSearchQuery, filterProductsBySearchQuery, searchMergedStorefrontCatalog, searchMergedStorefrontCatalogItems, } from './utils/storefront-search';
-export type { StorefrontSearchFilterOptions, StorefrontCatalogSearchItem } from './utils/storefront-search';
-export { buildStorefrontContactMessage, resolveStorefrontApiBaseUrl, resolveStorefrontSocialLinks, submitStorefrontContactTicket, } from './utils/storefront-contact';
-export type { StorefrontContactTicketInput, StorefrontContactTicketResult, StorefrontSocialLinks, } from './utils/storefront-contact';
-export type { BlockDefinition, BlockInstance, PageLayout, ThemeConfig, ThemeBlockManifest, SettingField, SectionDefinition, ResolvedThemeSettings, } from './types/theme-config';
-export type { PublishedBuilderSettings, PublishedThemeSettingsPayload } from './modules/theme';
-export type { NavigationMenuSlot } from '@shoppex/contracts/navigation';
-export { CATALOG_UNIT_PRICE_DECIMAL_PLACES, CATALOG_UNIT_PRICE_FORMAT_OPTIONS, PAYABLE_AMOUNT_DECIMAL_PLACES, roundPayableAmount, } from '@shoppex/contracts/catalog-unit-price';
-export { computeCartLineId, ensureCartLineId } from './utils/cart-line-id';
-export type { CartLineIdentityInput } from './utils/cart-line-id';
-export type { CheckoutOptions, CheckoutResult } from './modules/checkout';
-export { CheckoutCreateError } from './modules/checkout';
-export type { SearchOptions } from './modules/search';
-export { getShopReviewsPage } from './modules/reviews';
-export { requestOtp, verifyOtp, logout, me, dashboard, orders, order, loyalty, redeemLoyaltyPoints, warranties, claimWarranty, resetLicenseHwid, subscriptionBillingHistory, cancelSubscription, pauseSubscription, resumeSubscription, favorites, addFavorite, removeFavorite, affiliate, createTicket, ticket, replyToTicket, updateProfile, updateAvatar, removeAvatar, emailPreferences, updateEmailPreferences, sessions, revokeSession, revokeAllSessions, reseller, applyForReseller, enrollAsReseller, acceptResellerInvite, resellerCatalog, quoteResellerOrder, resellerOrders, resellerOrder, resellerWallet, resellerApiKeys, } from './modules/customer';
-export type { CustomerTicketPayload, CustomerProfilePatch, CustomerSubscriptionCancelOptions, CustomerEmailPreferencesPatch, ResellerOrderItem, ResellerCatalogQuery, ResellerOrdersQuery, } from './modules/customer';
-export { fetchPublishedBuilderSettings, fetchPublishedThemeSettings, resolveDefaults, mergeSettings } from './modules/theme';
-export { trackPageView } from './modules/analytics';
-export { getStorefrontOnlineUsers, getStorefrontRecentSales, touchStorefrontPresence } from './modules/presence';
-export { getMenus, getMenu, getMenuBySlot, getMenuByTitle, getMenuSlotTitles } from './modules/navigation';
+import { createApiClient, CustomerWarrantyClaimWire, CustomerPortalDashboardWire, CustomerPortalPaginatedInvoicesWire, CustomerPortalInvoiceDetailWire, CustomerLoyaltyWire, CustomerLoyaltyRedeemWire, CustomerWarrantyListWire } from '@shoppex/contracts';
+import { NavigationMenuSlot } from '@shoppex/contracts/navigation';
+export { NavigationMenuSlot } from '@shoppex/contracts/navigation';
+import * as src from 'src';
+export { CATALOG_UNIT_PRICE_DECIMAL_PLACES, CATALOG_UNIT_PRICE_FORMAT_OPTIONS, PAYABLE_AMOUNT_DECIMAL_PLACES, roundPayableAmount } from '@shoppex/contracts/catalog-unit-price';
+
+/**
+ * SDK Configuration Types
+ */
+interface ShoppexConfig {
+    storeSlug: string;
+    locale?: string;
+    currency?: string;
+    apiBaseUrl?: string;
+    checkoutBaseUrl?: string;
+}
+interface ShoppexInitOptions {
+    locale?: string;
+    currency?: string;
+    apiBaseUrl?: string;
+    checkoutBaseUrl?: string;
+    shopId?: string;
+}
+
+/**
+ * API Response Types
+ *
+ * Backend returns: { status: number, data: T, error: string | null }
+ * SDK maps to: { success: boolean, data?: T, message?: string }
+ */
+interface ApiResponse<T> {
+    status: number;
+    data: T;
+    error: string | null;
+    message?: string | null;
+    /**
+     * Machine-readable refusal identifier (e.g. `errors.checkout.coupon_no_longer_valid`).
+     * Emitted by every localized backend error; the localized `error` sentence is
+     * for humans, this is what code branches on.
+     */
+    error_code?: string | null;
+    error_params?: Record<string, unknown> | null;
+}
+interface ApiChallenge {
+    provider: 'turnstile';
+    siteKey: string;
+}
+interface SDKResponse<T> {
+    success: boolean;
+    data?: T;
+    message?: string;
+    /**
+     * The backend's `error_code`, preserved verbatim on every failure the server
+     * answered — including non-2xx HTTP responses. `message` is localized display
+     * copy and must never be pattern-matched; branch on `code` instead.
+     * Absent when the failure never reached the server (transport, timeout) or
+     * when the endpoint emits no machine-readable code.
+     */
+    code?: string;
+    errorParams?: Record<string, unknown>;
+    /**
+     * HTTP status of the server's answer, when there was one.
+     *
+     * Needed to tell "not signed in" (401) apart from "the server broke" (5xx) or
+     * a transport failure, which are otherwise indistinguishable. Without it a
+     * client has to treat every failure as no-session and show a sign-in form to
+     * someone who is signed in — a silent downgrade of the very state it is
+     * trying to report.
+     *
+     * Absent when the request never reached the server.
+     */
+    status?: number;
+    /**
+     * Whether the request received an HTTP response from the server.
+     *
+     * `false` identifies an ambiguous transport failure: the browser cannot
+     * know whether a mutation committed before the connection was lost. Public
+     * mutation helpers use this signal to retain their idempotency key for the
+     * buyer's retry. Absent on successful responses and older SDK results.
+     */
+    responseReceived?: boolean;
+    /**
+     * True only when a parsed server refusal proves that the mutation did not
+     * commit (currently a JSON 4xx other than timeout). Mutation helpers may
+     * rotate an idempotency key on this signal. A response whose body is
+     * truncated, malformed, or a 5xx remains ambiguous even though headers were
+     * received.
+     */
+    responseDefinitive?: boolean;
+    /** A renewable human-verification challenge returned with a refusal. */
+    challenge?: ApiChallenge;
+}
+interface Shop {
+    id: string;
+    name: string;
+    slug: string;
+    domain?: string;
+    description?: string;
+    title?: string;
+    message?: string;
+    url?: string;
+    logo?: string;
+    banner?: string;
+    avatar?: string;
+    average_score?: number | null;
+    rating?: number | null;
+    products_sold_count?: number;
+    customers_count?: number;
+    hide_products_sold?: boolean;
+    currency: string;
+    tos_enabled?: boolean;
+    dark_mode?: boolean;
+    search_enabled?: boolean;
+    sort_enabled?: boolean;
+    cart_enabled?: boolean;
+    contact_form_enabled?: boolean;
+    require_invoice_for_contact?: boolean;
+    hide_out_of_stock?: boolean;
+    hide_stock_counter?: boolean;
+    center_product_titles?: boolean;
+    center_group_titles?: boolean;
+    default_sort?: string;
+    social?: Record<string, string | null>;
+    discord_link?: string | null;
+    twitter_link?: string | null;
+    instagram_link?: string | null;
+    facebook_link?: string | null;
+    telegram_link?: string | null;
+    youtube_link?: string | null;
+    reddit_link?: string | null;
+    tiktok_link?: string | null;
+    verified?: boolean;
+    on_hold?: boolean;
+    theme?: ShopTheme | null;
+    builder_settings?: Record<string, unknown> | null;
+    feedback?: ShopFeedback;
+    trusted_checks?: TrustedChecks | null;
+    available_gateways?: string[];
+    payment_gateways_fees?: unknown[];
+    reward_program_summary?: RewardProgramSummary | null;
+}
+interface RewardProgramTeaserItem {
+    trigger_type: RewardReason;
+    action_type: RewardActionType;
+    label: string;
+}
+interface RewardProgramSummary {
+    enabled: boolean;
+    headline: string;
+    items: RewardProgramTeaserItem[];
+}
+interface ShopTheme {
+    primary_color?: string;
+    secondary_color?: string;
+    font?: string;
+    logo?: string | null;
+    logo_cloudflare_image_id?: string | null;
+    background_image?: string | null;
+    background_image_cloudflare_image_id?: string | null;
+    cards_in_row?: number | string;
+    cards_align?: string;
+    card_animation?: string;
+    dark_color?: string;
+    light_color?: string;
+    border_color?: string;
+    button_color?: string;
+}
+interface ShopFeedback {
+    positive: number;
+    neutral: number;
+    negative: number;
+    total: number;
+}
+interface TrustedChecks {
+    identity_verified?: boolean;
+    feedback_score?: string | null;
+    trusted_score?: number;
+    sales_last14days_metric?: string;
+}
+interface ProductCategory {
+    uniqid: string;
+    title: string;
+    description?: string | null;
+    image_attachment?: string | null;
+    image_name?: string | null;
+    image_storage?: string | null;
+    cloudflare_image_id?: string | null;
+    cdn_image_url?: string | null;
+}
+interface ProductDescriptionTab {
+    title: string;
+    content: string;
+}
+interface Product {
+    id?: string;
+    uniqid: string;
+    title: string;
+    slug?: string | null;
+    description?: string | null;
+    /** Merchant-defined description tabs; present when the shop configured them. */
+    description_tabs?: ProductDescriptionTab[];
+    product_highlights?: string[];
+    /**
+     * Merchant-defined public key/value pairs, set in the dashboard and readable
+     * here without a theme rebuild. Always present on storefront catalog reads —
+     * `{}` when the merchant set nothing — and values are always strings.
+     *
+     * Optional on this type because the older bound/legacy product payloads do not
+     * carry it; read it as `product.metadata?.status` on those paths.
+     */
+    metadata?: Record<string, string>;
+    price: string;
+    price_display?: string;
+    price_discount?: number;
+    currency: string;
+    /**
+     * RAW local stock only. `-1` (or any negative value) means unlimited, `0` means
+     * no local units. This is NEVER on its own a purchasable cap: a supplier-backed
+     * product reports `stock: 0` by design and is still buyable. Gate buying on
+     * {@link Product.orderable}, and use `resolveDisplayStock` / `isProductInStock`
+     * rather than reading this field directly.
+     */
+    stock?: number;
+    /**
+     * Per-product override for the shop's stock-counter setting; `null` inherits.
+     * Consumers must resolve it against the shop default rather than reading it
+     * alone.
+     *
+     * Both spellings are declared because both are really sent: the storefront
+     * catalog (`getStorefront`) emits camelCase alongside its other product
+     * fields, while `getProducts`, `getProduct` and `getStorefrontProductsPage`
+     * go through transformStorefrontCatalogProduct, which emits snake_case, and
+     * nothing normalizes between them. Declaring only one would have left readers
+     * of the other silently seeing `undefined` and falling back to the shop
+     * setting — showing a count the merchant hid, or hiding one they wanted shown.
+     */
+    hideStockCounter?: boolean | null;
+    hide_stock_counter?: boolean | null;
+    /**
+     * Authoritative buyability predicate, mirrored from the backend's order-time
+     * gate: `local stock covers one unit OR an eligible supplier source can fulfil
+     * the line`. This — not `stock` — is what a storefront must gate the buy button,
+     * the quantity cap and the sold-out badge on.
+     *
+     * Absent on payloads that predate Dynamic Delivery. When absent, treat
+     * availability exactly as `stock` alone dictates; a missing field must never
+     * turn a genuinely sold-out product into a buyable one.
+     */
+    orderable?: boolean;
+    /**
+     * True when an enabled supplier source fulfils this product instead of local
+     * stock. `orderable` remains the buy/sold-out gate; this field decides the
+     * QUANTITY CAP: the supplier purchase — not the local counter — fulfils the line
+     * and the completion excludes it from the local decrement, so residual local
+     * units bound nothing and the cap is unlimited even at `stock: 1`. Absent on
+     * payloads that predate Dynamic Delivery; when absent, the cap stays exactly
+     * what `stock` alone dictates.
+     */
+    supplier_backed?: boolean;
+    quantity_min?: number;
+    quantity_max?: number;
+    min_quantity?: number;
+    max_quantity?: number;
+    on_hold?: boolean | number;
+    unlisted?: boolean | number;
+    private?: boolean | number;
+    bestseller?: boolean | number;
+    type?: string;
+    subtype?: string | null;
+    isSubscription?: boolean;
+    isGroup?: boolean;
+    images: ProductImage[];
+    image_name?: string | null;
+    image_storage?: string | null;
+    cloudflare_image_id?: string | null;
+    image_attachment?: string | null;
+    sold_count?: number;
+    soldCount?: number;
+    variants?: ProductVariant[];
+    addons?: ProductAddon[];
+    price_variants?: PriceVariant[];
+    volume_discounts?: unknown;
+    custom_fields?: string | unknown[] | null;
+    categories?: ProductCategory[];
+    bundles?: ProductBundle[];
+    faqs?: ProductFaq[];
+    subscription?: Subscription;
+    feedbacks?: Feedback[];
+    feedback?: ProductFeedback;
+    cdn_image_url?: string;
+    detail_image_url?: string | null;
+    recurring_interval?: string | null;
+    recurring_interval_count?: number | null;
+    trial_period?: number | null;
+    setup_cost?: string;
+    licensing_enabled?: boolean | number;
+    license_period?: string | number | null;
+    delivery_text?: string;
+    service_text?: string;
+    terms_of_service?: string | null;
+    warranty?: number;
+    warranty_text?: string | null;
+    sort_priority?: number;
+    pay_what_you_want?: boolean | number;
+    video_link?: string | null;
+}
+interface ProductFeedback {
+    total: number;
+    positive: number;
+    neutral: number;
+    negative: number;
+    numbers?: Record<number, number>;
+    list?: Array<{
+        score: number;
+        message: string | null;
+        reply: string | null;
+        created_at: string | null;
+        createdAt?: string | null;
+        updated_at: string | null;
+        updatedAt?: string | null;
+        is_automated?: boolean;
+        isAutomated?: boolean;
+    }>;
+}
+interface ProductImage {
+    id: string;
+    url: string;
+    cloudflare_image_id?: string;
+    alt?: string;
+}
+interface ProductVariant {
+    id: string;
+    title: string;
+    price?: number;
+    /**
+     * RAW local stock for this option only. `-1` (or any negative value) means
+     * unlimited, `0` means no local units — which a supplier-backed option reports
+     * by design. Never render this as a purchasable cap on its own; gate on
+     * {@link ProductVariant.orderable}.
+     */
+    stock?: number;
+    /**
+     * Authoritative buyability predicate for this option: `local stock covers one
+     * unit OR an eligible supplier source can fulfil the line`. The backend resolves
+     * a product-wide supplier mapping onto every variant's own flag, so this alone
+     * is authoritative for a selected variant.
+     *
+     * Absent on payloads that predate Dynamic Delivery; when absent, availability
+     * follows `stock` alone, exactly as before.
+     */
+    orderable?: boolean;
+    /**
+     * True when an enabled supplier source fulfils this option instead of local
+     * stock. `orderable` remains the buy/sold-out gate; this field decides the
+     * QUANTITY CAP — a supplier-backed row is unbounded even when it still holds a
+     * few local units, because the supplier purchase fulfils the line and the
+     * completion excludes it from the local decrement. Absent on payloads that
+     * predate Dynamic Delivery.
+     */
+    supplier_backed?: boolean;
+    quantity_min?: number;
+    quantity_max?: number;
+    quantityMin?: number;
+    quantityMax?: number;
+    image_id?: string | null;
+    imageId?: string | null;
+    cloudflare_image_id?: string | null;
+    cloudflareImageId?: string | null;
+    image_url?: string | null;
+    imageUrl?: string | null;
+    /** Merchant-selected storefront highlight. It does not affect selection or availability. */
+    is_featured?: boolean;
+    isFeatured?: boolean;
+    /** License validity in days for this option. Zero means lifetime. */
+    license_period?: number | null;
+}
+interface ProductAddon {
+    id: string;
+    name?: string;
+    title?: string;
+    price: number;
+    required?: boolean;
+}
+interface PriceVariant {
+    id: string;
+    label?: string;
+    title?: string;
+    price: number;
+    /**
+     * RAW local stock for this price variant only. `-1` (or any negative value)
+     * means unlimited, `0` means no local units — which a supplier-backed variant
+     * reports by design. Never render this as a purchasable cap on its own; gate on
+     * {@link PriceVariant.orderable}.
+     */
+    stock?: number;
+    /**
+     * Authoritative buyability predicate for this price variant: `local stock covers
+     * one unit OR an eligible supplier source can fulfil the line`. The backend
+     * resolves a product-wide supplier mapping onto every variant's own flag, so
+     * this alone is authoritative for a selected variant.
+     *
+     * Absent on payloads that predate Dynamic Delivery; when absent, availability
+     * follows `stock` alone, exactly as before.
+     */
+    orderable?: boolean;
+    /**
+     * True when an enabled supplier source fulfils this price variant instead of
+     * local stock. `orderable` remains the buy/sold-out gate; this field decides the
+     * QUANTITY CAP — a supplier-backed row is unbounded even when it still holds a
+     * few local units, because the supplier purchase fulfils the line and the
+     * completion excludes it from the local decrement. Absent on payloads that
+     * predate Dynamic Delivery.
+     */
+    supplier_backed?: boolean;
+    quantity_min?: number;
+    quantity_max?: number;
+    quantityMin?: number;
+    quantityMax?: number;
+    image_id?: string | null;
+    imageId?: string | null;
+    cloudflare_image_id?: string | null;
+    cloudflareImageId?: string | null;
+    image_url?: string | null;
+    imageUrl?: string | null;
+    /** Merchant-selected storefront highlight. It does not affect selection or availability. */
+    is_featured?: boolean;
+    isFeatured?: boolean;
+    /** License validity in days for this option. Zero means lifetime. */
+    license_period?: number | null;
+}
+interface CustomFieldDefinition {
+    id: string;
+    name: string;
+    type: 'text' | 'textarea' | 'select' | 'checkbox';
+    required?: boolean;
+    options?: string[];
+}
+interface Feedback {
+    id: string;
+    rating: number;
+    score?: number;
+    author?: string;
+    customer_name?: string;
+    comment?: string;
+    message?: string | null;
+    reply?: string | null;
+    is_automated?: boolean;
+    isAutomated?: boolean;
+    product_id?: string | null;
+    product_title?: string | null;
+    cloudflare_image_id?: string | null;
+    created_at: string;
+    updated_at?: string | number | null;
+}
+interface ShopReviewsSummary {
+    total: number;
+    positive: number;
+    neutral: number;
+    negative: number;
+    average_score: number | null;
+}
+interface ShopReviewsPage {
+    feedback: Feedback[];
+    pagination: CursorPagination;
+    summary: ShopReviewsSummary;
+}
+interface ProductBundle {
+    id?: string;
+    uniqid?: string;
+    title?: string;
+    discount_type?: 'PERCENTAGE' | 'FIXED';
+    discount_amount?: number;
+    products?: ProductBundleProduct[];
+}
+interface ProductBundleProduct {
+    id?: string;
+    uniqid: string;
+    title?: string | null;
+    default_variant_id?: string;
+}
+interface ProductFaq {
+    id?: string;
+    uniqid?: string;
+    question: string;
+    answer: string;
+}
+interface SubscriptionInterval {
+    unit?: string;
+    count?: number;
+    label?: string;
+}
+interface SubscriptionFlags {
+    cancel_anytime?: boolean;
+}
+interface Subscription {
+    id?: string;
+    name?: string;
+    description?: string;
+    badge?: string;
+    interval?: SubscriptionInterval;
+    flags?: SubscriptionFlags;
+}
+interface Invoice {
+    uniqid: string;
+    status: string;
+    total: number;
+    currency: string;
+    gateway?: string;
+    products: InvoiceProduct[];
+    created_at: string;
+    rewards?: BuyerRewards | null;
+}
+interface InvoiceProduct {
+    product_id: string;
+    title: string;
+    quantity: number;
+    price: number;
+}
+type RewardActionType = 'WALLET_CREDIT' | 'COUPON';
+type RewardGrantStatus = 'PENDING' | 'FULFILLED' | 'FAILED' | 'REVOKED';
+type RewardReason = 'ORDER_COMPLETED' | 'ORDER_COUNT_REACHED' | 'SPEND_AMOUNT_REACHED' | 'POSITIVE_REVIEW_LEFT' | 'FIRST_PURCHASE_COMPLETED';
+interface BuyerRewardActivityItem {
+    id: string;
+    type: RewardActionType;
+    status: RewardGrantStatus;
+    amount: string | null;
+    currency: string | null;
+    coupon_code: string | null;
+    reason: RewardReason;
+    trigger_reference_type: string;
+    trigger_reference_id: string;
+    created_at: number;
+    fulfilled_at: number | null;
+    expires_at: number | null;
+}
+interface BuyerRewards {
+    summary: {
+        available: string;
+        pending: string;
+        lifetime_earned: string;
+        redeemed: string | null;
+        currency: string;
+    };
+    activity: BuyerRewardActivityItem[];
+    earned_after_invoice: BuyerRewardActivityItem[];
+    pending_after_invoice: BuyerRewardActivityItem[];
+}
+interface CouponValidation {
+    valid: boolean;
+    discount?: number;
+    discount_type?: 'percentage' | 'fixed';
+    first_order_only?: boolean;
+    source?: 'COUPON' | 'AFFILIATE';
+    product_restricted?: boolean;
+    variant_restricted?: boolean;
+    restriction_scope?: 'all' | 'products' | 'variants' | 'products_and_variants';
+    allowed_product_ids?: string[];
+    allowed_variant_ids?: string[];
+    message?: string;
+}
+interface CouponValidationOptions {
+    productId?: string;
+    variantId?: string;
+}
+interface AffiliateValidation {
+    valid: boolean;
+    program_enabled?: boolean;
+    affiliate_code: string | null;
+    discount_active: boolean;
+    discount_percent: number;
+    message?: string;
+}
+interface ProductGroup {
+    id?: string;
+    uniqid: string;
+    category_id?: string | null;
+    slug?: string | null;
+    name?: string | null;
+    title: string;
+    description?: string | null;
+    product_uniqids?: string[];
+    products_count?: number;
+    image_attachment?: string | null;
+    image_name?: string | null;
+    image_storage?: string | null;
+    cloudflare_image_id?: string | null;
+    cdn_image_url?: string | null;
+    sort_priority?: number | null;
+}
+interface Category {
+    uniqid: string;
+    title: string;
+    description?: string | null;
+    image_attachment?: string | null;
+    image_name?: string | null;
+    image_storage?: string | null;
+    cloudflare_image_id?: string | null;
+    cdn_image_url?: string | null;
+    product_uniqids?: string[];
+    products_bound?: Product[];
+    products_count?: number;
+    groups_bound?: ProductGroup[];
+    groups_count?: number;
+}
+interface CursorPagination {
+    next_cursor: string | null;
+    has_more: boolean;
+}
+interface StorefrontAnnouncementBarAddon {
+    id: string;
+    type: 'announcement_bar';
+    slot: string;
+    component: 'announcement_bar';
+    sort_order: number;
+    props: {
+        addon_id: string;
+        text: string;
+        link_label?: string | null;
+        link_url?: string | null;
+        dismissible: boolean;
+        display_mode: 'static' | 'marquee';
+        theme_preset: 'brand_blue' | 'emerald' | 'sunset' | 'rose' | 'charcoal' | 'custom';
+        animation_speed_seconds: number;
+        background_color: string;
+        text_color: string;
+    };
+}
+interface StorefrontCountdownBarAddon {
+    id: string;
+    type: 'countdown_bar';
+    slot: string;
+    component: 'countdown_bar';
+    sort_order: number;
+    props: {
+        addon_id: string;
+        text: string;
+        end_at: string;
+        link_label?: string | null;
+        link_url?: string | null;
+        dismissible: boolean;
+        theme_preset: 'brand_blue' | 'emerald' | 'sunset' | 'rose' | 'charcoal' | 'custom';
+        expired_behavior: 'hide' | 'message';
+        expired_message?: string | null;
+        density: 'compact' | 'comfortable';
+        cta_style: 'subtle' | 'outline' | 'solid';
+        timer_style: 'minimal' | 'boxed';
+        background_color: string;
+        text_color: string;
+    };
+}
+interface StorefrontPromoInfoCardAddon {
+    id: string;
+    type: 'promo_info_card';
+    slot: string;
+    component: 'promo_info_card';
+    sort_order: number;
+    props: {
+        addon_id: string;
+        eyebrow?: string | null;
+        title: string;
+        body: string;
+        link_label?: string | null;
+        link_url?: string | null;
+        theme_preset: 'indigo' | 'emerald' | 'amber' | 'rose' | 'slate' | 'custom';
+        layout_style: 'compact' | 'feature' | 'alert';
+        density: 'compact' | 'comfortable';
+        cta_style: 'subtle' | 'outline' | 'solid';
+        icon: 'sparkles' | 'megaphone' | 'gift' | 'truck' | 'shield' | 'support' | 'none';
+        icon_visibility: 'show' | 'hide';
+        background_color: string;
+        text_color: string;
+        accent_color: string;
+    };
+}
+interface StorefrontRecentPurchasePopupAddon {
+    id: string;
+    type: 'recent_purchase_popup';
+    slot: string;
+    component: 'recent_purchase_popup';
+    sort_order: number;
+    props: {
+        addon_id: string;
+        title: string;
+        cooldown_seconds: number;
+        items: Array<{
+            customer_label: string;
+            product_title: string;
+            created_at: string;
+        }>;
+    };
+}
+interface StorefrontCouponPopupModalAddon {
+    id: string;
+    type: 'coupon_popup_modal';
+    slot: string;
+    component: 'coupon_popup_modal';
+    sort_order: number;
+    props: {
+        addon_id: string;
+        eyebrow?: string | null;
+        title: string;
+        body: string;
+        coupon_code: string;
+        primary_button_label: string;
+        secondary_button_label: string;
+        disclaimer?: string | null;
+        theme_preset: 'midnight' | 'ocean' | 'ember' | 'forest' | 'custom';
+        trigger: 'delay' | 'exit_intent';
+        delay_seconds: number;
+        show_once_per_session: boolean;
+        reminder_hours: number;
+        background_color: string;
+        text_color: string;
+        accent_color: string;
+        hero_image_url?: string | null;
+        discount_display?: string | null;
+        expires_at?: string | null;
+    };
+}
+type StorefrontAddon = StorefrontAnnouncementBarAddon | StorefrontCountdownBarAddon | StorefrontPromoInfoCardAddon | StorefrontRecentPurchasePopupAddon | StorefrontCouponPopupModalAddon;
+interface StorefrontAddonBootstrap {
+    items: StorefrontAddon[];
+}
+interface StorefrontOnlineUsers {
+    count: number;
+    window_seconds: number;
+}
+interface StorefrontRecentSaleEntry {
+    product_title: string;
+    seconds_ago: number;
+}
+interface StorefrontRecentSales {
+    items: StorefrontRecentSaleEntry[];
+    window_hours: number;
+}
+type StorefrontItem = {
+    item_type: 'PRODUCT' | 'GROUP';
+    uniqid: string;
+    sort_priority?: number | null;
+    title?: string | null;
+};
+interface StorefrontData {
+    shop: Shop;
+    products: Product[];
+    products_pagination?: CursorPagination | null;
+    groups: ProductGroup[];
+    items: StorefrontItem[];
+    categories: Category[];
+    addons: StorefrontAddonBootstrap;
+}
+interface Page {
+    id: string;
+    shop_id?: string;
+    slug: string;
+    name: string;
+    content: string | null;
+    template_type: string;
+    is_system: boolean;
+    settings: Record<string, unknown> | null;
+    visible_after: string | null;
+    created_at: number;
+    updated_at: number;
+}
+interface Menu {
+    id: string;
+    shop_id: string;
+    title: string;
+    slot?: NavigationMenuSlot | null;
+    item_count?: number | null;
+    items?: MenuItem[];
+    created_at: number;
+    updated_at: number;
+}
+interface MenuItem {
+    id: string;
+    shop_id?: string;
+    menu_id: string;
+    page_id: string | null;
+    title: string;
+    url?: string | null;
+    link_type?: 'LINK' | 'PAGE' | 'link' | 'page' | null;
+    target?: '_self' | '_blank' | null;
+    sort_order: number;
+    page_slug: string | null;
+    created_at: number;
+    updated_at: number;
+    children?: MenuItem[];
+}
+
+/**
+ * Cart Types
+ *
+ * Extended cart schema supporting Shoppex features:
+ * - Addons (express shipping, gift wrap, etc.)
+ * - Custom Fields (engraving, gift message, etc.)
+ * - Price Variants (different pricing tiers)
+ *
+ * All fields use snake_case to match API conventions.
+ */
+interface CartAddon {
+    id: string;
+    quantity?: number;
+}
+/** Incoming basket rows may omit line_id; mergeBaskets derives it before deduping. */
+type CartBasketMergeLine = Omit<CartItem, 'line_id'> & {
+    line_id?: string;
+};
+interface CartItem {
+    /** Stable identity for this configuration (product + variant + addons + custom_fields + price snapshot). */
+    line_id: string;
+    product_id: string;
+    variant_id: string;
+    quantity: number;
+    addons?: CartAddon[];
+    custom_fields?: Record<string, string>;
+    price_variant_id?: string;
+    price_data?: {
+        unit_price: number;
+    };
+    /** Buyer-selected unit price for a product explicitly configured as pay-what-you-want. */
+    pay_what_you_want_price?: number;
+    title?: string;
+    variant_title?: string;
+    image_url?: string;
+    addon_labels?: string[];
+    max_quantity?: number;
+    min_quantity?: number;
+}
+/**
+ * The patch `updateCartItem` accepts, with an explicit TRI-STATE for the two
+ * bounds — the same shape `checkout()`'s `affiliateCode` uses for "none":
+ *
+ *   key absent  leave the stored bound exactly as it is;
+ *   `null`      DELETE the stored bound (the merchant removed it);
+ *   `number`    set it.
+ *
+ * Without the `null` arm a bound could be raised and lowered forever but never
+ * REMOVED: an update carrying `undefined` is indistinguishable from one that
+ * never mentioned the field, so a `max_quantity: 5` the merchant deleted stuck
+ * to the line for the life of the cart, and every quote-driven heal that tried
+ * to clear it was a silent no-op.
+ */
+type CartItemUpdate = Partial<Omit<CartItem, 'line_id' | 'product_id' | 'variant_id' | 'min_quantity' | 'max_quantity'>> & {
+    /** `null` clears the stored minimum. */
+    min_quantity?: number | null;
+    /** `null` clears the stored ceiling. */
+    max_quantity?: number | null;
+};
+interface CartAddOptions {
+    addons?: CartAddon[];
+    custom_fields?: Record<string, string>;
+    price_variant_id?: string;
+    price_data?: {
+        unit_price: number;
+    };
+    pay_what_you_want_price?: number;
+    title?: string;
+    variant_title?: string;
+    image_url?: string;
+    addon_labels?: string[];
+    max_quantity?: number;
+    min_quantity?: number;
+    replace_display_snapshot?: boolean;
+}
+interface CartPayload {
+    store_slug: string;
+    items: CartItem[];
+    coupon?: string;
+}
+type CartCodeSource = 'COUPON' | 'AFFILIATE';
+interface CartAppliedDiscount {
+    source: 'PRODUCT_DISCOUNT' | 'VOLUME_DISCOUNT' | 'AUTOMATIC_PRODUCT_DEAL' | 'BUNDLE_DEAL' | 'STORE_PROMOTION' | 'COUPON' | 'AFFILIATE';
+    source_id: string | null;
+    source_uniqid: string | null;
+    label: string;
+    amount: string;
+}
+interface EligibleCartDeal {
+    source?: 'AUTOMATIC_PRODUCT_DEAL';
+    deal_id: string;
+    deal_uniqid: string;
+    product_id: string;
+    product_uniqid: string | null;
+    label: string;
+    missing_quantity: number;
+    required_quantity: number;
+}
+interface EligibleBundleDealProduct {
+    product_id: string;
+    product_uniqid: string;
+    title: string;
+    /** Units to add for this member — its own configured MINIMUM, never a blind 1. */
+    quantity: number;
+    price: string;
+    currency: string;
+    /**
+     * The option this member is sellable on. A deal is only offered when every member has one, so
+     * this is never the "first variant, whatever its stock" it used to be.
+     */
+    default_variant_id: string;
+    /**
+     * The member's order bounds on that option — the merchant's configured range narrowed by what
+     * is actually on the shelf. `max_quantity: -1` means nothing bounds the line.
+     *
+     * OPTIONAL because a server older than this field simply does not send them, and a client
+     * cannot invent them: an add against such a payload sends no bounds, exactly as it did before.
+     * That is a version gap, not a fallback — the gating that makes the offer safe happens on the
+     * server, and a client that guessed bounds here would be inventing the merchant's limits.
+     */
+    min_quantity?: number;
+    max_quantity?: number;
+}
+interface EligibleBundleDeal {
+    source: 'BUNDLE_DEAL';
+    bundle_id: string;
+    bundle_uniqid: string;
+    label: string;
+    discount_type: 'PERCENTAGE' | 'FIXED';
+    discount_amount: string;
+    missing_products: EligibleBundleDealProduct[];
+    products: EligibleBundleDealProduct[];
+}
+/**
+ * THE CART BOUNDS CONTRACT — one quoted line's effective order bounds and sellability.
+ *
+ * Cart lines carry bounds that were snapshotted when the item was ADDED, so they go stale the
+ * moment stock moves or the merchant edits the limits — and a line added before bounds existed
+ * carries none at all. The quote is the only thing that runs server-side on every cart change, so
+ * it restates them: each settled quote reports the bounds derived from the CURRENT product row and
+ * the CURRENT shelf, through the same resolution the checkout refuses with.
+ *
+ * FIELD CONTRACT:
+ *   `product_id`   the product identifier the cart sent, echoed exactly.
+ *   `variant_id`   the resolved option id, `null` for a product with no variants.
+ *   `quantity`     the quantity this line was quoted at.
+ *   `min_quantity` ABSENT when it is 1. Present values are the stepper's floor.
+ *   `max_quantity` ABSENT when nothing bounds the line — absence is the unbounded sentinel, and
+ *                  `-1` is never sent. Never coerce an absent key to 0.
+ *                  SHARED across duplicate lines: cart lines naming the same product and option
+ *                  draw from ONE shelf, and the invoice endpoint sums them and refuses the TOTAL.
+ *                  The value is therefore this line's SHARE — the option's ceiling minus what its
+ *                  sibling lines request. One line per option (the ordinary cart) sees the option
+ *                  ceiling unchanged, and duplicate lines with equal quantities always carry equal
+ *                  bounds. When the siblings have taken the whole ceiling that share is 0 or less,
+ *                  which no per-line bound can express (1 would license a unit that does not exist,
+ *                  0 is not a quantity a line can hold, absence means unbounded): the line then
+ *                  carries the OPTION'S CEILING — the number the option as a whole must come down
+ *                  to — together with `sellable: false`.
+ *   `sellable`     FALSE when this line cannot be ordered as the cart stands — either no quantity
+ *                  of the option can be ordered at all (empty effective range, empty shelf, nothing
+ *                  to fulfil it), or the cart's lines of this option together request more units
+ *                  than the option's ceiling, which the invoice endpoint refuses on the SUM. The
+ *                  line is still priced and still counted in the totals: it is a line the buyer
+ *                  must resolve by reducing or removing, not one that vanishes. It answers for the
+ *                  OPTION and for the whole cart's demand on it, so every line of one option always
+ *                  reports the same value.
+ *
+ * CONSUMER DUTY: on every settled quote, REPLACE the stored line bounds with these (do not merge —
+ * an absent `max_quantity` means the ceiling was removed), disable `+` at `max_quantity`, hold `-`
+ * at `min_quantity`, show a sold-out state for `sellable: false`, and REFUSE THE HAND-OFF while any
+ * line is `sellable: false` — that cart is the one the invoice endpoint rejects.
+ *
+ * OPTIONAL on `CartQuote` because a server older than this field does not send it. A client that
+ * receives no `lines` keeps whatever bounds it already had — it must not invent them.
+ */
+interface CartQuoteLine {
+    product_id: string;
+    variant_id: string | null;
+    quantity: number;
+    /** Absent when 1. */
+    min_quantity?: number;
+    /** Absent when unbounded. Never `-1`. */
+    max_quantity?: number;
+    sellable: boolean;
+}
+interface CartQuote {
+    subtotal: string;
+    discount: string;
+    total: string;
+    currency: string;
+    /**
+     * Opaque server-signed proof of this quote, valid ~15 minutes. `checkout()`
+     * submits the most recent one automatically, which is what stops the invoice
+     * from being priced above the total shown here. Null when the server has no
+     * signing secret configured; absent on older backends.
+     */
+    quote_token?: string | null;
+    coupon_applied: boolean;
+    coupon_source: CartCodeSource | null;
+    coupon_discount_order_type: 'TOTAL' | 'PAYMENT_FEES' | null;
+    /** Referral code priced into this quote (ambient `?ref=` or a typed referral code). */
+    affiliate_code: string | null;
+    applied_discounts: CartAppliedDiscount[];
+    automatic_product_deals: Array<Record<string, unknown>>;
+    bundle_deals: Array<Record<string, unknown>>;
+    eligible_deals: EligibleCartDeal[];
+    eligible_bundle_deals: EligibleBundleDeal[];
+    /** Per-line effective bounds and sellability — see CartQuoteLine. Absent on older backends. */
+    lines?: CartQuoteLine[];
+    /**
+     * TRUE when this cart already exceeds the shop's configured checkout maximum.
+     *
+     * Advisory: warn the buyer in the drawer instead of letting them hit the checkout button and
+     * take an unexplained rejection. The server refuses authoritatively at checkout regardless, and
+     * the flag is conservative — it excludes payment fees, so a cart without it can still be
+     * refused. Absent when the cart is within the limit.
+     */
+    cart_max_exceeded?: true;
+    /** The configured maximum in the quote's currency. Present only alongside `cart_max_exceeded`. */
+    cart_maximum_checkout?: string;
+}
+interface CartMetadata {
+    created_at: number;
+    last_modified: number;
+    version: number;
+    checksum: string;
+}
+interface CartStats {
+    item_count: number;
+    total_quantity: number;
+    last_modified: number;
+    version: number;
+    has_backup: boolean;
+    integrity_valid: boolean;
+    total_price: number;
+    total_price_is_estimate: boolean;
+}
+
+/**
+ * SDK Configuration Management
+ */
+
+declare function getConfig(): ShoppexConfig;
+declare function isInitialized(): boolean;
+
+/**
+ * Typed OpenAPI client factory.
+ *
+ * Surfaces the generated `createApiClient` from `@shoppex/contracts` with the
+ * SDK's configured `apiBaseUrl`. This lets consumers of `@shoppexio/storefront`
+ * call any public Dev API endpoint with full end-to-end types without
+ * rebuilding a client from scratch.
+ *
+ * Prefer the high-level modules (`shoppex.getProducts()` etc.) for common
+ * read flows — they handle caching, pagination defaults, and storefront
+ * scoping. Drop down to `shoppex.client()` only when you need an endpoint
+ * the high-level API does not cover yet.
+ */
+
+type ApiClient = ReturnType<typeof createApiClient>;
+/**
+ * Return a typed OpenAPI client bound to the SDK's configured API base URL.
+ * The client is cached per base URL and recreated when the SDK is re-initialized
+ * against a different host.
+ */
+declare function getTypedClient(token?: string): ApiClient;
+
+/**
+ * SDK Error Classes
+ */
+declare class ShoppexError extends Error {
+    readonly code: string;
+    readonly statusCode?: number;
+    constructor(message: string, code: string, statusCode?: number);
+}
+declare class NotInitializedError extends ShoppexError {
+    constructor();
+}
+declare class NetworkError extends ShoppexError {
+    constructor(message: string, statusCode?: number);
+}
+/**
+ * A refusal the SERVER made and named. `code` is the backend's `error_code`
+ * (e.g. `errors.checkout.coupon_no_longer_valid`) — the branchable identity of
+ * the refusal, stable across locales, unlike the localized `message`.
+ *
+ * Distinct from {@link NetworkError}, whose `code` is always `NETWORK_ERROR`:
+ * that one means "the request did not produce a named answer".
+ */
+declare class ApiError extends ShoppexError {
+    readonly errorParams?: Record<string, unknown>;
+    constructor(message: string, code: string, statusCode?: number, errorParams?: Record<string, unknown>);
+}
+declare class ValidationError extends ShoppexError {
+    readonly invalidFields?: string[];
+    constructor(message: string, invalidFields?: string[]);
+}
+declare class CartError extends ShoppexError {
+    constructor(message: string);
+}
+
+interface StorefrontCustomField {
+    name: string;
+    type: string;
+    required: boolean;
+    defaultValue: string;
+    placeholder: string;
+    regex?: string;
+}
+declare function normalizeStorefrontCustomFields(raw: unknown): StorefrontCustomField[];
+declare function isStorefrontCheckboxCustomFieldValueChecked(value: string | undefined): boolean;
+declare function validateStorefrontCustomFieldValue(field: StorefrontCustomField, value: string): string | null;
+declare function buildStorefrontCustomFieldPayload(fields: StorefrontCustomField[], values: Record<string, string>): Record<string, string>;
+
+type VariantLike = Pick<ProductVariant, 'stock' | 'orderable' | 'supplier_backed'> | Pick<PriceVariant, 'stock' | 'orderable' | 'supplier_backed'>;
+type ProductLike = Pick<Product, 'type' | 'stock' | 'orderable' | 'supplier_backed' | 'on_hold' | 'price_variants' | 'variants'> & {
+    onHold?: boolean | number | string | null;
+    is_on_hold?: boolean | number | string | null;
+    isOnHold?: boolean | number | string | null;
+};
+declare function resolveVariantStockValue(variant: VariantLike | null | undefined): number;
+declare function resolveDisplayStock(product: ProductLike | null | undefined): number;
+declare function isProductOutOfStock(product: ProductLike | null | undefined): boolean;
+declare function isProductInStock(product: ProductLike | null | undefined): boolean;
+declare function isVariantOutOfStock(variant: VariantLike | null | undefined): boolean;
+
+declare function buildStorefrontProductLookup(products?: Product[]): Map<string, Product>;
+declare function getStorefrontGroupProducts(group: ProductGroup, productsOrLookup?: Product[] | Map<string, Product>): Product[];
+declare function getMergedStorefrontProducts(products?: Product[]): Product[];
+
+interface StorefrontSearchFilterOptions {
+    hideOutOfStock?: boolean;
+    maxResults?: number;
+}
+type StorefrontCatalogSearchItem = {
+    type: 'product';
+    product: Product;
+} | {
+    type: 'group';
+    group: ProductGroup;
+    products: Product[];
+};
+declare function stripHtmlFromText(value: string | null | undefined): string;
+declare function normalizeSearchQuery(query: string): string;
+declare function collectProductSearchHaystack(product: Product): string[];
+declare function productMatchesSearchQuery(product: Product, query: string): boolean;
+declare function groupMatchesSearchQuery(group: ProductGroup, query: string): boolean;
+declare function filterProductsBySearchQuery(products: Product[], query: string, options?: StorefrontSearchFilterOptions): Product[];
+declare function searchMergedStorefrontCatalogItems(products: Product[], groups: ProductGroup[], query: string, options?: StorefrontSearchFilterOptions): StorefrontCatalogSearchItem[];
+declare function searchMergedStorefrontCatalog(products: Product[], groups: ProductGroup[], query: string, options?: StorefrontSearchFilterOptions): Product[];
+
+type StorefrontContactTicketInput = {
+    shopSlug: string;
+    email: string;
+    message: string;
+    title?: string;
+    name?: string;
+    invoiceId?: string;
+    apiBaseUrl?: string;
+};
+type StorefrontContactTicketResult = {
+    uniqid: string;
+};
+declare function resolveStorefrontApiBaseUrl(options?: {
+    apiBaseUrl?: string;
+    hostname?: string;
+}): string;
+declare function buildStorefrontContactMessage(input: {
+    name?: string;
+    message: string;
+    maxLength?: number;
+}): string;
+declare function submitStorefrontContactTicket(input: StorefrontContactTicketInput): Promise<StorefrontContactTicketResult>;
+type StorefrontSocialLinks = {
+    discord?: string | null;
+    telegram?: string | null;
+};
+declare function resolveStorefrontSocialLinks(store: {
+    discord_link?: string | null;
+    telegram_link?: string | null;
+    social?: Record<string, string | null | undefined> | null;
+} | null | undefined): StorefrontSocialLinks;
+
+/**
+ * Theme configuration types (framework agnostic)
+ */
+type SettingFieldType = 'color' | 'text' | 'range' | 'select' | 'boolean' | 'image' | 'font' | 'richtext' | 'products' | 'images';
+interface BaseSettingField {
+    type: SettingFieldType;
+    label: string;
+    description?: string;
+}
+interface ColorField extends BaseSettingField {
+    type: 'color';
+    default: string;
+}
+interface RangeField extends BaseSettingField {
+    type: 'range';
+    default: number;
+    min: number;
+    max: number;
+    step?: number;
+    unit?: string;
+}
+interface SelectField extends BaseSettingField {
+    type: 'select';
+    default: string;
+    options: string[] | {
+        value: string;
+        label: string;
+    }[];
+}
+interface BooleanField extends BaseSettingField {
+    type: 'boolean';
+    default: boolean;
+}
+interface TextField extends BaseSettingField {
+    type: 'text';
+    default: string;
+}
+interface ImageField extends BaseSettingField {
+    type: 'image';
+    default: string | null;
+}
+interface FontField extends BaseSettingField {
+    type: 'font';
+    default: string;
+    options?: string[];
+}
+interface RichtextField extends BaseSettingField {
+    type: 'richtext';
+    default: string;
+}
+interface ProductsField extends BaseSettingField {
+    type: 'products';
+    default: string[];
+    max?: number;
+}
+interface ImagesField extends BaseSettingField {
+    type: 'images';
+    default: string[];
+    max?: number;
+}
+type SettingField = ColorField | RangeField | SelectField | BooleanField | TextField | ImageField | FontField | RichtextField | ProductsField | ImagesField;
+interface SectionDefinition {
+    name: string;
+    description?: string;
+    icon?: string;
+    settings: Record<string, SettingField>;
+}
+interface BlockDefinition {
+    name: string;
+    description?: string;
+    icon?: string;
+    settings: Record<string, SettingField>;
+    allowedPages?: string[];
+    maxPerPage?: number;
+}
+interface BlockInstance {
+    id: string;
+    type: string;
+    visible?: boolean;
+    settings?: Record<string, SettingValue>;
+}
+interface PageLayout {
+    blocks: BlockInstance[];
+}
+interface ThemeBlockManifest {
+    pages: string[];
+    blocks: Record<string, BlockDefinition>;
+    defaultLayouts?: Record<string, PageLayout>;
+}
+interface ThemeConfig {
+    id: string;
+    name: string;
+    description?: string;
+    version: string;
+    author?: string;
+    preview?: string;
+    settings: Record<string, Record<string, SettingField>>;
+    sections: Record<string, SectionDefinition>;
+    blocks?: Record<string, BlockDefinition>;
+    pageLayouts?: Record<string, PageLayout>;
+    builder?: ThemeBlockManifest;
+}
+type SettingValue = string | number | boolean | null | string[] | Record<string, unknown>;
+type ResolvedThemeSettings = {
+    [Category: string]: {
+        [Key: string]: SettingValue;
+    };
+};
+
+type JsonRecord = Record<string, unknown>;
+interface PublishedBuilderSettings {
+    version: number;
+    revision: number;
+    theme: {
+        content: JsonRecord;
+        layout: JsonRecord;
+        style_slots: JsonRecord;
+        pages?: unknown[];
+        terms?: JsonRecord;
+        [key: string]: unknown;
+    };
+    [key: string]: unknown;
+}
+interface PublishedThemeSettingsPayload {
+    settings: ResolvedThemeSettings;
+    builder_settings: PublishedBuilderSettings | null;
+    content: JsonRecord;
+    style_slots: JsonRecord;
+}
+declare function fetchPublishedBuilderSettings(shopSlug: string): Promise<PublishedThemeSettingsPayload | null>;
+declare function fetchPublishedThemeSettings(shopSlug: string): Promise<ResolvedThemeSettings | null>;
+declare function resolveDefaults(config: ThemeConfig): ResolvedThemeSettings;
+declare function mergeSettings(defaults: ResolvedThemeSettings, overrides: Partial<ResolvedThemeSettings>): ResolvedThemeSettings;
+
+/**
+ * Store Module
+ *
+ * API methods for store data.
+ */
+
+interface GetStorefrontOptions {
+    productsLimit?: number;
+    productsCursor?: string | null;
+}
+declare function getStore(): Promise<SDKResponse<Shop>>;
+declare function resolveStoreByDomain(domain?: string, apiBaseUrl?: string): Promise<SDKResponse<Shop>>;
+declare function getStorefront(options?: GetStorefrontOptions): Promise<SDKResponse<StorefrontData>>;
+declare function getStoreLogoUrl(): Promise<string | null>;
+declare function getStoreBannerUrl(): Promise<string | null>;
+
+/**
+ * Products Module
+ *
+ * API methods for product data.
+ */
+
+interface GetStorefrontProductsPageOptions {
+    cursor?: string | null;
+    limit?: number;
+    sort?: 'featured' | 'newest' | 'price-asc' | 'price-desc' | string | null;
+    category?: string | null;
+    hideOutOfStock?: boolean;
+}
+declare function getProducts(): Promise<SDKResponse<Product[]>>;
+declare function getStorefrontProductsPage(options?: GetStorefrontProductsPageOptions): Promise<SDKResponse<{
+    products: Product[];
+    pagination: CursorPagination | null;
+}>>;
+declare function getProduct(idOrSlug: string): Promise<SDKResponse<Product>>;
+declare function getCategories(): Promise<SDKResponse<string[]>>;
+
+declare function getCartCoupon(): string | null;
+declare function getCartCouponSource(): CartCodeSource | null;
+declare function setCartCoupon(coupon: string | null | undefined, source?: CartCodeSource): string | null;
+declare function clearCartCoupon(): void;
+declare function getCart(): CartItem[];
+/** Resolve a cart line_id for product+variant. When multiple configs exist, returns the first line. */
+declare function resolveCartLineId(productId: string, variantId: string, cart?: CartItem[]): string;
+declare function getCartItemCount(): number;
+declare function addToCart(productId: string, variantId: string, quantity?: number, options?: CartAddOptions): void;
+declare function setCartItem(productId: string, variantId: string, quantity?: number, options?: CartAddOptions): void;
+/**
+ * Patch one cart line.
+ *
+ * TRI-STATE BOUNDS: `min_quantity`/`max_quantity` accept `null` to DELETE the
+ * stored bound — see {@link CartItemUpdate}. `undefined` (or an absent key)
+ * leaves it alone, which is why a removed ceiling needs its own spelling.
+ *
+ * NO-OP UPDATES DO NOT WRITE. An update that leaves the cart byte-identical
+ * returns without touching storage: no metadata bump, no `version` increment,
+ * and — because the storage write is what other tabs observe — no `storage`
+ * event. Writing anyway made an ineffective heal indistinguishable from a real
+ * cart change, and two tabs healing the same line could hand the event back and
+ * forth indefinitely. Line-shape healing of a legacy stored row is NOT this
+ * function's job: `normalizeCartItems` clamps and repairs on every READ, which
+ * is the chokepoint every access already flows through.
+ */
+declare function updateCartItem(lineId: string, updates: CartItemUpdate): void;
+declare function removeFromCart(lineId: string): void;
+/**
+ * Discards the cart entirely — and with it the proof that describes it.
+ *
+ * PAYMENT PATH. `latestQuoteToken` is evidence about a specific cart, and this
+ * is the one mutation after which that cart does not exist in any form. Held
+ * across the clear, the proof outlives its subject: a caller that clears and
+ * re-adds (Buy Now REPLACES the cart) hands `/from-cart` a token bound to the
+ * previous cart's hash, which is refused as `quote_token_stale` — a hand-off
+ * dead-ended by a proof nobody asked for. And with no re-quote in between there
+ * is nothing to replace it with, so the retry is refused identically.
+ *
+ * Only this path clears it. Every OTHER mutation turns one cart into another
+ * cart, where a proof that no longer matches is the server's to refuse: it
+ * answers `quote_token_stale`, the surfaces re-quote, and the buyer approves the
+ * new total. Dropping the proof there instead would silently remove the approved
+ * -total ceiling from a checkout that raced the re-quote, which is the failure
+ * the token exists to prevent.
+ */
+declare function clearCart(): void;
+declare function createCartBackup(): void;
+declare function restoreCartFromBackup(): boolean;
+declare function mergeBaskets(items: CartBasketMergeLine[]): CartItem[];
+declare function moveBasketItem(fromProductId: string, fromVariantId: string, toProductId: string, toVariantId: string): void;
+declare function validateCartIntegrity(): boolean;
+declare function getCartStats(): CartStats;
+declare function quoteCart(coupon?: string, currency?: string): Promise<src.SDKResponse<CartQuote>>;
+
+type CartLineIdentityInput = Pick<CartItem, 'product_id' | 'variant_id' | 'price_variant_id' | 'addons' | 'custom_fields' | 'price_data' | 'pay_what_you_want_price'>;
+declare function computeCartLineId(input: CartLineIdentityInput): string;
+declare function ensureCartLineId(item: CartItem): CartItem;
+
+/**
+ * Checkout Module
+ *
+ * Creates invoice via backend API and redirects to hosted checkout page.
+ * All checkout flows go through: checkout.shoppex.io/invoice/{invoiceId}
+ */
+
+interface CheckoutOptions {
+    autoRedirect?: boolean;
+    locale?: string;
+    email?: string;
+    coupon?: string;
+    currency?: string;
+    /**
+     * Absolute HTTPS URL used after a completed purchase when the product does
+     * not define its own redirect. This is persisted on the invoice, so each
+     * sales channel can provide its own return destination.
+     */
+    redirectUrl?: string;
+    /**
+     * A Cloudflare Turnstile proof for the `storefront_checkout` action.
+     *
+     * Normally omitted. A checkout surface may provide a renewed proof when a
+     * legitimate shared network reaches the public invoice-create budget. The
+     * widget must run on the same origin that calls this SDK, while the proof is
+     * transport-only and does not change the checkout intent or its idempotency
+     * key.
+     */
+    turnstileToken?: string;
+    /**
+     * Referral (affiliate) code to submit, as a tri-state:
+     *
+     * - `undefined` — the SDK resolves it from storage (cart-applied referral
+     *   code first, then the ambient `?ref=` attribution).
+     * - `''` — explicitly none: submit no referral code and do NOT re-read
+     *   storage. This is how a caller pins "quoted WITHOUT a referral"; without
+     *   it a code captured between the quote and the submit would be applied to
+     *   a total the buyer never saw.
+     * - non-empty — pinned: submit exactly this code.
+     *
+     * `referralCode` is an alias and follows the same rules; `affiliateCode`
+     * wins when both are present.
+     */
+    affiliateCode?: string;
+    /** Alias of {@link CheckoutOptions.affiliateCode}, same tri-state. */
+    referralCode?: string;
+    customerCheckoutPath?: '/dashboard/api/checkout';
+    /**
+     * The cart this hand-off was approved FOR, as `JSON.stringify(getCart())`.
+     *
+     * PAYMENT PATH. A caller that writes the cart and reads it back before
+     * checking out (Buy Now, which replaces the cart, is the sharp case) verifies
+     * a cart it read at one moment, while these functions read storage again on
+     * their way into the request — and localStorage is shared with every other
+     * tab on the domain. A write landing in that gap is billed without ever
+     * having passed the caller's verification.
+     *
+     * The caller cannot close that itself: any check it makes is one more read
+     * BEFORE this one. Pinning the expected bytes moves the comparison to the
+     * only place it can be conclusive — against the exact cart the call is about
+     * to POST. A mismatch refuses before anything is created or sent.
+     *
+     * Honoured identically by BOTH invoice-creating entry points, `checkout()`
+     * and `buildCheckoutUrl()` — they hit the same endpoint and create the same
+     * invoice, so a pin that held on one and not the other would be a promise
+     * the caller could not rely on. Only the refusal shape differs, following
+     * each function's own success shape: `checkout()` returns
+     * `{ success: false }`, `buildCheckoutUrl()` throws.
+     *
+     * Optional and additive: omitted, nothing changes, and the server is not
+     * involved either way.
+     */
+    expectedCart?: string;
+}
+interface CheckoutResult {
+    success: boolean;
+    redirectUrl?: string;
+    invoiceId?: string;
+    rewards?: BuyerRewards | null;
+    message?: string;
+    /**
+     * The server's machine-readable refusal identifier when the checkout was
+     * refused, e.g. `errors.checkout.price_increased_since_quote` or
+     * `errors.checkout.affiliate_code_not_applicable`. Branch on this rather
+     * than on `message`, which is localized display copy.
+     *
+     * The quote-proof family — `errors.checkout.quote_token_invalid`,
+     * `errors.checkout.quote_token_expired`, `errors.checkout.quote_token_stale`
+     * — says the proof this call submitted could not be honoured: not ours, past
+     * its window, or priced for a cart/currency/codes that have since moved. The
+     * server refuses rather than pricing without the ceiling, so the caller's
+     * response is always the same: `quoteCart()` again, show the buyer the new
+     * total, and only then retry. A retry with the same stale token is refused
+     * identically.
+     *
+     * Absent for failures the server never named (transport, timeout, an empty
+     * cart caught client-side).
+     */
+    code?: string;
+    /**
+     * Human-verification challenge returned when a legitimate shared network
+     * reaches the invoice-create budget. Render the named provider on the same
+     * origin that calls the SDK, then retry with its proof as `turnstileToken`.
+     */
+    challenge?: ApiChallenge;
+}
+/**
+ * Typed refusal from {@link buildCheckoutUrl}. The function keeps its existing
+ * throw-based contract while exposing a server-requested human-verification
+ * challenge so callers can render it and retry with `turnstileToken`.
+ */
+declare class CheckoutCreateError extends Error {
+    readonly challenge?: ApiChallenge;
+    readonly code?: string;
+    readonly status?: number;
+    constructor(message: string, options?: {
+        challenge?: ApiChallenge;
+        code?: string;
+        status?: number;
+    });
+}
+declare function checkout(couponOrOptions?: string | CheckoutOptions, options?: CheckoutOptions): Promise<CheckoutResult>;
+/**
+ * Build checkout URL by creating invoice first.
+ * Returns the checkout URL for the created invoice.
+ *
+ * PAYMENT PATH. "Build a URL" names what this returns, not a lighter way to
+ * price a cart: it POSTs the same invoice-creating endpoint as `checkout()` and
+ * bills whatever storage holds when it reads. It therefore honours
+ * `CheckoutOptions.expectedCart` on exactly the same terms — a pinned cart that
+ * moved is refused, not invoiced.
+ *
+ * A refusal throws, like every other refusal on this function: the success
+ * shape is a URL string, so there is no in-band value that a caller could
+ * mistake for one. The thrown message is the buyer-facing copy, identical to
+ * the sentence `checkout()` returns, and callers that already handle the
+ * `Cart is empty` throw handle this one unchanged.
+ */
+declare function buildCheckoutUrl(couponOrOptions?: string | CheckoutOptions, options?: CheckoutOptions): Promise<string>;
+/**
+ * @deprecated Use buildCheckoutUrl instead.
+ * Sync version is no longer supported as invoice creation requires API call.
+ */
+declare function buildCheckoutUrlSync(): never;
+
+interface SearchOptions {
+    hideOutOfStock?: boolean;
+    maxResults?: number;
+}
+
+declare function searchCatalogItems(query: string, options?: SearchOptions): Promise<SDKResponse<StorefrontCatalogSearchItem[]>>;
+declare function searchProducts(query: string, options?: SearchOptions): Promise<SDKResponse<Product[]>>;
+
+declare function setAffiliateCode(code: string | null | undefined, ttlDays?: number): string | null;
+declare function clearAffiliateCode(): void;
+declare function getAffiliateCode(): string | null;
+declare function trackAffiliateEvent(eventType: 'add_to_cart' | 'checkout_started', options?: {
+    /**
+     * The code the surrounding call actually resolved and submitted (e.g.
+     * checkout()'s tri-state result). `null` means the caller explicitly
+     * submitted WITHOUT a referral — no event is recorded, so an ambient
+     * stored code is never credited for a sale it did not get. Omit the
+     * options object entirely to attribute to the stored ambient code.
+     */
+    code: string | null;
+    /**
+     * Overrides the per-browser-session dedupe key. checkout entry points
+     * pass `inv:<invoiceId>` so every created invoice counts as exactly one
+     * checkout — a session-wide key would drop the second checkout of a
+     * buyer who orders twice in one session while both sales still count.
+     */
+    dedupeKey?: string;
+}): Promise<void>;
+declare function validateAffiliateCode(code: string): Promise<SDKResponse<AffiliateValidation>>;
+declare function applyAffiliateCode(code: string): Promise<SDKResponse<AffiliateValidation>>;
+/**
+ * Capture an affiliate code from the current URL and store it for 30 days (last-click).
+ *
+ * Example:
+ * - URL: https://mystore.com/product/abc?ref=deadbeef
+ * - captureAffiliateFromUrl() stores "deadbeef" and returns it.
+ */
+declare function captureAffiliateFromUrl(param?: string): Promise<string | null>;
+
+/**
+ * Coupons Module
+ *
+ * Coupon validation before checkout.
+ */
+
+declare function validateCoupon(code: string, productOrOptions?: string | CouponValidationOptions): Promise<SDKResponse<CouponValidation>>;
+
+/**
+ * Reviews Module
+ *
+ * Shop-level feedback/reviews.
+ * Note: Shoppex has shop-level feedback, not product-level reviews.
+ */
+
+declare function getShopReviewsPage(cursor?: string | null): Promise<SDKResponse<ShopReviewsPage>>;
+declare function getShopReviews(): Promise<SDKResponse<Feedback[]>>;
+
+/**
+ * Customer Module
+ *
+ * Authenticated customer account calls for code-lane storefronts. The edge
+ * worker owns the HttpOnly session cookie and derives the shop from the host.
+ * This module therefore sends neither a session token nor shop identity.
+ */
+
+interface CustomerOrdersQuery {
+    page?: number;
+    limit?: number;
+    /**
+     * Invoice status filter, verbatim from the producer's enum. Anything else is
+     * answered with a 400 rather than quietly ignored, so pass what the buyer
+     * actually chose.
+     */
+    status?: string;
+    /** Partial invoice-id search. The producer trims it to 64 characters. */
+    search?: string;
+}
+interface CustomerTicketPayload {
+    title?: string;
+    message: string;
+    invoice_id?: string;
+}
+interface CustomerProfilePatch {
+    name: string;
+}
+interface CustomerSubscriptionCancelOptions {
+    cancel_at_period_end?: boolean;
+    reason?: string | null;
+}
+interface CustomerEmailPreferencesPatch {
+    global_unsubscribed?: boolean;
+    list_subscriptions?: Array<{
+        list_id: string;
+        subscribed: boolean;
+    }>;
+}
+/** One basket line for a QUOTE. `variant_id` is omitted, never null, when a product has no variants. */
+interface ResellerOrderItem {
+    product_id: string;
+    variant_id?: string;
+    quantity: number;
+}
+interface ResellerCatalogQuery {
+    search?: string;
+    page?: number;
+    per_page?: number;
+}
+interface ResellerOrdersQuery {
+    page?: number;
+    per_page?: number;
+}
+declare function requestOtp(email: string): Promise<SDKResponse<unknown>>;
+/**
+ * The wire field is `otp`, not `code` — `CustomerOtpVerifyBodySchema` in
+ * `apps/backend-elysia/src/routes/v1/customer/schemas.ts` requires it under that
+ * name, and a `code` body is rejected with 400.
+ */
+declare function verifyOtp(email: string, otp: string): Promise<SDKResponse<unknown>>;
+declare function logout(): Promise<SDKResponse<unknown>>;
+declare function me(): Promise<SDKResponse<unknown>>;
+declare function dashboard(): Promise<SDKResponse<CustomerPortalDashboardWire>>;
+/**
+ * Paginated order history.
+ *
+ * Page-based, matching the producer: `invoices.routes.ts` reads `page` and
+ * `limit` and answers with a `has_more` envelope. A cursor parameter would be
+ * ignored upstream and silently return page one forever.
+ *
+ * `status` and `search` are filtered SERVER-side, which is why they belong
+ * here rather than in the caller: `/invoices` is paged, and a filter applied
+ * to the page in hand would filter only the rows that page happens to hold.
+ * The producer spells the search `q`.
+ */
+declare function orders(options?: CustomerOrdersQuery): Promise<SDKResponse<CustomerPortalPaginatedInvoicesWire>>;
+declare function order(id: string): Promise<SDKResponse<CustomerPortalInvoiceDetailWire>>;
+declare function loyalty(): Promise<SDKResponse<CustomerLoyaltyWire>>;
+declare function redeemLoyaltyPoints(input: {
+    points: number;
+    idempotencyKey: string;
+}): Promise<SDKResponse<CustomerLoyaltyRedeemWire>>;
+/**
+ * The warranties this buyer holds — all of them, or the ones on one order.
+ *
+ * `invoiceUniqid` becomes the producer's own `invoice=` filter, which matches
+ * `invoices.uniqid`: the id an order carries everywhere a storefront shows one.
+ * So an order detail asks for its own cover rather than reading every warranty
+ * the buyer owns and discarding most of them.
+ */
+declare function warranties(invoiceUniqid?: string): Promise<SDKResponse<CustomerWarrantyListWire>>;
+declare function claimWarranty(uniqid: string, message?: string): Promise<SDKResponse<CustomerWarrantyClaimWire>>;
+declare function resetLicenseHwid(uniqid: string): Promise<SDKResponse<unknown>>;
+declare function subscriptionBillingHistory(uniqid: string): Promise<SDKResponse<unknown>>;
+declare function cancelSubscription(uniqid: string, options?: CustomerSubscriptionCancelOptions): Promise<SDKResponse<unknown>>;
+declare function pauseSubscription(uniqid: string): Promise<SDKResponse<unknown>>;
+declare function resumeSubscription(uniqid: string): Promise<SDKResponse<unknown>>;
+declare function favorites(): Promise<SDKResponse<unknown>>;
+/** Idempotent upstream, and a PUT — `customer-favorites.ts` has no POST route. */
+declare function addFavorite(productUniqid: string): Promise<SDKResponse<unknown>>;
+declare function removeFavorite(productUniqid: string): Promise<SDKResponse<unknown>>;
+declare function affiliate(): Promise<SDKResponse<unknown>>;
+declare function affiliateStats(days?: number): Promise<SDKResponse<unknown>>;
+declare function createTicket(payload: CustomerTicketPayload): Promise<SDKResponse<unknown>>;
+declare function ticket(uniqid: string): Promise<SDKResponse<unknown>>;
+declare function replyToTicket(uniqid: string, message: string): Promise<SDKResponse<unknown>>;
+/**
+ * The producer is `POST /v1/customer/profile`, not PATCH.
+ *
+ * There is no `GET /profile` to pair with it — the buyer's own record comes from
+ * `/me` and `/dashboard`.
+ */
+declare function updateProfile(patch: CustomerProfilePatch): Promise<SDKResponse<unknown>>;
+declare function updateAvatar(file: File): Promise<SDKResponse<unknown>>;
+declare function removeAvatar(): Promise<SDKResponse<unknown>>;
+declare function emailPreferences(): Promise<SDKResponse<unknown>>;
+declare function updateEmailPreferences(patch: CustomerEmailPreferencesPatch): Promise<SDKResponse<unknown>>;
+declare function sessions(): Promise<SDKResponse<unknown>>;
+declare function revokeSession(id: string): Promise<SDKResponse<unknown>>;
+/**
+ * Ends every session except this one.
+ *
+ * `others=true` is required, not decorative: `RevokeOtherSessionsQuerySchema`
+ * declares it as a literal, so the route answers 400 without it. The selector
+ * is explicit on purpose — "revoke sessions" with no qualifier is one typo away
+ * from signing the buyer out of the device they are holding.
+ */
+declare function revokeAllSessions(): Promise<SDKResponse<unknown>>;
+/** The program's state and this buyer's place in it. Null reseller means not enrolled. */
+declare function reseller(): Promise<SDKResponse<unknown>>;
+/** `APPLICATION` mode. The note is optional unless the shop requires one. */
+declare function applyForReseller(note?: string): Promise<SDKResponse<unknown>>;
+/** `OPEN` mode: no application, the buyer is a reseller when they say so. */
+declare function enrollAsReseller(): Promise<SDKResponse<unknown>>;
+/** `MANUAL` mode: the merchant invited this buyer and gave them a token. */
+declare function acceptResellerInvite(token: string): Promise<SDKResponse<unknown>>;
+/** The buyer's own tier prices. Page-based, like the order history. */
+declare function resellerCatalog(options?: ResellerCatalogQuery): Promise<SDKResponse<unknown>>;
+/**
+ * Prices a basket and writes nothing.
+ *
+ * The volume discount cannot be derived from the catalog — it only reports that
+ * one exists — so a storefront that adds up unit prices itself shows a total
+ * the shop will not charge. This is the number to display.
+ */
+declare function quoteResellerOrder(items: ResellerOrderItem[]): Promise<SDKResponse<unknown>>;
+declare function resellerOrders(options?: ResellerOrdersQuery): Promise<SDKResponse<unknown>>;
+/** One order with its lines, delivery state and delivered serials. */
+declare function resellerOrder(uniqid: string): Promise<SDKResponse<unknown>>;
+/** The prepaid balance the wholesale orders are paid from. */
+declare function resellerWallet(): Promise<SDKResponse<unknown>>;
+declare function resellerApiKeys(): Promise<SDKResponse<unknown>>;
+
+/**
+ * Invoices Module
+ *
+ * Invoice status checking after payment.
+ */
+
+declare function getInvoice(invoiceId: string): Promise<SDKResponse<Invoice>>;
+declare function getInvoiceStatus(invoiceId: string): Promise<SDKResponse<{
+    status: string;
+}>>;
+
+/**
+ * Pages Module
+ *
+ * API methods for public pages.
+ */
+
+/**
+ * Get all public pages for the store
+ */
+declare function getPages(): Promise<SDKResponse<Page[]>>;
+/**
+ * Get a public page by slug
+ */
+declare function getPage(slug: string): Promise<SDKResponse<Page>>;
+
+/**
+ * Navigation Module
+ *
+ * API methods for menus and navigation.
+ */
+
+/**
+ * Get all menus for the store
+ */
+declare function getMenus(): Promise<SDKResponse<Menu[]>>;
+/**
+ * Get a menu by its exact title.
+ */
+declare function getMenuByTitle(title: string): Promise<SDKResponse<Menu>>;
+/**
+ * Get a menu by its exact title.
+ */
+declare function getMenu(title: string): Promise<SDKResponse<Menu>>;
+/**
+ * Get a menu by canonical slot. The backend resolves legacy menu titles too.
+ */
+declare function getMenuBySlot(slot: NavigationMenuSlot): Promise<SDKResponse<Menu>>;
+declare function getMenuSlotTitles(slot: NavigationMenuSlot): string[];
+
+declare function trackPageView(cartValue?: number, itemCount?: number): Promise<void>;
+
+/**
+ * Anonymized recent-sales feed for storefront social proof (product title +
+ * relative age only — never buyer identity). Empty items when the shop has no
+ * recent completed orders.
+ */
+declare function getStorefrontRecentSales(): Promise<SDKResponse<StorefrontRecentSales>>;
+declare function getStorefrontOnlineUsers(): Promise<SDKResponse<StorefrontOnlineUsers>>;
+declare function touchStorefrontPresence(): Promise<SDKResponse<{
+    pong: string;
+}>>;
+
+/**
+ * Formatting Utilities
+ */
+declare function createFormatter(currency?: string, locale?: string): Intl.NumberFormat;
+declare function formatPrice(amount: number | string, currency?: string, locale?: string): string;
+
+interface CacheStats {
+    hits: number;
+    misses: number;
+    pendingRequests: number;
+    entries: number;
+}
+declare function getCacheStats(): CacheStats;
+declare function clearCache(): void;
+declare function invalidateCache(prefixOrKey: string): void;
+
+/**
+ * Shoppex Storefront SDK
+ *
+ * Usage:
+ * ```html
+ * <script src="https://cdn.shoppex.io/sdk/v1.0/shoppex.umd.js"></script>
+ * <script>
+ *   shoppex.init('my-store');
+ *
+ *   shoppex.getStore().then(store => console.log(store));
+ *   shoppex.addToCart('product-id', 'variant-id', 2);
+ *   shoppex.checkout();
+ * </script>
+ * ```
+ */
+
 /**
  * Initialize the SDK with a store slug
  */
@@ -54,7 +1862,7 @@ declare function init(options: ShoppexInitOptions & {
 /**
  * Shoppex SDK instance
  */
-export declare const shoppex: {
+declare const shoppex: {
     init: typeof init;
     isInitialized: typeof isInitialized;
     getConfig: typeof getConfig;
@@ -96,6 +1904,7 @@ export declare const shoppex: {
     getAffiliateCode: typeof getAffiliateCode;
     setAffiliateCode: typeof setAffiliateCode;
     clearAffiliateCode: typeof clearAffiliateCode;
+    trackAffiliateEvent: typeof trackAffiliateEvent;
     validateCoupon: typeof validateCoupon;
     getShopReviews: typeof getShopReviews;
     getShopReviewsPage: typeof getShopReviewsPage;
@@ -119,6 +1928,7 @@ export declare const shoppex: {
     addFavorite: typeof addFavorite;
     removeFavorite: typeof removeFavorite;
     affiliate: typeof affiliate;
+    affiliateStats: typeof affiliateStats;
     createTicket: typeof createTicket;
     ticket: typeof ticket;
     replyToTicket: typeof replyToTicket;
@@ -165,5 +1975,5 @@ export declare const shoppex: {
     resolveDefaults: typeof resolveDefaults;
     mergeSettings: typeof mergeSettings;
 };
-export default shoppex;
-//# sourceMappingURL=index.d.ts.map
+
+export { type AffiliateValidation, type ApiChallenge, ApiError, type ApiResponse, type BlockDefinition, type BlockInstance, type BuyerRewardActivityItem, type BuyerRewards, type CartAddOptions, type CartAddon, type CartAppliedDiscount, type CartBasketMergeLine, type CartCodeSource, CartError, type CartItem, type CartItemUpdate, type CartLineIdentityInput, type CartMetadata, type CartPayload, type CartQuote, type CartQuoteLine, type CartStats, type Category, CheckoutCreateError, type CheckoutOptions, type CheckoutResult, type CouponValidation, type CouponValidationOptions, type CursorPagination, type CustomFieldDefinition, type CustomerEmailPreferencesPatch, type CustomerProfilePatch, type CustomerSubscriptionCancelOptions, type CustomerTicketPayload, type EligibleBundleDeal, type EligibleBundleDealProduct, type EligibleCartDeal, type Feedback, type Invoice, type InvoiceProduct, type Menu, type MenuItem, NetworkError, NotInitializedError, type Page, type PageLayout, type PriceVariant, type Product, type ProductAddon, type ProductBundle, type ProductBundleProduct, type ProductCategory, type ProductDescriptionTab, type ProductFaq, type ProductFeedback, type ProductGroup, type ProductImage, type ProductVariant, type PublishedBuilderSettings, type PublishedThemeSettingsPayload, type ResellerCatalogQuery, type ResellerOrderItem, type ResellerOrdersQuery, type ResolvedThemeSettings, type RewardActionType, type RewardGrantStatus, type RewardProgramSummary, type RewardProgramTeaserItem, type RewardReason, type SDKResponse, type SearchOptions, type SectionDefinition, type SettingField, type Shop, type ShopFeedback, type ShopReviewsPage, type ShopReviewsSummary, type ShopTheme, type ShoppexConfig, ShoppexError, type ShoppexInitOptions, type StorefrontAddon, type StorefrontAddonBootstrap, type StorefrontAnnouncementBarAddon, type StorefrontCatalogSearchItem, type StorefrontContactTicketInput, type StorefrontContactTicketResult, type StorefrontCountdownBarAddon, type StorefrontCouponPopupModalAddon, type StorefrontCustomField, type StorefrontData, type StorefrontItem, type StorefrontOnlineUsers, type StorefrontPromoInfoCardAddon, type StorefrontRecentPurchasePopupAddon, type StorefrontRecentSaleEntry, type StorefrontRecentSales, type StorefrontSearchFilterOptions, type StorefrontSocialLinks, type Subscription, type SubscriptionFlags, type SubscriptionInterval, type ThemeBlockManifest, type ThemeConfig, type TrustedChecks, ValidationError, acceptResellerInvite, addFavorite, affiliate, affiliateStats, applyForReseller, buildStorefrontContactMessage, buildStorefrontCustomFieldPayload, buildStorefrontProductLookup, cancelSubscription, claimWarranty, collectProductSearchHaystack, computeCartLineId, createTicket, dashboard, shoppex as default, emailPreferences, enrollAsReseller, ensureCartLineId, favorites, fetchPublishedBuilderSettings, fetchPublishedThemeSettings, filterProductsBySearchQuery, getMenu, getMenuBySlot, getMenuByTitle, getMenuSlotTitles, getMenus, getMergedStorefrontProducts, getShopReviewsPage, getStorefrontGroupProducts, getStorefrontOnlineUsers, getStorefrontRecentSales, groupMatchesSearchQuery, isProductInStock, isProductOutOfStock, isStorefrontCheckboxCustomFieldValueChecked, isVariantOutOfStock, logout, loyalty, me, mergeSettings, normalizeSearchQuery, normalizeStorefrontCustomFields, order, orders, pauseSubscription, productMatchesSearchQuery, quoteResellerOrder, redeemLoyaltyPoints, removeAvatar, removeFavorite, replyToTicket, requestOtp, reseller, resellerApiKeys, resellerCatalog, resellerOrder, resellerOrders, resellerWallet, resetLicenseHwid, resolveDefaults, resolveDisplayStock, resolveStorefrontApiBaseUrl, resolveStorefrontSocialLinks, resolveVariantStockValue, resumeSubscription, revokeAllSessions, revokeSession, searchMergedStorefrontCatalog, searchMergedStorefrontCatalogItems, sessions, shoppex, stripHtmlFromText, submitStorefrontContactTicket, subscriptionBillingHistory, ticket, touchStorefrontPresence, trackPageView, updateAvatar, updateEmailPreferences, updateProfile, validateStorefrontCustomFieldValue, verifyOtp, warranties };