@12-apps/payments-frontend 1.0.0

package/src/components/ProviderStatusBar.tsx

@@ -0,0 +1,192 @@
+'use client';
+
+import { Box, Chip, FormControlLabel, Stack, Switch, Tooltip, Typography } from '@mui/material';
+
+import type { MaskedProviderConfig, ProviderDescriptor } from '@12-apps/payments-backend';
+
+import { isConnected } from './connection-state';
+
+/**
+ * The provider's headline: what state it is in, and the switch that decides
+ * whether real buyers are sent to it.
+ *
+ * Its own file since the credential form grew past what one module should
+ * carry, and because this bar is rendered above BOTH connection branches —
+ * it belongs to the provider, not to the form.
+ */
+
+/** What the chip says, in the owner's language, and what it is claiming. */
+interface StatusBadge {
+  label: string;
+  color: 'default' | 'info' | 'success' | 'error';
+}
+
+/**
+ * Three different facts used to share one word.
+ *
+ * The chip printed the stored `status` verbatim, so a store that had passed
+ * "Testar conexão" read `VERIFIED` — and `VERIFIED` is a claim about
+ * CREDENTIALS AUTHENTICATING, nothing more. PagBank answers yes to it while
+ * refusing every real charge until homologação; InfinitePay answers yes with
+ * Checkout Integrado switched off, which creates no links at all. An owner
+ * reading "verified" reasonably concludes the store can take money.
+ *
+ * So the technical fact and the money fact get different words. `CONEXÃO OK`
+ * says the account was reached. `VERIFICADO` is reserved for `chargeVerifiedAt`
+ * — a real payment that actually landed — and is the only one painted green.
+ */
+export function statusBadge(
+  config: MaskedProviderConfig | null,
+  descriptor?: ProviderDescriptor,
+): StatusBadge {
+  if (config?.chargeVerifiedAt) return { label: 'VERIFICADO', color: 'success' };
+  // A store that has entered nothing has not FAILED at anything. The stored
+  // status outlives the credential it described — clearing the field leaves the
+  // last verdict behind — so a red FALHOU sat above an empty form, accusing the
+  // owner of a mistake they had not yet had the chance to make.
+  if (descriptor && !anyCredentialStored(config, descriptor)) {
+    return { label: 'NÃO VERIFICADO', color: 'default' };
+  }
+  if (config?.status === 'RECONNECT_REQUIRED') return { label: 'RECONECTAR', color: 'error' };
+  if (isConnected(config)) return { label: 'CONEXÃO OK', color: 'info' };
+  // A FAILED probe lands here, and it says NÃO VERIFICADO like every other
+  // not-yet-connected state. `FALHOU` was a third word for the same fact — the
+  // store cannot take money through this provider yet — and it was the only
+  // one painted red, so a mistyped InfiniteTag read as a system fault rather
+  // than as a step still to finish. The probe's own sentence is directly
+  // underneath and says WHICH tag and WHAT to do about it, which no chip can.
+  //
+  // `RECONNECT_REQUIRED` stays red on purpose: that one is a connection that
+  // WAS working and stopped, which is news rather than a step.
+  return { label: 'NÃO VERIFICADO', color: 'default' };
+}
+
+/**
+ * Does this provider hold any credential at all in the environment in use?
+ *
+ * Only meaningful for providers that HAVE a credential form: under OAuth the
+ * grant is the credential and no field is ever filled, so those keep whatever
+ * the probe last said.
+ */
+function anyCredentialStored(
+  config: MaskedProviderConfig | null,
+  descriptor: ProviderDescriptor,
+): boolean {
+  // `?? []` because a descriptor may legitimately declare no schema at all, and
+  // a status chip must never be the thing that throws on a settings screen.
+  if ((descriptor.credentialSchema ?? []).length === 0) return true;
+  if (!config) return false;
+  const stored = config.environments[config.environment] ?? {};
+  return Object.values(stored).some((field) => field.configured);
+}
+
+/**
+ * May the switch be touched, and if not, why not?
+ *
+ * Activation is EARNED BY CHARGING. The status chip cannot be the gate, and
+ * that is the whole lesson: `VERIFIED` comes from the credential probe, which
+ * only asks whether the keys authenticate. A PagBank Connect grant answers yes
+ * to that while refusing every real charge with `403 ACCESS_DENIED` until the
+ * integration is homologated — so a store read `PagBank [VERIFIED] [on] Ativo`
+ * and declined every shopper.
+ *
+ * Two qualifications, both learned the hard way:
+ *
+ *  - Only providers that CAN charge are held to having charged. Stripe and
+ *    InfinitePay have no browser tokenization written, so requiring the proof
+ *    would not make their "Ativo" honest — it would make them unactivatable.
+ *  - Turning OFF is never blocked. An owner must be able to pull a provider out
+ *    of rotation at once, and rows enabled before this rule existed would
+ *    otherwise be stuck on with no way down.
+ *
+ * The hint names no amount. It used to promise "a cobrança de teste de R$ 0,01"
+ * while the step it points at charges R$ 1,01 for InfinitePay, which refuses a
+ * one-cent total outright — the figure is a per-provider fact this component
+ * does not have, and quoting it from here could only ever be a guess.
+ */
+function toggleGate(
+  descriptor: ProviderDescriptor,
+  config: MaskedProviderConfig | null,
+  enabled: boolean,
+): { lockedOff: boolean; hint: string } {
+  const provable = descriptor.capabilities?.activationCharge === true;
+  // `chargeVerifiedAt` PERSISTS once set, so an owner who paused a proven
+  // provider can resume it without charging a second time.
+  const ready = provable ? Boolean(config?.chargeVerifiedAt) : isConnected(config);
+  const lockedOff = !ready && !enabled;
+  if (!lockedOff) return { lockedOff, hint: '' };
+  return {
+    lockedOff,
+    hint: provable
+      ? 'Este provedor só passa a receber vendas depois dos 3 passos abaixo.'
+      : 'Conecte e verifique o provedor antes de ativar as vendas.',
+  };
+}
+
+/**
+ * Status chip + the "recebendo vendas" switch, hoisted OUT of the credential
+ * form.
+ *
+ * These belong to the provider, not to the form: a store that connected by
+ * OAuth is told no key needs copying, so it has no reason to open the
+ * "Prefiro informar as credenciais manualmente" disclosure — and while this
+ * lived inside it, the switch that actually lets checkout charge was hidden in
+ * there. The connect card said "conectado" and the page said "nenhum provedor
+ * está ativo", with the control to reconcile them out of sight.
+ *
+ * The switch is labelled with its CONSEQUENCE rather than with "Ativo". "Ativo"
+ * is a word about a database row; "Recebendo vendas" is the thing the owner is
+ * deciding, and the difference matters most in the state where the control is
+ * dead — where "Ativo" plus a greyed-out toggle reads as a broken screen unless
+ * you hover it. The reason is printed underneath instead of hidden in a
+ * tooltip, since the owner who most needs it is the one who cannot click.
+ */
+export function ProviderStatusBar({
+  descriptor,
+  config,
+  busy,
+  onToggle,
+}: {
+  descriptor: ProviderDescriptor;
+  config: MaskedProviderConfig | null;
+  busy: boolean;
+  onToggle: (enabled: boolean) => void;
+}) {
+  const enabled = config?.enabled ?? false;
+  const { lockedOff, hint } = toggleGate(descriptor, config, enabled);
+  const badge = statusBadge(config, descriptor);
+
+  return (
+    <Stack spacing={0.5}>
+      <Stack direction="row" spacing={1} alignItems="center">
+        <Typography variant="h6">{descriptor.displayName}</Typography>
+        <Chip size="small" data-testid="payments-status" label={badge.label} color={badge.color} />
+        {/* The switch belongs at the far edge: it is the one control here that
+            changes what buyers experience, and crowding it against the status
+            chip made the two read as one compound widget. */}
+        <Box sx={{ flexGrow: 1 }} />
+        <Tooltip title={hint}>
+          {/* A disabled control fires no events, so the tooltip needs a live wrapper. */}
+          <span>
+            <FormControlLabel
+              control={
+                <Switch
+                  data-testid="payments-enabled-toggle"
+                  checked={enabled}
+                  disabled={busy || lockedOff}
+                  onChange={(_, next) => onToggle(next)}
+                />
+              }
+              label={enabled ? 'Recebendo vendas' : 'Não está recebendo'}
+            />
+          </span>
+        </Tooltip>
+      </Stack>
+      {lockedOff ? (
+        <Typography variant="caption" color="text.secondary" data-testid="payments-enable-hint">
+          {hint}
+        </Typography>
+      ) : null}
+    </Stack>
+  );
+}

