@vtex/faststore 0.0.4 → 0.0.6

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

@@ -0,0 +1,276 @@
+"use client";
+import { defineActions } from "../../core/dist/actions/registry.js";
+import "../../core/dist/index.js";
+import { PAYMENT_BILLING_ADDRESS_UPDATE, PAYMENT_GATEWAY_CALLBACK, PAYMENT_INSTALLMENT_SELECT, PAYMENT_METHOD_SELECT, PAYMENT_NETWORK_ERROR_CODE, PAYMENT_START_TRANSACTION } from "./operations.js";
+import { loggableErrorName } from "../../utils/loggable-error-name.js";
+import { CLIENT_PREFERENCES_UPDATE } from "../identity/operations.js";
+import { PAYMENT_GATEWAY_USER_ERROR, postPaymentsToGateway } from "./gateway.js";
+import { useMutation } from "@apollo/client/react";
+import { useCallback, useMemo } from "react";
+//#region src/sdk/payment/use-payment-actions.ts
+const NETWORK_ERROR = {
+	code: PAYMENT_NETWORK_ERROR_CODE,
+	message: "Unable to complete the request. Please try again."
+};
+/** Mirrors the resolver's own nulled-fields constant, so one added field is nulled in one place. */
+const EMPTY_START_TRANSACTION = {
+	transactionId: null,
+	merchantName: null,
+	gatewayUrl: null,
+	orderGroup: null,
+	userProfileId: null,
+	value: null,
+	valueInCents: null,
+	referenceValueInCents: null
+};
+/**
+* The `payment` namespace hook. Registered with the first-party action registry via `paymentActions`
+* below; the compiler-emitted `PaymentActionProvider` calls it and threads the narrowed methods into
+* each consumer's `$actions.payment`. Writes persist purely through the normalized-cache merge of each
+* mutation response — no refetch, no imperative cache write.
+*/
+function usePaymentActions() {
+	const [methodSelectMutation] = useMutation(PAYMENT_METHOD_SELECT);
+	const [installmentSelectMutation] = useMutation(PAYMENT_INSTALLMENT_SELECT);
+	const [billingAddressMutation] = useMutation(PAYMENT_BILLING_ADDRESS_UPDATE);
+	const [preferencesMutation] = useMutation(CLIENT_PREFERENCES_UPDATE);
+	const [startTransactionMutation] = useMutation(PAYMENT_START_TRANSACTION);
+	const [gatewayCallbackMutation] = useMutation(PAYMENT_GATEWAY_CALLBACK);
+	const setMethod = useCallback(async (input) => {
+		try {
+			return (await methodSelectMutation({ variables: { input } })).data?.paymentMethodSelect.userErrors ?? [];
+		} catch (error) {
+			console.error("[payment.setMethod] paymentMethodSelect failed", loggableErrorName(error));
+			return [NETWORK_ERROR];
+		}
+	}, [methodSelectMutation]);
+	const setInstallments = useCallback(async (count) => {
+		try {
+			return (await installmentSelectMutation({ variables: { input: { count } } })).data?.paymentInstallmentSelect.userErrors ?? [];
+		} catch (error) {
+			console.error("[payment.setInstallments] paymentInstallmentSelect failed", loggableErrorName(error));
+			return [NETWORK_ERROR];
+		}
+	}, [installmentSelectMutation]);
+	const setBillingAddress = useCallback(async (input) => {
+		try {
+			return (await billingAddressMutation({ variables: { input } })).data?.paymentBillingAddressUpdate.userErrors ?? [];
+		} catch (error) {
+			console.error("[payment.setBillingAddress] paymentBillingAddressUpdate failed", loggableErrorName(error));
+			return [NETWORK_ERROR];
+		}
+	}, [billingAddressMutation]);
+	const saveCard = useCallback(async (enabled) => {
+		try {
+			return (await preferencesMutation({ variables: { input: { savePersonalData: enabled } } })).data?.clientPreferencesUpdate?.userErrors ?? [];
+		} catch (error) {
+			console.error("[payment.saveCard] clientPreferencesUpdate failed", loggableErrorName(error));
+			return [NETWORK_ERROR];
+		}
+	}, [preferencesMutation]);
+	const startTransaction = useCallback(async () => {
+		try {
+			const payload = (await startTransactionMutation()).data?.paymentStartTransaction;
+			return {
+				transactionId: payload?.transactionId ?? null,
+				merchantName: payload?.merchantName ?? null,
+				gatewayUrl: payload?.gatewayUrl ?? null,
+				orderGroup: payload?.orderGroup ?? null,
+				userProfileId: payload?.userProfileId ?? null,
+				value: payload?.value ?? null,
+				valueInCents: payload?.valueInCents ?? null,
+				referenceValueInCents: payload?.referenceValueInCents ?? null,
+				userErrors: payload?.userErrors ?? []
+			};
+		} catch (error) {
+			console.error("[payment.startTransaction] paymentStartTransaction failed", loggableErrorName(error));
+			return {
+				...EMPTY_START_TRANSACTION,
+				userErrors: [NETWORK_ERROR]
+			};
+		}
+	}, [startTransactionMutation]);
+	const gatewayCallback = useCallback(async (orderGroup) => {
+		try {
+			const payload = (await gatewayCallbackMutation({ variables: { input: { orderGroup } } })).data?.paymentGatewayCallback;
+			return {
+				orderId: payload?.orderId ?? null,
+				userErrors: payload?.userErrors ?? []
+			};
+		} catch (error) {
+			console.error("[payment.gatewayCallback] paymentGatewayCallback failed", loggableErrorName(error));
+			return {
+				orderId: null,
+				userErrors: [NETWORK_ERROR]
+			};
+		}
+	}, [gatewayCallbackMutation]);
+	const sendPayments = useCallback(async (request) => {
+		try {
+			return await postPaymentsToGateway(request);
+		} catch (error) {
+			console.error("[payment.sendPayments] gateway request failed", loggableErrorName(error));
+			return [PAYMENT_GATEWAY_USER_ERROR];
+		}
+	}, []);
+	return useMemo(() => ({
+		setMethod,
+		setInstallments,
+		setBillingAddress,
+		saveCard,
+		startTransaction,
+		gatewayCallback,
+		sendPayments
+	}), [
+		setMethod,
+		setInstallments,
+		setBillingAddress,
+		saveCard,
+		startTransaction,
+		gatewayCallback,
+		sendPayments
+	]);
+}
+defineActions({
+	namespace: "payment",
+	description: "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).",
+	provider: {
+		name: "PaymentActionProvider",
+		importPath: "@vtex/faststore/internal/client"
+	},
+	methods: {
+		setMethod: {
+			description: "Select a payment method, optionally identifying a new card by BIN or a saved card by account (async/pessimistic). Resolves the payload userErrors.",
+			payload: [
+				{
+					name: "methodId",
+					type: "string"
+				},
+				{
+					name: "bin",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "accountId",
+					type: "string",
+					optional: true
+				}
+			]
+		},
+		setInstallments: {
+			description: "Select an installment count for the current method (async/pessimistic). The response recomputes the cart total with interest. Resolves the payload userErrors.",
+			payload: [{
+				name: "count",
+				type: "number"
+			}]
+		},
+		setBillingAddress: {
+			description: "Persist the billing address, or fall back to the delivery address with sameAsDelivery (async/pessimistic). Resolves the payload userErrors.",
+			payload: [
+				{
+					name: "sameAsDelivery",
+					type: "boolean"
+				},
+				{
+					name: "addressType",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "postalCode",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "country",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "street",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "number",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "complement",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "neighborhood",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "city",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "state",
+					type: "string",
+					optional: true
+				},
+				{
+					name: "reference",
+					type: "string",
+					optional: true
+				}
+			]
+		},
+		saveCard: {
+			description: "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.",
+			payload: [{
+				name: "enabled",
+				type: "boolean"
+			}]
+		},
+		startTransaction: {
+			description: "Open a VTEX transaction from the persisted payment selection. Takes no arguments; resolves the transaction identifiers the gateway call needs.",
+			payload: []
+		},
+		gatewayCallback: {
+			description: "Finalize the transaction after the gateway accepted the card. Resolves the payload userErrors.",
+			payload: [{
+				name: "orderGroup",
+				type: "string"
+			}]
+		},
+		sendPayments: {
+			description: "Façade: post the card directly from the browser to the payment gateway. Issues no GraphQL operation and writes nothing to the cache. The card number and CVV are runtime-only arguments and are deliberately absent from this payload — they are never a bindable field (RFC D13).",
+			payload: [
+				{
+					name: "gatewayUrl",
+					type: "string"
+				},
+				{
+					name: "transactionId",
+					type: "string"
+				},
+				{
+					name: "merchantName",
+					type: "string"
+				},
+				{
+					name: "orderGroup",
+					type: "string"
+				},
+				{
+					name: "userProfileId",
+					type: "string"
+				}
+			]
+		}
+	},
+	use: usePaymentActions
+});
+//#endregion
+export { usePaymentActions };
+
+//# sourceMappingURL=use-payment-actions.js.map

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

