@doswiftly/storefront-sdk 14.0.0 → 16.0.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;AAqYH,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

@@ -74,6 +74,8 @@ const CART_COST_FRAGMENT = `
     totalTax { ...Money }
     totalDuty { ...Money }
     checkoutCharge { ...Money }
+    totalDiscount { ...Money }
+    totalShipping { ...Money }
   }
 `;
 const CART_LINE_COST_FRAGMENT = `
@@ -138,6 +140,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 +165,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 +180,7 @@ const CART_SHIPPING_METHOD_FRAGMENT = `
 `;
 const CART_APPLIED_GIFT_CARD_FRAGMENT = `
   fragment CartAppliedGiftCard on CartAppliedGiftCard {
+    id
     maskedCode
     lastCharacters
     appliedAmount { ...Money }
@@ -211,6 +226,15 @@ const CART_FRAGMENT = `
     requiresShipping
     createdAt
     updatedAt
+    status
+    completedOrder {
+      id
+      orderNumber
+      accessToken
+      status
+      paymentStatus
+      fulfillmentStatus
+    }
   }
   ${CART_COST_FRAGMENT}
   ${CART_LINE_FRAGMENT}
@@ -263,6 +287,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 +374,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 +501,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/components/Money.d.ts

@@ -3,16 +3,23 @@
  * formatted string. Wraps `formatPrice` from core so consumers don't need to
  * import the formatter manually.
  *
- * Headless: no styling, no currency context dependency. `currency` is required
- * — render explicitly from your cart/product/shop data. This keeps the
- * component usable both inside `StorefrontProvider` and in isolated rendering
- * (server components, e-mail templates, PDFs).
+ * Headless: no styling, no Context dependency. `currency` is required —
+ * render explicitly from your cart/product/shop data. `locale` is optional;
+ * pass it for deterministic output, or omit it to let the component fall
+ * back to the runtime default (`navigator.language` in browsers, `LANG` in
+ * Node). This keeps the component usable both inside `<StorefrontProvider>`
+ * and in isolated rendering (server components, e-mail templates, PDFs).
+ *
+ * Need the locale to follow the storefront's i18n state without passing it
+ * to every `<Money>`? Use `useFormatPrice()` from `@doswiftly/storefront-sdk/react`
+ * — it pulls the active language from `useLanguageStore` and returns a
+ * memoised `formatPrice` function.
  *
  * @example
  * ```tsx
- * <Money amount={9990} currency="PLN" />           // → "99,90 zł"
- * <Money amount={1295} currency="USD" />           // → "$12.95"
- * <Money amount={0} currency="EUR" />              // → "0,00 €"
+ * <Money amount={9990} currency="PLN" locale="pl-PL" />  // → "99,90 zł"
+ * <Money amount={1295} currency="USD" locale="en-US" />  // → "$12.95"
+ * <Money amount={0} currency="EUR" locale="de-DE" />     // → "0,00 €"
  * ```
  */
 export interface MoneyProps {
@@ -20,6 +27,13 @@ export interface MoneyProps {
     amount: number;
     /** ISO 4217 currency code (PLN, EUR, USD, …). Required — no implicit default. */
     currency: string;
+    /**
+     * BCP 47 locale tag (`'pl-PL'`, `'en-US'`, `'de-DE'`, …). Drives the symbol
+     * placement, decimal mark, and grouping separator. When omitted, the runtime
+     * default is used (`navigator.language` in browsers, `LANG` in Node) — pass
+     * an explicit locale for deterministic output.
+     */
+    locale?: string;
     /** Optional class for styling — keeps the component headless. */
     className?: string;
     /**
@@ -28,5 +42,5 @@ export interface MoneyProps {
      */
     as?: 'span' | 'div' | 'p' | 'strong' | 'em' | 'output';
 }
-export declare function Money({ amount, currency, className, as: As }: MoneyProps): import("react/jsx-runtime").JSX.Element;
+export declare function Money({ amount, currency, locale, className, as: As }: MoneyProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=Money.d.ts.map

package/dist/react/components/Money.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Money.d.ts","sourceRoot":"","sources":["../../../src/react/components/Money.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAMH,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,GAAG,GAAG,QAAQ,GAAG,IAAI,GAAG,QAAQ,CAAC;CACxD;AAED,wBAAgB,KAAK,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,EAAE,EAAW,EAAE,EAAE,UAAU,2CAMjF"}
+{"version":3,"file":"Money.d.ts","sourceRoot":"","sources":["../../../src/react/components/Money.tsx"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAMH,MAAM,WAAW,UAAU;IACzB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,iEAAiE;IACjE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,EAAE,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,GAAG,GAAG,QAAQ,GAAG,IAAI,GAAG,QAAQ,CAAC;CACxD;AAED,wBAAgB,KAAK,CAAC,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,EAAE,EAAW,EAAE,EAAE,UAAU,2CASzF"}

package/dist/react/components/Money.js

@@ -3,25 +3,32 @@
  * formatted string. Wraps `formatPrice` from core so consumers don't need to
  * import the formatter manually.
  *
- * Headless: no styling, no currency context dependency. `currency` is required
- * — render explicitly from your cart/product/shop data. This keeps the
- * component usable both inside `StorefrontProvider` and in isolated rendering
- * (server components, e-mail templates, PDFs).
+ * Headless: no styling, no Context dependency. `currency` is required —
+ * render explicitly from your cart/product/shop data. `locale` is optional;
+ * pass it for deterministic output, or omit it to let the component fall
+ * back to the runtime default (`navigator.language` in browsers, `LANG` in
+ * Node). This keeps the component usable both inside `<StorefrontProvider>`
+ * and in isolated rendering (server components, e-mail templates, PDFs).
+ *
+ * Need the locale to follow the storefront's i18n state without passing it
+ * to every `<Money>`? Use `useFormatPrice()` from `@doswiftly/storefront-sdk/react`
+ * — it pulls the active language from `useLanguageStore` and returns a
+ * memoised `formatPrice` function.
  *
  * @example
  * ```tsx
- * <Money amount={9990} currency="PLN" />           // → "99,90 zł"
- * <Money amount={1295} currency="USD" />           // → "$12.95"
- * <Money amount={0} currency="EUR" />              // → "0,00 €"
+ * <Money amount={9990} currency="PLN" locale="pl-PL" />  // → "99,90 zł"
+ * <Money amount={1295} currency="USD" locale="en-US" />  // → "$12.95"
+ * <Money amount={0} currency="EUR" locale="de-DE" />     // → "0,00 €"
  * ```
  */
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
 import { formatPrice } from '../../core/format';
-export function Money({ amount, currency, className, as: As = 'span' }) {
+export function Money({ amount, currency, locale, className, as: As = 'span' }) {
     const formatted = formatPrice({
         amount: (amount / 100).toString(),
         currencyCode: currency,
-    });
+    }, locale);
     return _jsx(As, { className: className, children: formatted });
 }

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/hooks/use-format.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Convenience hooks that pull the active language from `<StorefrontProvider>`
+ * and forward it to the core format utilities. Use these inside the provider
+ * tree for boilerplate-free locale-aware formatting; outside the provider,
+ * fall back to the vanilla `formatPrice` / `formatDate` / etc. from
+ * `@doswiftly/storefront-sdk` with an explicit `locale` argument.
+ *
+ * Each hook returns a memoised function so it's safe to use directly in
+ * render. The function accepts an optional final `localeOverride` argument
+ * that wins over the store value — handy for per-call overrides (e.g. a
+ * "show in US format" toggle on one element while the rest of the UI stays
+ * in Polish).
+ *
+ * Resolution order per call:
+ *   1. `localeOverride` argument                                  (highest)
+ *   2. `useLanguageStore().language` from `<StorefrontProvider>`
+ *   3. Runtime default (`Intl.NumberFormat().resolvedOptions().locale`)
+ */
+import { type PriceMoney } from '../../core/format';
+/**
+ * Memoised `formatPrice` bound to the active language from `<StorefrontProvider>`.
+ * Pass `localeOverride` as the second argument to override the store value for
+ * a single call.
+ *
+ * @example
+ * const formatPrice = useFormatPrice();
+ * return <span>{formatPrice(item.price)}</span>;
+ *
+ * @example
+ * // Per-call override:
+ * const formatPrice = useFormatPrice();
+ * <span>{formatPrice(item.price, 'en-US')}</span>
+ */
+export declare function useFormatPrice(): (price: PriceMoney | null | undefined, localeOverride?: string) => string;
+/**
+ * Memoised `formatAmount` bound to the active language from `<StorefrontProvider>`.
+ *
+ * @example
+ * const formatAmount = useFormatAmount();
+ * return <span>{formatAmount(item.totalPrice.amount, item.totalPrice.currencyCode)}</span>;
+ */
+export declare function useFormatAmount(): (amount: string | number, currencyCode: string, localeOverride?: string) => string;
+/**
+ * Memoised `formatPriceRange` bound to the active language from `<StorefrontProvider>`.
+ *
+ * @example
+ * const formatPriceRange = useFormatPriceRange();
+ * return <span>{formatPriceRange(min, max)}</span>;
+ */
+export declare function useFormatPriceRange(): (minPrice: PriceMoney, maxPrice: PriceMoney, localeOverride?: string) => string;
+/**
+ * Memoised `formatDate` bound to the active language from `<StorefrontProvider>`.
+ *
+ * @example
+ * const formatDate = useFormatDate();
+ * return <span>{formatDate(order.processedAt)}</span>;
+ */
+export declare function useFormatDate(): (date: Date | string, localeOverride?: string) => string;
+/**
+ * Memoised `formatDateTime` bound to the active language from `<StorefrontProvider>`.
+ *
+ * @example
+ * const formatDateTime = useFormatDateTime();
+ * return <span>{formatDateTime(event.timestamp)}</span>;
+ */
+export declare function useFormatDateTime(): (date: Date | string, localeOverride?: string) => string;
+/**
+ * Memoised `formatNumber` bound to the active language from `<StorefrontProvider>`.
+ *
+ * @example
+ * const formatNumber = useFormatNumber();
+ * return <span>{formatNumber(points.balance)}</span>;
+ */
+export declare function useFormatNumber(): (num: number, localeOverride?: string) => string;
+/**
+ * Memoised `getCurrencySymbol` bound to the active language from
+ * `<StorefrontProvider>`. The returned symbol is locale-dependent — see
+ * `getCurrencySymbol` in core for examples.
+ *
+ * @example
+ * const getCurrencySymbol = useGetCurrencySymbol();
+ * return <span>{getCurrencySymbol(shop.currencyCode)}</span>;
+ */
+export declare function useGetCurrencySymbol(): (code: string, localeOverride?: string) => string;
+//# sourceMappingURL=use-format.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-format.d.ts","sourceRoot":"","sources":["../../../src/react/hooks/use-format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAMH,OAAO,EAQL,KAAK,UAAU,EAChB,MAAM,mBAAmB,CAAC;AA8B3B;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,IAAI,CAChC,KAAK,EAAE,UAAU,GAAG,IAAI,GAAG,SAAS,EACpC,cAAc,CAAC,EAAE,MAAM,KACpB,MAAM,CAMV;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,CACjC,MAAM,EAAE,MAAM,GAAG,MAAM,EACvB,YAAY,EAAE,MAAM,EACpB,cAAc,CAAC,EAAE,MAAM,KACpB,MAAM,CAOV;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,IAAI,CACrC,QAAQ,EAAE,UAAU,EACpB,QAAQ,EAAE,UAAU,EACpB,cAAc,CAAC,EAAE,MAAM,KACpB,MAAM,CAOV;AAMD;;;;;;GAMG;AACH,wBAAgB,aAAa,IAAI,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,KAAK,MAAM,CAMxF;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,IAAI,CACnC,IAAI,EAAE,IAAI,GAAG,MAAM,EACnB,cAAc,CAAC,EAAE,MAAM,KACpB,MAAM,CAMV;AAMD;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,KAAK,MAAM,CAMlF;AAMD;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,cAAc,CAAC,EAAE,MAAM,KAAK,MAAM,CAMxF"}