@12-apps/payments-frontend 3.17.0 → 3.18.1

package/src/activation/screens/states.tsx

@@ -0,0 +1,244 @@
+'use client';
+
+import { Button, Stack } from '@mui/material';
+import type { JSX } from 'react';
+
+import { BTN_PRIMARY_SX, BTN_SECONDARY_SX, LINKISH_SX } from '../../components/panel-tokens';
+
+import { useActivationCopy } from './copy-context';
+import { Notice, ProviderMessage } from './notice';
+
+/**
+ * The settled outcomes of the activation charge, shared by both flows.
+ *
+ * They live apart from the panels that frame them because the panel is about
+ * layout and these are about what the owner is being TOLD — and every sentence
+ * here has cost real money to get right more than once. Three of the six are
+ * ways the link never got minted, and they are three screens rather than one
+ * because they are three different instructions: fix a setting, wait it out,
+ * read the provider's own words.
+ */
+
+/** Settled-and-passed: the provider is on, and the cent is on its way back. */
+export function PassedState({
+  amountLabel,
+  refunded,
+  onRetry,
+}: {
+  /** What was charged. `null` only while the endpoint has not priced it yet. */
+  amountLabel: string | null;
+  refunded: boolean;
+  onRetry: () => void;
+}): JSX.Element {
+  const { outcome, actions } = useActivationCopy();
+  const amount = amountLabel ?? outcome.someAmount;
+  return (
+    <Stack spacing={1} data-testid="verify-charge-passed">
+      <Notice
+        tone="ok"
+        title={outcome.approvedTitle}
+        description={refunded ? outcome.refundedBody(amount) : outcome.refundPendingBody(amount)}
+      />
+      <Stack direction="row">
+        <Button sx={LINKISH_SX} onClick={onRetry} data-testid="verify-charge-retry">
+          {actions.testAgain}
+        </Button>
+      </Stack>
+    </Stack>
+  );
+}
+
+/**
+ * Settled-and-refused. The wording is the point: the owner IS connected, so
+ * telling them the connection failed would send them to reauthorize something
+ * that already works.
+ */
+export function FailedState({
+  reason,
+  providerMessage,
+  onRetry,
+}: {
+  reason: string;
+  providerMessage?: string;
+  onRetry: () => void;
+}): JSX.Element {
+  const { outcome, actions } = useActivationCopy();
+  return (
+    <Stack spacing={1} data-testid="verify-charge-failed">
+      <Notice tone="bad" title={outcome.authenticatedNotActive} description={reason} />
+      {providerMessage ? (
+        <ProviderMessage message={providerMessage} label={outcome.providerSaid} />
+      ) : null}
+      <Stack direction="row">
+        <Button sx={BTN_PRIMARY_SX} onClick={onRetry} data-testid="verify-charge-retry">
+          {actions.retry}
+        </Button>
+      </Stack>
+    </Stack>
+  );
+}
+
+/**
+ * The provider would not CREATE the link. A different failure with a different
+ * owner, and it had been wearing the wrong one's clothes.
+ *
+ * Nothing was charged and nothing is outstanding — the request to mint a
+ * payment page was refused outright, which overwhelmingly means a provider-side
+ * switch is still off. That is a setup step rather than an error, and the
+ * screen it replaced ("authenticated but not active", with a retry button) sent
+ * the owner to re-check credentials that were fine and then to press retry
+ * against a setting that had not changed.
+ *
+ * `onDismiss` is not "try the same thing again": it clears the failed attempt
+ * and returns the step to its starting state, which is what the owner needs
+ * AFTER going to flip the setting. Safe here in a way it is not elsewhere in
+ * this flow, because nothing was charged — there is no outstanding payment for
+ * a second attempt to duplicate.
+ */
+export function SetupIncompleteState({
+  displayName,
+  reason,
+  providerMessage,
+  onDismiss,
+}: {
+  displayName: string;
+  reason: string;
+  providerMessage?: string;
+  onDismiss: () => void;
+}): JSX.Element {
+  const { outcome, actions } = useActivationCopy();
+  return (
+    <Stack spacing={1} data-testid="verify-charge-setup-incomplete">
+      <Notice
+        tone="warn"
+        title={outcome.refusedTitle(displayName)}
+        description={outcome.refusedBody(displayName)}
+      />
+      {reason ? <Notice tone="info" title={reason} /> : null}
+      {providerMessage ? (
+        <ProviderMessage message={providerMessage} label={outcome.providerSaid} />
+      ) : null}
+      <Stack direction="row">
+        <Button sx={LINKISH_SX} onClick={onDismiss} data-testid="verify-charge-retry">
+          {actions.restart}
+        </Button>
+      </Stack>
+    </Stack>
+  );
+}
+
+/**
+ * Already proven: the ONLY honest thing this step can render is that fact.
+ *
+ * It used to reset to the pay button on every reload, because the proof lives
+ * on the server and the screen never asked. An owner whose charge HAD landed
+ * was greeted by the pay button again — and one owner, reasonably reading that
+ * as "it did not work", paid four times.
+ *
+ * It is also the end of the flow, so it says where to go next. A terminal
+ * screen with no exit is how an owner who has just finished setting up payments
+ * ends up hunting the sidebar for the two things they now actually want: the
+ * order providers are tried in, and the storefront this was all for. Both sit
+ * INSIDE the panel, because they are what this outcome offers.
+ */
+export function ProvenState({
+  storeUrl,
+  onProviderOrder,
+}: {
+  /** The storefront this connection now takes money for. */
+  storeUrl: string;
+  /** Back to the provider list, which is where the failover chain lives. */
+  onProviderOrder: () => void;
+}): JSX.Element {
+  const { outcome, actions } = useActivationCopy();
+  return (
+    <Notice
+      tone="ok"
+      title={outcome.provenTitle}
+      description={outcome.provenBody}
+      dataTestId="verify-charge-proven"
+    >
+      <Stack direction="row" spacing={1} sx={{ flexWrap: 'wrap' }}>
+        <Button
+          sx={BTN_SECONDARY_SX}
+          onClick={onProviderOrder}
+          data-testid="verify-charge-provider-order"
+        >
+          {actions.setProviderOrder}
+        </Button>
+        <Button
+          sx={BTN_SECONDARY_SX}
+          onClick={() => window.open(storeUrl, '_blank', 'noopener')}
+          data-testid="verify-charge-open-store"
+        >
+          {actions.seePublishedStore}
+        </Button>
+      </Stack>
+    </Notice>
+  );
+}
+
+/**
+ * We could not reach the provider while MINTING the link.
+ *
+ * Deliberately not {@link SetupIncompleteState}, and the difference is the whole
+ * reason this exists: that screen tells the owner a provider-side switch is
+ * probably off and puts them back a step to fix it. A request that never
+ * arrived is no evidence of that at all — the provider refused nothing — so
+ * saying it would send someone whose connection blinked to change a setting
+ * that was already correct, and take a finished step away from them on the way.
+ *
+ * The only honest instruction is the one an outage deserves: try again.
+ */
+export function UnreachableState({
+  reason,
+  providerMessage,
+  onRetry,
+}: {
+  reason: string;
+  providerMessage?: string;
+  onRetry: () => void;
+}): JSX.Element {
+  const { outcome, actions } = useActivationCopy();
+  return (
+    <Stack spacing={1} data-testid="verify-charge-unreachable">
+      <Notice tone="warn" title={outcome.unreachableTitle} description={reason} />
+      {providerMessage ? (
+        <ProviderMessage message={providerMessage} label={outcome.providerSaid} />
+      ) : null}
+      <Stack direction="row">
+        <Button sx={BTN_PRIMARY_SX} onClick={onRetry} data-testid="verify-charge-retry-create">
+          {actions.tryAgain}
+        </Button>
+      </Stack>
+    </Stack>
+  );
+}
+
+/**
+ * The link's window elapsed with nobody paying it.
+ *
+ * Nothing failed and nothing was charged, so the wording carries no blame and
+ * the offer is the only thing that helps: another link. The sentence it
+ * replaced read as a refusal, and an owner who believes a charge was refused
+ * does not press a button that looks like it charges again.
+ */
+export function ExpiredState({
+  reason,
+  onRegenerate,
+}: {
+  reason: string;
+  onRegenerate: () => void;
+}): JSX.Element {
+  const { outcome, actions } = useActivationCopy();
+  return (
+    <Stack spacing={1} data-testid="verify-charge-expired">
+      <Notice tone="info" title={outcome.expiredTitle} description={reason} />
+      <Stack direction="row">
+        <Button sx={BTN_PRIMARY_SX} onClick={onRegenerate} data-testid="verify-charge-regenerate">
+          {actions.generateNewCharge}
+        </Button>
+      </Stack>
+    </Stack>
+  );
+}

