@12-apps/payments-frontend 3.4.0 → 3.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.4.0",
+  "version": "3.6.0",
   "type": "module",
   "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.",
   "exports": {
@@ -17,7 +17,7 @@
     "storybook:build": "storybook build"
   },
   "dependencies": {
-    "@12-apps/payments-backend": "^4.13.0",
+    "@12-apps/payments-backend": "^4.14.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {
@@ -28,7 +28,7 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
-    "@12-apps/eslint-config": "^1.20.0",
+    "@12-apps/eslint-config": "^1.21.0",
     "@12-apps/typescript-config": "^1.20.0",
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0",

package/src/activation/copy.ts

@@ -0,0 +1,36 @@
+/**
+ * The four sentences the redirect activation protocol has to put on screen
+ * itself (FUT-763).
+ *
+ * It renders nothing — the host owns the screen — but four states are reached
+ * INSIDE the protocol and carry a reason the host never sees the raw form of:
+ * the provider answered with no message, the poll gave up, the link expired.
+ * Something has to be shown, and a fallback string compiled into the package is
+ * how one product's voice reaches every adopter (`DEFAULT_CHECKOUT_COPY_FE`,
+ * removed for exactly that in FUT-760).
+ *
+ * So there are no defaults and the field is required. A host that has not
+ * written these sentences finds out at the type level rather than by reading
+ * another company's tone of voice on its own settings screen.
+ */
+export interface RedirectActivationCopy {
+  /**
+   * The activation link's window elapsed with nothing paid.
+   *
+   * Distinct from a refusal on purpose: nothing was charged, so the only
+   * useful offer is another link.
+   */
+  chargeExpired: string;
+  /** The provider answered "not paid" definitively, with no message of its own. */
+  confirmFailed: string;
+  /** The provider would not mint the link at all. */
+  createFailed: string;
+  /**
+   * The bounded poll elapsed while the charge was still live.
+   *
+   * The wording is the part that matters and the part only a host can own: the
+   * charge IS still payable, and telling an owner who has genuinely paid that
+   * their payment did not arrive in time is worse than saying nothing.
+   */
+  confirmTimedOut: string;
+}

package/src/activation/mint-charge.ts

@@ -0,0 +1,77 @@
+import {
+  creationFailure,
+  postActivation,
+  refusedByProvider,
+  type ActivationClock,
+  type RedirectActivationState,
+} from './redirect-state';
+import type { RedirectActivationCopy } from './copy';
+
+/**
+ * Getting the owner onto the provider's payment page, in one press (FUT-763).
+ *
+ * Its own file because the ORDER of what happens inside that click is the whole
+ * content of it, and it is easy to lose in a hook full of effects.
+ */
+
+/** A tab claimed for the payment page, before its address is known. */
+interface PendingTab {
+  send: (url: string) => void;
+  discard: () => void;
+}
+
+/**
+ * Claim a tab SYNCHRONOUSLY, to be pointed somewhere once the link exists.
+ *
+ * Pressing the pay button should land the owner on the payment page — that is
+ * the whole action, and making them find a second button afterwards is the
+ * extra step this flow exists to remove. But the URL does not exist yet: it is
+ * minted by a request, and a `window.open` issued after that `await` has lost
+ * the user's gesture, so every popup blocker eats it.
+ *
+ * Deliberately without `noopener`: that flag makes `window.open` return null,
+ * leaving no handle to navigate. `opener` is cleared by hand instead.
+ */
+function claimTab(): PendingTab {
+  const tab = window.open('', '_blank');
+  if (tab) tab.opener = null;
+  return {
+    // `replace`, so the blank entry does not become a Back destination.
+    send: (target) => tab?.location.replace(target),
+    discard: () => tab?.close(),
+  };
+}
+
+/**
+ * Mint the link and point the claimed tab at it.
+ *
+ * The ORDER here is load-bearing: the tab is claimed inside the click (see
+ * {@link claimTab}), discarded rather than stranded on a refusal, and the poll
+ * clock is only started once a link actually exists.
+ */
+export async function mintCharge(io: {
+  url: string;
+  live: ActivationClock;
+  setState: (next: RedirectActivationState) => void;
+  copy: RedirectActivationCopy;
+  onCreateFailed?: () => void;
+}): Promise<void> {
+  const tab = claimTab();
+
+  io.setState({ kind: 'creating' });
+  const body = await postActivation(io.url, 'start');
+  if (!body?.ok || !body.checkoutUrl) {
+    // Never strand a blank tab on a failure the owner is about to read here.
+    tab.discard();
+    io.setState(creationFailure(body, io.copy));
+    // A dropped request means the provider refused NOTHING, so nothing the
+    // owner told us is called into question. Only an actual refusal withdraws
+    // their confirmation of the provider-side step.
+    if (refusedByProvider(body)) io.onCreateFailed?.();
+    return;
+  }
+  tab.send(body.checkoutUrl);
+  io.live.current.polling = true;
+  io.live.current.startedAt = Date.now();
+  io.setState({ kind: 'awaiting', checkoutUrl: body.checkoutUrl });
+}

package/src/activation/redirect-state.ts

@@ -0,0 +1,184 @@
+import type React from 'react';
+import type { MutableRefObject } from 'react';
+
+import type { RedirectActivationCopy } from './copy';
+
+/**
+ * What the redirect activation step can BE, and how one answer from the
+ * provider moves it — with no React and no requests anywhere near (FUT-763).
+ *
+ * Split from the hook because these are the decisions and the hook is the
+ * wiring: timers, mount effects, a claimed tab, a memoized callback. Together
+ * they were one file nobody could read the rules out of, and the rules are the
+ * part that costs money when it is wrong.
+ */
+
+export type RedirectActivationState =
+  | { kind: 'idle' }
+  | { kind: 'creating' }
+  /** Link live (URL present) or confirming a return trip (URL null). */
+  | {
+      kind: 'awaiting';
+      checkoutUrl: string | null;
+      /**
+       * A payment ATTEMPT was refused, on a charge that is still payable.
+       *
+       * It stays `awaiting` rather than becoming a failure because nothing
+       * about the link changed: the card said no, and the next move is another
+       * card or another method on this same link. Settling it would clear the
+       * outstanding charge and put a button offering to mint a SECOND real one
+       * on screen, while the first sits live at the provider.
+       */
+      declined?: string;
+    }
+  /** The link's window elapsed unpaid. Nothing was charged; offer another. */
+  | { kind: 'expired'; reason: string }
+  | { kind: 'passed' }
+  | {
+      kind: 'failed';
+      reason: string;
+      providerMessage?: string;
+      /**
+       * The provider refused to CREATE the link, rather than refusing the
+       * payment. A different failure with a different owner: no money moved and
+       * nothing is outstanding, and the overwhelmingly likely cause is a
+       * provider-side switch still being off — which is a step, not an error.
+       */
+      atCreation?: boolean;
+      /**
+       * …unless the provider was never reached at all, in which case it refused
+       * nothing and the step the owner already completed must survive untouched.
+       */
+      transport?: boolean;
+    };
+
+/** One answer from the host's verify-charge endpoint. */
+export interface ActivationPollBody {
+  ok?: boolean;
+  pending?: boolean;
+  reason?: string;
+  providerMessage?: string;
+  checkoutUrl?: string;
+  /** Which settled-and-negative answer this was. */
+  outcome?: 'expired' | 'declined' | 'refused';
+  /** The charge is still payable; the server deliberately kept it outstanding. */
+  retryable?: boolean;
+  /** `start` only: the provider was never reached, so it refused nothing. */
+  transport?: boolean;
+}
+
+/** The outstanding charge, as the server remembers it. */
+export interface ActivationPendingBody {
+  reference: string;
+  checkoutUrl: string;
+  slug?: string;
+  startedAt: string;
+}
+
+/**
+ * Ask the host's endpoint to start, poll, or discard the activation charge.
+ *
+ * A thrown fetch and an unparsable body both answer `null`, which is the same
+ * fact one layer out: nothing came back. {@link refusedByProvider} is what
+ * turns that into a decision.
+ */
+export async function postActivation(
+  url: string,
+  action: 'start' | 'poll' | 'discard',
+  extra: Record<string, string> = {},
+): Promise<ActivationPollBody | null> {
+  try {
+    const response = await fetch(url, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ action, ...extra }),
+    });
+    return (await response.json().catch(() => null)) as ActivationPollBody | null;
+  } catch {
+    return null;
+  }
+}
+
+/** Live poll bookkeeping, mutated in place so a timer never reads a stale copy. */
+export type ActivationClock = MutableRefObject<{ polling: boolean; startedAt: number }>;
+
+/** What {@link settleActivationPoll} needs besides the answer itself. */
+export interface SettlePollIo {
+  live: ActivationClock;
+  setState: React.Dispatch<React.SetStateAction<RedirectActivationState>>;
+  onVerified: () => void;
+  /** Drop the parked return-trip ids — the charge is done with them. */
+  clearSettlement: () => void;
+  copy: RedirectActivationCopy;
+}
+
+/**
+ * Turn one poll answer into the screen's state, and say whether it SETTLED.
+ *
+ * Four outcomes, and the two in the middle are the ones worth naming. A
+ * `retryable` refusal is a payment ATTEMPT that failed on a charge still
+ * sitting live at the provider — so it stays `awaiting`, keeps the link on
+ * screen (paying it with another method is the entire fix) and does not stop
+ * the timer. An `expired` charge is the opposite: nobody can pay it now, so the
+ * only useful offer is another one.
+ */
+export function settleActivationPoll(body: ActivationPollBody | null, io: SettlePollIo): boolean {
+  if (!body) return false;
+  if (body.ok) {
+    io.live.current.polling = false;
+    io.clearSettlement();
+    io.setState({ kind: 'passed' });
+    io.onVerified();
+    return true;
+  }
+  if (body.pending) return false;
+  if (body.retryable) {
+    const declined = body.reason ?? '';
+    io.setState((current) =>
+      current.kind === 'awaiting'
+        ? { ...current, declined }
+        : { kind: 'awaiting', checkoutUrl: null, declined },
+    );
+    return false;
+  }
+  io.live.current.polling = false;
+  io.clearSettlement();
+  if (body.outcome === 'expired') {
+    io.setState({ kind: 'expired', reason: body.reason ?? io.copy.chargeExpired });
+    return true;
+  }
+  io.setState({
+    kind: 'failed',
+    reason: body.reason ?? io.copy.confirmFailed,
+    providerMessage: body.providerMessage,
+  });
+  return true;
+}
+
+/**
+ * Did the PROVIDER refuse, or was it simply never reached?
+ *
+ * `transport` says the request produced no response; a null body says the
+ * browser's own fetch threw, which is the same thing one layer out. Either way
+ * nothing was refused — and the distinction matters because a refusal, and only
+ * a refusal, is evidence that a step the owner ticked off is not in fact done.
+ * Treating an outage as one sends someone whose network blinked back to redo a
+ * finished step, to change a setting that was already correct.
+ */
+export function refusedByProvider(body: ActivationPollBody | null): boolean {
+  return Boolean(body) && !body?.transport;
+}
+
+/** The failed state a refused (or unreachable) `start` leaves behind. */
+export function creationFailure(
+  body: ActivationPollBody | null,
+  copy: RedirectActivationCopy,
+): RedirectActivationState {
+  return {
+    kind: 'failed',
+    reason: body?.reason ?? copy.createFailed,
+    providerMessage: body?.providerMessage,
+    atCreation: true,
+    ...(refusedByProvider(body) ? {} : { transport: true }),
+  };
+}

