@vtex/faststore 0.0.4 → 0.0.6

package/dist/sdk/payment/use-place-order.js

@@ -0,0 +1,640 @@
+"use client";
+import { usePaymentSubmission } from "./submission-registry.js";
+import { PAYMENT_NETWORK_ERROR_CODE } from "./operations.js";
+import { loggableErrorName } from "../../utils/loggable-error-name.js";
+import { isTrustedGatewayOrigin } from "./gateway-origin.js";
+import { useCallback, useMemo, useRef, useState } from "react";
+//#region src/sdk/payment/use-place-order.ts
+/**
+* The place-order orchestration (specs/use-place-order.md, T13; docs/features/credit-card/rfc.md
+* § D9) — the PCI-critical core of the credit-card feature, and the only module that knows placing an
+* order is three calls rather than one mutation.
+*
+* **This hook never holds card data.** It resolves an opaque continuation from the submission channel
+* by the shopper's entry path and invokes it between the two backend legs; the card stays in the
+* holder's closure (T7 for a new card, T12 for a saved one), which calls
+* `$actions.payment.sendPayments` itself. So the actions this hook needs are `startTransaction`,
+* `gatewayCallback`, and `analytics.track` — never the gateway façade. Two tests assert the boundary
+* against this file's own source text: no card field is named in code, and the single import from
+* `./gateway.js` is the transaction descriptor's type.
+*
+* The order of the pre-flight is load-bearing, not stylistic. The path, the continuation, and the
+* selected method are all resolved *before* `startTransaction` runs, because a transaction that is
+* opened and then cannot be completed is dangling state on the shopper's order form.
+*
+* v1 is the direct-API mode: the gateway leg resolves inline and the shopper stays on the page. The
+* redirect mode — an external navigation with a resume-on-callback route, and with it 3D Secure — is
+* phase 2, which is why no `callbackUrl` reaches the descriptor.
+*
+* Every failure resolves as `userErrors`; nothing here throws for an expected outcome, so the CTA
+* (T14) renders one error path. Its one per-code branch is PLACE_ORDER_UNCONFIRMED, a pending outcome
+* it shows as a status rather than an error (T176).
+*/
+/** No entry path chosen, or no holder registered for the one that was. */
+const PAYMENT_MISSING_SUBMISSION_CODE = "MISSING_PAYMENT_SUBMISSION";
+/**
+* No payment method selected. Reuses `PaymentStartTransactionErrorCode`'s own value for the same
+* state, so a consumer matches one code whichever side detected it.
+*/
+const PAYMENT_MISSING_METHOD_CODE = "MISSING_PAYMENT_METHOD_SELECTION";
+/**
+* The transaction opened but cannot be paid — an incomplete payload, or an origin this client will
+* not post a card to. Reuses the server's code for the same meaning (T18 Decision 5).
+*/
+const PAYMENT_INVALID_TRANSACTION_CODE = "INVALID_TRANSACTION_DATA";
+/**
+* The attempt's own sequence is still running — opened or finalizing, not yet settled. Not a
+* refusal: nothing failed, the record just belongs to a sequence this caller did not start.
+*/
+const PLACE_ORDER_IN_FLIGHT_CODE = "PLACE_ORDER_IN_FLIGHT";
+/**
+* The gatewayCallback leg ran after the gateway accepted the card POST, and this client could not confirm
+* its outcome — the payment may or may not have been authorized. Not a refusal (T176).
+*/
+const PLACE_ORDER_UNCONFIRMED_CODE = "PLACE_ORDER_UNCONFIRMED";
+const MISSING_SUBMISSION_ERROR = {
+	code: PAYMENT_MISSING_SUBMISSION_CODE,
+	message: "Enter your payment details before placing the order."
+};
+const MISSING_METHOD_ERROR = {
+	code: PAYMENT_MISSING_METHOD_CODE,
+	message: "Choose a payment method before placing the order."
+};
+const INVALID_TRANSACTION_ERROR = {
+	code: PAYMENT_INVALID_TRANSACTION_CODE,
+	message: "Unable to start the payment. Please try again."
+};
+const PLACE_ORDER_IN_FLIGHT_ERROR = {
+	code: PLACE_ORDER_IN_FLIGHT_CODE,
+	message: "This order is already being placed. Please wait."
+};
+/**
+* Worded as a pending state, never a failure: it must not tell the shopper to try again (FR-1).
+* `PlaceOrder`'s `unconfirmedMessage` schema default repeats this text verbatim.
+*/
+const PLACE_ORDER_UNCONFIRMED_ERROR = {
+	code: PLACE_ORDER_UNCONFIRMED_CODE,
+	message: "We could not confirm your order yet. Your payment may still be processing, so please do not pay again."
+};
+/** Mirrors `usePaymentActions`' own infrastructure-failure userError, which that module keeps private. */
+const NETWORK_ERROR = {
+	code: PAYMENT_NETWORK_ERROR_CODE,
+	message: "Unable to complete the request. Please try again."
+};
+/** Identifiers, a host, and amounts — nothing here is sensitive, so naming them in a log is safe. */
+function missingTransactionFields(payload) {
+	return Object.entries({
+		transactionId: payload.transactionId,
+		merchantName: payload.merchantName,
+		orderGroup: payload.orderGroup,
+		value: payload.value,
+		valueInCents: payload.valueInCents,
+		referenceValueInCents: payload.referenceValueInCents
+	}).filter(([, field]) => field === null).map(([name]) => name);
+}
+/**
+* Narrows a payload that reported no userErrors, or refuses it. The origin is checked first and
+* separately: it is the field that decides where a card is sent, and a refusal here happens before
+* any holder is asked to assemble one.
+*/
+function settleTransaction(payload) {
+	if (!isTrustedGatewayOrigin(payload.gatewayUrl)) {
+		console.error("[payment.placeOrder] the opened transaction carries no trusted https gateway origin");
+		return null;
+	}
+	const { transactionId, merchantName, orderGroup, userProfileId, value, valueInCents, referenceValueInCents } = payload;
+	if (transactionId === null || merchantName === null || orderGroup === null || value === null || valueInCents === null || referenceValueInCents === null) {
+		console.error("[payment.placeOrder] the opened transaction payload is incomplete", missingTransactionFields(payload).join(", "));
+		return null;
+	}
+	return {
+		gatewayUrl: payload.gatewayUrl,
+		transactionId,
+		merchantName,
+		orderGroup,
+		userProfileId,
+		value,
+		valueInCents,
+		referenceValueInCents
+	};
+}
+/**
+* The one derived amount on the descriptor. VTEX's `payments[0]` carries no per-installment minor-unit
+* value, so T18 could not expose one and the conversion stays here — rounded, because
+* `19.99 * 100 === 1998.9999999999998`. `Number()` is not redundant: the components codegen maps the
+* `Decimal` scalar to `number` while the resolver serializes it as a string (see the spec's Open items).
+*/
+function toMinorUnits(amount) {
+	return Math.round(Number(amount) * 100);
+}
+/**
+* The one call into holder-owned code. A holder's continuation is specified to resolve `userErrors` —
+* `sendPayments` already collapses every gateway outcome to one — so a throw means its contract broke.
+* Only a sanitised error *name* is logged (T160): the closure that threw holds the card, and a message
+* or stack could echo it — and so, unsanitised, could `.name` itself, since it is a writable own
+* property. See `loggableErrorName()`.
+*/
+async function invokeSubmission(submit, transaction) {
+	try {
+		const result = await submit(transaction);
+		if (result == null) {
+			console.error("[payment.placeOrder] the registered submission resolved with no result");
+			return [NETWORK_ERROR];
+		}
+		return result;
+	} catch (error) {
+		console.error("[payment.placeOrder] the registered submission threw", loggableErrorName(error));
+		return [NETWORK_ERROR];
+	}
+}
+/**
+* The pre-flight counterpart of `invokeSubmission`, and it inherits that function's one rule: the
+* closure that throws holds the card, so only a sanitised error *name* is logged (T160) — never a
+* message, a stack, or the raw writable `.name` property. See `loggableErrorName()`.
+*/
+function runPreflight(check) {
+	try {
+		return check();
+	} catch (error) {
+		console.error("[payment.placeOrder] the registered pre-flight threw", loggableErrorName(error));
+		return [NETWORK_ERROR];
+	}
+}
+/**
+* The `startTransaction` counterpart of `invokeSubmission`/`runPreflight` (fix pass, Medium finding):
+* before this, `run()` awaited `startTransaction()` directly, so a **rejection** — as opposed to a
+* resolved payload carrying `userErrors` — escaped past every one of `run()`'s own outcome branches
+* and `settleSequence`'s rejection handler never touches the attempt record, leaving it stuck at
+* `opening` for the payment root's lifetime. `opening` is the one phase `placeOrder()` treats as
+* "already running" with no failure exit, so every later click resolves `{ orderId: null, userErrors:
+* [] }` without running anything — a false "Order placed successfully." with the CTA disabled forever.
+* `usePlaceOrder` is exported public API and `$actions` is compiler-injected and pluggable, so a
+* provider that rejects here is reachable, not hypothetical. Collapsing the rejection to a resolved
+* payload with one `userErrors` entry means `run()`'s own existing `payload.userErrors.length > 0`
+* branch is what catches it — the same `refused` outcome a server-reported refusal already gets,
+* correct here too since nothing can have been paid before the transaction even opened.
+*
+* T156 fold: the result is destructured inside this `try`, not returned as `await startTransaction()`
+* untouched — a provider resolving `undefined` used to throw at the caller's own
+* `payload.userErrors.length` read, past this function's own `catch`, latching the attempt at
+* `opening` exactly like the rejection case above. Destructuring a nullish resolution throws here
+* instead, so it collapses the same way. Mirrors `invokeGatewayCallback`'s own reason for
+* destructuring, below.
+*
+* Fix pass (review F1/S1): `userErrors` is defaulted with `?? [NETWORK_ERROR]`, not `?? []` — a
+* *partial* payload (present, but missing `userErrors`, e.g. a provider whose GraphQL selection omits
+* the field) used to leave it `undefined`, reaching the caller's `payload.userErrors.length` read
+* (`:627`) and throwing past this function's own `catch`, latching the attempt at `opening` exactly
+* like the cases already fixed. `userErrors` is this result's only signal of whether anything actually
+* went wrong, so a payload that omits it defaults to a *failure*, mirroring a rejection — defaulting to
+* `[]` instead would settle the attempt on a payload this function never actually saw. (The in-repo
+* default provider's own `payload?.userErrors ?? []`, `use-payment-actions.ts:202`, defaults to `[]`
+* only because there `payload` itself — not just the field — is what may be missing.)
+*/
+async function invokeStartTransaction(startTransaction) {
+	try {
+		const { transactionId, merchantName, gatewayUrl, orderGroup, userProfileId, value, valueInCents, referenceValueInCents, userErrors } = await startTransaction();
+		if (userErrors == null) console.error("[payment.placeOrder] startTransaction resolved with no userErrors", orderGroup);
+		return {
+			transactionId,
+			merchantName,
+			gatewayUrl,
+			orderGroup,
+			userProfileId,
+			value,
+			valueInCents,
+			referenceValueInCents,
+			userErrors: userErrors ?? [NETWORK_ERROR]
+		};
+	} catch (error) {
+		console.error("[payment.placeOrder] startTransaction threw", loggableErrorName(error));
+		return {
+			transactionId: null,
+			merchantName: null,
+			gatewayUrl: null,
+			orderGroup: null,
+			userProfileId: null,
+			value: null,
+			valueInCents: null,
+			referenceValueInCents: null,
+			userErrors: [NETWORK_ERROR]
+		};
+	}
+}
+/**
+* The `gatewayCallback` counterpart of `invokeStartTransaction` above (T156, PR #756 review R-004):
+* before this, both call sites below awaited `gatewayCallback` directly, so a **rejection**
+* escaped past every outcome branch and `settleSequence`'s rejection handler never touches the attempt
+* record, leaving it stuck at `finalizing` for the payment root's lifetime — `placeOrder()` treats
+* `finalizing` exactly like `opening`, an already-running phase with no failure exit, so every later
+* click resolved `{ orderId: attempt.orderId, userErrors: [] }` without issuing anything.
+*
+* The destination is `unresolved`, never `refused` like `invokeStartTransaction`'s own collapse: this
+* leg only runs once the card already reached the gateway, so nothing here can pretend no money moved.
+* `unresolved` is exactly the phase `PlaceOrderAttemptPhase` already documents for this case, below,
+* and is already resumable.
+*
+* Three failure shapes collapse to the same `NETWORK_ERROR` result, logged distinctly (fix pass,
+* review F1/S1/F3): a **rejection**, caught below; a **nullish resolution** (`undefined`/`null`),
+* caught by the explicit check that follows rather than by letting a destructure throw, so it logs a
+* line of its own instead of printing identically to a rejection; and a **partial resolution** — an
+* object present but missing `userErrors`, e.g. a provider whose GraphQL selection omits the field —
+* defaulted with `?? [NETWORK_ERROR]`, not `?? []`. That last case used to return `{ orderId,
+* userErrors }` untouched, leaving `userErrors: undefined`, so the *caller's* `callback.userErrors.length`
+* read threw one call site away from where this wrapper's whole job is to stop exactly that. `[]` would
+* default a payload this function never actually saw to a clean success; `userErrors` is the only
+* signal of whether the callback settled anything, so omitting it means treating it as a failure.
+* Both failure branches log `orderGroup` and `attemptId` — neither is card data
+* (`missingTransactionFields`'s comment above), and this is the one point in the flow where money may
+* already have moved — but never the error's message, stack, or any call argument (FR-6).
+*
+* No `gatewayCallback` call may exist in this module outside this function (INV-2, asserted against
+* this file's own source text in use-place-order.test.tsx) — the two call sites below (`resume()` and
+* `run()`) call this and nothing else.
+*/
+async function invokeGatewayCallback(gatewayCallback, orderGroup, attemptId) {
+	let result;
+	try {
+		result = await gatewayCallback(orderGroup);
+	} catch (error) {
+		console.error("[payment.placeOrder] gatewayCallback threw", orderGroup, attemptId, loggableErrorName(error));
+		return {
+			orderId: null,
+			userErrors: [NETWORK_ERROR]
+		};
+	}
+	if (result == null) {
+		console.error("[payment.placeOrder] gatewayCallback resolved with no result", orderGroup, attemptId);
+		return {
+			orderId: null,
+			userErrors: [NETWORK_ERROR]
+		};
+	}
+	if (result.userErrors == null) console.error("[payment.placeOrder] gatewayCallback resolved with no userErrors", orderGroup, attemptId);
+	return {
+		orderId: result.orderId ?? null,
+		userErrors: result.userErrors ?? [NETWORK_ERROR]
+	};
+}
+/**
+* T176 (FR-2, FR-3): what the caller reads from a `gatewayCallback` that reported `userErrors`, on both
+* paths that issue it. The gateway already accepted the card POST by then, so a result made only of this
+* package's own collapse — `PAYMENT_NETWORK_ERROR_CODE`, which `usePaymentActions` and
+* `invokeGatewayCallback` resolve for every thrown, lost or shapeless response — says nothing about
+* whether VTEX processed the order. It becomes PLACE_ORDER_UNCONFIRMED rather than a "try again" that
+* invites a second payment. A code the server sent is an answer, and comes back unchanged (INV-10).
+*
+* Total, and never throws: a non-array, or an entry with no readable string `code`, carries no server
+* code, so it reads as unconfirmed too. A server code elsewhere in the same list still wins, whatever
+* order the entries come in.
+*/
+function reconcileCallbackUserErrors(userErrors) {
+	try {
+		if (!Array.isArray(userErrors)) return [PLACE_ORDER_UNCONFIRMED_ERROR];
+		if (userErrors.length === 0) return userErrors;
+		return userErrors.some((userError) => {
+			try {
+				const code = userError.code;
+				return typeof code === "string" && code !== "NETWORK_ERROR";
+			} catch {
+				return false;
+			}
+		}) ? userErrors : [PLACE_ORDER_UNCONFIRMED_ERROR];
+	} catch {
+		return [PLACE_ORDER_UNCONFIRMED_ERROR];
+	}
+}
+/**
+* `crypto.randomUUID()` is secure-context-only (fix pass, Low finding) — on a plain-HTTP preview or
+* staging origin the method does not exist on `crypto` at all, so calling it throws, and every click
+* collapses to a generic `NETWORK_ERROR` with no diagnostic. `localhost` is always a secure context,
+* so dev never reproduces it. Falls back to a timestamp+random string, which only needs to be unique
+* for one payment root's lifetime (the staleness guard below is its one reader) — not a real UUID.
+*/
+function generateAttemptId() {
+	if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
+	return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+/**
+* Fix pass (High finding, race #2): guards every write past an attempt's genesis against a stale,
+* out-of-order completion clobbering a newer outcome. `run()`/`resume()` mint one write *before* their
+* own first await (safe by construction — nothing can have superseded an attempt this call itself just
+* created) and one or more writes *after* an await, once `startTransaction`/the continuation/
+* `gatewayCallback` resolve. Because the writing closure keeps running after its own CTA unmounts
+* (NFR-3), that later write cannot assume the shared attempt is still the one it started with — a
+* remounted or sibling instance may have already resumed it to a newer phase in the meantime. Using
+* the setter's own functional-update form (`SetPlaceOrderAttempt`) checks against whatever the shared
+* attempt actually is *when the write is applied*, not the value this closure captured before its
+* await — mirrors `selectionToken`'s own precedent (`matter/payment/use-payment-method-selection.ts`)
+* for the identical shape of problem, keyed on the attempt's own id instead of a second counter.
+* `settled` is additionally excluded because INV-6 forbids any transition away from it.
+*/
+function writeAttemptIfCurrent(setAttempt, attemptId, next) {
+	setAttempt?.((prev) => prev !== null && prev.attemptId === attemptId && prev.phase !== "settled" ? next : prev);
+}
+/**
+* T29 (Decision 3, FR-3): the only path back into a `sent`/`unresolved` attempt — `gatewayCallback` is
+* the sole call it ever issues. Module scope, not a `useCallback` inside the hook (fix pass, Low
+* finding): the previous version of this doc comment claimed `startTransaction`, the submission
+* channel, and `PaymentGatewayTransaction` were "not in scope," so a careless future edit could not
+* make a resume re-pay — true at runtime today (verified by identifier sweep) but false as a
+* structural guarantee, since all three were merely unreferenced identifiers a nested closure could
+* still have read. Hoisting here makes the claim actually true: none of those three is even
+* *importable* from a bare module-level function that takes only `gatewayCallback`/`setAttempt`/
+* `setPlacing`/`current` as arguments — a resume is safe by construction, not by convention.
+*/
+async function resume(gatewayCallback, setAttempt, setPlacing, current) {
+	if (!gatewayCallback || current.orderGroup === null) {
+		console.error("[payment.placeOrder] cannot resume an attempt with no order group");
+		return {
+			orderId: null,
+			userErrors: [NETWORK_ERROR]
+		};
+	}
+	writeAttemptIfCurrent(setAttempt, current.attemptId, {
+		...current,
+		phase: "finalizing"
+	});
+	setPlacing(true);
+	const callback = await invokeGatewayCallback(gatewayCallback, current.orderGroup, current.attemptId);
+	const failed = callback.userErrors.length > 0;
+	const result = failed ? {
+		orderId: null,
+		userErrors: reconcileCallbackUserErrors(callback.userErrors)
+	} : {
+		orderId: callback.orderId,
+		userErrors: []
+	};
+	try {
+		writeAttemptIfCurrent(setAttempt, current.attemptId, failed ? {
+			...current,
+			phase: "unresolved"
+		} : {
+			...current,
+			phase: "settled",
+			orderId: callback.orderId
+		});
+	} catch (error) {
+		console.error("[payment.placeOrder] the resume record write threw", current.attemptId, loggableErrorName(error));
+	}
+	return result;
+}
+function usePlaceOrder({ $data, $actions, attempt, setAttempt, billingAddressDifferent, submitGate }) {
+	const { path, resolve, resolvePreflight } = usePaymentSubmission();
+	const [placing, setPlacing] = useState(false);
+	const [userErrors, setUserErrors] = useState([]);
+	const [orderId, setOrderId] = useState(null);
+	const inFlight = useRef(null);
+	const startTransaction = $actions?.payment?.startTransaction;
+	const gatewayCallback = $actions?.payment?.gatewayCallback;
+	const track = $actions?.analytics?.track;
+	const selectedMethodId = $data?.selectedMethodId ?? null;
+	const methods = $data?.methods;
+	const selectedInstallment = $data?.selectedInstallment ?? null;
+	const selectedMethod = useMemo(() => methods?.find((method) => method.id === selectedMethodId) ?? null, [methods, selectedMethodId]);
+	const run = useCallback(async () => {
+		if (!startTransaction || !gatewayCallback) {
+			console.error("[payment.placeOrder] the payment action namespace is not injected");
+			return {
+				orderId: null,
+				userErrors: [NETWORK_ERROR]
+			};
+		}
+		const submit = path === null ? null : resolve(path);
+		if (submit === null) {
+			console.error("[payment.placeOrder] no submission is registered for the entry path", path ?? "none");
+			return {
+				orderId: null,
+				userErrors: [MISSING_SUBMISSION_ERROR]
+			};
+		}
+		if (selectedMethod === null) {
+			console.error("[payment.placeOrder] no payment method is selected");
+			return {
+				orderId: null,
+				userErrors: [MISSING_METHOD_ERROR]
+			};
+		}
+		if (submitGate) {
+			console.error("[payment.placeOrder] a client-side gate refused the submission", submitGate.code);
+			return {
+				orderId: null,
+				userErrors: [submitGate]
+			};
+		}
+		const preflight = path === null ? null : resolvePreflight(path);
+		if (preflight) {
+			const refusals = runPreflight(preflight);
+			if (refusals.length > 0) {
+				console.error("[payment.placeOrder] the registered pre-flight refused the submission", refusals[0]?.code);
+				return {
+					orderId: null,
+					userErrors: refusals
+				};
+			}
+		}
+		let handedOver = false;
+		let settledOrderGroup = null;
+		let placedAttempt = null;
+		let outcome = null;
+		const attemptId = generateAttemptId();
+		setAttempt?.({
+			attemptId,
+			phase: "opening",
+			orderGroup: null,
+			orderId: null
+		});
+		try {
+			setPlacing(true);
+			const payload = await invokeStartTransaction(startTransaction);
+			if (payload.userErrors.length > 0) {
+				writeAttemptIfCurrent(setAttempt, attemptId, {
+					attemptId,
+					phase: "refused",
+					orderGroup: null,
+					orderId: null
+				});
+				return {
+					orderId: null,
+					userErrors: payload.userErrors
+				};
+			}
+			const settled = settleTransaction(payload);
+			if (settled === null) {
+				writeAttemptIfCurrent(setAttempt, attemptId, {
+					attemptId,
+					phase: "refused",
+					orderGroup: null,
+					orderId: null
+				});
+				return {
+					orderId: null,
+					userErrors: [INVALID_TRANSACTION_ERROR]
+				};
+			}
+			settledOrderGroup = settled.orderGroup;
+			writeAttemptIfCurrent(setAttempt, attemptId, {
+				attemptId,
+				phase: "opening",
+				orderGroup: settled.orderGroup,
+				orderId: null
+			});
+			const transaction = {
+				gatewayUrl: settled.gatewayUrl,
+				transactionId: settled.transactionId,
+				merchantName: settled.merchantName,
+				orderGroup: settled.orderGroup,
+				userProfileId: settled.userProfileId,
+				paymentSystem: selectedMethod.id,
+				groupName: selectedMethod.groupName,
+				currencyCode: settled.value.currencyCode,
+				valueInCents: settled.valueInCents,
+				referenceValueInCents: settled.referenceValueInCents,
+				installments: selectedInstallment?.count ?? 1,
+				installmentsValueInCents: selectedInstallment && selectedInstallment.count !== 1 ? toMinorUnits(selectedInstallment.value.amount) : settled.valueInCents,
+				interestRate: selectedInstallment?.interestRate ?? 0,
+				...billingAddressDifferent != null ? { billingAddressDifferent } : {}
+			};
+			handedOver = true;
+			const submissionErrors = await invokeSubmission(submit, transaction);
+			if (submissionErrors.length > 0) {
+				outcome = {
+					orderId: null,
+					userErrors: submissionErrors
+				};
+				writeAttemptIfCurrent(setAttempt, attemptId, {
+					attemptId,
+					phase: "unresolved",
+					orderGroup: settled.orderGroup,
+					orderId: null
+				});
+				return outcome;
+			}
+			writeAttemptIfCurrent(setAttempt, attemptId, {
+				attemptId,
+				phase: "finalizing",
+				orderGroup: settled.orderGroup,
+				orderId: null
+			});
+			const callback = await invokeGatewayCallback(gatewayCallback, settled.orderGroup, attemptId);
+			if (callback.userErrors.length > 0) {
+				outcome = {
+					orderId: null,
+					userErrors: reconcileCallbackUserErrors(callback.userErrors)
+				};
+				writeAttemptIfCurrent(setAttempt, attemptId, {
+					attemptId,
+					phase: "unresolved",
+					orderGroup: settled.orderGroup,
+					orderId: null
+				});
+				return outcome;
+			}
+			placedAttempt = {
+				attemptId,
+				phase: "settled",
+				orderGroup: settled.orderGroup,
+				orderId: callback.orderId
+			};
+			outcome = {
+				orderId: callback.orderId,
+				userErrors: []
+			};
+			track?.({
+				name: "purchase",
+				transactionId: callback.orderId ?? settled.transactionId,
+				value: {
+					amount: Number(settled.value.amount),
+					currencyCode: settled.value.currencyCode
+				}
+			});
+			writeAttemptIfCurrent(setAttempt, attemptId, placedAttempt);
+			return outcome;
+		} catch (error) {
+			console.error("[payment.placeOrder] the place-order sequence threw", attemptId, loggableErrorName(error));
+			try {
+				writeAttemptIfCurrent(setAttempt, attemptId, placedAttempt ?? (handedOver ? {
+					attemptId,
+					phase: "unresolved",
+					orderGroup: settledOrderGroup,
+					orderId: null
+				} : {
+					attemptId,
+					phase: "refused",
+					orderGroup: null,
+					orderId: null
+				}));
+			} catch (writeError) {
+				console.error("[payment.placeOrder] the place-order recovery write threw", attemptId, loggableErrorName(writeError));
+			}
+			return outcome ?? {
+				orderId: null,
+				userErrors: [NETWORK_ERROR]
+			};
+		}
+	}, [
+		startTransaction,
+		gatewayCallback,
+		track,
+		path,
+		resolve,
+		resolvePreflight,
+		selectedMethod,
+		selectedInstallment,
+		billingAddressDifferent,
+		submitGate,
+		setAttempt
+	]);
+	const placeOrder = useCallback(() => {
+		if (inFlight.current !== null) return inFlight.current;
+		const settleSequence = (sequence) => {
+			setUserErrors([]);
+			setOrderId(null);
+			const settle = (result) => {
+				inFlight.current = null;
+				setPlacing(false);
+				setUserErrors(result.userErrors);
+				setOrderId(result.orderId);
+				return result;
+			};
+			const outcome = sequence.then(settle, () => settle({
+				orderId: null,
+				userErrors: [NETWORK_ERROR]
+			}));
+			inFlight.current = outcome;
+			return outcome;
+		};
+		if (attempt) {
+			if (attempt.phase === "settled") return Promise.resolve({
+				orderId: attempt.orderId,
+				userErrors: []
+			});
+			if (attempt.phase === "opening" || attempt.phase === "finalizing") return settleSequence(Promise.resolve({
+				orderId: attempt.orderId,
+				userErrors: [PLACE_ORDER_IN_FLIGHT_ERROR]
+			}));
+			if (attempt.phase === "sent" || attempt.phase === "unresolved") return settleSequence(resume(gatewayCallback, setAttempt, setPlacing, attempt));
+		}
+		return settleSequence(run());
+	}, [
+		run,
+		attempt,
+		gatewayCallback,
+		setAttempt
+	]);
+	return useMemo(() => ({
+		placeOrder,
+		placing,
+		userErrors,
+		orderId
+	}), [
+		placeOrder,
+		placing,
+		userErrors,
+		orderId
+	]);
+}
+//#endregion
+export { PAYMENT_INVALID_TRANSACTION_CODE, PAYMENT_MISSING_METHOD_CODE, PAYMENT_MISSING_SUBMISSION_CODE, PLACE_ORDER_IN_FLIGHT_CODE, PLACE_ORDER_UNCONFIRMED_CODE, usePlaceOrder };
+
+//# sourceMappingURL=use-place-order.js.map