package/src/components/SetupGuideSection.tsx

@@ -0,0 +1,190 @@
+'use client';
+
+import { Box } from '@mui/material';
+import type { JSX, ReactNode } from 'react';
+
+import type { ProviderSetupGuide as Guide, SetupSection } from '@12-apps/payments-backend';
+
+import { DoneRow } from './CredentialFields';
+import { ProviderSetupGuide } from './ProviderSetupGuide';
+
+/**
+ * The walkthrough, plus the one step whose completion only the OWNER can
+ * report.
+ *
+ * ## The action id is a contract, like PagBank's
+ *
+ * `SetupStep.action` has always been an opaque id an adapter and a host agree
+ * on out of band — PagBank's `homologacao-anexo` asks the host to generate the
+ * evidence file its review form wants. This is the second such agreement, and
+ * the first whose answer is a FACT rather than a side effect: InfinitePay ships
+ * Checkout Integrado disabled and publishes nothing that reports its state, so
+ * the only reading available is the owner's.
+ *
+ * A guide that offers this action is asking "have you done this?", and a host
+ * that handles it owes an answer it can remember.
+ */
+export const CHECKOUT_CONFIRM_ACTION = 'checkout-integrado-confirmado';
+
+/** Does this section end in a question only the owner can answer? */
+function isConfirmable(section: SetupSection): boolean {
+  return section.steps.some((step) => step.action === CHECKOUT_CONFIRM_ACTION);
+}
+
+/**
+ * Which stage the walkthrough is REALLY on.
+ *
+ * The server reports what it can prove — credentials that reach an account, a
+ * charge that landed — and that is not the whole answer. One step in the middle
+ * can only be confirmed by the owner, because no API reports whether Checkout
+ * Integrado is switched on. Left to the server's number alone the screen ticked
+ * that step off and jumped to step 3 the moment the probe passed, having never
+ * shown it.
+ *
+ * So an unconfirmed confirmable section holds the walkthrough where it is. And
+ * `editing` beats everything: reopening a finished step means going back to it.
+ */
+function effectiveStage(
+  guide: Guide,
+  confirmed: boolean,
+  editing: boolean,
+  stored = true,
+): number {
+  const stage = guide.activeStage ?? 0;
+  if (editing) return 0;
+  // Nothing stored for the environment being LOOKED AT ⇒ step 1, whatever the
+  // active environment has achieved. `activeStage` is computed from the config
+  // the store actually charges with, so on the other tab it reported progress
+  // made somewhere else — a walkthrough claiming steps 1 and 2 were done over
+  // an empty Produção field, on the screen whose whole subject is which
+  // account receives the money.
+  if (!stored) return 0;
+  if (confirmed) return stage;
+  const waiting = confirmableStage(guide);
+  return waiting < 0 ? stage : Math.min(stage, waiting);
+}
+
+/** Index of the stage whose section ends in a question only the owner can answer. */
+function confirmableStage(guide: Guide): number {
+  return guide.stages.findIndex((stage) => {
+    const section = guide.sections.find((candidate) => candidate.id === stage.id);
+    return section ? isConfirmable(section) : false;
+  });
+}
+
+/**
+ * The section the walkthrough is showing, or null when it has nothing left.
+ *
+ * Exported because the ACTIVATION STEP needs the same answer: it is the last
+ * stage, so it may only appear once the guide is out of sections. Computing it
+ * twice is how the screen ended up rendering "Passo 3 · Ative as vendas" —
+ * complete with its pay button — directly under "Passo 2".
+ */
+export function openSection(
+  guide: Guide | null,
+  confirmed: boolean,
+  editing: boolean,
+  stored = true,
+) {
+  if (!guide) return null;
+  return sectionAt(guide, effectiveStage(guide, confirmed, editing, stored));
+}
+
+/** The section paired with a stage, when the adapter ships one for it. */
+function sectionAt(guide: Guide, stage: number): SetupSection | null {
+  const wanted = guide.stages[stage];
+  if (!wanted) return null;
+  return guide.sections.find((section) => section.id === wanted.id) ?? null;
+}
+
+export interface SetupGuideSectionProps {
+  guide: Guide | null;
+  /** The owner has confirmed the step that only they can see. */
+  confirmed: boolean;
+  onConfirm: () => void;
+  /** Re-open the confirmed step — the owner wants to check it again. */
+  onReopen: () => void;
+  /** Rows for steps finished elsewhere (a saved credential), shown alongside. */
+  rows?: ReactNode;
+  /** The live control for the open step — the credential form. */
+  sectionFooter?: ReactNode;
+  /** The owner has reopened a finished step; show that step, not the current one. */
+  editing?: boolean;
+  /** The environment on screen holds its credentials — see `renderGuide`. */
+  stored?: boolean;
+}
+
+/**
+ * A confirmed step collapses to one line, exactly as a saved credential does.
+ *
+ * Not removed: "I told you this was on" is the claim step 3 is about to test,
+ * and when the provider then refuses to mint a link, the owner needs the row
+ * still there to press Revisar on.
+ */
+function ConfirmedRow({ section, onReopen }: { section: SetupSection; onReopen: () => void }) {
+  return (
+    <DoneRow
+      testId="payments-setup-confirmed"
+      label={section.doneSummary?.label ?? section.title}
+      value={section.doneSummary?.value ?? 'Confirmado por você'}
+      editLabel="Revisar"
+      onEdit={onReopen}
+    />
+  );
+}
+
+export function SetupGuideSection({
+  guide,
+  confirmed,
+  onConfirm,
+  onReopen,
+  rows,
+  sectionFooter,
+  editing = false,
+  stored = true,
+}: SetupGuideSectionProps): JSX.Element {
+  // No walkthrough — PagBank ships none, because under Connect the platform is
+  // reviewed centrally and the owner has nothing to follow. The SLOTS still
+  // have to render: they are the credential form, and swallowing them left a
+  // provider with a status chip, a pair of environment tabs and no way to type
+  // anything in.
+  if (!guide) {
+    return (
+      <>
+        {rows}
+        {sectionFooter}
+      </>
+    );
+  }
+
+  const stage = effectiveStage(guide, confirmed, editing, stored);
+  const open = sectionAt(guide, stage);
+  // The confirmed step keeps a row of its own once the walkthrough has moved
+  // past it — it is the claim step 3 is about to test, and when the provider
+  // refuses to mint a link the owner needs somewhere to press Revisar.
+  const settledStage = confirmableStage(guide);
+  const settled = confirmed && !editing && settledStage >= 0 && stage > settledStage;
+  const settledSection = settled ? sectionAt(guide, settledStage) : null;
+
+  return (
+    <Box data-testid="payments-setup">
+      <ProviderSetupGuide
+        guide={{ ...guide, sections: open ? [open] : [] }}
+        activeStage={stage}
+        actions={{
+          [CHECKOUT_CONFIRM_ACTION]: {
+            label: 'Já habilitei o Checkout Integrado',
+            run: onConfirm,
+          },
+        }}
+        beforeSections={
+          <>
+            {rows}
+            {settledSection ? <ConfirmedRow section={settledSection} onReopen={onReopen} /> : null}
+          </>
+        }
+        sectionFooter={sectionFooter}
+      />
+    </Box>
+  );
+}

