@zappie/sdk 0.1.4 → 0.1.6

package/dist/types-CuDvfW9g.d.ts

@@ -0,0 +1,380 @@
+import { d as Currency, M as Money, I as Item } from './models-Rg5kQUkv.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;
+    /** The delivery region you selected from the branch. */
+    deliveryRegionId?: string;
+    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" | "choose_region";
+} | {
+    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;
+        /** Item identity echoed by the quote. */
+        itemId?: string;
+        /** Item name returned by the quote. */
+        name?: string;
+        /** Quantity priced by the quote. */
+        quantity?: number;
+        /** Authoritative option total, or null when the line could not be priced. */
+        optionsTotal?: Money | null;
+        /** Line status returned by the service. */
+        status?: string;
+    }[];
+    /** Whether the submitted menu version differs from the current version. */
+    menuVersionStale?: boolean;
+    /** Fulfilment details and arrival estimate returned by the service. */
+    fulfilment?: {
+        type: string;
+        scheduledFor: string | null;
+        etaMinutes?: number[];
+        deliveryRegionId?: string;
+    };
+    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 = {
+    /** Selected delivery region in API field names. */
+    delivery_region_id?: string;
+    /** Delivery instructions sent alongside the address. */
+    instructions?: string;
+    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 = {
+    /** Whether the submitted menu version is stale. */
+    menu_version_stale?: boolean;
+    /** Fulfilment details returned by the quote service. */
+    fulfilment?: {
+        type: string;
+        scheduled_for: string | null;
+        eta_minutes?: number[];
+        delivery_region_id?: string;
+    };
+    branch_id: string;
+    menu_version: string;
+    expires_at: string;
+    lines_unpriced?: boolean;
+    lines: {
+        line_id: string;
+        item_id?: string;
+        name?: string;
+        quantity?: number;
+        options_total?: WireMoney | null;
+        status?: 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;
+    }>;
+}
+
+export type { CartLine as C, DeliveryAddress as D, QuoteRequest as Q, WireFulfilment as W, Quote as a, CartLineInput as b, CartFulfilment as c, CartModule as d, CartState as e, CartIssue as f, WireQuote as g, CartFix as h, CartIssueCode as i, CartSnapshot as j, CartSyncAdapter as k, CartSyncDocument as l, WireFix as m, WireIssue as n, WireLine as o, WireMoney as p };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zappie/sdk",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Typed, framework-agnostic client for Zappie menus, carts, checkout, auth and events.",
   "type": "module",
   "sideEffects": false,
@@ -37,6 +37,10 @@
       "types": "./dist/cart/item.d.ts",
       "import": "./dist/cart/item.js"
     },
+    "./cart/branch": {
+      "types": "./dist/cart/branch.d.ts",
+      "import": "./dist/cart/branch.js"
+    },
     "./checkout": {
       "types": "./dist/checkout/index.d.ts",
       "import": "./dist/checkout/index.js"