@doswiftly/storefront-sdk 14.0.0 → 15.1.0

package/dist/core/operations/cart.d.ts

@@ -12,12 +12,42 @@
  * Drift detection: PreToolUse hook validuje strings przeciwko storefront-operations/schema.graphql.
  */
 export declare const CART_QUERY: string;
+/**
+ * cartAvailableShippingMethods — cart-aware shipping discovery for the
+ * checkout shipping step. Backend uses the cart's contents (subtotal,
+ * physical-item weight) and surfaces a `DIGITAL_ONLY_NO_SHIPPING` userError
+ * when the cart has no shippable items. Each method carries `deliveryType`
+ * so the storefront can render a pickup-point / locker picker without
+ * inferring the type from the method name.
+ */
+export declare const CART_AVAILABLE_SHIPPING_METHODS_QUERY: string;
+/**
+ * availablePaymentMethods — shop-level list of active payment methods
+ * (default + sorted by merchant position). Independent of cart contents
+ * today; storefront fetches once for the checkout payment step.
+ */
+export declare const AVAILABLE_PAYMENT_METHODS_QUERY: string;
+/**
+ * orderByToken — guest order lookup by opaque access token (returned by
+ * `cartComplete.order.accessToken`). Optional `email` adds defense-in-depth:
+ * if supplied it must match the order's buyer email case-insensitively, else
+ * the query returns `null` (same shape as an invalid token). Rate-limited by
+ * the backend (5/min per IP+shop); no cache (`Cache-Control: no-store`).
+ */
+export declare const ORDER_BY_TOKEN_QUERY: string;
 export declare const CART_CREATE: string;
 export declare const CART_ADD_LINES: string;
 export declare const CART_UPDATE_LINES: string;
 export declare const CART_REMOVE_LINES: string;
 export declare const CART_DISCOUNT_CODES_UPDATE: string;
 export declare const CART_UPDATE_NOTE: string;
+/**
+ * cartUpdateAttributes — replaces (NOT merges) the cart's custom `[{ key, value }]`
+ * attribute pairs. Free-form metadata visible to the merchant in admin: delivery
+ * instructions, gift-wrap flags, B2B PO numbers. Backend limit: 250 pairs / 255-char
+ * keys (rejected with `CART_ATTRIBUTES_LIMIT_EXCEEDED` userError).
+ */
+export declare const CART_UPDATE_ATTRIBUTES: string;
 export declare const CART_UPDATE_BUYER_IDENTITY: string;
 export declare const CART_SET_SHIPPING_ADDRESS: string;
 export declare const CART_SET_BILLING_ADDRESS: string;