package/src/activation/screens/use-verification-amount.ts

@@ -0,0 +1,42 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+/**
+ * What the activation charge will actually cost, per provider.
+ *
+ * NOT always a cent. At least one provider refuses a one-cent total outright —
+ * InfinitePay answers `422 {"errors":{"items":["Total price must be greater
+ * than 1"]}}`, where the "1" is one REAL — so its verification charges more,
+ * and a button promising one figure while charging another would be exactly the
+ * kind of lie this flow exists to remove.
+ *
+ * Read from the host's endpoint rather than assumed here: the minimum is a fact
+ * about the provider's API, discovered from its own refusal, and a constant in
+ * this package would be wrong for the first adopter whose provider disagrees.
+ *
+ * `null` until it answers — the caller decides what a sentence says before
+ * there is an amount to name, because that is a sentence and sentences are the
+ * host's. The CARD flow does not need this at all: `useActivationCharge` reads
+ * the amount out of the same body it reads the store's card key from.
+ */
+export function useVerificationAmount(verifyChargeUrl: string): number | null {
+  const [amountCents, setAmountCents] = useState<number | null>(null);
+
+  useEffect(() => {
+    let active = true;
+    void fetch(verifyChargeUrl)
+      .then((res) => (res.ok ? (res.json() as Promise<{ amountCents?: number }>) : null))
+      .then((body) => {
+        if (active && typeof body?.amountCents === 'number') setAmountCents(body.amountCents);
+      })
+      // A failed read leaves the amount unnamed rather than guessed — the
+      // screen still renders, and it is corrected the moment an answer lands.
+      .catch(() => undefined);
+    return () => {
+      active = false;
+    };
+  }, [verifyChargeUrl]);
+
+  return amountCents;
+}

