@vtex/faststore 0.0.1

package/dist/sdk/shipping/shipping-operations.js

@@ -0,0 +1,77 @@
+import { gql } from "../graphql-tag.js";
+import { CartFragment } from "../cart/operations.js";
+//#region src/sdk/shipping/shipping-operations.ts
+/**
+* The one client-synthesized error code, carried by the userError that `setAddress` *resolves*
+* (never throws) when the mutation fails at the transport/top-level-GraphQL layer. Consumers use
+* it to route the resolved synthetic failure to the generic upstream error state (Decision 5),
+* distinct from the domain `userErrors` codes that render inline.
+*/
+const SHIPPING_NETWORK_ERROR_CODE = "NETWORK_ERROR";
+const SHIPPING_ADDRESS_UPDATE = gql`
+  mutation ShippingAddressUpdate($input: ShippingAddressUpdateInput!) {
+    shippingAddressUpdate(input: $input) {
+      shipping {
+        __typename
+        id
+        address {
+          __typename
+          id
+          recipientName
+          postalCode
+          country
+          street
+          number
+          complement
+          neighborhood
+          city
+          state
+        }
+        savedAddresses {
+          __typename
+          id
+          recipientName
+          postalCode
+          country
+          street
+          number
+          complement
+          neighborhood
+          city
+          state
+        }
+        options {
+          __typename
+          id
+          name
+          channel
+          shippingEstimate {
+            value
+            unit
+          }
+          price {
+            amount
+            currencyCode
+          }
+          listPrice {
+            amount
+            currencyCode
+          }
+        }
+        selectedOptionId
+      }
+      cart {
+        ...CartFragment
+      }
+      userErrors {
+        code
+        message
+      }
+    }
+  }
+  ${CartFragment}
+`;
+//#endregion
+export { SHIPPING_ADDRESS_UPDATE, SHIPPING_NETWORK_ERROR_CODE };
+
+//# sourceMappingURL=shipping-operations.js.map

package/dist/sdk/shipping/shipping-operations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shipping-operations.js","names":[],"sources":["../../../src/sdk/shipping/shipping-operations.ts"],"sourcesContent":["import type { TypedDocumentNode } from '@apollo/client';\nimport { type CartEntity, CartFragment } from '../cart/operations.js';\nimport { gql } from '../graphql-tag.js';\n\n/**\n * Shipping address mutation documents (specs/shipping-address-step.md, US-7).\n *\n * Authored with the hand `gql` tag — the codegen `graphql()` factory is reserved for the reactive\n * read path (`operations.ts`) — and explicitly excluded from the codegen `documents` glob (see\n * `codegen.ts`): the `gql` tag alone is still plucked by `graphql-codegen`, which would duplicate\n * these hand-written types in `sdk/generated/`. The mutation stays hand-typed as a\n * `TypedDocumentNode` (Decision 3 in the spec). The payload projects the full refreshed `shipping`\n * and `cart` state, so the response write into the cache *is* the post-update refresh: `Shipping`'s\n * reactive read flips with no refetch and no imperative cache write.\n *\n * Failures follow ADR-00007's two-path contract: domain outcomes arrive as payload `userErrors`\n * (`ShippingAddressUpdateError`); transport and top-level GraphQL failures are infrastructure,\n * mapped by the handlers in `use-shipping-actions.ts` to the one client-synthesized code,\n * `NETWORK_USER_ERROR`.\n */\n\n/** A typed address-update failure; NETWORK_USER_ERROR is the one client-synthesized code. */\nexport type ShippingAddressUpdateErrorEntity = Readonly<{ code: string; message: string }>;\n\n/**\n * The one client-synthesized error code, carried by the userError that `setAddress` *resolves*\n * (never throws) when the mutation fails at the transport/top-level-GraphQL layer. Consumers use\n * it to route the resolved synthetic failure to the generic upstream error state (Decision 5),\n * distinct from the domain `userErrors` codes that render inline.\n */\nexport const SHIPPING_NETWORK_ERROR_CODE = 'NETWORK_ERROR';\n\nexport type ShippingAddressInput = Readonly<{\n  savedAddressId?: string;\n  recipientName: string;\n  postalCode: string;\n  country: string;\n  street?: string;\n  number?: string;\n  complement?: string;\n  neighborhood?: string;\n  city?: string;\n  state?: string;\n}>;\n\n/** The full shippingAddressUpdate mutation payload. */\nexport type ShippingAddressUpdatePayloadEntity = Readonly<{\n  __typename: 'ShippingAddressUpdatePayload';\n  shipping: {\n    __typename: 'Shipping';\n    id: string;\n    address: {\n      __typename: 'Address';\n      id?: string | null;\n      recipientName?: string | null;\n      postalCode?: string | null;\n      country: string;\n      street?: string | null;\n      number?: string | null;\n      complement?: string | null;\n      neighborhood?: string | null;\n      city?: string | null;\n      state?: string | null;\n    } | null;\n    savedAddresses: ReadonlyArray<{\n      __typename: 'Address';\n      id?: string | null;\n      recipientName?: string | null;\n      postalCode?: string | null;\n      country: string;\n      street?: string | null;\n      number?: string | null;\n      complement?: string | null;\n      neighborhood?: string | null;\n      city?: string | null;\n      state?: string | null;\n    }>;\n    options: ReadonlyArray<{\n      __typename: 'ShippingOption';\n      id: string;\n      name: string;\n      channel: string;\n      shippingEstimate: { __typename: 'ShippingEstimate'; value: number; unit: string };\n      price: { __typename: 'Money'; amount: number; currencyCode: string };\n      listPrice: { __typename: 'Money'; amount: number; currencyCode: string };\n    }>;\n    selectedOptionId?: string | null;\n  } | null;\n  cart: CartEntity;\n  userErrors: readonly ShippingAddressUpdateErrorEntity[];\n}>;\n\ntype ShippingAddressUpdateData = Readonly<{ shippingAddressUpdate: ShippingAddressUpdatePayloadEntity }>;\n\nexport const SHIPPING_ADDRESS_UPDATE: TypedDocumentNode<ShippingAddressUpdateData, { input: ShippingAddressInput }> =\n  gql`\n  mutation ShippingAddressUpdate($input: ShippingAddressUpdateInput!) {\n    shippingAddressUpdate(input: $input) {\n      shipping {\n        __typename\n        id\n        address {\n          __typename\n          id\n          recipientName\n          postalCode\n          country\n          street\n          number\n          complement\n          neighborhood\n          city\n          state\n        }\n        savedAddresses {\n          __typename\n          id\n          recipientName\n          postalCode\n          country\n          street\n          number\n          complement\n          neighborhood\n          city\n          state\n        }\n        options {\n          __typename\n          id\n          name\n          channel\n          shippingEstimate {\n            value\n            unit\n          }\n          price {\n            amount\n            currencyCode\n          }\n          listPrice {\n            amount\n            currencyCode\n          }\n        }\n        selectedOptionId\n      }\n      cart {\n        ...CartFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n  ${CartFragment}\n`;\n"],"mappings":";;;;;;;;;AA8BA,MAAa,8BAA8B;AAgE3C,MAAa,0BACX,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA6DD,aAAa"}

