@vtex/faststore 0.0.10 → 0.0.11

package/dist/sdk/i18n/format-error-code.js

@@ -0,0 +1,23 @@
+import { logMessageEvent } from "./message-formatter.js";
+import { ownValue } from "../../utils/own-value.js";
+//#region src/sdk/i18n/format-error-code.ts
+/**
+* Words an upstream error from the component's own `$content`: the message field `fields` names for its
+* `code`, or `fallbackField` for a code the map does not know (a newer server, or a code minted outside
+* the map). The error's own `message` is an English diagnostic, so it is never shown; an unknown code
+* logs `message.unknown-code` with the content type's id instead.
+*/
+function formatErrorCode(contentType, fields, error, format, fallbackField) {
+	const field = error.code == null ? void 0 : ownValue(fields, error.code);
+	if (field !== void 0) return format(field);
+	logMessageEvent("message.unknown-code", {
+		contentTypeId: contentType.id,
+		code: error.code ?? null,
+		field: fallbackField
+	});
+	return format(fallbackField);
+}
+//#endregion
+export { formatErrorCode };
+
+//# sourceMappingURL=format-error-code.js.map

package/dist/sdk/i18n/format-error-code.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"format-error-code.js","names":[],"sources":["../../../src/sdk/i18n/format-error-code.ts"],"sourcesContent":["import type { ContentTypeDefinition } from '@vtex/fs-core';\nimport { ownValue } from '../../utils/own-value.js';\nimport { logMessageEvent } from './message-formatter.js';\n\n/**\n * Words an upstream error from the component's own `$content`: the message field `fields` names for its\n * `code`, or `fallbackField` for a code the map does not know (a newer server, or a code minted outside\n * the map). The error's own `message` is an English diagnostic, so it is never shown; an unknown code\n * logs `message.unknown-code` with the content type's id instead.\n */\nexport function formatErrorCode<F extends string>(\n  contentType: Pick<ContentTypeDefinition, 'id'>,\n  fields: Readonly<Record<string, F>>,\n  error: { code?: string | null },\n  format: (field: F) => string,\n  fallbackField: NoInfer<F>,\n): string {\n  const field = error.code == null ? undefined : ownValue(fields, error.code);\n  if (field !== undefined) return format(field);\n  logMessageEvent('message.unknown-code', {\n    contentTypeId: contentType.id,\n    code: error.code ?? null,\n    field: fallbackField,\n  });\n  return format(fallbackField);\n}\n"],"mappings":";;;;;;;;;AAUA,SAAgB,gBACd,aACA,QACA,OACA,QACA,eACQ;CACR,MAAM,QAAQ,MAAM,QAAQ,OAAO,KAAA,IAAY,SAAS,QAAQ,MAAM,IAAI;CAC1E,IAAI,UAAU,KAAA,GAAW,OAAO,OAAO,KAAK;CAC5C,gBAAgB,wBAAwB;EACtC,eAAe,YAAY;EAC3B,MAAM,MAAM,QAAQ;EACpB,OAAO;CACT,CAAC;CACD,OAAO,OAAO,aAAa;AAC7B"}

package/dist/sdk/i18n/message-formatter.d.ts

@@ -0,0 +1,22 @@
+import { ContentTypeDefinition, ContentValue, MessageArguments, MessageFieldName, MessageTagName } from "../../core/dist/define-content-type.js";
+import "../../core/dist/index.js";
+import { ReactNode } from "react";
+//#region src/sdk/i18n/message-formatter.d.ts
+type MessageProperty<T extends ContentTypeDefinition, K> = K extends keyof T['schema']['properties'] ? T['schema']['properties'][K] : never;
+/** Optional when the message declares no arguments, required otherwise. */
+type ArgumentsParameter<P> = MessageArguments<P> extends Record<string, never> ? [args?: MessageArguments<P>] : [args: MessageArguments<P>];
+/** Formats the message fields of one component's `$content`, typed by their message contract. */
+export type MessageFormatter<T extends ContentTypeDefinition> = {
+  format<K extends MessageFieldName<T>>(field: K, ...args: ArgumentsParameter<MessageProperty<T, K>>): string;
+  rich<K extends MessageFieldName<T>>(field: K, args: MessageArguments<MessageProperty<T, K>>, tags: Record<MessageTagName<MessageProperty<T, K>>, (chunks: ReactNode[]) => ReactNode>): ReactNode;
+};
+/**
+ * The message formatter for a content type and its `$content`, in `locale`. Pure and side-neutral, so a
+ * Server Component formats without React context. Both methods are total: a missing message renders
+ * `''` and an invalid one renders the authored string, each logging an error (an optional message,
+ * `messageOptional`, renders `''` unwritten without logging). Without a locale (a
+ * Server Component rendered with no compiler-injected `$locale`) every message is invalid.
+ */
+export declare function createMessageFormatter<T extends ContentTypeDefinition>(locale: string | undefined, contentType: T, content: ContentValue<T> | undefined): MessageFormatter<T>;
+//#endregion
+//# sourceMappingURL=message-formatter.d.ts.map

package/dist/sdk/i18n/message-formatter.js

