@zappie/sdk 0.0.0-stage → 0.1.0

package/dist/client-BctSrEhO.d.ts

@@ -0,0 +1,725 @@
+import { d as Currency, M as Money, I as Item, a as Menu, C as CategoryPage, S as Store, F as Formatters } from './models-Dj-VkdU1.js';
+
+/**
+ * An item selection you submit to the cart, with optional quantity, choices, inputs and source menu.
+ */
+type CartLineInput = {
+    itemId: string;
+    /** The source menu the shopper selected. The SDK checks catalogue membership. */
+    menuId?: string;
+    quantity?: number;
+    choices?: {
+        groupId: string;
+        choiceId: string;
+        quantity?: number;
+    }[];
+    inputs?: Record<string, string>;
+    variantId?: string;
+    note?: string;
+};
+/**
+ * A readonly cart line with its selection, local price estimate and time added.
+ */
+type CartLine = Readonly<{
+    id: string;
+    itemId: string;
+    /** The source menu the shopper selected. The SDK checks catalogue membership. */
+    menuId?: string;
+    name: string;
+    quantity: number;
+    choices: readonly Readonly<{
+        groupId: string;
+        choiceId: string;
+        quantity: number;
+    }>[];
+    inputs: Readonly<Record<string, string>>;
+    variantId?: string;
+    note?: string;
+    unitPrice: Money;
+    lineSubtotal: Money;
+    addedAt: string;
+}>;
+/**
+ * A cart delivery address with optional place coordinates and instructions.
+ */
+type DeliveryAddress = {
+    line1: string;
+    line2?: string;
+    city?: string;
+    placeId?: string;
+    coordinates?: {
+        lat: number;
+        lng: number;
+    };
+    instructions?: string;
+};
+/** A shopper's selection, distinct from the store's Fulfilment capabilities. */
+type CartFulfilment = {
+    type: "pickup";
+    branchId: string;
+    scheduledFor?: string;
+} | {
+    type: "delivery";
+    branchId: string;
+    address: DeliveryAddress;
+    scheduledFor?: string;
+} | {
+    type: "dine_in";
+    branchId: string;
+    table?: string;
+};
+/**
+ * Stable identifiers for cart validation and quote issues you can handle in your UI.
+ */
+type CartIssueCode = "item_unavailable" | "item_not_found" | "option_unavailable" | "option_required" | "option_limit" | "quantity_limit" | "price_changed" | "branch_closed" | "fulfilment_unavailable" | "outside_delivery_zone" | "delivery_region_required" | "schedule_invalid" | "promo_invalid" | "promo_min_spend" | "min_order" | "menu_version_stale";
+/**
+ * A suggested cart correction, including any option, quantity or fulfilment details it needs.
+ */
+type CartFix = {
+    action: "remove_line" | "accept_price" | "remove_promo" | "change_address";
+} | {
+    action: "choose_option" | "choose_other_option";
+    groupId: string;
+} | {
+    action: "set_quantity";
+    quantity: number;
+} | {
+    action: "schedule";
+    nextOpenAt?: string;
+    slots?: string[];
+} | {
+    action: "switch_fulfilment";
+    types: CartFulfilment["type"][];
+};
+/**
+ * A local or quoted cart issue with severity, display message and suggested fixes.
+ */
+type CartIssue = {
+    code: CartIssueCode;
+    severity: "blocking" | "warning" | "info";
+    lineId?: string;
+    groupId?: string;
+    message: string;
+    data?: Record<string, unknown>;
+    fixes: CartFix[];
+    source: "local" | "quote";
+};
+/**
+ * Server-provided cart pricing, fees, discounts, issues and checkout readiness with an expiry.
+ */
+type Quote = {
+    /** Null prices mean the service could not split the subtotal across lines. */
+    lines: {
+        lineId: string;
+        unitPrice: Money | null;
+        total: Money | null;
+    }[];
+    linesUnpriced?: boolean;
+    subtotal: Money;
+    fees: {
+        code: string;
+        label: string;
+        amount: Money;
+    }[];
+    delivery?: Money;
+    discounts: {
+        code: string;
+        label: string;
+        amount: Money;
+    }[];
+    total: Money;
+    issues: CartIssue[];
+    canCheckout: boolean;
+    checkout: {
+        ready: boolean;
+        reason?: "issues" | "customer_required";
+    };
+    menuVersion: string;
+    expiresAt: string;
+};
+/**
+ * The cart validation and quoting state, with a quote or issues when available.
+ */
+type CartState = {
+    status: "ready";
+} | {
+    status: "quoting";
+} | {
+    status: "quoted";
+    quote: Quote;
+} | {
+    status: "needs_attention";
+    quote?: Quote;
+    issues: readonly CartIssue[];
+};
+/**
+ * The current readonly cart view, including lines, branch, fulfilment and hydration state.
+ */
+type CartSnapshot = {
+    /** Selected branch remains available before a fulfilment mode is chosen. */
+    readonly branchId?: string | undefined;
+    readonly lines: readonly CartLine[];
+    readonly count: number;
+    readonly subtotal: Money | null;
+    readonly fulfilment: CartFulfilment | null;
+    readonly promoCode: string | null;
+    readonly state: CartState;
+    readonly issues: readonly CartIssue[];
+    readonly isHydrated: boolean;
+};
+/**
+ * Cart state and operations for editing lines, quoting, persistence and subscriptions.
+ */
+interface CartModule extends CartSnapshot {
+    validate(input: CartLineInput): {
+        ok: true;
+    } | {
+        ok: false;
+        issues: CartIssue[];
+    };
+    add(item: Item | string, input?: Omit<CartLineInput, "itemId">): CartLine;
+    update(lineId: string, patch: Partial<Omit<CartLineInput, "itemId">>): CartLine;
+    remove(lineId: string): void;
+    clear(): void;
+    setFulfilment(fulfilment: CartFulfilment): void;
+    setPromoCode(code: string | null): void;
+    quote(opts?: {
+        force?: boolean;
+    }): Promise<Quote>;
+    /** Handle interactive fixes by calling the option, address or time setter. */
+    applyFix(issue: CartIssue, fix?: CartFix): void;
+    moveTo(branchId: string): Promise<void>;
+    hydrate(): Promise<void>;
+    /** Attach browser listeners. Use the returned cleanup in your component effect. */
+    mount(): () => void;
+    dispose(): void;
+    subscribe(fn: () => void): () => void;
+    getSnapshot(): CartSnapshot;
+    toCheckoutPayload(): {
+        lines: WireLine[];
+        fulfilment: CartFulfilment;
+        promo_code?: string;
+        menu_version: string;
+    };
+}
+/**
+ * A cart line serialized with API field names for quote and checkout requests.
+ */
+type WireLine = {
+    line_id: string;
+    item_id: string;
+    menu_id?: string;
+    quantity: number;
+    variant_id?: string;
+    options: {
+        group_id: string;
+        choice_id: string;
+        quantity: number;
+    }[];
+    inputs: Record<string, string>;
+    note?: string;
+};
+/**
+ * A fulfilment selection serialized with API field names, without its branch ID.
+ */
+type WireFulfilment = {
+    type: CartFulfilment["type"];
+    scheduled_for?: string;
+    table?: string;
+    address?: {
+        line1: string;
+        line2?: string;
+        city?: string;
+        place_id?: string;
+        lat?: number;
+        lng?: number;
+        instructions?: string;
+    };
+};
+/**
+ * The branch, menu version and cart contents you send for a server quote.
+ */
+type QuoteRequest = {
+    branch_id: string;
+    lines: WireLine[];
+    fulfilment?: WireFulfilment;
+    promo_code?: string;
+    menu_version: string;
+};
+/**
+ * An API monetary amount in minor units with its currency code.
+ */
+type WireMoney = {
+    amount_minor: number;
+    currency: Currency;
+};
+/**
+ * A suggested cart correction in API field names, before conversion to CartFix.
+ */
+type WireFix = {
+    action: CartFix["action"];
+    group_id?: string;
+    next_open_at?: string;
+    quantity?: number;
+    slots?: string[];
+    types?: CartFulfilment["type"][];
+};
+/**
+ * A server cart issue in API field names, before adding its quote source.
+ */
+type WireIssue = Omit<CartIssue, "source" | "lineId" | "groupId" | "fixes"> & {
+    line_id?: string;
+    group_id?: string;
+    fixes: WireFix[];
+};
+/**
+ * The server quote response in API field names, including prices, charges and checkout readiness.
+ */
+type WireQuote = {
+    branch_id: string;
+    menu_version: string;
+    expires_at: string;
+    lines_unpriced?: boolean;
+    lines: {
+        line_id: string;
+        unit_price: WireMoney | null;
+        line_total: WireMoney | null;
+    }[];
+    subtotal: WireMoney;
+    charges: {
+        code: string;
+        label: string;
+        amount: WireMoney;
+    }[];
+    discounts: {
+        code: string;
+        label: string;
+        amount: WireMoney;
+    }[];
+    total: WireMoney;
+    issues: WireIssue[];
+    can_checkout: boolean;
+    checkout: {
+        ready: boolean;
+        reason?: "issues" | "customer_required";
+    };
+};
+/** A saved cart with its scope, revision and expiry. */
+type CartSyncDocument = {
+    schemaVersion: 1;
+    store: string;
+    branchId: string;
+    revision: string;
+    expiresAt: string;
+    lines: WireLine[];
+    fulfilment: CartFulfilment | null;
+    promoCode: string | null;
+};
+/**
+ * A storage adapter for reading cart documents and writing them with revision checks.
+ * Writes return the saved document or the current document when revisions conflict.
+ */
+interface CartSyncAdapter {
+    read(scope: {
+        store: string;
+        branchId: string;
+    }, signal?: AbortSignal): Promise<CartSyncDocument | null>;
+    /** Write if the revision matches. Reuse the operation ID when you retry to avoid applying a change twice. */
+    write(document: Omit<CartSyncDocument, "revision" | "expiresAt">, options: {
+        expectedRevision: string | null;
+        operationId: string;
+        signal?: AbortSignal;
+    }): Promise<{
+        status: "saved";
+        document: CartSyncDocument;
+    } | {
+        status: "conflict";
+        document: CartSyncDocument;
+    }>;
+}
+
+/**
+ * The store, branch, order context and source menu that identify a saved catalogue.
+ */
+type CatalogueScope = {
+    store: string;
+    branchId: string;
+    orderContext: "delivery" | "pickup" | "dineIn";
+    menuId: string;
+};
+/** The saved coverage. A complete source menu still covers only part of the branch. */
+type SavedCatalogue = {
+    scope: CatalogueScope;
+    menu: Menu;
+    coverage: {
+        menuIds: string[];
+        complete: boolean;
+    };
+    pages: {
+        categoryId: string;
+        cursor?: string;
+        page: CategoryPage;
+    }[];
+    etag: string;
+    savedAt: number;
+    /**
+     * The host's catalogue revision when saved. An unchanged revision means the
+     * saved copy is current and needs no background refresh.
+     */
+    revision?: string;
+};
+/**
+ * Default saved-catalogue lifetime in milliseconds: 24 hours.
+ */
+declare const CATALOGUE_MAX_AGE_MS: number;
+/**
+ * Default per-store catalogue storage budget in serialized bytes: 16 MiB.
+ */
+declare const CATALOGUE_MAX_BYTES: number;
+/**
+ * Build a versioned JSON storage key from the store, branch, order context and menu ID.
+ */
+declare function catalogueKey(scope: CatalogueScope): string;
+/** Opt-in browser persistence. Storage failures never escape into shopper UI. */
+declare function createCatalogueStorage(store: string, options?: {
+    maxAgeMs?: number;
+    maxBytes?: number;
+}): {
+    read(scope: CatalogueScope): Promise<SavedCatalogue | undefined>;
+    save(value: SavedCatalogue): void;
+};
+/** Digest excludes transport versions: publication follows shopper-visible content. */
+declare function catalogueDigest(menu: Menu): Promise<string>;
+/** A saved source menu that stays separate from the complete branch catalogue. */
+declare function createSavedCatalogue(client: Zappie, scope: CatalogueScope): {
+    restore(): Promise<SavedCatalogue | undefined>;
+    /** Save in the background and return whether the content changed. */
+    publish(value: SavedCatalogue): Promise<boolean>;
+};
+
+/** Complete for the named source, never complete for the branch. */
+type SelectedMenu = {
+    menu: Menu & {
+        completeness: "partial";
+    };
+    coverage: {
+        menuIds: [string];
+        complete: true;
+    };
+};
+/**
+ * A source menu with its ETag, or an unchanged response carrying the matching ETag.
+ */
+type SelectedMenuResponse = (SelectedMenu & {
+    etag: string;
+}) | {
+    notModified: true;
+    etag: string;
+};
+/**
+ * A branch-scoped source-menu request with order context and an optional conditional ETag.
+ */
+type SelectedMenuRequest = RequestCtx & {
+    branchId: string;
+    menuId: string;
+    orderContext: CatalogueScope["orderContext"];
+    ifNoneMatch?: string;
+};
+/**
+ * A transport that reads one complete source menu without claiming branch-wide coverage.
+ */
+type SelectedMenuTransport = {
+    getSelectedMenu(request: SelectedMenuRequest): Promise<SelectedMenuResponse>;
+};
+/** Dependencies are passed by REST to avoid splitting core shared chunks. */
+declare function selectedMenu(ctx: SelectedMenuRequest, request: (path: string) => Promise<Response>, json: (response: Response) => Promise<unknown>, mapMenu: (value: unknown, branchId: string) => Menu, invalid: () => Error): Promise<SelectedMenuResponse>;
+/**
+ * Build a versioned cache key for a source menu within a store, branch and order context.
+ */
+declare function selectedMenuKey(scope: CatalogueScope): string;
+/** Dedicated lazy resource: deliberately does not call menu.hydrate(). */
+declare function createSelectedMenuReader(client: Zappie): {
+    read(scope: CatalogueScope, options?: {
+        signal?: AbortSignal;
+        ifNoneMatch?: string;
+    }): Promise<SelectedMenuResponse>;
+};
+
+/** Per-request credentials and cancellation. Never shared across clients. */
+type RequestCtx = {
+    key: string;
+    version: string;
+    signal?: AbortSignal;
+    idempotencyKey?: string;
+};
+/** Full menu response or a conditional-cache hit. */
+type MenuResponse = {
+    menu: Menu;
+    etag?: string;
+} | {
+    notModified: true;
+    etag?: string;
+};
+/** Opaque content and availability versions. */
+type MenuVersion = {
+    version: string;
+    availabilityHash: string;
+};
+/** Replaceable read-only backend for the storefront SDK. */
+interface Transport {
+    getSelectedMenu?(ctx: SelectedMenuRequest): Promise<SelectedMenuResponse>;
+    search?(ctx: SearchRequest): Promise<SearchPage>;
+    quote(ctx: RequestCtx, body: QuoteRequest): Promise<WireQuote>;
+    getStore(ctx: RequestCtx): Promise<Store>;
+    getMenu(ctx: RequestCtx & {
+        branchId: string;
+        ifNoneMatch?: string;
+        metadataOnly?: boolean;
+    }): Promise<MenuResponse>;
+    getCategoryPage?(ctx: RequestCtx & {
+        branchId: string;
+        menuId: string;
+        categoryId: string;
+        cursor?: string;
+    }): Promise<CategoryPage>;
+    getMenuVersion(ctx: RequestCtx & {
+        branchId: string;
+    }): Promise<MenuVersion>;
+    getItem(ctx: RequestCtx & {
+        branchId: string;
+        itemId: string;
+    }): Promise<Item>;
+}
+/** Bounded search across eligible source menus in the current order context. */
+type SearchRequest = RequestCtx & {
+    branchId: string;
+    query: string;
+    cursor?: string;
+};
+/** Matching items with their source menus and categories. This is a partial catalogue. */
+type SearchPage = {
+    menu: Menu;
+    nextCursor?: string;
+};
+
+/** Release-pinned REST contract version, independent of the package version. */
+declare const API_VERSION = "2026-10-01";
+/** A storage adapter you can supply to save carts. */
+interface StorageLike {
+    getItem(key: string): string | null;
+    setItem(key: string, value: string): void;
+    removeItem(key: string): void;
+    /** Provide length and key to let the SDK remove expired carts for this store. */
+    readonly length?: number;
+    key?(index: number): string | null;
+}
+/** Settings for your storefront client. Each client keeps its own credentials and caches. */
+type ZappieConfig = {
+    store: string;
+    key: string;
+    branch?: string;
+    transport?: Transport;
+    baseUrl?: string;
+    version?: string;
+    fetch?: typeof fetch;
+    storage?: StorageLike;
+    telemetry?: boolean;
+    cart?: {
+        ttl?: number;
+        storageScope?: string;
+    };
+};
+declare function validateConfig(config: ZappieConfig, secret?: boolean): "test" | "live";
+
+/** Stable public error codes. */
+type ZappieErrorCode = "network_error" | "timeout" | "rate_limited" | "unauthorized" | "forbidden_origin" | "not_found" | "store_not_found" | "branch_not_found" | "item_not_found" | "cart_invalid" | "invalid_request" | "version_unsupported" | "server_error";
+/** Context attached to an SDK failure. */
+type ErrorDetails = {
+    status?: number;
+    param?: string;
+    docUrl?: string;
+    requestId?: string;
+    retryable?: boolean;
+    cause?: unknown;
+};
+/** An SDK error you can handle by its stable code. */
+declare class ZappieError extends Error {
+    readonly code: ZappieErrorCode;
+    readonly status?: number;
+    readonly param?: string;
+    readonly docUrl: string;
+    readonly requestId?: string;
+    readonly retryable: boolean;
+    constructor(code: ZappieErrorCode, message: string, details?: ErrorDetails);
+}
+/** Check whether a thrown value is a ZappieError. */
+declare function isZappieError(error: unknown): error is ZappieError;
+
+type CacheEntry<T> = {
+    value?: T;
+    fetchedAt: number;
+    etag?: string;
+    error?: ZappieError;
+    failedAt?: number;
+    loading: boolean;
+};
+type Loaded<T> = {
+    value: T;
+    etag?: string;
+    onStored?: () => void;
+};
+/** Client-local SWR storage. Subscribers receive stable snapshots until an entry changes. */
+declare class Cache {
+    private onError;
+    private entries;
+    private listeners;
+    private flights;
+    constructor(onError: (error: ZappieError) => void);
+    snapshot<T>(key: string): CacheEntry<T>;
+    subscribe: (fn: () => void) => () => void;
+    private notify;
+    set<T>(key: string, value: T, etag?: string): void;
+    stale(key: string): boolean;
+    get<T>(key: string, loader: (signal: AbortSignal, entry: CacheEntry<T>) => Promise<Loaded<T>>, signal?: AbortSignal): Promise<T>;
+}
+
+/** Events currently emitted by the read-only SDK. */
+type ZappieEvents = {
+    search: {
+        query: string;
+        resultCount: number;
+    };
+    warning: {
+        message: string;
+    };
+    cart_expired: {
+        branchId: string;
+    };
+    add_to_cart: {
+        itemId: string;
+        quantity: number;
+        value: Money;
+    };
+    remove_from_cart: {
+        itemId: string;
+        quantity: number;
+        value: Money;
+    };
+    update_cart_line: {
+        lineId: string;
+        itemId: string;
+        quantity: number;
+    };
+    view_cart: Record<string, never>;
+    cart_issue: {
+        code: CartIssueCode;
+    };
+    quote_failed: {
+        code: string;
+    };
+    "menu:updated": {
+        branchId: string;
+        version: string;
+    };
+    error: {
+        error: ZappieError;
+    };
+};
+
+/** Optional branch selection and cancellation for resource reads. */
+type ReadOptions = {
+    branch?: string;
+    signal?: AbortSignal;
+};
+/** Read-only store resource. */
+interface StoreResource {
+    get(opts?: {
+        signal?: AbortSignal;
+    }): Promise<Store>;
+    peek(): Store | undefined;
+}
+/** Read-only branch catalogue and item resources. */
+interface MenuResource {
+    search(query: string, opts?: ReadOptions & {
+        cursor?: string;
+    }): Promise<SearchPage>;
+    get(opts?: ReadOptions & {
+        metadataOnly?: boolean;
+    }): Promise<Menu>;
+    page(menuId: string, categoryId: string, opts?: ReadOptions & {
+        cursor?: string;
+    }): Promise<CategoryPage>;
+    peek(branch?: string): Menu | undefined;
+    version(opts?: ReadOptions): Promise<MenuVersion>;
+    item(id: string, opts?: ReadOptions): Promise<Item>;
+    hydrate(menu: Menu): void;
+}
+/** A storefront client and its isolated resource state. */
+type Zappie = ReturnType<typeof buildClient>;
+declare function buildClient(input: ZappieConfig, secret?: boolean): Readonly<{
+    cart: Readonly<CartModule>;
+    config: Readonly<{
+        version: string;
+        telemetry: boolean;
+        store: string;
+        key: string;
+        branch?: string;
+        transport?: Transport;
+        baseUrl?: string;
+        fetch?: typeof fetch;
+        storage?: StorageLike;
+        cart?: {
+            ttl?: number;
+            storageScope?: string;
+        };
+    }>;
+    mode: "test" | "live";
+    store: StoreResource;
+    menu: MenuResource;
+    format: Formatters;
+    on: <E extends keyof ZappieEvents>(event: E, fn: (payload: ZappieEvents[E]) => void) => () => void;
+    _internal: {
+        cartCatalogue: () => Menu | undefined;
+        setLegacyReader: (reader: NonNullable<((read: (key: string) => string | null) => CartLineInput[]) | undefined>) => void;
+        transport: Transport;
+        cache: Cache;
+        emit: <E extends keyof ZappieEvents>(event: E, payload: ZappieEvents[E]) => void;
+        menuKey: (requested?: string) => string;
+        hydrateStore: (value: Store) => void;
+    };
+}>;
+/** Create a client with your publishable key. Requests start when you read a resource. */
+declare function createZappie(config: ZappieConfig): Readonly<{
+    cart: Readonly<CartModule>;
+    config: Readonly<{
+        version: string;
+        telemetry: boolean;
+        store: string;
+        key: string;
+        branch?: string;
+        transport?: Transport;
+        baseUrl?: string;
+        fetch?: typeof fetch;
+        storage?: StorageLike;
+        cart?: {
+            ttl?: number;
+            storageScope?: string;
+        };
+    }>;
+    mode: "test" | "live";
+    store: StoreResource;
+    menu: MenuResource;
+    format: Formatters;
+    on: <E extends keyof ZappieEvents>(event: E, fn: (payload: ZappieEvents[E]) => void) => () => void;
+    _internal: {
+        cartCatalogue: () => Menu | undefined;
+        setLegacyReader: (reader: NonNullable<((read: (key: string) => string | null) => CartLineInput[]) | undefined>) => void;
+        transport: Transport;
+        cache: Cache;
+        emit: <E extends keyof ZappieEvents>(event: E, payload: ZappieEvents[E]) => void;
+        menuKey: (requested?: string) => string;
+        hydrateStore: (value: Store) => void;
+    };
+}>;
+
+export { createSelectedMenuReader as $, API_VERSION as A, type WireFix as B, type CartLineInput as C, type DeliveryAddress as D, type ErrorDetails as E, type WireIssue as F, type WireLine as G, type WireMoney as H, createZappie as I, isZappieError as J, CATALOGUE_MAX_AGE_MS as K, CATALOGUE_MAX_BYTES as L, type MenuResource as M, type CatalogueScope as N, type SavedCatalogue as O, catalogueDigest as P, type QuoteRequest as Q, type RequestCtx as R, type StorageLike as S, type Transport as T, catalogueKey as U, createCatalogueStorage as V, type WireFulfilment as W, createSavedCatalogue as X, type SelectedMenu as Y, type Zappie as Z, type SelectedMenuTransport as _, type Quote as a, selectedMenu as a0, selectedMenuKey as a1, type CartFulfilment as b, ZappieError as c, type CartModule as d, type CartLine as e, type CartState as f, type CartIssue as g, type ZappieConfig as h, type StoreResource as i, type ZappieEvents as j, Cache as k, type ZappieErrorCode as l, type WireQuote as m, type MenuResponse as n, type SelectedMenuRequest as o, type SelectedMenuResponse as p, type SearchRequest as q, type SearchPage as r, type MenuVersion as s, type CartFix as t, type CartIssueCode as u, validateConfig as v, type CartSnapshot as w, type CartSyncAdapter as x, type CartSyncDocument as y, type ReadOptions as z };