@12-apps/payments-frontend 3.28.1 → 3.29.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.28.1",
+  "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.",
@@ -23,7 +23,7 @@
     "storybook:build": "storybook build"
   },
   "dependencies": {
-    "@12-apps/payments-backend": "^4.28.0",
+    "@12-apps/payments-backend": "^4.29.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

package/src/components/ProviderStatusBar.tsx

@@ -4,7 +4,7 @@ import { Box, Stack, Switch, Tooltip, Typography } from '@mui/material';
 
 import type { MaskedProviderConfig, ProviderDescriptor } from '@12-apps/payments-backend';
 
-import { isConnected } from './connection-state';
+import { certificateExpiryProximity, isConnected } from './connection-state';
 import { T } from './panel-tokens';
 import type { ConnectionStatusCopy } from './settings-copy';
 import { usePaymentsSettingsCopy } from './settings-copy-context';
@@ -218,6 +218,58 @@ function ProviderName({
   );
 }
 
+/**
+ * The saved production certificate's renewal warning, under the headline.
+ *
+ * Only for a store on PRODUCTION: that is the one whose PIX stops when the
+ * certificate lapses, and a sandbox store testing the form has nothing to
+ * renew yet. Silent outside the 30-day window (`certificateExpiryProximity`) —
+ * a date a year out is not news, and it is on the provider's portal anyway.
+ * A `status`, lapsed or not: it is state on load, and the probe's own error is
+ * already the alert — a second would be read out twice.
+ */
+function CertificateExpiryNote({ copy, config }: { copy: ConnectionStatusCopy; config: MaskedProviderConfig | null }) {
+  const note = certificateNote(copy, config);
+  if (!note) return null;
+  const tone = note.past
+    ? { border: T.badLine, background: T.badSoft, color: T.badInk }
+    : { border: T.warnLine, background: T.warnSoft, color: T.warnInk };
+  return (
+    <Typography
+      role="status"
+      data-testid="payments-certificate-expiry"
+      sx={{
+        fontSize: '12.5px',
+        fontWeight: 600,
+        lineHeight: 1.5,
+        maxWidth: '52ch',
+        mt: '8px',
+        px: '10px',
+        py: '7px',
+        borderRadius: '8px',
+        border: `1px solid ${tone.border}`,
+        background: tone.background,
+        color: tone.color,
+      }}
+    >
+      {note.text}
+    </Typography>
+  );
+}
+
+/** What the certificate note says, or null when it has nothing to say. */
+function certificateNote(
+  copy: ConnectionStatusCopy,
+  config: MaskedProviderConfig | null,
+): { text: string; past: boolean } | null {
+  const expiresAt = config?.environment === 'PRODUCTION' ? config.credentialExpiresAt : null;
+  if (!expiresAt) return null;
+  const proximity = certificateExpiryProximity(expiresAt);
+  if (proximity === 'PAST') return { text: copy.certificateExpired(expiresAt), past: true };
+  if (proximity === 'NEAR') return { text: copy.certificateExpires(expiresAt), past: false };
+  return null;
+}
+
 export function ProviderStatusBar({
   descriptor,
   config,
@@ -248,6 +300,7 @@ export function ProviderStatusBar({
         >
           {sub}
         </Typography>
+        <CertificateExpiryNote copy={copy} config={config} />
       </Box>
       {/* The switch belongs at the far edge: it is the one control here that
           changes what buyers experience, and crowding it against the status

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

package/src/components/connection-state.ts

@@ -71,11 +71,31 @@ export function expiryProximity(
   expiresAt: string | null | undefined,
   now: Date = new Date(),
 ): ExpiryProximity | null {
-  if (!expiresAt) return null;
-  const at = new Date(expiresAt).getTime();
+  return proximityWithin(EXPIRY_WARNING_WINDOW_MS, expiresAt, now);
+}
+
+/**
+ * A saved CERTIFICATE's proximity (`credentialExpiresAt`) — a different
+ * window from the OAuth grant's on purpose. No sweep renews a certificate:
+ * the owner generates a new one by hand, and Itaú opens that renewal 30 days
+ * before expiry, so the warning starts the day there is something to do about
+ * it rather than a week before the store's PIX stops.
+ */
+const CERTIFICATE_WARNING_WINDOW_MS = 30 * 24 * 60 * 60 * 1000;
+
+export function certificateExpiryProximity(
+  credentialExpiresAt: string | null | undefined,
+  now: Date = new Date(),
+): ExpiryProximity | null {
+  return proximityWithin(CERTIFICATE_WARNING_WINDOW_MS, credentialExpiresAt, now);
+}
+
+function proximityWithin(windowMs: number, iso: string | null | undefined, now: Date): ExpiryProximity | null {
+  if (!iso) return null;
+  const at = new Date(iso).getTime();
   if (Number.isNaN(at)) return null;
   if (at <= now.getTime()) return 'PAST';
-  return at - now.getTime() <= EXPIRY_WARNING_WINDOW_MS ? 'NEAR' : 'SAFE';
+  return at - now.getTime() <= windowMs ? 'NEAR' : 'SAFE';
 }
 
 /**

package/src/components/settings-copy.ts

@@ -49,6 +49,14 @@ export interface ConnectionStatusCopy {
   pausedChip: string;
   /** Proven, not switched on yet. */
   readyNotReceiving: { state: string; sub: string };
+  /**
+   * The saved production certificate lapses inside the renewal window, or has
+   * lapsed. Given the ISO `validTo`; the pack formats the date in its own
+   * locale. Provider-neutral wording — the certificate is the store's, the
+   * portal is the provider's.
+   */
+  certificateExpires: (iso: string) => string;
+  certificateExpired: (iso: string) => string;
 }
 
 /**

package/src/components/settings-en-US.ts

@@ -39,6 +39,12 @@ export const EN_US_PAYMENTS_SETTINGS_COPY: PaymentsSettingsCopy = {
       state: 'Not taking sales yet',
       sub: 'Everything is ready — flip the switch to start taking payments.',
     },
+    certificateExpires: (iso) =>
+      `The production certificate expires on ${new Date(iso).toLocaleDateString('en-US')}. ` +
+      'Before then, generate a new certificate and private key in the provider’s portal and paste both on the Production tab — with an expired certificate, Pix through this provider does not work.',
+    certificateExpired: (iso) =>
+      `The production certificate expired on ${new Date(iso).toLocaleDateString('en-US')}. ` +
+      'Until it is replaced, Pix through this provider does not work. Generate a new certificate and private key in the provider’s portal and paste both on the Production tab.',
   },
   listBadge: {
     active: 'Active',

package/src/components/settings-pt-BR.ts

@@ -31,6 +31,12 @@ export const PT_BR_PAYMENTS_SETTINGS_COPY: PaymentsSettingsCopy = {
       state: 'Ainda não está recebendo',
       sub: 'Tudo pronto — ligue a chave para começar a receber.',
     },
+    certificateExpires: (iso) =>
+      `O certificado de produção vence em ${new Date(iso).toLocaleDateString('pt-BR')}. ` +
+      'Antes disso, gere um novo certificado e uma nova chave privada no portal do provedor e cole os dois na aba Produção — com o certificado vencido, o Pix por este provedor não funciona.',
+    certificateExpired: (iso) =>
+      `O certificado de produção venceu em ${new Date(iso).toLocaleDateString('pt-BR')}. ` +
+      'Enquanto ele não for trocado, o Pix por este provedor não funciona. Gere um novo certificado e uma nova chave privada no portal do provedor e cole os dois na aba Produção.',
   },
   listBadge: {
     active: 'Ativo',