package/dist/sdk/shipping/use-cart-shipping-simulation.d.ts

@@ -0,0 +1,7 @@
+import { CartShippingSimulateInput } from "../generated/graphql.js";
+import "./cart-operations.js";
+import { ShippingSimulationPayload } from "../../matter/shipping-simulator/shipping-simulator.js";
+//#region src/sdk/shipping/use-cart-shipping-simulation.d.ts
+export declare function useCartShippingSimulation(): (input: CartShippingSimulateInput) => Promise<ShippingSimulationPayload>;
+//#endregion
+//# sourceMappingURL=use-cart-shipping-simulation.d.ts.map

package/dist/sdk/shipping/use-cart-shipping-simulation.js

@@ -0,0 +1,72 @@
+"use client";
+import { CART_SHIPPING_SIMULATION } from "./cart-operations.js";
+import { withRequestTimeout } from "./request-timeout.js";
+import { getApolloContext } from "@apollo/client/react";
+import { useCallback, useContext } from "react";
+//#region src/sdk/shipping/use-cart-shipping-simulation.ts
+const UNKNOWN_ERROR = {
+	code: "UNKNOWN",
+	message: "Unable to calculate shipping. Try again."
+};
+function mapErrorCode(code) {
+	return code === "INVALID_POSTAL_CODE" ? "INVALID_POSTAL_CODE" : "UNKNOWN";
+}
+function mapOption(option) {
+	return {
+		id: option.id,
+		name: option.name,
+		channel: option.channel,
+		shippingEstimate: option.shippingEstimate,
+		price: {
+			amount: option.price.amount,
+			currencyCode: option.price.currencyCode
+		},
+		listPrice: {
+			amount: option.listPrice.amount,
+			currencyCode: option.listPrice.currencyCode
+		}
+	};
+}
+function useCartShippingSimulation() {
+	const { client } = useContext(getApolloContext());
+	return useCallback(async (input) => {
+		if (!client) return {
+			shippingOptions: null,
+			userErrors: [UNKNOWN_ERROR]
+		};
+		try {
+			const result = await withRequestTimeout((signal) => client.query({
+				query: CART_SHIPPING_SIMULATION,
+				variables: { input },
+				fetchPolicy: "no-cache",
+				context: { fetchOptions: { signal } }
+			}));
+			if (result.error || !result.data) return {
+				shippingOptions: null,
+				userErrors: [UNKNOWN_ERROR]
+			};
+			const payload = result.data.cartShippingSimulation;
+			const userErrors = payload.userErrors.map((error) => ({
+				code: mapErrorCode(error.code),
+				message: error.message
+			}));
+			if (userErrors.length > 0) return {
+				shippingOptions: null,
+				userErrors
+			};
+			return {
+				shippingOptions: payload.shippingOptions?.map(mapOption) ?? null,
+				userErrors: []
+			};
+		} catch {
+			return {
+				shippingOptions: null,
+				userErrors: [UNKNOWN_ERROR]
+			};
+		}
+	}, [client]);
+}
+//#endregion
+export { useCartShippingSimulation };
+
+//# sourceMappingURL=use-cart-shipping-simulation.js.map

package/dist/sdk/shipping/use-cart-shipping-simulation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-cart-shipping-simulation.js","names":[],"sources":["../../../src/sdk/shipping/use-cart-shipping-simulation.ts"],"sourcesContent":["'use client';\n\nimport { getApolloContext } from '@apollo/client/react';\nimport { useCallback, useContext } from 'react';\nimport type {\n  ShippingOption,\n  ShippingSimulateError,\n  ShippingSimulationPayload,\n} from '../../matter/shipping-simulator/shipping-simulator.js';\nimport type { CartShippingSimulationQuery, ShippingSimulateErrorCode } from '../generated/graphql.js';\nimport { CART_SHIPPING_SIMULATION, type CartShippingSimulateInput } from './cart-operations.js';\nimport { withRequestTimeout } from './request-timeout.js';\n\n/**\n * Cart-scoped shipping-simulation SDK hook.\n *\n * Returns the calculator's `onSimulate(input) => Promise<payload>` callback. It runs the\n * `CartShippingSimulation` query imperatively per submit via the Apollo client read from\n * `getApolloContext()` (a non-throwing read, mirroring `useShippingSimulation`). The input carries\n * a destination only — items come from the cart via `x-order-form-id`, resolved server-side. The\n * mapping matches the PDP hook: the structured `ShippingEstimate { value, unit }` is carried through\n * untouched (the component localizes it), the API `Money` is carried as `{ amount, currencyCode }`,\n * and any transport/GraphQL failure is collapsed to one `UNKNOWN` userError so the calculator's\n * success/error transition stays deterministic.\n */\n\n// The calculator's domain payload is the seam's own type, imported from the component so the\n// binding is a direct assignment and the types never drift from the contract the component's tests\n// assert.\ntype RawOption = NonNullable<CartShippingSimulationQuery['cartShippingSimulation']['shippingOptions']>[number];\n\nconst UNKNOWN_ERROR: ShippingSimulateError = {\n  code: 'UNKNOWN',\n  message: 'Unable to calculate shipping. Try again.',\n};\n\nfunction mapErrorCode(code: ShippingSimulateErrorCode): ShippingSimulateError['code'] {\n  return code === 'INVALID_POSTAL_CODE' ? 'INVALID_POSTAL_CODE' : 'UNKNOWN';\n}\n\nfunction mapOption(option: RawOption): ShippingOption {\n  return {\n    id: option.id,\n    name: option.name,\n    channel: option.channel,\n    shippingEstimate: option.shippingEstimate,\n    price: { amount: option.price.amount, currencyCode: option.price.currencyCode },\n    listPrice: { amount: option.listPrice.amount, currencyCode: option.listPrice.currencyCode },\n  };\n}\n\nexport function useCartShippingSimulation(): (input: CartShippingSimulateInput) => Promise<ShippingSimulationPayload> {\n  // Read the client off Apollo's context directly rather than via `useApolloClient`, which throws at\n  // render when no provider is present. The hook is the calculator's default `onSimulate` and runs\n  // in every Root render, including presentational tests/stories that mount the Root with their own\n  // callback and no ApolloProvider; a missing client only matters when the default callback is\n  // actually invoked, where it is mapped to the same UNKNOWN userError as any other failure.\n  const { client } = useContext(getApolloContext());\n\n  return useCallback(\n    async (input: CartShippingSimulateInput): Promise<ShippingSimulationPayload> => {\n      if (!client) {\n        return { shippingOptions: null, userErrors: [UNKNOWN_ERROR] };\n      }\n      try {\n        const result = await withRequestTimeout((signal) =>\n          client.query({\n            query: CART_SHIPPING_SIMULATION,\n            variables: { input },\n            fetchPolicy: 'no-cache',\n            context: { fetchOptions: { signal } },\n          }),\n        );\n\n        if (result.error || !result.data) {\n          return { shippingOptions: null, userErrors: [UNKNOWN_ERROR] };\n        }\n\n        const payload = result.data.cartShippingSimulation;\n        const userErrors = payload.userErrors.map((error) => ({\n          code: mapErrorCode(error.code),\n          message: error.message,\n        }));\n\n        if (userErrors.length > 0) {\n          return { shippingOptions: null, userErrors };\n        }\n\n        return {\n          shippingOptions: payload.shippingOptions?.map(mapOption) ?? null,\n          userErrors: [],\n        };\n      } catch {\n        return { shippingOptions: null, userErrors: [UNKNOWN_ERROR] };\n      }\n    },\n    [client],\n  );\n}\n"],"mappings":";;;;;;AA+BA,MAAM,gBAAuC;CAC3C,MAAM;CACN,SAAS;AACX;AAEA,SAAS,aAAa,MAAgE;CACpF,OAAO,SAAS,wBAAwB,wBAAwB;AAClE;AAEA,SAAS,UAAU,QAAmC;CACpD,OAAO;EACL,IAAI,OAAO;EACX,MAAM,OAAO;EACb,SAAS,OAAO;EAChB,kBAAkB,OAAO;EACzB,OAAO;GAAE,QAAQ,OAAO,MAAM;GAAQ,cAAc,OAAO,MAAM;EAAa;EAC9E,WAAW;GAAE,QAAQ,OAAO,UAAU;GAAQ,cAAc,OAAO,UAAU;EAAa;CAC5F;AACF;AAEA,SAAgB,4BAAsG;CAMpH,MAAM,EAAE,WAAW,WAAW,iBAAiB,CAAC;CAEhD,OAAO,YACL,OAAO,UAAyE;EAC9E,IAAI,CAAC,QACH,OAAO;GAAE,iBAAiB;GAAM,YAAY,CAAC,aAAa;EAAE;EAE9D,IAAI;GACF,MAAM,SAAS,MAAM,oBAAoB,WACvC,OAAO,MAAM;IACX,OAAO;IACP,WAAW,EAAE,MAAM;IACnB,aAAa;IACb,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE;GACtC,CAAC,CACH;GAEA,IAAI,OAAO,SAAS,CAAC,OAAO,MAC1B,OAAO;IAAE,iBAAiB;IAAM,YAAY,CAAC,aAAa;GAAE;GAG9D,MAAM,UAAU,OAAO,KAAK;GAC5B,MAAM,aAAa,QAAQ,WAAW,KAAK,WAAW;IACpD,MAAM,aAAa,MAAM,IAAI;IAC7B,SAAS,MAAM;GACjB,EAAE;GAEF,IAAI,WAAW,SAAS,GACtB,OAAO;IAAE,iBAAiB;IAAM;GAAW;GAG7C,OAAO;IACL,iBAAiB,QAAQ,iBAAiB,IAAI,SAAS,KAAK;IAC5D,YAAY,CAAC;GACf;EACF,QAAQ;GACN,OAAO;IAAE,iBAAiB;IAAM,YAAY,CAAC,aAAa;GAAE;EAC9D;CACF,GACA,CAAC,MAAM,CACT;AACF"}

