@vtex/faststore 0.0.6 → 0.0.8

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

@@ -0,0 +1,247 @@
+"use client";
+import { defineActions } from "../../core/dist/actions/registry.js";
+import "../../core/dist/index.js";
+import { loggableErrorName } from "../../utils/loggable-error-name.js";
+import { CUSTOMER_ADDRESS_BOOK_IDENTITY, CUSTOMER_ADDRESS_CREATE, CUSTOMER_ADDRESS_DELETE, CUSTOMER_ADDRESS_UPDATE } from "./operations.js";
+import { useMutation } from "@apollo/client/react";
+import { useCallback, useMemo } from "react";
+import { CombinedGraphQLErrors } from "@apollo/client/errors";
+//#region src/sdk/address/use-address-actions.ts
+const NETWORK_ERROR = {
+	code: "NETWORK_ERROR",
+	message: "Unable to complete the request. Please try again.",
+	field: null
+};
+const UNAUTHORIZED_ERROR = {
+	code: "UNAUTHORIZED",
+	message: "Your session has expired. Please sign in again.",
+	field: null
+};
+/**
+* The writes answer an expired session with a top-level `UNAUTHORIZED`, never a `userError`.
+* Collapsing it into `NETWORK_ERROR` would offer a retry that cannot succeed, so it keeps its own
+* code and the caller can send the shopper back to sign-in.
+*/
+function toUserError(error) {
+	if (CombinedGraphQLErrors.is(error) && error.errors.some(({ extensions }) => extensions?.code === "UNAUTHORIZED")) return UNAUTHORIZED_ERROR;
+	return NETWORK_ERROR;
+}
+/**
+* Takes the address out of the cached address book, then evicts its entity. Apollo hides a dangling
+* reference when it reads a list, so the evict alone would empty the visible list; the explicit edit
+* keeps the stored array free of references to an entity that is gone. With no book cached, only the
+* evict runs.
+*/
+function dropAddress(cache, id) {
+	const book = cache.readQuery({ query: CUSTOMER_ADDRESS_BOOK_IDENTITY })?.customerAddressBook;
+	if (book) cache.modify({
+		id: cache.identify(book),
+		fields: { addresses(existing, { readField }) {
+			return existing.filter((reference) => readField("id", reference) !== id);
+		} }
+	});
+	cache.evict({ id: cache.identify({
+		__typename: "CustomerAddress",
+		id
+	}) });
+}
+/** True when the server says the address is not among the shopper's own: gone, or never theirs. */
+function isNotFound(userErrors) {
+	return userErrors?.some(({ code }) => code === "NOT_FOUND") ?? false;
+}
+/**
+* The `address` namespace hook. Registered with the first-party action registry via `addressActions`
+* below; the compiler-emitted `AddressActionProvider` calls it and threads the narrowed methods into
+* each consumer's `$actions.address`.
+*/
+function useAddressActions() {
+	const [createMutation] = useMutation(CUSTOMER_ADDRESS_CREATE, { update(cache, { data }) {
+		const address = data?.customerAddressCreate.customerAddress;
+		if (!address) return;
+		const book = cache.readQuery({ query: CUSTOMER_ADDRESS_BOOK_IDENTITY })?.customerAddressBook;
+		if (!book) return;
+		cache.modify({
+			id: cache.identify(book),
+			fields: { addresses(existing, { readField, toReference }) {
+				if (existing.some((reference) => readField("id", reference) === address.id)) return existing;
+				const created = toReference(address);
+				return created ? [...existing, created] : existing;
+			} }
+		});
+	} });
+	const [updateMutation] = useMutation(CUSTOMER_ADDRESS_UPDATE, { update(cache, { data }, { variables }) {
+		if (variables && isNotFound(data?.customerAddressUpdate.userErrors)) dropAddress(cache, variables.id);
+	} });
+	const [removeMutation] = useMutation(CUSTOMER_ADDRESS_DELETE, { update(cache, { data }, { variables }) {
+		const payload = data?.customerAddressDelete;
+		if (!payload) return;
+		if (payload.userErrors.length === 0 && payload.deletedCustomerAddressId) dropAddress(cache, payload.deletedCustomerAddressId);
+		else if (variables && isNotFound(payload.userErrors)) dropAddress(cache, variables.id);
+	} });
+	const create = useCallback(async (payload) => {
+		try {
+			return (await createMutation({ variables: { input: payload } })).data?.customerAddressCreate.userErrors ?? [];
+		} catch (error) {
+			console.error("[address.create] customerAddressCreate failed", loggableErrorName(error));
+			return [toUserError(error)];
+		}
+	}, [createMutation]);
+	const update = useCallback(async ({ id, ...input }) => {
+		try {
+			return (await updateMutation({ variables: {
+				id,
+				input
+			} })).data?.customerAddressUpdate.userErrors ?? [];
+		} catch (error) {
+			console.error("[address.update] customerAddressUpdate failed", loggableErrorName(error));
+			return [toUserError(error)];
+		}
+	}, [updateMutation]);
+	const remove = useCallback(async ({ id }) => {
+		try {
+			return (await removeMutation({ variables: { id } })).data?.customerAddressDelete.userErrors ?? [];
+		} catch (error) {
+			console.error("[address.remove] customerAddressDelete failed", loggableErrorName(error));
+			return [toUserError(error)];
+		}
+	}, [removeMutation]);
+	return useMemo(() => ({
+		create,
+		update,
+		remove
+	}), [
+		create,
+		update,
+		remove
+	]);
+}
+defineActions({
+	namespace: "address",
+	description: "Mutation-backed writes against the shopper's saved addresses (create, update, remove).",
+	provider: {
+		name: "AddressActionProvider",
+		importPath: "@vtex/faststore/internal/client"
+	},
+	methods: {
+		create: {
+			description: "Save a new address and add it to the cached address book (async/pessimistic). Resolves the payload userErrors.",
+			payload: [
+				{
+					name: "country",
+					type: "string"
+				},
+				{
+					name: "recipientName",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "street",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "number",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "complement",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "neighborhood",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "city",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "state",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "postalCode",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "reference",
+					type: "string",
+					optional: true
+				}
+			]
+		},
+		update: {
+			description: "Change a saved address (async/pessimistic). Omitted fields are kept; an empty string erases. Resolves the payload userErrors.",
+			payload: [
+				{
+					name: "id",
+					type: "string"
+				},
+				{
+					name: "recipientName",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "street",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "number",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "complement",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "neighborhood",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "city",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "state",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "postalCode",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "reference",
+					type: "string",
+					optional: true
+				}
+			]
+		},
+		remove: {
+			description: "Remove a saved address once the server confirms (async/pessimistic). Resolves the payload userErrors.",
+			payload: [{
+				name: "id",
+				type: "string"
+			}]
+		}
+	},
+	use: useAddressActions
+});
+//#endregion
+export { useAddressActions };
+
+//# sourceMappingURL=use-address-actions.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"use-address-actions.js","names":[],"sources":["../../../src/sdk/address/use-address-actions.ts"],"sourcesContent":["'use client';\n\nimport type { ApolloCache, Reference } from '@apollo/client';\nimport { CombinedGraphQLErrors } from '@apollo/client/errors';\nimport { useMutation } from '@apollo/client/react';\nimport { defineActions } from '@vtex/fs-core';\nimport { useCallback, useMemo } from 'react';\nimport { loggableErrorName } from '../../utils/loggable-error-name.js';\nimport {\n  type AddressCreatePayload,\n  type AddressRemovePayload,\n  type AddressUpdatePayload,\n  CUSTOMER_ADDRESS_BOOK_IDENTITY,\n  CUSTOMER_ADDRESS_CREATE,\n  CUSTOMER_ADDRESS_DELETE,\n  CUSTOMER_ADDRESS_UPDATE,\n  type CustomerAddressUserError,\n} from './operations.js';\n\nexport type {\n  AddressCreatePayload,\n  AddressRemovePayload,\n  AddressUpdatePayload,\n  CustomerAddressUserError,\n} from './operations.js';\n\n/**\n * The `address` action namespace: the one sanctioned client write surface for the shopper's saved\n * addresses (docs/storefront-core/adr-0010-actions-own-the-write-side.md,\n * docs/features/my-account-address-book/rfc.md § Address actions).\n *\n * Every method is async and pessimistic: the cache changes only after the server answers. Each\n * resolves to the payload's `userErrors` (empty on success), with their `field`, so the caller can\n * mark the field. None rejects for an expected outcome. ADR-0010 has handlers surface `userErrors`\n * through the `notifications` action; that action does not exist yet, so the caller presents them.\n */\nexport type AddressActions = Readonly<{\n  /** Save a new address. Appends it to the cached address book on success. Never rejects. */\n  create: (payload: AddressCreatePayload) => Promise<readonly CustomerAddressUserError[]>;\n  /**\n   * Change a saved address. Omit a field to keep it; an empty string erases it. Subscribers update\n   * through the normalized cache. Never rejects.\n   */\n  update: (payload: AddressUpdatePayload) => Promise<readonly CustomerAddressUserError[]>;\n  /**\n   * Remove a saved address. The list changes only once the server confirms. A `NOT_FOUND` answer\n   * means the server no longer has it, so it leaves the cache too. Never rejects.\n   */\n  remove: (payload: AddressRemovePayload) => Promise<readonly CustomerAddressUserError[]>;\n}>;\n\nconst NETWORK_ERROR: CustomerAddressUserError = {\n  code: 'NETWORK_ERROR',\n  message: 'Unable to complete the request. Please try again.',\n  field: null,\n};\n\nconst UNAUTHORIZED_ERROR: CustomerAddressUserError = {\n  code: 'UNAUTHORIZED',\n  message: 'Your session has expired. Please sign in again.',\n  field: null,\n};\n\n/**\n * The writes answer an expired session with a top-level `UNAUTHORIZED`, never a `userError`.\n * Collapsing it into `NETWORK_ERROR` would offer a retry that cannot succeed, so it keeps its own\n * code and the caller can send the shopper back to sign-in.\n */\nfunction toUserError(error: unknown): CustomerAddressUserError {\n  if (CombinedGraphQLErrors.is(error) && error.errors.some(({ extensions }) => extensions?.code === 'UNAUTHORIZED')) {\n    return UNAUTHORIZED_ERROR;\n  }\n  return NETWORK_ERROR;\n}\n\n/**\n * Takes the address out of the cached address book, then evicts its entity. Apollo hides a dangling\n * reference when it reads a list, so the evict alone would empty the visible list; the explicit edit\n * keeps the stored array free of references to an entity that is gone. With no book cached, only the\n * evict runs.\n */\nfunction dropAddress(cache: ApolloCache, id: string): void {\n  const book = cache.readQuery({ query: CUSTOMER_ADDRESS_BOOK_IDENTITY })?.customerAddressBook;\n  if (book) {\n    cache.modify({\n      id: cache.identify(book),\n      fields: {\n        addresses(existing: readonly Reference[], { readField }) {\n          return existing.filter((reference) => readField('id', reference) !== id);\n        },\n      },\n    });\n  }\n  cache.evict({ id: cache.identify({ __typename: 'CustomerAddress', id }) });\n}\n\n/** True when the server says the address is not among the shopper's own: gone, or never theirs. */\nfunction isNotFound(userErrors: readonly CustomerAddressUserError[] | undefined): boolean {\n  return userErrors?.some(({ code }) => code === 'NOT_FOUND') ?? false;\n}\n\n/**\n * The `address` namespace hook. Registered with the first-party action registry via `addressActions`\n * below; the compiler-emitted `AddressActionProvider` calls it and threads the narrowed methods into\n * each consumer's `$actions.address`.\n */\nexport function useAddressActions(): AddressActions {\n  const [createMutation] = useMutation(CUSTOMER_ADDRESS_CREATE, {\n    update(cache, { data }) {\n      const address = data?.customerAddressCreate.customerAddress;\n      if (!address) return;\n      // Read from the cache only: no mounted list means nothing to append to, and the entity the\n      // payload just normalized is all this write leaves behind.\n      const book = cache.readQuery({ query: CUSTOMER_ADDRESS_BOOK_IDENTITY })?.customerAddressBook;\n      if (!book) return;\n      cache.modify({\n        id: cache.identify(book),\n        fields: {\n          addresses(existing: readonly Reference[], { readField, toReference }) {\n            if (existing.some((reference) => readField('id', reference) === address.id)) {\n              return existing;\n            }\n            const created = toReference(address);\n            return created ? [...existing, created] : existing;\n          },\n        },\n      });\n    },\n  });\n\n  const [updateMutation] = useMutation(CUSTOMER_ADDRESS_UPDATE, {\n    update(cache, { data }, { variables }) {\n      if (variables && isNotFound(data?.customerAddressUpdate.userErrors)) dropAddress(cache, variables.id);\n    },\n  });\n\n  const [removeMutation] = useMutation(CUSTOMER_ADDRESS_DELETE, {\n    update(cache, { data }, { variables }) {\n      const payload = data?.customerAddressDelete;\n      if (!payload) return;\n      if (payload.userErrors.length === 0 && payload.deletedCustomerAddressId) {\n        dropAddress(cache, payload.deletedCustomerAddressId);\n      } else if (variables && isNotFound(payload.userErrors)) {\n        dropAddress(cache, variables.id);\n      }\n    },\n  });\n\n  const create = useCallback<AddressActions['create']>(\n    async (payload) => {\n      try {\n        const result = await createMutation({ variables: { input: payload } });\n        return result.data?.customerAddressCreate.userErrors ?? [];\n      } catch (error) {\n        // Log only the error name: the message can echo a submitted address value (PII).\n        console.error('[address.create] customerAddressCreate failed', loggableErrorName(error));\n        return [toUserError(error)];\n      }\n    },\n    [createMutation],\n  );\n\n  const update = useCallback<AddressActions['update']>(\n    async ({ id, ...input }) => {\n      try {\n        // Forwarded unmapped: an empty string is an explicit erase and must survive to the wire.\n        const result = await updateMutation({ variables: { id, input } });\n        return result.data?.customerAddressUpdate.userErrors ?? [];\n      } catch (error) {\n        console.error('[address.update] customerAddressUpdate failed', loggableErrorName(error));\n        return [toUserError(error)];\n      }\n    },\n    [updateMutation],\n  );\n\n  const remove = useCallback<AddressActions['remove']>(\n    async ({ id }) => {\n      try {\n        const result = await removeMutation({ variables: { id } });\n        return result.data?.customerAddressDelete.userErrors ?? [];\n      } catch (error) {\n        console.error('[address.remove] customerAddressDelete failed', loggableErrorName(error));\n        return [toUserError(error)];\n      }\n    },\n    [removeMutation],\n  );\n\n  return useMemo(() => ({ create, update, remove }), [create, update, remove]);\n}\n\n/**\n * Declares the `address` action namespace: the single source of truth for its method/payload\n * metadata, runtime provider, and `use` hook. The native catalog builder\n * (`scripts/build-catalog.mjs`) statically reads this call to emit `actions.json`; at runtime\n * `AddressActionProvider` calls `useAddressActions` directly.\n */\nexport const addressActions = defineActions({\n  namespace: 'address',\n  description: \"Mutation-backed writes against the shopper's saved addresses (create, update, remove).\",\n  provider: { name: 'AddressActionProvider', importPath: '@vtex/faststore/internal/client' },\n  methods: {\n    create: {\n      description:\n        'Save a new address and add it to the cached address book (async/pessimistic). Resolves the payload userErrors.',\n      payload: [\n        { name: 'country', type: 'string' },\n        { name: 'recipientName', type: 'string', optional: true },\n        { name: 'street', type: 'string', optional: true },\n        { name: 'number', type: 'string', optional: true },\n        { name: 'complement', type: 'string', optional: true },\n        { name: 'neighborhood', type: 'string', optional: true },\n        { name: 'city', type: 'string', optional: true },\n        { name: 'state', type: 'string', optional: true },\n        { name: 'postalCode', type: 'string', optional: true },\n        { name: 'reference', type: 'string', optional: true },\n      ],\n    },\n    update: {\n      description:\n        'Change a saved address (async/pessimistic). Omitted fields are kept; an empty string erases. Resolves the payload userErrors.',\n      payload: [\n        { name: 'id', type: 'string' },\n        { name: 'recipientName', type: 'string', optional: true },\n        { name: 'street', type: 'string', optional: true },\n        { name: 'number', type: 'string', optional: true },\n        { name: 'complement', type: 'string', optional: true },\n        { name: 'neighborhood', type: 'string', optional: true },\n        { name: 'city', type: 'string', optional: true },\n        { name: 'state', type: 'string', optional: true },\n        { name: 'postalCode', type: 'string', optional: true },\n        { name: 'reference', type: 'string', optional: true },\n      ],\n    },\n    remove: {\n      description:\n        'Remove a saved address once the server confirms (async/pessimistic). Resolves the payload userErrors.',\n      payload: [{ name: 'id', type: 'string' }],\n    },\n  },\n  use: useAddressActions,\n});\n"],"mappings":";;;;;;;;;AAmDA,MAAM,gBAA0C;CAC9C,MAAM;CACN,SAAS;CACT,OAAO;AACT;AAEA,MAAM,qBAA+C;CACnD,MAAM;CACN,SAAS;CACT,OAAO;AACT;;;;;;AAOA,SAAS,YAAY,OAA0C;CAC7D,IAAI,sBAAsB,GAAG,KAAK,KAAK,MAAM,OAAO,MAAM,EAAE,iBAAiB,YAAY,SAAS,cAAc,GAC9G,OAAO;CAET,OAAO;AACT;;;;;;;AAQA,SAAS,YAAY,OAAoB,IAAkB;CACzD,MAAM,OAAO,MAAM,UAAU,EAAE,OAAO,+BAA+B,CAAC,CAAC,EAAE;CACzE,IAAI,MACF,MAAM,OAAO;EACX,IAAI,MAAM,SAAS,IAAI;EACvB,QAAQ,EACN,UAAU,UAAgC,EAAE,aAAa;GACvD,OAAO,SAAS,QAAQ,cAAc,UAAU,MAAM,SAAS,MAAM,EAAE;EACzE,EACF;CACF,CAAC;CAEH,MAAM,MAAM,EAAE,IAAI,MAAM,SAAS;EAAE,YAAY;EAAmB;CAAG,CAAC,EAAE,CAAC;AAC3E;;AAGA,SAAS,WAAW,YAAsE;CACxF,OAAO,YAAY,MAAM,EAAE,WAAW,SAAS,WAAW,KAAK;AACjE;;;;;;AAOA,SAAgB,oBAAoC;CAClD,MAAM,CAAC,kBAAkB,YAAY,yBAAyB,EAC5D,OAAO,OAAO,EAAE,QAAQ;EACtB,MAAM,UAAU,MAAM,sBAAsB;EAC5C,IAAI,CAAC,SAAS;EAGd,MAAM,OAAO,MAAM,UAAU,EAAE,OAAO,+BAA+B,CAAC,CAAC,EAAE;EACzE,IAAI,CAAC,MAAM;EACX,MAAM,OAAO;GACX,IAAI,MAAM,SAAS,IAAI;GACvB,QAAQ,EACN,UAAU,UAAgC,EAAE,WAAW,eAAe;IACpE,IAAI,SAAS,MAAM,cAAc,UAAU,MAAM,SAAS,MAAM,QAAQ,EAAE,GACxE,OAAO;IAET,MAAM,UAAU,YAAY,OAAO;IACnC,OAAO,UAAU,CAAC,GAAG,UAAU,OAAO,IAAI;GAC5C,EACF;EACF,CAAC;CACH,EACF,CAAC;CAED,MAAM,CAAC,kBAAkB,YAAY,yBAAyB,EAC5D,OAAO,OAAO,EAAE,QAAQ,EAAE,aAAa;EACrC,IAAI,aAAa,WAAW,MAAM,sBAAsB,UAAU,GAAG,YAAY,OAAO,UAAU,EAAE;CACtG,EACF,CAAC;CAED,MAAM,CAAC,kBAAkB,YAAY,yBAAyB,EAC5D,OAAO,OAAO,EAAE,QAAQ,EAAE,aAAa;EACrC,MAAM,UAAU,MAAM;EACtB,IAAI,CAAC,SAAS;EACd,IAAI,QAAQ,WAAW,WAAW,KAAK,QAAQ,0BAC7C,YAAY,OAAO,QAAQ,wBAAwB;OAC9C,IAAI,aAAa,WAAW,QAAQ,UAAU,GACnD,YAAY,OAAO,UAAU,EAAE;CAEnC,EACF,CAAC;CAED,MAAM,SAAS,YACb,OAAO,YAAY;EACjB,IAAI;GAEF,QAAO,MADc,eAAe,EAAE,WAAW,EAAE,OAAO,QAAQ,EAAE,CAAC,EAAA,CACvD,MAAM,sBAAsB,cAAc,CAAC;EAC3D,SAAS,OAAO;GAEd,QAAQ,MAAM,iDAAiD,kBAAkB,KAAK,CAAC;GACvF,OAAO,CAAC,YAAY,KAAK,CAAC;EAC5B;CACF,GACA,CAAC,cAAc,CACjB;CAEA,MAAM,SAAS,YACb,OAAO,EAAE,IAAI,GAAG,YAAY;EAC1B,IAAI;GAGF,QAAO,MADc,eAAe,EAAE,WAAW;IAAE;IAAI;GAAM,EAAE,CAAC,EAAA,CAClD,MAAM,sBAAsB,cAAc,CAAC;EAC3D,SAAS,OAAO;GACd,QAAQ,MAAM,iDAAiD,kBAAkB,KAAK,CAAC;GACvF,OAAO,CAAC,YAAY,KAAK,CAAC;EAC5B;CACF,GACA,CAAC,cAAc,CACjB;CAEA,MAAM,SAAS,YACb,OAAO,EAAE,SAAS;EAChB,IAAI;GAEF,QAAO,MADc,eAAe,EAAE,WAAW,EAAE,GAAG,EAAE,CAAC,EAAA,CAC3C,MAAM,sBAAsB,cAAc,CAAC;EAC3D,SAAS,OAAO;GACd,QAAQ,MAAM,iDAAiD,kBAAkB,KAAK,CAAC;GACvF,OAAO,CAAC,YAAY,KAAK,CAAC;EAC5B;CACF,GACA,CAAC,cAAc,CACjB;CAEA,OAAO,eAAe;EAAE;EAAQ;EAAQ;CAAO,IAAI;EAAC;EAAQ;EAAQ;CAAM,CAAC;AAC7E;AAQ8B,cAAc;CAC1C,WAAW;CACX,aAAa;CACb,UAAU;EAAE,MAAM;EAAyB,YAAY;CAAkC;CACzF,SAAS;EACP,QAAQ;GACN,aACE;GACF,SAAS;IACP;KAAE,MAAM;KAAW,MAAM;IAAS;IAClC;KAAE,MAAM;KAAiB,MAAM;KAAU,UAAU;IAAK;IACxD;KAAE,MAAM;KAAU,MAAM;KAAU,UAAU;IAAK;IACjD;KAAE,MAAM;KAAU,MAAM;KAAU,UAAU;IAAK;IACjD;KAAE,MAAM;KAAc,MAAM;KAAU,UAAU;IAAK;IACrD;KAAE,MAAM;KAAgB,MAAM;KAAU,UAAU;IAAK;IACvD;KAAE,MAAM;KAAQ,MAAM;KAAU,UAAU;IAAK;IAC/C;KAAE,MAAM;KAAS,MAAM;KAAU,UAAU;IAAK;IAChD;KAAE,MAAM;KAAc,MAAM;KAAU,UAAU;IAAK;IACrD;KAAE,MAAM;KAAa,MAAM;KAAU,UAAU;IAAK;GACtD;EACF;EACA,QAAQ;GACN,aACE;GACF,SAAS;IACP;KAAE,MAAM;KAAM,MAAM;IAAS;IAC7B;KAAE,MAAM;KAAiB,MAAM;KAAU,UAAU;IAAK;IACxD;KAAE,MAAM;KAAU,MAAM;KAAU,UAAU;IAAK;IACjD;KAAE,MAAM;KAAU,MAAM;KAAU,UAAU;IAAK;IACjD;KAAE,MAAM;KAAc,MAAM;KAAU,UAAU;IAAK;IACrD;KAAE,MAAM;KAAgB,MAAM;KAAU,UAAU;IAAK;IACvD;KAAE,MAAM;KAAQ,MAAM;KAAU,UAAU;IAAK;IAC/C;KAAE,MAAM;KAAS,MAAM;KAAU,UAAU;IAAK;IAChD;KAAE,MAAM;KAAc,MAAM;KAAU,UAAU;IAAK;IACrD;KAAE,MAAM;KAAa,MAAM;KAAU,UAAU;IAAK;GACtD;EACF;EACA,QAAQ;GACN,aACE;GACF,SAAS,CAAC;IAAE,MAAM;IAAM,MAAM;GAAS,CAAC;EAC1C;CACF;CACA,KAAK;AACP,CAAC"}

