@12-apps/payments-frontend 3.21.2 → 3.21.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.21.2",
+  "version": "3.21.4",
   "type": "module",
   "sideEffects": false,
   "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.",

package/src/components/checkout/poll-loop.ts

@@ -1,4 +1,5 @@
 import type { Result } from "../../result";
+import { claimRearm } from "./poll-rearm";
 import { TERMINAL_STATUSES, type OrderStatus } from "./types";
 
 /**
@@ -18,6 +19,14 @@ export interface PollingOptions {
    * {@link DEFAULT_ASK_TIMEOUT_MS}; consumers override it only in tests.
    */
   askTimeoutMs?: number;
+  /**
+   * What the BUYER reads when an ask is abandoned for hanging.
+   *
+   * The hook passes the transport's own `copy.offline`, so a dead socket reads
+   * as the dropped connection it is. Optional only so a direct caller of
+   * `createPollLoop` need not thread copy it does not have.
+   */
+  askTimeoutError?: string;
   /** Poll only while `true` (e.g. after a card charge is submitted). */
   enabled?: boolean;
   /**
@@ -62,16 +71,6 @@ export interface PollingOptions {
  */
 const MAX_ERROR_BACKOFF_MS = 10_000;
 
-/**
- * How long a re-arm must stay quiet after the last ask.
- *
- * Returning to a tab commonly fires `visibilitychange` and `online` together —
- * and a shopper flicking between the bank app and the store fires them again
- * per trip. This collapses a burst into one request without delaying it: the
- * first re-arm of a burst polls immediately, the rest fall inside the gap.
- */
-const REARM_QUIET_MS = 1_000;
-
 /**
  * How long ONE status ask may take before the loop stops waiting on it.
  *
@@ -83,9 +82,10 @@ const REARM_QUIET_MS = 1_000;
 const DEFAULT_ASK_TIMEOUT_MS = 15_000;
 
 /**
- * What a timed-out ask reports. It reads as any other transport failure
- * because that is what it is to everything downstream: the counters, the
- * backoff and the stalled-wait panel treat it exactly like a 500.
+ * Last resort only, for a host that wired the loop without `askTimeoutError`.
+ * `Result.error` is what the BUYER reads — the PIX, card and wallet panels all
+ * render it verbatim — so the hook passes the transport's own `copy.offline`
+ * down and a hang reads as the dropped connection it is.
  */
 const ASK_TIMED_OUT = "timeout";
 
@@ -161,7 +161,17 @@ function newRun() {
     healthy: 0,
     startedAt: 0,
     askedAt: 0,
+    /** Live asks abandoned by a re-arm since the last answer. See `claimRearm`. */
+    supersededAsks: 0,
     timer: undefined as ReturnType<typeof setTimeout> | undefined,
+    /**
+     * The wall clock, as a timer rather than a check after an ask. `outOfTime`
+     * needs an ask to RETURN, and `askTimeout` stands down when its attempt is
+     * superseded — which every `poke` does. A shopper flicking to their bank
+     * app faster than `askTimeoutMs` refreshed it forever, so `maxWaitMs` never
+     * fired and the hosted return span with no error and no check-again button.
+     */
+    deadline: undefined as ReturnType<typeof setTimeout> | undefined,
   };
 }
 
@@ -183,7 +193,9 @@ function askTimeout(
 ): Promise<Result<OrderStatus>> {
   return new Promise((resolve) => {
     setTimeout(() => {
-      if (run.attempt === mine) resolve({ ok: false, error: ASK_TIMED_OUT });
+      if (run.attempt === mine) {
+        resolve({ ok: false, error: options.askTimeoutError ?? ASK_TIMED_OUT });
+      }
     }, options.askTimeoutMs ?? DEFAULT_ASK_TIMEOUT_MS);
   });
 }