package/dist/sdk/shipping/use-shipping-actions.d.ts

@@ -0,0 +1,27 @@
+import "../../core/dist/index.js";
+import { ShippingOptionSelectUserError } from "./option-select-operations.js";
+import { ShippingAddressInput, ShippingAddressUpdateErrorEntity } from "./shipping-operations.js";
+//#region src/sdk/shipping/use-shipping-actions.d.ts
+/**
+ * The `shipping` action namespace — the sanctioned client write surface against the VTEX orderForm
+ * shippingData: delivery-address updates (specs/shipping-address-step.md, US-7;
+ * docs/storefront-core/adr-0010-actions-own-the-write-side.md) and cart-scoped delivery-option
+ * selection (specs/delivery-options-step.md, Decision 4). Per Decision 4 the two tasks share this one
+ * namespace — T2 (`setAddress`) merged first and owns the registration, T3 extends it with
+ * `selectOption` here.
+ *
+ * Both actions are async/pessimistic (Decision 1 of the address spec): the handler awaits the
+ * mutation and only the server-confirmed payload changes the cache. Each is stateless (no reactive
+ * vars, no module state), resolves its payload `userErrors` (empty on success), and never throws for
+ * expected outcomes; an infrastructure failure (network or an upstream GraphQLError) is caught and
+ * collapsed to one synthetic network `userError` — no per-code branching (US-4, FR-5). Inputs pass
+ * through mutation variables only — never logged, never stored beyond the cache.
+ */
+export type ShippingActions = Readonly<{
+  /** Persist the single delivery address (async/pessimistic). Resolves the payload userErrors. */
+  setAddress: (address: ShippingAddressInput) => Promise<readonly ShippingAddressUpdateErrorEntity[]>;
+  /** Select a delivery option for the whole cart. Resolves the payload userErrors (empty on success). */
+  selectOption: (optionId: string) => Promise<readonly ShippingOptionSelectUserError[]>;
+}>;
+//#endregion
+//# sourceMappingURL=use-shipping-actions.d.ts.map

package/dist/sdk/shipping/use-shipping-actions.js