package/dist/sdk/address/use-address-by-postal-code.js

@@ -0,0 +1,57 @@
+"use client";
+import { withRequestTimeout } from "../shipping/request-timeout.js";
+import { loggableErrorName } from "../../utils/loggable-error-name.js";
+import { ADDRESS_BY_POSTAL_CODE } from "./postal-code-lookup-operations.js";
+import { getApolloContext } from "@apollo/client/react";
+import { useCallback, useContext } from "react";
+//#region src/sdk/address/use-address-by-postal-code.ts
+const FAILED = { status: "failed" };
+/**
+* Postal-code lookup SDK hook (specs/sfs-3430-address-by-postal-code.md).
+*
+* Returns a callback that runs the `AddressByPostalCode` query once per call and never rejects. It
+* reads the client from `getApolloContext()` (a non-throwing read, like `useShippingSimulation`), and
+* skips the cache: a lookup is a shopper's postal code, so it is neither read from nor written to the
+* normalized cache. The hook does not check `hasPostalCodeLookup(country)`; the caller decides
+* whether a country is worth a request, and when to ask and which reply is stale.
+*
+* A failure logs the error's name, as the address actions do, and never the country, the postal
+* code, or a message.
+*/
+function useAddressByPostalCode() {
+	const { client } = useContext(getApolloContext());
+	return useCallback(async ({ country, postalCode }) => {
+		try {
+			if (!client) throw new Error("No Apollo client is available.");
+			const result = await withRequestTimeout((signal) => client.query({
+				query: ADDRESS_BY_POSTAL_CODE,
+				variables: {
+					country,
+					postalCode
+				},
+				fetchPolicy: "no-cache",
+				context: { fetchOptions: { signal } }
+			}));
+			if (result.error) throw result.error;
+			if (!result.data) throw new Error("The lookup returned no data.");
+			const address = result.data.addressByPostalCode;
+			if (!address) return { status: "notFound" };
+			return {
+				status: "found",
+				address: {
+					city: address.city ?? null,
+					state: address.state ?? null,
+					street: address.street ?? null,
+					neighborhood: address.neighborhood ?? null
+				}
+			};
+		} catch (error) {
+			console.error("[address.postalCodeLookup] addressByPostalCode failed", loggableErrorName(error));
+			return FAILED;
+		}
+	}, [client]);
+}
+//#endregion
+export { useAddressByPostalCode };
+
+//# sourceMappingURL=use-address-by-postal-code.js.map