package/src/index.ts

@@ -334,37 +334,35 @@ export { PT_BR_PLATFORM_HOMOLOGACAO_COPY } from './components/platform/pt-BR';
 export type { PaymentEnvironment } from '@12-apps/payments-backend';
 
 // ---------------------------------------------------------------------------
-// The REDIRECT ACTIVATION protocol (FUT-463, packaged by FUT-763) — proving a
-// connection can charge, for a provider whose payer pays on its own page.
+// The ACTIVATION STEP (FUT-463, FUT-763, FUT-764) — proving a connection can
+// actually charge, both protocols and the screens that render them.
 //
-// `renderVerification` above stays what it was: the package decides where the
-// step appears and the host owns the screen. What moved is the protocol behind
-// it — resume-on-mount, the return trip's ids, the refusal/expiry/transport
-// distinctions, the bounded wait. Every one of those was learned from a payment
-// that went wrong, and no second host should have to learn them again.
+// A connection is not a capability: a completed grant says the owner authorized
+// us, not that the account can take money. The owner's own card — or a real
+// link they pay on the provider's page — goes through the SAME path a shopper's
+// does, for a small amount, refunded or landing in their own account.
+//
+// Every branch in there was learned from a payment that went wrong: an owner
+// who paid four times, a dead end blaming a store for a key that was never
+// going to exist, a refusal wearing another failure's clothes. The SENTENCES
+// stay the host's, required and defaultless, as everywhere here.
+//
+// Listed in `./activation/public` — see its header for why it is not inline.
 // ---------------------------------------------------------------------------
