@vtex/faststore 0.0.10 → 0.0.12

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 { 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"}
+{"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/**\n * The single userError a rejected request, a non-2xx response and a request the builder refused all resolve to.\n * Its `message` is diagnostic; `PlaceOrder` words the code.\n */\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 for the 3D Secure challenge. Omitted when the store authored no return page. */\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) {\n    params.append('callbackUrl', transaction.callbackUrl);\n    params.append('redirect', 'false');\n  }\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;;;;;AAM1C,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;EACzC,OAAO,OAAO,eAAe,YAAY,WAAW;EACpD,OAAO,OAAO,YAAY,OAAO;CACnC;CAEA,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.d.ts

@@ -1,3 +1,4 @@
+import "../generated/graphql.js";
 import "../cart/operations.js";
 import { TypedDocumentNode } from "@apollo/client";
 //#region src/sdk/payment/operations.d.ts

package/dist/sdk/payment/operations.js

@@ -40,11 +40,12 @@ const PaymentFragment = gql`
         amount
         currencyCode
       }
-      total {
+      totalAmount {
         amount
         currencyCode
       }
       interestRate
+      interestFree
     }
     installmentOptions {
       __typename
@@ -61,17 +62,19 @@ const PaymentFragment = gql`
           amount
           currencyCode
         }
-        total {
+        totalAmount {
           amount
           currencyCode
         }
         interestRate
+        interestFree
       }
     }
     methods {
       __typename
       id
       name
+      type
       groupName
       validator {
         __typename
@@ -137,9 +140,11 @@ const PAYMENT_METHOD_SELECT = gql`
   ${PaymentBillingAddressFragment}
 `;
 /**
-* Selects `cart { ...CartFragment }` alongside `payment` so the interest-inclusive order total lands
-* in the normalized cache in the same round trip (REQ-03) — the same reason `shippingOptionSelect`
-* selects the cart.
+* Selects `cart { ...CartFragment }` alongside `payment` so the cart total the server returns lands in
+* the normalized cache in the same round trip (REQ-03) — the same reason `shippingOptionSelect`
+* selects the cart. That total is the server's: the greater of the order form's value and the selected
+* payment's value (`mapOrderFormToGqlCart`), so it carries the picked tier's interest. Dropping `total`
+* from the selection leaves the total on screen at its previous value.
 */
 const PAYMENT_INSTALLMENT_SELECT = gql`
   mutation PaymentInstallmentSelect($input: PaymentInstallmentSelectInput!) {
@@ -202,6 +207,7 @@ const PAYMENT_START_TRANSACTION = gql`
       merchantName
       gatewayUrl
       orderGroup
+      orderNodeId
       userProfileId
       value {
         amount
@@ -221,6 +227,8 @@ const PAYMENT_GATEWAY_CALLBACK = gql`
     paymentGatewayCallback(input: $input) {
       __typename
       orderId
+      orderNodeId
+      redirectUrl
       userErrors {
         code
         message
@@ -228,7 +236,21 @@ const PAYMENT_GATEWAY_CALLBACK = gql`
     }
   }
 `;
+/** Only what `emitPurchaseForOrder` needs: the order's reference, its status, and what it costs. */
+const SETTLED_ORDER_FACTS = gql`
+  query SettledOrderFacts($id: ID!) {
+    order(id: $id) {
+      id
+      reference
+      status
+      total {
+        amount
+        currencyCode
+      }
+    }
+  }
+`;
 //#endregion
-export { PAYMENT_BILLING_ADDRESS_UPDATE, PAYMENT_GATEWAY_CALLBACK, PAYMENT_INSTALLMENT_SELECT, PAYMENT_METHOD_SELECT, PAYMENT_NETWORK_ERROR_CODE, PAYMENT_START_TRANSACTION, PaymentBillingAddressFragment, PaymentFragment };
+export { PAYMENT_BILLING_ADDRESS_UPDATE, PAYMENT_GATEWAY_CALLBACK, PAYMENT_INSTALLMENT_SELECT, PAYMENT_METHOD_SELECT, PAYMENT_NETWORK_ERROR_CODE, PAYMENT_START_TRANSACTION, PaymentBillingAddressFragment, PaymentFragment, SETTLED_ORDER_FACTS };
 
 //# sourceMappingURL=operations.js.map

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 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"}
+{"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 type { PaymentType } from '../generated/graphql.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  /** The whole-plan amount, interest included. */\n  totalAmount: PaymentMoney;\n  /** Hundredths of a percent. `null` when the order form did not say what the rate is. */\n  interestRate: number | null;\n  /** `null` exactly when `interestRate` is `null`. */\n  interestFree: boolean | null;\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  /** The vendor-neutral kind. Classify a method with this; `groupName` is the gateway transport value. */\n  type: PaymentType;\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; acceptChallenges?: boolean }>;\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      totalAmount {\n        amount\n        currencyCode\n      }\n      interestRate\n      interestFree\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        totalAmount {\n          amount\n          currencyCode\n        }\n        interestRate\n        interestFree\n      }\n    }\n    methods {\n      __typename\n      id\n      name\n      type\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 cart total the server returns lands in\n * the normalized cache in the same round trip (REQ-03) — the same reason `shippingOptionSelect`\n * selects the cart. That total is the server's: the greater of the order form's value and the selected\n * payment's value (`mapOrderFormToGqlCart`), so it carries the picked tier's interest. Dropping `total`\n * from the selection leaves the total on screen at its previous value.\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    orderNodeId: 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      orderNodeId\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    orderNodeId: string | null;\n    redirectUrl: 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      orderNodeId\n      redirectUrl\n      userErrors {\n        code\n        message\n      }\n    }\n  }\n`;\n\n// ---------------------------------------------------------------------------\n// The settled-order read the resume paths report a purchase from (T208)\n// ---------------------------------------------------------------------------\n\ntype SettledOrderQuery = Readonly<{\n  order: Readonly<{\n    __typename?: 'Order';\n    id: string;\n    reference: string;\n    status: 'APPROVED' | 'PENDING' | 'DENIED' | 'UNKNOWN';\n    total: Readonly<{ __typename?: 'Money'; amount: string; currencyCode: string }> | null;\n  }> | null;\n}>;\n\n/** Only what `emitPurchaseForOrder` needs: the order's reference, its status, and what it costs. */\nexport const SETTLED_ORDER_FACTS: TypedDocumentNode<SettledOrderQuery, Readonly<{ id: string }>> = gql`\n  query SettledOrderFacts($id: ID!) {\n    order(id: $id) {\n      id\n      reference\n      status\n      total {\n        amount\n        currencyCode\n      }\n    }\n  }\n`;\n"],"mappings":";;;;;;;;AAmCA,MAAa,6BAA6B;;;;;;;;;AA8I1C,MAAa,kBAAkB,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2FlC,MAAa,gCAAgC,GAAG;;;;;;;;;;;;;;;AA6BhD,MAAa,wBAGT,GAAG;;;;;;;;;;;;;;;;IAgBH,gBAAgB;IAChB,8BAA8B;;;;;;;;;AAoBlC,MAAa,6BAGT,GAAG;;;;;;;;;;;;;;;;;;;IAmBH,gBAAgB;IAChB,8BAA8B;IAC9B,aAAa;;AAYjB,MAAa,iCAGT,GAAG;;;;;;;;;;;;;;;;IAgBH,gBAAgB;IAChB,8BAA8B;;;;;;;;;;;;;AA8BlC,MAAa,4BAAuG,GAAG;;;;;;;;;;;;;;;;;;;;;;;AAkCvH,MAAa,2BAGT,GAAG;;;;;;;;;;;;;;;AA8BP,MAAa,sBAAsF,GAAG"}

package/dist/sdk/payment/resumed-purchase.d.ts

@@ -0,0 +1 @@
+import "../analytics/use-analytics-actions.js";

package/dist/sdk/payment/resumed-purchase.js

@@ -0,0 +1,119 @@
+"use client";
+import { loggableErrorName } from "../../utils/loggable-error-name.js";
+import { SETTLED_ORDER_FACTS } from "./operations.js";
+import { getApolloContext } from "@apollo/client/react";
+import { useCallback, useContext } from "react";
+//#region src/sdk/payment/resumed-purchase.ts
+/**
+* The `purchase` analytics event for an order that was finished on a second call: the in-page resume
+* that `usePlaceOrder` runs, and the return page the bank sends the shopper to (T208, RFC D23).
+*
+* The attempt record may carry no value or currency (T29 FR-7), and a resume holds no transaction, so
+* both are read from the settled order. Every `purchase` in this package goes through `claimPurchase`,
+* so an order is reported once whichever path finished it.
+*/
+const PURCHASE_MARKER_PREFIX = "fs:purchase-sent:";
+/** Only used when storage cannot be read or written: one page lifetime still reports an order once. */
+const claimedInMemory = /* @__PURE__ */ new Set();
+/**
+* A synchronous check-and-set on `localStorage`, keyed on the order group and holding `1`, never a value, a
+* currency or anything about the shopper. The key is written before the caller emits, so an emission that
+* throws is still never repeated. Two browsers may each report one order once (ruled 2026-10-14); the marker
+* never expires and no server holds it.
+*/
+function claimPurchase(orderGroup) {
+	const key = `${PURCHASE_MARKER_PREFIX}${orderGroup}`;
+	try {
+		if (localStorage.getItem(key) !== null) return false;
+		localStorage.setItem(key, "1");
+		return true;
+	} catch {
+		if (claimedInMemory.has(key)) return false;
+		claimedInMemory.add(key);
+		return true;
+	}
+}
+/**
+* The budget for the settled-order read: a hung read must not hold the shopper on a blank return page. A
+* local race with a cleared timer, mirroring the API's own ten-second default. On expiry nothing is
+* reported and the flow goes on.
+*/
+const SETTLED_ORDER_READ_TIMEOUT_MS = 1e4;
+const ABANDONED = Symbol("abandoned");
+async function readWithinBudget(readOrder, orderNodeId) {
+	let timer;
+	const deadline = new Promise((resolve) => {
+		timer = setTimeout(() => resolve(ABANDONED), SETTLED_ORDER_READ_TIMEOUT_MS);
+	});
+	try {
+		return await Promise.race([readOrder(orderNodeId), deadline]);
+	} finally {
+		clearTimeout(timer);
+	}
+}
+/**
+* Reads a settled order for the resume paths. `null` without an Apollo client, so a story or a test rendered
+* with no provider has no read and reports no purchase; the client is taken from Apollo's context rather than
+* `useApolloClient()`, which throws without one.
+*/
+function useSettledOrderRead() {
+	const { client } = useContext(getApolloContext());
+	const read = useCallback(async (orderNodeId) => {
+		if (!client) return null;
+		const { data } = await client.query({
+			query: SETTLED_ORDER_FACTS,
+			variables: { id: orderNodeId },
+			fetchPolicy: "network-only"
+		});
+		const order = data?.order;
+		if (!order) return null;
+		const { reference, status, total } = order;
+		return {
+			reference,
+			status,
+			total: total ? {
+				amount: total.amount,
+				currencyCode: total.currencyCode
+			} : null
+		};
+	}, [client]);
+	return client ? read : null;
+}
+/**
+* Reports the purchase of an order a resume just finished. Reads the order (under the budget), then emits
+* unless it is `DENIED` or carries no total: an order that failed is not a sale, and one without a total has
+* no value to report. `PENDING` (anti-fraud review) and `UNKNOWN` report, as the direct path reports a
+* placed order without reading its status. The marker is claimed only after those checks, so an order that
+* was not reported is not burned.
+*
+* Never rejects and never throws: the order is finished whether or not the event could be sent, so a read
+* that fails, a tracker that throws or storage that refuses must not change what the shopper sees.
+*/
+async function emitPurchaseForOrder({ track, readOrder, orderNodeId }) {
+	if (!track || !readOrder) return;
+	let facts;
+	try {
+		facts = await readWithinBudget(readOrder, orderNodeId);
+	} catch (error) {
+		console.error("[payment.purchase] the settled order could not be read", loggableErrorName(error));
+		return;
+	}
+	if (facts === ABANDONED || facts === null || facts.status === "DENIED" || facts.total === null) return;
+	if (!claimPurchase(facts.reference)) return;
+	try {
+		track({
+			name: "purchase",
+			transactionId: facts.reference,
+			value: {
+				amount: Number(facts.total.amount),
+				currencyCode: facts.total.currencyCode
+			}
+		});
+	} catch (error) {
+		console.error("[payment.purchase] the purchase event could not be sent", loggableErrorName(error));
+	}
+}
+//#endregion
+export { SETTLED_ORDER_READ_TIMEOUT_MS, claimPurchase, emitPurchaseForOrder, useSettledOrderRead };
+
+//# sourceMappingURL=resumed-purchase.js.map

package/dist/sdk/payment/resumed-purchase.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resumed-purchase.js","names":[],"sources":["../../../src/sdk/payment/resumed-purchase.ts"],"sourcesContent":["'use client';\n\nimport { getApolloContext } from '@apollo/client/react';\nimport { useCallback, useContext } from 'react';\nimport { loggableErrorName } from '../../utils/loggable-error-name.js';\nimport type { AnalyticsActions } from '../analytics/use-analytics-actions.js';\nimport { SETTLED_ORDER_FACTS } from './operations.js';\n\n/**\n * The `purchase` analytics event for an order that was finished on a second call: the in-page resume\n * that `usePlaceOrder` runs, and the return page the bank sends the shopper to (T208, RFC D23).\n *\n * The attempt record may carry no value or currency (T29 FR-7), and a resume holds no transaction, so\n * both are read from the settled order. Every `purchase` in this package goes through `claimPurchase`,\n * so an order is reported once whichever path finished it.\n */\n\nconst PURCHASE_MARKER_PREFIX = 'fs:purchase-sent:';\n\n/** Only used when storage cannot be read or written: one page lifetime still reports an order once. */\nconst claimedInMemory = new Set<string>();\n\n/**\n * A synchronous check-and-set on `localStorage`, keyed on the order group and holding `1`, never a value, a\n * currency or anything about the shopper. The key is written before the caller emits, so an emission that\n * throws is still never repeated. Two browsers may each report one order once (ruled 2026-10-14); the marker\n * never expires and no server holds it.\n */\nexport function claimPurchase(orderGroup: string): boolean {\n  const key = `${PURCHASE_MARKER_PREFIX}${orderGroup}`;\n  try {\n    if (localStorage.getItem(key) !== null) return false;\n    localStorage.setItem(key, '1');\n    return true;\n  } catch {\n    if (claimedInMemory.has(key)) return false;\n    claimedInMemory.add(key);\n    return true;\n  }\n}\n\nexport type SettledOrderFacts = Readonly<{\n  reference: string;\n  status: 'APPROVED' | 'PENDING' | 'DENIED' | 'UNKNOWN';\n  total: Readonly<{ amount: string; currencyCode: string }> | null;\n}>;\n\nexport type SettledOrderRead = (orderNodeId: string) => Promise<SettledOrderFacts | null>;\n\n/**\n * The budget for the settled-order read: a hung read must not hold the shopper on a blank return page. A\n * local race with a cleared timer, mirroring the API's own ten-second default. On expiry nothing is\n * reported and the flow goes on.\n */\nexport const SETTLED_ORDER_READ_TIMEOUT_MS = 10_000;\n\nconst ABANDONED = Symbol('abandoned');\n\nasync function readWithinBudget(\n  readOrder: SettledOrderRead,\n  orderNodeId: string,\n): Promise<SettledOrderFacts | null | typeof ABANDONED> {\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  const deadline = new Promise<typeof ABANDONED>((resolve) => {\n    timer = setTimeout(() => resolve(ABANDONED), SETTLED_ORDER_READ_TIMEOUT_MS);\n  });\n  try {\n    return await Promise.race([readOrder(orderNodeId), deadline]);\n  } finally {\n    clearTimeout(timer);\n  }\n}\n\n/**\n * Reads a settled order for the resume paths. `null` without an Apollo client, so a story or a test rendered\n * with no provider has no read and reports no purchase; the client is taken from Apollo's context rather than\n * `useApolloClient()`, which throws without one.\n */\nexport function useSettledOrderRead(): SettledOrderRead | null {\n  const { client } = useContext(getApolloContext());\n\n  const read = useCallback<SettledOrderRead>(\n    async (orderNodeId) => {\n      if (!client) return null;\n      const { data } = await client.query({\n        query: SETTLED_ORDER_FACTS,\n        variables: { id: orderNodeId },\n        fetchPolicy: 'network-only',\n      });\n      const order = data?.order;\n      if (!order) return null;\n      const { reference, status, total } = order;\n      return {\n        reference,\n        status,\n        total: total ? { amount: total.amount, currencyCode: total.currencyCode } : null,\n      };\n    },\n    [client],\n  );\n\n  return client ? read : null;\n}\n\n/**\n * Reports the purchase of an order a resume just finished. Reads the order (under the budget), then emits\n * unless it is `DENIED` or carries no total: an order that failed is not a sale, and one without a total has\n * no value to report. `PENDING` (anti-fraud review) and `UNKNOWN` report, as the direct path reports a\n * placed order without reading its status. The marker is claimed only after those checks, so an order that\n * was not reported is not burned.\n *\n * Never rejects and never throws: the order is finished whether or not the event could be sent, so a read\n * that fails, a tracker that throws or storage that refuses must not change what the shopper sees.\n */\nexport async function emitPurchaseForOrder({\n  track,\n  readOrder,\n  orderNodeId,\n}: {\n  track: AnalyticsActions['track'] | null | undefined;\n  readOrder: SettledOrderRead | null | undefined;\n  orderNodeId: string;\n}): Promise<void> {\n  if (!track || !readOrder) return;\n\n  let facts: SettledOrderFacts | null | typeof ABANDONED;\n  try {\n    facts = await readWithinBudget(readOrder, orderNodeId);\n  } catch (error) {\n    console.error('[payment.purchase] the settled order could not be read', loggableErrorName(error));\n    return;\n  }\n  if (facts === ABANDONED || facts === null || facts.status === 'DENIED' || facts.total === null) return;\n\n  if (!claimPurchase(facts.reference)) return;\n  try {\n    track({\n      name: 'purchase',\n      transactionId: facts.reference,\n      value: { amount: Number(facts.total.amount), currencyCode: facts.total.currencyCode },\n    });\n  } catch (error) {\n    console.error('[payment.purchase] the purchase event could not be sent', loggableErrorName(error));\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;AAiBA,MAAM,yBAAyB;;AAG/B,MAAM,kCAAkB,IAAI,IAAY;;;;;;;AAQxC,SAAgB,cAAc,YAA6B;CACzD,MAAM,MAAM,GAAG,yBAAyB;CACxC,IAAI;EACF,IAAI,aAAa,QAAQ,GAAG,MAAM,MAAM,OAAO;EAC/C,aAAa,QAAQ,KAAK,GAAG;EAC7B,OAAO;CACT,QAAQ;EACN,IAAI,gBAAgB,IAAI,GAAG,GAAG,OAAO;EACrC,gBAAgB,IAAI,GAAG;EACvB,OAAO;CACT;AACF;;;;;;AAeA,MAAa,gCAAgC;AAE7C,MAAM,YAAY,OAAO,WAAW;AAEpC,eAAe,iBACb,WACA,aACsD;CACtD,IAAI;CACJ,MAAM,WAAW,IAAI,SAA2B,YAAY;EAC1D,QAAQ,iBAAiB,QAAQ,SAAS,GAAG,6BAA6B;CAC5E,CAAC;CACD,IAAI;EACF,OAAO,MAAM,QAAQ,KAAK,CAAC,UAAU,WAAW,GAAG,QAAQ,CAAC;CAC9D,UAAU;EACR,aAAa,KAAK;CACpB;AACF;;;;;;AAOA,SAAgB,sBAA+C;CAC7D,MAAM,EAAE,WAAW,WAAW,iBAAiB,CAAC;CAEhD,MAAM,OAAO,YACX,OAAO,gBAAgB;EACrB,IAAI,CAAC,QAAQ,OAAO;EACpB,MAAM,EAAE,SAAS,MAAM,OAAO,MAAM;GAClC,OAAO;GACP,WAAW,EAAE,IAAI,YAAY;GAC7B,aAAa;EACf,CAAC;EACD,MAAM,QAAQ,MAAM;EACpB,IAAI,CAAC,OAAO,OAAO;EACnB,MAAM,EAAE,WAAW,QAAQ,UAAU;EACrC,OAAO;GACL;GACA;GACA,OAAO,QAAQ;IAAE,QAAQ,MAAM;IAAQ,cAAc,MAAM;GAAa,IAAI;EAC9E;CACF,GACA,CAAC,MAAM,CACT;CAEA,OAAO,SAAS,OAAO;AACzB;;;;;;;;;;;AAYA,eAAsB,qBAAqB,EACzC,OACA,WACA,eAKgB;CAChB,IAAI,CAAC,SAAS,CAAC,WAAW;CAE1B,IAAI;CACJ,IAAI;EACF,QAAQ,MAAM,iBAAiB,WAAW,WAAW;CACvD,SAAS,OAAO;EACd,QAAQ,MAAM,0DAA0D,kBAAkB,KAAK,CAAC;EAChG;CACF;CACA,IAAI,UAAU,aAAa,UAAU,QAAQ,MAAM,WAAW,YAAY,MAAM,UAAU,MAAM;CAEhG,IAAI,CAAC,cAAc,MAAM,SAAS,GAAG;CACrC,IAAI;EACF,MAAM;GACJ,MAAM;GACN,eAAe,MAAM;GACrB,OAAO;IAAE,QAAQ,OAAO,MAAM,MAAM,MAAM;IAAG,cAAc,MAAM,MAAM;GAAa;EACtF,CAAC;CACH,SAAS,OAAO;EACd,QAAQ,MAAM,2DAA2D,kBAAkB,KAAK,CAAC;CACnG;AACF"}

package/dist/sdk/payment/security-code-mask.js

@@ -39,33 +39,26 @@
 */
 const SECURITY_CODE_MASK_STYLE = Object.freeze({ WebkitTextSecurity: "disc" });
 /**
-* Whether the security code is fully typed — the moment `SECURITY_CODE_MASK_STYLE` above starts
-* applying (specs/mask-the-cvv-only-once-it.md, T173). Until then the field renders its digits in
-* the clear, so a shopper can read back what they just typed and catch a typo; from then on it
-* renders exactly as it did when the mask was unconditional. The mechanism is untouched; only its
-* timing moves. Never on blur, never after a delay: the mask engages on the keystroke that completes
-* the code.
+* Whether the security code is obscured: while it is non-empty and its input does not have focus
+* (specs/stop-sending-a-stale-non-displayable-cardholder.md, T34, reversing the T173 timing that
+* obscured a code the instant its last digit arrived). A shopper who is still in the field can read
+* back what they typed and catch a typo; the moment focus leaves, nothing is left legible. The
+* mechanism is untouched; only its timing moves.
 *
-* `expectedLength` is passed in because the two fields resolve it from different places and neither
-* belongs in this module: `CardEntry` takes the detected network's `cvvMask` (three digits for most
-* networks, four for Amex), while `SavedCardCvvField` has no per-network length at all and uses its
-* own three-or-four-digit floor. Resolving it here would mean knowing about payment-method validators
-* and saved-card rows, and would still leave the comparison itself free to drift between the two.
+* `focused` is passed in already folded with whatever else disables the input: a browser fires no
+* `blur` when a focused element becomes disabled, so each caller counts a disabled input as
+* unfocused. This function knows nothing about `disabled`.
 *
-* Both callers resolve a *floor*, and a ceiling would be a defect rather than a variation: whatever
-* length arrives here is the length at which digits stop being legible, so the widest of several
-* possible lengths leaves a code that is already complete for a shorter one readable for the rest of
-* the flow.
-*
-* Derived from the value on every render, with no state and no timer. That is what makes the render
-* which first holds a complete code already the masked one — so a paste delivering every digit in one
-* event opens no legible frame — lets a cleared field unmask with nothing to reset, and leaves a code
-* the shopper backspaces into legible again while they correct it.
+* Derived from the value and the focus flag on every render, never from an effect or a timer. That
+* is what makes the render which first holds an unfocused code already the masked one — so a paste or
+* a browser autofill delivering every digit in one event, and the blur itself, open no legible frame.
+* The length of the code plays no part: the mask no longer needs a per-network or per-field length,
+* and a partial code is hidden on blur like a complete one.
 */
-function isSecurityCodeComplete(value, expectedLength) {
-	return value.length > 0 && value.length >= expectedLength;
+function isSecurityCodeMasked(value, focused) {
+	return value.length > 0 && !focused;
 }
 //#endregion
-export { SECURITY_CODE_MASK_STYLE, isSecurityCodeComplete };
+export { SECURITY_CODE_MASK_STYLE, isSecurityCodeMasked };
 
 //# sourceMappingURL=security-code-mask.js.map

package/dist/sdk/payment/security-code-mask.js.map

@@ -1 +1 @@
-{"version":3,"file":"security-code-mask.js","names":[],"sources":["../../../src/sdk/payment/security-code-mask.ts"],"sourcesContent":["import type { CSSProperties } from 'react';\n\n/**\n * The security-code masking mechanism (specs/choose-a-security-code-masking-mechanism.md, T101 of\n * the Credit Card epic; docs/features/credit-card/rfc.md § D13). One shared constant for the two\n * inputs that hold a security code — `CardEntry`'s `cvv` field and `SavedCardCvvField`'s CVV\n * re-entry field — so the two call sites cannot drift on the mechanism.\n *\n * Why this and not `type=\"password\"`: T70 shipped `type=\"password\"` on both fields and it made real\n * Chrome offer a \"Save password?\" prompt on the new-card form — pairing the expiration date as a\n * fake *Username* and the security code as *Password*, and offering to store it in Google Password\n * Manager, synced to the signed-in account. PCI-DSS forbids retaining the security code past\n * authorization, and a cloud-synced credential vault is a strictly worse posture than the field's\n * pre-T70 baseline. `type=\"password\"` was reverted; both fields ship `type=\"text\"`.\n *\n * `-webkit-text-security: disc` obscures the digits on screen without touching `type`, so the\n * heuristic that triggered the prompt (keyed off `type=\"password\"` fields in the form) never fires —\n * settled by the 2026-08-24 unblock ruling through measurement in real Chrome, not documentation.\n * Applied as an **element inline style**, never a stylesheet the package ships (forbidden by\n * ADR-0007's Consequences, `:104`) and never a class a store authors (defeatable by any compound\n * swatch) — an inline declaration is the one CSS route that is both within the architecture rule and\n * outside the store's reach, and it outranks every class-based rule at normal importance.\n *\n * This closes the password-manager capture surface structurally — it does not mean the code never\n * leaves the browser by any path. `CardEntry`'s CVV keeps `autoComplete=\"cc-csc\"` (FR-5, unchanged by\n * this task): the exact token Chrome's own Autofill uses to classify the field as\n * `CREDIT_CARD_VERIFICATION_CODE`, and Chrome ships CVC storage (`AutofillEnableCvcStorageAndFilling`)\n * that retains the CVC beside a saved server card and syncs it to the signed-in Google account. This\n * mechanism does not close that path and is not trying to — it is the separate *card* vault the field\n * honestly declares itself to via `autoComplete`, not the credential vault this change removes (spec\n * § Verification, G1(d)).\n *\n * `WebkitTextSecurity` is asserted `as CSSProperties` because csstype 3.2.3 declares no such key —\n * mirrors the existing assertion in `variant-selector.tsx`. The property is standardized nowhere;\n * supported in Chromium and WebKit (and Firefox 114+, per T70's spec). An engine without it renders\n * exactly what ships today — not a regression.\n *\n * Defined once at module scope so the object is referentially stable and React's style diffing never\n * has work to do on re-render.\n */\nexport const SECURITY_CODE_MASK_STYLE: CSSProperties = Object.freeze({ WebkitTextSecurity: 'disc' }) as CSSProperties;\n\n/**\n * Whether the security code is fully typed — the moment `SECURITY_CODE_MASK_STYLE` above starts\n * applying (specs/mask-the-cvv-only-once-it.md, T173). Until then the field renders its digits in\n * the clear, so a shopper can read back what they just typed and catch a typo; from then on it\n * renders exactly as it did when the mask was unconditional. The mechanism is untouched; only its\n * timing moves. Never on blur, never after a delay: the mask engages on the keystroke that completes\n * the code.\n *\n * `expectedLength` is passed in because the two fields resolve it from different places and neither\n * belongs in this module: `CardEntry` takes the detected network's `cvvMask` (three digits for most\n * networks, four for Amex), while `SavedCardCvvField` has no per-network length at all and uses its\n * own three-or-four-digit floor. Resolving it here would mean knowing about payment-method validators\n * and saved-card rows, and would still leave the comparison itself free to drift between the two.\n *\n * Both callers resolve a *floor*, and a ceiling would be a defect rather than a variation: whatever\n * length arrives here is the length at which digits stop being legible, so the widest of several\n * possible lengths leaves a code that is already complete for a shorter one readable for the rest of\n * the flow.\n *\n * Derived from the value on every render, with no state and no timer. That is what makes the render\n * which first holds a complete code already the masked one — so a paste delivering every digit in one\n * event opens no legible frame — lets a cleared field unmask with nothing to reset, and leaves a code\n * the shopper backspaces into legible again while they correct it.\n */\nexport function isSecurityCodeComplete(value: string, expectedLength: number): boolean {\n  // The length guard is not redundant with `>=`: a store-configured empty `cvvMask` resolves to a\n  // zero expected length, which on its own would read an untouched field as fully typed.\n  return value.length > 0 && value.length >= expectedLength;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,MAAa,2BAA0C,OAAO,OAAO,EAAE,oBAAoB,OAAO,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;AA0BnG,SAAgB,uBAAuB,OAAe,gBAAiC;CAGrF,OAAO,MAAM,SAAS,KAAK,MAAM,UAAU;AAC7C"}
+{"version":3,"file":"security-code-mask.js","names":[],"sources":["../../../src/sdk/payment/security-code-mask.ts"],"sourcesContent":["import type { CSSProperties } from 'react';\n\n/**\n * The security-code masking mechanism (specs/choose-a-security-code-masking-mechanism.md, T101 of\n * the Credit Card epic; docs/features/credit-card/rfc.md § D13). One shared constant for the two\n * inputs that hold a security code — `CardEntry`'s `cvv` field and `SavedCardCvvField`'s CVV\n * re-entry field — so the two call sites cannot drift on the mechanism.\n *\n * Why this and not `type=\"password\"`: T70 shipped `type=\"password\"` on both fields and it made real\n * Chrome offer a \"Save password?\" prompt on the new-card form — pairing the expiration date as a\n * fake *Username* and the security code as *Password*, and offering to store it in Google Password\n * Manager, synced to the signed-in account. PCI-DSS forbids retaining the security code past\n * authorization, and a cloud-synced credential vault is a strictly worse posture than the field's\n * pre-T70 baseline. `type=\"password\"` was reverted; both fields ship `type=\"text\"`.\n *\n * `-webkit-text-security: disc` obscures the digits on screen without touching `type`, so the\n * heuristic that triggered the prompt (keyed off `type=\"password\"` fields in the form) never fires —\n * settled by the 2026-08-24 unblock ruling through measurement in real Chrome, not documentation.\n * Applied as an **element inline style**, never a stylesheet the package ships (forbidden by\n * ADR-0007's Consequences, `:104`) and never a class a store authors (defeatable by any compound\n * swatch) — an inline declaration is the one CSS route that is both within the architecture rule and\n * outside the store's reach, and it outranks every class-based rule at normal importance.\n *\n * This closes the password-manager capture surface structurally — it does not mean the code never\n * leaves the browser by any path. `CardEntry`'s CVV keeps `autoComplete=\"cc-csc\"` (FR-5, unchanged by\n * this task): the exact token Chrome's own Autofill uses to classify the field as\n * `CREDIT_CARD_VERIFICATION_CODE`, and Chrome ships CVC storage (`AutofillEnableCvcStorageAndFilling`)\n * that retains the CVC beside a saved server card and syncs it to the signed-in Google account. This\n * mechanism does not close that path and is not trying to — it is the separate *card* vault the field\n * honestly declares itself to via `autoComplete`, not the credential vault this change removes (spec\n * § Verification, G1(d)).\n *\n * `WebkitTextSecurity` is asserted `as CSSProperties` because csstype 3.2.3 declares no such key —\n * mirrors the existing assertion in `variant-selector.tsx`. The property is standardized nowhere;\n * supported in Chromium and WebKit (and Firefox 114+, per T70's spec). An engine without it renders\n * exactly what ships today — not a regression.\n *\n * Defined once at module scope so the object is referentially stable and React's style diffing never\n * has work to do on re-render.\n */\nexport const SECURITY_CODE_MASK_STYLE: CSSProperties = Object.freeze({ WebkitTextSecurity: 'disc' }) as CSSProperties;\n\n/**\n * Whether the security code is obscured: while it is non-empty and its input does not have focus\n * (specs/stop-sending-a-stale-non-displayable-cardholder.md, T34, reversing the T173 timing that\n * obscured a code the instant its last digit arrived). A shopper who is still in the field can read\n * back what they typed and catch a typo; the moment focus leaves, nothing is left legible. The\n * mechanism is untouched; only its timing moves.\n *\n * `focused` is passed in already folded with whatever else disables the input: a browser fires no\n * `blur` when a focused element becomes disabled, so each caller counts a disabled input as\n * unfocused. This function knows nothing about `disabled`.\n *\n * Derived from the value and the focus flag on every render, never from an effect or a timer. That\n * is what makes the render which first holds an unfocused code already the masked one — so a paste or\n * a browser autofill delivering every digit in one event, and the blur itself, open no legible frame.\n * The length of the code plays no part: the mask no longer needs a per-network or per-field length,\n * and a partial code is hidden on blur like a complete one.\n */\nexport function isSecurityCodeMasked(value: string, focused: boolean): boolean {\n  return value.length > 0 && !focused;\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,MAAa,2BAA0C,OAAO,OAAO,EAAE,oBAAoB,OAAO,CAAC;;;;;;;;;;;;;;;;;;AAmBnG,SAAgB,qBAAqB,OAAe,SAA2B;CAC7E,OAAO,MAAM,SAAS,KAAK,CAAC;AAC9B"}

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

@@ -1,5 +1,5 @@
 "use client";
-import { createContext, useContext, useEffect, useMemo, useRef } from "react";
+import { createContext, useContext, useLayoutEffect, useMemo, useRef } from "react";
 import { jsx } from "react/jsx-runtime";
 //#region src/sdk/payment/submission-registry.tsx
 const SUBMISSION_CONTEXT_UNSET = Symbol("PaymentSubmissionContextUnset");
@@ -45,10 +45,14 @@ function usePaymentSubmission() {
 * `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.
+*
+* Registration runs in the layout phase: before paint and before any passive effect of the commit.
+* A render that no discrete event caused (an async mutation response, a timer) can be clicked on
+* before its passive effects flush, and the click would then resolve the previous commit's closure.
 */
 function useRegisterPaymentSubmission(path, submit, preflight, explainMissingMethod) {
 	const { register } = usePaymentSubmission();
-	useEffect(() => register(path, submit, preflight, explainMissingMethod), [
+	useLayoutEffect(() => register(path, submit, preflight, explainMissingMethod), [
 		register,
 		path,
 		submit,

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 { 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"}
+{"version":3,"file":"submission-registry.js","names":[],"sources":["../../../src/sdk/payment/submission-registry.tsx"],"sourcesContent":["'use client';\n\nimport { createContext, type ReactNode, useContext, useLayoutEffect, 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  Readonly<{\n    /**\n     * `true` only from a holder whose order is placed by Start Transaction alone, so the gateway leg and its\n     * callback never run (T39). Read as `=== true`, and only with an empty `userErrors`: anything else keeps\n     * the callback leg.\n     */\n    completesWithoutGateway?: boolean;\n  }>;\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 *\n * Registration runs in the layout phase: before paint and before any passive effect of the commit.\n * A render that no discrete event caused (an async mutation response, a timer) can be clicked on\n * before its passive effects flush, and the click would then resolve the previous commit's closure.\n */\nexport function useRegisterPaymentSubmission(\n  path: PaymentSubmissionPath,\n  submit: PaymentSubmission,\n  preflight?: PaymentPreflightCheck,\n  explainMissingMethod?: PaymentMissingMethodExplainer,\n): void {\n  const { register } = usePaymentSubmission();\n\n  useLayoutEffect(\n    () => register(path, submit, preflight, explainMissingMethod),\n    [register, path, submit, preflight, explainMissingMethod],\n  );\n}\n"],"mappings":";;;;AAkHA,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;;;;;;;;;;;;AAaA,SAAgB,6BACd,MACA,QACA,WACA,sBACM;CACN,MAAM,EAAE,aAAa,qBAAqB;CAE1C,sBACQ,SAAS,MAAM,QAAQ,WAAW,oBAAoB,GAC5D;EAAC;EAAU;EAAM;EAAQ;EAAW;CAAoB,CAC1D;AACF"}