package/dist/sdk/address/use-address-by-postal-code.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-address-by-postal-code.js","names":[],"sources":["../../../src/sdk/address/use-address-by-postal-code.ts"],"sourcesContent":["'use client';\n\nimport { getApolloContext } from '@apollo/client/react';\nimport { useCallback, useContext } from 'react';\nimport { loggableErrorName } from '../../utils/loggable-error-name.js';\nimport { withRequestTimeout } from '../shipping/request-timeout.js';\nimport { ADDRESS_BY_POSTAL_CODE } from './postal-code-lookup-operations.js';\n\n/**\n * The fields the platform resolves for a postal code. Each is `null` where the platform left it\n * blank, and the state is as the platform codes it, so it may not match a select's option values.\n */\nexport type PostalCodeLookupFields = Readonly<{\n  city: string | null;\n  state: string | null;\n  street: string | null;\n  neighborhood: string | null;\n}>;\n\n/**\n * The three things a lookup can come to. `notFound` is a code the platform does not know; `failed`\n * is a lookup that could not run (no client, a GraphQL error, a transport error, a timeout). The two\n * never look alike, so a caller can show an outage differently from a typo.\n */\nexport type PostalCodeLookupResult =\n  | Readonly<{ status: 'found'; address: PostalCodeLookupFields }>\n  | Readonly<{ status: 'notFound' }>\n  | Readonly<{ status: 'failed' }>;\n\nconst FAILED: PostalCodeLookupResult = { status: 'failed' };\n\n/**\n * Postal-code lookup SDK hook (specs/sfs-3430-address-by-postal-code.md).\n *\n * Returns a callback that runs the `AddressByPostalCode` query once per call and never rejects. It\n * reads the client from `getApolloContext()` (a non-throwing read, like `useShippingSimulation`), and\n * skips the cache: a lookup is a shopper's postal code, so it is neither read from nor written to the\n * normalized cache. The hook does not check `hasPostalCodeLookup(country)`; the caller decides\n * whether a country is worth a request, and when to ask and which reply is stale.\n *\n * A failure logs the error's name, as the address actions do, and never the country, the postal\n * code, or a message.\n */\nexport function useAddressByPostalCode(): (input: {\n  country: string;\n  postalCode: string;\n}) => Promise<PostalCodeLookupResult> {\n  const { client } = useContext(getApolloContext());\n\n  return useCallback(\n    async ({ country, postalCode }): Promise<PostalCodeLookupResult> => {\n      try {\n        if (!client) {\n          throw new Error('No Apollo client is available.');\n        }\n        const result = await withRequestTimeout((signal) =>\n          client.query({\n            query: ADDRESS_BY_POSTAL_CODE,\n            variables: { country, postalCode },\n            fetchPolicy: 'no-cache',\n            context: { fetchOptions: { signal } },\n          }),\n        );\n\n        if (result.error) {\n          throw result.error;\n        }\n        if (!result.data) {\n          throw new Error('The lookup returned no data.');\n        }\n\n        const address = result.data.addressByPostalCode;\n        if (!address) {\n          return { status: 'notFound' };\n        }\n        return {\n          status: 'found',\n          address: {\n            city: address.city ?? null,\n            state: address.state ?? null,\n            street: address.street ?? null,\n            neighborhood: address.neighborhood ?? null,\n          },\n        };\n      } catch (error) {\n        console.error('[address.postalCodeLookup] addressByPostalCode failed', loggableErrorName(error));\n        return FAILED;\n      }\n    },\n    [client],\n  );\n}\n"],"mappings":";;;;;;;AA6BA,MAAM,SAAiC,EAAE,QAAQ,SAAS;;;;;;;;;;;;;AAc1D,SAAgB,yBAGsB;CACpC,MAAM,EAAE,WAAW,WAAW,iBAAiB,CAAC;CAEhD,OAAO,YACL,OAAO,EAAE,SAAS,iBAAkD;EAClE,IAAI;GACF,IAAI,CAAC,QACH,MAAM,IAAI,MAAM,gCAAgC;GAElD,MAAM,SAAS,MAAM,oBAAoB,WACvC,OAAO,MAAM;IACX,OAAO;IACP,WAAW;KAAE;KAAS;IAAW;IACjC,aAAa;IACb,SAAS,EAAE,cAAc,EAAE,OAAO,EAAE;GACtC,CAAC,CACH;GAEA,IAAI,OAAO,OACT,MAAM,OAAO;GAEf,IAAI,CAAC,OAAO,MACV,MAAM,IAAI,MAAM,8BAA8B;GAGhD,MAAM,UAAU,OAAO,KAAK;GAC5B,IAAI,CAAC,SACH,OAAO,EAAE,QAAQ,WAAW;GAE9B,OAAO;IACL,QAAQ;IACR,SAAS;KACP,MAAM,QAAQ,QAAQ;KACtB,OAAO,QAAQ,SAAS;KACxB,QAAQ,QAAQ,UAAU;KAC1B,cAAc,QAAQ,gBAAgB;IACxC;GACF;EACF,SAAS,OAAO;GACd,QAAQ,MAAM,yDAAyD,kBAAkB,KAAK,CAAC;GAC/F,OAAO;EACT;CACF,GACA,CAAC,MAAM,CACT;AACF"}