@@ -0,0 +1,140 @@
+import { Children, Fragment, createElement } from "react";
+import { TYPE, createNumberElement } from "@formatjs/icu-messageformat-parser";
+import { FormatError, IntlMessageFormat } from "intl-messageformat";
+//#region src/sdk/i18n/message-formatter.ts
+/**
+* The message formatter for a content type and its `$content`, in `locale`. Pure and side-neutral, so a
+* Server Component formats without React context. Both methods are total: a missing message renders
+* `''` and an invalid one renders the authored string, each logging an error (an optional message,
+* `messageOptional`, renders `''` unwritten without logging). Without a locale (a
+* Server Component rendered with no compiler-injected `$locale`) every message is invalid.
+*/
+function createMessageFormatter(locale, contentType, content) {
+	function resolve(field, values) {
+		const message = content?.[field];
+		const fields = {
+			contentTypeId: contentType.id,
+			field,
+			locale
+		};
+		if (typeof message !== "string" || message.trim() === "") {
+			if (!isOptionalMessage(contentType, field)) logMessageEvent("message.missing", {
+				...fields,
+				reason: typeof message === "string" ? "blank" : "absent"
+			});
+			return "";
+		}
+		if (!locale) {
+			logMessageEvent("message.invalid", {
+				...fields,
+				reason: "missing-locale"
+			});
+			return message;
+		}
+		try {
+			return formatIcu(locale, message, values);
+		} catch (error) {
+			logMessageEvent("message.invalid", {
+				...fields,
+				reason: invalidReason(error)
+			});
+			return message;
+		}
+	}
+	return {
+		format(field, ...[args]) {
+			return joinText(resolve(field, withoutPrototype(args)));
+		},
+		rich(field, args, tags) {
+			const values = withoutPrototype(args);
+			for (const [name, tag] of Object.entries(tags)) values[name] = (chunks) => tag(Children.toArray(chunks));
+			const result = resolve(field, values);
+			if (typeof result === "string") return result;
+			return createElement(Fragment, null, ...Array.isArray(result) ? result : [result]);
+		}
+	};
+}
+/**
+* `intl-messageformat` renders a plain argument as `String(value)`, and a name can be both a plural
+* selector and a plain argument in one message. So a plain argument holding a number is rewritten to
+* a `number` element, which formats with `Intl.NumberFormat` in `locale`, and selectors stay raw.
+*/
+function formatIcu(locale, message, values) {
+	return compiledMessage(locale, message, Object.keys(values).filter((name) => typeof values[name] === "number")).format(values);
+}
+/**
+* Parsing dominates a format call, and the same authored message renders on every row and every
+* render, so the compiled message is kept per locale and set of number arguments. Authored
+* copy is finite; the cap only guards against unbounded templates.
+*/
+const COMPILED_MESSAGES = /* @__PURE__ */ new Map();
+const COMPILED_MESSAGES_LIMIT = 1e3;
+function compiledMessage(locale, message, numberArguments) {
+	const key = [
+		locale,
+		numberArguments.join(","),
+		message
+	].join("\0");
+	const cached = COMPILED_MESSAGES.get(key);
+	if (cached) return cached;
+	const parsed = new IntlMessageFormat(message, locale);
+	const compiled = numberArguments.length === 0 ? parsed : new IntlMessageFormat(localizeNumberArguments(parsed.getAst(), new Set(numberArguments)), locale);
+	if (COMPILED_MESSAGES.size >= COMPILED_MESSAGES_LIMIT) COMPILED_MESSAGES.clear();
+	COMPILED_MESSAGES.set(key, compiled);
+	return compiled;
+}
+/**
+* The argument values in an object with no prototype, so a message argument named after an
+* `Object.prototype` member (`{toString}`, `{constructor}`) is a missing value, not an inherited one.
+*/
+function withoutPrototype(values) {
+	return Object.assign(Object.create(null), values);
+}
+/** Whether the content type declares `field` a message a store may leave unwritten. */
+function isOptionalMessage(contentType, field) {
+	return contentType.schema.properties[field]?.messageOptional === true;
+}
+/** Without tag functions every part is a string, and `intl-messageformat` joins them into one. */
+function joinText(result) {
+	return Array.isArray(result) ? result.join("") : result;
+}
+function localizeNumberArguments(elements, numberArguments) {
+	return elements.map((element) => {
+		switch (element.type) {
+			case TYPE.argument: return numberArguments.has(element.value) ? createNumberElement(element.value) : element;
+			case TYPE.plural:
+			case TYPE.select: return {
+				...element,
+				options: Object.fromEntries(Object.entries(element.options).map(([key, option]) => [key, {
+					...option,
+					value: localizeNumberArguments(option.value, numberArguments)
+				}]))
+			};
+			case TYPE.tag: return {
+				...element,
+				children: localizeNumberArguments(element.children, numberArguments)
+			};
+			default: return element;
+		}
+	});
+}
+/**
+* A code or kind name, never an error message: `InvalidValueError`'s message embeds the argument
+* value, which can carry shopper data.
+*/
+function invalidReason(error) {
+	if (error instanceof FormatError) return error.code;
+	if (error instanceof SyntaxError) return error.message;
+	return error instanceof Error ? error.name : "unknown";
+}
+/** One log line in every environment. Never the message text or an argument value. */
+function logMessageEvent(event, fields) {
+	console.error("[message]", {
+		...fields,
+		event
+	});
+}
+//#endregion
+export { createMessageFormatter, logMessageEvent };
+
+//# sourceMappingURL=message-formatter.js.map

