@12-apps/payments-frontend 3.24.1 → 3.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.24.1",
+  "version": "3.26.0",
   "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/checkout-flow.tsx

@@ -95,6 +95,11 @@ export interface CheckoutFlowProps extends CheckoutHostPorts {
   validateApplePayMerchant?: (validationURL: string) => Promise<unknown>;
   /** Host content shown on the paid confirmation (the storefront's install invite). */
   confirmationExtra?: ReactNode;
+  /**
+   * Host illustration that replaces the paid confirmation's icon —
+   * `PaymentStatusProps.paidHero`: pass it only when there is one, and mark it `aria-hidden`.
+   */
+  confirmationHero?: ReactNode;
   /** Host content shown AFTER the confirmation's actions — `PaymentStatusProps.paidFooter`. */
   confirmationFooter?: ReactNode;
   /** Whether the way out leads the paid screen — see {@link BackActionEmphasis}. */
@@ -185,6 +190,7 @@ function StatusStep({
   settlement,
   cart,
   confirmationExtra,
+  confirmationHero,
   confirmationFooter,
   backActionEmphasis,
 }: {
@@ -193,6 +199,7 @@ function StatusStep({
   settlement: SettlementCheckout | null | undefined;
   cart: CheckoutCartView;
   confirmationExtra: ReactNode;
+  confirmationHero: ReactNode;
   confirmationFooter: ReactNode;
   backActionEmphasis: BackActionEmphasis | undefined;
 }): JSX.Element {
@@ -206,6 +213,7 @@ function StatusStep({
       onRegenerate={() => { c.setStep("payment"); void c.startPayment("PIX"); }}
       onBackToMenu={c.goToMenu}
       paidExtra={confirmationExtra}
+      paidHero={confirmationHero}
       paidFooter={confirmationFooter}
       backActionEmphasis={backActionEmphasis}
       awaitingTimedOut={c.awaitingTimedOut}
@@ -308,7 +316,7 @@ function PagamentoStep({
 }
 
 function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Element {
-  const { copy, cart, defaultBuyer, settlement, taxIdOnFile = false, providerConfig, tenantSlug, confirmationExtra, confirmationFooter, backActionEmphasis, validateApplePayMerchant, oneClick = false, ...ports } = props;
+  const { copy, cart, defaultBuyer, settlement, taxIdOnFile = false, providerConfig, tenantSlug, confirmationExtra, confirmationHero, confirmationFooter, backActionEmphasis, validateApplePayMerchant, oneClick = false, ...ports } = props;
   // Resolved for NO method on purpose (FUT-595): the Dados step opens before
   // the picker, and the form is filled once — so it asks for the union of what
   // any chain member may need rather than re-opening after the choice. A chain
@@ -365,7 +373,7 @@ function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Ele
       ) : null}
 
       {c.step === "status" ? (
-        <StatusStep copy={copy} c={c} settlement={settlement} cart={cart} confirmationExtra={confirmationExtra} confirmationFooter={confirmationFooter} backActionEmphasis={backActionEmphasis} />
+        <StatusStep copy={copy} c={c} settlement={settlement} cart={cart} confirmationExtra={confirmationExtra} confirmationHero={confirmationHero} confirmationFooter={confirmationFooter} backActionEmphasis={backActionEmphasis} />
       ) : null}
     </Box>
   );

package/src/components/checkout/live-context.tsx

@@ -0,0 +1,108 @@
+/**
+ * The host's realtime channel for THIS buyer, handed to every payment wait
+ * below it (FUT-649).
+ *
+ * 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.
+ *
+ * The hint carries nothing and is never trusted as an answer: it only makes the
+ * wait ask `/status` now. The endpoint stays the truth.
+ */
+import { createContext, useCallback, useContext, useEffect, useRef, type JSX, type ReactNode } from "react";
+
+import type { PollLoop } from "./poll-loop";
+import { REARM_QUIET_MS } from "./poll-rearm";
+
+/** What a host hands the checkout about its own realtime channel. */
+export interface CheckoutLiveSignal {
+  /** Whether the channel is connected right now. */
+  live: boolean;
+  /**
+   * Be told when the channel says this buyer's orders moved. Returns the
+   * 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}. */
+  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.
+ */
+export const DEFAULT_LIVE_INTERVAL_MS = 15_000;
+
+const CheckoutLiveContext = createContext<CheckoutLiveSignal | null>(null);
+
+/** Hand every payment wait below the host's channel. */
+export function CheckoutLiveProvider({
+  signal,
+  children,
+}: {
+  signal: CheckoutLiveSignal;
+  children: ReactNode;
+}): JSX.Element {
+  return <CheckoutLiveContext.Provider value={signal}>{children}</CheckoutLiveContext.Provider>;
+}
+
+/** What one wait reads off the provider, for `createPollLoop`. */
+interface LiveWait {
+  isLive: () => boolean;
+  liveIntervalMs: number;
+}
+
+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.
+ */
+function wake(loop: LoopRef, pending: { timer?: ReturnType<typeof setTimeout> }): void {
+  if (loop.current?.poke() !== false) return;
+  clearTimeout(pending.timer);
+  pending.timer = setTimeout(() => loop.current?.poke(), REARM_QUIET_MS);
+}
+
+/**
+ * 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.
+ *
+ * `loop` is the hook's own ref to its running loop, read when the event lands.
+ */
+export function useLiveWait(loop: LoopRef): LiveWait {
+  const signal = useContext(CheckoutLiveContext);
+  const live = signal?.live === true;
+  const liveRef = useRef(live);
+  const pending = useRef<{ timer?: ReturnType<typeof setTimeout> }>({});
+  const subscribe = signal?.subscribe;
+
+  useEffect(() => {
+    const was = liveRef.current;
+    liveRef.current = live;
+    if (was && !live) wake(loop, pending.current);
+  }, [live, loop]);
+
+  useEffect(() => {
+    if (!subscribe) return undefined;
+    const retry = pending.current;
+    const unsubscribe = subscribe(() => wake(loop, retry));
+    return () => {
+      unsubscribe();
+      clearTimeout(retry.timer);
+    };
+  }, [subscribe, loop]);
+
+  // Stable, so the loop's deps do not churn: the loop reads the flag when it
+  // schedules, and a flip must never restart the wait's wall clock.
+  const isLive = useCallback(() => liveRef.current, []);
+  return { isLive, liveIntervalMs: signal?.liveIntervalMs ?? DEFAULT_LIVE_INTERVAL_MS };
+}

package/src/components/checkout/payment-status-parts.tsx

@@ -1,5 +1,5 @@
 import { Box } from "@mui/material";
-import type { JSX } from "react";
+import type { JSX, ReactNode } from "react";
 
 import { CheckCircleOutlineIcon, ErrorOutlineIcon, ScheduleIcon } from "./icons";
 import type { CheckoutDecline } from "./decline";
@@ -120,17 +120,27 @@ function failedOutcome(copy: PaymentStatusCopy, decline: CheckoutDecline | null)
   return (reason ? copy.declined?.[reason] : undefined) ?? copy.failed;
 }
 
-/** The headline block: icon, outcome, and one supporting line. */
+/**
+ * The headline block: icon, outcome, and one supporting line.
+ *
+ * `hero` replaces the PAID icon with the host's own illustration — a store's
+ * mascot celebrating the order, say — and only the icon: the heading and the
+ * support line stay the package's. Every other status keeps its icon, because
+ * a host celebrating a payment that failed would be telling the buyer the
+ * opposite of what happened.
+ */
 export function OutcomeHero({
   copy,
   status,
   wait,
   decline,
+  hero,
 }: {
   copy: PaymentStatusCopy;
   status: OrderStatus;
   wait: WaitState;
   decline: CheckoutDecline | null;
+  hero?: ReactNode;
 }): JSX.Element {
   const { Text } = useCheckoutComponents();
   const face = status === "AWAITING_PAYMENT" ? awaitingFace(copy, wait) : null;
@@ -154,7 +164,13 @@ export function OutcomeHero({
       }
       sx={{ display: "flex", flexDirection: "column", alignItems: "center", gap: 1, textAlign: "center" }}
     >
-      <Box sx={{ color: TONE_COLOR[visual.tone], display: "flex" }}>{visual.icon}</Box>
+      {status === "PAID" && hero ? (
+        <Box data-testid="payment-paid-hero" sx={{ display: "flex" }}>
+          {hero}
+        </Box>
+      ) : (
+        <Box sx={{ color: TONE_COLOR[visual.tone], display: "flex" }}>{visual.icon}</Box>
+      )}
       <Text variant="heading" size="md" weight="bold" as="h2">
         {outcome.heading}
       </Text>

package/src/components/checkout/payment-status.tsx

@@ -56,6 +56,16 @@ interface PaymentStatusProps {
    * is the difference between an offer and an interruption.
    */
   paidExtra?: ReactNode;
+  /**
+   * Host content that REPLACES the PAID icon at the top of the screen — the
+   * storefront's mascot celebrating a buyer's first order or birthday. Absent,
+   * the screen is exactly what it was. Never shown on any other status.
+   *
+   * Pass it only when there is something to show (`cond ? <Mascot /> : undefined`):
+   * an element that renders nothing still replaces the icon. It is decorative —
+   * the heading beside it says what happened — so mark it `aria-hidden`.
+   */
+  paidHero?: ReactNode;
   /**
    * Host content rendered AFTER the action row, and ONLY on PAID.
    *
@@ -182,7 +192,13 @@ export function PaymentStatus(props: PaymentStatusProps): JSX.Element {
       data-timed-out={view.wait.timedOut ? "true" : undefined}
       sx={{ display: "flex", flexDirection: "column", gap: 3, alignItems: "stretch", py: 2 }}
     >
-      <OutcomeHero copy={copy} status={view.effective} wait={view.wait} decline={view.decline} />
+      <OutcomeHero
+        copy={copy}
+        status={view.effective}
+        wait={view.wait}
+        decline={view.decline}
+        hero={props.paidHero}
+      />
 
       {view.paid ? (
         <PaidFacts copy={copy} totalLabel={totalLabel} orderId={orderId} buyerEmail={buyerEmail} />

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

@@ -0,0 +1,46 @@
+/**
+ * The cadence a payment wait keeps while the host HEARS the order move
+ * (FUT-649).
+ *
+ * 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.
+ *
+ * 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.
+ */
+export interface LiveCadence {
+  /**
+   * Whether the host's channel is live right now. Read at every scheduling
+   * decision rather than once, so a channel that drops mid-wait takes effect
+   * at the next tick instead of at the next restart.
+   */
+  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.
+   */
+  liveIntervalMs?: number;
+}
+
+/** `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;
+  return Math.max(delay, options.liveIntervalMs);
+}
+
+/**
+ * Whether the wait must stay open until its wall clock actually strikes.
+ *
+ * The loop normally ends one sleep EARLY when that sleep would cross
+ * `maxWaitMs` — nothing could land in it. While live, something can: the hint.
+ * Ending early there would hand a 90 s card wait over at 75 s and then refuse
+ * the hint that arrives at 80 s, so the armed deadline ends it instead.
+ */
+export function waitsForDeadline(options: LiveCadence): boolean {
+  return options.isLive?.() === true;
+}

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

@@ -1,4 +1,5 @@
 import type { Result } from "../../result";
+import { waitsForDeadline, withLive, type LiveCadence } from "./poll-live";
 import { claimRearm } from "./poll-rearm";
 import { TERMINAL_STATUSES, type OrderStatus } from "./types";
 
@@ -11,7 +12,7 @@ import { TERMINAL_STATUSES, type OrderStatus } from "./types";
  * attempt counter that lets a hung request be abandoned rather than waited on.
  */
 
-export interface PollingOptions {
+export interface PollingOptions extends LiveCadence {
   /** Delay between successful polls (ms). */
   intervalMs?: number;
   /**
@@ -106,7 +107,7 @@ function healthyDelay(healthy: number, options: PollingOptions): number {
   const { intervalMs = 2500, slowAfterPolls, slowIntervalMs } = options;
   const backingOff =
     slowAfterPolls !== undefined && slowIntervalMs !== undefined && healthy >= slowAfterPolls;
-  return backingOff ? slowIntervalMs : intervalMs;
+  return withLive(backingOff ? slowIntervalMs : intervalMs, options);
 }
 
 /**
@@ -281,7 +282,8 @@ async function askOnce(
 
 /** 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;
+  if (options.maxWaitMs === undefined || waitsForDeadline(options)) return false;
+  return Date.now() - run.startedAt + delay >= options.maxWaitMs;
 }
 
 /**
@@ -316,8 +318,8 @@ function scheduleNext(
 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. */
-  poke: () => void;
+  /** Ask immediately, keeping the clock — the re-arm events' entry point. Whether it asked. */
+  poke: () => boolean;
   /** Tear down: nothing further is scheduled and nothing further is written. */
   stop: () => void;
 }
@@ -336,8 +338,6 @@ export function createPollLoop(
   sink: PollSink,
 ): PollLoop {
   const run = newRun();
-
-
   const tick = async (): Promise<void> => {
     if (run.cancelled || run.settled || run.inFlight) return;
     run.inFlight = true;
@@ -364,9 +364,8 @@ export function createPollLoop(
     restart: (): void => {
       if (run.cancelled || run.settled) return;
       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.
+      // Same reasoning as `poke`, and this one is the buyer pressing a button: "Verificar
+      // de novo" that cleared the panel and sent nothing (an ask was in flight) is the complaint.
       run.attempt += 1;
       run.inFlight = false;
       run.stopped = false;
@@ -379,17 +378,18 @@ export function createPollLoop(
       sink.setError(null);
       void tick();
     },
-    poke: (): void => {
-      if (run.cancelled || run.stopped) return;
+    poke: (): boolean => {
+      if (run.cancelled || run.stopped) return false;
       // 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 —
       // but `claimRearm` bounds how many live asks that may abandon in a row.
-      if (!claimRearm(run)) return;
+      if (!claimRearm(run)) return false;
       run.attempt += 1;
       run.inFlight = false;
       clearPending(run);
       void tick();
+      return true;
     },
     stop: (): void => {
       run.cancelled = true;

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

@@ -28,7 +28,7 @@ interface RearmState {
  * 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;
+export const REARM_QUIET_MS = 1_000;
 
 /**
  * How many live asks a re-arm may abandon before it has to let one finish.

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

@@ -3,6 +3,7 @@ import { useCallback, useEffect, useRef, useState, type Dispatch, type SetStateA
 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 type { OrderStatus } from "./types";
 
 /** What a consumer reads off the wait, and the one action it can take. */
@@ -134,6 +135,7 @@ export function usePaymentPolling(
   // 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);
+  const { isLive, liveIntervalMs } = useLiveWait(loop); // FUT-649
 
   useEffect(() => {
     if (!orderId || !enabled) return undefined;
@@ -147,6 +149,7 @@ export function usePaymentPolling(
         slowIntervalMs,
         askTimeoutMs,
         askTimeoutError: transportCopy.offline,
+        ...{ isLive, liveIntervalMs },
       },
       sinkFor(orderId, setAnswer),
     );
@@ -169,6 +172,7 @@ export function usePaymentPolling(
     askTimeoutMs,
     client,
     transportCopy,
+    isLive, liveIntervalMs,
   ]);
 
   const checkAgain = useCallback(() => {

package/src/flows/create-payment-flows.tsx

@@ -106,6 +106,7 @@ function buildCheckout(
         providerConfig={config}
         tenantSlug={tenantSlug}
         confirmationExtra={runtime.config.confirmation?.extra}
+        confirmationHero={runtime.config.confirmation?.hero}
         validateApplePayMerchant={ports.validateApplePayMerchant}
       />
     );

package/src/flows/screens-pay.tsx

@@ -93,6 +93,7 @@ function buildPaymentStatus(runtime: FlowsRuntime): CheckoutScreens["PaymentStat
           orderId={payable?.orderId}
           onBackToMenu={backToMenu}
           paidExtra={runtime.config.confirmation?.extra}
+          paidHero={runtime.config.confirmation?.hero}
         />
       </FlowsShell>
     );

package/src/flows/types.ts

@@ -144,8 +144,11 @@ export interface PaymentFlowsConfig extends CheckoutPipelineConfig {
    * makes a new host answer once, at the one call site that knows the answer.
    */
   copy: CheckoutCopyFE;
-  /** Host content under the paid receipt (the storefront's PWA install invite). */
-  confirmation?: { extra?: ReactNode };
+  /**
+   * Host content under the paid receipt (the storefront's PWA install invite),
+   * and the host's own illustration in place of the paid icon (`hero`).
+   */
+  confirmation?: { extra?: ReactNode; hero?: ReactNode };
   /**
    * Warnings the host reports (Sentry). Default SILENT — never `console`: a
    * library that writes to a buyer's console tells them nothing and tells the

package/src/index.ts

@@ -131,6 +131,13 @@ export type {
 } from './components/checkout/screens-copy';
 export { PT_BR_CHECKOUT_SCREENS_COPY } from './components/checkout/screens-pt-BR';
 export { fetchCheckoutConfig } from './components/checkout/client';
+// The host's realtime channel for this buyer (FUT-649): a hint asks `/status`
+// now, and every wait slows to a floor while the channel is live.
+export {
+  CheckoutLiveProvider,
+  DEFAULT_LIVE_INTERVAL_MS,
+  type CheckoutLiveSignal,
+} from './components/checkout/live-context';
 /**
  * The `sessionStorage` key the hosted-checkout return leg parks the raised
  * order under. Public because it is already observable — a spec asserting the