@vtex/faststore 0.0.1

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

@@ -0,0 +1,62 @@
+import "../../core/dist/index.js";
+import { ClientPreferenceKey, ClientProfileUserError, CustomerProfileUpdateInput, CustomerProfileUserError } from "./operations.js";
+//#region src/sdk/identity/use-identity-actions.d.ts
+/**
+ * The `identity` action namespace — the context-free owner of the shopper-profile,
+ * consent-preference, and persistent-profile writes
+ * (specs/fspg-859-email-field.md, specs/consent-opt-in-component.md,
+ * specs/sfs-3286-customer-profile-update-action.md,
+ * docs/storefront-core/adr-0010-actions-own-the-write-side.md).
+ *
+ * It mirrors `useCartActions`: a component anywhere in the tree dispatches the write through the
+ * compiler-injected `$actions.identity.*` prop, and the handler calls the corresponding mutation.
+ * Every write is **async / pessimistic** (Decision 1): the caller awaits the persisted result. Each
+ * call returns its `userErrors` (empty on success) so the caller can surface server-side failures
+ * inline; the returned entity self-updates the normalized cache and every reactive subscriber.
+ *
+ * The first two writes target the cart's sibling identity entities; `customerProfileUpdate` targets
+ * the shopper's account profile, which needs no cart at all.
+ */
+/**
+ * Payload for the profile write. Callers persist only the fields they own; other fields are
+ * untouched. The payload is passed through to `ClientProfileUpdateInput` unmapped, so this type
+ * mirrors that input verbatim — a stacked field only needs a field to already exist here to reach
+ * the wire.
+ */
+export type ClientProfileUpdatePayload = Readonly<{
+  email?: string;
+  firstName?: string;
+  lastName?: string;
+  phone?: string;
+  document?: string;
+}>;
+/** Payload for the preferences write — one opt-in flag; the other flag is left untouched. */
+export type ClientPreferencesUpdatePayload = Readonly<Partial<Record<ClientPreferenceKey, boolean>>>;
+/**
+ * Payload for the persistent-profile write. Mirrors `CustomerProfileUpdateInput` verbatim and is
+ * forwarded unmapped, so an omitted field stays untouched upstream and an empty string erases.
+ */
+export type CustomerProfileUpdatePayload = CustomerProfileUpdateInput;
+export type IdentityActions = Readonly<{
+  /**
+   * Persist the provided profile fields (partial) to the active cart's `clientProfileData`.
+   * Async — awaits the mutation before resolving. Returns the resulting `userErrors` (empty on
+   * success).
+   */
+  clientProfileUpdate: (payload: ClientProfileUpdatePayload) => Promise<readonly ClientProfileUserError[]>;
+  /**
+   * Persist the provided consent opt-in flag(s) (partial) to the shopper's `ClientPreferences`
+   * entity (order-form-backed). Async — awaits the mutation before resolving. Writes ONLY the
+   * requested field. Returns the resulting `userErrors` (empty on success).
+   */
+  clientPreferencesUpdate: (payload: ClientPreferencesUpdatePayload) => Promise<readonly ClientProfileUserError[]>;
+  /**
+   * Persist the provided profile fields (partial) to the shopper's persistent, cart-independent
+   * account profile. Async — awaits the mutation before resolving. Sends exactly the fields it is
+   * given: an omitted field is left untouched, an empty string erases. Returns the resulting
+   * `userErrors` (empty on success).
+   */
+  customerProfileUpdate: (payload: CustomerProfileUpdatePayload) => Promise<readonly CustomerProfileUserError[]>;
+}>;
+//#endregion
+//# sourceMappingURL=use-identity-actions.d.ts.map

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