package/src/activation/returned-settlement.ts

@@ -0,0 +1,117 @@
+/**
+ * The settlement a redirect provider hands back on the return trip, made
+ * durable (FUT-763).
+ *
+ * The activation charge is paid on the PROVIDER'S site, so "left this page and
+ * came back" is the normal path. The provider appends the ids that prove the
+ * payment to the return URL, and those ids exist nowhere before the payment
+ * and — without care — nowhere after the first render: reading and scrubbing
+ * them in one call destroys them on a re-render, and a reload (the natural
+ * reaction to a screen that looks stuck) destroys an in-memory copy too.
+ *
+ * So they are parked in `sessionStorage` BEFORE the URL is scrubbed, survive
+ * both, and are cleared only when the charge settles.
+ *
+ * This is protocol, not presentation, which is why it moved: every host that
+ * mounts a redirect provider gets the same return trip, and the ordering above
+ * is not something a host should have to rediscover — it was rediscovered once
+ * already, by a payment that was confirmed, thrown away, and never asked about
+ * again.
+ */
+
+/**
+ * The default parking slot.
+ *
+ * Namespaced by the package rather than by an app, and overridable, so two
+ * surfaces of the same host can run the flow without reading each other's
+ * parked ids.
+ */
+export const RETURNED_SETTLEMENT_KEY = 'payments:activation-settlement';
+
+/**
+ * The ids a redirect provider appends, and the aliases it may use for them.
+ *
+ * Both matter, and this was measured against the live API rather than read off
+ * a doc page:
+ *
+ *   handle + order id + transaction id + slug → paid
+ *   the same call minus the slug              → not paid
+ *   the same call minus the transaction id    → not paid
+ *
+ * Neither is optional and neither exists before the payment. Asking with only
+ * the transaction id — while expecting the slug from link creation, where the
+ * provider does not put it — is a question that always answers no.
+ */
+const TRANSACTION_PARAMS = ['transaction_nsu', 'transaction_id'] as const;
+const SLUG_PARAM = 'slug';
+
+/**
+ * Everything the return trip may carry, scrubbed together.
+ *
+ * Wider than what is READ: a receipt link and a capture method identify a
+ * payment just as well, and have no business persisting in a URL somebody
+ * might copy or a history entry a reload might replay.
+ */
+const SETTLEMENT_PARAMS = [
+  ...TRANSACTION_PARAMS,
+  'order_nsu',
+  SLUG_PARAM,
+  'receipt_url',
+  'capture_method',
+];
+
+function parked(storageKey: string): Record<string, string> {
+  try {
+    const raw = window.sessionStorage.getItem(storageKey);
+    return raw ? (JSON.parse(raw) as Record<string, string>) : {};
+  } catch {
+    return {};
+  }
+}
+
+/** The charge settled — either way — so the parked ids have done their job. */
+export function clearReturnedSettlement(storageKey = RETURNED_SETTLEMENT_KEY): void {
+  try {
+    window.sessionStorage.removeItem(storageKey);
+  } catch {
+    // Best-effort: a stale parked value is re-sent once and ignored server-side.
+  }
+}
+
+/**
+ * Read the return trip's ids, park them, and take them out of the address bar.
+ *
+ * Safe to call on every render and every poll — which it is. With nothing in
+ * the URL it answers with whatever is already parked, so the fifth ask carries
+ * the same proof as the first.
+ */
+export function takeReturnedSettlement(
+  storageKey = RETURNED_SETTLEMENT_KEY,
+): Record<string, string> {
+  if (typeof window === 'undefined') return {};
+
+  const params = new URLSearchParams(window.location.search);
+  const transactionNsu = TRANSACTION_PARAMS.map((key) => params.get(key)).find(Boolean) ?? '';
+  const slug = params.get(SLUG_PARAM) ?? '';
+  if (!transactionNsu && !slug) return parked(storageKey);
+
+  const captured = {
+    ...(transactionNsu ? { transactionNsu } : {}),
+    ...(slug ? { slug } : {}),
+  };
+  try {
+    window.sessionStorage.setItem(storageKey, JSON.stringify(captured));
+  } catch {
+    // Storage refused (private-mode quirks): the in-URL copy still exists for
+    // this page-load, and the server persists the slug after one good poll.
+  }
+  scrubSettlementParams(params);
+  return captured;
+}
+
+/** Take the settlement params back out of the address bar, read once. */
+function scrubSettlementParams(params: URLSearchParams): void {
+  for (const key of SETTLEMENT_PARAMS) params.delete(key);
+  const query = params.toString();
+  window.history.replaceState({}, '', `${window.location.pathname}${query ? `?${query}` : ''}`);
+}