@vtex/faststore 0.0.1

package/dist/sdk/cart/use-cart-actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-cart-actions.js","names":[],"sources":["../../../src/sdk/cart/use-cart-actions.ts"],"sourcesContent":["'use client';\n\nimport type { ApolloClient } from '@apollo/client';\nimport { useApolloClient, useMutation } from '@apollo/client/react';\nimport { defineActions } from '@vtex/fs-core';\nimport { useCallback, useMemo } from 'react';\nimport { cartCouponErrorsVar, cartLastAddVar, cartUserErrorsVar, orderFormIdVar } from '../state/cart.js';\nimport {\n  CART_COUPON_APPLY,\n  CART_COUPON_REMOVE,\n  CART_ITEM_ADD,\n  CART_ITEM_QUANTITY_DECREASE,\n  CART_ITEM_QUANTITY_INCREASE,\n  CART_ITEM_REMOVE,\n  CART_ITEMS_REMOVE,\n  CART_VALIDATE,\n  type CartEntity,\n  CartFragment,\n  type CartItemEntity,\n  type CartUserError,\n} from './operations.js';\nimport {\n  buildOptimisticDecrease,\n  buildOptimisticIncrease,\n  buildOptimisticRemove,\n  buildOptimisticRemoveItems,\n} from './optimistic.js';\nimport { markAvailabilityFresh, trackCartWrite } from './write-gate.js';\n\n/**\n * The `cart` action namespace — the consolidated, context-free owner of every cart write\n * (specs/actions.md, docs/storefront-core/adr-0010-actions-own-the-write-side.md).\n *\n * It replaces `useCartMutations` + the mutation handlers `CartRoot` used to publish through\n * `CartDataContext`. A handler reads the current cart from the normalized Apollo cache (keyed by\n * `orderFormIdVar`), not from component props or React context, so any component anywhere in the\n * tree can dispatch a write through the compiler-injected `$actions.cart.*` prop — the cache is the\n * only meeting point between the read side and the write side (ADR-0010).\n *\n * `userErrors` from every call are published to `cartUserErrorsVar` (cleared at the start of the\n * next call) so `CartError` can surface them without a data context, and also returned to the caller.\n */\n\n/**\n * Thrown by the existing-line handlers (remove / quantity) when invoked before the cart resolves.\n * The first `addItem` mints the cart and hydrates `orderFormIdVar`; until then there is no cached\n * cart entity to read for the optimistic response.\n */\nexport class CartNotReadyError extends Error {\n  constructor(message?: string) {\n    super(message ?? 'CartNotReadyError: no cart in cache yet; add an item (or load the cart) before mutating a line.');\n    this.name = 'CartNotReadyError';\n  }\n}\n\nexport type AddItemPayload = Readonly<{\n  variantId: string;\n  quantity?: number;\n  /** Seller global Node ID, e.g. base64(\"Seller:1\"). The server rejects raw ids with INVALID_SELLER_ID. */\n  seller: string;\n}>;\n\n/** Existing-line payloads address the line by its opaque cart-item `id`; the handler reads the rest from cache. */\nexport type CartLinePayload = Readonly<{ id: string }>;\n\n/** Batch payloads address several lines by their opaque cart-item `id`s. */\nexport type CartLinesPayload = Readonly<{ ids: readonly string[] }>;\n\nexport type CartQuantityPayload = Readonly<{ id: string; by?: number }>;\n\n/** Coupon writes address the coupon by its `code`; the server resolves the cart from the cookie. */\nexport type CartCouponPayload = Readonly<{ code: string }>;\n\n/**\n * The `cart` namespace surface. Item writes return the resulting `userErrors` (empty on success)\n * and publish them to `cartUserErrorsVar`; coupon writes publish to the dedicated\n * `cartCouponErrorsVar` (specs/fspg-830-coupon-entry.md AD-2).\n */\nexport type CartActions = Readonly<{\n  /** Add an item to the cart. Async (no optimistic response). Creates the cart on first add. */\n  addItem: (payload: AddItemPayload) => Promise<readonly CartUserError[]>;\n  /** Remove a line entirely. Optimistic. */\n  removeItem: (payload: CartLinePayload) => Promise<readonly CartUserError[]>;\n  /** Remove several lines in one mutation. Optimistic. Ids missing from the cache are skipped. */\n  removeItems: (payload: CartLinesPayload) => Promise<readonly CartUserError[]>;\n  /** Increase a line's quantity by N (default 1). Optimistic. */\n  increaseQuantity: (payload: CartQuantityPayload) => Promise<readonly CartUserError[]>;\n  /** Decrease a line's quantity by N (default 1). Optimistic. Removes the line when result <= 0. */\n  decreaseQuantity: (payload: CartQuantityPayload) => Promise<readonly CartUserError[]>;\n  /** Apply a coupon code. Async (no optimistic). Publishes userErrors to cartCouponErrorsVar. */\n  applyCoupon: (payload: CartCouponPayload) => Promise<readonly CartUserError[]>;\n  /** Remove a coupon code by code. Async (no optimistic). Publishes userErrors to cartCouponErrorsVar. */\n  removeCoupon: (payload: CartCouponPayload) => Promise<readonly CartUserError[]>;\n  /**\n   * Re-check the active cart against the platform and adopt corrected availability. Async (no\n   * optimistic), read-only upstream. Returns userErrors (empty on success) to its caller and stamps\n   * the freshness window on success. Unlike the item writes it does NOT publish to\n   * `cartUserErrorsVar` — a speculative open-time failure must raise no error banner (Decision 6).\n   */\n  validate: () => Promise<readonly CartUserError[]>;\n}>;\n\nconst NETWORK_USER_ERROR: CartUserError = {\n  code: 'NETWORK_ERROR',\n  message: 'Unable to update cart. Please try again.',\n};\n\nfunction publish(errors: readonly CartUserError[]): readonly CartUserError[] {\n  cartUserErrorsVar(errors);\n  return errors;\n}\n\n/** Coupon-scoped publish — keeps coupon feedback off the shared item-error channel (AD-2). */\nfunction publishCoupon(errors: readonly CartUserError[]): readonly CartUserError[] {\n  cartCouponErrorsVar(errors);\n  return errors;\n}\n\n/**\n * Publish a write's outcome and, when it came back clean, stamp the availability freshness window —\n * a clean write's payload carries the platform's recomputed cart, which is what lets the\n * validate-on-open call skip (specs/mini-cart-validation-wiring.md, Decision 2). Used only on paths\n * where a mutation actually reached the server: a `userErrors` response carries `cart: null` and a\n * no-op (unknown line) issues no request, so neither refreshes availability.\n */\nfunction publishWrite(errors: readonly CartUserError[]): readonly CartUserError[] {\n  if (errors.length === 0) markAvailabilityFresh();\n  return publish(errors);\n}\n\n/** Coupon-channel counterpart of `publishWrite`. */\nfunction publishCouponWrite(errors: readonly CartUserError[]): readonly CartUserError[] {\n  if (errors.length === 0) markAvailabilityFresh();\n  return publishCoupon(errors);\n}\n\n/**\n * Backfill `orderFormIdVar` from a mutation's returned `cart.id` when local state is still cold.\n * A coupon op can be the first cart write (SSR cold / drawer closed on first load); without this the\n * later `requireLine` paths short-circuit on `orderFormIdVar() === null` and throw `CartNotReadyError`.\n * Mirrors the `addItem` first-add handoff.\n */\nfunction hydrateCartId(cartId: string | null): void {\n  if (cartId && orderFormIdVar() === null) orderFormIdVar(cartId);\n}\n\n/**\n * Read the live cart entity from the normalized cache (ADR-0010), keyed by `orderFormIdVar`. Returns\n * null before the cart is minted/loaded. Module-level so it can be shared with the read-only callers\n * that live outside this hook — the pre-checkout gate re-reads the corrected cart this way after\n * `validate` resolves, because Apollo commits the mutation's cache write before the promise settles\n * (specs/mini-cart-validation-wiring.md, Decision 3). The codegen `CartFragment` document embeds its\n * nested fragments, so it is a self-contained read.\n */\nexport function readCartFromCache(client: ApolloClient): CartEntity | null {\n  const cartId = orderFormIdVar();\n  if (!cartId) return null;\n  const cacheId = client.cache.identify({ __typename: 'Cart', id: cartId });\n  if (!cacheId) return null;\n  return (\n    client.cache.readFragment<CartEntity>({ id: cacheId, fragment: CartFragment, fragmentName: 'CartFragment' }) ?? null\n  );\n}\n\n/**\n * The `cart` namespace hook. Registered with the first-party action registry via `cartActions`\n * below; the compiler-emitted `CartActionProvider` calls it and threads the narrowed methods into\n * each consumer's `$actions.cart`.\n */\nexport function useCartActions(): CartActions {\n  const client = useApolloClient();\n\n  const [addMutation] = useMutation(CART_ITEM_ADD);\n  const [removeMutation] = useMutation(CART_ITEM_REMOVE);\n  const [removeItemsMutation] = useMutation(CART_ITEMS_REMOVE);\n  const [increaseMutation] = useMutation(CART_ITEM_QUANTITY_INCREASE);\n  const [decreaseMutation] = useMutation(CART_ITEM_QUANTITY_DECREASE);\n  const [applyCouponMutation] = useMutation(CART_COUPON_APPLY);\n  const [removeCouponMutation] = useMutation(CART_COUPON_REMOVE);\n  const [validateMutation] = useMutation(CART_VALIDATE);\n\n  const readCart = useCallback((): CartEntity | null => readCartFromCache(client), [client]);\n\n  const requireLine = useCallback(\n    (id: string): { cart: CartEntity; line: CartItemEntity } | null => {\n      const cart = readCart();\n      if (!cart) throw new CartNotReadyError();\n      const line = cart.items.find((item) => item.id === id);\n      if (!line) return null;\n      return { cart, line };\n    },\n    [readCart],\n  );\n\n  const addItem = useCallback<CartActions['addItem']>(\n    async (payload) => {\n      cartUserErrorsVar([]);\n      try {\n        const result = await trackCartWrite(\n          addMutation({\n            variables: {\n              input: { variantId: payload.variantId, quantity: payload.quantity ?? 1, seller: payload.seller },\n            },\n          }),\n        );\n        // Very-first add: the server minted a cart from the empty transport context. Hydrate the\n        // var so the existing-line handlers unlock without requiring a cart query.\n        if (orderFormIdVar() === null) {\n          const newId = result.data?.cartItemAdd?.cart?.id ?? null;\n          if (newId) orderFormIdVar(newId);\n        }\n        const errors = result.data?.cartItemAdd?.userErrors ?? [];\n        // Bump the add-success pulse only on the clean branch; the post-add behavior components\n        // (CartOpenOnAdd / CartRedirectOnAdd) key their effect on it. The userErrors and\n        // network-catch branches leave it untouched (specs/fspg-822-minicart-open-on-add.md).\n        if (errors.length === 0) cartLastAddVar(cartLastAddVar() + 1);\n        return publishWrite(errors);\n      } catch (error) {\n        console.error('[cart.addItem] cartItemAdd failed', error);\n        return publish([NETWORK_USER_ERROR]);\n      }\n    },\n    [addMutation],\n  );\n\n  const removeItem = useCallback<CartActions['removeItem']>(\n    async (payload) => {\n      const found = requireLine(payload.id);\n      if (!found) return publish([]);\n      cartUserErrorsVar([]);\n      try {\n        const result = await trackCartWrite(\n          removeMutation({\n            variables: { input: { variantId: found.line.variant.variantId } },\n            optimisticResponse: buildOptimisticRemove(found.cart, found.line),\n          }),\n        );\n        return publishWrite(result.data?.cartItemRemove?.userErrors ?? []);\n      } catch (error) {\n        console.error('[cart.removeItem] cartItemRemove failed', error);\n        return publish([NETWORK_USER_ERROR]);\n      }\n    },\n    [requireLine, removeMutation],\n  );\n\n  const removeItems = useCallback<CartActions['removeItems']>(\n    async (payload) => {\n      const cart = readCart();\n      if (!cart) throw new CartNotReadyError();\n      // Client-side tolerance mirroring removeItem's not-found no-op: ids without a cached line\n      // are skipped, and the surviving set is deduped before the single mutation.\n      const lines = cart.items.filter((item) => payload.ids.includes(item.id));\n      if (lines.length === 0) return publish([]);\n      const variantIds = [...new Set(lines.map((line) => line.variant.variantId))];\n      cartUserErrorsVar([]);\n      try {\n        const result = await trackCartWrite(\n          removeItemsMutation({\n            variables: { input: { variantIds } },\n            optimisticResponse: buildOptimisticRemoveItems(cart, lines),\n          }),\n        );\n        return publishWrite(result.data?.cartItemsRemove?.userErrors ?? []);\n      } catch (error) {\n        console.error('[cart.removeItems] cartItemsRemove failed', error);\n        return publish([NETWORK_USER_ERROR]);\n      }\n    },\n    [readCart, removeItemsMutation],\n  );\n\n  const increaseQuantity = useCallback<CartActions['increaseQuantity']>(\n    async (payload) => {\n      const by = payload.by ?? 1;\n      const found = requireLine(payload.id);\n      if (!found) return publish([]);\n      cartUserErrorsVar([]);\n      try {\n        const result = await trackCartWrite(\n          increaseMutation({\n            variables: { input: { variantId: found.line.variant.variantId, quantityToAdd: by } },\n            optimisticResponse: buildOptimisticIncrease(found.cart, found.line, by),\n          }),\n        );\n        return publishWrite(result.data?.cartItemQuantityIncrease?.userErrors ?? []);\n      } catch (error) {\n        console.error('[cart.increaseQuantity] cartItemQuantityIncrease failed', error);\n        return publish([NETWORK_USER_ERROR]);\n      }\n    },\n    [requireLine, increaseMutation],\n  );\n\n  const decreaseQuantity = useCallback<CartActions['decreaseQuantity']>(\n    async (payload) => {\n      const by = payload.by ?? 1;\n      const found = requireLine(payload.id);\n      if (!found) return publish([]);\n      cartUserErrorsVar([]);\n      try {\n        const result = await trackCartWrite(\n          decreaseMutation({\n            variables: { input: { variantId: found.line.variant.variantId, quantityToRemove: by } },\n            optimisticResponse: buildOptimisticDecrease(found.cart, found.line, by),\n          }),\n        );\n        return publishWrite(result.data?.cartItemQuantityDecrease?.userErrors ?? []);\n      } catch (error) {\n        console.error('[cart.decreaseQuantity] cartItemQuantityDecrease failed', error);\n        return publish([NETWORK_USER_ERROR]);\n      }\n    },\n    [requireLine, decreaseMutation],\n  );\n\n  // Coupons are cart-level: no `requireLine` gate (AD-9). No optimistic response and no client\n  // rollback — totals and `isUnmatchedCondition` are server-computed and the server rolls back its\n  // own single-coupon rejections; the returned cart (spreading the extended CartFragment)\n  // self-updates the cache and every reactive subscriber (specs/fspg-830-coupon-entry.md AD-3/AD-8).\n  const applyCoupon = useCallback<CartActions['applyCoupon']>(\n    async (payload) => {\n      cartCouponErrorsVar([]);\n      try {\n        const result = await trackCartWrite(applyCouponMutation({ variables: { input: { code: payload.code } } }));\n        hydrateCartId(result.data?.cartCouponApply?.cart?.id ?? null);\n        return publishCouponWrite(result.data?.cartCouponApply?.userErrors ?? []);\n      } catch (error) {\n        console.error('[cart.applyCoupon] cartCouponApply failed', error);\n        return publishCoupon([NETWORK_USER_ERROR]);\n      }\n    },\n    [applyCouponMutation],\n  );\n\n  const removeCoupon = useCallback<CartActions['removeCoupon']>(\n    async (payload) => {\n      cartCouponErrorsVar([]);\n      try {\n        const result = await trackCartWrite(removeCouponMutation({ variables: { input: { code: payload.code } } }));\n        hydrateCartId(result.data?.cartCouponRemove?.cart?.id ?? null);\n        return publishCouponWrite(result.data?.cartCouponRemove?.userErrors ?? []);\n      } catch (error) {\n        console.error('[cart.removeCoupon] cartCouponRemove failed', error);\n        return publishCoupon([NETWORK_USER_ERROR]);\n      }\n    },\n    [removeCouponMutation],\n  );\n\n  // Read-only upstream (specs/mini-cart-validate-operation.md): re-simulates the cart and returns it\n  // with `variant.availability` corrected, spreading CartFragment so the guard, the per-line alert,\n  // and the badge re-render off the cache. Deliberately unlike the item writes: it does NOT register\n  // as an in-flight write (it would gate itself) and it does NOT publish to cartUserErrorsVar — the\n  // open call is speculative and the pre-checkout call is fail-open, so a failure must raise no error\n  // banner (Decision 6). It stamps the freshness window on success so open-on-add does not re-check.\n  const validate = useCallback<CartActions['validate']>(async () => {\n    try {\n      const result = await validateMutation();\n      // Hydrate as the coupon writes do: the corrected cart is now in the cache, and the pre-checkout\n      // gate finds it by `orderFormIdVar`. Without this a cold var would leave the gate reading null\n      // and passing a cart it never actually checked.\n      hydrateCartId(result.data?.cartValidate?.cart?.id ?? null);\n      const errors = result.data?.cartValidate?.userErrors ?? [];\n      if (errors.length === 0) markAvailabilityFresh();\n      return errors;\n    } catch (error) {\n      console.error('[cart.validate] cartValidate failed', error);\n      return [NETWORK_USER_ERROR];\n    }\n  }, [validateMutation]);\n\n  return useMemo(\n    () => ({\n      addItem,\n      removeItem,\n      removeItems,\n      increaseQuantity,\n      decreaseQuantity,\n      applyCoupon,\n      removeCoupon,\n      validate,\n    }),\n    [addItem, removeItem, removeItems, increaseQuantity, decreaseQuantity, applyCoupon, removeCoupon, validate],\n  );\n}\n\n/**\n * Declares the `cart` action namespace — the single source of truth for its method/payload metadata,\n * runtime provider, and `use` hook (mirrors `defineComponent`). The native catalog builder\n * (`@vtex/sukima-node`'s `buildPackageCatalog`) statically reads this call to emit `actions.json`;\n * at runtime `CartActionProvider` calls `useCartActions` directly.\n */\nexport const cartActions = defineActions({\n  namespace: 'cart',\n  description: 'Mutation-backed writes against the current cart (consolidates useCartMutations / CartRoot).',\n  provider: { name: 'CartActionProvider', importPath: '@vtex/faststore/internal/client' },\n  methods: {\n    addItem: {\n      description: 'Add an item to the cart (async strategy). Creates the cart on first add.',\n      payload: [\n        { name: 'variantId', type: 'string' },\n        { name: 'seller', type: 'string' },\n        { name: 'quantity', type: 'number', optional: true },\n      ],\n    },\n    removeItem: {\n      description: 'Remove a line from the cart (optimistic strategy).',\n      payload: [{ name: 'id', type: 'string' }],\n    },\n    removeItems: {\n      description: 'Remove several lines from the cart in one call (optimistic strategy).',\n      payload: [{ name: 'ids', type: 'string[]' }],\n    },\n    increaseQuantity: {\n      description: \"Increase a line's quantity by N (default 1, optimistic strategy).\",\n      payload: [\n        { name: 'id', type: 'string' },\n        { name: 'by', type: 'number', optional: true },\n      ],\n    },\n    decreaseQuantity: {\n      description: \"Decrease a line's quantity by N (default 1, optimistic). Removes the line at <= 0.\",\n      payload: [\n        { name: 'id', type: 'string' },\n        { name: 'by', type: 'number', optional: true },\n      ],\n    },\n    applyCoupon: {\n      description: 'Apply a coupon code to the cart (async strategy). Server recomputes totals.',\n      payload: [{ name: 'code', type: 'string' }],\n    },\n    removeCoupon: {\n      description: 'Remove a coupon code from the cart (async strategy). Server recomputes totals.',\n      payload: [{ name: 'code', type: 'string' }],\n    },\n    validate: {\n      description:\n        'Re-check the active cart against the platform and adopt corrected availability (async, read-only upstream).',\n      payload: [],\n    },\n  },\n  use: useCartActions,\n});\n"],"mappings":"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"}

package/dist/sdk/cart/use-cart-validate-on-open.js

@@ -0,0 +1,50 @@
+"use client";
+import { cartAvailabilityFreshAtVar, cartWritesInFlightVar, miniCartOpenVar } from "../state/cart.js";
+import { readCartFromCache } from "./use-cart-actions.js";
+import { useApolloClient, useReactiveVar } from "@apollo/client/react";
+import { useEffect, useRef } from "react";
+//#region src/sdk/cart/use-cart-validate-on-open.ts
+/**
+* Runs stock validation when the mini-cart overlay opens (specs/mini-cart-validation-wiring.md, FR-5).
+*
+* `miniCartOpenVar` is the overlay's single source of truth — the add-pulse open, the header trigger,
+* and manual close all route through it — so watching its closed→open edge covers every way the
+* drawer opens. The call is bounded and cooperative: it fires at most once per transition, and skips
+* when there is nothing to gain — no validate action wired, a cart write in flight, availability
+* refreshed within the staleness window (which is why open-on-add does not re-validate), or an empty
+* cart. `validate` is the compiler-injected `$actions.cart.validate`; when it is absent the hook is a
+* no-op, so a store without the action wired pays nothing.
+*
+* A dispatch is reserved synchronously with a ref latch, cleared when the call settles. Freshness is
+* only stamped once `validate` resolves, so a close-and-reopen during that window would otherwise slip
+* past the staleness guard and fire a second call; the latch closes that gap.
+*/
+function useCartValidateOnOpen(validate) {
+	const client = useApolloClient();
+	const open = useReactiveVar(miniCartOpenVar);
+	const wasOpen = useRef(open);
+	const pending = useRef(false);
+	useEffect(() => {
+		const opened = open && !wasOpen.current;
+		wasOpen.current = open;
+		if (!opened || !validate || pending.current) return;
+		if (cartWritesInFlightVar() > 0) return;
+		if (Date.now() - cartAvailabilityFreshAtVar() < 3e4) return;
+		const cart = readCartFromCache(client);
+		if (!cart || cart.items.length === 0) return;
+		pending.current = true;
+		Promise.resolve(validate()).catch((error) => {
+			console.error("[cart.validateOnOpen] validate rejected", error);
+		}).finally(() => {
+			pending.current = false;
+		});
+	}, [
+		open,
+		validate,
+		client
+	]);
+}
+//#endregion
+export { useCartValidateOnOpen };
+
+//# sourceMappingURL=use-cart-validate-on-open.js.map

package/dist/sdk/cart/use-cart-validate-on-open.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-cart-validate-on-open.js","names":[],"sources":["../../../src/sdk/cart/use-cart-validate-on-open.ts"],"sourcesContent":["'use client';\n\nimport { useApolloClient, useReactiveVar } from '@apollo/client/react';\nimport { useEffect, useRef } from 'react';\nimport {\n  CART_VALIDATE_STALENESS_MS,\n  cartAvailabilityFreshAtVar,\n  cartWritesInFlightVar,\n  miniCartOpenVar,\n} from '../state/cart.js';\nimport { readCartFromCache } from './use-cart-actions.js';\n\n/**\n * Runs stock validation when the mini-cart overlay opens (specs/mini-cart-validation-wiring.md, FR-5).\n *\n * `miniCartOpenVar` is the overlay's single source of truth — the add-pulse open, the header trigger,\n * and manual close all route through it — so watching its closed→open edge covers every way the\n * drawer opens. The call is bounded and cooperative: it fires at most once per transition, and skips\n * when there is nothing to gain — no validate action wired, a cart write in flight, availability\n * refreshed within the staleness window (which is why open-on-add does not re-validate), or an empty\n * cart. `validate` is the compiler-injected `$actions.cart.validate`; when it is absent the hook is a\n * no-op, so a store without the action wired pays nothing.\n *\n * A dispatch is reserved synchronously with a ref latch, cleared when the call settles. Freshness is\n * only stamped once `validate` resolves, so a close-and-reopen during that window would otherwise slip\n * past the staleness guard and fire a second call; the latch closes that gap.\n */\nexport function useCartValidateOnOpen(validate: (() => Promise<unknown>) | undefined): void {\n  const client = useApolloClient();\n  const open = useReactiveVar(miniCartOpenVar);\n  const wasOpen = useRef(open);\n  const pending = useRef(false);\n\n  useEffect(() => {\n    const opened = open && !wasOpen.current;\n    wasOpen.current = open;\n    if (!opened || !validate || pending.current) return;\n    // A write in flight (or one that just settled, inside the window) already refreshed availability.\n    if (cartWritesInFlightVar() > 0) return;\n    if (Date.now() - cartAvailabilityFreshAtVar() < CART_VALIDATE_STALENESS_MS) return;\n    // Nothing to validate on an empty cart, and T1 would only round-trip a single read for it.\n    const cart = readCartFromCache(client);\n    if (!cart || cart.items.length === 0) return;\n    pending.current = true;\n    // The current wiring never rejects (useCartActions().validate catches and resolves with\n    // [NETWORK_USER_ERROR]); this guards a differently-injected validate so a rejection cannot\n    // escape as an unhandled promise rejection.\n    void Promise.resolve(validate())\n      .catch((error) => {\n        console.error('[cart.validateOnOpen] validate rejected', error);\n      })\n      .finally(() => {\n        pending.current = false;\n      });\n  }, [open, validate, client]);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;AA2BA,SAAgB,sBAAsB,UAAsD;CAC1F,MAAM,SAAS,gBAAgB;CAC/B,MAAM,OAAO,eAAe,eAAe;CAC3C,MAAM,UAAU,OAAO,IAAI;CAC3B,MAAM,UAAU,OAAO,KAAK;CAE5B,gBAAgB;EACd,MAAM,SAAS,QAAQ,CAAC,QAAQ;EAChC,QAAQ,UAAU;EAClB,IAAI,CAAC,UAAU,CAAC,YAAY,QAAQ,SAAS;EAE7C,IAAI,sBAAsB,IAAI,GAAG;EACjC,IAAI,KAAK,IAAI,IAAI,2BAA2B,IAAA,KAAgC;EAE5E,MAAM,OAAO,kBAAkB,MAAM;EACrC,IAAI,CAAC,QAAQ,KAAK,MAAM,WAAW,GAAG;EACtC,QAAQ,UAAU;EAIlB,QAAa,QAAQ,SAAS,CAAC,CAAC,CAC7B,OAAO,UAAU;GAChB,QAAQ,MAAM,2CAA2C,KAAK;EAChE,CAAC,CAAC,CACD,cAAc;GACb,QAAQ,UAAU;EACpB,CAAC;CACL,GAAG;EAAC;EAAM;EAAU;CAAM,CAAC;AAC7B"}

package/dist/sdk/cart/write-gate.js

@@ -0,0 +1,54 @@
+import { cartAvailabilityFreshAtVar, cartWritesInFlightVar } from "../state/cart.js";
+//#region src/sdk/cart/write-gate.ts
+/**
+* In-flight cart-write registry (specs/mini-cart-validation-wiring.md, Decision 2).
+*
+* The stock-validation wiring needs two things the mutation contract never had to expose, because
+* the open-time validate is the first cart call that is not user-initiated:
+*
+*   - an observable "is a write running" signal, so the open call can *skip* while one is (that
+*     write's response already carries current availability); and
+*   - an `await`-settlement primitive, so the pre-checkout call can *wait* for any write before it
+*     re-checks the cart it is about to send to checkout.
+*
+* Both derive from one module-scoped set of pending write promises. `validate` is read-only upstream
+* and must never register here — it would gate itself.
+*/
+const inFlight = /* @__PURE__ */ new Set();
+/**
+* Stamp "availability is fresh as of now". Called only where the client actually received current
+* availability: a cart write that came back clean, or a successful `validate`. A write answered with
+* `userErrors` carries `cart: null` (mutation contract), so it learned nothing and must not stamp —
+* otherwise the next overlay open would skip validation on the strength of a rejected write.
+*/
+function markAvailabilityFresh() {
+	cartAvailabilityFreshAtVar(Date.now());
+}
+/**
+* Register a cart write's promise for the lifetime of the call, publishing the reactive in-flight
+* count so the validate-on-open call can skip while a write is outstanding. Tracking only — the
+* freshness stamp belongs to the caller, which is the only place that can see whether the payload
+* came back clean. Returns the same promise so callers can `await trackCartWrite(mutation(...))`.
+*/
+function trackCartWrite(promise) {
+	inFlight.add(promise);
+	cartWritesInFlightVar(inFlight.size);
+	const clear = () => {
+		inFlight.delete(promise);
+		cartWritesInFlightVar(inFlight.size);
+	};
+	promise.then(clear, clear);
+	return promise;
+}
+/**
+* Resolve once every write registered at call time has settled (fulfilled or rejected). Writes
+* started afterwards are not awaited — this captures "any in-flight write" at the moment the
+* pre-checkout call fires, which is exactly the ordering guarantee the checkout gate needs.
+*/
+function awaitCartWrites() {
+	return Promise.allSettled(inFlight).then(() => void 0);
+}
+//#endregion
+export { awaitCartWrites, markAvailabilityFresh, trackCartWrite };
+
+//# sourceMappingURL=write-gate.js.map

package/dist/sdk/cart/write-gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-gate.js","names":[],"sources":["../../../src/sdk/cart/write-gate.ts"],"sourcesContent":["import { cartAvailabilityFreshAtVar, cartWritesInFlightVar } from '../state/cart.js';\n\n/**\n * In-flight cart-write registry (specs/mini-cart-validation-wiring.md, Decision 2).\n *\n * The stock-validation wiring needs two things the mutation contract never had to expose, because\n * the open-time validate is the first cart call that is not user-initiated:\n *\n *   - an observable \"is a write running\" signal, so the open call can *skip* while one is (that\n *     write's response already carries current availability); and\n *   - an `await`-settlement primitive, so the pre-checkout call can *wait* for any write before it\n *     re-checks the cart it is about to send to checkout.\n *\n * Both derive from one module-scoped set of pending write promises. `validate` is read-only upstream\n * and must never register here — it would gate itself.\n */\n\nconst inFlight = new Set<Promise<unknown>>();\n\n/**\n * Stamp \"availability is fresh as of now\". Called only where the client actually received current\n * availability: a cart write that came back clean, or a successful `validate`. A write answered with\n * `userErrors` carries `cart: null` (mutation contract), so it learned nothing and must not stamp —\n * otherwise the next overlay open would skip validation on the strength of a rejected write.\n */\nexport function markAvailabilityFresh(): void {\n  cartAvailabilityFreshAtVar(Date.now());\n}\n\n/**\n * Register a cart write's promise for the lifetime of the call, publishing the reactive in-flight\n * count so the validate-on-open call can skip while a write is outstanding. Tracking only — the\n * freshness stamp belongs to the caller, which is the only place that can see whether the payload\n * came back clean. Returns the same promise so callers can `await trackCartWrite(mutation(...))`.\n */\nexport function trackCartWrite<T>(promise: Promise<T>): Promise<T> {\n  inFlight.add(promise);\n  cartWritesInFlightVar(inFlight.size);\n  const clear = () => {\n    inFlight.delete(promise);\n    cartWritesInFlightVar(inFlight.size);\n  };\n  promise.then(clear, clear);\n  return promise;\n}\n\n/**\n * Resolve once every write registered at call time has settled (fulfilled or rejected). Writes\n * started afterwards are not awaited — this captures \"any in-flight write\" at the moment the\n * pre-checkout call fires, which is exactly the ordering guarantee the checkout gate needs.\n */\nexport function awaitCartWrites(): Promise<void> {\n  return Promise.allSettled(inFlight).then(() => undefined);\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAiBA,MAAM,2BAAW,IAAI,IAAsB;;;;;;;AAQ3C,SAAgB,wBAA8B;CAC5C,2BAA2B,KAAK,IAAI,CAAC;AACvC;;;;;;;AAQA,SAAgB,eAAkB,SAAiC;CACjE,SAAS,IAAI,OAAO;CACpB,sBAAsB,SAAS,IAAI;CACnC,MAAM,cAAc;EAClB,SAAS,OAAO,OAAO;EACvB,sBAAsB,SAAS,IAAI;CACrC;CACA,QAAQ,KAAK,OAAO,KAAK;CACzB,OAAO;AACT;;;;;;AAOA,SAAgB,kBAAiC;CAC/C,OAAO,QAAQ,WAAW,QAAQ,CAAC,CAAC,WAAW,KAAA,CAAS;AAC1D"}

package/dist/sdk/client/assert-api-url.js

@@ -0,0 +1,20 @@
+//#region src/sdk/client/assert-api-url.ts
+/**
+* Validates that `apiUrl` is a parseable URL with an http(s) protocol. Used by
+* `createClient` and `registerPreloadQuery` so misconfiguration (typo, missing
+* protocol, `file://`, internal scheme) fails at startup with a clear message
+* instead of surfacing as an opaque runtime fetch error.
+*/
+function assertValidApiUrl(apiUrl, fnName) {
+	let parsed;
+	try {
+		parsed = new URL(apiUrl);
+	} catch {
+		throw new Error(`${fnName}: \`apiUrl\` is not a valid URL (got "${apiUrl}").`);
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") throw new Error(`${fnName}: \`apiUrl\` must use http or https (got "${parsed.protocol}").`);
+}
+//#endregion
+export { assertValidApiUrl };
+
+//# sourceMappingURL=assert-api-url.js.map

package/dist/sdk/client/assert-api-url.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-api-url.js","names":[],"sources":["../../../src/sdk/client/assert-api-url.ts"],"sourcesContent":["/**\n * Validates that `apiUrl` is a parseable URL with an http(s) protocol. Used by\n * `createClient` and `registerPreloadQuery` so misconfiguration (typo, missing\n * protocol, `file://`, internal scheme) fails at startup with a clear message\n * instead of surfacing as an opaque runtime fetch error.\n */\nexport function assertValidApiUrl(apiUrl: string, fnName: string): void {\n  let parsed: URL;\n  try {\n    parsed = new URL(apiUrl);\n  } catch {\n    throw new Error(`${fnName}: \\`apiUrl\\` is not a valid URL (got \"${apiUrl}\").`);\n  }\n\n  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {\n    throw new Error(`${fnName}: \\`apiUrl\\` must use http or https (got \"${parsed.protocol}\").`);\n  }\n}\n"],"mappings":";;;;;;;AAMA,SAAgB,kBAAkB,QAAgB,QAAsB;CACtE,IAAI;CACJ,IAAI;EACF,SAAS,IAAI,IAAI,MAAM;CACzB,QAAQ;EACN,MAAM,IAAI,MAAM,GAAG,OAAO,wCAAwC,OAAO,IAAI;CAC/E;CAEA,IAAI,OAAO,aAAa,WAAW,OAAO,aAAa,UACrD,MAAM,IAAI,MAAM,GAAG,OAAO,4CAA4C,OAAO,SAAS,IAAI;AAE9F"}

package/dist/sdk/client/create-client.d.ts

@@ -0,0 +1,23 @@
+import { StorefrontContext } from "../../core/dist/schema/generated/schema.js";
+import "../../core/dist/index.js";
+import { ApolloClient } from "@apollo/client";
+//#region src/sdk/client/create-client.d.ts
+export type CreateClientOptions = {
+  apiUrl?: string;
+  /** The compiler-emitted context; its three headers ride every operation this client sends. */
+  context?: StorefrontContext;
+  headers?: Record<string, string>;
+};
+/**
+ * Returns a fresh, stateless Apollo Client suitable for server-side
+ * rendering / RSC calls. Every invocation builds a new cache — callers
+ * that need "one client per lambda" are responsible for caching the
+ * returned instance themselves (see the generated `utils/query-client.ts`).
+ *
+ * The client shares its `typePolicies` + `possibleTypes` with the
+ * browser-side client via `buildCache()` so normalized entities line up
+ * across SSR / CSR boundaries.
+ */
+export declare function createClient(options?: CreateClientOptions): ApolloClient;
+//#endregion
+//# sourceMappingURL=create-client.d.ts.map

package/dist/sdk/client/create-client.js

@@ -0,0 +1,46 @@
+import { buildStorefrontContextHeaders } from "../context/headers.js";
+import { buildCache } from "../cache/storefront-cache.js";
+import { assertValidApiUrl } from "./assert-api-url.js";
+import { ApolloClient, HttpLink } from "@apollo/client";
+//#region src/sdk/client/create-client.ts
+/**
+* Returns a fresh, stateless Apollo Client suitable for server-side
+* rendering / RSC calls. Every invocation builds a new cache — callers
+* that need "one client per lambda" are responsible for caching the
+* returned instance themselves (see the generated `utils/query-client.ts`).
+*
+* The client shares its `typePolicies` + `possibleTypes` with the
+* browser-side client via `buildCache()` so normalized entities line up
+* across SSR / CSR boundaries.
+*/
+function createClient(options = {}) {
+	const apiUrl = options.apiUrl ?? process.env.STOREFRONT_API_URL;
+	if (!apiUrl) throw new Error("createClient: `apiUrl` is required. Pass it via options or set the `STOREFRONT_API_URL` environment variable.");
+	assertValidApiUrl(apiUrl, "createClient");
+	const headers = options.context ? {
+		...options.headers,
+		...buildStorefrontContextHeaders(options.context)
+	} : options.headers;
+	const link = new HttpLink({
+		uri: apiUrl,
+		...headers ? { headers } : {}
+	});
+	return new ApolloClient({
+		cache: buildCache(),
+		link,
+		defaultOptions: {
+			query: {
+				errorPolicy: "all",
+				fetchPolicy: "no-cache"
+			},
+			watchQuery: {
+				errorPolicy: "all",
+				fetchPolicy: "no-cache"
+			}
+		}
+	});
+}
+//#endregion
+export { createClient };
+
+//# sourceMappingURL=create-client.js.map

package/dist/sdk/client/create-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-client.js","names":[],"sources":["../../../src/sdk/client/create-client.ts"],"sourcesContent":["import { ApolloClient, HttpLink } from '@apollo/client';\nimport type { StorefrontContext } from '@vtex/fs-core';\nimport { buildCache } from '../cache/storefront-cache.js';\nimport { buildStorefrontContextHeaders } from '../context/headers.js';\nimport { assertValidApiUrl } from './assert-api-url.js';\n\nexport type CreateClientOptions = {\n  apiUrl?: string;\n  /** The compiler-emitted context; its three headers ride every operation this client sends. */\n  context?: StorefrontContext;\n  headers?: Record<string, string>;\n};\n\n/**\n * Returns a fresh, stateless Apollo Client suitable for server-side\n * rendering / RSC calls. Every invocation builds a new cache — callers\n * that need \"one client per lambda\" are responsible for caching the\n * returned instance themselves (see the generated `utils/query-client.ts`).\n *\n * The client shares its `typePolicies` + `possibleTypes` with the\n * browser-side client via `buildCache()` so normalized entities line up\n * across SSR / CSR boundaries.\n */\nexport function createClient(options: CreateClientOptions = {}): ApolloClient {\n  const apiUrl = options.apiUrl ?? process.env.STOREFRONT_API_URL;\n\n  if (!apiUrl) {\n    throw new Error(\n      'createClient: `apiUrl` is required. Pass it via options or set the ' +\n        '`STOREFRONT_API_URL` environment variable.',\n    );\n  }\n\n  assertValidApiUrl(apiUrl, 'createClient');\n\n  // Context headers merge last: a caller cannot contradict the context the app rendered. To request a\n  // different locale, binding or sales channel, pass a different `context`.\n  const headers = options.context\n    ? { ...options.headers, ...buildStorefrontContextHeaders(options.context) }\n    : options.headers;\n\n  const link = new HttpLink({\n    uri: apiUrl,\n    ...(headers ? { headers } : {}),\n  });\n\n  return new ApolloClient({\n    cache: buildCache(),\n    link,\n    defaultOptions: {\n      query: { errorPolicy: 'all', fetchPolicy: 'no-cache' },\n      watchQuery: { errorPolicy: 'all', fetchPolicy: 'no-cache' },\n    },\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;AAuBA,SAAgB,aAAa,UAA+B,CAAC,GAAiB;CAC5E,MAAM,SAAS,QAAQ,UAAU,QAAQ,IAAI;CAE7C,IAAI,CAAC,QACH,MAAM,IAAI,MACR,+GAEF;CAGF,kBAAkB,QAAQ,cAAc;CAIxC,MAAM,UAAU,QAAQ,UACpB;EAAE,GAAG,QAAQ;EAAS,GAAG,8BAA8B,QAAQ,OAAO;CAAE,IACxE,QAAQ;CAEZ,MAAM,OAAO,IAAI,SAAS;EACxB,KAAK;EACL,GAAI,UAAU,EAAE,QAAQ,IAAI,CAAC;CAC/B,CAAC;CAED,OAAO,IAAI,aAAa;EACtB,OAAO,WAAW;EAClB;EACA,gBAAgB;GACd,OAAO;IAAE,aAAa;IAAO,aAAa;GAAW;GACrD,YAAY;IAAE,aAAa;IAAO,aAAa;GAAW;EAC5D;CACF,CAAC;AACH"}

package/dist/sdk/client/fetch-page-data.d.ts

@@ -0,0 +1,39 @@
+import { ApolloClient, DocumentNode, ErrorLike, OperationVariables, TypedDocumentNode } from "@apollo/client";
+//#region src/sdk/client/fetch-page-data.d.ts
+/**
+ * Options bag accepted by {@link fetchPageData}.
+ *
+ * Mirrors Apollo Client 4.x's own `VariablesOption<TVars>` shape: when
+ * `TVars` has no required keys (the default `OperationVariables`), variables
+ * are optional; when the caller supplies a concrete variables object with
+ * required fields, variables become required — matching the contract of the
+ * underlying `client.query` call.
+ */
+export type FetchPageDataOptions<TVars extends OperationVariables> = {} extends TVars ? {
+  variables?: TVars;
+} : {
+  variables: TVars;
+};
+export type FetchPageDataResult<TData> = {
+  data: TData | null;
+  error?: ErrorLike;
+};
+/**
+ * Runs a single query against the provided Apollo Client with the options
+ * required for stateless RSC rendering (`errorPolicy: 'all'` — partial data
+ * is returned alongside the error — and `fetchPolicy: 'no-cache'` — the
+ * client's cache is never consulted, so a long-lived module-level client
+ * cannot leak state across requests).
+ *
+ * Never constructs a client itself; callers own the client lifetime via
+ * the generated `utils/query-client.ts` or a direct `createClient()` call.
+ *
+ * Under `errorPolicy: 'all'`, Apollo reports every failure — GraphQL errors
+ * and transport-level errors alike — via the `error` field alongside any
+ * partial `data` the server produced. Callers who need to distinguish the
+ * two can inspect `result.error` with `CombinedGraphQLErrors.is()` from
+ * `@apollo/client/errors`.
+ */
+export declare function fetchPageData<TData = unknown, TVars extends OperationVariables = OperationVariables>(client: ApolloClient, document: DocumentNode | TypedDocumentNode<TData, TVars>, options?: FetchPageDataOptions<TVars>): Promise<FetchPageDataResult<TData>>;
+//#endregion
+//# sourceMappingURL=fetch-page-data.d.ts.map

package/dist/sdk/client/fetch-page-data.js

@@ -0,0 +1,33 @@
+//#region src/sdk/client/fetch-page-data.ts
+/**
+* Runs a single query against the provided Apollo Client with the options
+* required for stateless RSC rendering (`errorPolicy: 'all'` — partial data
+* is returned alongside the error — and `fetchPolicy: 'no-cache'` — the
+* client's cache is never consulted, so a long-lived module-level client
+* cannot leak state across requests).
+*
+* Never constructs a client itself; callers own the client lifetime via
+* the generated `utils/query-client.ts` or a direct `createClient()` call.
+*
+* Under `errorPolicy: 'all'`, Apollo reports every failure — GraphQL errors
+* and transport-level errors alike — via the `error` field alongside any
+* partial `data` the server produced. Callers who need to distinguish the
+* two can inspect `result.error` with `CombinedGraphQLErrors.is()` from
+* `@apollo/client/errors`.
+*/
+async function fetchPageData(client, document, options = {}) {
+	const result = await client.query({
+		...options,
+		query: document,
+		errorPolicy: "all",
+		fetchPolicy: "no-cache"
+	});
+	return {
+		data: result.data ?? null,
+		...result.error ? { error: result.error } : {}
+	};
+}
+//#endregion
+export { fetchPageData };
+
+//# sourceMappingURL=fetch-page-data.js.map

package/dist/sdk/client/fetch-page-data.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-page-data.js","names":[],"sources":["../../../src/sdk/client/fetch-page-data.ts"],"sourcesContent":["import type { ApolloClient, DocumentNode, ErrorLike, OperationVariables, TypedDocumentNode } from '@apollo/client';\n\n/**\n * Options bag accepted by {@link fetchPageData}.\n *\n * Mirrors Apollo Client 4.x's own `VariablesOption<TVars>` shape: when\n * `TVars` has no required keys (the default `OperationVariables`), variables\n * are optional; when the caller supplies a concrete variables object with\n * required fields, variables become required — matching the contract of the\n * underlying `client.query` call.\n */\n// biome-ignore lint/complexity/noBannedTypes: `{} extends TVars` is the idiomatic probe for \"variables has no required keys\" — same pattern Apollo itself uses.\nexport type FetchPageDataOptions<TVars extends OperationVariables> = {} extends TVars\n  ? { variables?: TVars }\n  : { variables: TVars };\n\nexport type FetchPageDataResult<TData> = {\n  data: TData | null;\n  error?: ErrorLike;\n};\n\n/**\n * Runs a single query against the provided Apollo Client with the options\n * required for stateless RSC rendering (`errorPolicy: 'all'` — partial data\n * is returned alongside the error — and `fetchPolicy: 'no-cache'` — the\n * client's cache is never consulted, so a long-lived module-level client\n * cannot leak state across requests).\n *\n * Never constructs a client itself; callers own the client lifetime via\n * the generated `utils/query-client.ts` or a direct `createClient()` call.\n *\n * Under `errorPolicy: 'all'`, Apollo reports every failure — GraphQL errors\n * and transport-level errors alike — via the `error` field alongside any\n * partial `data` the server produced. Callers who need to distinguish the\n * two can inspect `result.error` with `CombinedGraphQLErrors.is()` from\n * `@apollo/client/errors`.\n */\nexport async function fetchPageData<TData = unknown, TVars extends OperationVariables = OperationVariables>(\n  client: ApolloClient,\n  document: DocumentNode | TypedDocumentNode<TData, TVars>,\n  options: FetchPageDataOptions<TVars> = {} as FetchPageDataOptions<TVars>,\n): Promise<FetchPageDataResult<TData>> {\n  const result = await client.query<TData, TVars>({\n    ...options,\n    query: document,\n    errorPolicy: 'all',\n    fetchPolicy: 'no-cache',\n  });\n\n  return {\n    data: result.data ?? null,\n    ...(result.error ? { error: result.error } : {}),\n  };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAqCA,eAAsB,cACpB,QACA,UACA,UAAuC,CAAC,GACH;CACrC,MAAM,SAAS,MAAM,OAAO,MAAoB;EAC9C,GAAG;EACH,OAAO;EACP,aAAa;EACb,aAAa;CACf,CAAC;CAED,OAAO;EACL,MAAM,OAAO,QAAQ;EACrB,GAAI,OAAO,QAAQ,EAAE,OAAO,OAAO,MAAM,IAAI,CAAC;CAChD;AACF"}

package/dist/sdk/client/register-preload-query.d.ts

@@ -0,0 +1,24 @@
+import { StorefrontContext } from "../../core/dist/schema/generated/schema.js";
+import "../../core/dist/index.js";
+import { ApolloClient, registerApolloClient } from "@apollo/client-integration-nextjs";
+//#region src/sdk/client/register-preload-query.d.ts
+export type RegisterPreloadQueryOptions = {
+  /** Storefront GraphQL endpoint. Defaults to `process.env.STOREFRONT_API_URL`. */
+  apiUrl?: string;
+  /** The compiler-emitted context; its three headers ride every RSC-side query. */
+  context?: StorefrontContext;
+  /** Headers forwarded with every RSC-side query. */
+  headers?: Record<string, string>;
+};
+export type PreloadQueryRegistry = ReturnType<typeof registerApolloClient<ApolloClient>>;
+/**
+ * Registers an RSC-only ApolloClient using Apollo's streaming-aware classes and returns the
+ * destructurable `{ getClient, query, PreloadQuery }` shape. Call once at module level in the
+ * generated app (see `templates/nextjs-app/src/utils/query-client.ts`).
+ *
+ * The returned `PreloadQuery` prewarms the cache during RSC; the result is transported via
+ * Apollo's streaming protocol so `useSuspenseQuery` reads it synchronously on the client.
+ */
+export declare function registerPreloadQuery(options?: RegisterPreloadQueryOptions): PreloadQueryRegistry;
+//#endregion
+//# sourceMappingURL=register-preload-query.d.ts.map

package/dist/sdk/client/register-preload-query.js

@@ -0,0 +1,33 @@
+import { buildStorefrontContextHeaders } from "../context/headers.js";
+import { assertValidApiUrl } from "./assert-api-url.js";
+import { HttpLink } from "@apollo/client";
+import { ApolloClient as ApolloClient$1, InMemoryCache as InMemoryCache$1, registerApolloClient } from "@apollo/client-integration-nextjs";
+//#region src/sdk/client/register-preload-query.ts
+/**
+* Registers an RSC-only ApolloClient using Apollo's streaming-aware classes and returns the
+* destructurable `{ getClient, query, PreloadQuery }` shape. Call once at module level in the
+* generated app (see `templates/nextjs-app/src/utils/query-client.ts`).
+*
+* The returned `PreloadQuery` prewarms the cache during RSC; the result is transported via
+* Apollo's streaming protocol so `useSuspenseQuery` reads it synchronously on the client.
+*/
+function registerPreloadQuery(options = {}) {
+	const apiUrl = options.apiUrl ?? process.env.STOREFRONT_API_URL;
+	if (!apiUrl) throw new Error("registerPreloadQuery: `apiUrl` is required. Pass it via options or set the `STOREFRONT_API_URL` environment variable.");
+	assertValidApiUrl(apiUrl, "registerPreloadQuery");
+	const headers = options.context ? {
+		...options.headers,
+		...buildStorefrontContextHeaders(options.context)
+	} : options.headers;
+	return registerApolloClient(() => new ApolloClient$1({
+		cache: new InMemoryCache$1(),
+		link: new HttpLink({
+			uri: apiUrl,
+			...headers ? { headers } : {}
+		})
+	}));
+}
+//#endregion
+export { registerPreloadQuery };
+
+//# sourceMappingURL=register-preload-query.js.map

package/dist/sdk/client/register-preload-query.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"register-preload-query.js","names":["ApolloClient","InMemoryCache"],"sources":["../../../src/sdk/client/register-preload-query.ts"],"sourcesContent":["import { HttpLink } from '@apollo/client';\nimport { ApolloClient, InMemoryCache, registerApolloClient } from '@apollo/client-integration-nextjs';\nimport type { StorefrontContext } from '@vtex/fs-core';\nimport { buildStorefrontContextHeaders } from '../context/headers.js';\nimport { assertValidApiUrl } from './assert-api-url.js';\n\nexport type RegisterPreloadQueryOptions = {\n  /** Storefront GraphQL endpoint. Defaults to `process.env.STOREFRONT_API_URL`. */\n  apiUrl?: string;\n  /** The compiler-emitted context; its three headers ride every RSC-side query. */\n  context?: StorefrontContext;\n  /** Headers forwarded with every RSC-side query. */\n  headers?: Record<string, string>;\n};\n\nexport type PreloadQueryRegistry = ReturnType<typeof registerApolloClient<ApolloClient>>;\n\n/**\n * Registers an RSC-only ApolloClient using Apollo's streaming-aware classes and returns the\n * destructurable `{ getClient, query, PreloadQuery }` shape. Call once at module level in the\n * generated app (see `templates/nextjs-app/src/utils/query-client.ts`).\n *\n * The returned `PreloadQuery` prewarms the cache during RSC; the result is transported via\n * Apollo's streaming protocol so `useSuspenseQuery` reads it synchronously on the client.\n */\nexport function registerPreloadQuery(options: RegisterPreloadQueryOptions = {}): PreloadQueryRegistry {\n  const apiUrl = options.apiUrl ?? process.env.STOREFRONT_API_URL;\n\n  if (!apiUrl) {\n    throw new Error(\n      'registerPreloadQuery: `apiUrl` is required. Pass it via options or set the ' +\n        '`STOREFRONT_API_URL` environment variable.',\n    );\n  }\n\n  assertValidApiUrl(apiUrl, 'registerPreloadQuery');\n\n  // Context headers merge last: a caller cannot contradict the context the app rendered. To request a\n  // different locale, binding or sales channel, pass a different `context`.\n  const headers = options.context\n    ? { ...options.headers, ...buildStorefrontContextHeaders(options.context) }\n    : options.headers;\n\n  return registerApolloClient(\n    () =>\n      new ApolloClient({\n        cache: new InMemoryCache(),\n        link: new HttpLink({\n          uri: apiUrl,\n          ...(headers ? { headers } : {}),\n        }),\n      }),\n  );\n}\n"],"mappings":";;;;;;;;;;;;;AAyBA,SAAgB,qBAAqB,UAAuC,CAAC,GAAyB;CACpG,MAAM,SAAS,QAAQ,UAAU,QAAQ,IAAI;CAE7C,IAAI,CAAC,QACH,MAAM,IAAI,MACR,uHAEF;CAGF,kBAAkB,QAAQ,sBAAsB;CAIhD,MAAM,UAAU,QAAQ,UACpB;EAAE,GAAG,QAAQ;EAAS,GAAG,8BAA8B,QAAQ,OAAO;CAAE,IACxE,QAAQ;CAEZ,OAAO,2BAEH,IAAIA,eAAa;EACf,OAAO,IAAIC,gBAAc;EACzB,MAAM,IAAI,SAAS;GACjB,KAAK;GACL,GAAI,UAAU,EAAE,QAAQ,IAAI,CAAC;EAC/B,CAAC;CACH,CAAC,CACL;AACF"}

package/dist/sdk/content/create-content-runtime.d.ts

@@ -0,0 +1,68 @@
+import { ContentTypeDefinition } from "../../core/dist/define-content-type.js";
+import "../../core/dist/index.js";
+import { FC, ReactNode } from "react";
+//#region src/sdk/content/create-content-runtime.d.ts
+export type ContentRuntimeConfig = {
+  account: string;
+  storeId: string;
+  /** Canonical per-component models, verbatim from the aggregated content catalog, keyed by id. */
+  contentTypes: Record<string, ContentTypeDefinition>;
+};
+/** The coordinates of one composite read. `locale` arrives per call, so one build serves many. */
+export type ReadContentSlicesArgs = {
+  contentTypeId: string;
+  entryId: string;
+  locale: string;
+  /** `element.id → per-component model id` for every content-backed element in the scope. */
+  elements: Record<string, string>;
+};
+/**
+ * The scope's slices, keyed by `element.id`. A key is absent when its element must be omitted — a
+ * missing key, a shape violation, or a whole-entry failure.
+ *
+ * The value type is unchecked on purpose: the generated page forwards it to a component whose
+ * `$content` is `ContentValue<that component's model>`, a type that exists only in the component
+ * package, and an index signature cannot satisfy a model's required properties. Stated once here
+ * rather than cast at every emitted prop; the read below validates every value against its model.
+ */
+export type ContentSlices = {
+  [elementId: string]: any;
+};
+export type ContentEntryBoundaryProps = {
+  /** This element's slice, read at the top of the scope. `undefined` omits the component. */
+  value: unknown;
+  children: ReactNode;
+};
+export type ContentRuntime = {
+  readContentSlices: (args: ReadContentSlicesArgs) => Promise<ContentSlices>;
+  ContentEntryBoundary: FC<ContentEntryBoundaryProps>;
+};
+/**
+ * Internal result taxonomy: a read either finds a validated composite blob or fails for a definite,
+ * loggable reason. A transient upstream failure resolves `found` from the last-good store below when
+ * that store holds the entry, and degrades to `unavailable` — omitting the affected components —
+ * only when it does not.
+ */
+export type ContentEntryResult = {
+  status: 'found';
+  blob: Record<string, unknown>;
+} | {
+  status: 'not-found';
+} | {
+  status: 'unavailable';
+  reason: string;
+} | {
+  status: 'invalid';
+  reason: string;
+};
+/**
+ * Creates the one server-side content read surface for a store: a `React.cache`-deduped
+ * `readContentSlices` the generated page or layout awaits once at the top, and the
+ * `ContentEntryBoundary` the compiler wraps around each content-backed element. One read per scope
+ * yields every element's `$content` value keyed by `element.id`, so a page issues at most two Data
+ * Plane reads (its own entry plus its layout's) regardless of content-backed component count. Draft
+ * Mode switches the same read to Control Plane's preview endpoint through a server-only credential.
+ */
+export declare function createContentRuntime(config: ContentRuntimeConfig): ContentRuntime;
+//#endregion
+//# sourceMappingURL=create-content-runtime.d.ts.map