package/dist/core/operations/cart.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cart.d.ts","sourceRoot":"","sources":["../../../src/core/operations/cart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAsSH,eAAO,MAAM,UAAU,QAOrB,CAAC;AAMH,eAAO,MAAM,WAAW,QAWtB,CAAC;AAEH,eAAO,MAAM,cAAc,QAWzB,CAAC;AAEH,eAAO,MAAM,iBAAiB,QAW5B,CAAC;AAEH,eAAO,MAAM,iBAAiB,QAW5B,CAAC;AAEH,eAAO,MAAM,0BAA0B,QAWrC,CAAC;AAEH,eAAO,MAAM,gBAAgB,QAW3B,CAAC;AAEH,eAAO,MAAM,0BAA0B,QAWrC,CAAC;AAMH,eAAO,MAAM,yBAAyB,QAWpC,CAAC;AAEH,eAAO,MAAM,wBAAwB,QAWnC,CAAC;AAEH,eAAO,MAAM,2BAA2B,QAWtC,CAAC;AAEH,eAAO,MAAM,0BAA0B,QAWrC,CAAC;AAEH,eAAO,MAAM,oBAAoB,QAW/B,CAAC;AAEH,eAAO,MAAM,qBAAqB,QAWhC,CAAC;AAEH,eAAO,MAAM,+BAA+B,QAW1C,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,QAWxB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QASzB,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,QAoBtC,CAAC"}
+{"version":3,"file":"cart.d.ts","sourceRoot":"","sources":["../../../src/core/operations/cart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA0XH,eAAO,MAAM,UAAU,QAOrB,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,qCAAqC,QAehD,CAAC;AAEH;;;;GAIG;AACH,eAAO,MAAM,+BAA+B,QAO1C,CAAC;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,QAO/B,CAAC;AAMH,eAAO,MAAM,WAAW,QAWtB,CAAC;AAEH,eAAO,MAAM,cAAc,QAWzB,CAAC;AAEH,eAAO,MAAM,iBAAiB,QAW5B,CAAC;AAEH,eAAO,MAAM,iBAAiB,QAW5B,CAAC;AAEH,eAAO,MAAM,0BAA0B,QAWrC,CAAC;AAEH,eAAO,MAAM,gBAAgB,QAW3B,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,QAWjC,CAAC;AAEH,eAAO,MAAM,0BAA0B,QAWrC,CAAC;AAMH,eAAO,MAAM,yBAAyB,QAWpC,CAAC;AAEH,eAAO,MAAM,wBAAwB,QAWnC,CAAC;AAEH,eAAO,MAAM,2BAA2B,QAWtC,CAAC;AAEH,eAAO,MAAM,0BAA0B,QAWrC,CAAC;AAEH,eAAO,MAAM,oBAAoB,QAW/B,CAAC;AAEH,eAAO,MAAM,qBAAqB,QAWhC,CAAC;AAEH,eAAO,MAAM,+BAA+B,QAW1C,CAAC;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,QAWxB,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,cAAc,QASzB,CAAC;AAEH;;;;;;;GAOG;AACH,eAAO,MAAM,2BAA2B,QAoBtC,CAAC"}

package/dist/core/operations/cart.js

@@ -138,6 +138,14 @@ const CART_DISCOUNT_ALLOCATION_FRAGMENT = `
     amount { ...Money }
   }
 `;
+const PICKUP_POINT_FRAGMENT = `
+  fragment PickupPoint on PickupPoint {
+    provider
+    pointId
+    name
+    address
+  }
+`;
 const MAILING_ADDRESS_FRAGMENT = `
   fragment MailingAddress on MailingAddress {
     id
@@ -155,7 +163,11 @@ const MAILING_ADDRESS_FRAGMENT = `
     postalCode
     phone
     isDefault
+    taxId
+    vatNumber
+    pickupPoint { ...PickupPoint }
   }