@@ -0,0 +1,113 @@
+"use client";
+import { defineActions } from "../../core/dist/actions/registry.js";
+import "../../core/dist/index.js";
+import { SHIPPING_ADDRESS_UPDATE, SHIPPING_NETWORK_ERROR_CODE } from "./shipping-operations.js";
+import { SHIPPING_OPTION_SELECT } from "./option-select-operations.js";
+import { useMutation } from "@apollo/client/react";
+import { useCallback, useMemo } from "react";
+//#region src/sdk/shipping/use-shipping-actions.ts
+const SET_ADDRESS_NETWORK_ERROR = {
+	code: SHIPPING_NETWORK_ERROR_CODE,
+	message: "Unable to complete the request. Please try again."
+};
+const SELECT_OPTION_NETWORK_ERROR = {
+	code: "NETWORK_ERROR",
+	message: "Unable to update the delivery option. Please try again."
+};
+/**
+* The `shipping` namespace hook. Registered with the first-party action registry via `shippingActions`
+* below; the compiler-emitted `ShippingActionProvider` calls it and threads the narrowed methods into
+* each consumer's `$actions.shipping`. Writes persist purely through the normalized-cache merge of
+* each mutation response (Decision 2 of the address spec) — no refetch, no imperative write.
+*/
+function useShippingActions() {
+	const [addressMutation] = useMutation(SHIPPING_ADDRESS_UPDATE);
+	const [selectOptionMutation] = useMutation(SHIPPING_OPTION_SELECT);
+	const setAddress = useCallback(async (address) => {
+		try {
+			return (await addressMutation({ variables: { input: address } })).data?.shippingAddressUpdate.userErrors ?? [];
+		} catch (error) {
+			console.error("[shipping.setAddress] shippingAddressUpdate failed", error);
+			return [SET_ADDRESS_NETWORK_ERROR];
+		}
+	}, [addressMutation]);
+	const selectOption = useCallback(async (optionId) => {
+		try {
+			return (await selectOptionMutation({ variables: { input: { optionId } } })).data?.shippingOptionSelect.userErrors ?? [];
+		} catch (error) {
+			console.error("[shipping.selectOption] shippingOptionSelect failed", error);
+			return [SELECT_OPTION_NETWORK_ERROR];
+		}
+	}, [selectOptionMutation]);
+	return useMemo(() => ({
+		setAddress,
+		selectOption
+	}), [setAddress, selectOption]);
+}
+defineActions({
+	namespace: "shipping",
+	description: "Mutation-backed delivery writes against the VTEX orderForm shippingData (address in T2; option in T3).",
+	provider: {
+		name: "ShippingActionProvider",
+		importPath: "@vtex/faststore/internal/client"
+	},
+	methods: {
+		setAddress: {
+			description: "Persist the single delivery address in one submit (async/pessimistic). Resolves the payload userErrors.",
+			payload: [
+				{
+					name: "savedAddressId",
+					type: "string"
+				},
+				{
+					name: "recipientName",
+					type: "string"
+				},
+				{
+					name: "postalCode",
+					type: "string"
+				},
+				{
+					name: "country",
+					type: "string"
+				},
+				{
+					name: "street",
+					type: "string"
+				},
+				{
+					name: "number",
+					type: "string"
+				},
+				{
+					name: "complement",
+					type: "string"
+				},
+				{
+					name: "neighborhood",
+					type: "string"
+				},
+				{
+					name: "city",
+					type: "string"
+				},
+				{
+					name: "state",
+					type: "string"
+				}
+			]
+		},
+		selectOption: {
+			description: "Select a delivery option for the whole cart (async/pessimistic). Resolves the payload userErrors.",
+			payload: [{
+				name: "optionId",
+				type: "string"
+			}]
+		}
+	},
+	use: useShippingActions
+});
+//#endregion
+export { useShippingActions };
+
+//# sourceMappingURL=use-shipping-actions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-shipping-actions.js","names":[],"sources":["../../../src/sdk/shipping/use-shipping-actions.ts"],"sourcesContent":["'use client';\n\nimport { useMutation } from '@apollo/client/react';\nimport { defineActions } from '@vtex/fs-core';\nimport { useCallback, useMemo } from 'react';\nimport { SHIPPING_OPTION_SELECT, type ShippingOptionSelectUserError } from './option-select-operations.js';\nimport {\n  SHIPPING_ADDRESS_UPDATE,\n  SHIPPING_NETWORK_ERROR_CODE,\n  type ShippingAddressInput,\n  type ShippingAddressUpdateErrorEntity,\n} from './shipping-operations.js';\n\n/**\n * The `shipping` action namespace — the sanctioned client write surface against the VTEX orderForm\n * shippingData: delivery-address updates (specs/shipping-address-step.md, US-7;\n * docs/storefront-core/adr-0010-actions-own-the-write-side.md) and cart-scoped delivery-option\n * selection (specs/delivery-options-step.md, Decision 4). Per Decision 4 the two tasks share this one\n * namespace — T2 (`setAddress`) merged first and owns the registration, T3 extends it with\n * `selectOption` here.\n *\n * Both actions are async/pessimistic (Decision 1 of the address spec): the handler awaits the\n * mutation and only the server-confirmed payload changes the cache. Each is stateless (no reactive\n * vars, no module state), resolves its payload `userErrors` (empty on success), and never throws for\n * expected outcomes; an infrastructure failure (network or an upstream GraphQLError) is caught and\n * collapsed to one synthetic network `userError` — no per-code branching (US-4, FR-5). Inputs pass\n * through mutation variables only — never logged, never stored beyond the cache.\n */\nexport type ShippingActions = Readonly<{\n  /** Persist the single delivery address (async/pessimistic). Resolves the payload userErrors. */\n  setAddress: (address: ShippingAddressInput) => Promise<readonly ShippingAddressUpdateErrorEntity[]>;\n  /** Select a delivery option for the whole cart. Resolves the payload userErrors (empty on success). */\n  selectOption: (optionId: string) => Promise<readonly ShippingOptionSelectUserError[]>;\n}>;\n\nconst SET_ADDRESS_NETWORK_ERROR: ShippingAddressUpdateErrorEntity = {\n  code: SHIPPING_NETWORK_ERROR_CODE,\n  message: 'Unable to complete the request. Please try again.',\n};\n\nconst SELECT_OPTION_NETWORK_ERROR: ShippingOptionSelectUserError = {\n  code: 'NETWORK_ERROR',\n  message: 'Unable to update the delivery option. Please try again.',\n};\n\n/**\n * The `shipping` namespace hook. Registered with the first-party action registry via `shippingActions`\n * below; the compiler-emitted `ShippingActionProvider` calls it and threads the narrowed methods into\n * each consumer's `$actions.shipping`. Writes persist purely through the normalized-cache merge of\n * each mutation response (Decision 2 of the address spec) — no refetch, no imperative write.\n */\nexport function useShippingActions(): ShippingActions {\n  const [addressMutation] = useMutation(SHIPPING_ADDRESS_UPDATE);\n  const [selectOptionMutation] = useMutation(SHIPPING_OPTION_SELECT);\n\n  const setAddress = useCallback<ShippingActions['setAddress']>(\n    async (address) => {\n      try {\n        const result = await addressMutation({ variables: { input: address } });\n        return result.data?.shippingAddressUpdate.userErrors ?? [];\n      } catch (error) {\n        console.error('[shipping.setAddress] shippingAddressUpdate failed', error);\n        return [SET_ADDRESS_NETWORK_ERROR];\n      }\n    },\n    [addressMutation],\n  );\n\n  const selectOption = useCallback<ShippingActions['selectOption']>(\n    async (optionId) => {\n      try {\n        const result = await selectOptionMutation({ variables: { input: { optionId } } });\n        return result.data?.shippingOptionSelect.userErrors ?? [];\n      } catch (error) {\n        console.error('[shipping.selectOption] shippingOptionSelect failed', error);\n        return [SELECT_OPTION_NETWORK_ERROR];\n      }\n    },\n    [selectOptionMutation],\n  );\n\n  return useMemo(() => ({ setAddress, selectOption }), [setAddress, selectOption]);\n}\n\n/**\n * Declares the `shipping` action namespace — the single source of truth for its method/payload\n * metadata, runtime provider, and `use` hook (mirrors `cartActions`, `sessionActions`). The native\n * catalog builder (`scripts/build-catalog.mjs`) statically reads this call to emit `actions.json`;\n * at runtime `ShippingActionProvider` calls `useShippingActions` directly.\n */\nexport const shippingActions = defineActions({\n  namespace: 'shipping',\n  description: 'Mutation-backed delivery writes against the VTEX orderForm shippingData (address in T2; option in T3).',\n  provider: { name: 'ShippingActionProvider', importPath: '@vtex/faststore/internal/client' },\n  methods: {\n    setAddress: {\n      description:\n        'Persist the single delivery address in one submit (async/pessimistic). Resolves the payload userErrors.',\n      payload: [\n        { name: 'savedAddressId', type: 'string' },\n        { name: 'recipientName', type: 'string' },\n        { name: 'postalCode', type: 'string' },\n        { name: 'country', type: 'string' },\n        { name: 'street', type: 'string' },\n        { name: 'number', type: 'string' },\n        { name: 'complement', type: 'string' },\n        { name: 'neighborhood', type: 'string' },\n        { name: 'city', type: 'string' },\n        { name: 'state', type: 'string' },\n      ],\n    },\n    selectOption: {\n      description: 'Select a delivery option for the whole cart (async/pessimistic). Resolves the payload userErrors.',\n      payload: [{ name: 'optionId', type: 'string' }],\n    },\n  },\n  use: useShippingActions,\n});\n"],"mappings":";;;;;;;;AAmCA,MAAM,4BAA8D;CAClE,MAAM;CACN,SAAS;AACX;AAEA,MAAM,8BAA6D;CACjE,MAAM;CACN,SAAS;AACX;;;;;;;AAQA,SAAgB,qBAAsC;CACpD,MAAM,CAAC,mBAAmB,YAAY,uBAAuB;CAC7D,MAAM,CAAC,wBAAwB,YAAY,sBAAsB;CAEjE,MAAM,aAAa,YACjB,OAAO,YAAY;EACjB,IAAI;GAEF,QAAO,MADc,gBAAgB,EAAE,WAAW,EAAE,OAAO,QAAQ,EAAE,CAAC,EAAA,CACxD,MAAM,sBAAsB,cAAc,CAAC;EAC3D,SAAS,OAAO;GACd,QAAQ,MAAM,sDAAsD,KAAK;GACzE,OAAO,CAAC,yBAAyB;EACnC;CACF,GACA,CAAC,eAAe,CAClB;CAEA,MAAM,eAAe,YACnB,OAAO,aAAa;EAClB,IAAI;GAEF,QAAO,MADc,qBAAqB,EAAE,WAAW,EAAE,OAAO,EAAE,SAAS,EAAE,EAAE,CAAC,EAAA,CAClE,MAAM,qBAAqB,cAAc,CAAC;EAC1D,SAAS,OAAO;GACd,QAAQ,MAAM,uDAAuD,KAAK;GAC1E,OAAO,CAAC,2BAA2B;EACrC;CACF,GACA,CAAC,oBAAoB,CACvB;CAEA,OAAO,eAAe;EAAE;EAAY;CAAa,IAAI,CAAC,YAAY,YAAY,CAAC;AACjF;AAQ+B,cAAc;CAC3C,WAAW;CACX,aAAa;CACb,UAAU;EAAE,MAAM;EAA0B,YAAY;CAAkC;CAC1F,SAAS;EACP,YAAY;GACV,aACE;GACF,SAAS;IACP;KAAE,MAAM;KAAkB,MAAM;IAAS;IACzC;KAAE,MAAM;KAAiB,MAAM;IAAS;IACxC;KAAE,MAAM;KAAc,MAAM;IAAS;IACrC;KAAE,MAAM;KAAW,MAAM;IAAS;IAClC;KAAE,MAAM;KAAU,MAAM;IAAS;IACjC;KAAE,MAAM;KAAU,MAAM;IAAS;IACjC;KAAE,MAAM;KAAc,MAAM;IAAS;IACrC;KAAE,MAAM;KAAgB,MAAM;IAAS;IACvC;KAAE,MAAM;KAAQ,MAAM;IAAS;IAC/B;KAAE,MAAM;KAAS,MAAM;IAAS;GAClC;EACF;EACA,cAAc;GACZ,aAAa;GACb,SAAS,CAAC;IAAE,MAAM;IAAY,MAAM;GAAS,CAAC;EAChD;CACF;CACA,KAAK;AACP,CAAC"}