@@ -0,0 +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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"}

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

@@ -0,0 +1,65 @@
+import { PaymentMoney } from "./operations.js";
+import "../actions/types.js";
+//#region src/sdk/payment/use-place-order.d.ts
+export type PlaceOrderInstallment = Readonly<{
+  count: number;
+  /** Per-installment amount, as a display decimal. The gateway's unit is minor units. */
+  value: PaymentMoney;
+  interestRate: number;
+}>;
+export type PlaceOrderMethod = Readonly<{
+  id: string;
+  groupName: string;
+}>;
+/**
+ * The `Payment` slice T14's fragment forwards (arity-1, ADR-0015) — the same convention as
+ * `PaymentSectionData`. These five values are the part of the descriptor `paymentStartTransaction`
+ * does not carry: T18 deliberately did not re-project the read model onto a write payload.
+ */
+export type PlaceOrderData = {
+  selectedMethodId?: string | null;
+  selectedInstallment?: PlaceOrderInstallment | null;
+  methods?: readonly PlaceOrderMethod[];
+} | null;
+/**
+ * How far an order attempt got. The phase, not an error code, is what says whether money may already
+ * have moved — an aborted card POST and a refused transaction both surface as the same userError, and
+ * only this distinguishes them.
+ */
+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. */
+'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`. */
+'unresolved' |
+/** `gatewayCallback` is in flight for this attempt's order group. */
+'finalizing' |
+/** `gatewayCallback` resolved with no userErrors. Terminal. */
+'settled';
+export type PlaceOrderAttempt = Readonly<{
+  /** Identity that outlives any one mount. Not `useId()` — that is per-instance and resets. */
+  attemptId: string;
+  phase: PlaceOrderAttemptPhase;
+  /** Resolved by `startTransaction`; the only key a resume needs. Null before `opening` settles. */
+  orderGroup: string | null;
+  /**
+   * Resolved by `gatewayCallback`. Not an independent identifier: the resolver returns
+   * `orderId: input.orderGroup` (`checkout/index.ts:1965`), echoing the argument back, because the
+   * upstream success response body is discarded. So `orderId === orderGroup` on every success today.
+   */
+  orderId: string | null;
+}>;
+/**
+ * Fix pass (High finding, race #2): widened past a plain value so a write can be made conditional on
+ * whatever the shared attempt actually is *at write time* — the primitive `useState` already exposes
+ * this (its setter has always accepted an updater function; only this package's own declared type
+ * stopped a caller from using that form). A plain value remains valid; every existing caller that
+ * never needed the guard is unaffected.
+ */
+export type SetPlaceOrderAttempt = (update: PlaceOrderAttempt | null | ((prev: PlaceOrderAttempt | null) => PlaceOrderAttempt | null)) => void;
+//#endregion
+//# sourceMappingURL=use-place-order.d.ts.map