@12-apps/payments-frontend 3.34.2 → 3.34.3

package/package.json

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

@@ -5,9 +5,10 @@
  * Nothing here knows what the channel is. A host that can hear an order move —
  * a signed-in buyer's own topic, say — passes whether that channel is live and
  * a way to be told when it fires; every wait under the provider then asks the
- * moment it fires and slows its own timer while the channel is live. A tree with
- * no provider, or a host that passes `live: false` (a guest, who has no channel
- * of their own), polls exactly as before.
+ * moment it fires, and keeps no timer of its own while the channel is live
+ * (FUT-3223, `poll-live.ts`). A tree with no provider, or a host that passes
+ * `live: false` (a guest, who has no channel of their own), polls exactly as
+ * before.
  *
  * The hint carries nothing and is never trusted as an answer: it only makes the
  * wait ask `/status` now. The endpoint stays the truth.
@@ -26,14 +27,19 @@ export interface CheckoutLiveSignal {
    * unsubscribe. Should be stable across renders: a new function re-subscribes.
    */
   subscribe: (onHint: () => void) => () => void;
-  /** The wait's healthy delay while live (ms). Defaults to {@link DEFAULT_LIVE_INTERVAL_MS}. */
+  /**
+   * The healthy delay while live (ms) for the one wait that keeps reading while
+   * live: a hosted-checkout return carrying the settlement pair (`poll-live.ts`).
+   * Every other wait keeps no timer while live. Defaults to
+   * {@link DEFAULT_LIVE_INTERVAL_MS}.
+   */
   liveIntervalMs?: number;
 }
 
 /**
- * The floor under a lost hint while the channel is live: the same 15 s the PIX
- * wait already backs off to, so a wait whose channel is up never asks faster
- * than the slowest wait it would have become anyway.
+ * The floor a hosted-checkout return keeps while the channel is live: the same
+ * 15 s the PIX wait already backs off to, so a wait whose channel is up never
+ * asks faster than the slowest wait it would have become anyway.
  */
 export const DEFAULT_LIVE_INTERVAL_MS = 15_000;
 
@@ -61,9 +67,16 @@ type LoopRef = { readonly current: PollLoop | null };
 /**
  * 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.
+ * after may have been answered before the drop, and a live wait books no next
+ * tick, so declining for good would leave the buyer waiting with nobody left
+ * to wake them.
+ *
+ * A channel that (RE-)OPENS does not come here either: it is taken as a HINT
+ * (FUT-3223). A hint sent while the channel was down was never heard, and a
+ * live wait has no timer to catch it, so the open is the re-read that bounds a
+ * lost hint — and `PollLoop.hint` never drops it: with an ask in flight it
+ * owes one more the moment that ask answers, where a declined poke could leave
+ * a pre-open answer as the last word.
  *
  * 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.
@@ -75,9 +88,10 @@ function wake(loop: LoopRef, pending: { timer?: ReturnType<typeof setTimeout> })
 }
 
 /**
- * Tie one wait to the host's channel: a hint asks now, and a channel that
- * DROPS asks now too — the timer may be sleeping out the live floor, and the
- * buyer should not wait the rest of it with nobody left to wake them.
+ * Tie one wait to the host's channel: a hint asks now, a channel that DROPS
+ * asks now too (see {@link wake}), and a channel that (RE-)OPENS is taken as a
+ * hint. The channel's state at mount needs no ask of its own: the wait's first
+ * ask is already that read.
  *
  * `loop` is the hook's own ref to its running loop, read when the event lands.
  */
