@12-apps/payments-frontend 3.34.2 → 3.34.4

package/package.json

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

@@ -19,15 +19,21 @@ import {
   CircularProgress,
   FormControl,
   FormControlLabel,
+  FormHelperText,
   FormLabel,
+  InputLabel,
+  OutlinedInput,
   Radio,
   RadioGroup as MuiRadioGroup,
   Step,
   StepLabel,
   Stepper as MuiStepper,
-  TextField,
   Typography,
+  styled,
+  useThemeProps,
 } from '@mui/material';
+import type { TextFieldProps } from '@mui/material';
+import { useId } from 'react';
 import type { JSX } from 'react';
 
 import type {
@@ -93,25 +99,170 @@ function DefaultButton({ variant = 'solid', color = 'primary', size = 'md', full
   );
 }
 
-function DefaultInput({ label, type = 'text', inputMode, fullWidth, required, autoComplete, placeholder, maxLength, value, error, helperText, endAdornment, onChange, onBlur, ...rest }: CheckoutInputProps): JSX.Element {
-  return (
-    <TextField
-      label={label}
-      type={type}
-      size="small"
-      fullWidth={fullWidth}
-      required={required}
-      placeholder={placeholder}
-      value={value}
-      error={error}
-      helperText={helperText}
-      onChange={onChange}
-      onBlur={onBlur}
-      slotProps={{
+type OwnerState = Record<string, unknown>;
+type SlotProps = Record<string, unknown> | ((ownerState: OwnerState) => Record<string, unknown>) | undefined;
+
+/**
+ * `TextField`'s root, by name and with its `ownerState`: a theme's
+ * `components.MuiTextField` (`styleOverrides`, including functions reading
+ * `ownerState`, and `variants`) applies exactly as it did to `TextField`.
+ */
+const TextFieldRoot = styled(FormControl, {
+  name: 'MuiTextField',
+  slot: 'Root',
+  overridesResolver: (_props, styles) => styles.root,
+})<{ ownerState: OwnerState }>({});
+
+/** A theme's slot props may be a function of `ownerState`, as `useSlot` allows. */
+function slotPropsOf(slotProps: SlotProps, ownerState: OwnerState): Record<string, unknown> {
+  return (typeof slotProps === 'function' ? slotProps(ownerState) : slotProps) ?? {};
+}
+
+/** `TextField`'s `ownerState`, for the outlined, non-select field this slot is. */
+function ownerStateOf(props: TextFieldProps): OwnerState {
+  return {
+    ...props,
+    autoFocus: false,
+    color: props.color ?? 'primary',
+    disabled: props.disabled ?? false,
+    error: props.error ?? false,
+    fullWidth: props.fullWidth ?? false,
+    multiline: false,
+    required: props.required ?? false,
+    select: false,
+    variant: 'outlined',
+  };
+}
+
+/**
+ * The slot's own props, run through the theme's `MuiTextField` defaults the way
+ * `TextField` runs them (`useDefaultProps` is `useThemeProps` by another name).
+ */
+function useTextFieldProps({ label, type = 'text', inputMode, fullWidth, required, autoComplete, placeholder, maxLength, value, error, helperText, endAdornment, onChange, onBlur, ...rest }: CheckoutInputProps): TextFieldProps {
+  return useThemeProps({
+    name: 'MuiTextField',
+    props: {
+      label,
+      type,
+      size: 'small',
+      fullWidth,
+      required,
+      placeholder,
+      value,
+      error,
+      helperText,
+      onChange,
+      onBlur,
+      slotProps: {
         htmlInput: { inputMode, maxLength, autoComplete, 'data-testid': rest['data-testid'] },
         input: { endAdornment },
-      }}
-    />
+      },
+    } as TextFieldProps,
+  });
+}
+
+/**
+ * What `TextField` consumes by name rather than handing to its root. A key LIST
+ * rather than a destructure, which would bind every one of them only to drop it.
+ */
+const CONSUMED_BY_FIELD: ReadonlySet<string> = new Set([
+  'autoComplete', 'autoFocus', 'children', 'className', 'color', 'defaultValue', 'disabled', 'error',
+  'FormHelperTextProps', 'fullWidth', 'helperText', 'id', 'InputLabelProps', 'inputProps', 'InputProps',
+  'inputRef', 'label', 'maxRows', 'minRows', 'multiline', 'name', 'onBlur', 'onChange', 'onFocus',
+  'placeholder', 'required', 'rows', 'select', 'SelectProps', 'slotProps', 'slots', 'type', 'value',
+  'variant',
+]);
+
+/**
+ * The slot props as `TextField` resolves them: the legacy `InputProps`,
+ * `InputLabelProps`, `inputProps` and `FormHelperTextProps` first, then
+ * `slotProps` over them.
+ */
+function slotPropsFor(props: TextFieldProps): Record<string, SlotProps> {
+  return {
+    input: props.InputProps as SlotProps,
+    inputLabel: props.InputLabelProps as SlotProps,
+    htmlInput: props.inputProps as SlotProps,
+    formHelperText: props.FormHelperTextProps as SlotProps,
+    ...((props.slotProps ?? {}) as Record<string, SlotProps>),
+  };
+}
+
+/** The root: what `TextField` did not consume, then the props it hands the root by name. */
+function rootPropsOf(props: TextFieldProps, ownerState: OwnerState): Record<string, unknown> {
+  return {
+    ...Object.fromEntries(Object.entries(props).filter(([key]) => !CONSUMED_BY_FIELD.has(key))),
+    ownerState,
+    className: ['MuiTextField-root', (props.classes as { root?: string } | undefined)?.root, props.className]
+      .filter(Boolean)
+      .join(' '),
+    disabled: ownerState.disabled,
+    error: ownerState.error,
+    fullWidth: ownerState.fullWidth,
+    required: ownerState.required,
+    color: ownerState.color,
+    variant: 'outlined',
+  };
+}
+
+/** The input: the props `TextField` names, then the theme's and the slot's `input` slot props. */
+function inputPropsOf(props: TextFieldProps, ownerState: OwnerState, ids: { id: string; helperTextId?: string }): Record<string, unknown> {
+  const slots = slotPropsFor(props);
+  const shrink = slotPropsOf(slots.inputLabel, ownerState).shrink;
+  return {
+    'aria-describedby': ids.helperTextId,
+    autoComplete: props.autoComplete,
+    autoFocus: ownerState.autoFocus,
+    defaultValue: props.defaultValue,
+    fullWidth: ownerState.fullWidth,
+    name: props.name,
+    inputRef: props.inputRef,
+    onFocus: props.onFocus,
+    type: props.type,
+    value: props.value,
+    id: ids.id,
+    onBlur: props.onBlur,
+    onChange: props.onChange,
+    placeholder: props.placeholder,
+    inputProps: slotPropsOf(slots.htmlInput, ownerState),
+    label: props.label,
+    ...(shrink === undefined ? {} : { notched: shrink }),
+    ...slotPropsOf(slots.input, ownerState),
+  };
+}
+
+/**
+ * An outlined text field, composed from the parts MUI's `TextField` composes
+ * (FUT-3402). `TextField` itself imports `Select` unconditionally, and through
+ * it `Menu`, `MenuList`, `Popover` and `List`; this slot is in every host's
+ * checkout bundle whether or not the host fills it, so it paid for a dropdown
+ * it can never render.
+ *
+ * Same DOM and the same theme hooks — `defaultProps`, `styleOverrides`,
+ * `variants`, slot props — pinned by `default-input-parity.test.tsx`, with two
+ * deliberate exceptions: a theme default `variant` other than `outlined`, and
+ * `slots` replacing a part, are not honoured. Either would need the very
+ * components this slot exists to leave out; a host that wants them fills the
+ * `Input` slot.
+ */
+function DefaultInput(slotProps: CheckoutInputProps): JSX.Element {
+  const props = useTextFieldProps(slotProps);
+  const ownerState = ownerStateOf(props);
+  const generatedId = useId();
+  const id = props.id ?? generatedId;
+  const helperTextId = props.helperText ? `${id}-helper-text` : undefined;
+  const slots = slotPropsFor(props);
+  const { label, helperText } = props;
+  return (
+    <TextFieldRoot {...(rootPropsOf(props, ownerState) as { ownerState: OwnerState })}>
+      {label != null && label !== '' ? (
+        <InputLabel htmlFor={id} id={`${id}-label`} {...slotPropsOf(slots.inputLabel, ownerState)}>{label}</InputLabel>
+      ) : null}
+      <OutlinedInput {...inputPropsOf(props, ownerState, { id, helperTextId })} />
+      {helperText ? (
+        <FormHelperText id={helperTextId} {...slotPropsOf(slots.formHelperText, ownerState)}>{helperText}</FormHelperText>
+      ) : null}
+    </TextFieldRoot>
   );
 }
 

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),
     );