package/dist/sdk/shipping/use-shipping-simulation.d.ts

@@ -0,0 +1,7 @@
+import { ShippingSimulateInput } from "../generated/graphql.js";
+import "./operations.js";
+import { ShippingSimulationPayload } from "../../matter/shipping-simulator/shipping-simulator.js";
+//#region src/sdk/shipping/use-shipping-simulation.d.ts
+export declare function useShippingSimulation(): (input: ShippingSimulateInput) => Promise<ShippingSimulationPayload>;
+//#endregion
+//# sourceMappingURL=use-shipping-simulation.d.ts.map

package/dist/sdk/shipping/use-shipping-simulation.js

@@ -0,0 +1,72 @@
+"use client";
+import { withRequestTimeout } from "./request-timeout.js";
+import { SHIPPING_SIMULATION } from "./operations.js";
+import { getApolloContext } from "@apollo/client/react";
+import { useCallback, useContext } from "react";
+//#region src/sdk/shipping/use-shipping-simulation.ts
+const UNKNOWN_ERROR = {
+	code: "UNKNOWN",
+	message: "Unable to calculate shipping. Try again."
+};
+function mapErrorCode(code) {
+	return code === "INVALID_POSTAL_CODE" ? "INVALID_POSTAL_CODE" : "UNKNOWN";
+}
+function mapOption(option) {
+	return {
+		id: option.id,
+		name: option.name,
+		channel: option.channel,
+		shippingEstimate: option.shippingEstimate,
+		price: {
+			amount: option.price.amount,
+			currencyCode: option.price.currencyCode
+		},
+		listPrice: {
+			amount: option.listPrice.amount,
+			currencyCode: option.listPrice.currencyCode
+		}
+	};
+}
+function useShippingSimulation() {
+	const { client } = useContext(getApolloContext());
+	return useCallback(async (input) => {
+		if (!client) return {
+			shippingOptions: null,
+			userErrors: [UNKNOWN_ERROR]
+		};
+		try {
+			const result = await withRequestTimeout((signal) => client.query({
+				query: SHIPPING_SIMULATION,
+				variables: { input },
+				fetchPolicy: "no-cache",
+				context: { fetchOptions: { signal } }
+			}));
+			if (result.error || !result.data) return {
+				shippingOptions: null,
+				userErrors: [UNKNOWN_ERROR]
+			};
+			const payload = result.data.shippingSimulation;
+			const userErrors = payload.userErrors.map((error) => ({
+				code: mapErrorCode(error.code),
+				message: error.message
+			}));
+			if (userErrors.length > 0) return {
+				shippingOptions: null,
+				userErrors
+			};
+			return {
+				shippingOptions: payload.shippingOptions?.map(mapOption) ?? null,
+				userErrors: []
+			};
+		} catch {
+			return {
+				shippingOptions: null,
+				userErrors: [UNKNOWN_ERROR]
+			};
+		}
+	}, [client]);
+}
+//#endregion
+export { useShippingSimulation };
+
+//# sourceMappingURL=use-shipping-simulation.js.map