@@ -196,6 +208,9 @@ function askTimeout(
  * it has to be consulted against the delay it is about to sleep for.
  */
 function absorb(run: PollRun, result: Result<OrderStatus>, sink: PollSink): boolean {
+  // An answer got through, so the re-arm budget is no longer being spent into
+  // a void: refill it whether the answer was an error or a status.
+  run.supersededAsks = 0;
   if (!result.ok) {
     run.errors += 1;
     sink.setError(result.error);
@@ -213,6 +228,88 @@ function absorb(run: PollRun, result: Result<OrderStatus>, sink: PollSink): bool
   return true;
 }
 
+/** Cancel whatever tick is scheduled, if any. */
+function clearPending(run: PollRun): void {
+  if (run.timer !== undefined) clearTimeout(run.timer);
+  run.timer = undefined;
+}
+
+/** Cancel the wall clock, if it is armed. */
+function clearDeadline(run: PollRun): void {
+  if (run.deadline !== undefined) clearTimeout(run.deadline);
+  run.deadline = undefined;
+}
+
+/**
+ * The wall clock, armed once per run by `restart`, so `maxWaitMs` holds whether
+ * or not an ask ever returns. `outOfTime` stays too: it ends the wait one delay
+ * EARLIER when asks ARE returning. This is the backstop for when they are not.
+ */
+function armDeadline(run: PollRun, options: PollingOptions, sink: PollSink): void {
+  clearDeadline(run);
+  if (options.maxWaitMs === undefined) return;
+  run.deadline = setTimeout(() => {
+    run.deadline = undefined;
+    if (run.cancelled || run.settled) return;
+    run.stopped = true;
+    clearPending(run);
+    sink.setTimedOut(true);
+  }, options.maxWaitMs);
+}
+
+/**
+ * One ask, bounded by {@link askTimeout} and guaranteed not to throw. `race`
+ * rejects the instant either input does, so an `ask` that throws — a host
+ * client wrapping ours — left `inFlight` true with nothing scheduled: the very
+ * wedge this file removes, through the one door the race does not close.
+ */
+async function askOnce(
+  ask: () => Promise<Result<OrderStatus>>,
+  run: PollRun,
+  mine: number,
+  options: PollingOptions,
+): Promise<Result<OrderStatus>> {
+  try {
+    return await Promise.race([ask(), askTimeout(run, mine, options)]);
+  } catch (error) {
+    const fallback = options.askTimeoutError ?? ASK_TIMED_OUT;
+    return { ok: false, error: error instanceof Error ? error.message : fallback };
+  }
+}
+
+/** Whether sleeping `delay` would carry the wait past its wall-clock bound. */
+function outOfTime(run: PollRun, options: PollingOptions, delay: number): boolean {
+  return options.maxWaitMs !== undefined && Date.now() - run.startedAt + delay >= options.maxWaitMs;
+}
+
+/**
+ * Whether this attempt's answer may still be written. A superseded one writes
+ * nothing — it may be a hung request finally answering — EXCEPT a terminal
+ * status, which is the answer the wait exists for, is idempotent, and would
+ * otherwise be dropped because a re-arm landed first.
+ */
+function mayWrite(run: PollRun, mine: number, result: Result<OrderStatus>): boolean {
+  return run.attempt === mine || (result.ok && TERMINAL_STATUSES.includes(result.data));
+}
+
+/** Book the next tick, or end the wait because its clock has run out. */
+function scheduleNext(
+  run: PollRun,
+  options: PollingOptions,
+  sink: PollSink,
+  again: () => void,
+): void {
+  const delay = pollDelay(run.healthy, run.errors, options);
+  if (outOfTime(run, options, delay)) {
+    run.stopped = true;
+    clearDeadline(run);
+    sink.setTimedOut(true);
+    return;
+  }
+  clearPending(run);
+  run.timer = setTimeout(again, delay);
+}
+
 /** The handle the hook holds on one running wait. */
 export interface PollLoop {
   /** Reset the clock and the counters, then ask immediately. */
@@ -238,13 +335,6 @@ export function createPollLoop(
 ): PollLoop {
   const run = newRun();
 
-  const clearPending = (): void => {
-    if (run.timer !== undefined) clearTimeout(run.timer);
-    run.timer = undefined;
-  };
-
-  const outOfTime = (delay: number): boolean =>
-    options.maxWaitMs !== undefined && Date.now() - run.startedAt + delay >= options.maxWaitMs;
 
   const tick = async (): Promise<void> => {
     if (run.cancelled || run.settled || run.inFlight) return;
@@ -256,27 +346,22 @@ export function createPollLoop(
     // is supposed to end after `maxWaitMs` runs forever showing "we are still
     // trying". Racing a timer turns a hang into an ordinary failed poll, which
     // the backoff and the re-arm already know how to handle.
-    const result = await Promise.race([ask(), askTimeout(run, mine, options)]);
-    // A superseded attempt writes nothing: it may be a hung request finally
-    // answering, long after a poke or a restart moved on.
-    if (run.attempt !== mine) return;
-    run.inFlight = false;
+    const result = await askOnce(ask, run, mine, options);
+    if (!mayWrite(run, mine, result)) return;
+    if (run.attempt === mine) run.inFlight = false;
     if (run.cancelled || run.settled) return;
-    if (!absorb(run, result, sink)) return;
-    const delay = pollDelay(run.healthy, run.errors, options);
-    if (outOfTime(delay)) {
-      run.stopped = true;
-      sink.setTimedOut(true);
+    if (!absorb(run, result, sink)) {
+      clearDeadline(run);
       return;
     }
-    clearPending();
-    run.timer = setTimeout(() => void tick(), delay);
+    if (run.attempt !== mine) return;
+    scheduleNext(run, options, sink, () => void tick());
   };
 
   return {
     restart: (): void => {
       if (run.cancelled || run.settled) return;
-      clearPending();
+      clearPending(run);
       // Same reasoning as `poke`, and this one is the buyer pressing a button:
       // "Verificar de novo" that cleared the panel and sent nothing — because
       // an ask was still notionally in flight — is the exact complaint.
@@ -285,25 +370,29 @@ export function createPollLoop(
       run.stopped = false;
       run.errors = 0;
       run.healthy = 0;
+      run.supersededAsks = 0;
       run.startedAt = Date.now();
+      armDeadline(run, options, sink);
       sink.setTimedOut(false);
       sink.setError(null);
       void tick();
     },
     poke: (): void => {
       if (run.cancelled || run.stopped) return;
-      if (Date.now() - run.askedAt < REARM_QUIET_MS) return;
       // Deliberately NOT gated on `inFlight`: the shopper who just came back
       // from their bank app is exactly the case where the previous ask is a
-      // socket that died while the screen was hidden. Abandon it and ask now.
+      // socket that died while the screen was hidden. Abandon it and ask now —
+      // but `claimRearm` bounds how many live asks that may abandon in a row.
+      if (!claimRearm(run)) return;
       run.attempt += 1;
       run.inFlight = false;
-      clearPending();
+      clearPending(run);
       void tick();
     },
     stop: (): void => {
       run.cancelled = true;
-      clearPending();
+      clearPending(run);
+      clearDeadline(run);
     },
   };
 }

package/src/components/checkout/poll-rearm.ts

@@ -0,0 +1,86 @@
+/**
+ * When a re-arm may abandon an ask that is still in flight (FUT-1259).
+ *
+ * `visibilitychange` and `online` drive the loop's `poke`, and both fire for
+ * the same reason the wait exists: the shopper went to their bank app and came
+ * back, and the request left behind is quite likely a socket that died while
+ * the screen was hidden. Abandoning it is right. Abandoning it EVERY time is
+ * what this module bounds.
+ */
+
+/**
+ * The state a re-arm decision reads. Structural on purpose: the poll loop's own
+ * run object satisfies it, and typing it that way keeps this module free of an
+ * import back into the loop that imports it. Module-private — the loop passes
+ * its run and never names this type, so exporting it is an unused export.
+ */
+interface RearmState {
+  inFlight: boolean;
+  askedAt: number;
+  supersededAsks: number;
+}
+
+/**
+ * How long a re-arm must stay quiet after the last ask.
+ *
+ * Returning to a tab commonly fires `visibilitychange` and `online` together —
+ * and a shopper flicking between the bank app and the store fires them again
+ * per trip. This collapses a burst into one request without delaying it: the
+ * first re-arm of a burst polls immediately, the rest fall inside the gap.
+ */
+const REARM_QUIET_MS = 1_000;
+
+/**
+ * How many live asks a re-arm may abandon before it has to let one finish.
+ *
+ * The quiet window alone looked sufficient and is not, because it is measured
+ * against the CURRENT ask rather than against the previous re-arm. Once a round
+ * trip runs longer than the window — which is the ordinary state of the flaky
+ * link this whole feature exists for — every re-arm supersedes an ask that was
+ * still alive. Nothing is ever absorbed, so `errors` never rises, so the 2.5s →
+ * 5s → 10s backoff never engages, and the wait sits near one request per window
+ * instead of decaying to one per ten.
+ *
+ * So the budget: after this many abandoned asks with no answer in between, a
+ * re-arm stands down and lets the in-flight ask either return or hit its own
+ * `askTimeoutMs`. Either outcome reaches `absorb`, which refills the budget, so
+ * this only bites while genuinely nothing is getting through.
+ *
+ * **What it does NOT bound: the re-arm rate itself.** A re-arm that finds the
+ * loop idle spends nothing, so on a link whose asks RESOLVE inside the window —
+ * a fast 500, or the immediate `TypeError: Load failed` iOS raises for a killed
+ * socket — six `online` events still cost six requests, exactly as before. That
+ * flavour is bounded by {@link REARM_QUIET_MS} alone and always was. This
+ * constant is about the ask that hangs, which is the one the quiet window
+ * could not see.
+ */
+const MAX_SUPERSEDED_ASKS = 3;
+
+/**
+ * Decide whether a re-arm may proceed, and account for it if it may.
+ *
+ * Named `claim` rather than `may…` because it MUTATES on success: a re-arm that
+ * abandons a live ask spends one of the budget above. A re-arm that finds no
+ * ask in flight — the loop is simply between ticks — spends nothing, since
+ * there is no request to amplify.
+ *
+ * That second rule is what makes a denial safe, and it is an invariant worth
+ * stating: `supersededAsks > 0` implies `inFlight`, because every transition to
+ * `inFlight === false` in a live run either passes through `absorb` (which
+ * refills) or is followed synchronously by a `tick`. So a re-arm arriving at an
+ * IDLE loop is never denied, whatever the budget reads.
+ *
+ * The cost of a denial, stated honestly: the fourth consecutive return from the
+ * bank app does NOT poll immediately. It waits for the in-flight ask to resolve
+ * or reach `askTimeoutMs` (15s by default), plus one backoff step — so worst
+ * case the buyer learns they paid roughly 17s later than they would have. That
+ * is the price of not hammering `/status` on a link that is answering nothing,
+ * and the buyer's own "Verificar de novo" (`restart`) resets the budget outright.
+ */
+export function claimRearm(run: RearmState): boolean {
+  if (Date.now() - run.askedAt < REARM_QUIET_MS) return false;
+  if (!run.inFlight) return true;
+  if (run.supersededAsks >= MAX_SUPERSEDED_ASKS) return false;
+  run.supersededAsks += 1;
+  return true;
+}

package/src/components/checkout/use-payment-polling.ts

@@ -1,6 +1,7 @@
 import { useCallback, useEffect, useRef, useState } from "react";
 
 import { useCheckoutClientApi } from "./client-context";
+import { useCheckoutCopy } from "./copy-context";
 import { createPollLoop, type PollLoop, type PollingOptions } from "./poll-loop";
 import type { OrderStatus } from "./types";
 
@@ -83,6 +84,11 @@ export function usePaymentPolling(
   // belongs in the deps below rather than being read out of a ref: a checkout
   // re-pointed at another mount must re-poll against THAT one.
   const client = useCheckoutClientApi();
+  // The buyer's own sentence for "we could not reach the server", reused for an
+  // ask abandoned for hanging. `Result.error` is rendered verbatim by the PIX,
+  // card and wallet panels, so without this a hang printed the English token
+  // `timeout` into a Portuguese screen.
+  const transportCopy = useCheckoutCopy().screens.transport;
   // The live wait, so the returned action stays stable across renders while
   // still reaching whichever loop the effect currently owns.
   const loop = useRef<PollLoop | null>(null);
@@ -92,7 +98,14 @@ export function usePaymentPolling(
 
     const running = createPollLoop(
       () => client.getStatus(orderId),
-      { intervalMs, maxWaitMs, slowAfterPolls, slowIntervalMs, askTimeoutMs },
+      {
+        intervalMs,
+        maxWaitMs,
+        slowAfterPolls,
+        slowIntervalMs,
+        askTimeoutMs,
+        askTimeoutError: transportCopy.offline,
+      },
       { setStatus, setError, setTimedOut },
     );
     loop.current = running;
@@ -104,7 +117,17 @@ export function usePaymentPolling(
       running.stop();
       loop.current = null;
     };
-  }, [orderId, intervalMs, enabled, maxWaitMs, slowAfterPolls, slowIntervalMs, askTimeoutMs, client]);
+    }, [
+    orderId,
+    intervalMs,
+    enabled,
+    maxWaitMs,
+    slowAfterPolls,
+    slowIntervalMs,
+    askTimeoutMs,
+    client,
+    transportCopy,
+  ]);
 
   const checkAgain = useCallback(() => {
     loop.current?.restart();