@@ -92,6 +106,7 @@ export function useLiveWait(loop: LoopRef): LiveWait {
     const was = liveRef.current;
     liveRef.current = live;
     if (was && !live) wake(loop, pending.current);
+    else if (!was && live) loop.current?.hint();
   }, [live, loop]);
 
   useEffect(() => {

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

@@ -1,14 +1,29 @@
 /**
  * The cadence a payment wait keeps while the host HEARS the order move
- * (FUT-649).
+ * (FUT-649, FUT-3223).
  *
  * The wait asks `/status` every 2.5 s because, on its own, asking is the only
  * way it can learn that a webhook settled the order in another process. A host
  * that holds a realtime channel for this buyer already learns it the moment it
  * happens — `CheckoutLiveProvider` hands that hint in and the wait asks at once.
- * While that channel is live the timer is only the floor under a lost hint, so
- * it slows to {@link LiveCadence.liveIntervalMs}; the moment the channel drops,
- * the ordinary cadence is back on the next tick.
+ * So while that channel is live a healthy answer books NO timer: the wait asks
+ * on a hint, on `visibilitychange`/`online`, and when the channel opens or
+ * re-opens — a screen hears live data over the socket and polls only while the
+ * socket is down. The host's server owns what a timer used to catch: a lapsed
+ * code and a webhook that never came are found server-side and published to
+ * the same channel. The moment the channel drops, the ordinary cadence is back.
+ *
+ * Two exceptions keep a timer while live:
+ *
+ * - A FAILED ask is a read that did not happen, not a check for news, so it
+ *   retries on the ordinary error backoff (`poll-delay.ts`: 2.5 s, 5 s, then
+ *   every 10 s), as a wait with no channel does — no longer stretched to the
+ *   15 s live floor. Otherwise a hint whose ask hit a 500 would leave a paid
+ *   buyer waiting for a second hint that is never sent.
+ * - A wait given {@link LiveCadence.liveIntervalMs} keeps that floor. The hook
+ *   gives it one only on a hosted-checkout return carrying the settlement pair
+ *   (`carriesSettlementPair`), where the buyer's own read is what confirms the
+ *   payment and no server sweep can stand in for it.
  *
  * Split out of `poll-loop.ts` so the loop stays one question: WHEN to ask. This
  * file answers only how being live changes that answer.
@@ -21,12 +36,21 @@ export interface LiveCadence {
    */
   isLive?: () => boolean;
   /**
-   * The healthy delay while live (ms). A floor, never a speed-up: a slower
-   * cadence already in force (the PIX backoff) is kept.
+   * The healthy delay while live (ms), for a wait that must keep reading while
+   * live (see the module docblock). A floor, never a speed-up: a slower cadence
+   * already in force (the PIX backoff) is kept. Undefined: no timer while live.
    */
   liveIntervalMs?: number;
 }
 
+/**
+ * Whether the wait books nothing after this answer and waits to be told: a
+ * healthy answer, while live, for a wait with no live floor.
+ */
+export function idlesWhileLive(errors: number, options: LiveCadence): boolean {
+  return errors === 0 && options.liveIntervalMs === undefined && options.isLive?.() === true;
+}
+
 /** `delay`, stretched to the live floor while the host's channel is live. */
 export function withLive(delay: number, options: LiveCadence): number {
   if (options.liveIntervalMs === undefined || options.isLive?.() !== true) return delay;

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

@@ -1,6 +1,6 @@
 import type { Result } from "../../result";
 import { pollDelay } from "./poll-delay";
-import { waitsForDeadline, type LiveCadence } from "./poll-live";
+import { idlesWhileLive, waitsForDeadline, type LiveCadence } from "./poll-live";
 import { claimHint, owedAfterAnswer } from "./poll-hint";
 import { claimRearm } from "./poll-rearm";
 import { TERMINAL_STATUSES, type OrderStatus } from "./types";
@@ -254,13 +254,19 @@ function mayWrite(run: PollRun, mine: number, result: Result<OrderStatus>): bool
   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. */
+/**
+ * Book the next tick, or end the wait because its clock has run out — or, live
+ * with a healthy answer, book nothing: the hint, the re-arm events and the
+ * channel re-opening are what ask next (`poll-live.ts`, FUT-3223).
+ */
 function scheduleNext(
   run: PollRun,
   options: PollingOptions,
   sink: PollSink,
   again: () => void,
 ): void {
+  clearPending(run);
+  if (idlesWhileLive(run.errors, options)) return;
   const delay = pollDelay(run.healthy, run.errors, options);
   if (outOfTime(run, options, delay)) {
     run.stopped = true;
@@ -268,7 +274,6 @@ function scheduleNext(
     sink.setTimedOut(true);
     return;
   }
-  clearPending(run);
   run.timer = setTimeout(again, delay);
 }
 

package/src/components/checkout/transport.ts

@@ -152,6 +152,16 @@ function refused<T>(json: ApiEnvelope<T> | null, copy: CheckoutTransportCopy): R
   return err(json?.error ?? copy.failed, json?.code);
 }
 
+/**
+ * Whether this page is a hosted-checkout return carrying the WHOLE settlement
+ * pair — the one case where a `/status` read is itself what confirms the
+ * payment, so a live wait keeps reading on its floor (FUT-3223, `poll-live.ts`).
+ */
+export function carriesSettlementPair(): boolean {
+  const { transactionNsu, slug } = returnedSettlement();
+  return Boolean(transactionNsu && slug);
+}
+
 /**
  * What a hosted checkout appended to the return URL when it sent the buyer
  * back, or undefined.

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

@@ -4,6 +4,7 @@ import { useCheckoutClientApi } from "./client-context";
 import { useCheckoutCopy } from "./copy-context";
 import { createPollLoop, type PollLoop, type PollingOptions, type PollSink } from "./poll-loop";
 import { useLiveWait } from "./live-context";
+import { carriesSettlementPair } from "./transport";
 import type { OrderStatus } from "./types";
 
 /** What a consumer reads off the wait, and the one action it can take. */
@@ -110,6 +111,10 @@ function listenForRearm(poke: () => void): () => void {
  * QR under a red alert with no retry, a card spinner replaced by one, and the
  * hosted return spinning forever. None of the three could recover on its own,
  * which is what made a blip cost a payment nobody was ever told about.
+ *
+ * WHILE LIVE it keeps no timer (FUT-3223, `poll-live.ts`), except on a hosted
+ * return carrying the settlement pair, where the read itself confirms the
+ * payment and the live floor is kept.
  */
 export function usePaymentPolling(
   orderId: string | null,
@@ -149,7 +154,8 @@ export function usePaymentPolling(
         slowIntervalMs,
         askTimeoutMs,
         askTimeoutError: transportCopy.offline,
-        ...{ isLive, liveIntervalMs },
+        isLive,
+        liveIntervalMs: carriesSettlementPair() ? liveIntervalMs : undefined,
       },
       sinkFor(orderId, setAnswer),
     );