@12-apps/payments-frontend 3.29.0 → 3.29.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.29.0",
+  "version": "3.29.1",
   "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/live-context.tsx

@@ -59,11 +59,14 @@ interface LiveWait {
 type LoopRef = { readonly current: PollLoop | null };
 
 /**
- * Ask now — and if the loop declines because it asked a moment ago, ask again
- * once that quiet window is over. The window exists so a flapping network does
- * not stampede `/status`; a hint is different, because the ask it lands just
- * after may have been answered BEFORE the order moved. Dropping it would leave
- * the buyer on the live floor with the news already sent.
+ * A channel that DROPS: ask now — and if the loop declines because it asked a
+ * moment ago, ask again once that quiet window is over. The ask it lands just
+ * after may have been answered before the drop, and its next tick sleeps out
+ * the live floor, so declining for good would leave the buyer waiting with
+ * nobody left to wake them.
+ *
+ * A HINT does not come here. It is `PollLoop.hint` (FUT-3205): deferring a
+ * hint by the quiet window cost a paid buyer a full second on the pay step.
  */
 function wake(loop: LoopRef, pending: { timer?: ReturnType<typeof setTimeout> }): void {
   if (loop.current?.poke() !== false) return;
@@ -94,7 +97,7 @@ export function useLiveWait(loop: LoopRef): LiveWait {
   useEffect(() => {
     if (!subscribe) return undefined;
     const retry = pending.current;
-    const unsubscribe = subscribe(() => wake(loop, retry));
+    const unsubscribe = subscribe(() => loop.current?.hint());
     return () => {
       unsubscribe();
       clearTimeout(retry.timer);

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

@@ -0,0 +1,54 @@
+import { withLive } from "./poll-live";
+import type { PollingOptions } from "./poll-loop";
+
+/**
+ * How long a payment wait sleeps before its next ask — pure functions of the
+ * options and the run's counters, split out of `poll-loop.ts` so the loop
+ * stays one question: WHEN to ask, not how long.
+ */
+
+/**
+ * The slowest a failing poll may go (FUT-1144).
+ *
+ * Consecutive failures double the delay — 2.5 s, 5 s, 10 s — and stop there.
+ * The cap is what keeps the recovery cheap: a shopper whose signal comes back
+ * during a Wi-Fi→4G handoff waits at most this long to be told they paid, and
+ * the re-arm events (`poll-rearm.ts`) usually beat it outright.
+ */
+const MAX_ERROR_BACKOFF_MS = 10_000;
+
+/**
+ * How long before the next ask, given how many healthy polls have happened.
+ *
+ * A pure function of the options, so it lives out here rather than inside the
+ * effect — the hook is at its size gate, and a scheduling RULE is easier to
+ * read (and to test) stated once than threaded through a closure.
+ *
+ * Reads the count AFTER the poll just made, so the slow phase begins on the
+ * poll FOLLOWING the threshold rather than one early: a wait described as "N
+ * fast polls" has to actually make N of them.
+ */
+function healthyDelay(healthy: number, options: PollingOptions): number {
+  const { intervalMs = 2500, slowAfterPolls, slowIntervalMs } = options;
+  const backingOff =
+    slowAfterPolls !== undefined && slowIntervalMs !== undefined && healthy >= slowAfterPolls;
+  return withLive(backingOff ? slowIntervalMs : intervalMs, options);
+}
+
+/**
+ * The same rule with consecutive FAILURES folded in (FUT-1144).
+ *
+ * Errors never stop the wait, they only slow it. Doubling from the healthy
+ * cadence is what makes a ten-second blip cost one extra beat instead of the
+ * whole confirmation: four failures used to be terminal, and four failures is
+ * what a Wi-Fi→4G handoff produces at the default 2.5 s.
+ *
+ * The cap is `MAX_ERROR_BACKOFF_MS` or the healthy cadence, whichever is
+ * larger — a failing poll must never ask FASTER than a succeeding one, which
+ * is what a bare cap would do to a consumer whose slow interval is longer.
+ */
+export function pollDelay(healthy: number, errors: number, options: PollingOptions): number {
+  const base = healthyDelay(healthy, options);
+  if (errors === 0) return base;
+  return Math.min(base * 2 ** (errors - 1), Math.max(base, MAX_ERROR_BACKOFF_MS));
+}

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

@@ -0,0 +1,58 @@
+import { claimRearm, REARM_QUIET_MS } from "./poll-rearm";
+
+/**
+ * What a realtime hint does to a running payment wait (FUT-3205).
+ *
+ * A hint is NOT a re-arm. `poke`'s quiet window exists to collapse
+ * `visibilitychange` and `online` bursts, and a hint is a server fact.
+ * Deferring it by that window cost a paid buyer a full second on the pay step
+ * (P-040: the hint at 12,145 ms, the second read at 13,148 ms). So, by the
+ * loop's state:
+ *
+ * - The wait ended (settled, stopped, cancelled): nothing (FUT-1144).
+ * - No ask in flight: ask now.
+ * - An ask in flight for `REARM_QUIET_MS` or longer: supersede it the way
+ *   `poke` does, within `claimRearm`'s budget — the hung-socket case (FUT-1259).
+ * - Otherwise, or with that budget spent: keep the ask and MARK the run. One
+ *   more ask is owed the moment it answers non-terminal, so a hint is never
+ *   dropped (FUT-649), and a burst of hints during one ask costs one extra ask.
+ *
+ * The mark is cleared by `restart`, by a `poke` that supersedes the marked
+ * ask, by sending its follow-up and by a terminal answer. The deadline does
+ * NOT clear it: a marked ask answering after the deadline is caught by
+ * {@link owedAfterAnswer} and neither asks nor schedules.
+ *
+ * Structural state, as in `poll-rearm.ts`: the loop's run satisfies it.
+ */
+interface HintState {
+  cancelled: boolean;
+  settled: boolean;
+  stopped: boolean;
+  inFlight: boolean;
+  askedAt: number;
+  supersededAsks: number;
+  hinted: boolean;
+}
+
+/** Take a hint: whether the loop must ask now. Marks the run when it may not. */
+export function claimHint(run: HintState): boolean {
+  if (run.cancelled || run.settled || run.stopped) return false;
+  const young = run.inFlight && Date.now() - run.askedAt < REARM_QUIET_MS;
+  if (!run.inFlight || (!young && claimRearm(run))) {
+    run.hinted = false;
+    return true;
+  }
+  run.hinted = true;
+  return false;
+}
+
+/**
+ * After a non-terminal answer: `"ask"` when a mark owes one more ask now,
+ * `"ended"` when the wait stopped while that ask was out, `"none"` when nothing
+ * is owed and the loop schedules as usual. Clears the mark.
+ */
+export function owedAfterAnswer(run: Pick<HintState, "hinted" | "stopped">): "ask" | "ended" | "none" {
+  if (!run.hinted) return "none";
+  run.hinted = false;
+  return run.stopped ? "ended" : "ask";
+}

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

@@ -1,5 +1,7 @@
 import type { Result } from "../../result";
-import { waitsForDeadline, withLive, type LiveCadence } from "./poll-live";
+import { pollDelay } from "./poll-delay";
+import { waitsForDeadline, type LiveCadence } from "./poll-live";
+import { claimHint, owedAfterAnswer } from "./poll-hint";
 import { claimRearm } from "./poll-rearm";
 import { TERMINAL_STATUSES, type OrderStatus } from "./types";
 
@@ -64,16 +66,6 @@ export interface PollingOptions extends LiveCadence {
   slowIntervalMs?: number;
 }
 
-/**
- * The slowest a failing poll may go (FUT-1144).
- *
- * Consecutive failures double the delay — 2.5 s, 5 s, 10 s — and stop there.
- * The cap is what keeps the recovery cheap: a shopper whose signal comes back
- * during a Wi-Fi→4G handoff waits at most this long to be told they paid, and
- * the two re-arm events below usually beat it outright.
- */
-const MAX_ERROR_BACKOFF_MS = 10_000;
-
 /**
  * How long ONE status ask may take before the loop stops waiting on it.
  *
@@ -92,42 +84,6 @@ const DEFAULT_ASK_TIMEOUT_MS = 15_000;
  */
 const ASK_TIMED_OUT = "timeout";
 
-/**
- * How long before the next ask, given how many healthy polls have happened.
- *
- * A pure function of the options, so it lives out here rather than inside the
- * effect — the hook is at its size gate, and a scheduling RULE is easier to
- * read (and to test) stated once than threaded through a closure.
- *
- * Reads the count AFTER the poll just made, so the slow phase begins on the
- * poll FOLLOWING the threshold rather than one early: a wait described as "N
- * fast polls" has to actually make N of them.
- */
-function healthyDelay(healthy: number, options: PollingOptions): number {
-  const { intervalMs = 2500, slowAfterPolls, slowIntervalMs } = options;
-  const backingOff =
-    slowAfterPolls !== undefined && slowIntervalMs !== undefined && healthy >= slowAfterPolls;
-  return withLive(backingOff ? slowIntervalMs : intervalMs, options);
-}
-
-/**
- * The same rule with consecutive FAILURES folded in (FUT-1144).
- *
- * Errors never stop the wait, they only slow it. Doubling from the healthy
- * cadence is what makes a ten-second blip cost one extra beat instead of the
- * whole confirmation: four failures used to be terminal, and four failures is
- * what a Wi-Fi→4G handoff produces at the default 2.5 s.
- *
- * The cap is `MAX_ERROR_BACKOFF_MS` or the healthy cadence, whichever is
- * larger — a failing poll must never ask FASTER than a succeeding one, which
- * is what a bare cap would do to a consumer whose slow interval is longer.
- */
-function pollDelay(healthy: number, errors: number, options: PollingOptions): number {
-  const base = healthyDelay(healthy, options);
-  if (errors === 0) return base;
-  return Math.min(base * 2 ** (errors - 1), Math.max(base, MAX_ERROR_BACKOFF_MS));
-}
-
 /** Where a running wait writes what it has learned. */
 export interface PollSink {
   setStatus: (status: OrderStatus) => void;
@@ -166,6 +122,8 @@ function newRun() {
     askedAt: 0,
     /** Live asks abandoned by a re-arm since the last answer. See `claimRearm`. */
     supersededAsks: 0,
+    /** A hint owes one more ask once the one in flight answers. See `poll-hint.ts`. */
+    hinted: false,
     timer: undefined as ReturnType<typeof setTimeout> | undefined,
     /**
      * The wall clock, as a timer rather than a check after an ask. `outOfTime`
@@ -314,12 +272,29 @@ function scheduleNext(
   run.timer = setTimeout(again, delay);
 }
 
+/** Abandon whatever ask is current and ask now, keeping the clock. */
+function askNow(run: PollRun, tick: () => Promise<void>): void {
+  run.attempt += 1;
+  run.inFlight = false;
+  clearPending(run);
+  void tick();
+}
+
+/** After a non-terminal answer: the ask a hint owes, or the usual schedule. */
+function continueAfter(run: PollRun, tick: () => Promise<void>, schedule: () => void): void {
+  const owed = owedAfterAnswer(run);
+  if (owed === "ask") askNow(run, tick);
+  else if (owed === "none") schedule();
+}
+
 /** The handle the hook holds on one running wait. */
 export interface PollLoop {
   /** Reset the clock and the counters, then ask immediately. */
   restart: () => void;
   /** Ask immediately, keeping the clock — the re-arm events' entry point. Whether it asked. */
   poke: () => boolean;
+  /** A realtime hint: ask now, or owe one ask after the current one (`poll-hint.ts`, FUT-3205). */
+  hint: () => void;
   /** Tear down: nothing further is scheduled and nothing further is written. */
   stop: () => void;
 }
@@ -353,11 +328,12 @@ export function createPollLoop(
     if (run.attempt === mine) run.inFlight = false;
     if (run.cancelled || run.settled) return;
     if (!absorb(run, result, sink)) {
+      run.hinted = false;
       clearDeadline(run);
       return;
     }
     if (run.attempt !== mine) return;
-    scheduleNext(run, options, sink, () => void tick());
+    continueAfter(run, tick, () => scheduleNext(run, options, sink, () => void tick()));
   };
 
   return {
@@ -372,6 +348,7 @@ export function createPollLoop(
       run.errors = 0;
       run.healthy = 0;
       run.supersededAsks = 0;
+      run.hinted = false;
       run.startedAt = Date.now();
       armDeadline(run, options, sink);
       sink.setTimedOut(false);
@@ -385,12 +362,14 @@ export function createPollLoop(
       // 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 false;
-      run.attempt += 1;
-      run.inFlight = false;
-      clearPending(run);
-      void tick();
+      // The new ask is sent after any hint that marked the old one.
+      run.hinted = false;
+      askNow(run, tick);
       return true;
     },
+    hint: (): void => {
+      if (claimHint(run)) askNow(run, tick);
+    },
     stop: (): void => {
       run.cancelled = true;
       clearPending(run);