-export {
-  useRedirectActivation,
-  type RedirectActivation,
-  type RedirectActivationOptions,
-} from './activation/use-redirect-activation';
-export { type RedirectActivationCopy } from './activation/copy';
-export {
-  creationFailure,
-  postActivation,
-  refusedByProvider,
-  settleActivationPoll,
-  type ActivationClock,
-  type ActivationPendingBody,
-  type ActivationPollBody,
-  type RedirectActivationState,
-  type SettlePollIo,
-} from './activation/redirect-state';
-export {
-  clearReturnedSettlement,
-  takeReturnedSettlement,
-  RETURNED_SETTLEMENT_KEY,
-} from './activation/returned-settlement';
+export * from './activation/public';
+
+// ---------------------------------------------------------------------------
+// The two payment LEDGERS (FUT-764) — every charge raised against every order,
+// and the subset where the provider captured LESS than the order was worth.
+//
+// UI-free on purpose. There is no component in that folder: a ledger is a
+// table, every host already has one, and a grid slot wide enough to satisfy
+// them all would be a worse contract than handing over rows. What moves is
+// what a host was deriving twice and getting subtly wrong both times — which
+// amount is "captured" when the audit diff and the payment row disagree, why a
+// decision is shown INSTEAD of the order status, and what still counts as work.
+// ---------------------------------------------------------------------------
+export * from './ledger';
 
 // ---------------------------------------------------------------------------
 // The connect ROUND TRIP's other end (FUT-763): what the OAuth callback
@@ -378,23 +376,3 @@ export {
   type ConnectErrorCode,
   type ConnectReturn,
 } from './components/connect-return';
-
-// ---------------------------------------------------------------------------
-// The ACTIVATION CHARGE (FUT-463, packaged by FUT-763) — proving a connection
-// can charge, for a provider whose payer pays HERE.
-//
-// A connection is not a capability: a completed grant says the owner authorized
-// us, not that the account can take money. The owner's own card goes through
-// the SAME path a shopper's does — same fields, same validation, same
-// browser-side encryption — for one cent, refunded immediately.
-//
-// The sibling of `useRedirectActivation` for the other half of the same step.
-// As there, the SCREEN stays the host's.
-// ---------------------------------------------------------------------------
-export {
-  useActivationCharge,
-  type ActivationCharge,
-  type ActivationChargeOptions,
-  type ActivationChargeState,
-} from './activation/use-activation-charge';
-export { type ActivationChargeCopy } from './activation/charge-copy';

package/src/ledger/index.ts

@@ -0,0 +1,17 @@
+export {
+  toShortPaymentRows,
+  type ShortPaymentOutcomeCopy,
+  type ShortPaymentRow,
+} from './rows';
+export {
+  ledgerParams,
+  ledgerSearch,
+  ledgerSearchTerm,
+  ledgerSort,
+  type LedgerSort,
+} from './query';
+export {
+  type LedgerFormatters,
+  type PaymentLedgerWire,
+  type ShortPaymentWire,
+} from './wire';

package/src/ledger/query.ts

