@12-apps/payments-frontend 3.2.1 → 3.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.2.1",
+  "version": "3.2.3",
   "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.
@@ -197,6 +197,7 @@ function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Ele
           onRegenerate={() => { c.setStep("payment"); void c.startPayment("PIX"); }}
           onBackToMenu={c.goToMenu}
           paidExtra={confirmationExtra}
+          awaitingTimedOut={c.resumeTimedOut}
         />
       ) : null}
     </Box>

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

@@ -69,22 +69,66 @@ function isReturnTrip(): boolean {
  * Read WITHOUT consuming. The gate asks on every render; only the flow may
  * take the order.
  */
-export function hostedCheckoutReturnPending(): boolean {
-  if (isReturnTrip()) return true;
-  try {
-    return Boolean(
-      window.sessionStorage?.getItem(HOSTED_ORDER_STORAGE_KEY) ??
-        window.sessionStorage?.getItem(LEGACY_KEY),
-    );
-  } catch {
-    return false;
-  }
+export function hostedCheckoutReturnPending(tenantSlug?: string): boolean {
+  const parked = readParked();
+  // THE PARKED ENTRY DECIDES whenever there is one — the same two questions the
+  // resume asks, so a gate and the flow behind it cannot disagree about whose
+  // return this is. Another store's hand-off is not this route's business, and
+  // a stale one is nobody's.
+  //
+  // Asking the URL FIRST is what this used to do, and it made the two disagree
+  // exactly where it costs something: a provider marker is per-TAB, so store
+  // A's abandoned hand-off plus any marked URL had the gate answer "a return is
+  // pending here" on store B while `takeHostedOrder` correctly refused to
+  // resume it. A gate that stands aside for a return that is not going to
+  // happen is a gate that has been talked out of its job.
+  if (parked) return belongsHere(parked, tenantSlug) && !isStale(parked);
+  // Nothing parked, so the provider's own marker is the only evidence left that
+  // a return is in progress. It is kept, and only here, for the case that has
+  // no other signal: the flow has already CONSUMED the entry, and a gate
+  // re-asking mid-visit must not curtain the confirmation it just let through.
+  return isReturnTrip();
+}
+
+/**
+ * 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 +200,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 +214,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 +274,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/payment-status.tsx

@@ -66,6 +66,28 @@ const OUTCOME: Record<OrderStatus, Outcome> = {
   },
 };
 
+/**
+ * What the screen says once it has stopped asking (FUT-556).
+ *
+ * NOT an `OrderStatus`: the order really is still AWAITING_PAYMENT and may yet
+ * settle — the scheduled reconciliation keeps asking the provider long after
+ * this tab is gone. What ran out is the WAIT, not the order, and saying
+ * otherwise would be the more expensive lie: a buyer told "não concluído" who
+ * has in fact paid will either pay twice or call the store.
+ *
+ * So it leads with what is true and unglamorous — we have not heard yet — and
+ * spends its remaining words on the one instruction that matters, which is not
+ * to pay again.
+ */
+const AWAITING_TIMED_OUT: Outcome = {
+  heading: "Ainda não recebemos a confirmação",
+  support:
+    "Se você já pagou, o pedido é confirmado assim que a operadora avisar — " +
+    "não pague de novo. Você pode fechar esta tela.",
+  icon: <ScheduleIcon fontSize="large" />,
+  tone: "warning",
+};
+
 const TONE_COLOR: Record<Outcome["tone"], string> = {
   success: "success.main",
   danger: "error.main",
@@ -86,14 +108,29 @@ function orderReference(orderId: string): string {
 }
 
 /** The headline block: icon, outcome, and one supporting line. */
-function OutcomeHero({ status }: { status: OrderStatus }): JSX.Element {
+function OutcomeHero({
+  status,
+  timedOut = false,
+}: {
+  status: OrderStatus;
+  timedOut?: boolean;
+}): JSX.Element {
   const { Text } = useCheckoutComponents();
-  const outcome = OUTCOME[status];
+  const outcome = timedOut && status === "AWAITING_PAYMENT" ? AWAITING_TIMED_OUT : OUTCOME[status];
   return (
     <Box
       // `payment-paid` is load-bearing for the storefront journeys — it is how
-      // they assert the buyer actually got there.
-      data-testid={status === "PAID" ? "payment-paid" : `payment-${status.toLowerCase()}`}
+      // they assert the buyer actually got there. The timed-out wait gets its
+      // OWN id rather than reusing `payment-awaiting_payment`: a test that
+      // cannot tell "still asking" from "stopped asking" is a test that would
+      // pass against the unbounded spinner this replaced.
+      data-testid={
+        timedOut && status === "AWAITING_PAYMENT"
+          ? "payment-awaiting-timeout"
+          : status === "PAID"
+            ? "payment-paid"
+            : `payment-${status.toLowerCase()}`
+      }
       sx={{ display: "flex", flexDirection: "column", alignItems: "center", gap: 1, textAlign: "center" }}
     >
       <Box sx={{ color: TONE_COLOR[outcome.tone], display: "flex" }}>{outcome.icon}</Box>
@@ -206,6 +243,7 @@ export function PaymentStatus({
   onRegenerate,
   onBackToMenu,
   paidExtra,
+  awaitingTimedOut = false,
 }: {
   status: OrderStatus | null;
   totalLabel: string;
@@ -223,6 +261,12 @@ export function PaymentStatus({
    * is the difference between an offer and an interruption.
    */
   paidExtra?: ReactNode;
+  /**
+   * The wait has been given up on — see {@link AWAITING_TIMED_OUT}. Only
+   * meaningful while AWAITING_PAYMENT; every other status has already resolved,
+   * so a stale flag cannot change what a settled screen says.
+   */
+  awaitingTimedOut?: boolean;
 }): JSX.Element {
   const { LoadingState } = useCheckoutComponents();
   const effective: OrderStatus = status ?? "AWAITING_PAYMENT";
@@ -231,9 +275,10 @@ export function PaymentStatus({
     <Box
       data-testid="payment-status"
       data-status={effective}
+      data-timed-out={awaitingTimedOut ? "true" : undefined}
       sx={{ display: "flex", flexDirection: "column", gap: 3, alignItems: "stretch", py: 2 }}
     >
-      <OutcomeHero status={effective} />
+      <OutcomeHero status={effective} timedOut={awaitingTimedOut} />
 
       {effective === "PAID" ? (
         <PaidFacts totalLabel={totalLabel} orderId={orderId} buyerEmail={buyerEmail} />
@@ -241,7 +286,7 @@ export function PaymentStatus({
 
       {effective === "PAID" ? paidExtra : null}
 
-      {effective === "AWAITING_PAYMENT" ? (
+      {effective === "AWAITING_PAYMENT" && !awaitingTimedOut ? (
         <LoadingState variant="spinner" size="md" message="" dataTestId="payment-pending" />
       ) : null}
 

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

@@ -156,16 +156,43 @@ 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;
 }
 
+/**
+ * How long the resumed screen keeps asking, and how often.
+ *
+ * 180 polls at 5 s ≈ 15 minutes. Both halves are chosen against what actually
+ * settles a hosted charge, which is the WEBHOOK: it lands seconds after the
+ * payment, so a faster interval buys nothing, and by a quarter of an hour a
+ * delivery that was ever coming has come. Past that the answer is not going to
+ * change while the buyer watches — the scheduled reconciliation is what
+ * rescues a genuinely late one, and it does that whether the tab is open or
+ * not.
+ *
+ * The card wait is bounded at 90 s (`CARD_AWAITING_POLL_CAP`) because a card
+ * authorises inline and a buyer is holding their phone. This leg is the other
+ * shape: the buyer has already been off to another site and back, and may
+ * legitimately still be finishing there.
+ */
+const HOSTED_RESUME_POLL_MS = 5_000;
+const HOSTED_RESUME_POLL_CAP = 180;
+
 /**
  * The leg of checkout that resumes after a hosted provider sent the buyer back
  * (FUT-556).
@@ -174,11 +201,27 @@ function handOverToProvider(order: CheckoutOrder, navigate: CheckoutNavigate): b
  * parked copy — once, on first render — and polled here rather than in a PIX or
  * card view, because a redirect provider produced neither. The webhook is still
  * what settles the order; this only tells the buyer that it did.
+ *
+ * And it stops telling them eventually. This poll was the one unbounded wait
+ * left in checkout — card and wallet both cap theirs — so a buyer who came back
+ * from a payment they never completed got "Confirmando seu pagamento… isso
+ * costuma levar alguns segundos" and a spinner, truthfully forever. The screen
+ * had no way to reach a terminal state, because the ORDER has none: expiry is
+ * PIX-only, and a redirect charge carries no QR window to lapse. `timedOut` is
+ * what the screen says instead of spinning.
  */
-function useHostedResume(): { order: CheckoutOrder | null; status: OrderStatus | null } {
-  const [order] = useState(takeHostedOrder);
-  const { status } = usePaymentPolling(order?.orderId ?? null, { enabled: Boolean(order) });
-  return { order, status };
+function useHostedResume(tenantSlug?: string): {
+  order: CheckoutOrder | null;
+  status: OrderStatus | null;
+  timedOut: boolean;
+} {
+  const [order] = useState(() => takeHostedOrder(tenantSlug));
+  const { status, timedOut } = usePaymentPolling(order?.orderId ?? null, {
+    enabled: Boolean(order),
+    intervalMs: HOSTED_RESUME_POLL_MS,
+    maxHealthyPolls: HOSTED_RESUME_POLL_CAP,
+  });
+  return { order, status, timedOut };
 }
 
 /**
@@ -252,10 +295,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 +340,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 };
@@ -316,6 +360,10 @@ export function useCheckoutController(
   return {
     step, setStep, method, setMethod, buyer, setBuyer, saveProfile, setSaveProfile,
     order, finalStatus: finalStatus ?? resume.status, creating,
+    // Only ever true on the resumed leg: `useHostedResume` is the sole caller
+    // that caps its polls, and a buyer who never left has a card or PIX view
+    // reporting its own wait.
+    resumeTimedOut: resume.timedOut,
     createError: failure.message, errorField: failure.field, errorCode: failure.code,
     goToMenu: onExitToMenu, back, editBuyer,
     goToPayment, startPayment, payWithEmail, handleResolved, retry, completed,

package/src/flows/copy.ts

@@ -35,6 +35,18 @@ export interface CheckoutCopyFE {
   returnPending: string;
   /** The return leg when nothing was parked — the buyer came back to nothing. */
   returnUnknown: string;
+  /**
+   * The return leg once the bounded wait elapsed and the screen stopped asking
+   * (FUT-556) — say that nothing has arrived yet and, above all, not to pay
+   * again.
+   *
+   * OPTIONAL, so adopting a version with the bound is not a breaking change for
+   * a host that has not written the sentence yet. The BOUND itself applies
+   * either way: with no copy the screen still stops spinning and falls back to
+   * `returnPending` as a warning, which is the honest half. The words are the
+   * part only a host can own.
+   */
+  returnTimedOut?: string;
   /** Nothing to check out (cart mode only). */
   emptyCartTitle: string;
   emptyCartAction: string;

package/src/flows/screens-hosted.tsx

@@ -96,6 +96,20 @@ function buildHostedHandoff(runtime: FlowsRuntime): CheckoutScreens["HostedHando
   };
 }
 
+/**
+ * How long this screen keeps asking, and how often — see the twin constants in
+ * `use-checkout-controller.ts`, which bounds the same wait for the components
+ * layer. 180 polls at 5 s ≈ 15 minutes.
+ *
+ * Stated here rather than imported because the two waits are the same DECISION
+ * arrived at twice, not one shared implementation: this screen takes its
+ * interval from the host's `polling` config when there is one, and a host that
+ * tunes that must not have this package's cap silently mean a different
+ * wall-clock window than the constant's comment claims.
+ */
+const RETURN_POLL_MS = 5_000;
+const RETURN_POLL_CAP = 180;
+
 function buildHostedReturn(runtime: FlowsRuntime): CheckoutScreens["HostedReturn"] {
   function HostedReturnBody({
     onResolved,
@@ -106,9 +120,13 @@ function buildHostedReturn(runtime: FlowsRuntime): CheckoutScreens["HostedReturn
     // Read-and-clear, once, on first render: the resumed view belongs to
     // exactly one return trip.
     const [parked] = useState(takeHostedOrder);
-    const { status } = usePaymentPolling(parked?.orderId ?? null, {
+    // Bounded, for the reason on RETURN_POLL_CAP: nothing here can ever reach a
+    // terminal state on its own, so an unbounded poll is a spinner the buyer
+    // watches until they close the tab.
+    const { status, timedOut } = usePaymentPolling(parked?.orderId ?? null, {
       enabled: Boolean(parked),
-      intervalMs: runtime.config.polling?.intervalMs,
+      intervalMs: runtime.config.polling?.intervalMs ?? RETURN_POLL_MS,
+      maxHealthyPolls: RETURN_POLL_CAP,
     });
 
     useEffect(() => {
@@ -126,6 +144,21 @@ function buildHostedReturn(runtime: FlowsRuntime): CheckoutScreens["HostedReturn
         />
       );
     }
+    if (timedOut) {
+      return (
+        <Box data-testid="checkout-hosted-return" sx={{ py: 4 }}>
+          <Alert
+            variant="warning"
+            title={runtime.copy.returnPending}
+            {...(runtime.copy.returnTimedOut === undefined
+              ? {}
+              : { description: runtime.copy.returnTimedOut })}
+            showIcon
+            data-testid="checkout-hosted-return-timeout"
+          />
+        </Box>
+      );
+    }
     return (
       <Box data-testid="checkout-hosted-return" sx={{ py: 4 }}>
         <LoadingState