@vtex/faststore 0.0.7 → 0.0.10

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

@@ -1 +1 @@
-{"version":3,"file":"use-payment-actions.js","names":[],"sources":["../../../src/sdk/payment/use-payment-actions.ts"],"sourcesContent":["'use client';\n\nimport { useMutation } from '@apollo/client/react';\nimport { defineActions } from '@vtex/fs-core';\nimport { useCallback, useMemo } from 'react';\nimport { loggableErrorName } from '../../utils/loggable-error-name.js';\nimport { CLIENT_PREFERENCES_UPDATE } from '../identity/operations.js';\nimport { PAYMENT_GATEWAY_USER_ERROR, postPaymentsToGateway, type SendPaymentsRequest } from './gateway.js';\nimport {\n  PAYMENT_BILLING_ADDRESS_UPDATE,\n  PAYMENT_GATEWAY_CALLBACK,\n  PAYMENT_INSTALLMENT_SELECT,\n  PAYMENT_METHOD_SELECT,\n  PAYMENT_NETWORK_ERROR_CODE,\n  PAYMENT_START_TRANSACTION,\n  type PaymentBillingAddressUpdateInput,\n  type PaymentMethodSelectInput,\n  type PaymentMoney,\n  type PaymentUserError,\n} from './operations.js';\n\n/**\n * The `payment` action namespace — the sanctioned client write surface for credit-card payment\n * (specs/payment-action-namespace.md; docs/features/credit-card/rfc.md § D12;\n * docs/storefront-core/adr-0010-actions-own-the-write-side.md).\n *\n * Six mutation-backed methods run the write model T3 shipped (`checkout/schema.graphql` § 11), except\n * `saveCard`, which reuses the already-shipped `clientPreferencesUpdate` document this package owns —\n * there is no `paymentSaveCard` mutation and T3 decided there must not be one. All six are\n * async/pessimistic: the handler awaits the mutation and only the server-confirmed payload changes the\n * cache. Each is stateless (no reactive vars, no module state), resolves its payload `userErrors` (empty\n * on success), and never throws for an expected outcome; an infrastructure failure (transport or an\n * upstream GraphQLError) is caught and collapsed to one synthetic `NETWORK_ERROR` userError with no\n * per-code branching, mirroring `useShippingActions`.\n *\n * `sendPayments` is the seventh method and the odd one: a **façade** (ADR-0010's sanctioned flavor,\n * alongside `notifications`) that posts card data from the browser straight to the payment gateway,\n * touching neither our GraphQL layer nor the normalized cache. It is catalogued like any other method —\n * per D12, hiding a write route with no read-back would cost discoverability without protecting\n * anything, and the compiler wants to *see* which components reference it. What is deliberately absent\n * from the catalog is the card data itself: no `payload` entry below names a card number, CVV, expiry,\n * or holder name, so there is no schema-bindable name for the editor or the agent to map a value onto\n * (RFC D13). The card reaches the handler as a runtime argument from the card-entry component's local\n * state (T7), and `gateway.ts` — which has no Apollo import — is the only module that touches it.\n */\n\n/**\n * Everything `usePlaceOrder` (T13) needs to assemble `PaymentGatewayTransaction`, minus the five\n * fields that come from the `Payment` read model. Every field is nullable because a payload carrying\n * `userErrors` nulls all of them (T18 Decision 4), so a complete descriptor is only guaranteed once\n * `userErrors` is empty *and* the payload passes the caller's completeness check.\n */\nexport type PaymentStartTransactionResult = Readonly<{\n  transactionId: string | null;\n  merchantName: string | null;\n  /** Gateway origin. Nullable, and never interpolated into a URL before `isTrustedGatewayOrigin`. */\n  gatewayUrl: string | null;\n  orderGroup: string | null;\n  userProfileId: string | null;\n  /** Display decimal. The gateway body's unit is `valueInCents`. */\n  value: PaymentMoney | null;\n  valueInCents: number | null;\n  referenceValueInCents: number | null;\n  userErrors: readonly PaymentUserError[];\n}>;\n\nexport type PaymentGatewayCallbackResult = Readonly<{\n  orderId: string | null;\n  userErrors: readonly PaymentUserError[];\n}>;\n\nexport type PaymentActions = Readonly<{\n  /** Select a payment method, optionally identifying a new card's BIN or a saved card's account. */\n  setMethod: (input: PaymentMethodSelectInput) => Promise<readonly PaymentUserError[]>;\n  /** Select an installment count for the current method. The response carries the recomputed cart total. */\n  setInstallments: (count: number) => Promise<readonly PaymentUserError[]>;\n  /** Persist the billing address, or fall back to the delivery address (`sameAsDelivery: true`). */\n  setBillingAddress: (input: PaymentBillingAddressUpdateInput) => Promise<readonly PaymentUserError[]>;\n  /**\n   * Record the data-storage consent a saved card requires, over the existing `clientPreferencesUpdate`.\n   * This does not by itself save the card: the save flag and label travel on `sendPayments`'s card\n   * argument (RFC D5's two halves). The boolean passes through unchanged — whether unchecking should\n   * revoke a consent an unrelated opt-in component may have granted is T10's decision, and its spec must\n   * state one (Gap 4 in specs/payment-action-namespace.md).\n   */\n  saveCard: (enabled: boolean) => Promise<readonly PaymentUserError[]>;\n  /** Open a VTEX transaction from the persisted selection. Resolves the payload the gateway call needs. */\n  startTransaction: () => Promise<PaymentStartTransactionResult>;\n  /** Finalize the transaction after the gateway accepted the card. */\n  gatewayCallback: (orderGroup: string) => Promise<PaymentGatewayCallbackResult>;\n  /**\n   * Façade: post the card straight to the payment gateway. Issues no GraphQL operation and writes\n   * nothing to the cache. Resolves one `GATEWAY_ERROR` userError when the gateway rejects the call.\n   */\n  sendPayments: (request: SendPaymentsRequest) => Promise<readonly PaymentUserError[]>;\n}>;\n\nconst NETWORK_ERROR: PaymentUserError = {\n  code: PAYMENT_NETWORK_ERROR_CODE,\n  message: 'Unable to complete the request. Please try again.',\n};\n\n/** Mirrors the resolver's own nulled-fields constant, so one added field is nulled in one place. */\nconst EMPTY_START_TRANSACTION = {\n  transactionId: null,\n  merchantName: null,\n  gatewayUrl: null,\n  orderGroup: null,\n  userProfileId: null,\n  value: null,\n  valueInCents: null,\n  referenceValueInCents: null,\n} as const;\n\n/**\n * The `payment` namespace hook. Registered with the first-party action registry via `paymentActions`\n * below; the compiler-emitted `PaymentActionProvider` calls it and threads the narrowed methods into\n * each consumer's `$actions.payment`. Writes persist purely through the normalized-cache merge of each\n * mutation response — no refetch, no imperative cache write.\n */\nexport function usePaymentActions(): PaymentActions {\n  const [methodSelectMutation] = useMutation(PAYMENT_METHOD_SELECT);\n  const [installmentSelectMutation] = useMutation(PAYMENT_INSTALLMENT_SELECT);\n  const [billingAddressMutation] = useMutation(PAYMENT_BILLING_ADDRESS_UPDATE);\n  const [preferencesMutation] = useMutation(CLIENT_PREFERENCES_UPDATE);\n  const [startTransactionMutation] = useMutation(PAYMENT_START_TRANSACTION);\n  const [gatewayCallbackMutation] = useMutation(PAYMENT_GATEWAY_CALLBACK);\n\n  const setMethod = useCallback<PaymentActions['setMethod']>(\n    async (input) => {\n      try {\n        const result = await methodSelectMutation({ variables: { input } });\n        return result.data?.paymentMethodSelect.userErrors ?? [];\n      } catch (error) {\n        // Log only the error name — the input carries the card's BIN, and a variable-coercion error's\n        // message echoes the offending value (`got invalid value … at \"input.bin\"`).\n        console.error('[payment.setMethod] paymentMethodSelect failed', loggableErrorName(error));\n        return [NETWORK_ERROR];\n      }\n    },\n    [methodSelectMutation],\n  );\n\n  const setInstallments = useCallback<PaymentActions['setInstallments']>(\n    async (count) => {\n      try {\n        const result = await installmentSelectMutation({ variables: { input: { count } } });\n        return result.data?.paymentInstallmentSelect.userErrors ?? [];\n      } catch (error) {\n        console.error('[payment.setInstallments] paymentInstallmentSelect failed', loggableErrorName(error));\n        return [NETWORK_ERROR];\n      }\n    },\n    [installmentSelectMutation],\n  );\n\n  const setBillingAddress = useCallback<PaymentActions['setBillingAddress']>(\n    async (input) => {\n      try {\n        const result = await billingAddressMutation({ variables: { input } });\n        return result.data?.paymentBillingAddressUpdate.userErrors ?? [];\n      } catch (error) {\n        // Log only the error name — the message can echo the submitted address (PII).\n        console.error('[payment.setBillingAddress] paymentBillingAddressUpdate failed', loggableErrorName(error));\n        return [NETWORK_ERROR];\n      }\n    },\n    [billingAddressMutation],\n  );\n\n  const saveCard = useCallback<PaymentActions['saveCard']>(\n    async (enabled) => {\n      try {\n        const result = await preferencesMutation({ variables: { input: { savePersonalData: enabled } } });\n        return result.data?.clientPreferencesUpdate?.userErrors ?? [];\n      } catch (error) {\n        console.error('[payment.saveCard] clientPreferencesUpdate failed', loggableErrorName(error));\n        return [NETWORK_ERROR];\n      }\n    },\n    [preferencesMutation],\n  );\n\n  const startTransaction = useCallback<PaymentActions['startTransaction']>(async () => {\n    try {\n      const result = await startTransactionMutation();\n      const payload = result.data?.paymentStartTransaction;\n      return {\n        transactionId: payload?.transactionId ?? null,\n        merchantName: payload?.merchantName ?? null,\n        gatewayUrl: payload?.gatewayUrl ?? null,\n        orderGroup: payload?.orderGroup ?? null,\n        userProfileId: payload?.userProfileId ?? null,\n        value: payload?.value ?? null,\n        valueInCents: payload?.valueInCents ?? null,\n        referenceValueInCents: payload?.referenceValueInCents ?? null,\n        userErrors: payload?.userErrors ?? [],\n      };\n    } catch (error) {\n      console.error('[payment.startTransaction] paymentStartTransaction failed', loggableErrorName(error));\n      return { ...EMPTY_START_TRANSACTION, userErrors: [NETWORK_ERROR] };\n    }\n  }, [startTransactionMutation]);\n\n  const gatewayCallback = useCallback<PaymentActions['gatewayCallback']>(\n    async (orderGroup) => {\n      try {\n        const result = await gatewayCallbackMutation({ variables: { input: { orderGroup } } });\n        const payload = result.data?.paymentGatewayCallback;\n        return { orderId: payload?.orderId ?? null, userErrors: payload?.userErrors ?? [] };\n      } catch (error) {\n        console.error('[payment.gatewayCallback] paymentGatewayCallback failed', loggableErrorName(error));\n        return { orderId: null, userErrors: [NETWORK_ERROR] };\n      }\n    },\n    [gatewayCallbackMutation],\n  );\n\n  const sendPayments = useCallback<PaymentActions['sendPayments']>(async (request) => {\n    try {\n      return await postPaymentsToGateway(request);\n    } catch (error) {\n      // Log the error NAME ONLY. The request carries a card number and CVV, and a thrown fetch error's\n      // message can echo the URL or the body — nothing on this path is ever serialized to a log.\n      console.error('[payment.sendPayments] gateway request failed', loggableErrorName(error));\n      return [PAYMENT_GATEWAY_USER_ERROR];\n    }\n  }, []);\n\n  return useMemo(\n    () => ({\n      setMethod,\n      setInstallments,\n      setBillingAddress,\n      saveCard,\n      startTransaction,\n      gatewayCallback,\n      sendPayments,\n    }),\n    [setMethod, setInstallments, setBillingAddress, saveCard, startTransaction, gatewayCallback, sendPayments],\n  );\n}\n\n/**\n * Declares the `payment` action namespace — the single source of truth for its method/payload metadata,\n * runtime provider, and `use` hook (mirrors `cartActions`, `shippingActions`). The native catalog\n * builder (`scripts/build-catalog.mjs`) statically reads this call to emit `actions.json`; at runtime\n * `PaymentActionProvider` calls `usePaymentActions` directly.\n *\n * `sendPayments`'s `payload` lists only the non-sensitive transaction descriptor's identifiers.\n * `ActionPayloadField` is the surface a schema-bindable name would come from, so the card fields'\n * absence here is the mechanical form of RFC D13: card number and CVV are never expressed as a declared\n * action payload. The `SendPaymentsRequest` type in `gateway.ts` is the source of truth for the real\n * call shape.\n */\nexport const paymentActions = defineActions({\n  namespace: 'payment',\n  description:\n    'Mutation-backed payment writes against the VTEX orderForm paymentData/invoiceData, plus a façade that posts card data directly to the payment gateway (never through our GraphQL layer or cache).',\n  provider: { name: 'PaymentActionProvider', importPath: '@vtex/faststore/internal/client' },\n  methods: {\n    setMethod: {\n      description:\n        'Select a payment method, optionally identifying a new card by BIN or a saved card by account (async/pessimistic). Resolves the payload userErrors.',\n      payload: [\n        { name: 'methodId', type: 'string' },\n        { name: 'bin', type: 'string', optional: true },\n        { name: 'accountId', type: 'string', optional: true },\n      ],\n    },\n    setInstallments: {\n      description:\n        'Select an installment count for the current method (async/pessimistic). The response recomputes the cart total with interest. Resolves the payload userErrors.',\n      payload: [{ name: 'count', type: 'number' }],\n    },\n    setBillingAddress: {\n      description:\n        'Persist the billing address, or fall back to the delivery address with sameAsDelivery (async/pessimistic). Resolves the payload userErrors.',\n      payload: [\n        { name: 'sameAsDelivery', type: 'boolean' },\n        { name: 'addressType', type: 'string', optional: true },\n        { name: 'postalCode', type: 'string', optional: true },\n        { name: 'country', type: 'string', optional: true },\n        { name: 'street', type: 'string', optional: true },\n        { name: 'number', type: 'string', optional: true },\n        { name: 'complement', type: 'string', optional: true },\n        { name: 'neighborhood', type: 'string', optional: true },\n        { name: 'city', type: 'string', optional: true },\n        { name: 'state', type: 'string', optional: true },\n        { name: 'reference', type: 'string', optional: true },\n      ],\n    },\n    saveCard: {\n      description:\n        'Record the data-storage consent a saved card requires, reusing the existing clientPreferencesUpdate write. Does not itself save the card — the save flag and label travel on sendPayments.',\n      payload: [{ name: 'enabled', type: 'boolean' }],\n    },\n    startTransaction: {\n      description:\n        'Open a VTEX transaction from the persisted payment selection. Takes no arguments; resolves the transaction identifiers the gateway call needs.',\n      payload: [],\n    },\n    gatewayCallback: {\n      description: 'Finalize the transaction after the gateway accepted the card. Resolves the payload userErrors.',\n      payload: [{ name: 'orderGroup', type: 'string' }],\n    },\n    sendPayments: {\n      description:\n        'Façade: post the card directly from the browser to the payment gateway. Issues no GraphQL operation and writes nothing to the cache. The card number and CVV are runtime-only arguments and are deliberately absent from this payload — they are never a bindable field (RFC D13).',\n      payload: [\n        { name: 'gatewayUrl', type: 'string' },\n        { name: 'transactionId', type: 'string' },\n        { name: 'merchantName', type: 'string' },\n        { name: 'orderGroup', type: 'string' },\n        { name: 'userProfileId', type: 'string' },\n      ],\n    },\n  },\n  use: usePaymentActions,\n});\n"],"mappings":"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"}
+{"version":3,"file":"use-payment-actions.js","names":[],"sources":["../../../src/sdk/payment/use-payment-actions.ts"],"sourcesContent":["'use client';\n\nimport { useMutation } from '@apollo/client/react';\nimport { defineActions } from '@vtex/fs-core';\nimport { useCallback, useMemo } from 'react';\nimport { loggableErrorName } from '../../utils/loggable-error-name.js';\nimport { CLIENT_PREFERENCES_UPDATE } from '../identity/operations.js';\nimport {\n  PAYMENT_GATEWAY_USER_ERROR,\n  type PaymentGatewayResult,\n  postPaymentsToGateway,\n  type SendPaymentsRequest,\n} from './gateway.js';\nimport {\n  PAYMENT_BILLING_ADDRESS_UPDATE,\n  PAYMENT_GATEWAY_CALLBACK,\n  PAYMENT_INSTALLMENT_SELECT,\n  PAYMENT_METHOD_SELECT,\n  PAYMENT_NETWORK_ERROR_CODE,\n  PAYMENT_START_TRANSACTION,\n  type PaymentBillingAddressUpdateInput,\n  type PaymentMethodSelectInput,\n  type PaymentMoney,\n  type PaymentUserError,\n} from './operations.js';\n\n/**\n * The `payment` action namespace — the sanctioned client write surface for credit-card payment\n * (specs/payment-action-namespace.md; docs/features/credit-card/rfc.md § D12;\n * docs/storefront-core/adr-0010-actions-own-the-write-side.md).\n *\n * Six mutation-backed methods run the write model T3 shipped (`checkout/schema.graphql` § 11), except\n * `saveCard`, which reuses the already-shipped `clientPreferencesUpdate` document this package owns —\n * there is no `paymentSaveCard` mutation and T3 decided there must not be one. All six are\n * async/pessimistic: the handler awaits the mutation and only the server-confirmed payload changes the\n * cache. Each is stateless (no reactive vars, no module state), resolves its payload `userErrors` (empty\n * on success), and never throws for an expected outcome; an infrastructure failure (transport or an\n * upstream GraphQLError) is caught and collapsed to one synthetic `NETWORK_ERROR` userError with no\n * per-code branching, mirroring `useShippingActions`.\n *\n * `sendPayments` is the seventh method and the odd one: a **façade** (ADR-0010's sanctioned flavor,\n * alongside `notifications`) that posts card data from the browser straight to the payment gateway,\n * touching neither our GraphQL layer nor the normalized cache. It is catalogued like any other method —\n * per D12, hiding a write route with no read-back would cost discoverability without protecting\n * anything, and the compiler wants to *see* which components reference it. What is deliberately absent\n * from the catalog is the card data itself: no `payload` entry below names a card number, CVV, expiry,\n * or holder name, so there is no schema-bindable name for the editor or the agent to map a value onto\n * (RFC D13). The card reaches the handler as a runtime argument from the card-entry component's local\n * state (T7), and `gateway.ts` — which has no Apollo import — is the only module that touches it.\n */\n\n/**\n * Everything `usePlaceOrder` (T13) needs to assemble `PaymentGatewayTransaction`, minus the five\n * fields that come from the `Payment` read model. Every field is nullable because a payload carrying\n * `userErrors` nulls all of them (T18 Decision 4), so a complete descriptor is only guaranteed once\n * `userErrors` is empty *and* the payload passes the caller's completeness check.\n */\nexport type PaymentStartTransactionResult = Readonly<{\n  transactionId: string | null;\n  merchantName: string | null;\n  /** Gateway origin. Nullable, and never interpolated into a URL before `isTrustedGatewayOrigin`. */\n  gatewayUrl: string | null;\n  orderGroup: string | null;\n  userProfileId: string | null;\n  /** Display decimal. The gateway body's unit is `valueInCents`. */\n  value: PaymentMoney | null;\n  valueInCents: number | null;\n  referenceValueInCents: number | null;\n  userErrors: readonly PaymentUserError[];\n}>;\n\nexport type PaymentGatewayCallbackResult = Readonly<{\n  orderId: string | null;\n  userErrors: readonly PaymentUserError[];\n}>;\n\nexport type PaymentActions = Readonly<{\n  /** Select a payment method, optionally identifying a new card's BIN or a saved card's account. */\n  setMethod: (input: PaymentMethodSelectInput) => Promise<readonly PaymentUserError[]>;\n  /** Select an installment count for the current method. The response carries the recomputed cart total. */\n  setInstallments: (count: number) => Promise<readonly PaymentUserError[]>;\n  /** Persist the billing address, or fall back to the delivery address (`sameAsDelivery: true`). */\n  setBillingAddress: (input: PaymentBillingAddressUpdateInput) => Promise<readonly PaymentUserError[]>;\n  /**\n   * Record the data-storage consent a saved card requires, over the existing `clientPreferencesUpdate`.\n   * This does not by itself save the card: the save flag and label travel on `sendPayments`'s card\n   * argument (RFC D5's two halves). The boolean passes through unchanged — whether unchecking should\n   * revoke a consent an unrelated opt-in component may have granted is T10's decision, and its spec must\n   * state one (Gap 4 in specs/payment-action-namespace.md).\n   */\n  saveCard: (enabled: boolean) => Promise<readonly PaymentUserError[]>;\n  /** Open a VTEX transaction from the persisted selection. Resolves the payload the gateway call needs. */\n  startTransaction: () => Promise<PaymentStartTransactionResult>;\n  /** Finalize the transaction after the gateway accepted the card. */\n  gatewayCallback: (orderGroup: string) => Promise<PaymentGatewayCallbackResult>;\n  /**\n   * Façade: post the card straight to the payment gateway. Issues no GraphQL operation and writes\n   * nothing to the cache. Never rejects: resolves `{ reachedGateway, userErrors }`, with one `GATEWAY_ERROR`\n   * userError when the gateway rejects the call or it could not be issued. `reachedGateway` is `false`\n   * only when no request was issued; every outcome it cannot classify is `true`.\n   */\n  sendPayments: (request: SendPaymentsRequest) => Promise<PaymentGatewayResult>;\n}>;\n\nconst NETWORK_ERROR: PaymentUserError = {\n  code: PAYMENT_NETWORK_ERROR_CODE,\n  message: 'Unable to complete the request. Please try again.',\n};\n\n/** Mirrors the resolver's own nulled-fields constant, so one added field is nulled in one place. */\nconst EMPTY_START_TRANSACTION = {\n  transactionId: null,\n  merchantName: null,\n  gatewayUrl: null,\n  orderGroup: null,\n  userProfileId: null,\n  value: null,\n  valueInCents: null,\n  referenceValueInCents: null,\n} as const;\n\n/**\n * The `payment` namespace hook. Registered with the first-party action registry via `paymentActions`\n * below; the compiler-emitted `PaymentActionProvider` calls it and threads the narrowed methods into\n * each consumer's `$actions.payment`. Writes persist purely through the normalized-cache merge of each\n * mutation response — no refetch, no imperative cache write.\n */\nexport function usePaymentActions(): PaymentActions {\n  const [methodSelectMutation] = useMutation(PAYMENT_METHOD_SELECT);\n  const [installmentSelectMutation] = useMutation(PAYMENT_INSTALLMENT_SELECT);\n  const [billingAddressMutation] = useMutation(PAYMENT_BILLING_ADDRESS_UPDATE);\n  const [preferencesMutation] = useMutation(CLIENT_PREFERENCES_UPDATE);\n  const [startTransactionMutation] = useMutation(PAYMENT_START_TRANSACTION);\n  const [gatewayCallbackMutation] = useMutation(PAYMENT_GATEWAY_CALLBACK);\n\n  const setMethod = useCallback<PaymentActions['setMethod']>(\n    async (input) => {\n      try {\n        const result = await methodSelectMutation({ variables: { input } });\n        return result.data?.paymentMethodSelect.userErrors ?? [];\n      } catch (error) {\n        // Log only the error name — the input carries the card's BIN, and a variable-coercion error's\n        // message echoes the offending value (`got invalid value … at \"input.bin\"`).\n        console.error('[payment.setMethod] paymentMethodSelect failed', loggableErrorName(error));\n        return [NETWORK_ERROR];\n      }\n    },\n    [methodSelectMutation],\n  );\n\n  const setInstallments = useCallback<PaymentActions['setInstallments']>(\n    async (count) => {\n      try {\n        const result = await installmentSelectMutation({ variables: { input: { count } } });\n        return result.data?.paymentInstallmentSelect.userErrors ?? [];\n      } catch (error) {\n        console.error('[payment.setInstallments] paymentInstallmentSelect failed', loggableErrorName(error));\n        return [NETWORK_ERROR];\n      }\n    },\n    [installmentSelectMutation],\n  );\n\n  const setBillingAddress = useCallback<PaymentActions['setBillingAddress']>(\n    async (input) => {\n      try {\n        const result = await billingAddressMutation({ variables: { input } });\n        return result.data?.paymentBillingAddressUpdate.userErrors ?? [];\n      } catch (error) {\n        // Log only the error name — the message can echo the submitted address (PII).\n        console.error('[payment.setBillingAddress] paymentBillingAddressUpdate failed', loggableErrorName(error));\n        return [NETWORK_ERROR];\n      }\n    },\n    [billingAddressMutation],\n  );\n\n  const saveCard = useCallback<PaymentActions['saveCard']>(\n    async (enabled) => {\n      try {\n        const result = await preferencesMutation({ variables: { input: { savePersonalData: enabled } } });\n        return result.data?.clientPreferencesUpdate?.userErrors ?? [];\n      } catch (error) {\n        console.error('[payment.saveCard] clientPreferencesUpdate failed', loggableErrorName(error));\n        return [NETWORK_ERROR];\n      }\n    },\n    [preferencesMutation],\n  );\n\n  const startTransaction = useCallback<PaymentActions['startTransaction']>(async () => {\n    try {\n      const result = await startTransactionMutation();\n      const payload = result.data?.paymentStartTransaction;\n      return {\n        transactionId: payload?.transactionId ?? null,\n        merchantName: payload?.merchantName ?? null,\n        gatewayUrl: payload?.gatewayUrl ?? null,\n        orderGroup: payload?.orderGroup ?? null,\n        userProfileId: payload?.userProfileId ?? null,\n        value: payload?.value ?? null,\n        valueInCents: payload?.valueInCents ?? null,\n        referenceValueInCents: payload?.referenceValueInCents ?? null,\n        userErrors: payload?.userErrors ?? [],\n      };\n    } catch (error) {\n      console.error('[payment.startTransaction] paymentStartTransaction failed', loggableErrorName(error));\n      return { ...EMPTY_START_TRANSACTION, userErrors: [NETWORK_ERROR] };\n    }\n  }, [startTransactionMutation]);\n\n  const gatewayCallback = useCallback<PaymentActions['gatewayCallback']>(\n    async (orderGroup) => {\n      try {\n        const result = await gatewayCallbackMutation({ variables: { input: { orderGroup } } });\n        const payload = result.data?.paymentGatewayCallback;\n        return { orderId: payload?.orderId ?? null, userErrors: payload?.userErrors ?? [] };\n      } catch (error) {\n        console.error('[payment.gatewayCallback] paymentGatewayCallback failed', loggableErrorName(error));\n        return { orderId: null, userErrors: [NETWORK_ERROR] };\n      }\n    },\n    [gatewayCallbackMutation],\n  );\n\n  const sendPayments = useCallback<PaymentActions['sendPayments']>(async (request) => {\n    try {\n      return await postPaymentsToGateway(request);\n    } catch (error) {\n      // Log the error NAME ONLY. The request carries a card number and CVV, and a thrown fetch error's\n      // message can echo the URL or the body — nothing on this path is ever serialized to a log.\n      console.error('[payment.sendPayments] gateway request failed', loggableErrorName(error));\n      // A rejected request is unclassified — it may have been processed — so it counts as reached.\n      return { reachedGateway: true, userErrors: [PAYMENT_GATEWAY_USER_ERROR] };\n    }\n  }, []);\n\n  return useMemo(\n    () => ({\n      setMethod,\n      setInstallments,\n      setBillingAddress,\n      saveCard,\n      startTransaction,\n      gatewayCallback,\n      sendPayments,\n    }),\n    [setMethod, setInstallments, setBillingAddress, saveCard, startTransaction, gatewayCallback, sendPayments],\n  );\n}\n\n/**\n * Declares the `payment` action namespace — the single source of truth for its method/payload metadata,\n * runtime provider, and `use` hook (mirrors `cartActions`, `shippingActions`). The native catalog\n * builder (`scripts/build-catalog.mjs`) statically reads this call to emit `actions.json`; at runtime\n * `PaymentActionProvider` calls `usePaymentActions` directly.\n *\n * `sendPayments`'s `payload` lists only the non-sensitive transaction descriptor's identifiers.\n * `ActionPayloadField` is the surface a schema-bindable name would come from, so the card fields'\n * absence here is the mechanical form of RFC D13: card number and CVV are never expressed as a declared\n * action payload. The `SendPaymentsRequest` type in `gateway.ts` is the source of truth for the real\n * call shape.\n */\nexport const paymentActions = defineActions({\n  namespace: 'payment',\n  description:\n    'Mutation-backed payment writes against the VTEX orderForm paymentData/invoiceData, plus a façade that posts card data directly to the payment gateway (never through our GraphQL layer or cache).',\n  provider: { name: 'PaymentActionProvider', importPath: '@vtex/faststore/internal/client' },\n  methods: {\n    setMethod: {\n      description:\n        'Select a payment method, optionally identifying a new card by BIN or a saved card by account (async/pessimistic). Resolves the payload userErrors.',\n      payload: [\n        { name: 'methodId', type: 'string' },\n        { name: 'bin', type: 'string', optional: true },\n        { name: 'accountId', type: 'string', optional: true },\n      ],\n    },\n    setInstallments: {\n      description:\n        'Select an installment count for the current method (async/pessimistic). The response recomputes the cart total with interest. Resolves the payload userErrors.',\n      payload: [{ name: 'count', type: 'number' }],\n    },\n    setBillingAddress: {\n      description:\n        'Persist the billing address, or fall back to the delivery address with sameAsDelivery (async/pessimistic). Resolves the payload userErrors.',\n      payload: [\n        { name: 'sameAsDelivery', type: 'boolean' },\n        { name: 'addressType', type: 'string', optional: true },\n        { name: 'postalCode', type: 'string', optional: true },\n        { name: 'country', type: 'string', optional: true },\n        { name: 'street', type: 'string', optional: true },\n        { name: 'number', type: 'string', optional: true },\n        { name: 'complement', type: 'string', optional: true },\n        { name: 'neighborhood', type: 'string', optional: true },\n        { name: 'city', type: 'string', optional: true },\n        { name: 'state', type: 'string', optional: true },\n        { name: 'reference', type: 'string', optional: true },\n      ],\n    },\n    saveCard: {\n      description:\n        'Record the data-storage consent a saved card requires, reusing the existing clientPreferencesUpdate write. Does not itself save the card — the save flag and label travel on sendPayments.',\n      payload: [{ name: 'enabled', type: 'boolean' }],\n    },\n    startTransaction: {\n      description:\n        'Open a VTEX transaction from the persisted payment selection. Takes no arguments; resolves the transaction identifiers the gateway call needs.',\n      payload: [],\n    },\n    gatewayCallback: {\n      description: 'Finalize the transaction after the gateway accepted the card. Resolves the payload userErrors.',\n      payload: [{ name: 'orderGroup', type: 'string' }],\n    },\n    sendPayments: {\n      description:\n        'Façade: post the card directly from the browser to the payment gateway. Issues no GraphQL operation and writes nothing to the cache. Resolves { reachedGateway, userErrors }: reachedGateway is false only when no request was issued. The card number and CVV are runtime-only arguments and are deliberately absent from this payload — they are never a bindable field (RFC D13).',\n      payload: [\n        { name: 'gatewayUrl', type: 'string' },\n        { name: 'transactionId', type: 'string' },\n        { name: 'merchantName', type: 'string' },\n        { name: 'orderGroup', type: 'string' },\n        { name: 'userProfileId', type: 'string' },\n      ],\n    },\n  },\n  use: usePaymentActions,\n});\n"],"mappings":"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"}

package/dist/sdk/payment/use-place-order.d.ts

@@ -29,12 +29,15 @@ export type PlaceOrderData = {
 export type PlaceOrderAttemptPhase =
 /** `startTransaction` issued or resolved. Nothing has been paid. */
 'opening' |
-/** A leg refused before the card left the browser. A fresh full attempt is legal. */
+/** A leg refused before the card left the browser, or `gatewayCallback` answered with a server-coded
+ *  error the retry rule frees (T110; dormant today, the server sends no such code yet). A fresh full
+ *  attempt is legal. */
 'refused' |
 /** The continuation resolved with no userErrors — the card reached the gateway. */
 'sent' |
-/** The card's fate is unknown: the continuation threw, or the POST was aborted, or a finalization
- *  did not resolve. Treated exactly like `sent`. */
+/** The card's fate is unknown: the continuation threw, the POST was aborted, or a finalization got no
+ *  answer or only a locked code (`REDIRECT_REQUIRED`, `MISSING_TRANSACTION_COOKIES`). Resume-only.
+ *  Treated exactly like `sent`. */
 'unresolved' |
 /** `gatewayCallback` is in flight for this attempt's order group. */
 'finalizing' |