@shoppexio/storefront 1.0.57 → 1.0.59

package/dist/types/api.d.ts

@@ -1,757 +0,0 @@
-import { NavigationMenuSlot } from '@shoppex/contracts/navigation';
-/**
- * API Response Types
- *
- * Backend returns: { status: number, data: T, error: string | null }
- * SDK maps to: { success: boolean, data?: T, message?: string }
- */
-export 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;
-}
-export interface ApiChallenge {
-    provider: 'turnstile';
-    siteKey: string;
-}
-export 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;
-}
-export 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;
-}
-export interface RewardProgramTeaserItem {
-    trigger_type: RewardReason;
-    action_type: RewardActionType;
-    label: string;
-}
-export interface RewardProgramSummary {
-    enabled: boolean;
-    headline: string;
-    items: RewardProgramTeaserItem[];
-}
-export 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;
-}
-export interface ShopFeedback {
-    positive: number;
-    neutral: number;
-    negative: number;
-    total: number;
-}
-export interface TrustedChecks {
-    identity_verified?: boolean;
-    feedback_score?: string | null;
-    trusted_score?: number;
-    sales_last14days_metric?: string;
-}
-export 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;
-}
-export interface ProductDescriptionTab {
-    title: string;
-    content: string;
-}
-export 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[];
-    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;
-}
-export 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;
-    }>;
-}
-export interface ProductImage {
-    id: string;
-    url: string;
-    cloudflare_image_id?: string;
-    alt?: string;
-}
-export 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;
-}
-export interface ProductAddon {
-    id: string;
-    name?: string;
-    title?: string;
-    price: number;
-    required?: boolean;
-}
-export 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;
-}
-export interface CustomFieldDefinition {
-    id: string;
-    name: string;
-    type: 'text' | 'textarea' | 'select' | 'checkbox';
-    required?: boolean;
-    options?: string[];
-}
-export 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;
-}
-export interface ShopReviewsSummary {
-    total: number;
-    positive: number;
-    neutral: number;
-    negative: number;
-    average_score: number | null;
-}
-export interface ShopReviewsPage {
-    feedback: Feedback[];
-    pagination: CursorPagination;
-    summary: ShopReviewsSummary;
-}
-export interface ProductBundle {
-    id?: string;
-    uniqid?: string;
-    title?: string;
-    discount_type?: 'PERCENTAGE' | 'FIXED';
-    discount_amount?: number;
-    products?: ProductBundleProduct[];
-}
-export interface ProductBundleProduct {
-    id?: string;
-    uniqid: string;
-    title?: string | null;
-    default_variant_id?: string;
-}
-export interface ProductFaq {
-    id?: string;
-    uniqid?: string;
-    question: string;
-    answer: string;
-}
-export interface SubscriptionInterval {
-    unit?: string;
-    count?: number;
-    label?: string;
-}
-export interface SubscriptionFlags {
-    cancel_anytime?: boolean;
-}
-export interface Subscription {
-    id?: string;
-    name?: string;
-    description?: string;
-    badge?: string;
-    interval?: SubscriptionInterval;
-    flags?: SubscriptionFlags;
-}
-export interface Invoice {
-    uniqid: string;
-    status: string;
-    total: number;
-    currency: string;
-    gateway?: string;
-    products: InvoiceProduct[];
-    created_at: string;
-    rewards?: BuyerRewards | null;
-}
-export interface InvoiceProduct {
-    product_id: string;
-    title: string;
-    quantity: number;
-    price: number;
-}
-export type RewardActionType = 'WALLET_CREDIT' | 'COUPON';
-export type RewardGrantStatus = 'PENDING' | 'FULFILLED' | 'FAILED' | 'REVOKED';
-export type RewardReason = 'ORDER_COMPLETED' | 'ORDER_COUNT_REACHED' | 'SPEND_AMOUNT_REACHED' | 'POSITIVE_REVIEW_LEFT' | 'FIRST_PURCHASE_COMPLETED';
-export 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;
-}
-export 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[];
-}
-export 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;
-}
-export interface CouponValidationOptions {
-    productId?: string;
-    variantId?: string;
-}
-export interface AffiliateValidation {
-    valid: boolean;
-    program_enabled?: boolean;
-    affiliate_code: string | null;
-    discount_active: boolean;
-    discount_percent: number;
-    message?: string;
-}
-export 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;
-}
-export 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;
-}
-export interface CursorPagination {
-    next_cursor: string | null;
-    has_more: boolean;
-}
-export 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;
-    };
-}
-export 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;
-    };
-}
-export 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;
-    };
-}
-export 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;
-        }>;
-    };
-}
-export 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;
-    };
-}
-export type StorefrontAddon = StorefrontAnnouncementBarAddon | StorefrontCountdownBarAddon | StorefrontPromoInfoCardAddon | StorefrontRecentPurchasePopupAddon | StorefrontCouponPopupModalAddon;
-export interface StorefrontAddonBootstrap {
-    items: StorefrontAddon[];
-}
-export interface StorefrontOnlineUsers {
-    count: number;
-    window_seconds: number;
-}
-export interface StorefrontRecentSaleEntry {
-    product_title: string;
-    seconds_ago: number;
-}
-export interface StorefrontRecentSales {
-    items: StorefrontRecentSaleEntry[];
-    window_hours: number;
-}
-export type StorefrontItem = {
-    item_type: 'PRODUCT' | 'GROUP';
-    uniqid: string;
-    sort_priority?: number | null;
-    title?: string | null;
-};
-export interface StorefrontData {
-    shop: Shop;
-    products: Product[];
-    products_pagination?: CursorPagination | null;
-    groups: ProductGroup[];
-    items: StorefrontItem[];
-    categories: Category[];
-    addons: StorefrontAddonBootstrap;
-}
-export 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;
-}
-export interface Menu {
-    id: string;
-    shop_id: string;
-    title: string;
-    slot?: NavigationMenuSlot | null;
-    item_count?: number | null;
-    items?: MenuItem[];
-    created_at: number;
-    updated_at: number;
-}
-export 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[];
-}
-//# sourceMappingURL=api.d.ts.map