@12-apps/payments-frontend 3.40.0 → 3.41.0

package/package.json

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

package/src/activation/use-redirect-activation.ts

@@ -53,7 +53,10 @@ import { clearReturnedSettlement, takeReturnedSettlement } from './returned-sett
  * things that clear it are settlement and an explicit "give up".
  */
 
-/** How often to ask the provider whether the payment landed. */
+/**
+ * How often to ask the provider whether the payment landed — the recorded
+ * third-party-wait exception, see {@link usePollTimer}.
+ */
 const DEFAULT_POLL_MS = 4000;
 
 /** Give up asking after this long, rather than polling a tab forever. */
@@ -126,6 +129,24 @@ interface ActivationCallbacks {
 /**
  * Ask the provider every few seconds, and stop asking eventually.
  *
+ * ## A deliberate poll: the recorded exception to "hear, do not poll" (FUT-2433)
+ *
+ * Every other wait in this package hears the host's channel and keeps no timer
+ * while it is live. This one cannot, and it is the one exception class the
+ * origin host records: a timer-driven read of a THIRD PARTY's state that no
+ * webhook or publisher of the host's reaches yet, bounded in time, and named.
+ * Each tick is not a read of the host's own rows — `verify-charge` asks the
+ * PROVIDER whether the activation charge was paid, and while nobody has asked,
+ * nothing server-side has moved that a hint could carry. The activation webhook
+ * that would settle it is not guaranteed to arrive (a tunnel, a preview box), so
+ * the wait is the confirmation. It runs only while the owner is paying on the
+ * provider's page and gives up at `pollTimeoutMs` (ten minutes by default).
+ *
+ * Where it is recorded: the origin host's realtime doc ("Allowed exceptions")
+ * and the decision record that superseded its 0071 with it. If activation
+ * ever becomes webhook-only, this relaxes to the channel exactly as the
+ * checkout's waits did (FUT-649) and the exception goes away.
+ *
  * The give-up is a `failed` state carrying the host's own sentence, because the
  * wording is load-bearing: the charge is STILL valid, and an owner who has
  * genuinely paid must not be told they did not pay in time.

package/src/components/PaymentProviderSettings.tsx

@@ -21,6 +21,7 @@ import {
   type ProviderChangeHandler,
 } from './settings-state';
 import { openSection, SetupGuideSection } from './SetupGuideSection';
+import { useSettingsLive, type PaymentsSettingsLiveSignal } from './settings-live';
 import type { PaymentsSettingsCopy } from './settings-copy';
 import { PaymentsSettingsCopyProvider } from './settings-copy-context';
 
@@ -102,6 +103,16 @@ export interface PaymentProviderSettingsProps {
    * its history ({@link ProviderChangeHandler}).
    */
   onProviderChange?: ProviderChangeHandler;
+  /**
+   * The host's realtime channel for this store's payment settings (FUT-648).
+   *
+   * A hint re-reads the view, and so does every (re)connect: an OAuth grant
+   * completed in another tab, a colleague's save, a webhook settling the
+   * activation charge all reach this screen without a reload. Omit it and the
+   * screen reads on mount and after its own actions, exactly as before — it
+   * keeps no timer either way. See {@link PaymentsSettingsLiveSignal}.
+   */
+  live?: PaymentsSettingsLiveSignal;
   /**
    * The activation step, rendered under the connection card.
    *
@@ -299,8 +310,10 @@ export function PaymentProviderSettings({
   selectedProvider,
   onProviderChange,
   renderVerification,
+  live,
 }: PaymentProviderSettingsProps) {
   const { view, error, reload } = useSettingsState(client);
+  useSettingsLive(live, () => void reload());
   const { selected, setSelected } = useSelectedProvider(
     initialProvider,
     selectedProvider,

package/src/components/settings-live.ts

@@ -0,0 +1,66 @@
+'use client';
+
+import { useEffect, useRef } from 'react';
+
+/**
+ * The host's realtime channel for the settings screen (FUT-648).
+ *
+ * A provider's connection moves while nobody touches this tab: the OAuth grant
+ * completes in the tab the owner sent to the provider, a colleague saves a key
+ * or reorders the chain, a webhook or a sweep settles the activation charge.
+ * The screen read its view once on mount and then sat on it, so all of that
+ * reached the owner only through a reload.
+ *
+ * Nothing here knows what the channel is — the same split as the checkout's
+ * `CheckoutLiveSignal`. A host that can hear "this store's payment settings
+ * moved" passes whether its channel is live and a way to be told when it
+ * fires; the screen re-reads its view on every hint and once each time the
+ * channel (re)opens, because a hint published while it was down reached
+ * nobody. The hint carries nothing and is never trusted as data: the re-read
+ * goes through the same client, which is the only thing that decides what the
+ * owner may see.
+ *
+ * There is no timer, live or not. The screen never polled, so a host without a
+ * channel — or one whose channel is down — keeps exactly the mount read and its
+ * own actions' re-reads, as before.
+ */
+export interface PaymentsSettingsLiveSignal {
+  /** Whether the host's channel is connected right now. */
+  live: boolean;
+  /**
+   * Be told when the channel says this store's payment settings moved.
+   * Returns the unsubscribe. Should be stable across renders: a new function
+   * re-subscribes.
+   */
+  subscribe: (onHint: () => void) => () => void;
+}
+
+/**
+ * Re-read on every hint, and once whenever the channel goes from not-live to
+ * live — the first connect after mount included, since the mount read may
+ * have been answered before the subscription existed.
+ *
+ * `reload` is read through a ref so a host re-rendering with a new function
+ * neither re-subscribes nor re-reads.
+ */
+export function useSettingsLive(
+  signal: PaymentsSettingsLiveSignal | undefined,
+  reload: () => void,
+): void {
+  const latest = useRef(reload);
+  latest.current = reload;
+  const live = signal?.live === true;
+  const wasLive = useRef(live);
+  const subscribe = signal?.subscribe;
+
+  useEffect(() => {
+    const opened = live && !wasLive.current;
+    wasLive.current = live;
+    if (opened) latest.current();
+  }, [live]);
+
+  useEffect(() => {
+    if (!subscribe) return undefined;
+    return subscribe(() => latest.current());
+  }, [subscribe]);
+}

package/src/flows/create-payments-settings.tsx

@@ -18,10 +18,11 @@
  * settings page behind.
  *
  * **`prepareConnect`, `selectedProvider` / `onProviderChange`,
- * `initialProvider`, `onChanged`.** The OAuth CSRF state is minted against
+ * `initialProvider`, `onChanged`, `live`.** The OAuth CSRF state is minted against
  * the host's admin session; which provider is open may live in the host's
  * URL. Both are the host's, per render, and a factory that froze them would
- * make the page uncontrollable.
+ * make the page uncontrollable. `live` is the host's realtime channel, whose
+ * status changes from render to render (FUT-648).
  */
 
 import type { ComponentType, JSX } from "react";
@@ -32,6 +33,9 @@ import {
 } from "../components/PaymentProviderSettings";
 import type { PaymentsSettingsClient } from "../client";
 
+/** The `live` prop's shape — the host's channel, see `../components/settings-live`. */
+export type { PaymentsSettingsLiveSignal } from "../components/settings-live";
+
 /** What a host binds ONCE: the settings port. */
 export interface PaymentsSettingsWebConfig {
   /**

package/src/index.ts

@@ -323,7 +323,7 @@ export {
   type PaymentProviderSettingsProps,
 } from './components/PaymentProviderSettings';
 export { createWebPaymentsSettings } from './flows/create-payments-settings';
-export type { BoundPaymentsSettingsProps, PaymentsSettingsSurface, PaymentsSettingsWebConfig } from './flows/create-payments-settings';
+export type { BoundPaymentsSettingsProps, PaymentsSettingsLiveSignal, PaymentsSettingsSurface, PaymentsSettingsWebConfig } from './flows/create-payments-settings';
 
 // ---------------------------------------------------------------------------
 // The PLATFORM operations screens (FUT-479 / FUT-483, packaged by FUT-573) —