@vtex/faststore 0.0.7 → 0.0.8

package/dist/sdk/orders/use-order-actions.js

@@ -0,0 +1,62 @@
+"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_ORDER_CANCEL } from "./order-operations.js";
+import { useMutation } from "@apollo/client/react";
+import { useCallback, useMemo } from "react";
+//#region src/sdk/orders/use-order-actions.ts
+const NETWORK_RESULT = {
+	customerOrder: null,
+	userErrors: [{
+		code: "NETWORK_ERROR",
+		message: "Unable to cancel the order. Please try again."
+	}]
+};
+function cancelVariables(input) {
+	return {
+		id: input.id,
+		input: input.reason == null ? {} : { reason: input.reason }
+	};
+}
+function useOrderActions() {
+	const [cancelMutation] = useMutation(CUSTOMER_ORDER_CANCEL);
+	const cancel = useCallback(async (input) => {
+		try {
+			const payload = (await cancelMutation({ variables: cancelVariables(input) })).data?.customerOrderCancel;
+			if (!payload) return NETWORK_RESULT;
+			return {
+				customerOrder: payload.customerOrder,
+				userErrors: payload.userErrors
+			};
+		} catch (error) {
+			console.error("[order.cancel] customerOrderCancel failed", loggableErrorName(error));
+			return NETWORK_RESULT;
+		}
+	}, [cancelMutation]);
+	return useMemo(() => ({ cancel }), [cancel]);
+}
+defineActions({
+	namespace: "order",
+	description: "Mutation-backed cancellation of one of the shopper's orders.",
+	provider: {
+		name: "OrderActionProvider",
+		importPath: "@vtex/faststore/internal/client"
+	},
+	methods: { cancel: {
+		description: "Request cancellation of one order (async/pessimistic). Resolves the payload, including a null order after an accepted write.",
+		payload: [{
+			name: "id",
+			type: "string"
+		}, {
+			name: "reason",
+			type: "string",
+			optional: true
+		}]
+	} },
+	use: useOrderActions
+});
+//#endregion
+export { useOrderActions };
+
+//# sourceMappingURL=use-order-actions.js.map

package/dist/sdk/orders/use-order-actions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-order-actions.js","names":[],"sources":["../../../src/sdk/orders/use-order-actions.ts"],"sourcesContent":["'use client';\n\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 { CUSTOMER_ORDER_CANCEL, type OrderCancelOrder, type OrderCancelUserError } from './order-operations.js';\n\nexport type { OrderCancelOrder, OrderCancelUserError } from './order-operations.js';\n\n/**\n * The `order` action namespace. `cancel` awaits `customerOrderCancel` and returns the payload.\n * It does not throw: a typed refusal stays in `userErrors`, and a transport failure becomes one\n * `NETWORK_ERROR`. A null order with empty `userErrors` means the write was accepted and the\n * re-read failed. The order id and the reason are never logged.\n */\nexport type OrderCancelInput = Readonly<{\n  id: string;\n  reason?: string | null;\n}>;\n\nexport type OrderCancelResult = Readonly<{\n  customerOrder: OrderCancelOrder | null;\n  userErrors: readonly OrderCancelUserError[];\n}>;\n\nexport type OrderActions = Readonly<{\n  cancel: (input: OrderCancelInput) => Promise<OrderCancelResult>;\n}>;\n\nconst NETWORK_ERROR: OrderCancelUserError = {\n  code: 'NETWORK_ERROR',\n  message: 'Unable to cancel the order. Please try again.',\n};\n\nconst NETWORK_RESULT: OrderCancelResult = { customerOrder: null, userErrors: [NETWORK_ERROR] };\n\nfunction cancelVariables(input: OrderCancelInput) {\n  return {\n    id: input.id,\n    input: input.reason == null ? {} : { reason: input.reason },\n  };\n}\n\nexport function useOrderActions(): OrderActions {\n  const [cancelMutation] = useMutation(CUSTOMER_ORDER_CANCEL);\n\n  const cancel = useCallback<OrderActions['cancel']>(\n    async (input) => {\n      try {\n        const result = await cancelMutation({ variables: cancelVariables(input) });\n        const payload = result.data?.customerOrderCancel;\n        if (!payload) return NETWORK_RESULT;\n        return { customerOrder: payload.customerOrder, userErrors: payload.userErrors };\n      } catch (error) {\n        console.error('[order.cancel] customerOrderCancel failed', loggableErrorName(error));\n        return NETWORK_RESULT;\n      }\n    },\n    [cancelMutation],\n  );\n\n  return useMemo(() => ({ cancel }), [cancel]);\n}\n\nexport const orderActions = defineActions({\n  namespace: 'order',\n  description: \"Mutation-backed cancellation of one of the shopper's orders.\",\n  provider: { name: 'OrderActionProvider', importPath: '@vtex/faststore/internal/client' },\n  methods: {\n    cancel: {\n      description:\n        'Request cancellation of one order (async/pessimistic). Resolves the payload, including a null order after an accepted write.',\n      payload: [\n        { name: 'id', type: 'string' },\n        { name: 'reason', type: 'string', optional: true },\n      ],\n    },\n  },\n  use: useOrderActions,\n});\n"],"mappings":";;;;;;;;AAmCA,MAAM,iBAAoC;CAAE,eAAe;CAAM,YAAY,CAAC;EAJ5E,MAAM;EACN,SAAS;CAG+E,CAAC;AAAE;AAE7F,SAAS,gBAAgB,OAAyB;CAChD,OAAO;EACL,IAAI,MAAM;EACV,OAAO,MAAM,UAAU,OAAO,CAAC,IAAI,EAAE,QAAQ,MAAM,OAAO;CAC5D;AACF;AAEA,SAAgB,kBAAgC;CAC9C,MAAM,CAAC,kBAAkB,YAAY,qBAAqB;CAE1D,MAAM,SAAS,YACb,OAAO,UAAU;EACf,IAAI;GAEF,MAAM,WAAU,MADK,eAAe,EAAE,WAAW,gBAAgB,KAAK,EAAE,CAAC,EAAA,CAClD,MAAM;GAC7B,IAAI,CAAC,SAAS,OAAO;GACrB,OAAO;IAAE,eAAe,QAAQ;IAAe,YAAY,QAAQ;GAAW;EAChF,SAAS,OAAO;GACd,QAAQ,MAAM,6CAA6C,kBAAkB,KAAK,CAAC;GACnF,OAAO;EACT;CACF,GACA,CAAC,cAAc,CACjB;CAEA,OAAO,eAAe,EAAE,OAAO,IAAI,CAAC,MAAM,CAAC;AAC7C;AAE4B,cAAc;CACxC,WAAW;CACX,aAAa;CACb,UAAU;EAAE,MAAM;EAAuB,YAAY;CAAkC;CACvF,SAAS,EACP,QAAQ;EACN,aACE;EACF,SAAS,CACP;GAAE,MAAM;GAAM,MAAM;EAAS,GAC7B;GAAE,MAAM;GAAU,MAAM;GAAU,UAAU;EAAK,CACnD;CACF,EACF;CACA,KAAK;AACP,CAAC"}

package/dist/sdk/payment/gateway-origin.js

@@ -1,33 +1,46 @@
 //#region src/sdk/payment/gateway-origin.ts
+const VAULT_HOST_SUFFIX = ".vtexvault.com";
 /**
 * The one rule deciding whether a gateway origin may be interpolated into the card POST's URL
-* (specs/use-place-order.md, Decision 4). It lives in its own module rather than in `gateway.ts`
-* because `usePlaceOrder` needs it too, and that hook imports nothing executable from the module that
-* touches card data — a boundary its own tests assert against the file's source text.
+* (specs/use-place-order.md, Decision 4; specs/route-send-payments-through-vtex-vault.md, Decision 3). It
+* lives in its own module rather than in `gateway.ts` because `usePlaceOrder` needs it too, and that hook
+* imports nothing executable from the module that touches card data — a boundary its own tests assert
+* against the file's source text.
 *
 * `PaymentStartTransactionPayload.gatewayUrl` is nullable, and `buildGatewayPaymentsRequest`
-* concatenates it (`${gatewayUrl}/api/pub/transactions/…`). Three untrusted values are real rather
-* than hypothetical, and each produces a URL that resolves against the storefront's own origin or
-* sends the card in plaintext:
+* concatenates it (`${gatewayUrl}/api/payments/transactions/…`). A value is trusted only when it is a
+* canonical `https:` origin (the string equals what the URL parser normalises it to) made of one account
+* label followed by `.vtexvault.com`, with no credentials, port, path, query, fragment, stray whitespace
+* or backslash. The label's characters and length are not checked here; the host suffix is what is
+* pinned. That rejects, besides every foreign host, the three values that are
+* real rather than hypothetical because each produces a URL that resolves against the storefront's own
+* origin or sends the card in plaintext:
 *
-* - `null` / `undefined` / `''` — the payload's own error shape (T18 nulls every field beside
-*   `userErrors`), yielding a relative path.
+* - `null` / `undefined` / `''` — the payload's own error shape (every field beside `userErrors` is
+*   nulled), yielding a relative path.
 * - the four-character string `"null"` — what `new URL('mailto:x').origin` evaluates to, so a
 *   non-special scheme upstream survives a parse-only check.
 * - an `http:` origin — parses fine and sends the PAN and CVV unencrypted.
 *
-* The `.vtexpayments.com.br` host suffix is deliberately *not* re-checked here. T18 resolves and
-* validates the origin server-side and is the authoritative source; repeating the suffix in shipped
-* client code would add nothing against the three failures above while hard-coding a deployment
-* assumption a sandbox or a future gateway host would break.
+* The host is pinned because VTEX documents one gateway host family for Send Payments and blocks every
+* other with a 404, so a host outside it can never succeed and the only thing left to defend against is a
+* backend that names one. A second gateway host (a sandbox, say) needs one more line here, on purpose.
 */
 function isTrustedGatewayOrigin(value) {
 	if (!value) return false;
+	let url;
 	try {
-		return new URL(value).protocol === "https:";
+		url = new URL(value);
 	} catch {
 		return false;
 	}
+	if (url.protocol !== "https:") return false;
+	if (url.username !== "" || url.password !== "" || url.port !== "") return false;
+	if (url.pathname !== "/" || url.search !== "" || url.hash !== "") return false;
+	if (url.origin !== value) return false;
+	if (!url.hostname.endsWith(VAULT_HOST_SUFFIX)) return false;
+	const label = url.hostname.slice(0, -14);
+	return label !== "" && !label.includes(".");
 }
 //#endregion
 export { isTrustedGatewayOrigin };

package/dist/sdk/payment/gateway-origin.js.map

