@12-apps/payments-frontend 3.2.0 → 3.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.2.0",
+  "version": "3.2.2",
   "type": "module",
   "description": "Browser half of the vendor-agnostic payments platform: plug-and-play MUI components for the per-provider settings page (credential form from each provider's schema, masked hints, verify/enable) and the checkout page (PIX QR + polling, card tokenization, hosted-checkout redirect), plus the headless hooks and fetch clients they build on. Talks only to the host's payments HTTP surface — never to a provider directly. Microfrontend-ready: no app coupling, host injects theme and auth.",
   "exports": {
@@ -17,7 +17,7 @@
     "storybook:build": "storybook build"
   },
   "dependencies": {
-    "@12-apps/payments-backend": "^4.3.0",
+    "@12-apps/payments-backend": "^4.5.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

package/src/components/checkout/checkout-flow.tsx

@@ -131,7 +131,7 @@ function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Ele
   // any chain member may need rather than re-opening after the choice. A chain
   // that declares nothing degrades to CPF-required, never to "ask nothing".
   const buyerFields = useMemo(() => buyerFieldsFor(providerConfig?.chain, null), [providerConfig]);
-  const c = useCheckoutController(ports, defaultBuyer, taxIdOnFile, buyerFields);
+  const c = useCheckoutController(ports, defaultBuyer, taxIdOnFile, buyerFields, tenantSlug);
 
   // A settlement settlement pays already-sent kitchen items — the cart is
   // legitimately empty here, so the empty-cart guard only applies to cart mode.

package/src/components/checkout/hosted-return.ts

@@ -54,10 +54,70 @@ function isReturnTrip(): boolean {
   return RETURN_MARKERS.some((marker) => params.has(marker));
 }
 
+/**
+ * Whether a hand-off from THIS tab is still waiting to be resolved.
+ *
+ * Exported because a host needs it and was otherwise forced to reimplement it.
+ * `/menu/checkout` is a URL like any other, so a host may put a gate in front
+ * of it — a closed-shop curtain, a plan check — and every such gate has to
+ * stand aside for a buyer coming back from a payment, because that route is
+ * where the money is confirmed. Deciding that from the outside meant copying
+ * this module's marker list and its storage key into the host, which is
+ * precisely the drift this package exists to stop: the copy went stale the
+ * moment Stripe's 3-D Secure markers were added here.
+ *
+ * Read WITHOUT consuming. The gate asks on every render; only the flow may
+ * take the order.
+ */
+export function hostedCheckoutReturnPending(tenantSlug?: string): boolean {
+  if (isReturnTrip()) return true;
+  const parked = readParked();
+  if (!parked) return false;
+  // Same two questions the resume asks, so a gate and the flow behind it can
+  // never disagree: another store's hand-off is not this route's business, and
+  // a stale one is nobody's.
+  return belongsHere(parked, tenantSlug) && !isStale(parked);
+}
+
+/**
+ * What is actually parked: the order, WHOSE STORE it belongs to, and when.
+ *
+ * `CheckoutOrder` carries no tenant, and on a multi-tenant storefront every
+ * store shares one origin — so one tab holds one slot for all of them. Without
+ * the slug, a buyer who abandoned store A's hand-off and opened store B's
+ * checkout resumed A's order on B's screen: a confirmation for an unrelated
+ * order, and B's own checkout skipped.
+ *
+ * `parkedAt` bounds the other axis. A hand-off is a round trip of minutes; an
+ * entry older than {@link MAX_PARKED_AGE_MS} belongs to a session the buyer has
+ * long since abandoned, and resuming it tells them about an order they are no
+ * longer trying to place.
+ */
+interface ParkedHostedOrder {
+  order: CheckoutOrder;
+  /** The store this hand-off belongs to; absent for an unscoped host. */
+  tenantSlug?: string;
+  parkedAt: number;
+}
+
+/**
+ * How long a parked hand-off stays resumable.
+ *
+ * Thirty minutes: a hosted payment takes minutes, and the window has to cover a
+ * buyer who fetches their card, not one who comes back tomorrow. Beyond it the
+ * entry is dropped on read rather than resumed.
+ */
+const MAX_PARKED_AGE_MS = 30 * 60_000;
+
 /** Park the raised order before handing the buyer to the provider's page. */
-export function rememberHostedOrder(order: CheckoutOrder): void {
+export function rememberHostedOrder(order: CheckoutOrder, tenantSlug?: string): void {
   try {
-    window.sessionStorage?.setItem(HOSTED_ORDER_STORAGE_KEY, JSON.stringify(order));
+    const parked: ParkedHostedOrder = {
+      order,
+      ...(tenantSlug ? { tenantSlug } : {}),
+      parkedAt: Date.now(),
+    };
+    window.sessionStorage?.setItem(HOSTED_ORDER_STORAGE_KEY, JSON.stringify(parked));
   } catch {
     // Storage disabled or full. The redirect must still happen: the webhook
     // settles the order either way, and refusing to send the buyer to pay
@@ -66,12 +126,30 @@ export function rememberHostedOrder(order: CheckoutOrder): void {
 }
 
 /**
- * The parked order, but ONLY on a return trip — and cleared as it is read.
+ * The parked order, cleared as it is read.
+ *
+ * This USED to require a marker on the URL, so that a buyer who abandoned the
+ * provider's page and reopened checkout got a fresh order rather than resuming
+ * one they never paid. That reasoning is inverted for the provider it matters
+ * most for, and the inversion is a money bug rather than a UX preference.
+ *
+ * Pressing the provider's "Continuar" is the ONLY thing that marks the URL.
+ * Closing the tab, hitting back, or retyping the store's address are all
+ * commoner, and all of them landed the buyer on a live payment step for an
+ * order that may already be paid — an invitation to pay twice. It cannot be
+ * decided by asking first, either: InfinitePay's `payment_check` refuses to
+ * answer without a `transaction_nsu` that only that same redirect carries, so
+ * "poll before resuming" reads PAID as PENDING and drops them on the pay
+ * button anyway.
  *
- * Gated on the URL rather than on mere presence so a buyer who abandons the
- * provider's page and later opens checkout again starts a fresh order instead
- * of resuming one they never paid. Read-and-clear for the same reason: the
- * resumed view belongs to exactly one return.
+ * So a parked order is itself the signal. The cost is that a buyer who truly
+ * abandoned sees one confirmation screen reporting what the store actually
+ * knows — which is the truth — with the way back on it. The read-and-clear
+ * bounds it: the resume happens once per hand-off, and leaving and reopening
+ * checkout gives a fresh one.
+ *
+ * `sessionStorage` already scopes this to one tab's round trip, so nothing
+ * here can resurface in a later, unrelated session.
  */
 /**
  * The key before the 2.0.0 rename, READ ONLY — decoded from base64 so no
@@ -111,15 +189,13 @@ const LEGACY_KEY = atob('ZnV0dXJlcGF5LmNoZWNrb3V0Lmhvc3RlZE9yZGVy');
  * legacy entry left behind would let a later return trip resume an order that
  * was already consumed.
  */
-function takeParkedPayload(): string | null {
+function peekParkedPayload(): string | null {
   try {
-    const raw =
+    return (
       window.sessionStorage?.getItem(HOSTED_ORDER_STORAGE_KEY) ??
       window.sessionStorage?.getItem(LEGACY_KEY) ??
-      null;
-    window.sessionStorage?.removeItem(HOSTED_ORDER_STORAGE_KEY);
-    window.sessionStorage?.removeItem(LEGACY_KEY);
-    return raw;
+      null
+    );
   } catch {
     // Storage disabled or unavailable — the same "no parked order" as an empty
     // slot, and the webhook still settles the order regardless.
@@ -127,13 +203,51 @@ function takeParkedPayload(): string | null {
   }
 }
 
-export function takeHostedOrder(): CheckoutOrder | null {
-  if (!isReturnTrip()) return null;
-  const raw = takeParkedPayload();
+export function takeHostedOrder(tenantSlug?: string): CheckoutOrder | null {
+  const parked = readParked();
+  if (!parked) return null;
+  // A hand-off from ANOTHER store is left where it is rather than consumed: it
+  // is that store's to resume, and this buyer may well go back to it.
+  if (!belongsHere(parked, tenantSlug)) return null;
+  clearParked();
+  if (isStale(parked)) return null;
+  return parked.order;
+}
+
+/** Whether a parked hand-off is this store's. */
+function belongsHere(parked: ParkedHostedOrder, tenantSlug?: string): boolean {
+  // An unscoped entry (a host that passes no slug, or one parked by an older
+  // bundle) stays readable by anyone — the single-tenant case, where there is
+  // no other store to confuse it with.
+  if (!parked.tenantSlug || !tenantSlug) return true;
+  return parked.tenantSlug === tenantSlug;
+}
+
+/** Whether it has been sitting long enough to no longer be this trip's. */
+function isStale(parked: ParkedHostedOrder): boolean {
+  if (typeof parked.parkedAt !== "number") return false;
+  return Date.now() - parked.parkedAt > MAX_PARKED_AGE_MS;
+}
+
+/**
+ * The parked entry, parsed, or null. Tolerates the PRE-SCOPE shape — a bare
+ * `CheckoutOrder` — so a buyer mid-hand-off across the deploy still comes back
+ * to their confirmation.
+ */
+function readParked(): ParkedHostedOrder | null {
+  const raw = peekParkedPayload();
   if (!raw) return null;
   try {
     const parsed: unknown = JSON.parse(raw);
-    return isCheckoutOrder(parsed) ? parsed : null;
+    if (isCheckoutOrder(parsed)) return { order: parsed, parkedAt: Date.now() };
+    if (typeof parsed !== "object" || parsed === null) return null;
+    const candidate = parsed as Partial<ParkedHostedOrder>;
+    if (!isCheckoutOrder(candidate.order)) return null;
+    return {
+      order: candidate.order,
+      ...(candidate.tenantSlug ? { tenantSlug: candidate.tenantSlug } : {}),
+      parkedAt: typeof candidate.parkedAt === "number" ? candidate.parkedAt : Date.now(),
+    };
   } catch {
     return null;
   }
@@ -149,3 +263,20 @@ function isCheckoutOrder(value: unknown): value is CheckoutOrder {
   const candidate = value as Partial<CheckoutOrder>;
   return typeof candidate.orderId === "string" && typeof candidate.totalLabel === "string";
 }
+
+/**
+ * Drop the parked entry. Split from the read because the READ now has to
+ * decide whose it is first — consuming another store's hand-off was the bug
+ * this scoping exists to stop.
+ *
+ * BOTH keys, whichever answered: a legacy entry left behind would let a later
+ * return trip resume an order that was already consumed.
+ */
+function clearParked(): void {
+  try {
+    window.sessionStorage?.removeItem(HOSTED_ORDER_STORAGE_KEY);
+    window.sessionStorage?.removeItem(LEGACY_KEY);
+  } catch {
+    // Storage disabled — there was nothing to clear.
+  }
+}

package/src/components/checkout/use-checkout-controller.ts

@@ -156,12 +156,20 @@ function initialStep(resuming: boolean, taxIdOnFile: boolean): Step {
  *
  * @returns true when the buyer is on their way and the caller must stop.
  */
-function handOverToProvider(order: CheckoutOrder, navigate: CheckoutNavigate): boolean {
+function handOverToProvider(
+  order: CheckoutOrder,
+  navigate: CheckoutNavigate,
+  tenantSlug?: string,
+): boolean {
   if (!order.hostedCheckoutUrl) return false;
   // PARK FIRST, navigate second. The order is the only thing the return trip
   // has to rehydrate from, and the navigation may tear this SPA down before
   // any later write lands.
-  rememberHostedOrder(order);
+  //
+  // The STORE goes with it: one tab holds one slot, and on a multi-tenant
+  // storefront every store shares an origin. Without the slug, abandoning this
+  // hand-off and opening another store's checkout resumed THIS order there.
+  rememberHostedOrder(order, tenantSlug);
   navigate(order.hostedCheckoutUrl);
   return true;
 }
@@ -175,8 +183,11 @@ function handOverToProvider(order: CheckoutOrder, navigate: CheckoutNavigate): b
  * card view, because a redirect provider produced neither. The webhook is still
  * what settles the order; this only tells the buyer that it did.
  */
-function useHostedResume(): { order: CheckoutOrder | null; status: OrderStatus | null } {
-  const [order] = useState(takeHostedOrder);
+function useHostedResume(tenantSlug?: string): {
+  order: CheckoutOrder | null;
+  status: OrderStatus | null;
+} {
+  const [order] = useState(() => takeHostedOrder(tenantSlug));
   const { status } = usePaymentPolling(order?.orderId ?? null, { enabled: Boolean(order) });
   return { order, status };
 }
@@ -252,10 +263,11 @@ export function useCheckoutController(
   defaultBuyer?: BuyerInfo,
   taxIdOnFile = false,
   buyerFields: readonly CheckoutCustomerField[] = CPF_ONLY,
+  tenantSlug?: string,
 ) {
   const { createOrder, saveBuyerContact, onExitToMenu, onPaid } = ports;
   const navigate = useCheckoutNavigate();
-  const resume = useHostedResume();
+  const resume = useHostedResume(tenantSlug);
   const [step, setStep] = useState<Step>(initialStep(Boolean(resume.order), taxIdOnFile));
   // No method pre-selected: the Pagamento step shows just the picker until the
   // buyer chooses PIX or card, then that method's order is raised and its UI
@@ -296,10 +308,10 @@ export function useCheckoutController(
     const result = await createOrder({ method: chosen, buyer: override ?? buyer, saveProfile });
     setCreating(false);
     if (!result.ok) { failure.fail(result.error); return; }
-    if (handOverToProvider(result.data, navigate)) return;
+    if (handOverToProvider(result.data, navigate, tenantSlug)) return;
     setOrder(result.data);
     setFinalStatus(null);
-  }, [buyer, saveProfile, createOrder, clearError, navigate]);
+  }, [buyer, saveProfile, createOrder, clearError, navigate, tenantSlug]);
   const payWithEmail = useCallback((email: string) => {
     if (!method) return;
     const next = { ...buyer, email };

package/src/index.ts

@@ -93,6 +93,17 @@ export { fetchCheckoutConfig } from './components/checkout/client';
  * literal and silently drifts when it changes.
  */
 export { HOSTED_ORDER_STORAGE_KEY } from './components/checkout/hosted-return';
+/**
+ * Whether a hand-off from this tab is still waiting to be resolved.
+ *
+ * For a HOST GATE in front of the checkout route — a closed-shop curtain, a
+ * plan check. Every such gate has to stand aside for a buyer coming back from
+ * a payment, because that route is where the money gets confirmed, and a host
+ * deciding it alone had to copy this package's marker list and storage key.
+ * That copy goes stale: it did, the moment Stripe's 3-D Secure markers were
+ * added here. Reads without consuming.
+ */
+export { hostedCheckoutReturnPending } from './components/checkout/hosted-return';
 // ---------------------------------------------------------------------------
 // Digital wallets (FUT-471/472) — the Google-branded button and the capability
 // read it is gated on. `CheckoutFlow` wires these automatically; they are