@@ -0,0 +1,180 @@
+"use client";
+import { defineActions } from "../../core/dist/actions/registry.js";
+import "../../core/dist/index.js";
+import { CLIENT_PREFERENCES_UPDATE, CLIENT_PROFILE_UPDATE, CUSTOMER_PROFILE_UPDATE } from "./operations.js";
+import { useMutation } from "@apollo/client/react";
+import { useCallback, useMemo } from "react";
+import { CombinedGraphQLErrors } from "@apollo/client/errors";
+//#region src/sdk/identity/use-identity-actions.ts
+const NETWORK_PROFILE_ERROR = {
+	code: "NETWORK_ERROR",
+	message: "Unable to save your details. Please try again."
+};
+const NETWORK_PREFERENCE_ERROR = {
+	code: "NETWORK_ERROR",
+	message: "Unable to save your preference. Please try again."
+};
+const NETWORK_CUSTOMER_PROFILE_ERROR = {
+	code: "NETWORK_ERROR",
+	message: "Unable to save your profile. Please try again."
+};
+const UNAUTHORIZED_CUSTOMER_PROFILE_ERROR = {
+	code: "UNAUTHORIZED",
+	message: "Your session has expired. Please sign in again."
+};
+/**
+* The profile module answers an anonymous or expired session with a top-level `UNAUTHORIZED`, never
+* a `userError`. Collapsing it into `NETWORK_ERROR` would offer a retry that cannot succeed, so it
+* gets its own code and the caller can send the shopper back to sign-in.
+*/
+function toCustomerProfileError(error) {
+	if (CombinedGraphQLErrors.is(error)) {
+		if (error.errors.some(({ extensions }) => extensions?.code === "UNAUTHORIZED")) return UNAUTHORIZED_CUSTOMER_PROFILE_ERROR;
+	}
+	return NETWORK_CUSTOMER_PROFILE_ERROR;
+}
+/**
+* The `identity` namespace hook. Registered with the first-party action registry via `identityActions`
+* below; the compiler-emitted `IdentityActionProvider` calls it and threads the narrowed methods into
+* each consumer's `$actions.identity`.
+*/
+function useIdentityActions() {
+	const [profileMutation] = useMutation(CLIENT_PROFILE_UPDATE);
+	const [preferencesMutation] = useMutation(CLIENT_PREFERENCES_UPDATE);
+	const [customerProfileMutation] = useMutation(CUSTOMER_PROFILE_UPDATE);
+	const clientProfileUpdate = useCallback(async (payload) => {
+		try {
+			return (await profileMutation({ variables: { input: payload } })).data?.clientProfileUpdate?.userErrors ?? [];
+		} catch (error) {
+			console.error("[identity.clientProfileUpdate] clientProfileUpdate failed", error instanceof Error ? error.name : "UnknownError");
+			return [NETWORK_PROFILE_ERROR];
+		}
+	}, [profileMutation]);
+	const clientPreferencesUpdate = useCallback(async (payload) => {
+		try {
+			return (await preferencesMutation({ variables: { input: payload } })).data?.clientPreferencesUpdate?.userErrors ?? [];
+		} catch (error) {
+			console.error("[identity.clientPreferencesUpdate] clientPreferencesUpdate failed", error instanceof Error ? error.name : "UnknownError");
+			return [NETWORK_PREFERENCE_ERROR];
+		}
+	}, [preferencesMutation]);
+	const customerProfileUpdate = useCallback(async (payload) => {
+		try {
+			return (await customerProfileMutation({ variables: { input: payload } })).data?.customerProfileUpdate?.userErrors ?? [];
+		} catch (error) {
+			console.error("[identity.customerProfileUpdate] customerProfileUpdate failed", error instanceof Error ? error.name : "UnknownError");
+			return [toCustomerProfileError(error)];
+		}
+	}, [customerProfileMutation]);
+	return useMemo(() => ({
+		clientProfileUpdate,
+		clientPreferencesUpdate,
+		customerProfileUpdate
+	}), [
+		clientProfileUpdate,
+		clientPreferencesUpdate,
+		customerProfileUpdate
+	]);
+}
+defineActions({
+	namespace: "identity",
+	description: "Mutation-backed writes against the shopper identity entities (client profile, consent preferences, account profile).",
+	provider: {
+		name: "IdentityActionProvider",
+		importPath: "@vtex/faststore/internal/client"
+	},
+	methods: {
+		clientProfileUpdate: {
+			description: "Persist profile fields (partial) to the active cart (async strategy). Sending email flips Session.isIdentified.",
+			payload: [
+				{
+					name: "email",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "firstName",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "lastName",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "phone",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "document",
+					type: "string",
+					optional: true
+				}
+			]
+		},
+		clientPreferencesUpdate: {
+			description: "Persist consent opt-in flags (partial) to the active cart (async strategy). Writes only the provided flag(s).",
+			payload: [{
+				name: "optinNewsLetter",
+				type: "boolean",
+				optional: true
+			}, {
+				name: "savePersonalData",
+				type: "boolean",
+				optional: true
+			}]
+		},
+		customerProfileUpdate: {
+			description: "Persist profile fields (partial) to the persistent account profile, not the cart (async strategy). Omitted fields are untouched; an empty string erases.",
+			payload: [
+				{
+					name: "firstName",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "lastName",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "homePhone",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "mobilePhone",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "document",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "documentType",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "birthDate",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "gender",
+					type: "string",
+					optional: true
+				}
+			]
+		}
+	},
+	use: useIdentityActions
+});
+//#endregion
+export { useIdentityActions };
+
+//# sourceMappingURL=use-identity-actions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-identity-actions.js","names":[],"sources":["../../../src/sdk/identity/use-identity-actions.ts"],"sourcesContent":["'use client';\n\nimport { CombinedGraphQLErrors } from '@apollo/client/errors';\nimport { useMutation } from '@apollo/client/react';\nimport { defineActions } from '@vtex/fs-core';\nimport { useCallback, useMemo } from 'react';\nimport {\n  CLIENT_PREFERENCES_UPDATE,\n  CLIENT_PROFILE_UPDATE,\n  type ClientPreferenceKey,\n  type ClientProfileUserError,\n  CUSTOMER_PROFILE_UPDATE,\n  type CustomerProfileUpdateInput,\n  type CustomerProfileUserError,\n} from './operations.js';\n\n/**\n * The `identity` action namespace — the context-free owner of the shopper-profile,\n * consent-preference, and persistent-profile writes\n * (specs/fspg-859-email-field.md, specs/consent-opt-in-component.md,\n * specs/sfs-3286-customer-profile-update-action.md,\n * docs/storefront-core/adr-0010-actions-own-the-write-side.md).\n *\n * It mirrors `useCartActions`: a component anywhere in the tree dispatches the write through the\n * compiler-injected `$actions.identity.*` prop, and the handler calls the corresponding mutation.\n * Every write is **async / pessimistic** (Decision 1): the caller awaits the persisted result. Each\n * call returns its `userErrors` (empty on success) so the caller can surface server-side failures\n * inline; the returned entity self-updates the normalized cache and every reactive subscriber.\n *\n * The first two writes target the cart's sibling identity entities; `customerProfileUpdate` targets\n * the shopper's account profile, which needs no cart at all.\n */\n\n/**\n * Payload for the profile write. Callers persist only the fields they own; other fields are\n * untouched. The payload is passed through to `ClientProfileUpdateInput` unmapped, so this type\n * mirrors that input verbatim — a stacked field only needs a field to already exist here to reach\n * the wire.\n */\nexport type ClientProfileUpdatePayload = Readonly<{\n  email?: string;\n  firstName?: string;\n  lastName?: string;\n  phone?: string;\n  document?: string;\n}>;\n\n/** Payload for the preferences write — one opt-in flag; the other flag is left untouched. */\nexport type ClientPreferencesUpdatePayload = Readonly<Partial<Record<ClientPreferenceKey, boolean>>>;\n\n/**\n * Payload for the persistent-profile write. Mirrors `CustomerProfileUpdateInput` verbatim and is\n * forwarded unmapped, so an omitted field stays untouched upstream and an empty string erases.\n */\nexport type CustomerProfileUpdatePayload = CustomerProfileUpdateInput;\n\nexport type IdentityActions = Readonly<{\n  /**\n   * Persist the provided profile fields (partial) to the active cart's `clientProfileData`.\n   * Async — awaits the mutation before resolving. Returns the resulting `userErrors` (empty on\n   * success).\n   */\n  clientProfileUpdate: (payload: ClientProfileUpdatePayload) => Promise<readonly ClientProfileUserError[]>;\n  /**\n   * Persist the provided consent opt-in flag(s) (partial) to the shopper's `ClientPreferences`\n   * entity (order-form-backed). Async — awaits the mutation before resolving. Writes ONLY the\n   * requested field. Returns the resulting `userErrors` (empty on success).\n   */\n  clientPreferencesUpdate: (payload: ClientPreferencesUpdatePayload) => Promise<readonly ClientProfileUserError[]>;\n  /**\n   * Persist the provided profile fields (partial) to the shopper's persistent, cart-independent\n   * account profile. Async — awaits the mutation before resolving. Sends exactly the fields it is\n   * given: an omitted field is left untouched, an empty string erases. Returns the resulting\n   * `userErrors` (empty on success).\n   */\n  customerProfileUpdate: (payload: CustomerProfileUpdatePayload) => Promise<readonly CustomerProfileUserError[]>;\n}>;\n\nconst NETWORK_PROFILE_ERROR: ClientProfileUserError = {\n  code: 'NETWORK_ERROR',\n  message: 'Unable to save your details. Please try again.',\n};\n\nconst NETWORK_PREFERENCE_ERROR: ClientProfileUserError = {\n  code: 'NETWORK_ERROR',\n  message: 'Unable to save your preference. Please try again.',\n};\n\nconst NETWORK_CUSTOMER_PROFILE_ERROR: CustomerProfileUserError = {\n  code: 'NETWORK_ERROR',\n  message: 'Unable to save your profile. Please try again.',\n};\n\nconst UNAUTHORIZED_CUSTOMER_PROFILE_ERROR: CustomerProfileUserError = {\n  code: 'UNAUTHORIZED',\n  message: 'Your session has expired. Please sign in again.',\n};\n\n/**\n * The profile module answers an anonymous or expired session with a top-level `UNAUTHORIZED`, never\n * a `userError`. Collapsing it into `NETWORK_ERROR` would offer a retry that cannot succeed, so it\n * gets its own code and the caller can send the shopper back to sign-in.\n */\nfunction toCustomerProfileError(error: unknown): CustomerProfileUserError {\n  if (CombinedGraphQLErrors.is(error)) {\n    const unauthorized = error.errors.some(({ extensions }) => extensions?.code === 'UNAUTHORIZED');\n    if (unauthorized) return UNAUTHORIZED_CUSTOMER_PROFILE_ERROR;\n  }\n  return NETWORK_CUSTOMER_PROFILE_ERROR;\n}\n\n/**\n * The `identity` namespace hook. Registered with the first-party action registry via `identityActions`\n * below; the compiler-emitted `IdentityActionProvider` calls it and threads the narrowed methods into\n * each consumer's `$actions.identity`.\n */\nexport function useIdentityActions(): IdentityActions {\n  const [profileMutation] = useMutation(CLIENT_PROFILE_UPDATE);\n  const [preferencesMutation] = useMutation(CLIENT_PREFERENCES_UPDATE);\n  const [customerProfileMutation] = useMutation(CUSTOMER_PROFILE_UPDATE);\n\n  const clientProfileUpdate = useCallback<IdentityActions['clientProfileUpdate']>(\n    async (payload) => {\n      try {\n        const result = await profileMutation({ variables: { input: payload } });\n        return result.data?.clientProfileUpdate?.userErrors ?? [];\n      } catch (error) {\n        // Log only the error name — the message can echo the submitted email (PII).\n        console.error(\n          '[identity.clientProfileUpdate] clientProfileUpdate failed',\n          error instanceof Error ? error.name : 'UnknownError',\n        );\n        return [NETWORK_PROFILE_ERROR];\n      }\n    },\n    [profileMutation],\n  );\n\n  const clientPreferencesUpdate = useCallback<IdentityActions['clientPreferencesUpdate']>(\n    async (payload) => {\n      try {\n        const result = await preferencesMutation({ variables: { input: payload } });\n        return result.data?.clientPreferencesUpdate?.userErrors ?? [];\n      } catch (error) {\n        // Log only the error name — mirrors the profile write's PII-safe logging.\n        console.error(\n          '[identity.clientPreferencesUpdate] clientPreferencesUpdate failed',\n          error instanceof Error ? error.name : 'UnknownError',\n        );\n        return [NETWORK_PREFERENCE_ERROR];\n      }\n    },\n    [preferencesMutation],\n  );\n\n  const customerProfileUpdate = useCallback<IdentityActions['customerProfileUpdate']>(\n    async (payload) => {\n      try {\n        // Forwarded unmapped: an empty string is an explicit erase and must survive to the wire.\n        const result = await customerProfileMutation({ variables: { input: payload } });\n        return result.data?.customerProfileUpdate?.userErrors ?? [];\n      } catch (error) {\n        // Log only the error name — the message can echo a submitted profile value (PII).\n        console.error(\n          '[identity.customerProfileUpdate] customerProfileUpdate failed',\n          error instanceof Error ? error.name : 'UnknownError',\n        );\n        return [toCustomerProfileError(error)];\n      }\n    },\n    [customerProfileMutation],\n  );\n\n  return useMemo(\n    () => ({ clientProfileUpdate, clientPreferencesUpdate, customerProfileUpdate }),\n    [clientProfileUpdate, clientPreferencesUpdate, customerProfileUpdate],\n  );\n}\n\n/**\n * Declares the `identity` action namespace — the single source of truth for its method/payload\n * metadata, runtime provider, and `use` hook (mirrors `cartActions`). The native catalog builder\n * (`scripts/build-catalog.mjs`) statically reads this call to emit `actions.json`; at runtime\n * `IdentityActionProvider` calls `useIdentityActions` directly.\n */\nexport const identityActions = defineActions({\n  namespace: 'identity',\n  description:\n    'Mutation-backed writes against the shopper identity entities (client profile, consent preferences, account profile).',\n  provider: { name: 'IdentityActionProvider', importPath: '@vtex/faststore/internal/client' },\n  methods: {\n    clientProfileUpdate: {\n      description:\n        'Persist profile fields (partial) to the active cart (async strategy). Sending email flips Session.isIdentified.',\n      payload: [\n        { name: 'email', type: 'string', optional: true },\n        { name: 'firstName', type: 'string', optional: true },\n        { name: 'lastName', type: 'string', optional: true },\n        { name: 'phone', type: 'string', optional: true },\n        { name: 'document', type: 'string', optional: true },\n      ],\n    },\n    clientPreferencesUpdate: {\n      description:\n        'Persist consent opt-in flags (partial) to the active cart (async strategy). Writes only the provided flag(s).',\n      payload: [\n        { name: 'optinNewsLetter', type: 'boolean', optional: true },\n        { name: 'savePersonalData', type: 'boolean', optional: true },\n      ],\n    },\n    customerProfileUpdate: {\n      description:\n        'Persist profile fields (partial) to the persistent account profile, not the cart (async strategy). Omitted fields are untouched; an empty string erases.',\n      payload: [\n        { name: 'firstName', type: 'string', optional: true },\n        { name: 'lastName', type: 'string', optional: true },\n        { name: 'homePhone', type: 'string', optional: true },\n        { name: 'mobilePhone', type: 'string', optional: true },\n        { name: 'document', type: 'string', optional: true },\n        { name: 'documentType', type: 'string', optional: true },\n        { name: 'birthDate', type: 'string', optional: true },\n        { name: 'gender', type: 'string', optional: true },\n      ],\n    },\n  },\n  use: useIdentityActions,\n});\n"],"mappings":";;;;;;;;AA8EA,MAAM,wBAAgD;CACpD,MAAM;CACN,SAAS;AACX;AAEA,MAAM,2BAAmD;CACvD,MAAM;CACN,SAAS;AACX;AAEA,MAAM,iCAA2D;CAC/D,MAAM;CACN,SAAS;AACX;AAEA,MAAM,sCAAgE;CACpE,MAAM;CACN,SAAS;AACX;;;;;;AAOA,SAAS,uBAAuB,OAA0C;CACxE,IAAI,sBAAsB,GAAG,KAAK,GACX;MAAA,MAAM,OAAO,MAAM,EAAE,iBAAiB,YAAY,SAAS,cACjE,GAAG,OAAO;CAAA;CAE3B,OAAO;AACT;;;;;;AAOA,SAAgB,qBAAsC;CACpD,MAAM,CAAC,mBAAmB,YAAY,qBAAqB;CAC3D,MAAM,CAAC,uBAAuB,YAAY,yBAAyB;CACnE,MAAM,CAAC,2BAA2B,YAAY,uBAAuB;CAErE,MAAM,sBAAsB,YAC1B,OAAO,YAAY;EACjB,IAAI;GAEF,QAAO,MADc,gBAAgB,EAAE,WAAW,EAAE,OAAO,QAAQ,EAAE,CAAC,EAAA,CACxD,MAAM,qBAAqB,cAAc,CAAC;EAC1D,SAAS,OAAO;GAEd,QAAQ,MACN,6DACA,iBAAiB,QAAQ,MAAM,OAAO,cACxC;GACA,OAAO,CAAC,qBAAqB;EAC/B;CACF,GACA,CAAC,eAAe,CAClB;CAEA,MAAM,0BAA0B,YAC9B,OAAO,YAAY;EACjB,IAAI;GAEF,QAAO,MADc,oBAAoB,EAAE,WAAW,EAAE,OAAO,QAAQ,EAAE,CAAC,EAAA,CAC5D,MAAM,yBAAyB,cAAc,CAAC;EAC9D,SAAS,OAAO;GAEd,QAAQ,MACN,qEACA,iBAAiB,QAAQ,MAAM,OAAO,cACxC;GACA,OAAO,CAAC,wBAAwB;EAClC;CACF,GACA,CAAC,mBAAmB,CACtB;CAEA,MAAM,wBAAwB,YAC5B,OAAO,YAAY;EACjB,IAAI;GAGF,QAAO,MADc,wBAAwB,EAAE,WAAW,EAAE,OAAO,QAAQ,EAAE,CAAC,EAAA,CAChE,MAAM,uBAAuB,cAAc,CAAC;EAC5D,SAAS,OAAO;GAEd,QAAQ,MACN,iEACA,iBAAiB,QAAQ,MAAM,OAAO,cACxC;GACA,OAAO,CAAC,uBAAuB,KAAK,CAAC;EACvC;CACF,GACA,CAAC,uBAAuB,CAC1B;CAEA,OAAO,eACE;EAAE;EAAqB;EAAyB;CAAsB,IAC7E;EAAC;EAAqB;EAAyB;CAAqB,CACtE;AACF;AAQ+B,cAAc;CAC3C,WAAW;CACX,aACE;CACF,UAAU;EAAE,MAAM;EAA0B,YAAY;CAAkC;CAC1F,SAAS;EACP,qBAAqB;GACnB,aACE;GACF,SAAS;IACP;KAAE,MAAM;KAAS,MAAM;KAAU,UAAU;IAAK;IAChD;KAAE,MAAM;KAAa,MAAM;KAAU,UAAU;IAAK;IACpD;KAAE,MAAM;KAAY,MAAM;KAAU,UAAU;IAAK;IACnD;KAAE,MAAM;KAAS,MAAM;KAAU,UAAU;IAAK;IAChD;KAAE,MAAM;KAAY,MAAM;KAAU,UAAU;IAAK;GACrD;EACF;EACA,yBAAyB;GACvB,aACE;GACF,SAAS,CACP;IAAE,MAAM;IAAmB,MAAM;IAAW,UAAU;GAAK,GAC3D;IAAE,MAAM;IAAoB,MAAM;IAAW,UAAU;GAAK,CAC9D;EACF;EACA,uBAAuB;GACrB,aACE;GACF,SAAS;IACP;KAAE,MAAM;KAAa,MAAM;KAAU,UAAU;IAAK;IACpD;KAAE,MAAM;KAAY,MAAM;KAAU,UAAU;IAAK;IACnD;KAAE,MAAM;KAAa,MAAM;KAAU,UAAU;IAAK;IACpD;KAAE,MAAM;KAAe,MAAM;KAAU,UAAU;IAAK;IACtD;KAAE,MAAM;KAAY,MAAM;KAAU,UAAU;IAAK;IACnD;KAAE,MAAM;KAAgB,MAAM;KAAU,UAAU;IAAK;IACvD;KAAE,MAAM;KAAa,MAAM;KAAU,UAAU;IAAK;IACpD;KAAE,MAAM;KAAU,MAAM;KAAU,UAAU;IAAK;GACnD;EACF;CACF;CACA,KAAK;AACP,CAAC"}