package/dist/sdk/i18n/message-formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-formatter.js","names":[],"sources":["../../../src/sdk/i18n/message-formatter.ts"],"sourcesContent":["import { createNumberElement, type MessageFormatElement, TYPE } from '@formatjs/icu-messageformat-parser';\nimport type {\n  ContentTypeDefinition,\n  ContentValue,\n  MessageArguments,\n  MessageFieldName,\n  MessageTagName,\n} from '@vtex/fs-core';\nimport { FormatError, type FormatXMLElementFn, IntlMessageFormat, type PrimitiveType } from 'intl-messageformat';\nimport { Children, createElement, Fragment, type ReactNode } from 'react';\n\ntype MessageProperty<T extends ContentTypeDefinition, K> = K extends keyof T['schema']['properties']\n  ? T['schema']['properties'][K]\n  : never;\n\n/** Optional when the message declares no arguments, required otherwise. */\ntype ArgumentsParameter<P> =\n  MessageArguments<P> extends Record<string, never> ? [args?: MessageArguments<P>] : [args: MessageArguments<P>];\n\n/** `R` is what a tag renders: `ReactNode` for rich messages, `string` when there are no tags. */\ntype MessageValues<R = ReactNode> = Record<string, PrimitiveType | R | FormatXMLElementFn<R>>;\n\ntype FormatResult<R> = string | R | (string | R)[];\n\ntype MessageEvent = 'message.missing' | 'message.invalid' | 'message.unknown-code';\n\n/** Formats the message fields of one component's `$content`, typed by their message contract. */\nexport type MessageFormatter<T extends ContentTypeDefinition> = {\n  format<K extends MessageFieldName<T>>(field: K, ...args: ArgumentsParameter<MessageProperty<T, K>>): string;\n  rich<K extends MessageFieldName<T>>(\n    field: K,\n    args: MessageArguments<MessageProperty<T, K>>,\n    tags: Record<MessageTagName<MessageProperty<T, K>>, (chunks: ReactNode[]) => ReactNode>,\n  ): ReactNode;\n};\n\n/**\n * The message formatter for a content type and its `$content`, in `locale`. Pure and side-neutral, so a\n * Server Component formats without React context. Both methods are total: a missing message renders\n * `''` and an invalid one renders the authored string, each logging an error (an optional message,\n * `messageOptional`, renders `''` unwritten without logging). Without a locale (a\n * Server Component rendered with no compiler-injected `$locale`) every message is invalid.\n */\nexport function createMessageFormatter<T extends ContentTypeDefinition>(\n  locale: string | undefined,\n  contentType: T,\n  content: ContentValue<T> | undefined,\n): MessageFormatter<T> {\n  function resolve<R>(field: string, values: MessageValues<R>): FormatResult<R> {\n    const message = (content as Record<string, unknown> | undefined)?.[field];\n    const fields = { contentTypeId: contentType.id, field, locale };\n    if (typeof message !== 'string' || message.trim() === '') {\n      if (!isOptionalMessage(contentType, field)) {\n        logMessageEvent('message.missing', { ...fields, reason: typeof message === 'string' ? 'blank' : 'absent' });\n      }\n      return '';\n    }\n    if (!locale) {\n      logMessageEvent('message.invalid', { ...fields, reason: 'missing-locale' });\n      return message;\n    }\n    try {\n      return formatIcu(locale, message, values);\n    } catch (error) {\n      logMessageEvent('message.invalid', { ...fields, reason: invalidReason(error) });\n      return message;\n    }\n  }\n\n  return {\n    format(field, ...[args]) {\n      return joinText(resolve<string>(field, withoutPrototype(args)));\n    },\n    rich(field, args, tags) {\n      const values: MessageValues = withoutPrototype(args);\n      for (const [name, tag] of Object.entries<(chunks: ReactNode[]) => ReactNode>(tags)) {\n        values[name] = (chunks: ReactNode[]) => tag(Children.toArray(chunks));\n      }\n      const result = resolve<ReactNode>(field, values);\n      if (typeof result === 'string') {\n        return result;\n      }\n      // Positional children, so React asks for no keys.\n      return createElement(Fragment, null, ...(Array.isArray(result) ? result : [result]));\n    },\n  };\n}\n\n/**\n * `intl-messageformat` renders a plain argument as `String(value)`, and a name can be both a plural\n * selector and a plain argument in one message. So a plain argument holding a number is rewritten to\n * a `number` element, which formats with `Intl.NumberFormat` in `locale`, and selectors stay raw.\n */\nfunction formatIcu<R>(locale: string, message: string, values: MessageValues<R>): FormatResult<R> {\n  const numberArguments = Object.keys(values).filter((name) => typeof values[name] === 'number');\n  return compiledMessage(locale, message, numberArguments).format<R>(values);\n}\n\n/**\n * Parsing dominates a format call, and the same authored message renders on every row and every\n * render, so the compiled message is kept per locale and set of number arguments. Authored\n * copy is finite; the cap only guards against unbounded templates.\n */\nconst COMPILED_MESSAGES = new Map<string, IntlMessageFormat>();\nconst COMPILED_MESSAGES_LIMIT = 1000;\n\nfunction compiledMessage(locale: string, message: string, numberArguments: readonly string[]): IntlMessageFormat {\n  const key = [locale, numberArguments.join(','), message].join('\\u0000');\n  const cached = COMPILED_MESSAGES.get(key);\n  if (cached) return cached;\n  const parsed = new IntlMessageFormat(message, locale);\n  const compiled =\n    numberArguments.length === 0\n      ? parsed\n      : new IntlMessageFormat(localizeNumberArguments(parsed.getAst(), new Set(numberArguments)), locale);\n  if (COMPILED_MESSAGES.size >= COMPILED_MESSAGES_LIMIT) COMPILED_MESSAGES.clear();\n  COMPILED_MESSAGES.set(key, compiled);\n  return compiled;\n}\n\n/**\n * The argument values in an object with no prototype, so a message argument named after an\n * `Object.prototype` member (`{toString}`, `{constructor}`) is a missing value, not an inherited one.\n */\nfunction withoutPrototype<V>(values: Readonly<Record<string, V>> | undefined): Record<string, V> {\n  return Object.assign(Object.create(null), values);\n}\n\n/** Whether the content type declares `field` a message a store may leave unwritten. */\nfunction isOptionalMessage(contentType: ContentTypeDefinition, field: string): boolean {\n  const property = (contentType.schema.properties as Record<string, { messageOptional?: boolean } | undefined>)[field];\n  return property?.messageOptional === true;\n}\n\n/** Without tag functions every part is a string, and `intl-messageformat` joins them into one. */\nfunction joinText(result: FormatResult<string>): string {\n  return Array.isArray(result) ? result.join('') : result;\n}\n\nfunction localizeNumberArguments(\n  elements: MessageFormatElement[],\n  numberArguments: ReadonlySet<string>,\n): MessageFormatElement[] {\n  return elements.map((element) => {\n    switch (element.type) {\n      case TYPE.argument:\n        return numberArguments.has(element.value) ? createNumberElement(element.value) : element;\n      case TYPE.plural:\n      case TYPE.select:\n        return {\n          ...element,\n          options: Object.fromEntries(\n            Object.entries(element.options).map(([key, option]) => [\n              key,\n              { ...option, value: localizeNumberArguments(option.value, numberArguments) },\n            ]),\n          ),\n        };\n      case TYPE.tag:\n        return { ...element, children: localizeNumberArguments(element.children, numberArguments) };\n      default:\n        return element;\n    }\n  });\n}\n\n/**\n * A code or kind name, never an error message: `InvalidValueError`'s message embeds the argument\n * value, which can carry shopper data.\n */\nfunction invalidReason(error: unknown): string {\n  if (error instanceof FormatError) return error.code;\n  // The parser throws a `SyntaxError` whose message is its `ErrorKind` name.\n  if (error instanceof SyntaxError) return error.message;\n  return error instanceof Error ? error.name : 'unknown';\n}\n\n/** One log line in every environment. Never the message text or an argument value. */\nexport function logMessageEvent(event: MessageEvent, fields: Record<string, unknown>): void {\n  // `event` spreads last so a `fields` key of the same name cannot displace the discriminator.\n  console.error('[message]', { ...fields, event });\n}\n"],"mappings":"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"}

package/dist/sdk/i18n/use-message-formatter.d.ts

@@ -0,0 +1,8 @@
+import { ContentTypeDefinition, ContentValue } from "../../core/dist/define-content-type.js";
+import "../../core/dist/index.js";
+import { MessageFormatter } from "./message-formatter.js";
+//#region src/sdk/i18n/use-message-formatter.d.ts
+/** The message formatter for a Client Component, in the locale `StorefrontProvider` published. */
+export declare function useMessageFormatter<T extends ContentTypeDefinition>(contentType: T, content: ContentValue<T> | undefined): MessageFormatter<T>;
+//#endregion
+//# sourceMappingURL=use-message-formatter.d.ts.map

package/dist/sdk/i18n/use-message-formatter.js

@@ -0,0 +1,18 @@
+"use client";
+import { useStorefrontContext } from "../context/storefront-context.js";
+import { createMessageFormatter } from "./message-formatter.js";
+import { useMemo } from "react";
+//#region src/sdk/i18n/use-message-formatter.ts
+/** The message formatter for a Client Component, in the locale `StorefrontProvider` published. */
+function useMessageFormatter(contentType, content) {
+	const { locale } = useStorefrontContext();
+	return useMemo(() => createMessageFormatter(locale, contentType, content), [
+		locale,
+		contentType,
+		content
+	]);
+}
+//#endregion
+export { useMessageFormatter };
+
+//# sourceMappingURL=use-message-formatter.js.map

package/dist/sdk/i18n/use-message-formatter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-message-formatter.js","names":[],"sources":["../../../src/sdk/i18n/use-message-formatter.ts"],"sourcesContent":["'use client';\n\nimport type { ContentTypeDefinition, ContentValue } from '@vtex/fs-core';\nimport { useMemo } from 'react';\nimport { useStorefrontContext } from '../context/storefront-context.js';\nimport { createMessageFormatter, type MessageFormatter } from './message-formatter.js';\n\n/** The message formatter for a Client Component, in the locale `StorefrontProvider` published. */\nexport function useMessageFormatter<T extends ContentTypeDefinition>(\n  contentType: T,\n  content: ContentValue<T> | undefined,\n): MessageFormatter<T> {\n  const { locale } = useStorefrontContext();\n  return useMemo(() => createMessageFormatter(locale, contentType, content), [locale, contentType, content]);\n}\n"],"mappings":";;;;;;AAQA,SAAgB,oBACd,aACA,SACqB;CACrB,MAAM,EAAE,WAAW,qBAAqB;CACxC,OAAO,cAAc,uBAAuB,QAAQ,aAAa,OAAO,GAAG;EAAC;EAAQ;EAAa;CAAO,CAAC;AAC3G"}

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

@@ -1 +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 { loggableErrorName } from '../../utils/loggable-error-name.js';\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 * docs/storefront-core/reference-free-particle-model.md § Write side — actions,\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 write answers an anonymous or expired session with a top-level `UNAUTHORIZED`, never\n * a `userError` (the read answers an anonymous one with a null profile instead). Collapsing it into\n * `NETWORK_ERROR` would offer a retry that cannot succeed, so it gets its own code and the caller can\n * 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('[identity.clientProfileUpdate] clientProfileUpdate failed', loggableErrorName(error));\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('[identity.clientPreferencesUpdate] clientPreferencesUpdate failed', loggableErrorName(error));\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('[identity.customerProfileUpdate] customerProfileUpdate failed', loggableErrorName(error));\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":"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"}
+{"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 { loggableErrorName } from '../../utils/loggable-error-name.js';\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 * docs/storefront-core/reference-free-particle-model.md § Write side — actions,\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\n// A diagnostic message: components word this code from their own `$content`.\nconst NETWORK_PROFILE_ERROR: ClientProfileUserError = {\n  code: 'NETWORK_ERROR',\n  message: 'Unable to save your details. Please try again.',\n};\n\n// A diagnostic message: components word this code from their own `$content`.\nconst NETWORK_PREFERENCE_ERROR: ClientProfileUserError = {\n  code: 'NETWORK_ERROR',\n  message: 'Unable to save your preference. Please try again.',\n};\n\n// A diagnostic message: components word this code from their own `$content`.\nconst NETWORK_CUSTOMER_PROFILE_ERROR: CustomerProfileUserError = {\n  code: 'NETWORK_ERROR',\n  message: 'Unable to save your profile. Please try again.',\n};\n\n// A diagnostic message: components word this code from their own `$content`.\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 write answers an anonymous or expired session with a top-level `UNAUTHORIZED`, never\n * a `userError` (the read answers an anonymous one with a null profile instead). Collapsing it into\n * `NETWORK_ERROR` would offer a retry that cannot succeed, so it gets its own code and the caller can\n * 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('[identity.clientProfileUpdate] clientProfileUpdate failed', loggableErrorName(error));\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('[identity.clientPreferencesUpdate] clientPreferencesUpdate failed', loggableErrorName(error));\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('[identity.customerProfileUpdate] customerProfileUpdate failed', loggableErrorName(error));\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":"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"}

package/dist/sdk/navigation/redirect.d.ts

@@ -7,5 +7,7 @@ type BindingContext = Pick<StorefrontContext, 'bindingId' | 'basePath'>;
 export declare function redirectToStorefrontPage(context: BindingContext, routeMap: RouteMap, target: PageRef | string): never;
 /** Next's `permanentRedirect` to a page reference or a logical path, resolved for the binding. */
 export declare function permanentRedirectToStorefrontPage(context: BindingContext, routeMap: RouteMap, target: PageRef | string): never;
+/** Next's `redirect` to `resolveSignInHref`: the session gate's answer to an anonymous request. */
+export declare function redirectToSignIn(context: BindingContext, routeMap: RouteMap, returnPath: string): never;
 //#endregion
 //# sourceMappingURL=redirect.d.ts.map

package/dist/sdk/navigation/redirect.js

@@ -1,5 +1,7 @@
+import { RETURN_URL_PARAM, resolveSiteRelativeHref, signInTarget } from "../../utils/safe-href.js";
 import { resolveStorefrontHref } from "./resolve-storefront-href.js";
 import { reportUnresolved } from "./report.js";
+import { MOCK_SESSION_ROUTE, mockSessionToken } from "../session/mock-session.js";
 import { permanentRedirect, redirect } from "next/navigation";
 //#region src/sdk/navigation/redirect.ts
 function resolveOrThrow(context, routeMap, target) {
@@ -16,7 +18,23 @@ function redirectToStorefrontPage(context, routeMap, target) {
 function permanentRedirectToStorefrontPage(context, routeMap, target) {
 	return permanentRedirect(resolveOrThrow(context, routeMap, target));
 }
+/**
+* Where the session gate sends an anonymous request: the binding's sign-in page carrying `returnPath`, a
+* logical path. With `FS_MOCK_SESSION` set it is the mock session handler instead, which lives outside
+* every binding, so the return it carries is already the public path.
+*/
+function resolveSignInHref(context, routeMap, returnPath) {
+	if (mockSessionToken() === null) return resolveOrThrow(context, routeMap, signInTarget(returnPath));
+	const back = resolveStorefrontHref(context, routeMap, returnPath).href;
+	const destination = back === null ? null : resolveSiteRelativeHref(back);
+	if (!destination?.safe) return MOCK_SESSION_ROUTE;
+	return `${MOCK_SESSION_ROUTE}?${new URLSearchParams({ [RETURN_URL_PARAM]: destination.href })}`;
+}
+/** Next's `redirect` to `resolveSignInHref`: the session gate's answer to an anonymous request. */
+function redirectToSignIn(context, routeMap, returnPath) {
+	return redirect(resolveSignInHref(context, routeMap, returnPath));
+}
 //#endregion
-export { permanentRedirectToStorefrontPage, redirectToStorefrontPage };
+export { permanentRedirectToStorefrontPage, redirectToSignIn, redirectToStorefrontPage, resolveSignInHref };
 
 //# sourceMappingURL=redirect.js.map

package/dist/sdk/navigation/redirect.js.map

@@ -1 +1 @@
-{"version":3,"file":"redirect.js","names":[],"sources":["../../../src/sdk/navigation/redirect.ts"],"sourcesContent":["import type { StorefrontContext } from '@vtex/fs-core';\nimport { permanentRedirect, redirect } from 'next/navigation';\nimport { reportUnresolved } from './report.js';\nimport { resolveStorefrontHref } from './resolve-storefront-href.js';\nimport type { PageRef, RouteMap } from './types.js';\n\ntype BindingContext = Pick<StorefrontContext, 'bindingId' | 'basePath'>;\n\nfunction resolveOrThrow(context: BindingContext, routeMap: RouteMap, target: PageRef | string): string {\n  const result = resolveStorefrontHref(context, routeMap, target);\n  if (result.href !== null) return result.href;\n  reportUnresolved(result.reason, target);\n  throw new Error(\n    `Cannot redirect: ${JSON.stringify(target)} resolved to no href (${result.reason}) on ` +\n      `binding ${JSON.stringify(context.bindingId)}.`,\n  );\n}\n\n/** Next's `redirect` to a page reference or a logical path, resolved for the binding. */\nexport function redirectToStorefrontPage(context: BindingContext, routeMap: RouteMap, target: PageRef | string): never {\n  return redirect(resolveOrThrow(context, routeMap, target));\n}\n\n/** Next's `permanentRedirect` to a page reference or a logical path, resolved for the binding. */\nexport function permanentRedirectToStorefrontPage(\n  context: BindingContext,\n  routeMap: RouteMap,\n  target: PageRef | string,\n): never {\n  return permanentRedirect(resolveOrThrow(context, routeMap, target));\n}\n"],"mappings":";;;;AAQA,SAAS,eAAe,SAAyB,UAAoB,QAAkC;CACrG,MAAM,SAAS,sBAAsB,SAAS,UAAU,MAAM;CAC9D,IAAI,OAAO,SAAS,MAAM,OAAO,OAAO;CACxC,iBAAiB,OAAO,QAAQ,MAAM;CACtC,MAAM,IAAI,MACR,oBAAoB,KAAK,UAAU,MAAM,EAAE,wBAAwB,OAAO,OAAO,eACpE,KAAK,UAAU,QAAQ,SAAS,EAAE,EACjD;AACF;;AAGA,SAAgB,yBAAyB,SAAyB,UAAoB,QAAiC;CACrH,OAAO,SAAS,eAAe,SAAS,UAAU,MAAM,CAAC;AAC3D;;AAGA,SAAgB,kCACd,SACA,UACA,QACO;CACP,OAAO,kBAAkB,eAAe,SAAS,UAAU,MAAM,CAAC;AACpE"}
+{"version":3,"file":"redirect.js","names":[],"sources":["../../../src/sdk/navigation/redirect.ts"],"sourcesContent":["import type { StorefrontContext } from '@vtex/fs-core';\nimport { permanentRedirect, redirect } from 'next/navigation';\nimport { RETURN_URL_PARAM, resolveSiteRelativeHref, signInTarget } from '../../utils/safe-href.js';\nimport { MOCK_SESSION_ROUTE, mockSessionToken } from '../session/mock-session.js';\nimport { reportUnresolved } from './report.js';\nimport { resolveStorefrontHref } from './resolve-storefront-href.js';\nimport type { PageRef, RouteMap } from './types.js';\n\ntype BindingContext = Pick<StorefrontContext, 'bindingId' | 'basePath'>;\n\nfunction resolveOrThrow(context: BindingContext, routeMap: RouteMap, target: PageRef | string): string {\n  const result = resolveStorefrontHref(context, routeMap, target);\n  if (result.href !== null) return result.href;\n  reportUnresolved(result.reason, target);\n  throw new Error(\n    `Cannot redirect: ${JSON.stringify(target)} resolved to no href (${result.reason}) on ` +\n      `binding ${JSON.stringify(context.bindingId)}.`,\n  );\n}\n\n/** Next's `redirect` to a page reference or a logical path, resolved for the binding. */\nexport function redirectToStorefrontPage(context: BindingContext, routeMap: RouteMap, target: PageRef | string): never {\n  return redirect(resolveOrThrow(context, routeMap, target));\n}\n\n/** Next's `permanentRedirect` to a page reference or a logical path, resolved for the binding. */\nexport function permanentRedirectToStorefrontPage(\n  context: BindingContext,\n  routeMap: RouteMap,\n  target: PageRef | string,\n): never {\n  return permanentRedirect(resolveOrThrow(context, routeMap, target));\n}\n\n/**\n * Where the session gate sends an anonymous request: the binding's sign-in page carrying `returnPath`, a\n * logical path. With `FS_MOCK_SESSION` set it is the mock session handler instead, which lives outside\n * every binding, so the return it carries is already the public path.\n */\nexport function resolveSignInHref(context: BindingContext, routeMap: RouteMap, returnPath: string): string {\n  if (mockSessionToken() === null) {\n    return resolveOrThrow(context, routeMap, signInTarget(returnPath));\n  }\n  const back = resolveStorefrontHref(context, routeMap, returnPath).href;\n  const destination = back === null ? null : resolveSiteRelativeHref(back);\n  if (!destination?.safe) return MOCK_SESSION_ROUTE;\n  return `${MOCK_SESSION_ROUTE}?${new URLSearchParams({ [RETURN_URL_PARAM]: destination.href })}`;\n}\n\n/** Next's `redirect` to `resolveSignInHref`: the session gate's answer to an anonymous request. */\nexport function redirectToSignIn(context: BindingContext, routeMap: RouteMap, returnPath: string): never {\n  return redirect(resolveSignInHref(context, routeMap, returnPath));\n}\n"],"mappings":";;;;;;AAUA,SAAS,eAAe,SAAyB,UAAoB,QAAkC;CACrG,MAAM,SAAS,sBAAsB,SAAS,UAAU,MAAM;CAC9D,IAAI,OAAO,SAAS,MAAM,OAAO,OAAO;CACxC,iBAAiB,OAAO,QAAQ,MAAM;CACtC,MAAM,IAAI,MACR,oBAAoB,KAAK,UAAU,MAAM,EAAE,wBAAwB,OAAO,OAAO,eACpE,KAAK,UAAU,QAAQ,SAAS,EAAE,EACjD;AACF;;AAGA,SAAgB,yBAAyB,SAAyB,UAAoB,QAAiC;CACrH,OAAO,SAAS,eAAe,SAAS,UAAU,MAAM,CAAC;AAC3D;;AAGA,SAAgB,kCACd,SACA,UACA,QACO;CACP,OAAO,kBAAkB,eAAe,SAAS,UAAU,MAAM,CAAC;AACpE;;;;;;AAOA,SAAgB,kBAAkB,SAAyB,UAAoB,YAA4B;CACzG,IAAI,iBAAiB,MAAM,MACzB,OAAO,eAAe,SAAS,UAAU,aAAa,UAAU,CAAC;CAEnE,MAAM,OAAO,sBAAsB,SAAS,UAAU,UAAU,CAAC,CAAC;CAClE,MAAM,cAAc,SAAS,OAAO,OAAO,wBAAwB,IAAI;CACvE,IAAI,CAAC,aAAa,MAAM,OAAO;CAC/B,OAAO,GAAG,mBAAmB,GAAG,IAAI,gBAAgB,GAAG,mBAAmB,YAAY,KAAK,CAAC;AAC9F;;AAGA,SAAgB,iBAAiB,SAAyB,UAAoB,YAA2B;CACvG,OAAO,SAAS,kBAAkB,SAAS,UAAU,UAAU,CAAC;AAClE"}

package/dist/sdk/navigation/types.d.ts

@@ -26,6 +26,19 @@ export type RouteMapEntry = {
   params?: string[];
   aliases?: Record<string, string>;
   bindings?: string[];
+  /**
+   * Set on a Search Landing Page: the term a singleton pins, as authored, or the content type and route
+   * parameter of the page over CMS term entries, whose item slug is the normalized term.
+   */
+  searchTerm?: string | {
+    contentType: string;
+    param: string;
+  };
+  /**
+   * Set on an Entity Landing Page: the Relay node ID of the collection, category, or brand whose standard
+   * listing points its canonical here, the ID `catalogRoute` returns for that listing.
+   */
+  canonicalFor?: string;
 };
 /** Keyed by page name. */
 export type RouteMap = Record<string, RouteMapEntry>;

package/dist/sdk/payment/bin-format.js

@@ -0,0 +1,20 @@
+import { isAcceptedCardBin } from "@vtex/fs-domain-logic/checkout/rules";
+//#region src/sdk/payment/bin-format.ts
+/**
+* The browser-side use of the rule `paymentMethodSelect` applies to `bin`, so a malformed value never leaves
+* through `payment.setMethod`. The rule itself lives in `@vtex/fs-domain-logic/checkout/rules`, shared with the
+* server, so the two can no longer drift; the fixed refusal text lives there too. A new card (no `accountId`,
+* or an empty one) carries nothing or exactly eight digits; a saved card carries nothing or one to eight,
+* because the server compares it to the card's own stored BIN. `null` counts as nothing, like the server; any
+* other value that is not a string is refused. Reads the value and returns a boolean: it never stores, logs or
+* interpolates it.
+*/
+function isAcceptedBin({ bin, accountId }) {
+	if (bin === void 0 || bin === null || bin === "") return true;
+	if (typeof bin !== "string") return false;
+	return isAcceptedCardBin(bin, Boolean(accountId));
+}
+//#endregion
+export { isAcceptedBin };
+
+//# sourceMappingURL=bin-format.js.map

package/dist/sdk/payment/bin-format.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bin-format.js","names":[],"sources":["../../../src/sdk/payment/bin-format.ts"],"sourcesContent":["import { isAcceptedCardBin } from '@vtex/fs-domain-logic/checkout/rules';\n\n/**\n * The browser-side use of the rule `paymentMethodSelect` applies to `bin`, so a malformed value never leaves\n * through `payment.setMethod`. The rule itself lives in `@vtex/fs-domain-logic/checkout/rules`, shared with the\n * server, so the two can no longer drift; the fixed refusal text lives there too. A new card (no `accountId`,\n * or an empty one) carries nothing or exactly eight digits; a saved card carries nothing or one to eight,\n * because the server compares it to the card's own stored BIN. `null` counts as nothing, like the server; any\n * other value that is not a string is refused. Reads the value and returns a boolean: it never stores, logs or\n * interpolates it.\n */\nexport function isAcceptedBin({ bin, accountId }: Readonly<{ bin?: string | null; accountId?: string }>): boolean {\n  if (bin === undefined || bin === null || bin === '') return true;\n  if (typeof bin !== 'string') return false;\n  return isAcceptedCardBin(bin, Boolean(accountId));\n}\n"],"mappings":";;;;;;;;;;;AAWA,SAAgB,cAAc,EAAE,KAAK,aAA6E;CAChH,IAAI,QAAQ,KAAA,KAAa,QAAQ,QAAQ,QAAQ,IAAI,OAAO;CAC5D,IAAI,OAAO,QAAQ,UAAU,OAAO;CACpC,OAAO,kBAAkB,KAAK,QAAQ,SAAS,CAAC;AAClD"}

package/dist/sdk/payment/challenge-return.js

@@ -0,0 +1,37 @@
+//#region src/sdk/payment/challenge-return.ts
+/**
+* The contract between the two ends of the 3D Secure round trip (T208, Decision 2): `usePlaceOrder` builds
+* the return URL's query before the card is posted, and the `ChallengeReturn` page reads it back when the
+* bank sends the shopper home. Both ends live here so they cannot drift apart.
+*
+* The query is the order group and a literal flag, nothing else. The group is the only key the gateway
+* callback needs and it exists before the card is posted. The reader is strict because the page it feeds
+* issues a write: exactly one `orderGroup` that fits `ORDER_GROUP_PATTERN` (which excludes `.`, so a dot
+* segment cannot arrive) and `redirect` equal to the string `true`. Anything else the gateway or the bank
+* appends is ignored, and never returned.
+*/
+const ORDER_GROUP_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
+const GROUP_PARAM = "orderGroup";
+const FLAG_PARAM = "redirect";
+const FLAG_VALUE = "true";
+/** The query for a group's return URL, or `null` when the group is not one a return page would accept. */
+function buildChallengeReturnQuery(orderGroup) {
+	if (!ORDER_GROUP_PATTERN.test(orderGroup)) return null;
+	return {
+		[GROUP_PARAM]: orderGroup,
+		[FLAG_PARAM]: FLAG_VALUE
+	};
+}
+/** The order group a return URL's query names, or `null` for anything that is not exactly a return query. */
+function readChallengeReturn(search) {
+	const params = new URLSearchParams(search);
+	const groups = params.getAll(GROUP_PARAM);
+	const [orderGroup] = groups;
+	if (groups.length !== 1 || orderGroup === void 0 || !ORDER_GROUP_PATTERN.test(orderGroup)) return null;
+	if (params.get(FLAG_PARAM) !== FLAG_VALUE) return null;
+	return { orderGroup };
+}
+//#endregion
+export { buildChallengeReturnQuery, readChallengeReturn };
+
+//# sourceMappingURL=challenge-return.js.map

package/dist/sdk/payment/challenge-return.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"challenge-return.js","names":[],"sources":["../../../src/sdk/payment/challenge-return.ts"],"sourcesContent":["/**\n * The contract between the two ends of the 3D Secure round trip (T208, Decision 2): `usePlaceOrder` builds\n * the return URL's query before the card is posted, and the `ChallengeReturn` page reads it back when the\n * bank sends the shopper home. Both ends live here so they cannot drift apart.\n *\n * The query is the order group and a literal flag, nothing else. The group is the only key the gateway\n * callback needs and it exists before the card is posted. The reader is strict because the page it feeds\n * issues a write: exactly one `orderGroup` that fits `ORDER_GROUP_PATTERN` (which excludes `.`, so a dot\n * segment cannot arrive) and `redirect` equal to the string `true`. Anything else the gateway or the bank\n * appends is ignored, and never returned.\n */\n\nconst ORDER_GROUP_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;\n\nconst GROUP_PARAM = 'orderGroup';\nconst FLAG_PARAM = 'redirect';\nconst FLAG_VALUE = 'true';\n\n/** The query for a group's return URL, or `null` when the group is not one a return page would accept. */\nexport function buildChallengeReturnQuery(orderGroup: string): Record<string, string> | null {\n  if (!ORDER_GROUP_PATTERN.test(orderGroup)) return null;\n  return { [GROUP_PARAM]: orderGroup, [FLAG_PARAM]: FLAG_VALUE };\n}\n\n/** The order group a return URL's query names, or `null` for anything that is not exactly a return query. */\nexport function readChallengeReturn(search: string): { orderGroup: string } | null {\n  const params = new URLSearchParams(search);\n  const groups = params.getAll(GROUP_PARAM);\n  const [orderGroup] = groups;\n  if (groups.length !== 1 || orderGroup === undefined || !ORDER_GROUP_PATTERN.test(orderGroup)) return null;\n  if (params.get(FLAG_PARAM) !== FLAG_VALUE) return null;\n  return { orderGroup };\n}\n"],"mappings":";;;;;;;;;;;;AAYA,MAAM,sBAAsB;AAE5B,MAAM,cAAc;AACpB,MAAM,aAAa;AACnB,MAAM,aAAa;;AAGnB,SAAgB,0BAA0B,YAAmD;CAC3F,IAAI,CAAC,oBAAoB,KAAK,UAAU,GAAG,OAAO;CAClD,OAAO;GAAG,cAAc;GAAa,aAAa;CAAW;AAC/D;;AAGA,SAAgB,oBAAoB,QAA+C;CACjF,MAAM,SAAS,IAAI,gBAAgB,MAAM;CACzC,MAAM,SAAS,OAAO,OAAO,WAAW;CACxC,MAAM,CAAC,cAAc;CACrB,IAAI,OAAO,WAAW,KAAK,eAAe,KAAA,KAAa,CAAC,oBAAoB,KAAK,UAAU,GAAG,OAAO;CACrG,IAAI,OAAO,IAAI,UAAU,MAAM,YAAY,OAAO;CAClD,OAAO,EAAE,WAAW;AACtB"}

package/dist/sdk/payment/confirmation-last-four.js

@@ -0,0 +1,39 @@
+import { useSyncExternalStore } from "react";
+//#region src/sdk/payment/confirmation-last-four.ts
+const FOUR_ASCII_DIGITS = /^\d{4}$/;
+const NOT_AN_ASCII_DIGIT = /\D/g;
+const SHORTEST_NUMBER_LENGTH = 8;
+let record = null;
+const listeners = /* @__PURE__ */ new Set();
+function notify() {
+	for (const listener of listeners) listener();
+}
+function subscribe(listener) {
+	listeners.add(listener);
+	return () => {
+		listeners.delete(listener);
+	};
+}
+/** The last four ASCII digits of `rawDigits` once every non-digit is removed; null below 8 digits. */
+function lastFourOf(rawDigits) {
+	const digits = rawDigits.replaceAll(NOT_AN_ASCII_DIGIT, "");
+	return digits.length >= SHORTEST_NUMBER_LENGTH ? digits.slice(-4) : null;
+}
+/** Stores one record. Refuses (no-op) unless `lastFour` is exactly four ASCII digits and `orderGroup` is non-empty. */
+function rememberConfirmationLastFour(orderGroup, lastFour) {
+	if (typeof orderGroup !== "string" || orderGroup === "") return;
+	if (typeof lastFour !== "string" || !FOUR_ASCII_DIGITS.test(lastFour)) return;
+	record = {
+		orderGroup,
+		lastFour
+	};
+	notify();
+}
+/** The four digits for this order group, or null. The server snapshot is always null. */
+function useConfirmationLastFour(orderGroup) {
+	return useSyncExternalStore(subscribe, () => record !== null && orderGroup != null && record.orderGroup === orderGroup ? record.lastFour : null, () => null);
+}
+//#endregion
+export { lastFourOf, rememberConfirmationLastFour, useConfirmationLastFour };
+
+//# sourceMappingURL=confirmation-last-four.js.map

package/dist/sdk/payment/confirmation-last-four.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"confirmation-last-four.js","names":[],"sources":["../../../src/sdk/payment/confirmation-last-four.ts"],"sourcesContent":["import { useSyncExternalStore } from 'react';\n\n/**\n * The masked last four of a newly typed payment instrument, carried in module memory from the place-order\n * step to the confirmation recap (T82, US-8). It holds one record: four ASCII digits and the order group\n * they belong to. It is never written to a storage API, a cookie, a URL, a header, a log, an analytics\n * event, a GraphQL variable or an error, and it is empty on the server and on first load.\n */\ntype ConfirmationLastFour = Readonly<{ orderGroup: string; lastFour: string }>;\n\nconst FOUR_ASCII_DIGITS = /^\\d{4}$/;\nconst NOT_AN_ASCII_DIGIT = /\\D/g;\nconst SHORTEST_NUMBER_LENGTH = 8;\n\nlet record: ConfirmationLastFour | null = null;\nconst listeners = new Set<() => void>();\n\nfunction notify(): void {\n  for (const listener of listeners) listener();\n}\n\nfunction subscribe(listener: () => void): () => void {\n  listeners.add(listener);\n  return () => {\n    listeners.delete(listener);\n  };\n}\n\n/** The last four ASCII digits of `rawDigits` once every non-digit is removed; null below 8 digits. */\nexport function lastFourOf(rawDigits: string): string | null {\n  const digits = rawDigits.replaceAll(NOT_AN_ASCII_DIGIT, '');\n  return digits.length >= SHORTEST_NUMBER_LENGTH ? digits.slice(-4) : null;\n}\n\n/** Stores one record. Refuses (no-op) unless `lastFour` is exactly four ASCII digits and `orderGroup` is non-empty. */\nexport function rememberConfirmationLastFour(orderGroup: string, lastFour: string): void {\n  if (typeof orderGroup !== 'string' || orderGroup === '') return;\n  if (typeof lastFour !== 'string' || !FOUR_ASCII_DIGITS.test(lastFour)) return;\n  record = { orderGroup, lastFour };\n  notify();\n}\n\n/** The current record, or null. */\nexport function readConfirmationLastFour(): ConfirmationLastFour | null {\n  return record;\n}\n\n/** The four digits for this order group, or null. The server snapshot is always null. */\nexport function useConfirmationLastFour(orderGroup: string | null | undefined): string | null {\n  return useSyncExternalStore(\n    subscribe,\n    () => (record !== null && orderGroup != null && record.orderGroup === orderGroup ? record.lastFour : null),\n    () => null,\n  );\n}\n\n/** Test seam: empties the record. */\nexport function clearConfirmationLastFour(): void {\n  record = null;\n  notify();\n}\n"],"mappings":";;AAUA,MAAM,oBAAoB;AAC1B,MAAM,qBAAqB;AAC3B,MAAM,yBAAyB;AAE/B,IAAI,SAAsC;AAC1C,MAAM,4BAAY,IAAI,IAAgB;AAEtC,SAAS,SAAe;CACtB,KAAK,MAAM,YAAY,WAAW,SAAS;AAC7C;AAEA,SAAS,UAAU,UAAkC;CACnD,UAAU,IAAI,QAAQ;CACtB,aAAa;EACX,UAAU,OAAO,QAAQ;CAC3B;AACF;;AAGA,SAAgB,WAAW,WAAkC;CAC3D,MAAM,SAAS,UAAU,WAAW,oBAAoB,EAAE;CAC1D,OAAO,OAAO,UAAU,yBAAyB,OAAO,MAAM,EAAE,IAAI;AACtE;;AAGA,SAAgB,6BAA6B,YAAoB,UAAwB;CACvF,IAAI,OAAO,eAAe,YAAY,eAAe,IAAI;CACzD,IAAI,OAAO,aAAa,YAAY,CAAC,kBAAkB,KAAK,QAAQ,GAAG;CACvE,SAAS;EAAE;EAAY;CAAS;CAChC,OAAO;AACT;;AAQA,SAAgB,wBAAwB,YAAsD;CAC5F,OAAO,qBACL,iBACO,WAAW,QAAQ,cAAc,QAAQ,OAAO,eAAe,aAAa,OAAO,WAAW,YAC/F,IACR;AACF"}

package/dist/sdk/payment/gateway.d.ts

@@ -38,7 +38,7 @@ export type PaymentGatewayTransaction = Readonly<{
   installmentsValueInCents: number;
   /** `PaymentInstallment.interestRate`; 0 for the interest-free 1x default. */
   interestRate: number;
-  /** Absolute return URL. Phase-2 redirect mode only; omitted in v1's direct mode. */
+  /** Absolute return URL for the 3D Secure challenge. Omitted when the store authored no return page. */
   callbackUrl?: string;
   /**
    * Billing differs from the delivery address. Defaults to `false`, because `setBillingAddress` persists

package/dist/sdk/payment/gateway.js

@@ -23,7 +23,10 @@ import { isTrustedGatewayOrigin } from "./gateway-origin.js";
 */
 /** Client-synthesized code for a failed gateway leg — distinct from the BFF's `NETWORK_ERROR`. */
 const PAYMENT_GATEWAY_ERROR_CODE = "GATEWAY_ERROR";
-/** The single userError a rejected request, a non-2xx response and a request the builder refused all resolve to. */
+/**
+* The single userError a rejected request, a non-2xx response and a request the builder refused all resolve to.
+* Its `message` is diagnostic; `PlaceOrder` words the code.
+*/
 const PAYMENT_GATEWAY_USER_ERROR = {
 	code: PAYMENT_GATEWAY_ERROR_CODE,
 	message: "Unable to complete the payment. Please try again."
@@ -85,7 +88,10 @@ function buildGatewayPaymentsRequest({ transaction, card }) {
 	if (!isTrustedGatewayOrigin(transaction.gatewayUrl)) throw new Error("Refusing to post card data: the transaction carries no trusted https gateway origin.");
 	const params = new URLSearchParams({ orderId: transaction.orderGroup });
 	if (transaction.userProfileId !== null) params.append("userProfileId", transaction.userProfileId);
-	if (transaction.callbackUrl !== void 0) params.append("callbackUrl", transaction.callbackUrl);
+	if (transaction.callbackUrl !== void 0) {
+		params.append("callbackUrl", transaction.callbackUrl);
+		params.append("redirect", "false");
+	}
 	const transactionId = encodeURIComponent(transaction.transactionId);
 	const url = `${transaction.gatewayUrl}/api/payments/transactions/${transactionId}/payments?${params}`;
 	const { bin, fields } = toCardBody(card);