package/dist/sdk/address/validate-address.js

@@ -0,0 +1,62 @@
+import { ACCOUNT_MAX_LENGTH } from "./constants.js";
+import { resolveLibraryError } from "./messages.js";
+import { declaredMaxLength, toFormValues } from "./schema.js";
+import { createFormState, getVisibleFields, resolveFieldOptions, validate } from "@vtex/country-forms";
+//#region src/sdk/address/validate-address.ts
+const REQUIRED = {
+	code: "required",
+	messageId: "fs/address.error.required"
+};
+const INVALID = {
+	code: "invalid",
+	messageId: "fs/address.error.invalid"
+};
+function isAddressField(name) {
+	return Object.hasOwn(ACCOUNT_MAX_LENGTH, name);
+}
+function isOutsideOptions(field, values, fields) {
+	const value = values[field.name] ?? "";
+	if (field.type !== "select" || value === "") return false;
+	const controller = fields.find(({ name }) => name === field.dependsOn);
+	if (controller && ((values[controller.name] ?? "") === "" || isOutsideOptions(controller, values, fields))) return false;
+	return !(resolveFieldOptions(field, values) ?? []).some((option) => option.value === value);
+}
+/**
+* Checks a draft or a stored address against its country's rules and the account's own rules, and
+* returns at most one error per field. A field's first error wins, in this order: the library's,
+* a select value outside its options, then the account's maximum length.
+*
+* The account's rules cover what the library does not: `recipientName` must not be blank,
+* `reference` and the address name may be empty, every free-text field has a maximum length, and a
+* select's value must be one of the options the library resolves. Keys outside the ten address
+* fields are ignored, so a merged record can carry `geoCoordinate` as it is.
+*/
+function validateAddress(values, rules) {
+	const text = toFormValues(values);
+	const fields = getVisibleFields(rules.schema, text);
+	const errors = {};
+	const declared = new Map(rules.schema.fields.map((field) => [field.name, field]));
+	const libraryErrors = validate(createFormState(rules.schema, text), rules.schema);
+	for (const [name, key] of Object.entries(libraryErrors)) {
+		const field = declared.get(name);
+		if (isAddressField(name) && field) errors[name] = resolveLibraryError(key, {
+			country: rules.country,
+			maxLength: declaredMaxLength(field)
+		});
+	}
+	for (const field of fields) if (isAddressField(field.name) && !errors[field.name] && isOutsideOptions(field, text, fields)) errors[field.name] = INVALID;
+	if ((values.recipientName ?? "").trim() === "" && !errors.recipientName) errors.recipientName = REQUIRED;
+	for (const name of Object.keys(ACCOUNT_MAX_LENGTH).filter(isAddressField)) {
+		const maxLength = ACCOUNT_MAX_LENGTH[name];
+		if (!errors[name] && (values[name] ?? "").length > maxLength) errors[name] = {
+			code: "tooLong",
+			messageId: "fs/address.error.too-long",
+			values: { maxLength }
+		};
+	}
+	return errors;
+}
+//#endregion
+export { validateAddress };
+
+//# sourceMappingURL=validate-address.js.map

package/dist/sdk/address/validate-address.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate-address.js","names":[],"sources":["../../../src/sdk/address/validate-address.ts"],"sourcesContent":["import {\n  createFormState,\n  type FieldDefinition,\n  type FormValues,\n  getVisibleFields,\n  resolveFieldOptions,\n  validate,\n} from '@vtex/country-forms';\nimport { ACCOUNT_MAX_LENGTH } from './constants.js';\nimport { resolveLibraryError } from './messages.js';\nimport { declaredMaxLength, toFormValues } from './schema.js';\nimport type { AddressErrors, AddressFieldError, AddressFieldName, AddressValues, CountryRules } from './types.js';\n\nconst REQUIRED: AddressFieldError = { code: 'required', messageId: 'fs/address.error.required' };\nconst INVALID: AddressFieldError = { code: 'invalid', messageId: 'fs/address.error.invalid' };\n\nfunction isAddressField(name: string): name is AddressFieldName {\n  return Object.hasOwn(ACCOUNT_MAX_LENGTH, name);\n}\n\nfunction isOutsideOptions(field: FieldDefinition, values: FormValues, fields: readonly FieldDefinition[]): boolean {\n  const value = values[field.name] ?? '';\n  if (field.type !== 'select' || value === '') {\n    return false;\n  }\n\n  // A dependent list exists only for a valid controller; the controller carries its own error.\n  const controller = fields.find(({ name }) => name === field.dependsOn);\n  if (controller && ((values[controller.name] ?? '') === '' || isOutsideOptions(controller, values, fields))) {\n    return false;\n  }\n\n  return !(resolveFieldOptions(field, values) ?? []).some((option) => option.value === value);\n}\n\n/**\n * Checks a draft or a stored address against its country's rules and the account's own rules, and\n * returns at most one error per field. A field's first error wins, in this order: the library's,\n * a select value outside its options, then the account's maximum length.\n *\n * The account's rules cover what the library does not: `recipientName` must not be blank,\n * `reference` and the address name may be empty, every free-text field has a maximum length, and a\n * select's value must be one of the options the library resolves. Keys outside the ten address\n * fields are ignored, so a merged record can carry `geoCoordinate` as it is.\n */\nexport function validateAddress(values: AddressValues, rules: CountryRules): AddressErrors {\n  const text = toFormValues(values);\n  const fields = getVisibleFields(rules.schema, text);\n  const errors: Partial<Record<AddressFieldName, AddressFieldError>> = {};\n\n  const declared = new Map(rules.schema.fields.map((field) => [field.name, field]));\n  const libraryErrors = validate(createFormState(rules.schema, text), rules.schema);\n  for (const [name, key] of Object.entries(libraryErrors)) {\n    const field = declared.get(name);\n    if (isAddressField(name) && field) {\n      errors[name] = resolveLibraryError(key, { country: rules.country, maxLength: declaredMaxLength(field) });\n    }\n  }\n\n  for (const field of fields) {\n    if (isAddressField(field.name) && !errors[field.name] && isOutsideOptions(field, text, fields)) {\n      errors[field.name] = INVALID;\n    }\n  }\n\n  if ((values.recipientName ?? '').trim() === '' && !errors.recipientName) {\n    errors.recipientName = REQUIRED;\n  }\n\n  for (const name of Object.keys(ACCOUNT_MAX_LENGTH).filter(isAddressField)) {\n    const maxLength = ACCOUNT_MAX_LENGTH[name];\n    if (!errors[name] && (values[name] ?? '').length > maxLength) {\n      errors[name] = { code: 'tooLong', messageId: 'fs/address.error.too-long', values: { maxLength } };\n    }\n  }\n\n  return errors;\n}\n"],"mappings":";;;;;AAaA,MAAM,WAA8B;CAAE,MAAM;CAAY,WAAW;AAA4B;AAC/F,MAAM,UAA6B;CAAE,MAAM;CAAW,WAAW;AAA2B;AAE5F,SAAS,eAAe,MAAwC;CAC9D,OAAO,OAAO,OAAO,oBAAoB,IAAI;AAC/C;AAEA,SAAS,iBAAiB,OAAwB,QAAoB,QAA6C;CACjH,MAAM,QAAQ,OAAO,MAAM,SAAS;CACpC,IAAI,MAAM,SAAS,YAAY,UAAU,IACvC,OAAO;CAIT,MAAM,aAAa,OAAO,MAAM,EAAE,WAAW,SAAS,MAAM,SAAS;CACrE,IAAI,gBAAgB,OAAO,WAAW,SAAS,QAAQ,MAAM,iBAAiB,YAAY,QAAQ,MAAM,IACtG,OAAO;CAGT,OAAO,EAAE,oBAAoB,OAAO,MAAM,KAAK,CAAC,EAAA,CAAG,MAAM,WAAW,OAAO,UAAU,KAAK;AAC5F;;;;;;;;;;;AAYA,SAAgB,gBAAgB,QAAuB,OAAoC;CACzF,MAAM,OAAO,aAAa,MAAM;CAChC,MAAM,SAAS,iBAAiB,MAAM,QAAQ,IAAI;CAClD,MAAM,SAA+D,CAAC;CAEtE,MAAM,WAAW,IAAI,IAAI,MAAM,OAAO,OAAO,KAAK,UAAU,CAAC,MAAM,MAAM,KAAK,CAAC,CAAC;CAChF,MAAM,gBAAgB,SAAS,gBAAgB,MAAM,QAAQ,IAAI,GAAG,MAAM,MAAM;CAChF,KAAK,MAAM,CAAC,MAAM,QAAQ,OAAO,QAAQ,aAAa,GAAG;EACvD,MAAM,QAAQ,SAAS,IAAI,IAAI;EAC/B,IAAI,eAAe,IAAI,KAAK,OAC1B,OAAO,QAAQ,oBAAoB,KAAK;GAAE,SAAS,MAAM;GAAS,WAAW,kBAAkB,KAAK;EAAE,CAAC;CAE3G;CAEA,KAAK,MAAM,SAAS,QAClB,IAAI,eAAe,MAAM,IAAI,KAAK,CAAC,OAAO,MAAM,SAAS,iBAAiB,OAAO,MAAM,MAAM,GAC3F,OAAO,MAAM,QAAQ;CAIzB,KAAK,OAAO,iBAAiB,GAAA,CAAI,KAAK,MAAM,MAAM,CAAC,OAAO,eACxD,OAAO,gBAAgB;CAGzB,KAAK,MAAM,QAAQ,OAAO,KAAK,kBAAkB,CAAC,CAAC,OAAO,cAAc,GAAG;EACzE,MAAM,YAAY,mBAAmB;EACrC,IAAI,CAAC,OAAO,UAAU,OAAO,SAAS,GAAA,CAAI,SAAS,WACjD,OAAO,QAAQ;GAAE,MAAM;GAAW,WAAW;GAA6B,QAAQ,EAAE,UAAU;EAAE;CAEpG;CAEA,OAAO;AACT"}

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

@@ -2,6 +2,7 @@
 import { defineActions } from "../../core/dist/actions/registry.js";
 import "../../core/dist/index.js";
 import { DEFAULT_ANALYTICS_DESTINATION, resolveAnalyticsDestination, useAnalyticsDestination } from "./analytics-destination.js";
+import { loggableErrorName } from "../../utils/loggable-error-name.js";
 import { useCallback, useMemo, useRef } from "react";
 //#region src/sdk/analytics/use-analytics-actions.ts
 function toEcommerceItems(items) {
@@ -61,7 +62,7 @@ function useAnalyticsActions() {
 			});
 			pushToDataLayer(event, destination);
 		} catch (error) {
-			console.error(`[analytics.track] window.${destination} push failed`, error);
+			console.error(`[analytics.track] window.${destination} push failed`, loggableErrorName(error));
 		}
 	}, [override]);
 	return useMemo(() => ({ track }), [track]);

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