package/dist/sdk/provider/index.d.ts

@@ -0,0 +1,2 @@
+import { StorefrontProvider, StorefrontProviderProps } from "./storefront-provider.js";
+export { StorefrontProvider, type StorefrontProviderProps };

package/dist/sdk/provider/index.js

@@ -0,0 +1,2 @@
+import { StorefrontProvider } from "./storefront-provider.js";
+export { StorefrontProvider };

package/dist/sdk/provider/storefront-provider.d.ts

@@ -0,0 +1,32 @@
+import { StorefrontContext } from "../../core/dist/schema/generated/schema.js";
+import "../../core/dist/index.js";
+import { Messages } from "../i18n/locales.js";
+import { ReactNode } from "react";
+//#region src/sdk/provider/storefront-provider.d.ts
+export type StorefrontProviderProps = Readonly<{
+  apiUrl: string;
+  /** The compiler-emitted context. Published to the tree and sent on every operation. */
+  context: StorefrontContext;
+  /**
+   * The record the generated root layout resolved for this binding. Omitted means no messages —
+   * legal, and only observable once a component renders one.
+   */
+  messages?: Messages;
+  headers?: Record<string, string>;
+  children: ReactNode;
+}>;
+/**
+ * Wraps a React tree in the Apollo context, using the Next.js App Router
+ * integration so that `useQuery` / `useSuspenseQuery` results can be
+ * streamed from the server SSR pass into the browser cache.
+ *
+ * On the server a fresh `ApolloClient` is built per request. In the browser it is built once per
+ * **document**: `WrapApolloProvider` keeps it at `window[Symbol.for('ApolloClientSingleton')]` and
+ * assigns only when that slot is empty, so `makeClient` never runs a second time no matter how the
+ * provider re-renders. Everything the factory closes over — the cache and the context headers — is
+ * therefore frozen for the document's lifetime, which is why crossing bindings has to be a full
+ * document load and why the guard below exists.
+ */
+export declare function StorefrontProvider({ apiUrl, context, messages, headers, children }: StorefrontProviderProps): import("react/jsx-runtime").JSX.Element;
+//#endregion
+//# sourceMappingURL=storefront-provider.d.ts.map