package/src/components/checkout-ack.ts

@@ -0,0 +1,106 @@
+import { useCallback, useSyncExternalStore } from 'react';
+
+/**
+ * "I have switched Checkout Integrado on" — the one setup fact no API answers.
+ *
+ * InfinitePay ships Checkout Integrado disabled and exposes nothing that
+ * reports its state: `payment_check` resolves the handle and stops there. So a
+ * store can pass "Testar conexão", read a green result, and still be unable to
+ * create a single payment link. The only way to know is to ask the owner, and
+ * the only honest thing to do with the answer is treat it as a claim — which
+ * step 3 then either confirms, by minting a link, or refutes, by being refused.
+ *
+ * ## Why the browser keeps it
+ *
+ * It is not a fact about the merchant's account, it is a fact about what the
+ * owner has told us, so putting it in `payment_provider_configs` would dress a
+ * self-report up as provider state — and the schema already carries one field
+ * (`chargeVerifiedAt`) that means "proved by money moving". Two fields one
+ * letter apart in meaning is how a screen ends up claiming a store can charge.
+ *
+ * `localStorage` and not React state because the flow deliberately LEAVES the
+ * page: the owner pays on InfinitePay's site and comes back. In-memory, that
+ * round trip would drop the acknowledgement and bounce them to step 2 —
+ * hiding the panel that is polling the payment they just made.
+ *
+ * Keyed by the client's base URL, which is tenant-scoped
+ * (`/api/admin/<slug>/payments`), so an owner who administers two stores does
+ * not confirm the setting once and have it apply to the other.
+ */
+
+function storageKey(scope: string, provider: string): string {
+  return `payments:checkout-confirmed:${scope}:${provider}`;
+}
+
+/** Cross-component notification — two panels must not disagree about this. */
+const listeners = new Set<() => void>();
+
+function subscribe(listener: () => void): () => void {
+  listeners.add(listener);
+  // A confirmation made in another TAB is the same owner saying the same
+  // thing; nothing here should contradict it.
+  window.addEventListener('storage', listener);
+  return () => {
+    listeners.delete(listener);
+    window.removeEventListener('storage', listener);
+  };
+}
+
+/**
+ * Every read and write is guarded: `localStorage` throws outright in a
+ * partitioned or storage-blocked context, and a setup screen must not go blank
+ * because a browser declined to remember a checkbox. Unavailable storage
+ * simply means "not confirmed yet" — the owner confirms again, which costs a
+ * click and nothing else.
+ */
+function read(key: string): boolean {
+  try {
+    return window.localStorage.getItem(key) === 'true';
+  } catch {
+    return false;
+  }
+}
+
+function write(key: string, value: boolean): void {
+  try {
+    if (value) window.localStorage.setItem(key, 'true');
+    else window.localStorage.removeItem(key);
+  } catch {
+    // Nothing to recover: the caller's UI already reflects the intent, and the
+    // worst case is being asked to confirm once more on the next visit.
+  }
+  listeners.forEach((listener) => listener());
+}
+
+interface CheckoutAck {
+  /** The owner has said Checkout Integrado is on for this store. */
+  confirmed: boolean;
+  confirm: () => void;
+  /**
+   * Withdraw it. Called when the provider REFUSES to mint a link, which is the
+   * strongest available evidence that the setting is in fact off — leaving the
+   * claim standing there would keep the owner on a step 3 that cannot work.
+   */
+  withdraw: () => void;
+}
+
+export function useCheckoutAck(scope: string, provider: string | null): CheckoutAck {
+  const key = provider ? storageKey(scope, provider) : null;
+
+  const confirmed = useSyncExternalStore(
+    subscribe,
+    () => (key ? read(key) : false),
+    // Server render: nothing is confirmed, which is the state that shows the
+    // step rather than the state that skips it.
+    () => false,
+  );
+
+  const confirm = useCallback(() => {
+    if (key) write(key, true);
+  }, [key]);
+  const withdraw = useCallback(() => {
+    if (key) write(key, false);
+  }, [key]);
+
+  return { confirmed, confirm, withdraw };
+}

