@vtex/faststore 0.0.10 → 0.0.11

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

@@ -1,35 +1,12 @@
 "use client";
+import { resolveNavigableHref } from "../../utils/safe-href.js";
 import { loggableErrorName } from "../../utils/loggable-error-name.js";
 import { usePaymentSubmission } from "./submission-registry.js";
 import { PAYMENT_NETWORK_ERROR_CODE } from "./operations.js";
+import { claimPurchase, emitPurchaseForOrder } from "./resumed-purchase.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";
 /**
@@ -70,7 +47,7 @@ const PLACE_ORDER_IN_FLIGHT_ERROR = {
 };
 /**
 * 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.
+* `PlaceOrder`'s `unconfirmedMessage` source copy repeats this text verbatim.
 */
 const PLACE_ORDER_UNCONFIRMED_ERROR = {
 	code: PLACE_ORDER_UNCONFIRMED_CODE,
@@ -112,6 +89,7 @@ function settleTransaction(payload) {
 		transactionId,
 		merchantName,
 		orderGroup,
+		orderNodeId: payload.orderNodeId ?? null,
 		userProfileId,
 		value,
 		valueInCents,
@@ -140,7 +118,8 @@ function toMinorUnits(amount) {
 * a boolean is read as `true`: only a literal `false` may free the attempt, so a holder that omits the
 * signal locks it rather than inviting a second payment. An empty `userErrors` is a success whatever the
 * flag says. Each field is read once, into a local, and the result handed back is a fresh object — a
-* getter that answers differently across reads has no second read to answer differently on.
+* getter that answers differently across reads has no second read to answer differently on. T39: the one
+* field kept beyond those two is `completesWithoutGateway`, and only as the literal `true` on a success.
 */
 async function invokeSubmission(submit, transaction) {
 	try {
@@ -152,7 +131,7 @@ async function invokeSubmission(submit, transaction) {
 				userErrors: [NETWORK_ERROR]
 			};
 		}
-		const { reachedGateway, userErrors } = result;
+		const { reachedGateway, userErrors, completesWithoutGateway } = result;
 		if (!Array.isArray(userErrors)) {
 			console.error("[payment.placeOrder] the registered submission resolved a result with no userErrors list");
 			return {
@@ -160,7 +139,11 @@ async function invokeSubmission(submit, transaction) {
 				userErrors: [NETWORK_ERROR]
 			};
 		}
-		if (userErrors.length === 0) return {
+		if (userErrors.length === 0) return completesWithoutGateway === true ? {
+			reachedGateway: true,
+			userErrors: [],
+			completesWithoutGateway: true
+		} : {
 			reachedGateway: true,
 			userErrors: []
 		};
@@ -249,13 +232,14 @@ function runMissingMethodExplainer(explain) {
 */
 async function invokeStartTransaction(startTransaction) {
 	try {
-		const { transactionId, merchantName, gatewayUrl, orderGroup, userProfileId, value, valueInCents, referenceValueInCents, userErrors } = await startTransaction();
+		const { transactionId, merchantName, gatewayUrl, orderGroup, orderNodeId, 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,
+			orderNodeId,
 			userProfileId,
 			value,
 			valueInCents,
@@ -269,6 +253,7 @@ async function invokeStartTransaction(startTransaction) {
 			merchantName: null,
 			gatewayUrl: null,
 			orderGroup: null,
+			orderNodeId: null,
 			userProfileId: null,
 			value: null,
 			valueInCents: null,
@@ -316,6 +301,7 @@ async function invokeGatewayCallback(gatewayCallback, orderGroup, attemptId) {
 		console.error("[payment.placeOrder] gatewayCallback threw", orderGroup, attemptId, loggableErrorName(error));
 		return {
 			orderId: null,
+			orderNodeId: null,
 			userErrors: [NETWORK_ERROR]
 		};
 	}
@@ -323,23 +309,28 @@ async function invokeGatewayCallback(gatewayCallback, orderGroup, attemptId) {
 		console.error("[payment.placeOrder] gatewayCallback resolved with no result", orderGroup, attemptId);
 		return {
 			orderId: null,
+			orderNodeId: null,
 			userErrors: [NETWORK_ERROR]
 		};
 	}
 	if (result.userErrors == null) console.error("[payment.placeOrder] gatewayCallback resolved with no userErrors", orderGroup, attemptId);
 	return {
 		orderId: result.orderId ?? null,
+		orderNodeId: result.orderNodeId ?? null,
+		redirectUrl: result.redirectUrl ?? null,
 		userErrors: result.userErrors ?? [NETWORK_ERROR]
 	};
 }
 /**
-* The two codes the server sends today on `gatewayCallback`. Neither is a verdict on the order, so
-* `callbackFreesAttempt` never frees an attempt that carries either (T110, Decision 3):
-* `REDIRECT_REQUIRED` is a bank challenge, and `MISSING_TRANSACTION_COOKIES` means the card POST was
-* already accepted while the callback never reached VTEX, so a second POST could authorize the card twice.
+* The codes the server sends on `gatewayCallback` that are not a verdict on the order, so
+* `callbackFreesAttempt` never frees an attempt that carries one (T110, Decision 3):
+* `REDIRECT_REQUIRED` is a bank challenge, and `MISSING_TRANSACTION_COOKIES` and `ORDER_GROUP_MISMATCH`
+* mean the card POST was already accepted while the callback never reached VTEX, so a second POST could
+* authorize the card twice.
 */
 const REDIRECT_REQUIRED_CODE = "REDIRECT_REQUIRED";
 const MISSING_TRANSACTION_COOKIES_CODE = "MISSING_TRANSACTION_COOKIES";
+const ORDER_GROUP_MISMATCH_CODE = "ORDER_GROUP_MISMATCH";
 /** The entry's `code`, or `undefined` when it cannot be read (a `null` entry, a getter that throws). */
 function readCode(userError) {
 	try {
@@ -356,15 +347,15 @@ function carriesServerCode(userError) {
 /**
 * T110: whether a `gatewayCallback` that reported `userErrors` frees the attempt for a fresh run. It does
 * when the server sent a string `code`, none of the entries is a locked code (`REDIRECT_REQUIRED`,
-* `MISSING_TRANSACTION_COOKIES`), and the result carries no `orderId`: an order the callback confirmed is
-* never freed. Everything else keeps the attempt resume-only, because a payment that may have gone through
+* `MISSING_TRANSACTION_COOKIES`, `ORDER_GROUP_MISMATCH`), and the result carries no `orderId`: an order the
+* callback confirmed is never freed. Everything else keeps the attempt resume-only, because a payment that may have gone through
 * must never be paid twice. Total, and never throws: a non-array, an empty list or an entry nobody can read
 * frees nothing.
 *
-* Dormant today: the server sends only the two locked codes, so no real callback frees an attempt yet.
-* The rule fires for a server-coded error the server does not send yet (task T225 will). It fails open on
-* a code it does not know (spec AC-5: no per-code table); a future allowlist of the codes that really are
-* declines belongs to T225, not to this hook.
+* Live since T203: the server answers a refused callback with `PAYMENT_DECLINED`, which frees the attempt,
+* while the locked codes it also sends stay resume-only. The rule fails open on a code it does not
+* know (spec AC-5: no per-code table); an allowlist of the codes that really are declines is not this
+* hook's job.
 */
 function callbackFreesAttempt(callback) {
 	const { orderId, userErrors } = callback;
@@ -372,10 +363,28 @@ function callbackFreesAttempt(callback) {
 	if (!Array.isArray(userErrors)) return false;
 	return userErrors.some((userError) => carriesServerCode(userError)) && !userErrors.some((userError) => {
 		const code = readCode(userError);
-		return code === REDIRECT_REQUIRED_CODE || code === MISSING_TRANSACTION_COOKIES_CODE;
+		return code === REDIRECT_REQUIRED_CODE || code === MISSING_TRANSACTION_COOKIES_CODE || code === ORDER_GROUP_MISMATCH_CODE;
 	});
 }
 /**
+* T208 (Decision 3): the bank's challenge page, when this callback answer may be followed. Only when a return
+* URL was sent (the bank could not send the shopper back otherwise), the answer asks for a challenge and
+* places no order, and the URL is absolute `http(s)`. A site-relative URL is refused too: the only
+* navigation off the store's own pages is the one to the bank. Total, and never throws.
+*/
+function readChallengeRedirect(callback, returnUrlSent) {
+	if (!returnUrlSent || callback.orderId != null) return null;
+	const { userErrors, redirectUrl } = callback;
+	if (!Array.isArray(userErrors) || typeof redirectUrl !== "string") return null;
+	if (!userErrors.some((userError) => readCode(userError) === REDIRECT_REQUIRED_CODE)) return null;
+	const destination = resolveNavigableHref(redirectUrl);
+	return destination.safe && destination.href === redirectUrl && !destination.href.startsWith("/") ? redirectUrl : null;
+}
+/** The result field a redirect adds: absent, never an explicit `undefined`, when there is nothing to follow. */
+function redirectField(redirectUrl) {
+	return redirectUrl === null ? {} : { redirectUrl };
+}
+/**
 * 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
@@ -446,7 +455,8 @@ function resumedRecord(current, callback, failed, freed) {
 	return {
 		...current,
 		phase: "settled",
-		orderId: callback.orderId
+		orderId: callback.orderId,
+		orderNodeId: callback.orderNodeId ?? null
 	};
 }
 /**
@@ -565,7 +575,7 @@ async function openTransaction(startTransaction, setAttempt, attemptId) {
 	};
 }
 /** The descriptor `run()` hands to the registered submission. Nothing in it is sensitive. */
-function buildTransaction({ settled, method, selectedInstallment, billingAddressDifferent }) {
+function buildTransaction({ settled, method, selectedInstallment, billingAddressDifferent, callbackUrl }) {
 	return {
 		gatewayUrl: settled.gatewayUrl,
 		transactionId: settled.transactionId,
@@ -580,9 +590,15 @@ function buildTransaction({ settled, method, selectedInstallment, billingAddress
 		installments: selectedInstallment?.count ?? 1,
 		installmentsValueInCents: selectedInstallment && selectedInstallment.count !== 1 ? toMinorUnits(selectedInstallment.value.amount) : settled.valueInCents,
 		interestRate: selectedInstallment?.interestRate ?? 0,
-		...billingAddressDifferent == null ? {} : { billingAddressDifferent }
+		...billingAddressDifferent == null ? {} : { billingAddressDifferent },
+		...callbackUrl === null ? {} : { callbackUrl }
 	};
 }
+/** The return URL for a group, or `null` when none was authored or the builder gave none. */
+function returnUrlFor(challengeReturn, orderGroup) {
+	const url = challengeReturn?.(orderGroup);
+	return typeof url === "string" && url !== "" ? url : null;
+}
 /**
 * 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
@@ -596,8 +612,12 @@ function buildTransaction({ settled, method, selectedInstallment, billingAddress
 *
 * T110: a callback the retry rule frees records `refused`, as `run()` does, so the next click is a fresh
 * full run. This function still issues nothing but `gatewayCallback`.
+*
+* T208: a callback that answers a challenge redirects here too, when `returnUrlSent` says the original request
+* carried a return URL (the attempt record does not carry that fact). A resume that finishes the order reports
+* its purchase, reading value and currency from the settled order: the record may hold neither.
 */
-async function resume(gatewayCallback, setAttempt, setPlacing, current) {
+async function resume(gatewayCallback, setAttempt, setPlacing, current, { returnUrlSent, track, readSettledOrder }) {
 	if (!gatewayCallback || current.orderGroup === null) {
 		console.error("[payment.placeOrder] cannot resume an attempt with no order group");
 		return {
@@ -613,15 +633,23 @@ async function resume(gatewayCallback, setAttempt, setPlacing, current) {
 	setPlacing(true);
 	const callback = await invokeGatewayCallback(gatewayCallback, current.orderGroup, current.attemptId);
 	const failed = callback.userErrors.length > 0;
+	const redirectUrl = failed ? readChallengeRedirect(callback, returnUrlSent) : null;
 	const result = failed ? {
 		orderId: null,
 		userErrors: reconcileCallbackUserErrors(callback.userErrors),
-		reachedGateway: true
+		reachedGateway: true,
+		...redirectField(redirectUrl)
 	} : {
 		orderId: callback.orderId,
+		orderNodeId: callback.orderNodeId ?? null,
 		userErrors: [],
 		reachedGateway: true
 	};
+	if (!failed && callback.orderNodeId != null) await emitPurchaseForOrder({
+		track,
+		readOrder: readSettledOrder,
+		orderNodeId: callback.orderNodeId
+	});
 	const freed = failed && callbackFreesAttempt(callback);
 	try {
 		writeAttemptIfCurrent(setAttempt, current.attemptId, resumedRecord(current, callback, failed, freed));
@@ -630,12 +658,14 @@ async function resume(gatewayCallback, setAttempt, setPlacing, current) {
 	}
 	return result;
 }
-function usePlaceOrder({ $data, $actions, attempt, setAttempt, billingAddressDifferent, submitGate }) {
+function usePlaceOrder({ $data, $actions, attempt, setAttempt, billingAddressDifferent, submitGate, challengeReturn, readSettledOrder }) {
 	const { path, resolve, resolvePreflight, resolveMissingMethodExplainer } = usePaymentSubmission();
 	const [placing, setPlacing] = useState(false);
 	const [userErrors, setUserErrors] = useState([]);
 	const [orderId, setOrderId] = useState(null);
+	const [orderNodeId, setOrderNodeId] = useState(null);
 	const [reachedGateway, setReachedGateway] = useState(null);
+	const [redirectUrl, setRedirectUrl] = useState(null);
 	const inFlight = useRef(null);
 	const startTransaction = $actions?.payment?.startTransaction;
 	const gatewayCallback = $actions?.payment?.gatewayCallback;
@@ -688,11 +718,13 @@ function usePlaceOrder({ $data, $actions, attempt, setAttempt, billingAddressDif
 				orderGroup: settled.orderGroup,
 				orderId: null
 			});
+			const callbackUrl = returnUrlFor(challengeReturn, settled.orderGroup);
 			const transaction = buildTransaction({
 				settled,
 				method,
 				selectedInstallment,
-				billingAddressDifferent
+				billingAddressDifferent,
+				callbackUrl
 			});
 			handedOver = true;
 			const submissionErrors = await invokeSubmission(submit, transaction);
@@ -707,37 +739,47 @@ function usePlaceOrder({ $data, $actions, attempt, setAttempt, billingAddressDif
 				writeAttemptIfCurrent(setAttempt, attemptId, recoveryRecord(attemptId, null, handedOver, settled.orderGroup));
 				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),
-					reachedGateway: true
-				};
-				handedOver = !callbackFreesAttempt(callback);
-				writeAttemptIfCurrent(setAttempt, attemptId, recoveryRecord(attemptId, null, handedOver, settled.orderGroup));
-				return outcome;
+			const completesWithoutGateway = submissionErrors.completesWithoutGateway === true;
+			let placedOrderId = settled.orderGroup;
+			let placedOrderNodeId = settled.orderNodeId;
+			if (!completesWithoutGateway) {
+				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),
+						reachedGateway: true,
+						...redirectField(readChallengeRedirect(callback, callbackUrl !== null))
+					};
+					handedOver = !callbackFreesAttempt(callback);
+					writeAttemptIfCurrent(setAttempt, attemptId, recoveryRecord(attemptId, null, handedOver, settled.orderGroup));
+					return outcome;
+				}
+				placedOrderId = callback.orderId;
+				placedOrderNodeId = callback.orderNodeId ?? settled.orderNodeId;
 			}
 			placedAttempt = {
 				attemptId,
 				phase: "settled",
 				orderGroup: settled.orderGroup,
-				orderId: callback.orderId
+				orderId: placedOrderId,
+				orderNodeId: placedOrderNodeId
 			};
 			outcome = {
-				orderId: callback.orderId,
+				orderId: placedOrderId,
+				orderNodeId: placedOrderNodeId,
 				userErrors: [],
 				reachedGateway: true
 			};
-			track?.({
+			if (track && claimPurchase(settled.orderGroup)) track({
 				name: "purchase",
-				transactionId: callback.orderId ?? settled.transactionId,
+				transactionId: placedOrderId ?? settled.transactionId,
 				value: {
 					amount: Number(settled.value.amount),
 					currencyCode: settled.value.currencyCode
@@ -766,20 +808,28 @@ function usePlaceOrder({ $data, $actions, attempt, setAttempt, billingAddressDif
 		selectedInstallment,
 		billingAddressDifferent,
 		submitGate,
-		setAttempt
+		setAttempt,
+		challengeReturn
 	]);
 	const placeOrder = useCallback(() => {
 		if (inFlight.current !== null) return inFlight.current;
 		const settleSequence = (sequence) => {
 			setUserErrors([]);
 			setOrderId(null);
+			setOrderNodeId(null);
 			setReachedGateway(null);
+			setRedirectUrl(null);
 			const settle = (result) => {
-				inFlight.current = null;
-				setPlacing(false);
-				setUserErrors(result.userErrors);
+				const redirecting = typeof result.redirectUrl === "string";
+				if (!redirecting) {
+					inFlight.current = null;
+					setPlacing(false);
+				}
+				setUserErrors(redirecting ? [] : result.userErrors);
 				setOrderId(result.orderId);
+				setOrderNodeId(result.orderNodeId ?? null);
 				setReachedGateway(result.reachedGateway);
+				setRedirectUrl(redirecting ? result.redirectUrl ?? null : null);
 				return result;
 			};
 			const outcome = sequence.then(settle, () => settle({
@@ -793,6 +843,7 @@ function usePlaceOrder({ $data, $actions, attempt, setAttempt, billingAddressDif
 		if (attempt) {
 			if (attempt.phase === "settled") return settleSequence(Promise.resolve({
 				orderId: attempt.orderId,
+				orderNodeId: attempt.orderNodeId ?? null,
 				userErrors: [],
 				reachedGateway: true
 			}));
@@ -801,27 +852,38 @@ function usePlaceOrder({ $data, $actions, attempt, setAttempt, billingAddressDif
 				userErrors: [PLACE_ORDER_IN_FLIGHT_ERROR],
 				reachedGateway: true
 			}));
-			if (attempt.phase === "sent" || attempt.phase === "unresolved") return settleSequence(resume(gatewayCallback, setAttempt, setPlacing, attempt));
+			if (attempt.phase === "sent" || attempt.phase === "unresolved") return settleSequence(resume(gatewayCallback, setAttempt, setPlacing, attempt, {
+				returnUrlSent: attempt.orderGroup !== null && returnUrlFor(challengeReturn, attempt.orderGroup) !== null,
+				track,
+				readSettledOrder
+			}));
 		}
 		return settleSequence(run());
 	}, [
 		run,
 		attempt,
 		gatewayCallback,
-		setAttempt
+		setAttempt,
+		challengeReturn,
+		track,
+		readSettledOrder
 	]);
 	return useMemo(() => ({
 		placeOrder,
 		placing,
 		userErrors,
 		orderId,
-		reachedGateway
+		orderNodeId,
+		reachedGateway,
+		redirectUrl
 	}), [
 		placeOrder,
 		placing,
 		userErrors,
 		orderId,
-		reachedGateway
+		orderNodeId,
+		reachedGateway,
+		redirectUrl
 	]);
 }
 //#endregion