package/dist/sdk/provider/storefront-provider.js

@@ -0,0 +1,111 @@
+"use client";
+import { StorefrontContextProvider } from "../context/storefront-context.js";
+import { MessageProvider } from "../i18n/provider.js";
+import { buildStorefrontContextHeaders } from "../context/headers.js";
+import { getCacheConfig } from "../cache/storefront-cache.js";
+import { jsx } from "react/jsx-runtime";
+import { ApolloLink, HttpLink } from "@apollo/client";
+import { SetContextLink } from "@apollo/client/link/context";
+import { ApolloClient as ApolloClient$1, ApolloNextAppProvider, InMemoryCache as InMemoryCache$1 } from "@apollo/client-integration-nextjs";
+//#region src/sdk/provider/storefront-provider.tsx
+/** One frozen instance, so an omitted `messages` does not hand `IntlProvider` a new object per render. */
+const NO_MESSAGES = Object.freeze({});
+/** Where `WrapApolloProvider` memoizes the browser's one client, per document. */
+const APOLLO_CLIENT_SINGLETON = Symbol.for("ApolloClientSingleton");
+/** The binding a client was built for, stamped by `makeClient` so a later render can compare. */
+const CLIENT_BINDING = Symbol.for("faststore.apolloClientBinding");
+/**
+* Fails when the live client was built for a different binding than the one now rendering.
+*
+* This cannot be fixed by rebuilding: the client is memoized per document, so the cache *and* the
+* baked `x-faststore-*` headers belong to whichever binding loaded the document first. A client-side
+* navigation across bindings would therefore render a correct-looking page filled with the previous
+* binding's data — silent, and worse than a stale cache. Crossing bindings is a full document load;
+* this is the tripwire for anything that tries otherwise.
+*
+* Throws in development so it cannot be missed, warns in production so a shopper is not shown an
+* error page over it. A no-op on the server and before the first client is built.
+*/
+function assertClientMatchesBinding(bindingId) {
+	const win = globalThis.window;
+	if (!win) return;
+	const live = Reflect.get(win, APOLLO_CLIENT_SINGLETON);
+	if (!live) return;
+	const built = Reflect.get(live, CLIENT_BINDING) ?? null;
+	if (built === bindingId) return;
+	const message = `StorefrontProvider: the live Apollo client was built for binding ${JSON.stringify(built)} but this render is binding ${JSON.stringify(bindingId)}. The client is memoized per document, so its cache and its \`x-faststore-*\` headers still belong to the previous binding. Navigate between bindings with a full document load (a plain anchor, not \`<Link>\`).`;
+	if (process.env.NODE_ENV === "production") {
+		console.error(message);
+		return;
+	}
+	throw new Error(message);
+}
+/**
+* Debug-only cart-context override. Injects `x-order-form-id` only when the page URL carries
+* `?debug_ofid=<id>`. In normal flow the header is absent: the server resolves the cart from the
+* HttpOnly cookie, which the browser attaches automatically on same-origin requests. No-op during
+* SSR (no `window`).
+*/
+const cartContextLink = new SetContextLink((prevContext) => {
+	const win = globalThis.window;
+	if (!win) return prevContext;
+	const debugOfid = new URLSearchParams(win.location.search).get("debug_ofid");
+	if (!debugOfid) return prevContext;
+	return {
+		...prevContext,
+		headers: {
+			...prevContext.headers,
+			"x-order-form-id": debugOfid
+		}
+	};
+});
+/**
+* Wraps a React tree in the Apollo context, using the Next.js App Router
+* integration so that `useQuery` / `useSuspenseQuery` results can be
+* streamed from the server SSR pass into the browser cache.
+*
+* On the server a fresh `ApolloClient` is built per request. In the browser it is built once per
+* **document**: `WrapApolloProvider` keeps it at `window[Symbol.for('ApolloClientSingleton')]` and
+* assigns only when that slot is empty, so `makeClient` never runs a second time no matter how the
+* provider re-renders. Everything the factory closes over — the cache and the context headers — is
+* therefore frozen for the document's lifetime, which is why crossing bindings has to be a full
+* document load and why the guard below exists.
+*/
+function StorefrontProvider({ apiUrl, context, messages, headers, children }) {
+	if (typeof apiUrl !== "string" || apiUrl.length === 0) throw new Error("StorefrontProvider: `apiUrl` is required. Set `NEXT_PUBLIC_STOREFRONT_API_URL` in your environment or pass `apiUrl` explicitly.");
+	const requestHeaders = {
+		...headers,
+		...buildStorefrontContextHeaders(context)
+	};
+	function makeClient() {
+		const client = new ApolloClient$1({
+			cache: new InMemoryCache$1(getCacheConfig()),
+			link: ApolloLink.from([cartContextLink, new HttpLink({
+				uri: apiUrl,
+				...requestHeaders ? { headers: requestHeaders } : {}
+			})]),
+			defaultOptions: {
+				watchQuery: { errorPolicy: "all" },
+				query: { errorPolicy: "all" }
+			}
+		});
+		Reflect.set(client, CLIENT_BINDING, context.bindingId);
+		return client;
+	}
+	assertClientMatchesBinding(context.bindingId);
+	return /* @__PURE__ */ jsx(StorefrontContextProvider, {
+		context,
+		children: /* @__PURE__ */ jsx(MessageProvider, {
+			locale: context.locale,
+			messages: messages ?? NO_MESSAGES,
+			children: /* @__PURE__ */ jsx(ApolloNextAppProvider, {
+				makeClient,
+				children
+			})
+		})
+	});
+}
+//#endregion
+export { APOLLO_CLIENT_SINGLETON, StorefrontProvider };
+
+//# sourceMappingURL=storefront-provider.js.map