@@ -0,0 +1,81 @@
+/**
+ * The URL a ledger page is bookmarkable at, and the request it becomes.
+ *
+ * A server-driven list keeps its search, its sort and its page in the address
+ * bar so a link an operator sends to a colleague opens the same rows. Both
+ * ledgers do it identically, and both got the same two things subtly wrong
+ * when written twice:
+ *
+ * - a facet value from a stale bookmark forwarded straight into a 400, which
+ *   replaces the WHOLE page — grid, selector and all — with an error whose only
+ *   affordance re-requests the same bad URL;
+ * - the default facet included in the query, so the react-query key differed
+ *   between an operator who arrived with `?view=all` and one who arrived with
+ *   nothing, and the identical list was fetched twice and cached apart.
+ */
+
+/** The params a ledger grid owns and forwards verbatim. */
+const OWNED = ['q', 'page', 'sort'] as const;
+
+/** A sort as the wire spells it, or nothing when the URL carries none. */
+export interface LedgerSort {
+  id: string;
+  dir: 'asc' | 'desc';
+}
+
+/**
+ * The query string for the current URL.
+ *
+ * `facet` is passed already SANITIZED — a caller resolves an unknown value to
+ * its default first — and omitted when it IS the default, so the request and
+ * the cache key are identical however the operator arrived.
+ */
+export function ledgerSearch(
+  params: URLSearchParams,
+  facet?: { key: string; value: string; fallback: string },
+): string {
+  const query = new URLSearchParams();
+  for (const key of OWNED) {
+    const value = params.get(key);
+    if (value) query.set(key, value);
+  }
+  if (facet && facet.value !== facet.fallback) query.set(facet.key, facet.value);
+  return query.toString();
+}
+
+/** The sort the URL is carrying, if it is carrying a well-formed one. */
+export function ledgerSort(params: URLSearchParams): LedgerSort[] {
+  const [id, dir] = (params.get('sort') ?? '').split(':');
+  if (!id || !dir) return [];
+  return [{ id, dir: dir === 'desc' ? 'desc' : 'asc' }];
+}
+
+/** The search term the URL is carrying. */
+export function ledgerSearchTerm(params: URLSearchParams): string {
+  return params.get('q') ?? '';
+}
+
+/**
+ * A grid query mapped back onto the params a ledger URL owns.
+ *
+ * `dir` accepts `null` as well as absent, because that is what a real grid
+ * produces: a column can be in the sort list with no direction chosen yet, and
+ * a data-grid library spells that `null` rather than by leaving the key out.
+ * The runtime always treated the two the same — an unsorted column contributes
+ * no `sort` param — so this is the TYPE catching up with the behaviour rather
+ * than a change to it. Typed the other way, every adopter writes the same
+ * `?? undefined` mapping at the call site, which is exactly the boilerplate
+ * this module exists to delete.
+ */
+export function ledgerParams(query: {
+  search: string;
+  page: number;
+  sortBy: readonly { id: string; dir?: 'asc' | 'desc' | null }[];
+}): Record<string, string | undefined> {
+  const sort = query.sortBy[0];
+  return {
+    q: query.search || undefined,
+    page: query.page > 1 ? String(query.page) : undefined,
+    sort: sort?.dir ? `${sort.id}:${sort.dir}` : undefined,
+  };
+}

package/src/ledger/rows.ts

@@ -0,0 +1,85 @@
+import type { LedgerFormatters, ShortPaymentWire } from './wire';
+
+/**
+ * The short-payment queue's display projection.
+ *
+ * Three of these five decisions are the reason this is not a `map` a host
+ * writes for itself, and each one has been wrong in production:
+ *
+ * - **Which amount is "captured".** The audit diff can be missing it, and the
+ *   payment row beside it is the same money seen by a second witness. Reading
+ *   only the diff printed a dash where real money had landed.
+ * - **What the row's SITUATION is.** An operator's decision is shown INSTEAD of
+ *   the order status, not beside it: a refunded shortfall leaves the order
+ *   FAILED forever, so reading the status alone keeps calling finished work
+ *   unreconciled — the same reason a sidebar badge has to subtract decisions.
+ * - **Whether the row is still WORK.** `pending` is what the row actions hang
+ *   off, and a settled order with no decision recorded is not work either.
+ */
+
+/** A wire row shaped for a table. Labels are formatted; `pending` is a fact. */
+export interface ShortPaymentRow extends Record<string, unknown> {
+  id: string;
+  detectedAtLabel: string;
+  orderId: string;
+  expectedLabel: string;
+  capturedLabel: string;
+  shortfallLabel: string;
+  outcomeLabel: string;
+  methodLabel: string;
+  chargeLabel: string;
+  /** Drives the row actions: a decided shortfall offers none. */
+  pending: boolean;
+}
+
+/**
+ * What the SITUATION column can say, in the host's words.
+ *
+ * Two tables rather than one, because they answer different questions: what an
+ * operator DECIDED, and — when nobody has — what the order's status implies. A
+ * status or resolution with no entry falls through as its own raw value, which
+ * is the honest answer for a state this package has not met.
+ */
+export interface ShortPaymentOutcomeCopy {
+  /** Keyed by `resolution` — `SETTLED`, `REFUNDED`. */
+  readonly resolution: Readonly<Record<string, string>>;
+  /** Keyed by `orderStatus`, for a row nobody has decided yet. */
+  readonly orderStatus: Readonly<Record<string, string>>;
+}
+
+/** The decision if there is one, else what the order's status implies. */
+function outcomeLabel(
+  entry: ShortPaymentWire,
+  copy: ShortPaymentOutcomeCopy,
+  placeholder: string,
+): string {
+  if (entry.resolution) return copy.resolution[entry.resolution] ?? entry.resolution;
+  if (!entry.orderStatus) return placeholder;
+  return copy.orderStatus[entry.orderStatus] ?? entry.orderStatus;
+}
+
+export function toShortPaymentRows(
+  entries: ShortPaymentWire[],
+  format: LedgerFormatters,
+  copy: ShortPaymentOutcomeCopy,
+): ShortPaymentRow[] {
+  const money = (cents: number | null): string =>
+    cents === null ? format.placeholder : format.amount(cents);
+
+  return entries.map((entry) => ({
+    id: entry.id,
+    detectedAtLabel: format.dateTime(entry.detectedAt),
+    orderId: entry.orderId,
+    expectedLabel: money(entry.expectedCents),
+    // Same money, two witnesses: prefer the audit diff, fall back to the
+    // payment row it was joined to. Reading only the diff printed a dash over
+    // a capture that had really happened.
+    capturedLabel: money(entry.capturedCents ?? entry.payment?.amountCents ?? null),
+    shortfallLabel: money(entry.shortfallCents),
+    outcomeLabel: outcomeLabel(entry, copy, format.placeholder),
+    methodLabel: entry.method ?? format.placeholder,
+    chargeLabel: entry.providerChargeId ?? format.placeholder,
+    // Still work: nobody decided, and the order did not settle by itself.
+    pending: entry.resolution === null && entry.orderStatus !== 'PAID',
+  }));
+}