+  ${PICKUP_POINT_FRAGMENT}
 `;
 const CART_SHIPPING_METHOD_FRAGMENT = `
   fragment CartShippingMethod on CartShippingMethod {
@@ -166,6 +178,7 @@ const CART_SHIPPING_METHOD_FRAGMENT = `
 `;
 const CART_APPLIED_GIFT_CARD_FRAGMENT = `
   fragment CartAppliedGiftCard on CartAppliedGiftCard {
+    id
     maskedCode
     lastCharacters
     appliedAmount { ...Money }
@@ -263,6 +276,70 @@ const CART_WARNING_FRAGMENT = `
     target
   }
 `;
+const SHIPPING_CARRIER_FRAGMENT = `
+  fragment ShippingCarrier on ShippingCarrier {
+    id
+    name
+    logoUrl
+    serviceCode
+  }
+`;
+const DELIVERY_ESTIMATE_FRAGMENT = `
+  fragment DeliveryEstimate on DeliveryEstimate {
+    minDays
+    maxDays
+    description
+  }
+`;
+const FREE_SHIPPING_PROGRESS_FRAGMENT = `
+  fragment FreeShippingProgress on FreeShippingProgress {
+    qualifies
+    currentAmount { ...Money }
+    threshold { ...Money }
+    remaining { ...Money }
+    progressPercent
+    message
+  }
+  ${MONEY_FRAGMENT}
+`;
+const AVAILABLE_SHIPPING_METHOD_FRAGMENT = `
+  fragment AvailableShippingMethod on AvailableShippingMethod {
+    id
+    name
+    description
+    deliveryType
+    carrier { ...ShippingCarrier }
+    price { ...Money }
+    isFree
+    estimatedDelivery { ...DeliveryEstimate }
+    freeShippingProgress { ...FreeShippingProgress }
+    sortOrder
+  }
+  ${SHIPPING_CARRIER_FRAGMENT}
+  ${MONEY_FRAGMENT}
+  ${DELIVERY_ESTIMATE_FRAGMENT}
+  ${FREE_SHIPPING_PROGRESS_FRAGMENT}
+`;
+const PAYMENT_METHOD_FRAGMENT = `
+  fragment PaymentMethod on PaymentMethod {
+    id
+    name
+    provider
+    type
+    icon
+    description
+    isDefault
+    supportedCurrencies
+    position
+  }
+`;
+const AVAILABLE_PAYMENT_METHODS_FRAGMENT = `
+  fragment AvailablePaymentMethods on AvailablePaymentMethods {
+    methods { ...PaymentMethod }
+    defaultMethod { ...PaymentMethod }
+  }
+  ${PAYMENT_METHOD_FRAGMENT}
+`;
 const PAYMENT_SESSION_FRAGMENT = `
   fragment PaymentSession on PaymentSession {
     id
@@ -286,6 +363,58 @@ export const CART_QUERY = composeOperation(`
   }
   ${CART_FRAGMENT}
 `);
+/**
+ * cartAvailableShippingMethods — cart-aware shipping discovery for the
+ * checkout shipping step. Backend uses the cart's contents (subtotal,
+ * physical-item weight) and surfaces a `DIGITAL_ONLY_NO_SHIPPING` userError
+ * when the cart has no shippable items. Each method carries `deliveryType`
+ * so the storefront can render a pickup-point / locker picker without
+ * inferring the type from the method name.
+ */
+export const CART_AVAILABLE_SHIPPING_METHODS_QUERY = composeOperation(`
+  query CartAvailableShippingMethods($cartId: ID!, $address: ShippingAddressInput!) {
+    cart(id: $cartId) {
+      id
+      requiresShipping
+      availableShippingMethods(address: $address) {
+        methods { ...AvailableShippingMethod }
+        freeShippingProgress { ...FreeShippingProgress }
+        userErrors { ...UserError }
+      }
+    }
+  }
+  ${AVAILABLE_SHIPPING_METHOD_FRAGMENT}
+  ${FREE_SHIPPING_PROGRESS_FRAGMENT}
+  ${USER_ERROR_FRAGMENT}
+`);
+/**
+ * availablePaymentMethods — shop-level list of active payment methods
+ * (default + sorted by merchant position). Independent of cart contents
+ * today; storefront fetches once for the checkout payment step.
+ */
+export const AVAILABLE_PAYMENT_METHODS_QUERY = composeOperation(`
+  query AvailablePaymentMethods {
+    availablePaymentMethods {
+      ...AvailablePaymentMethods
+    }
+  }
+  ${AVAILABLE_PAYMENT_METHODS_FRAGMENT}
+`);
+/**
+ * orderByToken — guest order lookup by opaque access token (returned by
+ * `cartComplete.order.accessToken`). Optional `email` adds defense-in-depth:
+ * if supplied it must match the order's buyer email case-insensitively, else
+ * the query returns `null` (same shape as an invalid token). Rate-limited by
+ * the backend (5/min per IP+shop); no cache (`Cache-Control: no-store`).
+ */
+export const ORDER_BY_TOKEN_QUERY = composeOperation(`
+  query OrderByToken($token: String!, $email: String) {
+    orderByToken(token: $token, email: $email) {
+      ...Order
+    }
+  }
+  ${ORDER_FRAGMENT}
+`);
 // ---------------------------------------------------------------------------
 // Mutations
 // ---------------------------------------------------------------------------
@@ -361,6 +490,24 @@ export const CART_UPDATE_NOTE = composeOperation(`
   ${USER_ERROR_FRAGMENT}
   ${CART_WARNING_FRAGMENT}
 `);
+/**
+ * cartUpdateAttributes — replaces (NOT merges) the cart's custom `[{ key, value }]`
+ * attribute pairs. Free-form metadata visible to the merchant in admin: delivery
+ * instructions, gift-wrap flags, B2B PO numbers. Backend limit: 250 pairs / 255-char
+ * keys (rejected with `CART_ATTRIBUTES_LIMIT_EXCEEDED` userError).
+ */
+export const CART_UPDATE_ATTRIBUTES = composeOperation(`
+  mutation CartUpdateAttributes($id: ID!, $attributes: [CartAttributeInput!]!) {
+    cartUpdateAttributes(id: $id, attributes: $attributes) {
+      cart { ...Cart }
+      userErrors { ...UserError }
+      warnings { ...CartWarning }
+    }
+  }
+  ${CART_FRAGMENT}
+  ${USER_ERROR_FRAGMENT}
+  ${CART_WARNING_FRAGMENT}
+`);
 export const CART_UPDATE_BUYER_IDENTITY = composeOperation(`
   mutation CartUpdateBuyerIdentity($id: ID!, $buyerIdentity: CartBuyerIdentityInput!) {
     cartUpdateBuyerIdentity(id: $id, buyerIdentity: $buyerIdentity) {

package/dist/react/hooks/use-cart.d.ts

@@ -0,0 +1,78 @@
+/**
+ * useCart — server-driven cart hook bound to an explicit `cartId`.
+ *
+ * Sister of {@link useCartManager}: same `CartClient` actions, different
+ * lifecycle. `useCartManager` reads the cart id from the `cart-id` cookie and
+ * runs auto-recovery on stale carts (cookie-first flow — browser-rendered
+ * storefront). `useCart` takes the cart id as a prop and never touches the
+ * cookie, which is what SSR, deep-link recovery, and admin "view this cart"
+ * UIs need.
+ *
+ * State management follows the platform's store pattern: a vanilla Zustand
+ * store is created per hook mount via `useMemo` (component-scoped, no
+ * module-level singleton — Inv-3 of the SDK), and React subscribes through
+ * `useStore`. Changing `cartId` recreates the store; refetches are explicit
+ * (`refetch()` or any mutation triggers one).
+ *
+ * @example
+ * ```tsx
+ * // Server component / route handler hands the cartId to the client tree.
+ * function CheckoutPage({ cartId }: { cartId: string }) {
+ *   const { cart, isLoading, error, addItems, updateAttributes } = useCart(cartId);
+ *
+ *   if (isLoading) return <Spinner />;
+ *   if (error) return <ErrorBanner error={error} />;
+ *   if (!cart) return null;
+ *
+ *   return <CheckoutForm cart={cart} onAdd={addItems} onAttrs={updateAttributes} />;
+ * }
+ * ```
+ */
+import type { CartMutationOutcome } from '../../core/cart/cart-client';
+import type { Cart, CartAddressInput, CartAttributeInput, CartBuyerIdentityInput, CartLineInput, CartLineUpdateInput } from '../../core/cart/types';
+/** Names of mutations exposed by the hook — useful for telemetry / spinners. */
+export type ServerCartOperation = 'fetch' | 'addItems' | 'updateItems' | 'removeItems' | 'updateBuyerIdentity' | 'setShippingAddress' | 'updateDiscountCodes' | 'updateNote' | 'updateAttributes';
+export interface UseCartOptions {
+    /**
+     * Fetch the cart automatically when the hook mounts. Set to `false` when the
+     * server has already pre-rendered the cart and you want to seed the store
+     * instead of double-fetching. Default `true`.
+     */
+    autoFetch?: boolean;
+    /**
+     * Pre-loaded cart used as the initial store value — e.g. the cart already
+     * resolved on the server during SSR. Combine with `autoFetch: false` to avoid
+     * a duplicate round-trip on hydration.
+     */
+    initialCart?: Cart | null;
+}
+export interface UseCartResult {
+    /** Currently loaded cart, or null before the first fetch / when not found. */
+    cart: Cart | null;
+    /** True while any operation (fetch or mutation) is in flight. */
+    isLoading: boolean;
+    /** Last error from any operation, or null. */
+    error: Error | null;
+    /** Which operation produced the current `isLoading` / `error`, if any. */
+    operation: ServerCartOperation | null;
+    /** Re-fetch the cart from the backend. Resolves with the fresh cart or null. */
+    refetch: () => Promise<Cart | null>;
+    /** Append line items to the cart. Resolves with `{ cart, warnings }`. */
+    addItems: (lines: CartLineInput[]) => Promise<CartMutationOutcome>;
+    /** Update line items (quantity, attributes) by their line IDs. */
+    updateItems: (lines: CartLineUpdateInput[]) => Promise<CartMutationOutcome>;
+    /** Remove line items by their line IDs. */
+    removeItems: (lineIds: string[]) => Promise<CartMutationOutcome>;
+    /** Update buyer identity (email, phone, country, customer link, language). */
+    updateBuyerIdentity: (buyerIdentity: CartBuyerIdentityInput) => Promise<CartMutationOutcome>;
+    /** Set the shipping address (full replace). */
+    setShippingAddress: (address: CartAddressInput) => Promise<CartMutationOutcome>;
+    /** Apply discount codes (replace-all — pass `[]` to clear). */
+    updateDiscountCodes: (codes: string[]) => Promise<CartMutationOutcome>;
+    /** Update the cart note / gift message. */
+    updateNote: (note: string) => Promise<CartMutationOutcome>;
+    /** Replace the cart's custom `{ key, value }` attribute pairs. */
+    updateAttributes: (attributes: CartAttributeInput[]) => Promise<CartMutationOutcome>;
+}
+export declare function useCart(cartId: string, options?: UseCartOptions): UseCartResult;
+//# sourceMappingURL=use-cart.d.ts.map

package/dist/react/hooks/use-cart.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-cart.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/use-cart.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AASH,OAAO,KAAK,EAAc,mBAAmB,EAAE,MAAM,6BAA6B,CAAC;AACnF,OAAO,KAAK,EACV,IAAI,EACJ,gBAAgB,EAChB,kBAAkB,EAClB,sBAAsB,EACtB,aAAa,EACb,mBAAmB,EACpB,MAAM,uBAAuB,CAAC;AAM/B,gFAAgF;AAChF,MAAM,MAAM,mBAAmB,GAC3B,OAAO,GACP,UAAU,GACV,aAAa,GACb,aAAa,GACb,qBAAqB,GACrB,oBAAoB,GACpB,qBAAqB,GACrB,YAAY,GACZ,kBAAkB,CAAC;AAEvB,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;OAIG;IACH,WAAW,CAAC,EAAE,IAAI,GAAG,IAAI,CAAC;CAC3B;AAED,MAAM,WAAW,aAAa;IAC5B,8EAA8E;IAC9E,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;IAClB,iEAAiE;IACjE,SAAS,EAAE,OAAO,CAAC;IACnB,8CAA8C;IAC9C,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpB,0EAA0E;IAC1E,SAAS,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAEtC,gFAAgF;IAChF,OAAO,EAAE,MAAM,OAAO,CAAC,IAAI,GAAG,IAAI,CAAC,CAAC;IACpC,yEAAyE;IACzE,QAAQ,EAAE,CAAC,KAAK,EAAE,aAAa,EAAE,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACnE,kEAAkE;IAClE,WAAW,EAAE,CAAC,KAAK,EAAE,mBAAmB,EAAE,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC5E,2CAA2C;IAC3C,WAAW,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACjE,8EAA8E;IAC9E,mBAAmB,EAAE,CAAC,aAAa,EAAE,sBAAsB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC7F,+CAA+C;IAC/C,kBAAkB,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAChF,+DAA+D;IAC/D,mBAAmB,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACvE,2CAA2C;IAC3C,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAC3D,kEAAkE;IAClE,gBAAgB,EAAE,CAAC,UAAU,EAAE,kBAAkB,EAAE,KAAK,OAAO,CAAC,mBAAmB,CAAC,CAAC;CACtF;AAoFD,wBAAgB,OAAO,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,GAAE,cAAmB,GAAG,aAAa,CA4CnF"}

package/dist/react/hooks/use-cart.js

@@ -0,0 +1,121 @@
+/**
+ * useCart — server-driven cart hook bound to an explicit `cartId`.
+ *
+ * Sister of {@link useCartManager}: same `CartClient` actions, different
+ * lifecycle. `useCartManager` reads the cart id from the `cart-id` cookie and
+ * runs auto-recovery on stale carts (cookie-first flow — browser-rendered
+ * storefront). `useCart` takes the cart id as a prop and never touches the
+ * cookie, which is what SSR, deep-link recovery, and admin "view this cart"
+ * UIs need.
+ *
+ * State management follows the platform's store pattern: a vanilla Zustand
+ * store is created per hook mount via `useMemo` (component-scoped, no
+ * module-level singleton — Inv-3 of the SDK), and React subscribes through
+ * `useStore`. Changing `cartId` recreates the store; refetches are explicit
+ * (`refetch()` or any mutation triggers one).
+ *
+ * @example
+ * ```tsx
+ * // Server component / route handler hands the cartId to the client tree.
+ * function CheckoutPage({ cartId }: { cartId: string }) {
+ *   const { cart, isLoading, error, addItems, updateAttributes } = useCart(cartId);
+ *
+ *   if (isLoading) return <Spinner />;
+ *   if (error) return <ErrorBanner error={error} />;
+ *   if (!cart) return null;
+ *
+ *   return <CheckoutForm cart={cart} onAdd={addItems} onAttrs={updateAttributes} />;
+ * }
+ * ```
+ */
+'use client';
+import { useEffect, useMemo } from 'react';
+import { createStore } from 'zustand/vanilla';
+import { useStore } from 'zustand';
+import { useStorefrontClientContext } from '../providers/storefront-client-provider';
+function createServerCartStore(opts) {
+    const { cartClient, cartId, initialCart } = opts;
+    const store = createStore(() => ({
+        cart: initialCart ?? null,
+        isLoading: false,
+        error: null,
+        operation: null,
+    }));
+    async function run(operation, exec) {
+        store.setState({ isLoading: true, error: null, operation });
+        try {
+            const result = await exec();
+            store.setState({ isLoading: false, error: null, operation: null });
+            return result;
+        }
+        catch (err) {
+            const error = err instanceof Error ? err : new Error(String(err));
+            store.setState({ isLoading: false, error, operation });
+            throw err;
+        }
+    }
+    async function runMutation(operation, exec) {
+        const outcome = await run(operation, exec);
+        store.setState({ cart: outcome.cart });
+        return outcome;
+    }
+    return {
+        store,
+        async refetch() {
+            const cart = await run('fetch', () => cartClient.get(cartId));
+            store.setState({ cart });
+            return cart;
+        },
+        addItems: (lines) => runMutation('addItems', () => cartClient.addItems(cartId, lines)),
+        updateItems: (lines) => runMutation('updateItems', () => cartClient.updateItems(cartId, lines)),
+        removeItems: (lineIds) => runMutation('removeItems', () => cartClient.removeItems(cartId, lineIds)),
+        updateBuyerIdentity: (buyerIdentity) => runMutation('updateBuyerIdentity', () => cartClient.updateBuyerIdentity(cartId, buyerIdentity)),
+        setShippingAddress: (address) => runMutation('setShippingAddress', () => cartClient.setShippingAddress({ cartId, address })),
+        updateDiscountCodes: (codes) => runMutation('updateDiscountCodes', () => cartClient.updateDiscountCodes(cartId, codes)),
+        updateNote: (note) => runMutation('updateNote', () => cartClient.updateNote(cartId, note)),
+        updateAttributes: (attributes) => runMutation('updateAttributes', () => cartClient.updateAttributes(cartId, attributes)),
+    };
+}
+// ---------------------------------------------------------------------------
+// Hook
+// ---------------------------------------------------------------------------
+export function useCart(cartId, options = {}) {
+    const { cartClient } = useStorefrontClientContext();
+    const { autoFetch = true, initialCart } = options;
+    // Recreate the store when `cartId` or the underlying client changes. The
+    // useMemo dependency list captures store identity (component-scoped, not
+    // module-level — Inv-3). Mutations capture the store instance for stable
+    // references via the api object.
+    const api = useMemo(() => createServerCartStore({ cartClient, cartId, initialCart }), 
+    // initialCart deliberately excluded — it only seeds the FIRST mount; we do
+    // not want to reset the store when the parent re-renders with a stale
+    // server snapshot.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [cartClient, cartId]);
+    const state = useStore(api.store);
+    // Initial fetch — runs once per (cartId, cartClient) pair when autoFetch is
+    // enabled. Catches and stores any error via the runner; the caller observes
+    // it through `error` rather than an unhandled promise.
+    useEffect(() => {
+        if (!autoFetch)
+            return;
+        api.refetch().catch(() => {
+            // already captured in store state via the runner
+        });
+    }, [api, autoFetch]);
+    return {
+        cart: state.cart,
+        isLoading: state.isLoading,
+        error: state.error,
+        operation: state.operation,
+        refetch: api.refetch,
+        addItems: api.addItems,
+        updateItems: api.updateItems,
+        removeItems: api.removeItems,
+        updateBuyerIdentity: api.updateBuyerIdentity,
+        setShippingAddress: api.setShippingAddress,
+        updateDiscountCodes: api.updateDiscountCodes,
+        updateNote: api.updateNote,
+        updateAttributes: api.updateAttributes,
+    };
+}

package/dist/react/index.d.ts

@@ -20,6 +20,7 @@ export { useLogin, type UseLoginOptions, type UseLoginReturn } from './hooks/use
 export { useLogout, type UseLogoutOptions, type UseLogoutReturn } from './hooks/use-logout';
 export { useRefreshToken, type UseRefreshTokenOptions, type UseRefreshTokenReturn } from './hooks/use-refresh-token';
 export { useCartManager, type CartManagerOperation, type CartManagerStatus, type UseCartManagerResult } from './hooks/use-cart-manager';
+export { useCart, type UseCartOptions, type UseCartResult, type ServerCartOperation } from './hooks/use-cart';
 export { useStorefrontClient } from './hooks/use-storefront-client';
 export { useCurrency } from './hooks/use-currency';
 export { useAuthStore, useAuthStoreApi, useAuthHydrated } from './stores/store-context';

package/dist/react/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/react/index.ts"],"names":[],"mappings":"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"}

package/dist/react/index.js

@@ -22,6 +22,7 @@ export { useLogin } from './hooks/use-login';
 export { useLogout } from './hooks/use-logout';
 export { useRefreshToken } from './hooks/use-refresh-token';
 export { useCartManager } from './hooks/use-cart-manager';
+export { useCart } from './hooks/use-cart';
 export { useStorefrontClient } from './hooks/use-storefront-client';
 export { useCurrency } from './hooks/use-currency';
 // Store hooks (Context-based)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@doswiftly/storefront-sdk",
-  "version": "14.0.0",
+  "version": "15.1.0",
   "description": "Storefront runtime SDK for DoSwiftly Commerce — layered transport, middleware pipeline, React providers, Zustand stores, cache strategies. 0 runtime dependencies in core.",
   "type": "module",
   "sideEffects": false,
@@ -41,16 +41,21 @@
   "author": "DoSwiftly Team",
   "license": "MIT",
   "devDependencies": {
+    "@graphql-codegen/cli": "^5.0.0",
+    "@graphql-codegen/typescript": "^4.0.0",
+    "@graphql-codegen/typescript-operations": "^4.0.0",
     "@testing-library/react": "^16.1.0",
     "@types/node": "^22.10.2",
     "@types/react": "^18.3.0 || ^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitest/coverage-v8": "^4.1.0",
     "fast-check": "^3.23.2",
+    "graphql": "^16.13.2",
     "jsdom": "^25.0.1",
     "next": "^16.2.3",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
+    "tsx": "^4.0.0",
     "typescript": "^5.7.2",
     "vitest": "^4.1.0",
     "zustand": "^5.0.2"
@@ -70,6 +75,7 @@
   "scripts": {
     "build": "tsc",
     "build:only": "tsc",
+    "codegen": "tsx scripts/codegen.mts",
     "dev": "tsc --watch",
     "clean": "rm -rf dist",
     "test": "vitest run",