@@ -1 +1 @@
-{"version":3,"file":"use-analytics-actions.js","names":[],"sources":["../../../src/sdk/analytics/use-analytics-actions.ts"],"sourcesContent":["'use client';\n\nimport { defineActions } from '@vtex/fs-core';\nimport { useCallback, useMemo, useRef } from 'react';\nimport {\n  type AnalyticsDestination,\n  DEFAULT_ANALYTICS_DESTINATION,\n  resolveAnalyticsDestination,\n  useAnalyticsDestination,\n} from './analytics-destination.js';\n\n/**\n * The `analytics` action namespace (specs/analytics-events.md) — a dispatcher-flavor namespace\n * (docs/storefront-core/adr-0010-actions-own-the-write-side.md; docs/storefront-core/rfc-actions.md\n * § \"Three binding flavors\") that pushes the two standard payment analytics events,\n * `add_payment_info` and `purchase`, to a `window` array — `window.dataLayer` by default, the\n * GTM/GA4-recognizable event convention. It never touches the Apollo cache, never issues a GraphQL\n * operation, and never throws: a broken tag-manager script can never block payment submission or\n * order placement.\n *\n * The destination array is configurable at build time\n * (specs/make-the-analytics-destination-configurable-for.md; T120) — see\n * `./analytics-destination.js` for the resolution precedence, validation, and the\n * `AnalyticsDestinationProvider`. The pushed entry's shape is a data *contract* (a well-known\n * browser-global array shape), not a *provider* — no vendor SDK, no server call. A future\n * platform/foundation epic may replace this sink with a real `AnalyticsContext`; the\n * `track(event: AnalyticsEvent): void` signature and `AnalyticsActions` type are the stable public\n * contract every call site depends on until then (US-4).\n */\n\nexport type AnalyticsMoney = Readonly<{\n  amount: number;\n  currencyCode: string;\n}>;\n\nexport type AnalyticsLineItem = Readonly<{\n  sku: string;\n  name: string;\n  price: AnalyticsMoney;\n  quantity: number;\n}>;\n\n/** Dispatched by T7's CardEntry, before opening the transaction. */\nexport type AddPaymentInfoEvent = Readonly<{\n  name: 'add_payment_info';\n  value: AnalyticsMoney;\n  /**\n   * Derived from the selected method's `groupName` at the moment this fires (T140, Decision 5).\n   * Optional because the event fires on the cart total, before a method is necessarily selected —\n   * omitted rather than a guessed literal, so a downstream consumer never reads a false payment kind.\n   * `toEcommercePayload` below drops the corresponding key entirely when this is absent.\n   */\n  paymentType?: 'Credit Card' | 'Debit Card';\n  items?: readonly AnalyticsLineItem[];\n}>;\n\n/** Dispatched by T13's usePlaceOrder, after a successful gateway callback. */\nexport type PurchaseEvent = Readonly<{\n  name: 'purchase';\n  transactionId: string;\n  value: AnalyticsMoney;\n  items?: readonly AnalyticsLineItem[];\n}>;\n\nexport type AnalyticsEvent = AddPaymentInfoEvent | PurchaseEvent;\n\nexport type AnalyticsActions = Readonly<{\n  /** Push a standard analytics event to window.dataLayer. Fire-and-forget; never throws. */\n  track: (event: AnalyticsEvent) => void;\n}>;\n\n/** The shape pushed onto window.dataLayer — GTM/GA4's own event convention. */\nexport type AnalyticsDataLayerEvent = Readonly<{\n  event: 'add_payment_info' | 'purchase';\n  ecommerce: Record<string, unknown>;\n}>;\n\nfunction toEcommerceItems(items: readonly AnalyticsLineItem[] | undefined) {\n  return (items ?? []).map((item) => ({\n    item_id: item.sku,\n    item_name: item.name,\n    price: item.price.amount,\n    quantity: item.quantity,\n  }));\n}\n\nfunction toEcommercePayload(event: AnalyticsEvent): Record<string, unknown> {\n  if (event.name === 'add_payment_info') {\n    return {\n      currency: event.value.currencyCode,\n      value: event.value.amount,\n      // T140, Decision 5: the key itself must be absent when `paymentType` is, not merely `undefined`\n      // — `pushToDataLayer` pushes this object as-is with no serialization step to strip it, and\n      // `'payment_type' in ecommerce` would otherwise still report true.\n      ...(event.paymentType !== undefined ? { payment_type: event.paymentType } : {}),\n      items: toEcommerceItems(event.items),\n    };\n  }\n  return {\n    transaction_id: event.transactionId,\n    currency: event.value.currencyCode,\n    value: event.value.amount,\n    items: toEcommerceItems(event.items),\n  };\n}\n\n// `Reflect.get`/`Reflect.set` below match `storefront-provider.tsx`'s existing pattern for a\n// dynamic `window` key — they are not a security mechanism. `Reflect.set(target, k, v)` invokes\n// an inherited setter and creates no own property, exactly like `window[k] = v` would; it adds no\n// hardening on its own. What actually blocks prototype pollution is\n// `isValidAnalyticsDestination`'s denylist and identifier pattern, checked by the caller before\n// `destination` ever reaches this function, plus the non-array guard immediately below.\n//\n// The cast below, not a `declare global` augmentation of `Window`, is what keeps this typed: a\n// global augmentation here would ship inside this package's own `.d.ts` output and hand every\n// consumer's `window.dataLayer` this package's narrow event union, wrong for a store that also\n// pushes its own GTM events (packages/components/scripts/dist-type-boundary.test.ts). `destination`\n// is a runtime string anyway — `Window` has nothing to look up a dynamic key against — so the local\n// cast is also the only type-safe option, not merely the non-leaking one.\nfunction pushToDataLayer(event: AnalyticsEvent, destination: AnalyticsDestination): void {\n  if (typeof window === 'undefined') return;\n\n  let layer = Reflect.get(window, destination) as AnalyticsDataLayerEvent[] | undefined;\n  if (layer === undefined) {\n    layer = [];\n    Reflect.set(window, destination, layer);\n  } else if (!Array.isArray(layer)) {\n    console.error(`[analytics.track] window.${destination} already exists and is not an array; the event was dropped`);\n    return;\n  }\n\n  layer.push({ event: event.name, ecommerce: toEcommercePayload(event) });\n}\n\n/**\n * The `analytics` namespace hook. Registered with the first-party action registry via\n * `analyticsActions` below; the compiler-emitted `AnalyticsActionProvider` calls it and threads\n * the narrowed methods into each consumer's `$actions.analytics`. Dispatcher flavor: no\n * `useMutation`, no cache read or write (ADR-0010). Fire-and-forget — `track` never throws, so a\n * broken tag-manager script can never block payment submission or order placement.\n */\nexport function useAnalyticsActions(): AnalyticsActions {\n  const override = useAnalyticsDestination();\n  // Scoped to this hook instance, not the module: \"logs once\" means once per mounted\n  // `useAnalyticsActions()`, so two independent call sites each still get their own first warning.\n  const hasLoggedRejectionRef = useRef(false);\n\n  const track = useCallback<AnalyticsActions['track']>(\n    (event) => {\n      // The SSR guard runs before any destination resolution is attempted — not just before the\n      // write. Preserved from the pre-T120 behaviour (US-3, \"SSR — no destination resolution\n      // attempted at all\").\n      if (typeof window === 'undefined') return;\n      let destination: AnalyticsDestination = DEFAULT_ANALYTICS_DESTINATION;\n      try {\n        destination = resolveAnalyticsDestination({\n          override,\n          hasLoggedRejection: hasLoggedRejectionRef,\n        });\n        pushToDataLayer(event, destination);\n      } catch (error) {\n        console.error(`[analytics.track] window.${destination} push failed`, error);\n      }\n    },\n    [override],\n  );\n\n  return useMemo(() => ({ track }), [track]);\n}\n\n/**\n * Declares the `analytics` action namespace — the single source of truth for its method/payload\n * metadata, runtime provider, and `use` hook (mirrors `cartActions`, `shippingActions`). The\n * native catalog builder (`scripts/build-catalog.mjs`) statically reads this call to emit\n * `actions.json`; at runtime `AnalyticsActionProvider` calls `useAnalyticsActions` directly.\n *\n * The `payload` below is a flattened, best-effort scalar approximation of `AnalyticsEvent` for\n * catalog/docs tooling: `ActionPayloadField.type` supports only scalar primitives and cannot\n * express a discriminated union or a nested `items` array. The TS `AnalyticsEvent` union above is\n * the source of truth for the real call shape.\n */\nexport const analyticsActions = defineActions({\n  namespace: 'analytics',\n  description:\n    'Dispatcher-flavor namespace that pushes standard add_payment_info / purchase events to window.dataLayer. Never touches the Apollo cache.',\n  provider: { name: 'AnalyticsActionProvider', importPath: '@vtex/faststore/internal/client' },\n  methods: {\n    track: {\n      description:\n        'Push a standard analytics event (add_payment_info | purchase) to window.dataLayer. Fire-and-forget; never throws.',\n      payload: [\n        { name: 'name', type: 'string' },\n        { name: 'currencyCode', type: 'string' },\n        { name: 'amount', type: 'number' },\n        { name: 'paymentType', type: 'string', optional: true },\n        { name: 'transactionId', type: 'string', optional: true },\n      ],\n    },\n  },\n  use: useAnalyticsActions,\n});\n"],"mappings":";;;;;;AA6EA,SAAS,iBAAiB,OAAiD;CACzE,QAAQ,SAAS,CAAC,EAAA,CAAG,KAAK,UAAU;EAClC,SAAS,KAAK;EACd,WAAW,KAAK;EAChB,OAAO,KAAK,MAAM;EAClB,UAAU,KAAK;CACjB,EAAE;AACJ;AAEA,SAAS,mBAAmB,OAAgD;CAC1E,IAAI,MAAM,SAAS,oBACjB,OAAO;EACL,UAAU,MAAM,MAAM;EACtB,OAAO,MAAM,MAAM;EAInB,GAAI,MAAM,gBAAgB,KAAA,IAAY,EAAE,cAAc,MAAM,YAAY,IAAI,CAAC;EAC7E,OAAO,iBAAiB,MAAM,KAAK;CACrC;CAEF,OAAO;EACL,gBAAgB,MAAM;EACtB,UAAU,MAAM,MAAM;EACtB,OAAO,MAAM,MAAM;EACnB,OAAO,iBAAiB,MAAM,KAAK;CACrC;AACF;AAeA,SAAS,gBAAgB,OAAuB,aAAyC;CACvF,IAAI,OAAO,WAAW,aAAa;CAEnC,IAAI,QAAQ,QAAQ,IAAI,QAAQ,WAAW;CAC3C,IAAI,UAAU,KAAA,GAAW;EACvB,QAAQ,CAAC;EACT,QAAQ,IAAI,QAAQ,aAAa,KAAK;CACxC,OAAO,IAAI,CAAC,MAAM,QAAQ,KAAK,GAAG;EAChC,QAAQ,MAAM,4BAA4B,YAAY,2DAA2D;EACjH;CACF;CAEA,MAAM,KAAK;EAAE,OAAO,MAAM;EAAM,WAAW,mBAAmB,KAAK;CAAE,CAAC;AACxE;;;;;;;;AASA,SAAgB,sBAAwC;CACtD,MAAM,WAAW,wBAAwB;CAGzC,MAAM,wBAAwB,OAAO,KAAK;CAE1C,MAAM,QAAQ,aACX,UAAU;EAIT,IAAI,OAAO,WAAW,aAAa;EACnC,IAAI,cAAoC;EACxC,IAAI;GACF,cAAc,4BAA4B;IACxC;IACA,oBAAoB;GACtB,CAAC;GACD,gBAAgB,OAAO,WAAW;EACpC,SAAS,OAAO;GACd,QAAQ,MAAM,4BAA4B,YAAY,eAAe,KAAK;EAC5E;CACF,GACA,CAAC,QAAQ,CACX;CAEA,OAAO,eAAe,EAAE,MAAM,IAAI,CAAC,KAAK,CAAC;AAC3C;AAagC,cAAc;CAC5C,WAAW;CACX,aACE;CACF,UAAU;EAAE,MAAM;EAA2B,YAAY;CAAkC;CAC3F,SAAS,EACP,OAAO;EACL,aACE;EACF,SAAS;GACP;IAAE,MAAM;IAAQ,MAAM;GAAS;GAC/B;IAAE,MAAM;IAAgB,MAAM;GAAS;GACvC;IAAE,MAAM;IAAU,MAAM;GAAS;GACjC;IAAE,MAAM;IAAe,MAAM;IAAU,UAAU;GAAK;GACtD;IAAE,MAAM;IAAiB,MAAM;IAAU,UAAU;GAAK;EAC1D;CACF,EACF;CACA,KAAK;AACP,CAAC"}
+{"version":3,"file":"use-analytics-actions.js","names":[],"sources":["../../../src/sdk/analytics/use-analytics-actions.ts"],"sourcesContent":["'use client';\n\nimport { defineActions } from '@vtex/fs-core';\nimport { useCallback, useMemo, useRef } from 'react';\nimport { loggableErrorName } from '../../utils/loggable-error-name.js';\nimport {\n  type AnalyticsDestination,\n  DEFAULT_ANALYTICS_DESTINATION,\n  resolveAnalyticsDestination,\n  useAnalyticsDestination,\n} from './analytics-destination.js';\n\n/**\n * The `analytics` action namespace (specs/analytics-events.md) — a dispatcher-flavor namespace\n * (docs/storefront-core/adr-0010-actions-own-the-write-side.md; docs/storefront-core/rfc-actions.md\n * § \"Three binding flavors\") that pushes the two standard payment analytics events,\n * `add_payment_info` and `purchase`, to a `window` array — `window.dataLayer` by default, the\n * GTM/GA4-recognizable event convention. It never touches the Apollo cache, never issues a GraphQL\n * operation, and never throws: a broken tag-manager script can never block payment submission or\n * order placement.\n *\n * The destination array is configurable at build time\n * (specs/make-the-analytics-destination-configurable-for.md; T120) — see\n * `./analytics-destination.js` for the resolution precedence, validation, and the\n * `AnalyticsDestinationProvider`. The pushed entry's shape is a data *contract* (a well-known\n * browser-global array shape), not a *provider* — no vendor SDK, no server call. A future\n * platform/foundation epic may replace this sink with a real `AnalyticsContext`; the\n * `track(event: AnalyticsEvent): void` signature and `AnalyticsActions` type are the stable public\n * contract every call site depends on until then (US-4).\n */\n\nexport type AnalyticsMoney = Readonly<{\n  amount: number;\n  currencyCode: string;\n}>;\n\nexport type AnalyticsLineItem = Readonly<{\n  sku: string;\n  name: string;\n  price: AnalyticsMoney;\n  quantity: number;\n}>;\n\n/** Dispatched by T7's CardEntry, before opening the transaction. */\nexport type AddPaymentInfoEvent = Readonly<{\n  name: 'add_payment_info';\n  value: AnalyticsMoney;\n  /**\n   * Derived from the selected method's `groupName` at the moment this fires (T140, Decision 5).\n   * Optional because the event fires on the cart total, before a method is necessarily selected —\n   * omitted rather than a guessed literal, so a downstream consumer never reads a false payment kind.\n   * `toEcommercePayload` below drops the corresponding key entirely when this is absent.\n   */\n  paymentType?: 'Credit Card' | 'Debit Card';\n  items?: readonly AnalyticsLineItem[];\n}>;\n\n/** Dispatched by T13's usePlaceOrder, after a successful gateway callback. */\nexport type PurchaseEvent = Readonly<{\n  name: 'purchase';\n  transactionId: string;\n  value: AnalyticsMoney;\n  items?: readonly AnalyticsLineItem[];\n}>;\n\nexport type AnalyticsEvent = AddPaymentInfoEvent | PurchaseEvent;\n\nexport type AnalyticsActions = Readonly<{\n  /** Push a standard analytics event to window.dataLayer. Fire-and-forget; never throws. */\n  track: (event: AnalyticsEvent) => void;\n}>;\n\n/** The shape pushed onto window.dataLayer — GTM/GA4's own event convention. */\nexport type AnalyticsDataLayerEvent = Readonly<{\n  event: 'add_payment_info' | 'purchase';\n  ecommerce: Record<string, unknown>;\n}>;\n\nfunction toEcommerceItems(items: readonly AnalyticsLineItem[] | undefined) {\n  return (items ?? []).map((item) => ({\n    item_id: item.sku,\n    item_name: item.name,\n    price: item.price.amount,\n    quantity: item.quantity,\n  }));\n}\n\nfunction toEcommercePayload(event: AnalyticsEvent): Record<string, unknown> {\n  if (event.name === 'add_payment_info') {\n    return {\n      currency: event.value.currencyCode,\n      value: event.value.amount,\n      // T140, Decision 5: the key itself must be absent when `paymentType` is, not merely `undefined`\n      // — `pushToDataLayer` pushes this object as-is with no serialization step to strip it, and\n      // `'payment_type' in ecommerce` would otherwise still report true.\n      ...(event.paymentType !== undefined ? { payment_type: event.paymentType } : {}),\n      items: toEcommerceItems(event.items),\n    };\n  }\n  return {\n    transaction_id: event.transactionId,\n    currency: event.value.currencyCode,\n    value: event.value.amount,\n    items: toEcommerceItems(event.items),\n  };\n}\n\n// `Reflect.get`/`Reflect.set` below match `storefront-provider.tsx`'s existing pattern for a\n// dynamic `window` key — they are not a security mechanism. `Reflect.set(target, k, v)` invokes\n// an inherited setter and creates no own property, exactly like `window[k] = v` would; it adds no\n// hardening on its own. What actually blocks prototype pollution is\n// `isValidAnalyticsDestination`'s denylist and identifier pattern, checked by the caller before\n// `destination` ever reaches this function, plus the non-array guard immediately below.\n//\n// The cast below, not a `declare global` augmentation of `Window`, is what keeps this typed: a\n// global augmentation here would ship inside this package's own `.d.ts` output and hand every\n// consumer's `window.dataLayer` this package's narrow event union, wrong for a store that also\n// pushes its own GTM events (packages/components/scripts/dist-type-boundary.test.ts). `destination`\n// is a runtime string anyway — `Window` has nothing to look up a dynamic key against — so the local\n// cast is also the only type-safe option, not merely the non-leaking one.\nfunction pushToDataLayer(event: AnalyticsEvent, destination: AnalyticsDestination): void {\n  if (typeof window === 'undefined') return;\n\n  let layer = Reflect.get(window, destination) as AnalyticsDataLayerEvent[] | undefined;\n  if (layer === undefined) {\n    layer = [];\n    Reflect.set(window, destination, layer);\n  } else if (!Array.isArray(layer)) {\n    console.error(`[analytics.track] window.${destination} already exists and is not an array; the event was dropped`);\n    return;\n  }\n\n  layer.push({ event: event.name, ecommerce: toEcommercePayload(event) });\n}\n\n/**\n * The `analytics` namespace hook. Registered with the first-party action registry via\n * `analyticsActions` below; the compiler-emitted `AnalyticsActionProvider` calls it and threads\n * the narrowed methods into each consumer's `$actions.analytics`. Dispatcher flavor: no\n * `useMutation`, no cache read or write (ADR-0010). Fire-and-forget — `track` never throws, so a\n * broken tag-manager script can never block payment submission or order placement.\n */\nexport function useAnalyticsActions(): AnalyticsActions {\n  const override = useAnalyticsDestination();\n  // Scoped to this hook instance, not the module: \"logs once\" means once per mounted\n  // `useAnalyticsActions()`, so two independent call sites each still get their own first warning.\n  const hasLoggedRejectionRef = useRef(false);\n\n  const track = useCallback<AnalyticsActions['track']>(\n    (event) => {\n      // The SSR guard runs before any destination resolution is attempted — not just before the\n      // write. Preserved from the pre-T120 behaviour (US-3, \"SSR — no destination resolution\n      // attempted at all\").\n      if (typeof window === 'undefined') return;\n      let destination: AnalyticsDestination = DEFAULT_ANALYTICS_DESTINATION;\n      try {\n        destination = resolveAnalyticsDestination({\n          override,\n          hasLoggedRejection: hasLoggedRejectionRef,\n        });\n        pushToDataLayer(event, destination);\n      } catch (error) {\n        console.error(`[analytics.track] window.${destination} push failed`, loggableErrorName(error));\n      }\n    },\n    [override],\n  );\n\n  return useMemo(() => ({ track }), [track]);\n}\n\n/**\n * Declares the `analytics` action namespace — the single source of truth for its method/payload\n * metadata, runtime provider, and `use` hook (mirrors `cartActions`, `shippingActions`). The\n * native catalog builder (`scripts/build-catalog.mjs`) statically reads this call to emit\n * `actions.json`; at runtime `AnalyticsActionProvider` calls `useAnalyticsActions` directly.\n *\n * The `payload` below is a flattened, best-effort scalar approximation of `AnalyticsEvent` for\n * catalog/docs tooling: `ActionPayloadField.type` supports only scalar primitives and cannot\n * express a discriminated union or a nested `items` array. The TS `AnalyticsEvent` union above is\n * the source of truth for the real call shape.\n */\nexport const analyticsActions = defineActions({\n  namespace: 'analytics',\n  description:\n    'Dispatcher-flavor namespace that pushes standard add_payment_info / purchase events to window.dataLayer. Never touches the Apollo cache.',\n  provider: { name: 'AnalyticsActionProvider', importPath: '@vtex/faststore/internal/client' },\n  methods: {\n    track: {\n      description:\n        'Push a standard analytics event (add_payment_info | purchase) to window.dataLayer. Fire-and-forget; never throws.',\n      payload: [\n        { name: 'name', type: 'string' },\n        { name: 'currencyCode', type: 'string' },\n        { name: 'amount', type: 'number' },\n        { name: 'paymentType', type: 'string', optional: true },\n        { name: 'transactionId', type: 'string', optional: true },\n      ],\n    },\n  },\n  use: useAnalyticsActions,\n});\n"],"mappings":";;;;;;;AA8EA,SAAS,iBAAiB,OAAiD;CACzE,QAAQ,SAAS,CAAC,EAAA,CAAG,KAAK,UAAU;EAClC,SAAS,KAAK;EACd,WAAW,KAAK;EAChB,OAAO,KAAK,MAAM;EAClB,UAAU,KAAK;CACjB,EAAE;AACJ;AAEA,SAAS,mBAAmB,OAAgD;CAC1E,IAAI,MAAM,SAAS,oBACjB,OAAO;EACL,UAAU,MAAM,MAAM;EACtB,OAAO,MAAM,MAAM;EAInB,GAAI,MAAM,gBAAgB,KAAA,IAAY,EAAE,cAAc,MAAM,YAAY,IAAI,CAAC;EAC7E,OAAO,iBAAiB,MAAM,KAAK;CACrC;CAEF,OAAO;EACL,gBAAgB,MAAM;EACtB,UAAU,MAAM,MAAM;EACtB,OAAO,MAAM,MAAM;EACnB,OAAO,iBAAiB,MAAM,KAAK;CACrC;AACF;AAeA,SAAS,gBAAgB,OAAuB,aAAyC;CACvF,IAAI,OAAO,WAAW,aAAa;CAEnC,IAAI,QAAQ,QAAQ,IAAI,QAAQ,WAAW;CAC3C,IAAI,UAAU,KAAA,GAAW;EACvB,QAAQ,CAAC;EACT,QAAQ,IAAI,QAAQ,aAAa,KAAK;CACxC,OAAO,IAAI,CAAC,MAAM,QAAQ,KAAK,GAAG;EAChC,QAAQ,MAAM,4BAA4B,YAAY,2DAA2D;EACjH;CACF;CAEA,MAAM,KAAK;EAAE,OAAO,MAAM;EAAM,WAAW,mBAAmB,KAAK;CAAE,CAAC;AACxE;;;;;;;;AASA,SAAgB,sBAAwC;CACtD,MAAM,WAAW,wBAAwB;CAGzC,MAAM,wBAAwB,OAAO,KAAK;CAE1C,MAAM,QAAQ,aACX,UAAU;EAIT,IAAI,OAAO,WAAW,aAAa;EACnC,IAAI,cAAoC;EACxC,IAAI;GACF,cAAc,4BAA4B;IACxC;IACA,oBAAoB;GACtB,CAAC;GACD,gBAAgB,OAAO,WAAW;EACpC,SAAS,OAAO;GACd,QAAQ,MAAM,4BAA4B,YAAY,eAAe,kBAAkB,KAAK,CAAC;EAC/F;CACF,GACA,CAAC,QAAQ,CACX;CAEA,OAAO,eAAe,EAAE,MAAM,IAAI,CAAC,KAAK,CAAC;AAC3C;AAagC,cAAc;CAC5C,WAAW;CACX,aACE;CACF,UAAU;EAAE,MAAM;EAA2B,YAAY;CAAkC;CAC3F,SAAS,EACP,OAAO;EACL,aACE;EACF,SAAS;GACP;IAAE,MAAM;IAAQ,MAAM;GAAS;GAC/B;IAAE,MAAM;IAAgB,MAAM;GAAS;GACvC;IAAE,MAAM;IAAU,MAAM;GAAS;GACjC;IAAE,MAAM;IAAe,MAAM;IAAU,UAAU;GAAK;GACtD;IAAE,MAAM;IAAiB,MAAM;IAAU,UAAU;GAAK;EAC1D;CACF,EACF;CACA,KAAK;AACP,CAAC"}

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