package/dist/sdk/shipping/use-shipping-simulation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-shipping-simulation.js","names":[],"sources":["../../../src/sdk/shipping/use-shipping-simulation.ts"],"sourcesContent":["'use client';\n\nimport { getApolloContext } from '@apollo/client/react';\nimport { useCallback, useContext } from 'react';\nimport type {\n  ShippingOption,\n  ShippingSimulateError,\n  ShippingSimulationPayload,\n} from '../../matter/shipping-simulator/shipping-simulator.js';\nimport type { ShippingSimulateErrorCode, ShippingSimulationQuery } from '../generated/graphql.js';\nimport { SHIPPING_SIMULATION, type ShippingSimulateInput } from './operations.js';\nimport { withRequestTimeout } from './request-timeout.js';\n\n/**\n * Shipping-simulation SDK hook (FSPG-815 / specs/fspg-815-minicart-wire-shipping-simulator-pdp.md).\n *\n * Returns the simulator's `onSimulate(input) => Promise<payload>` callback. It runs the\n * `ShippingSimulation` query imperatively per submit via the Apollo client read from\n * `getApolloContext()` (a non-throwing read; see the inline note below). The mapping is thin: the\n * structured `ShippingEstimate { value, unit }` is carried through untouched (the component\n * localizes it, where the `locale` lives), the API `Money` is carried as `{ amount, currencyCode }`,\n * and any transport/GraphQL failure is collapsed to one `UNKNOWN` userError so the component's\n * success/error transition stays deterministic.\n */\n\n// The simulator's domain payload is the seam's own type, imported from the component so the binding\n// is a direct assignment and the types never drift from the contract the component's tests assert.\ntype RawOption = NonNullable<ShippingSimulationQuery['shippingSimulation']['shippingOptions']>[number];\n\nconst UNKNOWN_ERROR: ShippingSimulateError = {\n  code: 'UNKNOWN',\n  message: 'Unable to calculate shipping. Try again.',\n};\n\nfunction mapErrorCode(code: ShippingSimulateErrorCode): ShippingSimulateError['code'] {\n  return code === 'INVALID_POSTAL_CODE' ? 'INVALID_POSTAL_CODE' : 'UNKNOWN';\n}\n\nfunction mapOption(option: RawOption): ShippingOption {\n  return {\n    id: option.id,\n    name: option.name,\n    channel: option.channel,\n    shippingEstimate: option.shippingEstimate,\n    price: { amount: option.price.amount, currencyCode: option.price.currencyCode },\n    listPrice: { amount: option.listPrice.amount, currencyCode: option.listPrice.currencyCode },\n  };\n}\n\nexport function useShippingSimulation(): (input: ShippingSimulateInput) => Promise<ShippingSimulationPayload> {\n  // Read the client off Apollo's context directly rather than via `useApolloClient`, which throws\n  // at render when no provider is present. The hook is the default `onSimulate` and runs in every\n  // Root render, including presentational tests/stories that mount the Root with their own callback\n  // and no ApolloProvider; a missing client only matters when the default callback is actually\n  // invoked, where it is mapped to the same UNKNOWN userError as any other failure.\n  const { client } = useContext(getApolloContext());\n\n  return useCallback(\n    async (input: ShippingSimulateInput): Promise<ShippingSimulationPayload> => {\n      if (!client) {\n        return { shippingOptions: null, userErrors: [UNKNOWN_ERROR] };\n      }\n      try {\n        const result = await withRequestTimeout((signal) =>\n          client.query({\n            query: SHIPPING_SIMULATION,\n            variables: { input },\n            fetchPolicy: 'no-cache',\n            context: { fetchOptions: { signal } },\n          }),\n        );\n\n        if (result.error || !result.data) {\n          return { shippingOptions: null, userErrors: [UNKNOWN_ERROR] };\n        }\n\n        const payload = result.data.shippingSimulation;\n        const userErrors = payload.userErrors.map((error) => ({\n          code: mapErrorCode(error.code),\n          message: error.message,\n        }));\n\n        if (userErrors.length > 0) {\n          return { shippingOptions: null, userErrors };\n        }\n\n        return {\n          shippingOptions: payload.shippingOptions?.map(mapOption) ?? null,\n          userErrors: [],\n        };\n      } catch {\n        return { shippingOptions: null, userErrors: [UNKNOWN_ERROR] };\n      }\n    },\n    [client],\n  );\n}\n"],"mappings":";;;;;;AA6BA,MAAM,gBAAuC;CAC3C,MAAM;CACN,SAAS;AACX;AAEA,SAAS,aAAa,MAAgE;CACpF,OAAO,SAAS,wBAAwB,wBAAwB;AAClE;AAEA,SAAS,UAAU,QAAmC;CACpD,OAAO;EACL,IAAI,OAAO;EACX,MAAM,OAAO;EACb,SAAS,OAAO;EAChB,kBAAkB,OAAO;EACzB,OAAO;GAAE,QAAQ,OAAO,MAAM;GAAQ,cAAc,OAAO,MAAM;EAAa;EAC9E,WAAW;GAAE,QAAQ,OAAO,UAAU;GAAQ,cAAc,OAAO,UAAU;EAAa;CAC5F;AACF;AAEA,SAAgB,wBAA8F;CAM5G,MAAM,EAAE,WAAW,WAAW,iBAAiB,CAAC;CAEhD,OAAO,YACL,OAAO,UAAqE;EAC1E,IAAI,CAAC,QACH,OAAO;GAAE,iBAAiB;GAAM,YAAY,CAAC,aAAa;EAAE;EAE9D,IAAI;GACF,MAAM,SAAS,MAAM,oBAAoB,WACvC,OAAO,MAAM;IACX,OAAO;IACP,WAAW,EAAE,MAAM;IACnB,aAAa;IACb,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE;GACtC,CAAC,CACH;GAEA,IAAI,OAAO,SAAS,CAAC,OAAO,MAC1B,OAAO;IAAE,iBAAiB;IAAM,YAAY,CAAC,aAAa;GAAE;GAG9D,MAAM,UAAU,OAAO,KAAK;GAC5B,MAAM,aAAa,QAAQ,WAAW,KAAK,WAAW;IACpD,MAAM,aAAa,MAAM,IAAI;IAC7B,SAAS,MAAM;GACjB,EAAE;GAEF,IAAI,WAAW,SAAS,GACtB,OAAO;IAAE,iBAAiB;IAAM;GAAW;GAG7C,OAAO;IACL,iBAAiB,QAAQ,iBAAiB,IAAI,SAAS,KAAK;IAC5D,YAAY,CAAC;GACf;EACF,QAAQ;GACN,OAAO;IAAE,iBAAiB;IAAM,YAAY,CAAC,aAAa;GAAE;EAC9D;CACF,GACA,CAAC,MAAM,CACT;AACF"}

package/dist/sdk/state/cart.d.ts