@@ -1 +1 @@
-{"version":3,"file":"gateway-origin.js","names":[],"sources":["../../../src/sdk/payment/gateway-origin.ts"],"sourcesContent":["/**\n * The one rule deciding whether a gateway origin may be interpolated into the card POST's URL\n * (specs/use-place-order.md, Decision 4). It lives in its own module rather than in `gateway.ts`\n * because `usePlaceOrder` needs it too, and that hook imports nothing executable from the module that\n * touches card data — a boundary its own tests assert against the file's source text.\n *\n * `PaymentStartTransactionPayload.gatewayUrl` is nullable, and `buildGatewayPaymentsRequest`\n * concatenates it (`${gatewayUrl}/api/pub/transactions/…`). Three untrusted values are real rather\n * than hypothetical, and each produces a URL that resolves against the storefront's own origin or\n * sends the card in plaintext:\n *\n * - `null` / `undefined` / `''` — the payload's own error shape (T18 nulls every field beside\n *   `userErrors`), yielding a relative path.\n * - the four-character string `\"null\"` — what `new URL('mailto:x').origin` evaluates to, so a\n *   non-special scheme upstream survives a parse-only check.\n * - an `http:` origin — parses fine and sends the PAN and CVV unencrypted.\n *\n * The `.vtexpayments.com.br` host suffix is deliberately *not* re-checked here. T18 resolves and\n * validates the origin server-side and is the authoritative source; repeating the suffix in shipped\n * client code would add nothing against the three failures above while hard-coding a deployment\n * assumption a sandbox or a future gateway host would break.\n */\nexport function isTrustedGatewayOrigin(value: string | null | undefined): value is string {\n  if (!value) return false;\n\n  try {\n    return new URL(value).protocol === 'https:';\n  } catch {\n    // Not an absolute URL — `'/api'`, `'acme.vtexpayments.com.br'`, `'not-a-url'`.\n    return false;\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAsBA,SAAgB,uBAAuB,OAAmD;CACxF,IAAI,CAAC,OAAO,OAAO;CAEnB,IAAI;EACF,OAAO,IAAI,IAAI,KAAK,CAAC,CAAC,aAAa;CACrC,QAAQ;EAEN,OAAO;CACT;AACF"}
+{"version":3,"file":"gateway-origin.js","names":[],"sources":["../../../src/sdk/payment/gateway-origin.ts"],"sourcesContent":["const VAULT_HOST_SUFFIX = '.vtexvault.com';\n\n/**\n * The one rule deciding whether a gateway origin may be interpolated into the card POST's URL\n * (specs/use-place-order.md, Decision 4; specs/route-send-payments-through-vtex-vault.md, Decision 3). It\n * lives in its own module rather than in `gateway.ts` because `usePlaceOrder` needs it too, and that hook\n * imports nothing executable from the module that touches card data — a boundary its own tests assert\n * against the file's source text.\n *\n * `PaymentStartTransactionPayload.gatewayUrl` is nullable, and `buildGatewayPaymentsRequest`\n * concatenates it (`${gatewayUrl}/api/payments/transactions/…`). A value is trusted only when it is a\n * canonical `https:` origin (the string equals what the URL parser normalises it to) made of one account\n * label followed by `.vtexvault.com`, with no credentials, port, path, query, fragment, stray whitespace\n * or backslash. The label's characters and length are not checked here; the host suffix is what is\n * pinned. That rejects, besides every foreign host, the three values that are\n * real rather than hypothetical because each produces a URL that resolves against the storefront's own\n * origin or sends the card in plaintext:\n *\n * - `null` / `undefined` / `''` — the payload's own error shape (every field beside `userErrors` is\n *   nulled), yielding a relative path.\n * - the four-character string `\"null\"` — what `new URL('mailto:x').origin` evaluates to, so a\n *   non-special scheme upstream survives a parse-only check.\n * - an `http:` origin — parses fine and sends the PAN and CVV unencrypted.\n *\n * The host is pinned because VTEX documents one gateway host family for Send Payments and blocks every\n * other with a 404, so a host outside it can never succeed and the only thing left to defend against is a\n * backend that names one. A second gateway host (a sandbox, say) needs one more line here, on purpose.\n */\nexport function isTrustedGatewayOrigin(value: string | null | undefined): value is string {\n  if (!value) return false;\n\n  let url: URL;\n  try {\n    url = new URL(value);\n  } catch {\n    // Not an absolute URL — `'/api'`, `'acme.vtexvault.com'`, `'not-a-url'`.\n    return false;\n  }\n\n  if (url.protocol !== 'https:') return false;\n  if (url.username !== '' || url.password !== '' || url.port !== '') return false;\n  if (url.pathname !== '/' || url.search !== '' || url.hash !== '') return false;\n  // The parser forgives `https://acme.vtexvault.com?`, a trailing `/`, a leading space or an explicit\n  // `:443`; the concatenation in `buildGatewayPaymentsRequest` does not.\n  if (url.origin !== value) return false;\n  if (!url.hostname.endsWith(VAULT_HOST_SUFFIX)) return false;\n\n  const label = url.hostname.slice(0, -VAULT_HOST_SUFFIX.length);\n  return label !== '' && !label.includes('.');\n}\n"],"mappings":";AAAA,MAAM,oBAAoB;;;;;;;;;;;;;;;;;;;;;;;;;;;AA4B1B,SAAgB,uBAAuB,OAAmD;CACxF,IAAI,CAAC,OAAO,OAAO;CAEnB,IAAI;CACJ,IAAI;EACF,MAAM,IAAI,IAAI,KAAK;CACrB,QAAQ;EAEN,OAAO;CACT;CAEA,IAAI,IAAI,aAAa,UAAU,OAAO;CACtC,IAAI,IAAI,aAAa,MAAM,IAAI,aAAa,MAAM,IAAI,SAAS,IAAI,OAAO;CAC1E,IAAI,IAAI,aAAa,OAAO,IAAI,WAAW,MAAM,IAAI,SAAS,IAAI,OAAO;CAGzE,IAAI,IAAI,WAAW,OAAO,OAAO;CACjC,IAAI,CAAC,IAAI,SAAS,SAAS,iBAAiB,GAAG,OAAO;CAEtD,MAAM,QAAQ,IAAI,SAAS,MAAM,GAAG,GAAyB;CAC7D,OAAO,UAAU,MAAM,CAAC,MAAM,SAAS,GAAG;AAC5C"}

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

@@ -1,4 +1,4 @@
-import "./operations.js";
+import { PaymentUserError } from "./operations.js";
 //#region src/sdk/payment/gateway.d.ts
 /**
  * Non-sensitive descriptor of the open transaction. Every field maps to a value the caller already
@@ -9,7 +9,7 @@ import "./operations.js";
  */
 export type PaymentGatewayTransaction = Readonly<{
   /**
-   * Gateway origin, e.g. `https://acme.vtexpayments.com.br`. Server-resolved by T18 and read off
+   * Gateway origin, e.g. `https://acme.vtexvault.com`. Server-resolved by T18 and read off
    * `paymentStartTransaction`'s payload; never derived here. It is nullable there and required here,
    * so the builder re-checks it (`isTrustedGatewayOrigin`) rather than trusting the type.
    */
@@ -81,5 +81,17 @@ export type SendPaymentsRequest = Readonly<{
   transaction: PaymentGatewayTransaction;
   card: PaymentGatewayCard;
 }>;
+/**
+ * What a card POST resolves (T112). `reachedGateway` is `false` only when this module can show no request
+ * was issued — the request builder refused before any `fetch`. Anything it cannot classify (a rejection, a
+ * timeout, an abort, a malformed result) is `true`: a browser cannot tell whether a request that never
+ * answered was processed, and a `false` frees the shopper to post the card again. Beside it, `userErrors`
+ * keeps the `{ ..., userErrors }` payload shape (ADR-00005); it carries no card value.
+ */
+export type PaymentGatewayResult = Readonly<{
+  /** false only when no request was issued to the gateway. Anything unclassified is true. */
+  reachedGateway: boolean;
+  userErrors: readonly PaymentUserError[];
+}>;
 //#endregion
 //# sourceMappingURL=gateway.d.ts.map

package/dist/sdk/payment/gateway.js

@@ -1,3 +1,4 @@
+import { loggableErrorName } from "../../utils/loggable-error-name.js";
 import { isTrustedGatewayOrigin } from "./gateway-origin.js";
 //#region src/sdk/payment/gateway.ts
 /**
@@ -22,7 +23,7 @@ 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 both a rejected request and a non-2xx response resolve to. */
+/** The single userError a rejected request, a non-2xx response and a request the builder refused all resolve to. */
 const PAYMENT_GATEWAY_USER_ERROR = {
 	code: PAYMENT_GATEWAY_ERROR_CODE,
 	message: "Unable to complete the payment. Please try again."
@@ -85,7 +86,8 @@ function buildGatewayPaymentsRequest({ transaction, card }) {
 	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);
-	const url = `${transaction.gatewayUrl}/api/pub/transactions/${transaction.transactionId}/payments?${params}`;
+	const transactionId = encodeURIComponent(transaction.transactionId);
+	const url = `${transaction.gatewayUrl}/api/payments/transactions/${transactionId}/payments?${params}`;
 	const { bin, fields } = toCardBody(card);
 	const billingAddressDifferent = transaction.billingAddressDifferent ?? false;
 	return {
@@ -136,11 +138,14 @@ function buildGatewayPaymentsRequest({ transaction, card }) {
 */
 const GATEWAY_REQUEST_TIMEOUT_MS = 3e4;
 /**
-* Posts the card straight to the gateway and resolves the gateway leg's `userErrors` (empty on success).
-* A non-2xx response resolves one `GATEWAY_ERROR`; a rejected request — including this leg's own
-* timeout firing, or `options.signal` aborting — propagates, and the handler in `use-payment-actions.ts`
-* collapses it to the same one. Neither outcome reads the response body: it may echo the request, and
-* it tells the shopper nothing more actionable than "try again".
+* Posts the card straight to the gateway and resolves a `PaymentGatewayResult`. A non-2xx response
+* resolves `{ reachedGateway: true, userErrors: [GATEWAY_ERROR] }`; a request the builder refuses
+* (an untrusted origin, a malformed card) resolves `{ reachedGateway: false, userErrors: [GATEWAY_ERROR] }`
+* without issuing a `fetch` or arming a timer, logging only the error's name. A rejected request —
+* including this leg's own timeout firing, or `options.signal` aborting — propagates, and the handler in
+* `use-payment-actions.ts` collapses it to a `reachedGateway: true` result: nothing here can prove it
+* never left. Neither outcome reads the response body: it may echo the request, and it tells the shopper
+* nothing more actionable than "try again".
 *
 * `options.signal`, when given, aborts this request in *addition to* — never instead of — this module's
 * own timeout: a caller opts into an earlier or externally triggered abort, but cannot opt out of the
@@ -156,7 +161,17 @@ const GATEWAY_REQUEST_TIMEOUT_MS = 3e4;
 * dead `AbortController`, per call that resolved normally.
 */
 async function postPaymentsToGateway(request, options) {
-	const { url, body } = buildGatewayPaymentsRequest(request);
+	let built;
+	try {
+		built = buildGatewayPaymentsRequest(request);
+	} catch (error) {
+		console.error("[payment.sendPayments] the gateway request was refused before it was sent", loggableErrorName(error));
+		return {
+			reachedGateway: false,
+			userErrors: [PAYMENT_GATEWAY_USER_ERROR]
+		};
+	}
+	const { url, body } = built;
 	const controller = new AbortController();
 	const timeoutId = setTimeout(() => controller.abort(new DOMException("The gateway request timed out.", "TimeoutError")), GATEWAY_REQUEST_TIMEOUT_MS);
 	const externalSignal = options?.signal;
@@ -166,12 +181,15 @@ async function postPaymentsToGateway(request, options) {
 		else externalSignal.addEventListener("abort", onExternalAbort, { once: true });
 	}
 	try {
-		return (await fetch(url, {
-			method: "POST",
-			headers: { "Content-Type": "application/json" },
-			body: JSON.stringify(body),
-			signal: controller.signal
-		})).ok ? [] : [PAYMENT_GATEWAY_USER_ERROR];
+		return {
+			reachedGateway: true,
+			userErrors: (await fetch(url, {
+				method: "POST",
+				headers: { "Content-Type": "application/json" },
+				body: JSON.stringify(body),
+				signal: controller.signal
+			})).ok ? [] : [PAYMENT_GATEWAY_USER_ERROR]
+		};
 	} finally {
 		clearTimeout(timeoutId);
 		externalSignal?.removeEventListener("abort", onExternalAbort);

package/dist/sdk/payment/gateway.js.map

@@ -1 +1 @@
-{"version":3,"file":"gateway.js","names":[],"sources":["../../../src/sdk/payment/gateway.ts"],"sourcesContent":["/**\n * The direct-to-gateway card POST (specs/payment-action-namespace.md, US-6) — the PCI boundary of the\n * credit-card feature. A new card's number and CVV, or a saved card's CVV, go from the browser straight\n * to the VTEX payment gateway and never transit our GraphQL layer or the normalized Apollo cache\n * (RFC D13; ADR-0010's sanctioned façade flavor).\n *\n * This module imports no Apollo and no GraphQL symbol on purpose: the code that holds card data has no\n * route to the cache, and that property is checkable by reading the imports above. Card data arrives as\n * a runtime argument from the card-entry component's local state (T7) — it is never a declared action\n * payload, a fragment field, or a schema-bindable prop, so the AI Store Builder and the visual editor\n * have no name to map a value onto.\n *\n * Nothing on this path is ever logged, serialized, or stored anywhere but the request body: the caller\n * in `use-payment-actions.ts` logs a static message plus the error's `name` only.\n *\n * The request shape is behavior evidence from the legacy checkout\n * (`fastcheckout@cd09bec3`, `packages/apps/client/src/screens/Payment/components/CardForm/services/gateway.service.ts`)\n * — never a port. Where the legacy hardcoded a value under a `TODO` (installment count, interest rate,\n * reference value) this builder reads it off the transaction descriptor instead.\n */\n\nimport { isTrustedGatewayOrigin } from './gateway-origin.js';\nimport type { PaymentUserError } from './operations.js';\n\n/** Client-synthesized code for a failed gateway leg — distinct from the BFF's `NETWORK_ERROR`. */\nexport const PAYMENT_GATEWAY_ERROR_CODE = 'GATEWAY_ERROR';\n\n/** The single userError both a rejected request and a non-2xx response resolve to. */\nexport const PAYMENT_GATEWAY_USER_ERROR: PaymentUserError = {\n  code: PAYMENT_GATEWAY_ERROR_CODE,\n  message: 'Unable to complete the payment. Please try again.',\n};\n\n/**\n * Non-sensitive descriptor of the open transaction. Every field maps to a value the caller already\n * holds — `paymentStartTransaction`'s payload (T3) or the `Payment` read model (T1) — except\n * `gatewayUrl` and `merchantName`, which that payload does not carry today (Gaps 1 and 2 in the spec).\n * Amounts are in the currency's **minor units**; `PaymentStartTransactionPayload.value.amount` is a\n * decimal, so the caller converts once, visibly, rather than having this module assume an exponent.\n */\nexport type PaymentGatewayTransaction = Readonly<{\n  /**\n   * Gateway origin, e.g. `https://acme.vtexpayments.com.br`. Server-resolved by T18 and read off\n   * `paymentStartTransaction`'s payload; never derived here. It is nullable there and required here,\n   * so the builder re-checks it (`isTrustedGatewayOrigin`) rather than trusting the type.\n   */\n  gatewayUrl: string;\n  /** `PaymentStartTransactionPayload.transactionId`. */\n  transactionId: string;\n  /** VTEX merchant name for this transaction. Resolved server-side by T3 but not exposed on its payload. */\n  merchantName: string;\n  /** `PaymentStartTransactionPayload.orderGroup` — the gateway's `orderId` query parameter. */\n  orderGroup: string;\n  /** `PaymentStartTransactionPayload.userProfileId`; null for a guest order, so the query parameter is left out. */\n  userProfileId: string | null;\n  /** `Payment.selectedMethodId` — the VTEX payment-system id. */\n  paymentSystem: string;\n  /** `PaymentMethod.groupName`, e.g. `creditCardPaymentGroup`. */\n  groupName: string;\n  /** `PaymentStartTransactionPayload.value.currencyCode`. */\n  currencyCode: string;\n  /** Transaction total, in minor units. */\n  valueInCents: number;\n  /** Pre-interest base (`PaymentInstallmentOption.baseValue`), in minor units. */\n  referenceValueInCents: number;\n  /** `Payment.selectedInstallment.count`; 1 when the shopper never picked a plan. */\n  installments: number;\n  /** Per-installment amount (`PaymentInstallment.value`), in minor units. */\n  installmentsValueInCents: number;\n  /** `PaymentInstallment.interestRate`; 0 for the interest-free 1x default. */\n  interestRate: number;\n  /** Absolute return URL. Phase-2 redirect mode only; omitted in v1's direct mode. */\n  callbackUrl?: string;\n  /**\n   * Billing differs from the delivery address. Defaults to `false`, because `setBillingAddress` persists\n   * billing on the order form's `invoiceData` (T3) and the gateway reads it from there rather than from\n   * this body. The call site that would override it is T13's `usePlaceOrder`, the one place the\n   * descriptor is assembled; T11 owns the live verification of the assumption and publishes the flag to\n   * T5's `draft` for T13 to read. Confirming it never reopens this module.\n   */\n  billingAddressDifferent?: boolean;\n}>;\n\n/** A newly entered card. Runtime argument only — never declared, never logged, never cached. */\nexport type PaymentGatewayNewCard = Readonly<{\n  kind: 'new';\n  /** Full card number. The builder strips whatever separators the method's `numberMask` inserted. */\n  number: string;\n  /** Security code (CVV). */\n  securityCode: string;\n  /** Expiry. Normalized to `MM/YY`, so a `MM/YYYY` mask is accepted. */\n  expirationDate: string;\n  holderName: string;\n  /** Shopper document (a CPF). The builder strips its punctuation. */\n  document?: string;\n  /** Shopper-assigned label, when the save-card control collected one. */\n  cardLabel?: string;\n  /** The card-save flag itself — the other half of `payment.saveCard`'s consent write (RFC D5). */\n  saveCard?: boolean;\n}>;\n\n/** A previously saved card: its account reference plus the CVV the shopper re-enters. */\nexport type PaymentGatewaySavedCard = Readonly<{\n  kind: 'saved';\n  /** `SavedCard.accountId`. */\n  accountId: string;\n  /** `SavedCard.bin` — not sensitive; the read model exposes it for installment lookup. */\n  bin: string;\n  /** Security code (CVV). */\n  securityCode: string;\n}>;\n\nexport type PaymentGatewayCard = PaymentGatewayNewCard | PaymentGatewaySavedCard;\n\nexport type SendPaymentsRequest = Readonly<{\n  transaction: PaymentGatewayTransaction;\n  card: PaymentGatewayCard;\n}>;\n\n/** The assembled request. Exported so the body shape is unit-testable without issuing a POST. */\nexport type GatewayPaymentsRequest = Readonly<{ url: string; body: readonly unknown[] }>;\n\n/** VTEX bins the leading eight digits, not six — the legacy's own `sanitizedBin` slice. */\nconst BIN_LENGTH = 8;\n\n/**\n * Strips the separators a mask inserted. `PaymentMethodValidator.numberMask` is server-driven (T1) and the\n * card-entry component (T7) renders the input through it, so its local state holds `4111 1111 1111 1111`\n * rather than the digits. The legacy normalized here, in the builder, before its own BIN slice\n * (`card.cardNumber = card.cardNumber.replace(/ /g, '')`) — the boundary is the one place the obligation\n * cannot be forgotten, and a spaced BIN is a lookup the gateway fails with no diagnosable error.\n */\nfunction toDigits(value: string): string {\n  return value.replace(/\\D/g, '');\n}\n\n/** `MM/YY` whatever the mask produced (`MM/YYYY`, `MMYY`) — the legacy's own two-slice normalization. */\nfunction toDueDate(expirationDate: string): string {\n  const digits = toDigits(expirationDate);\n  return `${digits.slice(0, 2)}/${digits.slice(-2)}`;\n}\n\n/** The card half of the body — the BIN and the `fields` map, both derived from one normalization pass. */\nfunction toCardBody(card: PaymentGatewayCard): { bin: string; fields: Record<string, unknown> } {\n  if (card.kind === 'saved') {\n    return { bin: card.bin, fields: { bin: card.bin, validationCode: card.securityCode } };\n  }\n\n  const number = toDigits(card.number);\n  const bin = number.slice(0, BIN_LENGTH);\n\n  return {\n    bin,\n    fields: {\n      bin,\n      cardNumber: number,\n      // The legacy's own `\\W` strip, so a CPF typed `123.456.789-00` reaches the gateway unpunctuated.\n      document: card.document === undefined ? null : card.document.replace(/\\W/g, ''),\n      dueDate: toDueDate(card.expirationDate),\n      holderName: card.holderName,\n      validationCode: card.securityCode,\n      cardLabel: card.cardLabel,\n      savePaymentData: card.saveCard ?? false,\n    },\n  };\n}\n\n/**\n * Builds the gateway URL and body. Billing is deliberately absent from the body: `setBillingAddress`\n * already persisted it on the order form's `invoiceData` (T3), so the gateway reads it from there — hence\n * the `billingAddressDifferent: false` default the two billing flags derive from. `originalPaymentIndex`\n * is the legacy's own constant for a single-payment order.\n *\n * The origin check is the last line of defence, not the first: `usePlaceOrder` already refuses an\n * untrusted origin *before* asking a holder for the card (T13, Decision 4). A builder has no userError\n * channel, so it throws — `sendPayments` catches, collapses it to `GATEWAY_ERROR`, and logs the error's\n * name only, so nothing about the card reaches a log. The throw happens before the body is assembled.\n */\nexport function buildGatewayPaymentsRequest({ transaction, card }: SendPaymentsRequest): GatewayPaymentsRequest {\n  if (!isTrustedGatewayOrigin(transaction.gatewayUrl)) {\n    throw new Error('Refusing to post card data: the transaction carries no trusted https gateway origin.');\n  }\n\n  const params = new URLSearchParams({ orderId: transaction.orderGroup });\n  if (transaction.userProfileId !== null) params.append('userProfileId', transaction.userProfileId);\n  if (transaction.callbackUrl !== undefined) params.append('callbackUrl', transaction.callbackUrl);\n\n  const url = `${transaction.gatewayUrl}/api/pub/transactions/${transaction.transactionId}/payments?${params}`;\n\n  const { bin, fields } = toCardBody(card);\n  const billingAddressDifferent = transaction.billingAddressDifferent ?? false;\n\n  const payment = {\n    accountId: card.kind === 'saved' ? card.accountId : null,\n    bin,\n    chooseToUseNewCard: card.kind === 'new',\n    currencyCode: transaction.currencyCode,\n    fields,\n    groupName: transaction.groupName,\n    hasDefaultBillingAddress: !billingAddressDifferent,\n    id: transaction.merchantName,\n    installmentValue: transaction.installmentsValueInCents,\n    installments: transaction.installments,\n    installmentsInterestRate: transaction.interestRate,\n    installmentsValue: transaction.installmentsValueInCents,\n    interestRate: transaction.interestRate,\n    isBillingAddressDifferent: billingAddressDifferent,\n    originalPaymentIndex: 1,\n    paymentSystem: transaction.paymentSystem,\n    referenceValue: transaction.referenceValueInCents,\n    tokenId: null,\n    transaction: { id: transaction.transactionId, merchantName: transaction.merchantName },\n    value: transaction.valueInCents,\n  };\n\n  return { url, body: [payment] };\n}\n\n/**\n * T29 (FR-6, OQ-7): this leg's own abort budget. Before this task the direct-to-gateway POST carried no\n * `AbortSignal` and no timeout at all, so a gateway that never answered left `placing` true and the CTA\n * dead for the life of the mount (Route C, `place-order.md`'s Known limitations). The BFF's own default\n * is 10s (`apps/storefront-api-core/.../api-timeout.ts:9`), but a card authorization can legitimately\n * run longer than a GraphQL round trip, and this exact number is not confirmed with payments (spec\n * OQ-7) — a placeholder pending that answer, not a tuned production value.\n *\n * Exported so `gateway.test.ts`'s own abort-budget test can assert the abort fires at exactly this\n * duration, rather than against `vi.runAllTimersAsync()`, which fires any pending timer regardless of\n * duration and would stay green even if this were edited to `300_000`. That mechanism test alone is\n * still self-referential about this constant's own *value* — it advances the fake clock by whatever\n * `GATEWAY_REQUEST_TIMEOUT_MS` currently holds, so on its own it cannot catch an edit to the constant\n * either (fix round 2, verification finding V2). `gateway.test.ts` also asserts this constant against\n * the literal `30_000` directly, in its own dedicated test — that is what actually fails if this\n * constant's value ever changes.\n */\nexport const GATEWAY_REQUEST_TIMEOUT_MS = 30_000;\n\n/**\n * Posts the card straight to the gateway and resolves the gateway leg's `userErrors` (empty on success).\n * A non-2xx response resolves one `GATEWAY_ERROR`; a rejected request — including this leg's own\n * timeout firing, or `options.signal` aborting — propagates, and the handler in `use-payment-actions.ts`\n * collapses it to the same one. Neither outcome reads the response body: it may echo the request, and\n * it tells the shopper nothing more actionable than \"try again\".\n *\n * `options.signal`, when given, aborts this request in *addition to* — never instead of — this module's\n * own timeout: a caller opts into an earlier or externally triggered abort, but cannot opt out of the\n * budget that keeps this leg from hanging forever (FR-6, US-3). Composed with a plain `AbortController`\n * rather than `AbortSignal.any`/`AbortSignal.timeout` so the timeout is driven by an ordinary\n * `setTimeout`, the one implementation a test can advance deterministically with fake timers.\n *\n * No caller in this package passes `options.signal` today — it exists to satisfy the spec's own\n * Technical Contract (`specs/make-an-order-attempt-survive-a.md`) ahead of a future integration. Fix\n * pass, Low finding: the listener this composes onto `externalSignal` is now removed in the `finally`\n * below on every exit path, not only when it fires — previously, a caller that supplied a long-lived\n * signal (as opposed to a fresh one per call) would accumulate one listener, and this function's own\n * dead `AbortController`, per call that resolved normally.\n */\nexport async function postPaymentsToGateway(\n  request: SendPaymentsRequest,\n  options?: { signal?: AbortSignal },\n): Promise<readonly PaymentUserError[]> {\n  const { url, body } = buildGatewayPaymentsRequest(request);\n\n  const controller = new AbortController();\n  const timeoutId = setTimeout(\n    () => controller.abort(new DOMException('The gateway request timed out.', 'TimeoutError')),\n    GATEWAY_REQUEST_TIMEOUT_MS,\n  );\n  const externalSignal = options?.signal;\n  const onExternalAbort = () => controller.abort(externalSignal?.reason);\n  if (externalSignal) {\n    if (externalSignal.aborted) {\n      controller.abort(externalSignal.reason);\n    } else {\n      externalSignal.addEventListener('abort', onExternalAbort, { once: true });\n    }\n  }\n\n  try {\n    const response = await fetch(url, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify(body),\n      signal: controller.signal,\n    });\n\n    return response.ok ? [] : [PAYMENT_GATEWAY_USER_ERROR];\n  } finally {\n    clearTimeout(timeoutId);\n    externalSignal?.removeEventListener('abort', onExternalAbort);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;AAyBA,MAAa,6BAA6B;;AAG1C,MAAa,6BAA+C;CAC1D,MAAM;CACN,SAAS;AACX;;AA4FA,MAAM,aAAa;;;;;;;;AASnB,SAAS,SAAS,OAAuB;CACvC,OAAO,MAAM,QAAQ,OAAO,EAAE;AAChC;;AAGA,SAAS,UAAU,gBAAgC;CACjD,MAAM,SAAS,SAAS,cAAc;CACtC,OAAO,GAAG,OAAO,MAAM,GAAG,CAAC,EAAE,GAAG,OAAO,MAAM,EAAE;AACjD;;AAGA,SAAS,WAAW,MAA4E;CAC9F,IAAI,KAAK,SAAS,SAChB,OAAO;EAAE,KAAK,KAAK;EAAK,QAAQ;GAAE,KAAK,KAAK;GAAK,gBAAgB,KAAK;EAAa;CAAE;CAGvF,MAAM,SAAS,SAAS,KAAK,MAAM;CACnC,MAAM,MAAM,OAAO,MAAM,GAAG,UAAU;CAEtC,OAAO;EACL;EACA,QAAQ;GACN;GACA,YAAY;GAEZ,UAAU,KAAK,aAAa,KAAA,IAAY,OAAO,KAAK,SAAS,QAAQ,OAAO,EAAE;GAC9E,SAAS,UAAU,KAAK,cAAc;GACtC,YAAY,KAAK;GACjB,gBAAgB,KAAK;GACrB,WAAW,KAAK;GAChB,iBAAiB,KAAK,YAAY;EACpC;CACF;AACF;;;;;;;;;;;;AAaA,SAAgB,4BAA4B,EAAE,aAAa,QAAqD;CAC9G,IAAI,CAAC,uBAAuB,YAAY,UAAU,GAChD,MAAM,IAAI,MAAM,sFAAsF;CAGxG,MAAM,SAAS,IAAI,gBAAgB,EAAE,SAAS,YAAY,WAAW,CAAC;CACtE,IAAI,YAAY,kBAAkB,MAAM,OAAO,OAAO,iBAAiB,YAAY,aAAa;CAChG,IAAI,YAAY,gBAAgB,KAAA,GAAW,OAAO,OAAO,eAAe,YAAY,WAAW;CAE/F,MAAM,MAAM,GAAG,YAAY,WAAW,wBAAwB,YAAY,cAAc,YAAY;CAEpG,MAAM,EAAE,KAAK,WAAW,WAAW,IAAI;CACvC,MAAM,0BAA0B,YAAY,2BAA2B;CAyBvE,OAAO;EAAE;EAAK,MAAM,CAAC;GAtBnB,WAAW,KAAK,SAAS,UAAU,KAAK,YAAY;GACpD;GACA,oBAAoB,KAAK,SAAS;GAClC,cAAc,YAAY;GAC1B;GACA,WAAW,YAAY;GACvB,0BAA0B,CAAC;GAC3B,IAAI,YAAY;GAChB,kBAAkB,YAAY;GAC9B,cAAc,YAAY;GAC1B,0BAA0B,YAAY;GACtC,mBAAmB,YAAY;GAC/B,cAAc,YAAY;GAC1B,2BAA2B;GAC3B,sBAAsB;GACtB,eAAe,YAAY;GAC3B,gBAAgB,YAAY;GAC5B,SAAS;GACT,aAAa;IAAE,IAAI,YAAY;IAAe,cAAc,YAAY;GAAa;GACrF,OAAO,YAAY;EAGM,CAAC;CAAE;AAChC;;;;;;;;;;;;;;;;;;AAmBA,MAAa,6BAA6B;;;;;;;;;;;;;;;;;;;;;AAsB1C,eAAsB,sBACpB,SACA,SACsC;CACtC,MAAM,EAAE,KAAK,SAAS,4BAA4B,OAAO;CAEzD,MAAM,aAAa,IAAI,gBAAgB;CACvC,MAAM,YAAY,iBACV,WAAW,MAAM,IAAI,aAAa,kCAAkC,cAAc,CAAC,GACzF,0BACF;CACA,MAAM,iBAAiB,SAAS;CAChC,MAAM,wBAAwB,WAAW,MAAM,gBAAgB,MAAM;CACrE,IAAI,gBAAgB;EAClB,IAAI,eAAe,SACjB,WAAW,MAAM,eAAe,MAAM;OAEtC,eAAe,iBAAiB,SAAS,iBAAiB,EAAE,MAAM,KAAK,CAAC;CAE5E;CAEA,IAAI;EAQF,QAAO,MAPgB,MAAM,KAAK;GAChC,QAAQ;GACR,SAAS,EAAE,gBAAgB,mBAAmB;GAC9C,MAAM,KAAK,UAAU,IAAI;GACzB,QAAQ,WAAW;EACrB,CAAC,EAAA,CAEe,KAAK,CAAC,IAAI,CAAC,0BAA0B;CACvD,UAAU;EACR,aAAa,SAAS;EACtB,gBAAgB,oBAAoB,SAAS,eAAe;CAC9D;AACF"}
+{"version":3,"file":"gateway.js","names":[],"sources":["../../../src/sdk/payment/gateway.ts"],"sourcesContent":["/**\n * The direct-to-gateway card POST (specs/payment-action-namespace.md, US-6) — the PCI boundary of the\n * credit-card feature. A new card's number and CVV, or a saved card's CVV, go from the browser straight\n * to the VTEX payment gateway and never transit our GraphQL layer or the normalized Apollo cache\n * (RFC D13; ADR-0010's sanctioned façade flavor).\n *\n * This module imports no Apollo and no GraphQL symbol on purpose: the code that holds card data has no\n * route to the cache, and that property is checkable by reading the imports above. Card data arrives as\n * a runtime argument from the card-entry component's local state (T7) — it is never a declared action\n * payload, a fragment field, or a schema-bindable prop, so the AI Store Builder and the visual editor\n * have no name to map a value onto.\n *\n * Nothing on this path is ever logged, serialized, or stored anywhere but the request body: the caller\n * in `use-payment-actions.ts` logs a static message plus the error's `name` only.\n *\n * The request shape is behavior evidence from the legacy checkout\n * (`fastcheckout@cd09bec3`, `packages/apps/client/src/screens/Payment/components/CardForm/services/gateway.service.ts`)\n * — never a port. Where the legacy hardcoded a value under a `TODO` (installment count, interest rate,\n * reference value) this builder reads it off the transaction descriptor instead.\n */\n\nimport { loggableErrorName } from '../../utils/loggable-error-name.js';\nimport { isTrustedGatewayOrigin } from './gateway-origin.js';\nimport type { PaymentUserError } from './operations.js';\n\n/** Client-synthesized code for a failed gateway leg — distinct from the BFF's `NETWORK_ERROR`. */\nexport const PAYMENT_GATEWAY_ERROR_CODE = 'GATEWAY_ERROR';\n\n/** The single userError a rejected request, a non-2xx response and a request the builder refused all resolve to. */\nexport const PAYMENT_GATEWAY_USER_ERROR: PaymentUserError = {\n  code: PAYMENT_GATEWAY_ERROR_CODE,\n  message: 'Unable to complete the payment. Please try again.',\n};\n\n/**\n * Non-sensitive descriptor of the open transaction. Every field maps to a value the caller already\n * holds — `paymentStartTransaction`'s payload (T3) or the `Payment` read model (T1) — except\n * `gatewayUrl` and `merchantName`, which that payload does not carry today (Gaps 1 and 2 in the spec).\n * Amounts are in the currency's **minor units**; `PaymentStartTransactionPayload.value.amount` is a\n * decimal, so the caller converts once, visibly, rather than having this module assume an exponent.\n */\nexport type PaymentGatewayTransaction = Readonly<{\n  /**\n   * Gateway origin, e.g. `https://acme.vtexvault.com`. Server-resolved by T18 and read off\n   * `paymentStartTransaction`'s payload; never derived here. It is nullable there and required here,\n   * so the builder re-checks it (`isTrustedGatewayOrigin`) rather than trusting the type.\n   */\n  gatewayUrl: string;\n  /** `PaymentStartTransactionPayload.transactionId`. */\n  transactionId: string;\n  /** VTEX merchant name for this transaction. Resolved server-side by T3 but not exposed on its payload. */\n  merchantName: string;\n  /** `PaymentStartTransactionPayload.orderGroup` — the gateway's `orderId` query parameter. */\n  orderGroup: string;\n  /** `PaymentStartTransactionPayload.userProfileId`; null for a guest order, so the query parameter is left out. */\n  userProfileId: string | null;\n  /** `Payment.selectedMethodId` — the VTEX payment-system id. */\n  paymentSystem: string;\n  /** `PaymentMethod.groupName`, e.g. `creditCardPaymentGroup`. */\n  groupName: string;\n  /** `PaymentStartTransactionPayload.value.currencyCode`. */\n  currencyCode: string;\n  /** Transaction total, in minor units. */\n  valueInCents: number;\n  /** Pre-interest base (`PaymentInstallmentOption.baseValue`), in minor units. */\n  referenceValueInCents: number;\n  /** `Payment.selectedInstallment.count`; 1 when the shopper never picked a plan. */\n  installments: number;\n  /** Per-installment amount (`PaymentInstallment.value`), in minor units. */\n  installmentsValueInCents: number;\n  /** `PaymentInstallment.interestRate`; 0 for the interest-free 1x default. */\n  interestRate: number;\n  /** Absolute return URL. Phase-2 redirect mode only; omitted in v1's direct mode. */\n  callbackUrl?: string;\n  /**\n   * Billing differs from the delivery address. Defaults to `false`, because `setBillingAddress` persists\n   * billing on the order form's `invoiceData` (T3) and the gateway reads it from there rather than from\n   * this body. The call site that would override it is T13's `usePlaceOrder`, the one place the\n   * descriptor is assembled; T11 owns the live verification of the assumption and publishes the flag to\n   * T5's `draft` for T13 to read. Confirming it never reopens this module.\n   */\n  billingAddressDifferent?: boolean;\n}>;\n\n/** A newly entered card. Runtime argument only — never declared, never logged, never cached. */\nexport type PaymentGatewayNewCard = Readonly<{\n  kind: 'new';\n  /** Full card number. The builder strips whatever separators the method's `numberMask` inserted. */\n  number: string;\n  /** Security code (CVV). */\n  securityCode: string;\n  /** Expiry. Normalized to `MM/YY`, so a `MM/YYYY` mask is accepted. */\n  expirationDate: string;\n  holderName: string;\n  /** Shopper document (a CPF). The builder strips its punctuation. */\n  document?: string;\n  /** Shopper-assigned label, when the save-card control collected one. */\n  cardLabel?: string;\n  /** The card-save flag itself — the other half of `payment.saveCard`'s consent write (RFC D5). */\n  saveCard?: boolean;\n}>;\n\n/** A previously saved card: its account reference plus the CVV the shopper re-enters. */\nexport type PaymentGatewaySavedCard = Readonly<{\n  kind: 'saved';\n  /** `SavedCard.accountId`. */\n  accountId: string;\n  /** `SavedCard.bin` — not sensitive; the read model exposes it for installment lookup. */\n  bin: string;\n  /** Security code (CVV). */\n  securityCode: string;\n}>;\n\nexport type PaymentGatewayCard = PaymentGatewayNewCard | PaymentGatewaySavedCard;\n\nexport type SendPaymentsRequest = Readonly<{\n  transaction: PaymentGatewayTransaction;\n  card: PaymentGatewayCard;\n}>;\n\n/** The assembled request. Exported so the body shape is unit-testable without issuing a POST. */\nexport type GatewayPaymentsRequest = Readonly<{ url: string; body: readonly unknown[] }>;\n\n/** VTEX bins the leading eight digits, not six — the legacy's own `sanitizedBin` slice. */\nconst BIN_LENGTH = 8;\n\n/**\n * Strips the separators a mask inserted. `PaymentMethodValidator.numberMask` is server-driven (T1) and the\n * card-entry component (T7) renders the input through it, so its local state holds `4111 1111 1111 1111`\n * rather than the digits. The legacy normalized here, in the builder, before its own BIN slice\n * (`card.cardNumber = card.cardNumber.replace(/ /g, '')`) — the boundary is the one place the obligation\n * cannot be forgotten, and a spaced BIN is a lookup the gateway fails with no diagnosable error.\n */\nfunction toDigits(value: string): string {\n  return value.replace(/\\D/g, '');\n}\n\n/** `MM/YY` whatever the mask produced (`MM/YYYY`, `MMYY`) — the legacy's own two-slice normalization. */\nfunction toDueDate(expirationDate: string): string {\n  const digits = toDigits(expirationDate);\n  return `${digits.slice(0, 2)}/${digits.slice(-2)}`;\n}\n\n/** The card half of the body — the BIN and the `fields` map, both derived from one normalization pass. */\nfunction toCardBody(card: PaymentGatewayCard): { bin: string; fields: Record<string, unknown> } {\n  if (card.kind === 'saved') {\n    return { bin: card.bin, fields: { bin: card.bin, validationCode: card.securityCode } };\n  }\n\n  const number = toDigits(card.number);\n  const bin = number.slice(0, BIN_LENGTH);\n\n  return {\n    bin,\n    fields: {\n      bin,\n      cardNumber: number,\n      // The legacy's own `\\W` strip, so a CPF typed `123.456.789-00` reaches the gateway unpunctuated.\n      document: card.document === undefined ? null : card.document.replace(/\\W/g, ''),\n      dueDate: toDueDate(card.expirationDate),\n      holderName: card.holderName,\n      validationCode: card.securityCode,\n      cardLabel: card.cardLabel,\n      savePaymentData: card.saveCard ?? false,\n    },\n  };\n}\n\n/**\n * Builds the gateway URL and body. Billing is deliberately absent from the body: `setBillingAddress`\n * already persisted it on the order form's `invoiceData` (T3), so the gateway reads it from there — hence\n * the `billingAddressDifferent: false` default the two billing flags derive from. `originalPaymentIndex`\n * is the legacy's own constant for a single-payment order.\n *\n * The origin check is the last line of defence, not the first: `usePlaceOrder` already refuses an\n * untrusted origin *before* asking a holder for the card (T13, Decision 4). A builder has no userError\n * channel, so it throws — `sendPayments` catches, collapses it to `GATEWAY_ERROR`, and logs the error's\n * name only, so nothing about the card reaches a log. The throw happens before the body is assembled.\n */\nexport function buildGatewayPaymentsRequest({ transaction, card }: SendPaymentsRequest): GatewayPaymentsRequest {\n  if (!isTrustedGatewayOrigin(transaction.gatewayUrl)) {\n    throw new Error('Refusing to post card data: the transaction carries no trusted https gateway origin.');\n  }\n\n  const params = new URLSearchParams({ orderId: transaction.orderGroup });\n  if (transaction.userProfileId !== null) params.append('userProfileId', transaction.userProfileId);\n  if (transaction.callbackUrl !== undefined) params.append('callbackUrl', transaction.callbackUrl);\n\n  const transactionId = encodeURIComponent(transaction.transactionId);\n  const url = `${transaction.gatewayUrl}/api/payments/transactions/${transactionId}/payments?${params}`;\n\n  const { bin, fields } = toCardBody(card);\n  const billingAddressDifferent = transaction.billingAddressDifferent ?? false;\n\n  const payment = {\n    accountId: card.kind === 'saved' ? card.accountId : null,\n    bin,\n    chooseToUseNewCard: card.kind === 'new',\n    currencyCode: transaction.currencyCode,\n    fields,\n    groupName: transaction.groupName,\n    hasDefaultBillingAddress: !billingAddressDifferent,\n    id: transaction.merchantName,\n    installmentValue: transaction.installmentsValueInCents,\n    installments: transaction.installments,\n    installmentsInterestRate: transaction.interestRate,\n    installmentsValue: transaction.installmentsValueInCents,\n    interestRate: transaction.interestRate,\n    isBillingAddressDifferent: billingAddressDifferent,\n    originalPaymentIndex: 1,\n    paymentSystem: transaction.paymentSystem,\n    referenceValue: transaction.referenceValueInCents,\n    tokenId: null,\n    transaction: { id: transaction.transactionId, merchantName: transaction.merchantName },\n    value: transaction.valueInCents,\n  };\n\n  return { url, body: [payment] };\n}\n\n/**\n * T29 (FR-6, OQ-7): this leg's own abort budget. Before this task the direct-to-gateway POST carried no\n * `AbortSignal` and no timeout at all, so a gateway that never answered left `placing` true and the CTA\n * dead for the life of the mount (Route C, `place-order.md`'s Known limitations). The BFF's own default\n * is 10s (`apps/storefront-api-core/.../api-timeout.ts:9`), but a card authorization can legitimately\n * run longer than a GraphQL round trip, and this exact number is not confirmed with payments (spec\n * OQ-7) — a placeholder pending that answer, not a tuned production value.\n *\n * Exported so `gateway.test.ts`'s own abort-budget test can assert the abort fires at exactly this\n * duration, rather than against `vi.runAllTimersAsync()`, which fires any pending timer regardless of\n * duration and would stay green even if this were edited to `300_000`. That mechanism test alone is\n * still self-referential about this constant's own *value* — it advances the fake clock by whatever\n * `GATEWAY_REQUEST_TIMEOUT_MS` currently holds, so on its own it cannot catch an edit to the constant\n * either (fix round 2, verification finding V2). `gateway.test.ts` also asserts this constant against\n * the literal `30_000` directly, in its own dedicated test — that is what actually fails if this\n * constant's value ever changes.\n */\nexport const GATEWAY_REQUEST_TIMEOUT_MS = 30_000;\n\n/**\n * What a card POST resolves (T112). `reachedGateway` is `false` only when this module can show no request\n * was issued — the request builder refused before any `fetch`. Anything it cannot classify (a rejection, a\n * timeout, an abort, a malformed result) is `true`: a browser cannot tell whether a request that never\n * answered was processed, and a `false` frees the shopper to post the card again. Beside it, `userErrors`\n * keeps the `{ ..., userErrors }` payload shape (ADR-00005); it carries no card value.\n */\nexport type PaymentGatewayResult = Readonly<{\n  /** false only when no request was issued to the gateway. Anything unclassified is true. */\n  reachedGateway: boolean;\n  userErrors: readonly PaymentUserError[];\n}>;\n\n/**\n * Posts the card straight to the gateway and resolves a `PaymentGatewayResult`. A non-2xx response\n * resolves `{ reachedGateway: true, userErrors: [GATEWAY_ERROR] }`; a request the builder refuses\n * (an untrusted origin, a malformed card) resolves `{ reachedGateway: false, userErrors: [GATEWAY_ERROR] }`\n * without issuing a `fetch` or arming a timer, logging only the error's name. A rejected request —\n * including this leg's own timeout firing, or `options.signal` aborting — propagates, and the handler in\n * `use-payment-actions.ts` collapses it to a `reachedGateway: true` result: nothing here can prove it\n * never left. Neither outcome reads the response body: it may echo the request, and it tells the shopper\n * nothing more actionable than \"try again\".\n *\n * `options.signal`, when given, aborts this request in *addition to* — never instead of — this module's\n * own timeout: a caller opts into an earlier or externally triggered abort, but cannot opt out of the\n * budget that keeps this leg from hanging forever (FR-6, US-3). Composed with a plain `AbortController`\n * rather than `AbortSignal.any`/`AbortSignal.timeout` so the timeout is driven by an ordinary\n * `setTimeout`, the one implementation a test can advance deterministically with fake timers.\n *\n * No caller in this package passes `options.signal` today — it exists to satisfy the spec's own\n * Technical Contract (`specs/make-an-order-attempt-survive-a.md`) ahead of a future integration. Fix\n * pass, Low finding: the listener this composes onto `externalSignal` is now removed in the `finally`\n * below on every exit path, not only when it fires — previously, a caller that supplied a long-lived\n * signal (as opposed to a fresh one per call) would accumulate one listener, and this function's own\n * dead `AbortController`, per call that resolved normally.\n */\nexport async function postPaymentsToGateway(\n  request: SendPaymentsRequest,\n  options?: { signal?: AbortSignal },\n): Promise<PaymentGatewayResult> {\n  let built: GatewayPaymentsRequest;\n  try {\n    built = buildGatewayPaymentsRequest(request);\n  } catch (error) {\n    // Name only: the builder's message and the request it rejected can carry the card.\n    console.error(\n      '[payment.sendPayments] the gateway request was refused before it was sent',\n      loggableErrorName(error),\n    );\n    return { reachedGateway: false, userErrors: [PAYMENT_GATEWAY_USER_ERROR] };\n  }\n  const { url, body } = built;\n\n  const controller = new AbortController();\n  const timeoutId = setTimeout(\n    () => controller.abort(new DOMException('The gateway request timed out.', 'TimeoutError')),\n    GATEWAY_REQUEST_TIMEOUT_MS,\n  );\n  const externalSignal = options?.signal;\n  const onExternalAbort = () => controller.abort(externalSignal?.reason);\n  if (externalSignal) {\n    if (externalSignal.aborted) {\n      controller.abort(externalSignal.reason);\n    } else {\n      externalSignal.addEventListener('abort', onExternalAbort, { once: true });\n    }\n  }\n\n  try {\n    const response = await fetch(url, {\n      method: 'POST',\n      headers: { 'Content-Type': 'application/json' },\n      body: JSON.stringify(body),\n      signal: controller.signal,\n    });\n\n    return { reachedGateway: true, userErrors: response.ok ? [] : [PAYMENT_GATEWAY_USER_ERROR] };\n  } finally {\n    clearTimeout(timeoutId);\n    externalSignal?.removeEventListener('abort', onExternalAbort);\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;AA0BA,MAAa,6BAA6B;;AAG1C,MAAa,6BAA+C;CAC1D,MAAM;CACN,SAAS;AACX;;AA4FA,MAAM,aAAa;;;;;;;;AASnB,SAAS,SAAS,OAAuB;CACvC,OAAO,MAAM,QAAQ,OAAO,EAAE;AAChC;;AAGA,SAAS,UAAU,gBAAgC;CACjD,MAAM,SAAS,SAAS,cAAc;CACtC,OAAO,GAAG,OAAO,MAAM,GAAG,CAAC,EAAE,GAAG,OAAO,MAAM,EAAE;AACjD;;AAGA,SAAS,WAAW,MAA4E;CAC9F,IAAI,KAAK,SAAS,SAChB,OAAO;EAAE,KAAK,KAAK;EAAK,QAAQ;GAAE,KAAK,KAAK;GAAK,gBAAgB,KAAK;EAAa;CAAE;CAGvF,MAAM,SAAS,SAAS,KAAK,MAAM;CACnC,MAAM,MAAM,OAAO,MAAM,GAAG,UAAU;CAEtC,OAAO;EACL;EACA,QAAQ;GACN;GACA,YAAY;GAEZ,UAAU,KAAK,aAAa,KAAA,IAAY,OAAO,KAAK,SAAS,QAAQ,OAAO,EAAE;GAC9E,SAAS,UAAU,KAAK,cAAc;GACtC,YAAY,KAAK;GACjB,gBAAgB,KAAK;GACrB,WAAW,KAAK;GAChB,iBAAiB,KAAK,YAAY;EACpC;CACF;AACF;;;;;;;;;;;;AAaA,SAAgB,4BAA4B,EAAE,aAAa,QAAqD;CAC9G,IAAI,CAAC,uBAAuB,YAAY,UAAU,GAChD,MAAM,IAAI,MAAM,sFAAsF;CAGxG,MAAM,SAAS,IAAI,gBAAgB,EAAE,SAAS,YAAY,WAAW,CAAC;CACtE,IAAI,YAAY,kBAAkB,MAAM,OAAO,OAAO,iBAAiB,YAAY,aAAa;CAChG,IAAI,YAAY,gBAAgB,KAAA,GAAW,OAAO,OAAO,eAAe,YAAY,WAAW;CAE/F,MAAM,gBAAgB,mBAAmB,YAAY,aAAa;CAClE,MAAM,MAAM,GAAG,YAAY,WAAW,6BAA6B,cAAc,YAAY;CAE7F,MAAM,EAAE,KAAK,WAAW,WAAW,IAAI;CACvC,MAAM,0BAA0B,YAAY,2BAA2B;CAyBvE,OAAO;EAAE;EAAK,MAAM,CAAC;GAtBnB,WAAW,KAAK,SAAS,UAAU,KAAK,YAAY;GACpD;GACA,oBAAoB,KAAK,SAAS;GAClC,cAAc,YAAY;GAC1B;GACA,WAAW,YAAY;GACvB,0BAA0B,CAAC;GAC3B,IAAI,YAAY;GAChB,kBAAkB,YAAY;GAC9B,cAAc,YAAY;GAC1B,0BAA0B,YAAY;GACtC,mBAAmB,YAAY;GAC/B,cAAc,YAAY;GAC1B,2BAA2B;GAC3B,sBAAsB;GACtB,eAAe,YAAY;GAC3B,gBAAgB,YAAY;GAC5B,SAAS;GACT,aAAa;IAAE,IAAI,YAAY;IAAe,cAAc,YAAY;GAAa;GACrF,OAAO,YAAY;EAGM,CAAC;CAAE;AAChC;;;;;;;;;;;;;;;;;;AAmBA,MAAa,6BAA6B;;;;;;;;;;;;;;;;;;;;;;;;AAsC1C,eAAsB,sBACpB,SACA,SAC+B;CAC/B,IAAI;CACJ,IAAI;EACF,QAAQ,4BAA4B,OAAO;CAC7C,SAAS,OAAO;EAEd,QAAQ,MACN,6EACA,kBAAkB,KAAK,CACzB;EACA,OAAO;GAAE,gBAAgB;GAAO,YAAY,CAAC,0BAA0B;EAAE;CAC3E;CACA,MAAM,EAAE,KAAK,SAAS;CAEtB,MAAM,aAAa,IAAI,gBAAgB;CACvC,MAAM,YAAY,iBACV,WAAW,MAAM,IAAI,aAAa,kCAAkC,cAAc,CAAC,GACzF,0BACF;CACA,MAAM,iBAAiB,SAAS;CAChC,MAAM,wBAAwB,WAAW,MAAM,gBAAgB,MAAM;CACrE,IAAI,gBAAgB;EAClB,IAAI,eAAe,SACjB,WAAW,MAAM,eAAe,MAAM;OAEtC,eAAe,iBAAiB,SAAS,iBAAiB,EAAE,MAAM,KAAK,CAAC;CAE5E;CAEA,IAAI;EAQF,OAAO;GAAE,gBAAgB;GAAM,aAAY,MAPpB,MAAM,KAAK;IAChC,QAAQ;IACR,SAAS,EAAE,gBAAgB,mBAAmB;IAC9C,MAAM,KAAK,UAAU,IAAI;IACzB,QAAQ,WAAW;GACrB,CAAC,EAAA,CAEmD,KAAK,CAAC,IAAI,CAAC,0BAA0B;EAAE;CAC7F,UAAU;EACR,aAAa,SAAS;EACtB,gBAAgB,oBAAoB,SAAS,eAAe;CAC9D;AACF"}

package/dist/sdk/payment/operations.js

@@ -22,6 +22,17 @@ const PaymentFragment = gql`
     selectedMethodId
     selectedAccountId
     selectedBin
+    storeCountryCode
+    countries {
+      __typename
+      countryCode
+      documents {
+        __typename
+        type
+        displayable
+        required
+      }
+    }
     selectedInstallment {
       __typename
       count

package/dist/sdk/payment/operations.js.map

@@ -1 +1 @@
-{"version":3,"file":"operations.js","names":[],"sources":["../../../src/sdk/payment/operations.ts"],"sourcesContent":["import type { TypedDocumentNode } from '@apollo/client';\nimport { type CartEntity, CartFragment } from '../cart/operations.js';\nimport { gql } from '../graphql-tag.js';\n\n/**\n * Payment write-model GraphQL operations (specs/payment-action-namespace.md, T4) — the five mutations\n * `api-module:PaymentWriteModel` shipped (T3, `checkout/schema.graphql` § 11). Nothing here is\n * invented: every mutation, input field, and payload field is pinned to that schema.\n *\n * Authored with the hand `gql` tag — the codegen `graphql()` factory is reserved for the reactive read\n * path — and excluded from the codegen `documents` glob (see `codegen.ts`): the `gql` tag alone is\n * still plucked by `graphql-codegen`, which would duplicate these hand-written types in\n * `sdk/generated/`. Mirrors `shipping/option-select-operations.ts` and `identity/operations.ts`.\n *\n * No field at any nesting depth carries a card number or CVV — the read model guarantees it (RFC D13),\n * and the one call that does carry them never touches GraphQL at all (see `gateway.ts`).\n *\n * Failures follow ADR-00007's two-path contract: domain outcomes arrive as payload `userErrors`;\n * transport and top-level GraphQL failures are infrastructure, collapsed by the handlers in\n * `use-payment-actions.ts` to the one client-synthesized code, `PAYMENT_NETWORK_ERROR_CODE`.\n */\n\n// ---------------------------------------------------------------------------\n// Domain types — mirror the shipped checkout schema\n// ---------------------------------------------------------------------------\n\n/** A payment domain error. Every mutation's error type is `{ code, message }`; codes stay strings. */\nexport type PaymentUserError = Readonly<{ code: string; message: string }>;\n\n/**\n * The one client-synthesized error code, carried by the userError every mutation-backed method\n * *resolves* (never throws) when its mutation fails at the transport or top-level-GraphQL layer.\n * `gateway.ts` owns the separate code for a failed gateway leg (Decision 7).\n */\nexport const PAYMENT_NETWORK_ERROR_CODE = 'NETWORK_ERROR';\n\nexport type PaymentMoney = Readonly<{ __typename?: 'Money'; amount: number; currencyCode: string }>;\n\ntype PaymentInstallmentEntity = Readonly<{\n  __typename?: 'PaymentInstallment';\n  count: number;\n  value: PaymentMoney;\n  total: PaymentMoney;\n  interestRate: number;\n}>;\n\ntype PaymentMethodValidatorEntity = Readonly<{\n  __typename?: 'PaymentMethodValidator';\n  numberMask: string | null;\n  numberRegex: string | null;\n  cvvMask: string | null;\n  cvvRegex: string | null;\n  cvvRequired: boolean;\n  expirationRequired: boolean;\n  holderNameRequired: boolean;\n  billingAddressRequired: boolean;\n  documentDisplayable: boolean;\n  documentRequired: boolean;\n}>;\n\ntype PaymentMethodEntity = Readonly<{\n  __typename?: 'PaymentMethod';\n  id: string;\n  name: string;\n  groupName: string;\n  validator: PaymentMethodValidatorEntity;\n}>;\n\ntype PaymentInstallmentOptionEntity = Readonly<{\n  __typename?: 'PaymentInstallmentOption';\n  methodId: string;\n  bin: string | null;\n  baseValue: PaymentMoney;\n  installments: readonly PaymentInstallmentEntity[];\n}>;\n\ntype SavedCardEntity = Readonly<{\n  __typename?: 'SavedCard';\n  id: string;\n  accountId: string;\n  methodId: string;\n  network: string;\n  lastFourDigits: string;\n  bin: string;\n  label: string | null;\n  expired: boolean;\n  cvvRequired: boolean;\n}>;\n\n/** The full `Payment` entity every selection mutation echoes back. Never carries a PAN or CVV. */\nexport type PaymentEntity = Readonly<{\n  __typename?: 'Payment';\n  id: string;\n  methods: readonly PaymentMethodEntity[];\n  selectedMethodId: string | null;\n  selectedAccountId: string | null;\n  selectedBin: string | null;\n  selectedInstallment: PaymentInstallmentEntity | null;\n  installmentOptions: readonly PaymentInstallmentOptionEntity[];\n  savedCards: readonly SavedCardEntity[];\n}>;\n\n/** The billing-address echo on the selection payloads — the schema's shared `Address` type. */\nexport type PaymentBillingAddressEntity = Readonly<{\n  __typename?: 'Address';\n  id: string | null;\n  recipientName: string | null;\n  postalCode: string | null;\n  country: string;\n  street: string | null;\n  number: string | null;\n  complement: string | null;\n  neighborhood: string | null;\n  city: string | null;\n  state: string | null;\n}>;\n\n// ---------------------------------------------------------------------------\n// Mutation inputs — mirror the schema's input types verbatim\n// ---------------------------------------------------------------------------\n\n/** A `bin` with an `accountId` is validated against the saved card's own BIN (MISMATCHED_BIN_FOR_SAVED_CARD). */\nexport type PaymentMethodSelectInput = Readonly<{ methodId: string; bin?: string; accountId?: string }>;\n\nexport type PaymentInstallmentSelectInput = Readonly<{ count: number }>;\n\n/** With `sameAsDelivery: true` every other field is ignored and the server performs no upstream write. */\nexport type PaymentBillingAddressUpdateInput = Readonly<{\n  sameAsDelivery: boolean;\n  addressType?: string;\n  postalCode?: string;\n  country?: string;\n  street?: string;\n  number?: string;\n  complement?: string;\n  neighborhood?: string;\n  city?: string;\n  state?: string;\n  reference?: string;\n}>;\n\nexport type PaymentGatewayCallbackInput = Readonly<{ orderGroup: string }>;\n\n// ---------------------------------------------------------------------------\n// Shared fragment\n// ---------------------------------------------------------------------------\n\n/**\n * The canonical `Payment` selection set, spread by every selection mutation so one response\n * re-normalizes the whole entity and every reactive subscriber re-renders with no refetch — the\n * payload-completeness invariant writes must honor (ADR-0010). Selecting the entire entity mirrors\n * `CartFragment` and `SHIPPING_ADDRESS_UPDATE`'s full-`Shipping` selection: the method list (T5), the\n * validator config (T7), `installmentOptions` (T9), and the summary's selection fields (T6) are all\n * subscribed independently, and a partial selection would leave one of them incomplete.\n */\nexport const PaymentFragment = gql`\n  fragment PaymentFragment on Payment {\n    __typename\n    id\n    selectedMethodId\n    selectedAccountId\n    selectedBin\n    selectedInstallment {\n      __typename\n      count\n      value {\n        amount\n        currencyCode\n      }\n      total {\n        amount\n        currencyCode\n      }\n      interestRate\n    }\n    installmentOptions {\n      __typename\n      methodId\n      bin\n      baseValue {\n        amount\n        currencyCode\n      }\n      installments {\n        __typename\n        count\n        value {\n          amount\n          currencyCode\n        }\n        total {\n          amount\n          currencyCode\n        }\n        interestRate\n      }\n    }\n    methods {\n      __typename\n      id\n      name\n      groupName\n      validator {\n        __typename\n        numberMask\n        numberRegex\n        cvvMask\n        cvvRegex\n        cvvRequired\n        expirationRequired\n        holderNameRequired\n        billingAddressRequired\n        documentDisplayable\n        documentRequired\n      }\n    }\n    savedCards {\n      __typename\n      id\n      accountId\n      methodId\n      network\n      lastFourDigits\n      bin\n      label\n      expired\n      cvvRequired\n    }\n  }\n`;\n\n/** The billing-address echo, spread by the three selection mutations that return one. */\nexport const PaymentBillingAddressFragment = gql`\n  fragment PaymentBillingAddressFragment on Address {\n    __typename\n    id\n    recipientName\n    postalCode\n    country\n    street\n    number\n    complement\n    neighborhood\n    city\n    state\n  }\n`;\n\n// ---------------------------------------------------------------------------\n// Mutation operations\n// ---------------------------------------------------------------------------\n\ntype PaymentMethodSelectMutation = Readonly<{\n  paymentMethodSelect: Readonly<{\n    __typename?: 'PaymentMethodSelectPayload';\n    payment: PaymentEntity | null;\n    billingAddress: PaymentBillingAddressEntity | null;\n    userErrors: readonly PaymentUserError[];\n  }>;\n}>;\n\nexport const PAYMENT_METHOD_SELECT: TypedDocumentNode<\n  PaymentMethodSelectMutation,\n  Readonly<{ input: PaymentMethodSelectInput }>\n> = gql`\n  mutation PaymentMethodSelect($input: PaymentMethodSelectInput!) {\n    paymentMethodSelect(input: $input) {\n      __typename\n      payment {\n        ...PaymentFragment\n      }\n      billingAddress {\n        ...PaymentBillingAddressFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n  ${PaymentFragment}\n  ${PaymentBillingAddressFragment}\n`;\n\ntype PaymentInstallmentSelectMutation = Readonly<{\n  paymentInstallmentSelect: Readonly<{\n    __typename?: 'PaymentInstallmentSelectPayload';\n    payment: PaymentEntity | null;\n    cart: CartEntity | null;\n    billingAddress: PaymentBillingAddressEntity | null;\n    userErrors: readonly PaymentUserError[];\n  }>;\n}>;\n\n/**\n * Selects `cart { ...CartFragment }` alongside `payment` so the interest-inclusive order total lands\n * in the normalized cache in the same round trip (REQ-03) — the same reason `shippingOptionSelect`\n * selects the cart.\n */\nexport const PAYMENT_INSTALLMENT_SELECT: TypedDocumentNode<\n  PaymentInstallmentSelectMutation,\n  Readonly<{ input: PaymentInstallmentSelectInput }>\n> = gql`\n  mutation PaymentInstallmentSelect($input: PaymentInstallmentSelectInput!) {\n    paymentInstallmentSelect(input: $input) {\n      __typename\n      payment {\n        ...PaymentFragment\n      }\n      cart {\n        ...CartFragment\n      }\n      billingAddress {\n        ...PaymentBillingAddressFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n  ${PaymentFragment}\n  ${PaymentBillingAddressFragment}\n  ${CartFragment}\n`;\n\ntype PaymentBillingAddressUpdateMutation = Readonly<{\n  paymentBillingAddressUpdate: Readonly<{\n    __typename?: 'PaymentBillingAddressUpdatePayload';\n    billingAddress: PaymentBillingAddressEntity | null;\n    payment: PaymentEntity | null;\n    userErrors: readonly PaymentUserError[];\n  }>;\n}>;\n\nexport const PAYMENT_BILLING_ADDRESS_UPDATE: TypedDocumentNode<\n  PaymentBillingAddressUpdateMutation,\n  Readonly<{ input: PaymentBillingAddressUpdateInput }>\n> = gql`\n  mutation PaymentBillingAddressUpdate($input: PaymentBillingAddressUpdateInput!) {\n    paymentBillingAddressUpdate(input: $input) {\n      __typename\n      billingAddress {\n        ...PaymentBillingAddressFragment\n      }\n      payment {\n        ...PaymentFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n  ${PaymentFragment}\n  ${PaymentBillingAddressFragment}\n`;\n\ntype PaymentStartTransactionMutation = Readonly<{\n  paymentStartTransaction: Readonly<{\n    __typename?: 'PaymentStartTransactionPayload';\n    transactionId: string | null;\n    merchantName: string | null;\n    gatewayUrl: string | null;\n    orderGroup: string | null;\n    userProfileId: string | null;\n    value: PaymentMoney | null;\n    valueInCents: number | null;\n    referenceValueInCents: number | null;\n    userErrors: readonly PaymentUserError[];\n  }>;\n}>;\n\n/**\n * Takes no input: every field VTEX's transaction endpoint needs is derived server-side from the\n * already-persisted selection (T3 Decision 9). The transaction cookies it mints ride on the HTTP\n * response, not on the payload.\n *\n * `merchantName`, `gatewayUrl`, `valueInCents`, and `referenceValueInCents` are T18's additions\n * (specs/payment-transaction-payload-gaps.md), selected here by T13: `PaymentGatewayTransaction`\n * requires all four, so the descriptor cannot be assembled without them. `value` stays selected\n * beside the minor-unit pair — it is the display decimal, and the `purchase` analytics event reports\n * it rather than a client-side division.\n */\nexport const PAYMENT_START_TRANSACTION: TypedDocumentNode<PaymentStartTransactionMutation, Record<string, never>> = gql`\n  mutation PaymentStartTransaction {\n    paymentStartTransaction {\n      __typename\n      transactionId\n      merchantName\n      gatewayUrl\n      orderGroup\n      userProfileId\n      value {\n        amount\n        currencyCode\n      }\n      valueInCents\n      referenceValueInCents\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n`;\n\ntype PaymentGatewayCallbackMutation = Readonly<{\n  paymentGatewayCallback: Readonly<{\n    __typename?: 'PaymentGatewayCallbackPayload';\n    orderId: string | null;\n    userErrors: readonly PaymentUserError[];\n  }>;\n}>;\n\nexport const PAYMENT_GATEWAY_CALLBACK: TypedDocumentNode<\n  PaymentGatewayCallbackMutation,\n  Readonly<{ input: PaymentGatewayCallbackInput }>\n> = gql`\n  mutation PaymentGatewayCallback($input: PaymentGatewayCallbackInput!) {\n    paymentGatewayCallback(input: $input) {\n      __typename\n      orderId\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n`;\n"],"mappings":";;;;;;;;AAkCA,MAAa,6BAA6B;;;;;;;;;AAyH1C,MAAa,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA6ElC,MAAa,gCAAgC,GAAG;;;;;;;;;;;;;;;AA6BhD,MAAa,wBAGT,GAAG;;;;;;;;;;;;;;;;IAgBH,gBAAgB;IAChB,8BAA8B;;;;;;;AAkBlC,MAAa,6BAGT,GAAG;;;;;;;;;;;;;;;;;;;IAmBH,gBAAgB;IAChB,8BAA8B;IAC9B,aAAa;;AAYjB,MAAa,iCAGT,GAAG;;;;;;;;;;;;;;;;IAgBH,gBAAgB;IAChB,8BAA8B;;;;;;;;;;;;;AA6BlC,MAAa,4BAAuG,GAAG;;;;;;;;;;;;;;;;;;;;;;AA+BvH,MAAa,2BAGT,GAAG"}
+{"version":3,"file":"operations.js","names":[],"sources":["../../../src/sdk/payment/operations.ts"],"sourcesContent":["import type { TypedDocumentNode } from '@apollo/client';\nimport { type CartEntity, CartFragment } from '../cart/operations.js';\nimport { gql } from '../graphql-tag.js';\n\n/**\n * Payment write-model GraphQL operations (specs/payment-action-namespace.md, T4) — the five mutations\n * `api-module:PaymentWriteModel` shipped (T3, `checkout/schema.graphql` § 11). Nothing here is\n * invented: every mutation, input field, and payload field is pinned to that schema.\n *\n * Authored with the hand `gql` tag — the codegen `graphql()` factory is reserved for the reactive read\n * path — and excluded from the codegen `documents` glob (see `codegen.ts`): the `gql` tag alone is\n * still plucked by `graphql-codegen`, which would duplicate these hand-written types in\n * `sdk/generated/`. Mirrors `shipping/option-select-operations.ts` and `identity/operations.ts`.\n *\n * No field at any nesting depth carries a card number or CVV — the read model guarantees it (RFC D13),\n * and the one call that does carry them never touches GraphQL at all (see `gateway.ts`).\n *\n * Failures follow ADR-00007's two-path contract: domain outcomes arrive as payload `userErrors`;\n * transport and top-level GraphQL failures are infrastructure, collapsed by the handlers in\n * `use-payment-actions.ts` to the one client-synthesized code, `PAYMENT_NETWORK_ERROR_CODE`.\n */\n\n// ---------------------------------------------------------------------------\n// Domain types — mirror the shipped checkout schema\n// ---------------------------------------------------------------------------\n\n/** A payment domain error. Every mutation's error type is `{ code, message }`; codes stay strings. */\nexport type PaymentUserError = Readonly<{ code: string; message: string }>;\n\n/**\n * The one client-synthesized error code, carried by the userError every mutation-backed method\n * *resolves* (never throws) when its mutation fails at the transport or top-level-GraphQL layer.\n * `gateway.ts` owns the separate code for a failed gateway leg (Decision 7).\n */\nexport const PAYMENT_NETWORK_ERROR_CODE = 'NETWORK_ERROR';\n\nexport type PaymentMoney = Readonly<{ __typename?: 'Money'; amount: number; currencyCode: string }>;\n\ntype PaymentInstallmentEntity = Readonly<{\n  __typename?: 'PaymentInstallment';\n  count: number;\n  value: PaymentMoney;\n  total: PaymentMoney;\n  interestRate: number;\n}>;\n\ntype PaymentMethodValidatorEntity = Readonly<{\n  __typename?: 'PaymentMethodValidator';\n  numberMask: string | null;\n  numberRegex: string | null;\n  cvvMask: string | null;\n  cvvRegex: string | null;\n  cvvRequired: boolean;\n  expirationRequired: boolean;\n  holderNameRequired: boolean;\n  billingAddressRequired: boolean;\n  documentDisplayable: boolean;\n  documentRequired: boolean;\n}>;\n\ntype PaymentCountryDocumentEntity = Readonly<{\n  __typename?: 'PaymentCountryDocument';\n  type: string;\n  displayable: boolean;\n  required: boolean;\n}>;\n\ntype PaymentCountryEntity = Readonly<{\n  __typename?: 'PaymentCountry';\n  countryCode: string;\n  documents: readonly PaymentCountryDocumentEntity[];\n}>;\n\ntype PaymentMethodEntity = Readonly<{\n  __typename?: 'PaymentMethod';\n  id: string;\n  name: string;\n  groupName: string;\n  validator: PaymentMethodValidatorEntity;\n}>;\n\ntype PaymentInstallmentOptionEntity = Readonly<{\n  __typename?: 'PaymentInstallmentOption';\n  methodId: string;\n  bin: string | null;\n  baseValue: PaymentMoney;\n  installments: readonly PaymentInstallmentEntity[];\n}>;\n\ntype SavedCardEntity = Readonly<{\n  __typename?: 'SavedCard';\n  id: string;\n  accountId: string;\n  methodId: string;\n  network: string;\n  lastFourDigits: string;\n  bin: string;\n  label: string | null;\n  expired: boolean;\n  cvvRequired: boolean;\n}>;\n\n/** The full `Payment` entity every selection mutation echoes back. Never carries a PAN or CVV. */\nexport type PaymentEntity = Readonly<{\n  __typename?: 'Payment';\n  id: string;\n  methods: readonly PaymentMethodEntity[];\n  selectedMethodId: string | null;\n  selectedAccountId: string | null;\n  selectedBin: string | null;\n  storeCountryCode: string | null;\n  countries: readonly PaymentCountryEntity[];\n  selectedInstallment: PaymentInstallmentEntity | null;\n  installmentOptions: readonly PaymentInstallmentOptionEntity[];\n  savedCards: readonly SavedCardEntity[];\n}>;\n\n/** The billing-address echo on the selection payloads — the schema's shared `Address` type. */\nexport type PaymentBillingAddressEntity = Readonly<{\n  __typename?: 'Address';\n  id: string | null;\n  recipientName: string | null;\n  postalCode: string | null;\n  country: string;\n  street: string | null;\n  number: string | null;\n  complement: string | null;\n  neighborhood: string | null;\n  city: string | null;\n  state: string | null;\n}>;\n\n// ---------------------------------------------------------------------------\n// Mutation inputs — mirror the schema's input types verbatim\n// ---------------------------------------------------------------------------\n\n/** A `bin` with an `accountId` is validated against the saved card's own BIN (MISMATCHED_BIN_FOR_SAVED_CARD). */\nexport type PaymentMethodSelectInput = Readonly<{ methodId: string; bin?: string; accountId?: string }>;\n\nexport type PaymentInstallmentSelectInput = Readonly<{ count: number }>;\n\n/** With `sameAsDelivery: true` every other field is ignored and the server performs no upstream write. */\nexport type PaymentBillingAddressUpdateInput = Readonly<{\n  sameAsDelivery: boolean;\n  addressType?: string;\n  postalCode?: string;\n  country?: string;\n  street?: string;\n  number?: string;\n  complement?: string;\n  neighborhood?: string;\n  city?: string;\n  state?: string;\n  reference?: string;\n}>;\n\nexport type PaymentGatewayCallbackInput = Readonly<{ orderGroup: string }>;\n\n// ---------------------------------------------------------------------------\n// Shared fragment\n// ---------------------------------------------------------------------------\n\n/**\n * The canonical `Payment` selection set, spread by every selection mutation so one response\n * re-normalizes the whole entity and every reactive subscriber re-renders with no refetch — the\n * payload-completeness invariant writes must honor (ADR-0010). Selecting the entire entity mirrors\n * `CartFragment` and `SHIPPING_ADDRESS_UPDATE`'s full-`Shipping` selection: the method list (T5), the\n * validator config (T7), `installmentOptions` (T9), and the summary's selection fields (T6) are all\n * subscribed independently, and a partial selection would leave one of them incomplete.\n */\nexport const PaymentFragment = gql`\n  fragment PaymentFragment on Payment {\n    __typename\n    id\n    selectedMethodId\n    selectedAccountId\n    selectedBin\n    storeCountryCode\n    countries {\n      __typename\n      countryCode\n      documents {\n        __typename\n        type\n        displayable\n        required\n      }\n    }\n    selectedInstallment {\n      __typename\n      count\n      value {\n        amount\n        currencyCode\n      }\n      total {\n        amount\n        currencyCode\n      }\n      interestRate\n    }\n    installmentOptions {\n      __typename\n      methodId\n      bin\n      baseValue {\n        amount\n        currencyCode\n      }\n      installments {\n        __typename\n        count\n        value {\n          amount\n          currencyCode\n        }\n        total {\n          amount\n          currencyCode\n        }\n        interestRate\n      }\n    }\n    methods {\n      __typename\n      id\n      name\n      groupName\n      validator {\n        __typename\n        numberMask\n        numberRegex\n        cvvMask\n        cvvRegex\n        cvvRequired\n        expirationRequired\n        holderNameRequired\n        billingAddressRequired\n        documentDisplayable\n        documentRequired\n      }\n    }\n    savedCards {\n      __typename\n      id\n      accountId\n      methodId\n      network\n      lastFourDigits\n      bin\n      label\n      expired\n      cvvRequired\n    }\n  }\n`;\n\n/** The billing-address echo, spread by the three selection mutations that return one. */\nexport const PaymentBillingAddressFragment = gql`\n  fragment PaymentBillingAddressFragment on Address {\n    __typename\n    id\n    recipientName\n    postalCode\n    country\n    street\n    number\n    complement\n    neighborhood\n    city\n    state\n  }\n`;\n\n// ---------------------------------------------------------------------------\n// Mutation operations\n// ---------------------------------------------------------------------------\n\ntype PaymentMethodSelectMutation = Readonly<{\n  paymentMethodSelect: Readonly<{\n    __typename?: 'PaymentMethodSelectPayload';\n    payment: PaymentEntity | null;\n    billingAddress: PaymentBillingAddressEntity | null;\n    userErrors: readonly PaymentUserError[];\n  }>;\n}>;\n\nexport const PAYMENT_METHOD_SELECT: TypedDocumentNode<\n  PaymentMethodSelectMutation,\n  Readonly<{ input: PaymentMethodSelectInput }>\n> = gql`\n  mutation PaymentMethodSelect($input: PaymentMethodSelectInput!) {\n    paymentMethodSelect(input: $input) {\n      __typename\n      payment {\n        ...PaymentFragment\n      }\n      billingAddress {\n        ...PaymentBillingAddressFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n  ${PaymentFragment}\n  ${PaymentBillingAddressFragment}\n`;\n\ntype PaymentInstallmentSelectMutation = Readonly<{\n  paymentInstallmentSelect: Readonly<{\n    __typename?: 'PaymentInstallmentSelectPayload';\n    payment: PaymentEntity | null;\n    cart: CartEntity | null;\n    billingAddress: PaymentBillingAddressEntity | null;\n    userErrors: readonly PaymentUserError[];\n  }>;\n}>;\n\n/**\n * Selects `cart { ...CartFragment }` alongside `payment` so the interest-inclusive order total lands\n * in the normalized cache in the same round trip (REQ-03) — the same reason `shippingOptionSelect`\n * selects the cart.\n */\nexport const PAYMENT_INSTALLMENT_SELECT: TypedDocumentNode<\n  PaymentInstallmentSelectMutation,\n  Readonly<{ input: PaymentInstallmentSelectInput }>\n> = gql`\n  mutation PaymentInstallmentSelect($input: PaymentInstallmentSelectInput!) {\n    paymentInstallmentSelect(input: $input) {\n      __typename\n      payment {\n        ...PaymentFragment\n      }\n      cart {\n        ...CartFragment\n      }\n      billingAddress {\n        ...PaymentBillingAddressFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n  ${PaymentFragment}\n  ${PaymentBillingAddressFragment}\n  ${CartFragment}\n`;\n\ntype PaymentBillingAddressUpdateMutation = Readonly<{\n  paymentBillingAddressUpdate: Readonly<{\n    __typename?: 'PaymentBillingAddressUpdatePayload';\n    billingAddress: PaymentBillingAddressEntity | null;\n    payment: PaymentEntity | null;\n    userErrors: readonly PaymentUserError[];\n  }>;\n}>;\n\nexport const PAYMENT_BILLING_ADDRESS_UPDATE: TypedDocumentNode<\n  PaymentBillingAddressUpdateMutation,\n  Readonly<{ input: PaymentBillingAddressUpdateInput }>\n> = gql`\n  mutation PaymentBillingAddressUpdate($input: PaymentBillingAddressUpdateInput!) {\n    paymentBillingAddressUpdate(input: $input) {\n      __typename\n      billingAddress {\n        ...PaymentBillingAddressFragment\n      }\n      payment {\n        ...PaymentFragment\n      }\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n  ${PaymentFragment}\n  ${PaymentBillingAddressFragment}\n`;\n\ntype PaymentStartTransactionMutation = Readonly<{\n  paymentStartTransaction: Readonly<{\n    __typename?: 'PaymentStartTransactionPayload';\n    transactionId: string | null;\n    merchantName: string | null;\n    gatewayUrl: string | null;\n    orderGroup: string | null;\n    userProfileId: string | null;\n    value: PaymentMoney | null;\n    valueInCents: number | null;\n    referenceValueInCents: number | null;\n    userErrors: readonly PaymentUserError[];\n  }>;\n}>;\n\n/**\n * Takes no input: every field VTEX's transaction endpoint needs is derived server-side from the\n * already-persisted selection (T3 Decision 9). The transaction cookies it mints ride on the HTTP\n * response, not on the payload.\n *\n * `merchantName`, `gatewayUrl`, `valueInCents`, and `referenceValueInCents` are T18's additions\n * (specs/payment-transaction-payload-gaps.md), selected here by T13: `PaymentGatewayTransaction`\n * requires all four, so the descriptor cannot be assembled without them. `value` stays selected\n * beside the minor-unit pair — it is the display decimal, and the `purchase` analytics event reports\n * it rather than a client-side division.\n */\nexport const PAYMENT_START_TRANSACTION: TypedDocumentNode<PaymentStartTransactionMutation, Record<string, never>> = gql`\n  mutation PaymentStartTransaction {\n    paymentStartTransaction {\n      __typename\n      transactionId\n      merchantName\n      gatewayUrl\n      orderGroup\n      userProfileId\n      value {\n        amount\n        currencyCode\n      }\n      valueInCents\n      referenceValueInCents\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n`;\n\ntype PaymentGatewayCallbackMutation = Readonly<{\n  paymentGatewayCallback: Readonly<{\n    __typename?: 'PaymentGatewayCallbackPayload';\n    orderId: string | null;\n    userErrors: readonly PaymentUserError[];\n  }>;\n}>;\n\nexport const PAYMENT_GATEWAY_CALLBACK: TypedDocumentNode<\n  PaymentGatewayCallbackMutation,\n  Readonly<{ input: PaymentGatewayCallbackInput }>\n> = gql`\n  mutation PaymentGatewayCallback($input: PaymentGatewayCallbackInput!) {\n    paymentGatewayCallback(input: $input) {\n      __typename\n      orderId\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n`;\n"],"mappings":";;;;;;;;AAkCA,MAAa,6BAA6B;;;;;;;;;AAwI1C,MAAa,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwFlC,MAAa,gCAAgC,GAAG;;;;;;;;;;;;;;;AA6BhD,MAAa,wBAGT,GAAG;;;;;;;;;;;;;;;;IAgBH,gBAAgB;IAChB,8BAA8B;;;;;;;AAkBlC,MAAa,6BAGT,GAAG;;;;;;;;;;;;;;;;;;;IAmBH,gBAAgB;IAChB,8BAA8B;IAC9B,aAAa;;AAYjB,MAAa,iCAGT,GAAG;;;;;;;;;;;;;;;;IAgBH,gBAAgB;IAChB,8BAA8B;;;;;;;;;;;;;AA6BlC,MAAa,4BAAuG,GAAG;;;;;;;;;;;;;;;;;;;;;;AA+BvH,MAAa,2BAGT,GAAG"}

package/dist/sdk/payment/submission-registry.d.ts

@@ -8,7 +8,8 @@ import { ReactNode } from "react";
  *
  * T7 (new card) and T12 (saved card) each register a submit-time continuation here. Each closes over
  * its own card fields, builds the gateway card object inside that closure, calls
- * `$actions.payment.sendPayments` itself, and returns only the gateway leg's `userErrors`. T13's
+ * `$actions.payment.sendPayments` itself, and returns only the gateway leg's result: its `userErrors` and
+ * whether a request reached the gateway (T112). T13's
  * `usePlaceOrder` resolves one by `path` and invokes it between start-transaction and
  * gateway-callback, so no card-shaped field appears anywhere in this channel's type signature.
  *

package/dist/sdk/payment/submission-registry.js

@@ -9,17 +9,19 @@ function PaymentSubmissionProvider({ path, children }) {
 	const submissions = useRef(/* @__PURE__ */ new Map());
 	const channel = useMemo(() => ({
 		path,
-		register: (registeredPath, submit, preflight) => {
+		register: (registeredPath, submit, preflight, explainMissingMethod) => {
 			submissions.current.set(registeredPath, {
 				submit,
-				preflight: preflight ?? null
+				preflight: preflight ?? null,
+				explainMissingMethod: explainMissingMethod ?? null
 			});
 			return () => {
 				if (submissions.current.get(registeredPath)?.submit === submit) submissions.current.delete(registeredPath);
 			};
 		},
 		resolve: (registeredPath) => submissions.current.get(registeredPath)?.submit ?? null,
-		resolvePreflight: (registeredPath) => submissions.current.get(registeredPath)?.preflight ?? null
+		resolvePreflight: (registeredPath) => submissions.current.get(registeredPath)?.preflight ?? null,
+		resolveMissingMethodExplainer: (registeredPath) => submissions.current.get(registeredPath)?.explainMissingMethod ?? null
 	}), [path]);
 	return /* @__PURE__ */ jsx(PaymentSubmissionContext, {
 		value: channel,
@@ -38,18 +40,20 @@ function usePaymentSubmission() {
 	return channel;
 }
 /**
-* The holder-facing signature (T7, T12; `preflight` added by T27). Registers `submit` — and,
-* optionally, its pre-flight check — for `path`, and unregisters on unmount or on any argument
+* The holder-facing signature (T7, T12; `preflight` added by T27, `explainMissingMethod` by T47).
+* Registers `submit` — and, optionally, its pre-flight check and its missing-method explainer — for
+* `path`, and unregisters on unmount or on any argument
 * changing, so the map always holds the latest closures over the holder's card fields — a stale one
 * would pay with the previous keystroke's CVV.
 */
-function useRegisterPaymentSubmission(path, submit, preflight) {
+function useRegisterPaymentSubmission(path, submit, preflight, explainMissingMethod) {
 	const { register } = usePaymentSubmission();
-	useEffect(() => register(path, submit, preflight), [
+	useEffect(() => register(path, submit, preflight, explainMissingMethod), [
 		register,
 		path,
 		submit,
-		preflight
+		preflight,
+		explainMissingMethod
 	]);
 }
 //#endregion

package/dist/sdk/payment/submission-registry.js.map

@@ -1 +1 @@
-{"version":3,"file":"submission-registry.js","names":[],"sources":["../../../src/sdk/payment/submission-registry.tsx"],"sourcesContent":["'use client';\n\nimport { createContext, type ReactNode, useContext, useEffect, useMemo, useRef } from 'react';\nimport type { PaymentGatewayTransaction } from './gateway.js';\nimport type { PaymentUserError } from './operations.js';\n\n/**\n * The card-data submission channel (specs/use-place-order.md, Decision 1; specs/epics/credit-card.md\n * § \"The card-data submission channel\"). **The holder submits; the orchestrator never holds.**\n *\n * T7 (new card) and T12 (saved card) each register a submit-time continuation here. Each closes over\n * its own card fields, builds the gateway card object inside that closure, calls\n * `$actions.payment.sendPayments` itself, and returns only the gateway leg's `userErrors`. T13's\n * `usePlaceOrder` resolves one by `path` and invokes it between start-transaction and\n * gateway-callback, so no card-shaped field appears anywhere in this channel's type signature.\n *\n * It is a *second*, narrow context beside T5's `payment` context rather than a field on it, because\n * the two have different shapes and different readers: `draft` is render state every leaf reads, this\n * is an imperative registry exactly two components write and one hook reads. Registration is a\n * ref-held `Map`, not state — T7 re-registers a fresh closure on every keystroke, and making that a\n * render would re-render the whole payment section per character.\n *\n * Values that are **not** sensitive travel on T5's `draft`, never here: the save-card flag and label\n * (T10), the cardholder document (T8), and the billing-address-differs flag (T11). The holder folds\n * them into the card object inside its own closure.\n *\n * This module lives in the SDK rather than beside T5's roots so the layering stays `matter → sdk`:\n * `usePlaceOrder` is an SDK hook and cannot import from `matter/`. \"Provided by T5's root\" means the\n * root renders `PaymentSubmissionProvider`, which it does — both of them, for the same ADR-0009\n * reason the `payment` context has two providers.\n */\n\n/** Which entry path a submission serves. The canonical key type; T5's `PaymentPath` aliases it. */\nexport type PaymentSubmissionPath = 'new-card' | 'saved-card';\n\n/**\n * A holder's submit-time continuation — the whole channel. It takes the non-sensitive transaction\n * descriptor and resolves the gateway leg's `userErrors` (empty on success). It must not log,\n * serialize, or return the card.\n */\nexport type PaymentSubmission = (transaction: PaymentGatewayTransaction) => Promise<readonly PaymentUserError[]>;\n\n/**\n * A holder's pre-flight verdict on its own draft, resolved before any transaction opens (T27,\n * specs/place-order-preflight-card-validation.md). Returns the refusals that would make this\n * submission pointless, or an empty array to proceed. Synchronous by contract (Decision 6): a holder\n * validates what it already holds and performs no I/O.\n *\n * Card-free by the same rule the submission itself follows — it returns `PaymentUserError`s and never\n * the fields it inspected. It may have side effects inside its own component (rendering field errors,\n * moving focus); that is the half a value-shaped gate cannot carry.\n */\nexport type PaymentPreflightCheck = () => readonly PaymentUserError[];\n\n/** One path's registration. `preflight` is `null` when its holder registered none (FR-6). */\ntype PaymentSubmissionEntry = Readonly<{\n  submit: PaymentSubmission;\n  preflight: PaymentPreflightCheck | null;\n}>;\n\nexport type PaymentSubmissionChannel = Readonly<{\n  /**\n   * The entry path the shopper is on — T5's `draft.path`, mirrored here so the place-order sequence\n   * resolves it without reading the matter context. One-way and derived: the root passes it through\n   * on every render.\n   */\n  path: PaymentSubmissionPath | null;\n  /** Registers (or replaces) the continuation, and optionally its pre-flight check, for a path. Returns its unregister function. */\n  register: (path: PaymentSubmissionPath, submit: PaymentSubmission, preflight?: PaymentPreflightCheck) => () => void;\n  /** Unchanged: the continuation registered for a path, or `null` when its holder is not composed or unmounted. */\n  resolve: (path: PaymentSubmissionPath) => PaymentSubmission | null;\n  /** The pre-flight check registered for a path, or `null` when its holder registered none. */\n  resolvePreflight: (path: PaymentSubmissionPath) => PaymentPreflightCheck | null;\n}>;\n\nconst SUBMISSION_CONTEXT_UNSET = Symbol('PaymentSubmissionContextUnset');\n\nconst PaymentSubmissionContext = createContext<PaymentSubmissionChannel | typeof SUBMISSION_CONTEXT_UNSET>(\n  SUBMISSION_CONTEXT_UNSET,\n);\n\nexport type PaymentSubmissionProviderProps = Readonly<{\n  /** T5's `draft.path`. */\n  path: PaymentSubmissionPath | null;\n  children: ReactNode;\n}>;\n\n/** Rendered by `PaymentSectionRoot` and `PaymentSectionController` around the section composition. */\nexport function PaymentSubmissionProvider({ path, children }: PaymentSubmissionProviderProps) {\n  const submissions = useRef(new Map<PaymentSubmissionPath, PaymentSubmissionEntry>());\n\n  const channel = useMemo<PaymentSubmissionChannel>(\n    () => ({\n      path,\n      register: (registeredPath, submit, preflight) => {\n        submissions.current.set(registeredPath, { submit, preflight: preflight ?? null });\n        return () => {\n          // Delete only if this registration is still the one on file: a Map holds one entry per\n          // path, so an unmounting holder whose registration was already superseded by a still-mounted\n          // sibling under the same path must not wipe that sibling's live continuation (or its check).\n          if (submissions.current.get(registeredPath)?.submit === submit) {\n            submissions.current.delete(registeredPath);\n          }\n        };\n      },\n      resolve: (registeredPath) => submissions.current.get(registeredPath)?.submit ?? null,\n      resolvePreflight: (registeredPath) => submissions.current.get(registeredPath)?.preflight ?? null,\n    }),\n    [path],\n  );\n\n  return <PaymentSubmissionContext value={channel}>{children}</PaymentSubmissionContext>;\n}\n\n/**\n * Read the submission channel from the nearest `PaymentSectionRoot` or `PaymentSectionController`.\n * Throws outside either subtree, mirroring `usePayment()`: a misplaced holder or CTA is a composition\n * bug the author should see immediately. Distinct from the two *runtime* states — no path chosen, no\n * continuation registered — which `usePlaceOrder` resolves as a userError.\n */\nexport function usePaymentSubmission(): PaymentSubmissionChannel {\n  const channel = useContext(PaymentSubmissionContext);\n  if (channel === SUBMISSION_CONTEXT_UNSET) {\n    throw new Error(\n      'usePaymentSubmission() must be used inside a <PaymentSectionRoot> or <PaymentSectionController> subtree.',\n    );\n  }\n  return channel;\n}\n\n/**\n * The holder-facing signature (T7, T12; `preflight` added by T27). Registers `submit` — and,\n * optionally, its pre-flight check — for `path`, and unregisters on unmount or on any argument\n * changing, so the map always holds the latest closures over the holder's card fields — a stale one\n * would pay with the previous keystroke's CVV.\n */\nexport function useRegisterPaymentSubmission(\n  path: PaymentSubmissionPath,\n  submit: PaymentSubmission,\n  preflight?: PaymentPreflightCheck,\n): void {\n  const { register } = usePaymentSubmission();\n\n  useEffect(() => register(path, submit, preflight), [register, path, submit, preflight]);\n}\n"],"mappings":";;;;AA2EA,MAAM,2BAA2B,OAAO,+BAA+B;AAEvE,MAAM,2BAA2B,cAC/B,wBACF;;AASA,SAAgB,0BAA0B,EAAE,MAAM,YAA4C;CAC5F,MAAM,cAAc,uBAAO,IAAI,IAAmD,CAAC;CAEnF,MAAM,UAAU,eACP;EACL;EACA,WAAW,gBAAgB,QAAQ,cAAc;GAC/C,YAAY,QAAQ,IAAI,gBAAgB;IAAE;IAAQ,WAAW,aAAa;GAAK,CAAC;GAChF,aAAa;IAIX,IAAI,YAAY,QAAQ,IAAI,cAAc,CAAC,EAAE,WAAW,QACtD,YAAY,QAAQ,OAAO,cAAc;GAE7C;EACF;EACA,UAAU,mBAAmB,YAAY,QAAQ,IAAI,cAAc,CAAC,EAAE,UAAU;EAChF,mBAAmB,mBAAmB,YAAY,QAAQ,IAAI,cAAc,CAAC,EAAE,aAAa;CAC9F,IACA,CAAC,IAAI,CACP;CAEA,OAAO,oBAAC,0BAAD;EAA0B,OAAO;EAAU;CAAmC,CAAA;AACvF;;;;;;;AAQA,SAAgB,uBAAiD;CAC/D,MAAM,UAAU,WAAW,wBAAwB;CACnD,IAAI,YAAY,0BACd,MAAM,IAAI,MACR,0GACF;CAEF,OAAO;AACT;;;;;;;AAQA,SAAgB,6BACd,MACA,QACA,WACM;CACN,MAAM,EAAE,aAAa,qBAAqB;CAE1C,gBAAgB,SAAS,MAAM,QAAQ,SAAS,GAAG;EAAC;EAAU;EAAM;EAAQ;CAAS,CAAC;AACxF"}
+{"version":3,"file":"submission-registry.js","names":[],"sources":["../../../src/sdk/payment/submission-registry.tsx"],"sourcesContent":["'use client';\n\nimport { createContext, type ReactNode, useContext, useEffect, useMemo, useRef } from 'react';\nimport type { PaymentGatewayResult, PaymentGatewayTransaction } from './gateway.js';\nimport type { PaymentUserError } from './operations.js';\n\n/**\n * The card-data submission channel (specs/use-place-order.md, Decision 1; specs/epics/credit-card.md\n * § \"The card-data submission channel\"). **The holder submits; the orchestrator never holds.**\n *\n * T7 (new card) and T12 (saved card) each register a submit-time continuation here. Each closes over\n * its own card fields, builds the gateway card object inside that closure, calls\n * `$actions.payment.sendPayments` itself, and returns only the gateway leg's result: its `userErrors` and\n * whether a request reached the gateway (T112). T13's\n * `usePlaceOrder` resolves one by `path` and invokes it between start-transaction and\n * gateway-callback, so no card-shaped field appears anywhere in this channel's type signature.\n *\n * It is a *second*, narrow context beside T5's `payment` context rather than a field on it, because\n * the two have different shapes and different readers: `draft` is render state every leaf reads, this\n * is an imperative registry exactly two components write and one hook reads. Registration is a\n * ref-held `Map`, not state — T7 re-registers a fresh closure on every keystroke, and making that a\n * render would re-render the whole payment section per character.\n *\n * Values that are **not** sensitive travel on T5's `draft`, never here: the save-card flag and label\n * (T10), the cardholder document (T8), and the billing-address-differs flag (T11). The holder folds\n * them into the card object inside its own closure.\n *\n * This module lives in the SDK rather than beside T5's roots so the layering stays `matter → sdk`:\n * `usePlaceOrder` is an SDK hook and cannot import from `matter/`. \"Provided by T5's root\" means the\n * root renders `PaymentSubmissionProvider`, which it does — both of them, for the same ADR-0009\n * reason the `payment` context has two providers.\n */\n\n/** Which entry path a submission serves. The canonical key type; T5's `PaymentPath` aliases it. */\nexport type PaymentSubmissionPath = 'new-card' | 'saved-card';\n\n/**\n * What a continuation resolves (T112): the gateway leg's `userErrors` (empty on success) and\n * `reachedGateway`, which is `false` only when the holder can show it refused before issuing any\n * request. `usePlaceOrder` frees the attempt for exactly that case and locks it for every other one,\n * including a missing or non-boolean flag. Defined by the producer, `gateway.ts`; re-exported here so the\n * hook imports it from this module and keeps `./gateway.js` to the transaction type alone.\n */\nexport type PaymentSubmissionResult = PaymentGatewayResult;\n\n/**\n * A holder's submit-time continuation — the whole channel. It takes the non-sensitive transaction\n * descriptor and resolves a `PaymentSubmissionResult`. It must not log, serialize, or return the card.\n */\nexport type PaymentSubmission = (transaction: PaymentGatewayTransaction) => Promise<PaymentSubmissionResult>;\n\n/**\n * A holder's pre-flight verdict on its own draft, resolved before any transaction opens (T27,\n * specs/place-order-preflight-card-validation.md). Returns the refusals that would make this\n * submission pointless, or an empty array to proceed. Synchronous by contract (Decision 6): a holder\n * validates what it already holds and performs no I/O.\n *\n * Card-free by the same rule the submission itself follows — it returns `PaymentUserError`s and never\n * the fields it inspected. It may have side effects inside its own component (rendering field errors,\n * moving focus); that is the half a value-shaped gate cannot carry.\n */\nexport type PaymentPreflightCheck = () => readonly PaymentUserError[];\n\n/**\n * A holder's explanation of why no payment method is selected (T47, specs/distinguish-a-pan-that-\n * matches-no-configured.md, Decision 2/4/5). Consulted only by `usePlaceOrder`'s method step, and only\n * when nothing is selected, so it can never reorder the checks. Returns the refusal to show in place of\n * the generic missing-method one, or `null` when the holder has nothing more specific to say.\n *\n * Synchronous and side-effect-free, unlike the pre-flight: it returns a value and touches nothing in its\n * own component. Fixed copy and a fixed code only — it must never echo anything the shopper typed.\n */\nexport type PaymentMissingMethodExplainer = () => PaymentUserError | null;\n\n/** One path's registration. `preflight` and `explainMissingMethod` are `null` when its holder registered none (FR-6). */\ntype PaymentSubmissionEntry = Readonly<{\n  submit: PaymentSubmission;\n  preflight: PaymentPreflightCheck | null;\n  explainMissingMethod: PaymentMissingMethodExplainer | null;\n}>;\n\nexport type PaymentSubmissionChannel = Readonly<{\n  /**\n   * The entry path the shopper is on — T5's `draft.path`, mirrored here so the place-order sequence\n   * resolves it without reading the matter context. One-way and derived: the root passes it through\n   * on every render.\n   */\n  path: PaymentSubmissionPath | null;\n  /**\n   * Registers (or replaces) the continuation, and optionally its pre-flight check and its missing-method\n   * explainer, for a path. Returns its unregister function.\n   */\n  register: (\n    path: PaymentSubmissionPath,\n    submit: PaymentSubmission,\n    preflight?: PaymentPreflightCheck,\n    explainMissingMethod?: PaymentMissingMethodExplainer,\n  ) => () => void;\n  /** Unchanged: the continuation registered for a path, or `null` when its holder is not composed or unmounted. */\n  resolve: (path: PaymentSubmissionPath) => PaymentSubmission | null;\n  /** The pre-flight check registered for a path, or `null` when its holder registered none. */\n  resolvePreflight: (path: PaymentSubmissionPath) => PaymentPreflightCheck | null;\n  /** The missing-method explainer registered for a path, or `null` when its holder registered none (T47). */\n  resolveMissingMethodExplainer: (path: PaymentSubmissionPath) => PaymentMissingMethodExplainer | null;\n}>;\n\nconst SUBMISSION_CONTEXT_UNSET = Symbol('PaymentSubmissionContextUnset');\n\nconst PaymentSubmissionContext = createContext<PaymentSubmissionChannel | typeof SUBMISSION_CONTEXT_UNSET>(\n  SUBMISSION_CONTEXT_UNSET,\n);\n\nexport type PaymentSubmissionProviderProps = Readonly<{\n  /** T5's `draft.path`. */\n  path: PaymentSubmissionPath | null;\n  children: ReactNode;\n}>;\n\n/** Rendered by `PaymentSectionRoot` and `PaymentSectionController` around the section composition. */\nexport function PaymentSubmissionProvider({ path, children }: PaymentSubmissionProviderProps) {\n  const submissions = useRef(new Map<PaymentSubmissionPath, PaymentSubmissionEntry>());\n\n  const channel = useMemo<PaymentSubmissionChannel>(\n    () => ({\n      path,\n      register: (registeredPath, submit, preflight, explainMissingMethod) => {\n        submissions.current.set(registeredPath, {\n          submit,\n          preflight: preflight ?? null,\n          explainMissingMethod: explainMissingMethod ?? null,\n        });\n        return () => {\n          // Delete only if this registration is still the one on file: a Map holds one entry per\n          // path, so an unmounting holder whose registration was already superseded by a still-mounted\n          // sibling under the same path must not wipe that sibling's live continuation (or its check).\n          if (submissions.current.get(registeredPath)?.submit === submit) {\n            submissions.current.delete(registeredPath);\n          }\n        };\n      },\n      resolve: (registeredPath) => submissions.current.get(registeredPath)?.submit ?? null,\n      resolvePreflight: (registeredPath) => submissions.current.get(registeredPath)?.preflight ?? null,\n      resolveMissingMethodExplainer: (registeredPath) =>\n        submissions.current.get(registeredPath)?.explainMissingMethod ?? null,\n    }),\n    [path],\n  );\n\n  return <PaymentSubmissionContext value={channel}>{children}</PaymentSubmissionContext>;\n}\n\n/**\n * Read the submission channel from the nearest `PaymentSectionRoot` or `PaymentSectionController`.\n * Throws outside either subtree, mirroring `usePayment()`: a misplaced holder or CTA is a composition\n * bug the author should see immediately. Distinct from the two *runtime* states — no path chosen, no\n * continuation registered — which `usePlaceOrder` resolves as a userError.\n */\nexport function usePaymentSubmission(): PaymentSubmissionChannel {\n  const channel = useContext(PaymentSubmissionContext);\n  if (channel === SUBMISSION_CONTEXT_UNSET) {\n    throw new Error(\n      'usePaymentSubmission() must be used inside a <PaymentSectionRoot> or <PaymentSectionController> subtree.',\n    );\n  }\n  return channel;\n}\n\n/**\n * The holder-facing signature (T7, T12; `preflight` added by T27, `explainMissingMethod` by T47).\n * Registers `submit` — and, optionally, its pre-flight check and its missing-method explainer — for\n * `path`, and unregisters on unmount or on any argument\n * changing, so the map always holds the latest closures over the holder's card fields — a stale one\n * would pay with the previous keystroke's CVV.\n */\nexport function useRegisterPaymentSubmission(\n  path: PaymentSubmissionPath,\n  submit: PaymentSubmission,\n  preflight?: PaymentPreflightCheck,\n  explainMissingMethod?: PaymentMissingMethodExplainer,\n): void {\n  const { register } = usePaymentSubmission();\n\n  useEffect(\n    () => register(path, submit, preflight, explainMissingMethod),\n    [register, path, submit, preflight, explainMissingMethod],\n  );\n}\n"],"mappings":";;;;AA0GA,MAAM,2BAA2B,OAAO,+BAA+B;AAEvE,MAAM,2BAA2B,cAC/B,wBACF;;AASA,SAAgB,0BAA0B,EAAE,MAAM,YAA4C;CAC5F,MAAM,cAAc,uBAAO,IAAI,IAAmD,CAAC;CAEnF,MAAM,UAAU,eACP;EACL;EACA,WAAW,gBAAgB,QAAQ,WAAW,yBAAyB;GACrE,YAAY,QAAQ,IAAI,gBAAgB;IACtC;IACA,WAAW,aAAa;IACxB,sBAAsB,wBAAwB;GAChD,CAAC;GACD,aAAa;IAIX,IAAI,YAAY,QAAQ,IAAI,cAAc,CAAC,EAAE,WAAW,QACtD,YAAY,QAAQ,OAAO,cAAc;GAE7C;EACF;EACA,UAAU,mBAAmB,YAAY,QAAQ,IAAI,cAAc,CAAC,EAAE,UAAU;EAChF,mBAAmB,mBAAmB,YAAY,QAAQ,IAAI,cAAc,CAAC,EAAE,aAAa;EAC5F,gCAAgC,mBAC9B,YAAY,QAAQ,IAAI,cAAc,CAAC,EAAE,wBAAwB;CACrE,IACA,CAAC,IAAI,CACP;CAEA,OAAO,oBAAC,0BAAD;EAA0B,OAAO;EAAU;CAAmC,CAAA;AACvF;;;;;;;AAQA,SAAgB,uBAAiD;CAC/D,MAAM,UAAU,WAAW,wBAAwB;CACnD,IAAI,YAAY,0BACd,MAAM,IAAI,MACR,0GACF;CAEF,OAAO;AACT;;;;;;;;AASA,SAAgB,6BACd,MACA,QACA,WACA,sBACM;CACN,MAAM,EAAE,aAAa,qBAAqB;CAE1C,gBACQ,SAAS,MAAM,QAAQ,WAAW,oBAAoB,GAC5D;EAAC;EAAU;EAAM;EAAQ;EAAW;CAAoB,CAC1D;AACF"}

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

@@ -1,6 +1,6 @@
 import "../../core/dist/index.js";
 import { PaymentBillingAddressUpdateInput, PaymentMethodSelectInput, PaymentMoney, PaymentUserError } from "./operations.js";
-import { SendPaymentsRequest } from "./gateway.js";
+import { PaymentGatewayResult, SendPaymentsRequest } from "./gateway.js";
 //#region src/sdk/payment/use-payment-actions.d.ts
 /**
  * The `payment` action namespace — the sanctioned client write surface for credit-card payment
@@ -70,9 +70,11 @@ export type PaymentActions = Readonly<{
   gatewayCallback: (orderGroup: string) => Promise<PaymentGatewayCallbackResult>;
   /**
    * Façade: post the card straight to the payment gateway. Issues no GraphQL operation and writes
-   * nothing to the cache. Resolves one `GATEWAY_ERROR` userError when the gateway rejects the call.
+   * nothing to the cache. Never rejects: resolves `{ reachedGateway, userErrors }`, with one `GATEWAY_ERROR`
+   * userError when the gateway rejects the call or it could not be issued. `reachedGateway` is `false`
+   * only when no request was issued; every outcome it cannot classify is `true`.
    */
-  sendPayments: (request: SendPaymentsRequest) => Promise<readonly PaymentUserError[]>;
+  sendPayments: (request: SendPaymentsRequest) => Promise<PaymentGatewayResult>;
 }>;
 //#endregion
 //# sourceMappingURL=use-payment-actions.d.ts.map

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

@@ -110,7 +110,10 @@ function usePaymentActions() {
 			return await postPaymentsToGateway(request);
 		} catch (error) {
 			console.error("[payment.sendPayments] gateway request failed", loggableErrorName(error));
-			return [PAYMENT_GATEWAY_USER_ERROR];
+			return {
+				reachedGateway: true,
+				userErrors: [PAYMENT_GATEWAY_USER_ERROR]
+			};
 		}
 	}, []);
 	return useMemo(() => ({
@@ -243,7 +246,7 @@ defineActions({
 			}]
 		},
 		sendPayments: {
-			description: "Façade: post the card directly from the browser to the payment gateway. Issues no GraphQL operation and writes nothing to the cache. The card number and CVV are runtime-only arguments and are deliberately absent from this payload — they are never a bindable field (RFC D13).",
+			description: "Façade: post the card directly from the browser to the payment gateway. Issues no GraphQL operation and writes nothing to the cache. Resolves { reachedGateway, userErrors }: reachedGateway is false only when no request was issued. The card number and CVV are runtime-only arguments and are deliberately absent from this payload — they are never a bindable field (RFC D13).",
 			payload: [
 				{
 					name: "gatewayUrl",