@@ -4,11 +4,36 @@ import { InMemoryCache } from "@apollo/client";
 /**
 * Per-entity normalization and field-merge rules for the Storefront cache.
 *
-* Empty in T1. Domain entries (Product, Cart, OrderForm, …) arrive with the
-* particles that need them — see docs/storefront-core/reference-free-particle-model.md § Typed documents and the shared cache,
-* "Out of Scope".
+* The cart and the order share three types whose ids neither can scope
+* (docs/features/order-placed/rfc.md, 3.4): a totalizer's id is its category
+* ("Items"), which the cart's totalizer line selects by; an address's id is the
+* saved address itself, masked on the order and not on the cart; and a
+* customization's id is the assembly ("Engraving"), which two lines of one cart
+* already share. Normalized, one record would overwrite the other, so each is
+* stored inside the record that holds it, and replaced on every write: safe
+* while every fragment selects the same subfields of each.
+*
+* The lists that hold them are the server's whole answer, so each write
+* replaces the list (`merge: false`). Apollo does the same by default, but warns
+* that data may be lost whenever such a list shrinks, as when a discount line
+* leaves the cart's totalizers; a merge by id would keep that stale line.
+*
+* Other domain entries arrive with the particles that need them — see
+* docs/storefront-core/reference-free-particle-model.md § Typed documents and the shared cache.
 */