@@ -0,0 +1,42 @@
+//#region src/sdk/state/cart.d.ts
+export declare const orderFormIdVar: import("@apollo/client").ReactiveVar<string | null>;
+/**
+ * Latest `userErrors` from any cart write, surfaced context-free. The cart action hook publishes
+ * here on every call (cleared synchronously at the start of the next call) and `CartError` reads it
+ * via `useReactiveVar`, decoupling error display from `CartRoot`'s data context (specs/actions.md
+ * FR-9). Stays in client state — never a query variable or request header.
+ */
+export declare const cartUserErrorsVar: import("@apollo/client").ReactiveVar<readonly Readonly<{
+  code: string;
+  message: string;
+}>[]>;
+/**
+ * Monotonic add-success pulse. `addItem` increments it on each successful add (no userErrors); the
+ * error and network-catch branches leave it untouched. `CartOpenOnAdd` and `CartRedirectOnAdd` key
+ * a `useEffect` on it via `useReactiveVar`, so every successful add re-fires their behavior even when
+ * the drawer is already open or was just closed — a boolean would not re-fire on an unchanged value
+ * (specs/fspg-822-minicart-open-on-add.md, Decision 2). Client state only — never a query variable
+ * or request header.
+ */
+export declare const cartLastAddVar: import("@apollo/client").ReactiveVar<number>;
+/**
+ * The mini-cart's open state, surfaced context-free. `CartOpenOnAdd` reads it via `useReactiveVar`
+ * to control the `DrawerRoot` and writes it back through `onOpenChange` so the header trigger and
+ * manual close (Escape / backdrop / close button) stay in sync. The single source of truth for the
+ * controlled drawer; `addItem` never writes it. Client state only — never a query variable or
+ * request header.
+ */
+export declare const miniCartOpenVar: import("@apollo/client").ReactiveVar<boolean>;
+/**
+ * Latest `userErrors` from a coupon write (`applyCoupon` / `removeCoupon`), surfaced context-free.
+ * A dedicated channel mirroring `cartUserErrorsVar` so coupon feedback sits next to the coupon form
+ * and never collides with item-write errors (specs/fspg-830-coupon-entry.md AD-2). The coupon
+ * actions publish here on every call (cleared at the start of the next call) and `CartCouponError`
+ * reads it via `useReactiveVar`. Stays in client state — never a query variable or request header.
+ */
+export declare const cartCouponErrorsVar: import("@apollo/client").ReactiveVar<readonly Readonly<{
+  code: string;
+  message: string;
+}>[]>;
+//#endregion
+//# sourceMappingURL=cart.d.ts.map

package/dist/sdk/state/cart.js

@@ -0,0 +1,64 @@
+import { makeVar } from "@apollo/client";
+//#region src/sdk/state/cart.ts
+const orderFormIdVar = makeVar(null);
+/**
+* Latest `userErrors` from any cart write, surfaced context-free. The cart action hook publishes
+* here on every call (cleared synchronously at the start of the next call) and `CartError` reads it
+* via `useReactiveVar`, decoupling error display from `CartRoot`'s data context (specs/actions.md
+* FR-9). Stays in client state — never a query variable or request header.
+*/
+const cartUserErrorsVar = makeVar([]);
+/**
+* Monotonic add-success pulse. `addItem` increments it on each successful add (no userErrors); the
+* error and network-catch branches leave it untouched. `CartOpenOnAdd` and `CartRedirectOnAdd` key
+* a `useEffect` on it via `useReactiveVar`, so every successful add re-fires their behavior even when
+* the drawer is already open or was just closed — a boolean would not re-fire on an unchanged value
+* (specs/fspg-822-minicart-open-on-add.md, Decision 2). Client state only — never a query variable
+* or request header.
+*/
+const cartLastAddVar = makeVar(0);
+/**
+* The mini-cart's open state, surfaced context-free. `CartOpenOnAdd` reads it via `useReactiveVar`
+* to control the `DrawerRoot` and writes it back through `onOpenChange` so the header trigger and
+* manual close (Escape / backdrop / close button) stay in sync. The single source of truth for the
+* controlled drawer; `addItem` never writes it. Client state only — never a query variable or
+* request header.
+*/
+const miniCartOpenVar = makeVar(false);
+/**
+* Latest `userErrors` from a coupon write (`applyCoupon` / `removeCoupon`), surfaced context-free.
+* A dedicated channel mirroring `cartUserErrorsVar` so coupon feedback sits next to the coupon form
+* and never collides with item-write errors (specs/fspg-830-coupon-entry.md AD-2). The coupon
+* actions publish here on every call (cleared at the start of the next call) and `CartCouponError`
+* reads it via `useReactiveVar`. Stays in client state — never a query variable or request header.
+*/
+const cartCouponErrorsVar = makeVar([]);
+/**
+* Count of cart writes currently in flight (specs/mini-cart-validation-wiring.md). Every mutating
+* handler in the cart action namespace registers for the lifetime of its call, so `> 0` means a
+* write is outstanding. The stock-validation open call reads this to skip while a write is running —
+* that write's own response already carries current availability, so re-validating would be
+* redundant. `validate` itself is read-only upstream and never registers here. Client state only —
+* never a query variable or request header.
+*/
+const cartWritesInFlightVar = makeVar(0);
+/**
+* Epoch-ms timestamp of when the client last received current availability (`0` = never). Stamped on
+* a successful `validate` and on every successful cart write, because a write's response already
+* carries recomputed availability (specs/mini-cart-validation-wiring.md, Decision 2). The
+* stock-validation open call compares `now - cartAvailabilityFreshAtVar()` against
+* `CART_VALIDATE_STALENESS_MS` and skips while inside the window, so reopening the overlay — or
+* opening it right after an add — does not re-validate. Client state only.
+*/
+const cartAvailabilityFreshAtVar = makeVar(0);
+/**
+* The staleness window for the stock-validation open call, in milliseconds. The single tuning knob:
+* the platform's rate limits under real traffic are not known yet, so this value is a starting point,
+* not a contract (specs/mini-cart-validation-wiring.md). The pre-checkout call ignores it and always
+* runs.
+*/
+const CART_VALIDATE_STALENESS_MS = 3e4;
+//#endregion
+export { CART_VALIDATE_STALENESS_MS, cartAvailabilityFreshAtVar, cartCouponErrorsVar, cartLastAddVar, cartUserErrorsVar, cartWritesInFlightVar, miniCartOpenVar, orderFormIdVar };
+
+//# sourceMappingURL=cart.js.map

