@12-apps/payments-frontend 3.2.1 → 3.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.2.1",
+  "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": {

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

@@ -69,22 +69,55 @@ function isReturnTrip(): boolean {
  * Read WITHOUT consuming. The gate asks on every render; only the flow may
  * take the order.
  */
-export function hostedCheckoutReturnPending(): boolean {
+export function hostedCheckoutReturnPending(tenantSlug?: string): boolean {
   if (isReturnTrip()) return true;
-  try {
-    return Boolean(
-      window.sessionStorage?.getItem(HOSTED_ORDER_STORAGE_KEY) ??
-        window.sessionStorage?.getItem(LEGACY_KEY),
-    );
-  } catch {
-    return false;
-  }
+  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
@@ -156,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.
@@ -172,12 +203,51 @@ function takeParkedPayload(): string | null {
   }
 }
 
-export function takeHostedOrder(): CheckoutOrder | 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;
   }
@@ -193,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 };