-const typePolicies = {};
+const replaceList = { merge: false };
+const typePolicies = {
+	CartTotalizer: { keyFields: false },
+	Address: { keyFields: false },
+	CartItemCustomization: { keyFields: false },
+	Cart: { fields: { totalizers: replaceList } },
+	CartItem: { fields: { customizations: replaceList } },
+	CartItemComposition: { fields: { customizations: replaceList } },
+	Shipping: { fields: { savedAddresses: replaceList } },
+	Order: { fields: { totals: replaceList } },
+	SellerOrder: { fields: { totals: replaceList } },
+	OrderItem: { fields: { customizations: replaceList } }
+};
 /**
 * The single source of truth for InMemoryCache configuration. Both the
 * server-side `createClient` and the client-side `StorefrontProvider`

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

@@ -1 +1 @@
-{"version":3,"file":"storefront-cache.js","names":[],"sources":["../../../src/sdk/cache/storefront-cache.ts"],"sourcesContent":["import { InMemoryCache, type InMemoryCacheConfig, type TypePolicies } from '@apollo/client';\nimport { possibleTypes } from '../generated/fragment-types.js';\n\n/**\n * Per-entity normalization and field-merge rules for the Storefront cache.\n *\n * Empty in T1. Domain entries (Product, Cart, OrderForm, …) arrive with the\n * particles that need them — see docs/storefront-core/reference-free-particle-model.md § Typed documents and the shared cache,\n * \"Out of Scope\".\n */\nexport const typePolicies: TypePolicies = {};\n\nexport { possibleTypes };\n\n/**\n * The single source of truth for InMemoryCache configuration. Both the\n * server-side `createClient` and the client-side `StorefrontProvider`\n * consume this so SSR and CSR normalize entities identically.\n */\nexport function getCacheConfig(): InMemoryCacheConfig {\n  return {\n    typePolicies,\n    possibleTypes,\n  };\n}\n\n/**\n * The only place an `InMemoryCache` is constructed on the server path.\n * The client-side provider builds its cache from `getCacheConfig()` so the\n * config is shared verbatim without coupling to a specific InMemoryCache\n * subclass (the Next.js integration ships its own SSR-aware variant).\n */\nexport function buildCache(): InMemoryCache {\n  return new InMemoryCache(getCacheConfig());\n}\n"],"mappings":";;;;;;;;;;AAUA,MAAa,eAA6B,CAAC;;;;;;AAS3C,SAAgB,iBAAsC;CACpD,OAAO;EACL;EACA;CACF;AACF;;;;;;;AAQA,SAAgB,aAA4B;CAC1C,OAAO,IAAI,cAAc,eAAe,CAAC;AAC3C"}
+{"version":3,"file":"storefront-cache.js","names":[],"sources":["../../../src/sdk/cache/storefront-cache.ts"],"sourcesContent":["import { InMemoryCache, type InMemoryCacheConfig, type TypePolicies } from '@apollo/client';\nimport { possibleTypes } from '../generated/fragment-types.js';\n\n/**\n * Per-entity normalization and field-merge rules for the Storefront cache.\n *\n * The cart and the order share three types whose ids neither can scope\n * (docs/features/order-placed/rfc.md, 3.4): a totalizer's id is its category\n * (\"Items\"), which the cart's totalizer line selects by; an address's id is the\n * saved address itself, masked on the order and not on the cart; and a\n * customization's id is the assembly (\"Engraving\"), which two lines of one cart\n * already share. Normalized, one record would overwrite the other, so each is\n * stored inside the record that holds it, and replaced on every write: safe\n * while every fragment selects the same subfields of each.\n *\n * The lists that hold them are the server's whole answer, so each write\n * replaces the list (`merge: false`). Apollo does the same by default, but warns\n * that data may be lost whenever such a list shrinks, as when a discount line\n * leaves the cart's totalizers; a merge by id would keep that stale line.\n *\n * Other domain entries arrive with the particles that need them — see\n * docs/storefront-core/reference-free-particle-model.md § Typed documents and the shared cache.\n */\nconst replaceList = { merge: false } as const;\n\nexport const typePolicies: TypePolicies = {\n  CartTotalizer: { keyFields: false },\n  Address: { keyFields: false },\n  CartItemCustomization: { keyFields: false },\n  Cart: { fields: { totalizers: replaceList } },\n  CartItem: { fields: { customizations: replaceList } },\n  CartItemComposition: { fields: { customizations: replaceList } },\n  Shipping: { fields: { savedAddresses: replaceList } },\n  Order: { fields: { totals: replaceList } },\n  SellerOrder: { fields: { totals: replaceList } },\n  OrderItem: { fields: { customizations: replaceList } },\n};\n\nexport { possibleTypes };\n\n/**\n * The single source of truth for InMemoryCache configuration. Both the\n * server-side `createClient` and the client-side `StorefrontProvider`\n * consume this so SSR and CSR normalize entities identically.\n */\nexport function getCacheConfig(): InMemoryCacheConfig {\n  return {\n    typePolicies,\n    possibleTypes,\n  };\n}\n\n/**\n * The only place an `InMemoryCache` is constructed on the server path.\n * The client-side provider builds its cache from `getCacheConfig()` so the\n * config is shared verbatim without coupling to a specific InMemoryCache\n * subclass (the Next.js integration ships its own SSR-aware variant).\n */\nexport function buildCache(): InMemoryCache {\n  return new InMemoryCache(getCacheConfig());\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAuBA,MAAM,cAAc,EAAE,OAAO,MAAM;AAEnC,MAAa,eAA6B;CACxC,eAAe,EAAE,WAAW,MAAM;CAClC,SAAS,EAAE,WAAW,MAAM;CAC5B,uBAAuB,EAAE,WAAW,MAAM;CAC1C,MAAM,EAAE,QAAQ,EAAE,YAAY,YAAY,EAAE;CAC5C,UAAU,EAAE,QAAQ,EAAE,gBAAgB,YAAY,EAAE;CACpD,qBAAqB,EAAE,QAAQ,EAAE,gBAAgB,YAAY,EAAE;CAC/D,UAAU,EAAE,QAAQ,EAAE,gBAAgB,YAAY,EAAE;CACpD,OAAO,EAAE,QAAQ,EAAE,QAAQ,YAAY,EAAE;CACzC,aAAa,EAAE,QAAQ,EAAE,QAAQ,YAAY,EAAE;CAC/C,WAAW,EAAE,QAAQ,EAAE,gBAAgB,YAAY,EAAE;AACvD;;;;;;AASA,SAAgB,iBAAsC;CACpD,OAAO;EACL;EACA;CACF;AACF;;;;;;;AAQA,SAAgB,aAA4B;CAC1C,OAAO,IAAI,cAAc,eAAe,CAAC;AAC3C"}

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

@@ -1,6 +1,7 @@
 "use client";
 import { defineActions } from "../../core/dist/actions/registry.js";
 import "../../core/dist/index.js";
+import { loggableErrorName } from "../../utils/loggable-error-name.js";
 import { CART_COUPON_APPLY, CART_COUPON_REMOVE, CART_ITEMS_REMOVE, CART_ITEM_ADD, CART_ITEM_QUANTITY_DECREASE, CART_ITEM_QUANTITY_INCREASE, CART_ITEM_REMOVE, CART_VALIDATE, CartFragment } from "./operations.js";
 import { cartCouponErrorsVar, cartLastAddVar, cartUserErrorsVar, orderFormIdVar } from "../state/cart.js";
 import { buildOptimisticDecrease, buildOptimisticIncrease, buildOptimisticRemove, buildOptimisticRemoveItems } from "./optimistic.js";
@@ -134,7 +135,7 @@ function useCartActions() {
 			if (errors.length === 0) cartLastAddVar(cartLastAddVar() + 1);
 			return publishWrite(errors);
 		} catch (error) {
-			console.error("[cart.addItem] cartItemAdd failed", error);
+			console.error("[cart.addItem] cartItemAdd failed", loggableErrorName(error));
 			return publish([NETWORK_USER_ERROR]);
 		}
 	}, [addMutation]);