package/dist/sdk/state/cart.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cart.js","names":[],"sources":["../../../src/sdk/state/cart.ts"],"sourcesContent":["import { makeVar } from '@apollo/client';\nimport type { CartUserError } from '../cart/operations.js';\n\n// Session-scoped cart identifier (`Cart.id` from the cart query response). Client state only —\n// never sent as a query variable or request header; the x-order-form-id cookie carries cart\n// context on the transport. Starts null; hydrated when the cart entity arrives, which opens the\n// cart action ready gate. See specs/cart-context-client-migrate.md (Decisions 2, 6).\nexport const orderFormIdVar = makeVar<string | null>(null);\n\n/**\n * Latest `userErrors` from any cart write, surfaced context-free. The cart action hook publishes\n * here on every call (cleared synchronously at the start of the next call) and `CartError` reads it\n * via `useReactiveVar`, decoupling error display from `CartRoot`'s data context (specs/actions.md\n * FR-9). Stays in client state — never a query variable or request header.\n */\nexport const cartUserErrorsVar = makeVar<readonly CartUserError[]>([]);\n\n/**\n * Monotonic add-success pulse. `addItem` increments it on each successful add (no userErrors); the\n * error and network-catch branches leave it untouched. `CartOpenOnAdd` and `CartRedirectOnAdd` key\n * a `useEffect` on it via `useReactiveVar`, so every successful add re-fires their behavior even when\n * the drawer is already open or was just closed — a boolean would not re-fire on an unchanged value\n * (specs/fspg-822-minicart-open-on-add.md, Decision 2). Client state only — never a query variable\n * or request header.\n */\nexport const cartLastAddVar = makeVar<number>(0);\n\n/**\n * The mini-cart's open state, surfaced context-free. `CartOpenOnAdd` reads it via `useReactiveVar`\n * to control the `DrawerRoot` and writes it back through `onOpenChange` so the header trigger and\n * manual close (Escape / backdrop / close button) stay in sync. The single source of truth for the\n * controlled drawer; `addItem` never writes it. Client state only — never a query variable or\n * request header.\n */\nexport const miniCartOpenVar = makeVar<boolean>(false);\n\n/**\n * Latest `userErrors` from a coupon write (`applyCoupon` / `removeCoupon`), surfaced context-free.\n * A dedicated channel mirroring `cartUserErrorsVar` so coupon feedback sits next to the coupon form\n * and never collides with item-write errors (specs/fspg-830-coupon-entry.md AD-2). The coupon\n * actions publish here on every call (cleared at the start of the next call) and `CartCouponError`\n * reads it via `useReactiveVar`. Stays in client state — never a query variable or request header.\n */\nexport const cartCouponErrorsVar = makeVar<readonly CartUserError[]>([]);\n\n/**\n * Count of cart writes currently in flight (specs/mini-cart-validation-wiring.md). Every mutating\n * handler in the cart action namespace registers for the lifetime of its call, so `> 0` means a\n * write is outstanding. The stock-validation open call reads this to skip while a write is running —\n * that write's own response already carries current availability, so re-validating would be\n * redundant. `validate` itself is read-only upstream and never registers here. Client state only —\n * never a query variable or request header.\n */\nexport const cartWritesInFlightVar = makeVar<number>(0);\n\n/**\n * Epoch-ms timestamp of when the client last received current availability (`0` = never). Stamped on\n * a successful `validate` and on every successful cart write, because a write's response already\n * carries recomputed availability (specs/mini-cart-validation-wiring.md, Decision 2). The\n * stock-validation open call compares `now - cartAvailabilityFreshAtVar()` against\n * `CART_VALIDATE_STALENESS_MS` and skips while inside the window, so reopening the overlay — or\n * opening it right after an add — does not re-validate. Client state only.\n */\nexport const cartAvailabilityFreshAtVar = makeVar<number>(0);\n\n/**\n * The staleness window for the stock-validation open call, in milliseconds. The single tuning knob:\n * the platform's rate limits under real traffic are not known yet, so this value is a starting point,\n * not a contract (specs/mini-cart-validation-wiring.md). The pre-checkout call ignores it and always\n * runs.\n */\nexport const CART_VALIDATE_STALENESS_MS = 30_000;\n"],"mappings":";;AAOA,MAAa,iBAAiB,QAAuB,IAAI;;;;;;;AAQzD,MAAa,oBAAoB,QAAkC,CAAC,CAAC;;;;;;;;;AAUrE,MAAa,iBAAiB,QAAgB,CAAC;;;;;;;;AAS/C,MAAa,kBAAkB,QAAiB,KAAK;;;;;;;;AASrD,MAAa,sBAAsB,QAAkC,CAAC,CAAC;;;;;;;;;AAUvE,MAAa,wBAAwB,QAAgB,CAAC;;;;;;;;;AAUtD,MAAa,6BAA6B,QAAgB,CAAC;;;;;;;AAQ3D,MAAa,6BAA6B"}

package/dist/sdk/state/index.js

@@ -0,0 +1,3 @@
+import { publishedVariantIdFor, selectedVariantVar } from "./variant-selector.js";
+import { cartCouponErrorsVar, cartLastAddVar, cartUserErrorsVar, miniCartOpenVar, orderFormIdVar } from "./cart.js";
+export { cartCouponErrorsVar, cartLastAddVar, cartUserErrorsVar, miniCartOpenVar, orderFormIdVar, publishedVariantIdFor, selectedVariantVar };

package/dist/sdk/state/variant-selector.d.ts

@@ -0,0 +1,17 @@
+//#region src/sdk/state/variant-selector.d.ts
+/** The shopper's in-page variant selection, scoped to the product it belongs to. The `productId`
+ *  is the `Product` Node ID of the PDP that owns the selection; `variantId` is the selected
+ *  `Variant` Node ID. Scoping prevents a selection made on one PDP from leaking into another after
+ *  client-side navigation, since this var is a module-global singleton. See specs/sku-selector.md
+ *  Decision 1. */
+export type SelectedVariant = {
+  productId: string;
+  variantId: string;
+};
+export declare const selectedVariantVar: import("@apollo/client").ReactiveVar<SelectedVariant | null>;
+/** Resolves the published variant id for `productId`, or `null` when nothing is selected or the
+ *  current selection belongs to a different product. Pass the value read via
+ *  `useReactiveVar(selectedVariantVar)` so callers stay reactive. */
+export declare function publishedVariantIdFor(selection: SelectedVariant | null, productId: string | null | undefined): string | null;
+//#endregion
+//# sourceMappingURL=variant-selector.d.ts.map

package/dist/sdk/state/variant-selector.js

@@ -0,0 +1,14 @@
+import { makeVar } from "@apollo/client";
+//#region src/sdk/state/variant-selector.ts
+const selectedVariantVar = makeVar(null);
+/** Resolves the published variant id for `productId`, or `null` when nothing is selected or the
+*  current selection belongs to a different product. Pass the value read via
+*  `useReactiveVar(selectedVariantVar)` so callers stay reactive. */
+function publishedVariantIdFor(selection, productId) {
+	if (!selection || !productId) return null;
+	return selection.productId === productId ? selection.variantId : null;
+}
+//#endregion
+export { publishedVariantIdFor, selectedVariantVar };
+
+//# sourceMappingURL=variant-selector.js.map

package/dist/sdk/state/variant-selector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variant-selector.js","names":[],"sources":["../../../src/sdk/state/variant-selector.ts"],"sourcesContent":["import { makeVar } from '@apollo/client';\n\n/** The shopper's in-page variant selection, scoped to the product it belongs to. The `productId`\n *  is the `Product` Node ID of the PDP that owns the selection; `variantId` is the selected\n *  `Variant` Node ID. Scoping prevents a selection made on one PDP from leaking into another after\n *  client-side navigation, since this var is a module-global singleton. See specs/sku-selector.md\n *  Decision 1. */\nexport type SelectedVariant = {\n  productId: string;\n  variantId: string;\n};\n\n// Published by the PDP variant swatches; read by sibling matter (gallery, pricing, buy button) so a\n// swatch change refreshes them without a full page navigation. Starts null — the VariantSelectorRoot\n// derivation falls back to the page-supplied SKU (then the first variant) until a shopper activates a\n// swatch.\nexport const selectedVariantVar = makeVar<SelectedVariant | null>(null);\n\n/** Resolves the published variant id for `productId`, or `null` when nothing is selected or the\n *  current selection belongs to a different product. Pass the value read via\n *  `useReactiveVar(selectedVariantVar)` so callers stay reactive. */\nexport function publishedVariantIdFor(\n  selection: SelectedVariant | null,\n  productId: string | null | undefined,\n): string | null {\n  if (!selection || !productId) return null;\n  return selection.productId === productId ? selection.variantId : null;\n}\n"],"mappings":";;AAgBA,MAAa,qBAAqB,QAAgC,IAAI;;;;AAKtE,SAAgB,sBACd,WACA,WACe;CACf,IAAI,CAAC,aAAa,CAAC,WAAW,OAAO;CACrC,OAAO,UAAU,cAAc,YAAY,UAAU,YAAY;AACnE"}