package/src/components/connection-state.ts

@@ -0,0 +1,66 @@
+import type { MaskedProviderConfig } from '@12-apps/payments-backend';
+
+/**
+ * Is there actually a connection here?
+ *
+ * The one definition, because the screen shipped with two. Disconnecting does
+ * NOT delete the row — it empties every environment's credentials and resets
+ * the status — so `config !== null` keeps answering "yes" for a store that has
+ * nothing left to charge with. The provider list said `Conectado` while the
+ * panel one click away offered `Conectar com PagBank`.
+ *
+ * `RECONNECT_REQUIRED` counts as connected on purpose: that store demonstrably
+ * worked and still holds credentials, it is the AUTHORIZATION that lapsed.
+ */
+export function isConnected(config: MaskedProviderConfig | null | undefined): boolean {
+  const status = config?.status;
+  return status === 'VERIFIED' || status === 'RECONNECT_REQUIRED';
+}
+
+/**
+ * Is there enough here to attempt the activation charge?
+ *
+ * Deliberately NOT {@link isConnected}. That reads `status`, which only the
+ * credential PROBE sets — so a store that had pasted perfectly good keys saw no
+ * activation step at all until it ran "Testar conexão" first, and for a
+ * key-based provider that probe answers a question nobody asked. The charge is
+ * the real test; making it wait behind a weaker one is backwards.
+ *
+ * Credentials in the ACTIVE environment are the bar, plus `isConnected` for the
+ * OAuth case, where the grant is the credential and no field is ever filled in.
+ */
+export function canAttemptCharge(config: MaskedProviderConfig | null | undefined): boolean {
+  if (!config) return false;
+  if (isConnected(config)) return true;
+  // Credentials alone are NOT enough for a provider whose activation charge is
+  // a real payment. Offering "Pagar R$1,01 e ativar" beside an UNVERIFIED tag
+  // invites an owner to send real money through a handle nothing has checked —
+  // and a mistyped InfiniteTag pays a stranger, irreversibly. It also put the
+  // step-3 card on screen while the walkthrough was still saying "step 2: go
+  // enable Checkout", which is two answers to "what do I do now".
+  //
+  // The probe is one click and costs nothing, so requiring it first takes away
+  // no capability — it just orders the two steps the way the guide already
+  // describes them.
+  if (config.chargeVerifiedAt) return true;
+  return false;
+}
+
+/** What a provider card reports at a glance. */
+type ConnectionBadge =
+  | { label: 'Ativo'; color: 'success' }
+  | { label: 'Conectado'; color: 'default' }
+  | { label: 'Reconectar'; color: 'error' }
+  | { label: 'Não conectado'; color: 'warning' };
+
+/**
+ * `enabled` is deliberately checked first: it is the only state that means
+ * money can move, and a store reading `Ativo` has already passed everything
+ * below it.
+ */
+export function connectionBadge(config: MaskedProviderConfig | null): ConnectionBadge {
+  if (config?.enabled) return { label: 'Ativo', color: 'success' };
+  if (config?.status === 'RECONNECT_REQUIRED') return { label: 'Reconectar', color: 'error' };
+  if (isConnected(config)) return { label: 'Conectado', color: 'default' };
+  return { label: 'Não conectado', color: 'warning' };
+}