package/src/ledger/wire.ts

@@ -0,0 +1,58 @@
+/**
+ * The two payment LEDGERS a store operator reads (FUT-764 burn-down).
+ *
+ * Every charge raised against every order, and the subset where the provider
+ * captured LESS than the order was worth. Both are server-driven lists over
+ * rows this package's own tables produce, and every host that mounts the
+ * payments platform has both — which is why the projection, the query mapping
+ * and the one write live here rather than being derived again per adopter.
+ *
+ * Deliberately UI-FREE. There is no component in this folder and no design
+ * system anywhere near it: a ledger is a table, every host already has one, and
+ * a grid slot wide enough to satisfy them all would be a worse contract than
+ * handing over rows. What a host renders is its own; WHAT IT MEANS is here.
+ */
+
+/** One row of the store's payment ledger, as the API answers it. */
+export interface PaymentLedgerWire {
+  id: string;
+  createdAt: string;
+  orderId: string | null;
+  status: string;
+  provider: string | null;
+  method: string | null;
+  amountCents: number;
+  /** What the order was worth, when this charge fell short of it. */
+  expectedCents?: number | null;
+  /** The gap, present only on a short capture. */
+  shortfallCents?: number | null;
+  providerChargeId: string | null;
+}
+
+/** One row of the short-payment reconciliation queue, as the API answers it. */
+export interface ShortPaymentWire {
+  id: string;
+  detectedAt: string;
+  orderId: string;
+  orderStatus: string | null;
+  capturedCents: number | null;
+  expectedCents: number | null;
+  shortfallCents: number | null;
+  method: string | null;
+  providerChargeId: string | null;
+  /** The payment row the money actually landed on — the second witness. */
+  payment: { id: string; status: string; amountCents: number; createdAt: string } | null;
+  /** `SETTLED` / `REFUNDED` once an operator decided; null while waiting. */
+  resolution: string | null;
+  resolvedAt: string | null;
+}
+
+/** How a host writes the two things a ledger row is made of. */
+export interface LedgerFormatters {
+  /** A cents amount, in the operator's language and this product's currency. */
+  amount: (cents: number) => string;
+  /** A wire timestamp, as the operator reads dates elsewhere in the console. */
+  dateTime: (iso: string) => string;
+  /** What stands in for a field the row does not carry. */
+  placeholder: string;
+}