package/dist/sdk/provider/storefront-provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storefront-provider.js","names":["ApolloClient","InMemoryCache"],"sources":["../../../src/sdk/provider/storefront-provider.tsx"],"sourcesContent":["'use client';\n\nimport { ApolloLink, HttpLink } from '@apollo/client';\nimport { SetContextLink } from '@apollo/client/link/context';\nimport { ApolloClient, ApolloNextAppProvider, InMemoryCache } from '@apollo/client-integration-nextjs';\nimport type { StorefrontContext } from '@vtex/fs-core';\nimport type { ReactNode } from 'react';\nimport { getCacheConfig } from '../cache/storefront-cache.js';\nimport { buildStorefrontContextHeaders } from '../context/headers.js';\nimport { StorefrontContextProvider } from '../context/storefront-context.js';\nimport type { Messages } from '../i18n/locales.js';\nimport { MessageProvider } from '../i18n/provider.js';\n\nexport type StorefrontProviderProps = Readonly<{\n  apiUrl: string;\n  /** The compiler-emitted context. Published to the tree and sent on every operation. */\n  context: StorefrontContext;\n  /**\n   * The record the generated root layout resolved for this binding. Omitted means no messages —\n   * legal, and only observable once a component renders one.\n   */\n  messages?: Messages;\n  headers?: Record<string, string>;\n  children: ReactNode;\n}>;\n\n/** One frozen instance, so an omitted `messages` does not hand `IntlProvider` a new object per render. */\nconst NO_MESSAGES: Messages = Object.freeze({});\n\n/** Where `WrapApolloProvider` memoizes the browser's one client, per document. */\nexport const APOLLO_CLIENT_SINGLETON = Symbol.for('ApolloClientSingleton');\n\n/** The binding a client was built for, stamped by `makeClient` so a later render can compare. */\nconst CLIENT_BINDING = Symbol.for('faststore.apolloClientBinding');\n\n/**\n * Fails when the live client was built for a different binding than the one now rendering.\n *\n * This cannot be fixed by rebuilding: the client is memoized per document, so the cache *and* the\n * baked `x-faststore-*` headers belong to whichever binding loaded the document first. A client-side\n * navigation across bindings would therefore render a correct-looking page filled with the previous\n * binding's data — silent, and worse than a stale cache. Crossing bindings is a full document load;\n * this is the tripwire for anything that tries otherwise.\n *\n * Throws in development so it cannot be missed, warns in production so a shopper is not shown an\n * error page over it. A no-op on the server and before the first client is built.\n */\nfunction assertClientMatchesBinding(bindingId: string | null): void {\n  const win: Window | undefined = globalThis.window;\n  if (!win) return;\n  const live = Reflect.get(win, APOLLO_CLIENT_SINGLETON);\n  if (!live) return;\n  const built = (Reflect.get(live as object, CLIENT_BINDING) ?? null) as string | null;\n  if (built === bindingId) return;\n\n  const message =\n    `StorefrontProvider: the live Apollo client was built for binding ${JSON.stringify(built)} but ` +\n    `this render is binding ${JSON.stringify(bindingId)}. The client is memoized per document, so ` +\n    'its cache and its `x-faststore-*` headers still belong to the previous binding. Navigate ' +\n    'between bindings with a full document load (a plain anchor, not `<Link>`).';\n  if (process.env.NODE_ENV === 'production') {\n    console.error(message);\n    return;\n  }\n  throw new Error(message);\n}\n\n/**\n * Debug-only cart-context override. Injects `x-order-form-id` only when the page URL carries\n * `?debug_ofid=<id>`. In normal flow the header is absent: the server resolves the cart from the\n * HttpOnly cookie, which the browser attaches automatically on same-origin requests. No-op during\n * SSR (no `window`).\n */\nconst cartContextLink = new SetContextLink((prevContext) => {\n  // Typed as optional: the DOM lib declares `window` non-nullable, but it is absent during SSR.\n  const win: Window | undefined = globalThis.window;\n  if (!win) return prevContext;\n  const debugOfid = new URLSearchParams(win.location.search).get('debug_ofid');\n  if (!debugOfid) return prevContext;\n  return {\n    ...prevContext,\n    headers: { ...prevContext.headers, 'x-order-form-id': debugOfid },\n  };\n});\n\n/**\n * Wraps a React tree in the Apollo context, using the Next.js App Router\n * integration so that `useQuery` / `useSuspenseQuery` results can be\n * streamed from the server SSR pass into the browser cache.\n *\n * On the server a fresh `ApolloClient` is built per request. In the browser it is built once per\n * **document**: `WrapApolloProvider` keeps it at `window[Symbol.for('ApolloClientSingleton')]` and\n * assigns only when that slot is empty, so `makeClient` never runs a second time no matter how the\n * provider re-renders. Everything the factory closes over — the cache and the context headers — is\n * therefore frozen for the document's lifetime, which is why crossing bindings has to be a full\n * document load and why the guard below exists.\n */\nexport function StorefrontProvider({ apiUrl, context, messages, headers, children }: StorefrontProviderProps) {\n  if (typeof apiUrl !== 'string' || apiUrl.length === 0) {\n    throw new Error(\n      'StorefrontProvider: `apiUrl` is required. Set ' +\n        '`NEXT_PUBLIC_STOREFRONT_API_URL` in your environment or pass ' +\n        '`apiUrl` explicitly.',\n    );\n  }\n\n  // Context headers merge last, so a caller cannot send a locale, binding or sales channel that\n  // disagrees with the context the app rendered. Requesting a different one is what `context` is for.\n  const requestHeaders = { ...headers, ...buildStorefrontContextHeaders(context) };\n\n  function makeClient() {\n    const client = new ApolloClient({\n      cache: new InMemoryCache(getCacheConfig()),\n      link: ApolloLink.from([\n        cartContextLink,\n        new HttpLink({\n          uri: apiUrl,\n          ...(requestHeaders ? { headers: requestHeaders } : {}),\n        }),\n      ]),\n      // `cart` is non-null (`Cart!`), so an upstream cart failure nulls the whole operation's\n      // `data`. 'all' delivers `{ data, error }` instead of throwing, letting the cart subtree\n      // degrade in place.\n      defaultOptions: {\n        watchQuery: { errorPolicy: 'all' },\n        query: { errorPolicy: 'all' },\n      },\n    });\n    // Stamp which binding this client's cache and headers belong to, so a later render can tell.\n    Reflect.set(client, CLIENT_BINDING, context.bindingId);\n    return client;\n  }\n\n  assertClientMatchesBinding(context.bindingId);\n\n  return (\n    <StorefrontContextProvider context={context}>\n      <MessageProvider locale={context.locale} messages={messages ?? NO_MESSAGES}>\n        <ApolloNextAppProvider makeClient={makeClient}>{children}</ApolloNextAppProvider>\n      </MessageProvider>\n    </StorefrontContextProvider>\n  );\n}\n"],"mappings":";;;;;;;;;;;AA2BA,MAAM,cAAwB,OAAO,OAAO,CAAC,CAAC;;AAG9C,MAAa,0BAA0B,OAAO,IAAI,uBAAuB;;AAGzE,MAAM,iBAAiB,OAAO,IAAI,+BAA+B;;;;;;;;;;;;;AAcjE,SAAS,2BAA2B,WAAgC;CAClE,MAAM,MAA0B,WAAW;CAC3C,IAAI,CAAC,KAAK;CACV,MAAM,OAAO,QAAQ,IAAI,KAAK,uBAAuB;CACrD,IAAI,CAAC,MAAM;CACX,MAAM,QAAS,QAAQ,IAAI,MAAgB,cAAc,KAAK;CAC9D,IAAI,UAAU,WAAW;CAEzB,MAAM,UACJ,oEAAoE,KAAK,UAAU,KAAK,EAAE,8BAChE,KAAK,UAAU,SAAS,EAAE;CAGtD,IAAI,QAAQ,IAAI,aAAa,cAAc;EACzC,QAAQ,MAAM,OAAO;EACrB;CACF;CACA,MAAM,IAAI,MAAM,OAAO;AACzB;;;;;;;AAQA,MAAM,kBAAkB,IAAI,gBAAgB,gBAAgB;CAE1D,MAAM,MAA0B,WAAW;CAC3C,IAAI,CAAC,KAAK,OAAO;CACjB,MAAM,YAAY,IAAI,gBAAgB,IAAI,SAAS,MAAM,CAAC,CAAC,IAAI,YAAY;CAC3E,IAAI,CAAC,WAAW,OAAO;CACvB,OAAO;EACL,GAAG;EACH,SAAS;GAAE,GAAG,YAAY;GAAS,mBAAmB;EAAU;CAClE;AACF,CAAC;;;;;;;;;;;;;AAcD,SAAgB,mBAAmB,EAAE,QAAQ,SAAS,UAAU,SAAS,YAAqC;CAC5G,IAAI,OAAO,WAAW,YAAY,OAAO,WAAW,GAClD,MAAM,IAAI,MACR,iIAGF;CAKF,MAAM,iBAAiB;EAAE,GAAG;EAAS,GAAG,8BAA8B,OAAO;CAAE;CAE/E,SAAS,aAAa;EACpB,MAAM,SAAS,IAAIA,eAAa;GAC9B,OAAO,IAAIC,gBAAc,eAAe,CAAC;GACzC,MAAM,WAAW,KAAK,CACpB,iBACA,IAAI,SAAS;IACX,KAAK;IACL,GAAI,iBAAiB,EAAE,SAAS,eAAe,IAAI,CAAC;GACtD,CAAC,CACH,CAAC;GAID,gBAAgB;IACd,YAAY,EAAE,aAAa,MAAM;IACjC,OAAO,EAAE,aAAa,MAAM;GAC9B;EACF,CAAC;EAED,QAAQ,IAAI,QAAQ,gBAAgB,QAAQ,SAAS;EACrD,OAAO;CACT;CAEA,2BAA2B,QAAQ,SAAS;CAE5C,OACE,oBAAC,2BAAD;EAAoC;EAClC,UAAA,oBAAC,iBAAD;GAAiB,QAAQ,QAAQ;GAAQ,UAAU,YAAY;GAC7D,UAAA,oBAAC,uBAAD;IAAmC;IAAa;GAAgC,CAAA;EACjE,CAAA;CACQ,CAAA;AAE/B"}

package/dist/sdk/region/operations.d.ts

@@ -0,0 +1,6 @@
+import { RegionFragmentFragment } from "../generated/graphql.js";
+import { TypedDocumentNode } from "@apollo/client";
+//#region src/sdk/region/operations.d.ts
+export type RegionEntity = RegionFragmentFragment;
+//#endregion
+//# sourceMappingURL=operations.d.ts.map

package/dist/sdk/region/region-operations.d.ts

@@ -0,0 +1,30 @@
+import "./operations.js";
+import { TypedDocumentNode } from "@apollo/client";
+//#region src/sdk/region/region-operations.d.ts
+/**
+ * The region write document.
+ *
+ * Authored with the hand `gql` tag and excluded from the codegen `documents` glob (see
+ * `codegen.ts`), mirroring `sdk/session/auth-operations.ts`: the codegen `graphql()` factory is
+ * reserved for the reactive read path, and plucking this file would emit a duplicate
+ * `RegionUpdate` document alongside the hand-written one.
+ *
+ * The payload selects the full `Region` field set — `__typename` and `id` included — so the response
+ * merges into the normalized cache and every `RegionFragment` subscriber re-renders with no refetch.
+ * The merge carries the field values; only the nullable `Query.region` root field needs pointing at
+ * the entity, which the action's `update` does on the session's first write.
+ *
+ * Failures follow the repo's two-path contract: a rejected postal code arrives as payload `errors`,
+ * while transport and top-level GraphQL failures are infrastructure, mapped by the action handler to
+ * the one client-synthesized `NETWORK_ERROR`.
+ */
+/**
+ * A typed rejection of a region write. `code` is the server's `RegionErrorCode` (`INVALID_POSTAL_CODE`,
+ * `UNSERVED_POSTAL_CODE`) or the client-minted `NETWORK_ERROR`; `RegionError` keys its copy on it.
+ */
+export type RegionUserError = Readonly<{
+  code?: string;
+  message: string;
+}>;
+//#endregion
+//# sourceMappingURL=region-operations.d.ts.map

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

@@ -0,0 +1,23 @@
+import { gql } from "../graphql-tag.js";
+//#region src/sdk/region/region-operations.ts
+const REGION_UPDATE = gql`
+  mutation RegionUpdate($postalCode: String!) {
+    regionUpdate(postalCode: $postalCode) {
+      __typename
+      region {
+        __typename
+        id
+        postalCode
+        city
+      }
+      errors {
+        code
+        message
+      }
+    }
+  }
+`;
+//#endregion
+export { REGION_UPDATE };
+
+//# sourceMappingURL=region-operations.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"region-operations.js","names":[],"sources":["../../../src/sdk/region/region-operations.ts"],"sourcesContent":["import type { TypedDocumentNode } from '@apollo/client';\nimport { gql } from '../graphql-tag.js';\nimport type { RegionEntity } from './operations.js';\n\n/**\n * The region write document.\n *\n * Authored with the hand `gql` tag and excluded from the codegen `documents` glob (see\n * `codegen.ts`), mirroring `sdk/session/auth-operations.ts`: the codegen `graphql()` factory is\n * reserved for the reactive read path, and plucking this file would emit a duplicate\n * `RegionUpdate` document alongside the hand-written one.\n *\n * The payload selects the full `Region` field set — `__typename` and `id` included — so the response\n * merges into the normalized cache and every `RegionFragment` subscriber re-renders with no refetch.\n * The merge carries the field values; only the nullable `Query.region` root field needs pointing at\n * the entity, which the action's `update` does on the session's first write.\n *\n * Failures follow the repo's two-path contract: a rejected postal code arrives as payload `errors`,\n * while transport and top-level GraphQL failures are infrastructure, mapped by the action handler to\n * the one client-synthesized `NETWORK_ERROR`.\n */\n\n/**\n * A typed rejection of a region write. `code` is the server's `RegionErrorCode` (`INVALID_POSTAL_CODE`,\n * `UNSERVED_POSTAL_CODE`) or the client-minted `NETWORK_ERROR`; `RegionError` keys its copy on it.\n */\nexport type RegionUserError = Readonly<{ code?: string; message: string }>;\n\nexport type RegionUpdatePayloadEntity = Readonly<{\n  __typename: 'RegionUpdatePayload';\n  region: RegionEntity | null;\n  errors: readonly RegionUserError[];\n}>;\n\ntype RegionUpdateData = Readonly<{ regionUpdate: RegionUpdatePayloadEntity }>;\n\nexport const REGION_UPDATE: TypedDocumentNode<RegionUpdateData, { postalCode: string }> = gql`\n  mutation RegionUpdate($postalCode: String!) {\n    regionUpdate(postalCode: $postalCode) {\n      __typename\n      region {\n        __typename\n        id\n        postalCode\n        city\n      }\n      errors {\n        code\n        message\n      }\n    }\n  }\n`;\n"],"mappings":";;AAoCA,MAAa,gBAA6E,GAAG"}

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

@@ -0,0 +1,23 @@
+import "../../core/dist/index.js";
+import { RegionUserError } from "./region-operations.js";
+//#region src/sdk/region/use-region-actions.d.ts
+/**
+ * The `region` action namespace — the one sanctioned client write surface for the shopper's active
+ * region (docs/storefront-core/adr-0010-actions-own-the-write-side.md).
+ *
+ * The single action is async/pessimistic: the handler awaits the mutation and only the
+ * server-confirmed payload changes the cache. A region cannot be guessed client-side, because the
+ * server owns both the postal-code format and the city it resolves to. The handler is stateless — no
+ * reactive vars, no module state — since the active value lives in the normalized cache and its
+ * persistence is the server's business.
+ *
+ * `setPostalCode` resolves the payload `errors` (empty on success) and never throws for an expected
+ * outcome; infrastructure failures resolve as the synthetic `NETWORK_ERROR`, matching `session` and
+ * `identity`.
+ */
+export type RegionActions = Readonly<{
+  /** Submits a postal code as the shopper typed it (masked). Resolves to [] on success. Never throws. */
+  setPostalCode: (postalCode: string) => Promise<readonly RegionUserError[]>;
+}>;
+//#endregion
+//# sourceMappingURL=use-region-actions.d.ts.map

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

@@ -0,0 +1,66 @@
+"use client";
+import { defineActions } from "../../core/dist/actions/registry.js";
+import "../../core/dist/index.js";
+import { REGION_UPDATE } from "./region-operations.js";
+import { useMutation } from "@apollo/client/react";
+import { useCallback, useMemo } from "react";
+//#region src/sdk/region/use-region-actions.ts
+const NETWORK_USER_ERROR = {
+	code: "NETWORK_ERROR",
+	message: "Unable to set your region. Please try again."
+};
+/**
+* The `region` namespace hook. Registered with the first-party action registry via `regionActions`
+* below; the compiler-emitted `RegionActionProvider` calls it and threads the narrowed method into
+* each consumer's `$actions.region`.
+*
+* A successful write merges the payload into the normalized cache — it selects the full `Region`
+* field set including `id`, so Apollo identifies the entity and every `RegionFragment` subscriber
+* re-renders with no refetch. The merge alone is not enough on the *first* write of a session,
+* though: `Query.region` is nullable, so a shopper who arrives with no region has `null` stored at
+* that root field, and merging an entity never repoints a root field that holds null. The reactive
+* read resolves the entity *through* `Query.region`, so it would keep reading null until a reload.
+* Hence the `update` below, which points the root field at the entity. It is idempotent, so writes
+* after the first cost nothing.
+*
+* The masked value is passed through untouched: the server strips the mask and echoes back a
+* formatted `postalCode`, which keeps one authority on format instead of two that can diverge.
+*/
+function useRegionActions() {
+	const [updateMutation] = useMutation(REGION_UPDATE, { update(cache, { data }) {
+		const region = data?.regionUpdate.region;
+		if (!region) return;
+		const id = cache.identify(region);
+		if (!id) return;
+		cache.modify({ fields: { region: (_existing, { toReference }) => toReference(id) } });
+	} });
+	const setPostalCode = useCallback(async (postalCode) => {
+		try {
+			return (await updateMutation({ variables: { postalCode } })).data?.regionUpdate.errors ?? [];
+		} catch (error) {
+			console.error("[region.setPostalCode] regionUpdate failed", error);
+			return [NETWORK_USER_ERROR];
+		}
+	}, [updateMutation]);
+	return useMemo(() => ({ setPostalCode }), [setPostalCode]);
+}
+defineActions({
+	namespace: "region",
+	description: "Mutation-backed writes against the shopper's active region (postal code).",
+	provider: {
+		name: "RegionActionProvider",
+		importPath: "@vtex/faststore/internal/client"
+	},
+	methods: { setPostalCode: {
+		description: "Set the active region from a postal code, masked or bare (async/pessimistic). Resolves the payload errors.",
+		payload: [{
+			name: "postalCode",
+			type: "string"
+		}]
+	} },
+	use: useRegionActions
+});
+//#endregion
+export { useRegionActions };
+
+//# sourceMappingURL=use-region-actions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-region-actions.js","names":[],"sources":["../../../src/sdk/region/use-region-actions.ts"],"sourcesContent":["'use client';\n\nimport { useMutation } from '@apollo/client/react';\nimport { defineActions } from '@vtex/fs-core';\nimport { useCallback, useMemo } from 'react';\nimport { REGION_UPDATE, type RegionUserError } from './region-operations.js';\n\nexport type { RegionUserError } from './region-operations.js';\n\n/**\n * The `region` action namespace — the one sanctioned client write surface for the shopper's active\n * region (docs/storefront-core/adr-0010-actions-own-the-write-side.md).\n *\n * The single action is async/pessimistic: the handler awaits the mutation and only the\n * server-confirmed payload changes the cache. A region cannot be guessed client-side, because the\n * server owns both the postal-code format and the city it resolves to. The handler is stateless — no\n * reactive vars, no module state — since the active value lives in the normalized cache and its\n * persistence is the server's business.\n *\n * `setPostalCode` resolves the payload `errors` (empty on success) and never throws for an expected\n * outcome; infrastructure failures resolve as the synthetic `NETWORK_ERROR`, matching `session` and\n * `identity`.\n */\nexport type RegionActions = Readonly<{\n  /** Submits a postal code as the shopper typed it (masked). Resolves to [] on success. Never throws. */\n  setPostalCode: (postalCode: string) => Promise<readonly RegionUserError[]>;\n}>;\n\nconst NETWORK_USER_ERROR: RegionUserError = {\n  code: 'NETWORK_ERROR',\n  message: 'Unable to set your region. Please try again.',\n};\n\n/**\n * The `region` namespace hook. Registered with the first-party action registry via `regionActions`\n * below; the compiler-emitted `RegionActionProvider` calls it and threads the narrowed method into\n * each consumer's `$actions.region`.\n *\n * A successful write merges the payload into the normalized cache — it selects the full `Region`\n * field set including `id`, so Apollo identifies the entity and every `RegionFragment` subscriber\n * re-renders with no refetch. The merge alone is not enough on the *first* write of a session,\n * though: `Query.region` is nullable, so a shopper who arrives with no region has `null` stored at\n * that root field, and merging an entity never repoints a root field that holds null. The reactive\n * read resolves the entity *through* `Query.region`, so it would keep reading null until a reload.\n * Hence the `update` below, which points the root field at the entity. It is idempotent, so writes\n * after the first cost nothing.\n *\n * The masked value is passed through untouched: the server strips the mask and echoes back a\n * formatted `postalCode`, which keeps one authority on format instead of two that can diverge.\n */\nexport function useRegionActions(): RegionActions {\n  const [updateMutation] = useMutation(REGION_UPDATE, {\n    update(cache, { data }) {\n      const region = data?.regionUpdate.region;\n      if (!region) return;\n      const id = cache.identify(region);\n      if (!id) return;\n      cache.modify({\n        fields: {\n          region: (_existing, { toReference }) => toReference(id),\n        },\n      });\n    },\n  });\n\n  const setPostalCode = useCallback<RegionActions['setPostalCode']>(\n    async (postalCode) => {\n      try {\n        const result = await updateMutation({ variables: { postalCode } });\n        return result.data?.regionUpdate.errors ?? [];\n      } catch (error) {\n        console.error('[region.setPostalCode] regionUpdate failed', error);\n        return [NETWORK_USER_ERROR];\n      }\n    },\n    [updateMutation],\n  );\n\n  return useMemo(() => ({ setPostalCode }), [setPostalCode]);\n}\n\n/**\n * Declares the `region` action namespace — the single source of truth for its method/payload\n * metadata, runtime provider, and `use` hook (mirrors `sessionActions`). The native catalog builder\n * (`scripts/build-catalog.mjs`) statically reads this call to emit `actions.json`; at runtime\n * `RegionActionProvider` calls `useRegionActions` directly.\n */\nexport const regionActions = defineActions({\n  namespace: 'region',\n  description: \"Mutation-backed writes against the shopper's active region (postal code).\",\n  provider: { name: 'RegionActionProvider', importPath: '@vtex/faststore/internal/client' },\n  methods: {\n    setPostalCode: {\n      description:\n        'Set the active region from a postal code, masked or bare (async/pessimistic). Resolves the payload errors.',\n      payload: [{ name: 'postalCode', type: 'string' }],\n    },\n  },\n  use: useRegionActions,\n});\n"],"mappings":";;;;;;;AA4BA,MAAM,qBAAsC;CAC1C,MAAM;CACN,SAAS;AACX;;;;;;;;;;;;;;;;;;AAmBA,SAAgB,mBAAkC;CAChD,MAAM,CAAC,kBAAkB,YAAY,eAAe,EAClD,OAAO,OAAO,EAAE,QAAQ;EACtB,MAAM,SAAS,MAAM,aAAa;EAClC,IAAI,CAAC,QAAQ;EACb,MAAM,KAAK,MAAM,SAAS,MAAM;EAChC,IAAI,CAAC,IAAI;EACT,MAAM,OAAO,EACX,QAAQ,EACN,SAAS,WAAW,EAAE,kBAAkB,YAAY,EAAE,EACxD,EACF,CAAC;CACH,EACF,CAAC;CAED,MAAM,gBAAgB,YACpB,OAAO,eAAe;EACpB,IAAI;GAEF,QAAO,MADc,eAAe,EAAE,WAAW,EAAE,WAAW,EAAE,CAAC,EAAA,CACnD,MAAM,aAAa,UAAU,CAAC;EAC9C,SAAS,OAAO;GACd,QAAQ,MAAM,8CAA8C,KAAK;GACjE,OAAO,CAAC,kBAAkB;EAC5B;CACF,GACA,CAAC,cAAc,CACjB;CAEA,OAAO,eAAe,EAAE,cAAc,IAAI,CAAC,aAAa,CAAC;AAC3D;AAQ6B,cAAc;CACzC,WAAW;CACX,aAAa;CACb,UAAU;EAAE,MAAM;EAAwB,YAAY;CAAkC;CACxF,SAAS,EACP,eAAe;EACb,aACE;EACF,SAAS,CAAC;GAAE,MAAM;GAAc,MAAM;EAAS,CAAC;CAClD,EACF;CACA,KAAK;AACP,CAAC"}

package/dist/sdk/seller.js

@@ -0,0 +1,11 @@
+//#region src/sdk/seller.ts
+/** Resolves the seller a matter should read for a variant: the one flagged `isDefault`, or the first
+*  seller as a fallback when none is marked default. Shared by BuyButton and Pricing so the
+*  default-seller rule lives in one place instead of being duplicated per transform. */
+function resolveDefaultSeller(sellers) {
+	return sellers.find((seller) => seller.isDefault) ?? sellers[0];
+}
+//#endregion
+export { resolveDefaultSeller };
+
+//# sourceMappingURL=seller.js.map

package/dist/sdk/seller.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"seller.js","names":[],"sources":["../../src/sdk/seller.ts"],"sourcesContent":["/** Resolves the seller a matter should read for a variant: the one flagged `isDefault`, or the first\n *  seller as a fallback when none is marked default. Shared by BuyButton and Pricing so the\n *  default-seller rule lives in one place instead of being duplicated per transform. */\nexport function resolveDefaultSeller<T extends { isDefault: boolean }>(sellers: readonly T[]): T | undefined {\n  return sellers.find((seller) => seller.isDefault) ?? sellers[0];\n}\n"],"mappings":";;;;AAGA,SAAgB,qBAAuD,SAAsC;CAC3G,OAAO,QAAQ,MAAM,WAAW,OAAO,SAAS,KAAK,QAAQ;AAC/D"}