package/src/components/credential-rules.ts

@@ -0,0 +1,120 @@
+import type {
+  CredentialFieldSpec,
+  MaskedProviderConfig,
+  PaymentEnvironment,
+  ProviderDescriptor,
+} from '@12-apps/payments-backend';
+
+import type { PendingSave } from './ConfirmCredentialSave';
+
+/**
+ * The DECISIONS the credential form makes, with no JSX anywhere near them.
+ *
+ * Each one is a rule about money rather than about layout — is there anything
+ * stored to probe, could this value possibly be a real handle, is it changing
+ * at all, what does the button commit — and every one of them was learned from
+ * a screen that got it wrong. Kept together, and apart from the rendering, so
+ * they can be read as the set of rules they are.
+ */
+
+/**
+ * Is there actually something stored to probe?
+ *
+ * Read from the SERVER's answer to the save rather than from the form: blank
+ * fields are preserved rather than cleared, so what the browser just typed does
+ * not describe what is now on record.
+ */
+export function allRequiredStored(
+  descriptor: ProviderDescriptor,
+  config: MaskedProviderConfig,
+  environment: PaymentEnvironment,
+): boolean {
+  const stored = config.environments[environment] ?? {};
+  return descriptor.credentialSchema
+    .filter((spec) => spec.required)
+    .every((spec) => stored[spec.key]?.configured === true);
+}
+
+/**
+ * Does every edited field match the SHAPE its provider declares?
+ *
+ * Shape only — it cannot know whether an account exists, which is what the
+ * probe immediately after the save is for. But `$` followed by a few safe
+ * characters is free to check, and it stops the ordinary slips (an e-mail, an
+ * `@handle` with no `$`) reaching a confirmation dialog that would then ask the
+ * owner to vouch for them.
+ */
+export function fieldsWellFormed(
+  descriptor: ProviderDescriptor,
+  values: Record<string, string>,
+): boolean {
+  return descriptor.credentialSchema.every((spec) => {
+    const value = values[spec.key];
+    if (!spec.pattern || value === undefined || value === '') return true;
+    return new RegExp(spec.pattern).test(value.trim());
+  });
+}
+
+export function saveLabel(descriptor: ProviderDescriptor): string {
+  const required = descriptor.credentialSchema.filter((field) => field.required);
+  const only = required.length === 1 ? required[0] : undefined;
+  if (!only) return 'Salvar';
+  return `Salvar ${only.label.replace(/\s*\([^)]*\)\s*$/, '')}`;
+}
+
+/**
+ * The stored value of the field a finished step collapses around.
+ *
+ * Non-secret fields keep their value in `hint` (secrets never leave the
+ * server), so a provider whose one credential is a public handle can show it
+ * back verbatim — which is the entire content of the summary row.
+ *
+ * Deliberately narrow: EXACTLY ONE required field, and it must be readable
+ * back. A form of four fields does not have a one-line summary, and collapsing
+ * it would hide inputs the owner still has to reach — so those providers keep
+ * the form they have always had.
+ */
+export function summaryOf(
+  descriptor: ProviderDescriptor,
+  config: MaskedProviderConfig | null,
+  environment: PaymentEnvironment,
+): { spec: CredentialFieldSpec; value: string } | null {
+  const required = descriptor.credentialSchema.filter((field) => field.required);
+  const spec = required.length === 1 ? required[0] : undefined;
+  if (!spec || spec.secret) return null;
+  const state = config?.environments[environment]?.[spec.key];
+  if (!state?.configured || !state.hint) return null;
+  return { spec, value: state.hint };
+}
+
+/**
+ * Which field, if any, needs reading back before the write.
+ *
+ * Only when it is actually CHANGING: `confirmOnSave` guards against a wrong
+ * value being stored, and re-saving the value already stored cannot introduce
+ * one. Confirming a no-op would train the owner to click through the dialog,
+ * which is the one way to make it useless.
+ */
+export function needsConfirmation(
+  descriptor: ProviderDescriptor,
+  config: MaskedProviderConfig | null,
+  environment: PaymentEnvironment,
+  values: Record<string, string>,
+): PendingSave | null {
+  for (const spec of descriptor.credentialSchema) {
+    if (!spec.confirmOnSave) continue;
+    const next = values[spec.key];
+    if (next === undefined || next === '') continue;
+    if (next === config?.environments[environment]?.[spec.key]?.hint) continue;
+    return { spec, value: next };
+  }
+  return null;
+}
+
+/**
+ * Everything the form remembers, and the two writes it can make.
+ *
+ * Hoisted out of the component so that stays about LAYOUT — which of the two
+ * shapes (fields or summary row) is on screen — while this owns the rules that
+ * decide it. Splitting the two is also what keeps each inside the size gate.
+ */