@@ -148,7 +149,7 @@ function useCartActions() {
 				optimisticResponse: buildOptimisticRemove(found.cart, found.line)
 			}))).data?.cartItemRemove?.userErrors ?? []);
 		} catch (error) {
-			console.error("[cart.removeItem] cartItemRemove failed", error);
+			console.error("[cart.removeItem] cartItemRemove failed", loggableErrorName(error));
 			return publish([NETWORK_USER_ERROR]);
 		}
 	}, [requireLine, removeMutation]);
@@ -165,7 +166,7 @@ function useCartActions() {
 				optimisticResponse: buildOptimisticRemoveItems(cart, lines)
 			}))).data?.cartItemsRemove?.userErrors ?? []);
 		} catch (error) {
-			console.error("[cart.removeItems] cartItemsRemove failed", error);
+			console.error("[cart.removeItems] cartItemsRemove failed", loggableErrorName(error));
 			return publish([NETWORK_USER_ERROR]);
 		}
 	}, [readCart, removeItemsMutation]);
@@ -183,7 +184,7 @@ function useCartActions() {
 				optimisticResponse: buildOptimisticIncrease(found.cart, found.line, by)
 			}))).data?.cartItemQuantityIncrease?.userErrors ?? []);
 		} catch (error) {
-			console.error("[cart.increaseQuantity] cartItemQuantityIncrease failed", error);
+			console.error("[cart.increaseQuantity] cartItemQuantityIncrease failed", loggableErrorName(error));
 			return publish([NETWORK_USER_ERROR]);
 		}
 	}, [requireLine, increaseMutation]);
@@ -201,7 +202,7 @@ function useCartActions() {
 				optimisticResponse: buildOptimisticDecrease(found.cart, found.line, by)
 			}))).data?.cartItemQuantityDecrease?.userErrors ?? []);
 		} catch (error) {
-			console.error("[cart.decreaseQuantity] cartItemQuantityDecrease failed", error);
+			console.error("[cart.decreaseQuantity] cartItemQuantityDecrease failed", loggableErrorName(error));
 			return publish([NETWORK_USER_ERROR]);
 		}
 	}, [requireLine, decreaseMutation]);
@@ -212,7 +213,7 @@ function useCartActions() {
 			hydrateCartId(result.data?.cartCouponApply?.cart?.id ?? null);
 			return publishCouponWrite(result.data?.cartCouponApply?.userErrors ?? []);
 		} catch (error) {
-			console.error("[cart.applyCoupon] cartCouponApply failed", error);
+			console.error("[cart.applyCoupon] cartCouponApply failed", loggableErrorName(error));
 			return publishCoupon([NETWORK_USER_ERROR]);
 		}
 	}, [applyCouponMutation]);
@@ -223,7 +224,7 @@ function useCartActions() {
 			hydrateCartId(result.data?.cartCouponRemove?.cart?.id ?? null);
 			return publishCouponWrite(result.data?.cartCouponRemove?.userErrors ?? []);
 		} catch (error) {
-			console.error("[cart.removeCoupon] cartCouponRemove failed", error);
+			console.error("[cart.removeCoupon] cartCouponRemove failed", loggableErrorName(error));
 			return publishCoupon([NETWORK_USER_ERROR]);
 		}
 	}, [removeCouponMutation]);
@@ -235,7 +236,7 @@ function useCartActions() {
 			if (errors.length === 0) markAvailabilityFresh();
 			return errors;
 		} catch (error) {
-			console.error("[cart.validate] cartValidate failed", error);
+			console.error("[cart.validate] cartValidate failed", loggableErrorName(error));
 			return [NETWORK_USER_ERROR];
 		}
 	}, [validateMutation]);