@12-apps/payments-frontend 1.0.0

package/src/components/CredentialFormAlerts.tsx

@@ -0,0 +1,144 @@
+'use client';
+
+import { Alert, Button, CircularProgress, Stack, Typography } from '@mui/material';
+
+import type { VerifiedProviderConfig } from '@12-apps/payments-backend';
+
+import { ENVIRONMENT_LABELS } from './EnvironmentTabs';
+
+/**
+ * The credential step's alerts and its one button.
+ *
+ * Split from `ProviderCredentialForm` because that file is about the FORM's
+ * state machine — what is typed, what is stored, what the probe last said —
+ * while these three are about the sentences the owner reads when it goes
+ * wrong, and each of those sentences was learned from a screen that got it
+ * wrong in a way that cost somebody money.
+ */
+
+// Named for what it is here, not `ProbeResult` — the payments package already
+// exports a different `ProbeResult` (failover classification).
+export type VerifyProbe = VerifiedProviderConfig['probe'];
+
+/**
+ * What the probe found — only when it found something WRONG.
+ *
+ * A passing probe already has a place to be said: the `CONEXÃO OK` chip in the
+ * header, which persists. Repeating it as a green banner mid-flow added a
+ * fourth block to a screen whose whole point is showing one step at a time,
+ * and said nothing the chip had not. A failure is different: the chip can only
+ * report that something is wrong, not which environment or what to do, so that
+ * one still gets its sentence.
+ */
+export function ProbeAlert({
+  probe,
+  busy,
+  onRetry,
+}: {
+  probe: VerifyProbe;
+  busy: boolean;
+  onRetry: () => void;
+}) {
+  if (probe.ok) return null;
+  const where = ENVIRONMENT_LABELS[probe.environment];
+  // The ADAPTER's sentence when it has one. Only it knows the provider's name,
+  // what that provider's own app calls this field and which screen states it —
+  // "confira as credenciais deste ambiente" is advice you can follow all
+  // afternoon without ever finding the value you were asked to check.
+  const message =
+    probe.message ??
+    `Não foi possível conectar em ${where}. Confira as credenciais deste ambiente.`;
+
+  // An outage is not a rejection. The credential is already SAVED and may well
+  // be perfect; nothing was learned about it. So it is amber rather than red,
+  // and it carries the only control that helps — ask again. Without one the
+  // owner's sole route back was to re-save a value that was never wrong, and
+  // saving is what resets the connection.
+  const unreachable = probe.fault === 'UNREACHABLE';
+  return (
+    <Alert
+      severity={unreachable ? 'warning' : 'error'}
+      data-testid="payments-probe-result"
+      action={
+        unreachable ? (
+          <Button
+            size="small"
+            disabled={busy}
+            onClick={onRetry}
+            data-testid="payments-verify-retry"
+            sx={{ textTransform: 'none' }}
+          >
+            Testar conexão
+          </Button>
+        ) : undefined
+      }
+    >
+      {message}
+    </Alert>
+  );
+}
+
+/**
+ * Changing the tag on a store that has ALREADY proved it can receive.
+ *
+ * The dialog two steps later asks "is this the right account"; this answers a
+ * different question the owner has not thought to ask — what happens to the
+ * store while they do it. A save invalidates the proof and drops the provider
+ * out of the failover chain (`applySaveCredentials`), so the shop stops taking
+ * money through it until a new activation charge lands. That is entirely
+ * correct and entirely invisible, and an owner who came to fix a typo deserves
+ * to learn it before typing rather than from a quiet storefront.
+ */
+export function ReverifyWarning() {
+  return (
+    <Alert severity="warning" data-testid="payments-reverify-warning">
+      Esta loja já está verificada. Trocar a InfiniteTag <strong>exige uma nova verificação</strong>{' '}
+      e a loja <strong>para de receber</strong> por este provedor até que ela termine.
+    </Alert>
+  );
+}
+
+/** Salvar + Testar conexão, each dead when it would do nothing (or harm). */
+/**
+ * One button. Saving IS testing.
+ *
+ * "Testar conexão" was a second button the owner had to know to press, guarding
+ * a step they could not finish without it — and its enablement rule was the
+ * inverse of Salvar's (dead while the form was dirty, live only once it was
+ * clean), so the two took turns being grey for reasons no label explained.
+ * Nothing is learned by separating them: the probe reads what was just stored,
+ * so the only useful moment to run it is immediately after a save.
+ */
+export function FormActions({
+  busy,
+  label,
+  disabled,
+  onSave,
+}: {
+  busy: string | null;
+  label: string;
+  disabled: boolean;
+  onSave: () => void;
+}) {
+  return (
+    <Stack spacing={1} alignItems="flex-start">
+      <Button
+        variant="contained"
+        data-testid="payments-save"
+        disabled={busy !== null || disabled}
+        sx={{ textTransform: 'none' }}
+        onClick={onSave}
+      >
+        {busy === 'save' ? <CircularProgress size={18} /> : label}
+      </Button>
+      {busy === 'verify' ? (
+        <Stack direction="row" spacing={1} alignItems="center" data-testid="payments-verifying">
+          <CircularProgress size={14} />
+          <Typography variant="body2" color="text.secondary">
+            Testando a conexão…
+          </Typography>
+        </Stack>
+      ) : null}
+    </Stack>
+  );
+}

package/src/components/EnvironmentTabs.tsx

@@ -0,0 +1,109 @@
+'use client';
+
+import { Alert, Tab, Tabs } from '@mui/material';
+
+import type { PaymentEnvironment } from '@12-apps/payments-backend';
+
+/** One environment's human name — the tabs and the probe result share it. */
+export const ENVIRONMENT_LABELS: Record<PaymentEnvironment, string> = {
+  SANDBOX: 'Sandbox',
+  PRODUCTION: 'Produção',
+};
+
+/**
+ * Sentence case, because these are place names rather than shouted commands —
+ * MUI upper-cases tab labels by default, which turns "Produção" into signage.
+ */
+const TAB_SX = { textTransform: 'none' } as const;
+
+/**
+ * The two environments as tabs, not a select: there are exactly two, and which
+ * one you are editing changes what every field below it means. A closed
+ * dropdown hides that, and credentials are stored PER environment — so pasting
+ * a production token while "Sandbox" sits collapsed above is a mistake the
+ * control itself should not allow.
+ */
+export function EnvironmentSelector({
+  environment,
+  onChange,
+}: {
+  environment: PaymentEnvironment;
+  onChange: (next: PaymentEnvironment) => void;
+}) {
+  return (
+    <Tabs
+      value={environment}
+      onChange={(_, next: PaymentEnvironment) => onChange(next)}
+      aria-label="Ambiente"
+      data-testid="payments-environment-tabs"
+    >
+      <Tab
+        label="Sandbox"
+        value="SANDBOX"
+        data-testid="payments-environment-SANDBOX"
+        sx={TAB_SX}
+      />
+      <Tab
+        label="Produção"
+        value="PRODUCTION"
+        data-testid="payments-environment-PRODUCTION"
+        sx={TAB_SX}
+      />
+    </Tabs>
+  );
+}
+
+/**
+ * A banner that makes Produção LOOK different from Sandbox.
+ *
+ * Two tabs of identical fields, differing by one word in a tab label, is the
+ * whole of what distinguished "type here and nothing happens" from "type here
+ * and this is what charges your customers". The tab you are on is the least
+ * noticeable thing on the screen, and the consequences of being on the wrong
+ * one are entirely invisible until money moves.
+ *
+ * It states only what this package can actually back. NOT "nothing is real in
+ * Sandbox": whether a sandbox call is faked depends on the deployment, and
+ * InfinitePay has no sandbox at all — a reassurance that is sometimes false is
+ * worse than none. What is always true is that the two credential sets are
+ * separate, and which one serves the store's checkout is `config.environment`
+ * — so when you are looking at the other one, the banner says so.
+ */
+export function EnvironmentNotice({
+  environment,
+  active,
+}: {
+  environment: PaymentEnvironment;
+  /** The environment this store's real checkout uses, when it has one. */
+  active: PaymentEnvironment | null;
+}) {
+  const elsewhere = active !== null && active !== environment ? ENVIRONMENT_LABELS[active] : null;
+  const production = environment === 'PRODUCTION';
+  return (
+    <Alert
+      severity={production ? 'warning' : 'info'}
+      variant="standard"
+      square
+      data-testid={`payments-environment-notice-${environment}`}
+      sx={{ borderRadius: 0, py: 0.5, px: 3 }}
+    >
+      <strong>
+        {production ? 'Produção — dinheiro real.' : 'Sandbox — ambiente de teste.'}
+      </strong>{' '}
+      {production
+        ? 'Tudo o que você fizer aqui vale para as vendas da loja.'
+        : 'Nenhum valor sai ou entra de verdade.'}
+      {elsewhere ? ` Hoje a loja está usando ${elsewhere}.` : ''}
+    </Alert>
+  );
+}
+
+/**
+ * The banner is deliberately NOT bundled with the tabs any more.
+ *
+ * It has to run edge to edge across the provider card — a full-bleed strip is
+ * what makes it read as a property of everything below it, rather than as one
+ * more paragraph indented inside the content. That is only possible if the card
+ * has a padded header and an unpadded band between it and the body, so the two
+ * halves are placed separately by `ActivePanel`.
+ */

package/src/components/PaymentProviderSettings.tsx

@@ -0,0 +1,267 @@
+'use client';
+
+import { Alert, Box, Button, CircularProgress } from '@mui/material';
+import type { ReactNode } from 'react';
+
+import type { MaskedProviderConfig } from '@12-apps/payments-backend';
+
+import type { PaymentsSettingsClient } from '../client';
+import { canAttemptCharge } from './connection-state';
+import { ProviderList } from './ProviderList';
+import { ActivePanel, type ActivePanelProps, type PrepareConnect } from './ProviderPanel';
+import {
+  guideAwaitsConfirmation,
+  progressKeyOf,
+  useOpenProvider,
+  useSelectedProvider,
+  useSettingsState,
+  useSetupConfirmation,
+  useSetupGuide,
+} from './settings-state';
+import { openSection, SetupGuideSection } from './SetupGuideSection';
+
+/**
+ * Plug-and-play settings page for payment providers — the reusable
+ * equivalent of the app's per-provider config screen:
+ *
+ *   - the FAILOVER CHAIN: the enabled providers in the order checkout will
+ *     try them, reorderable by drag or by keyboard
+ *   - provider selector (every adapter registered in the backend)
+ *   - per provider, EITHER a connect button (`authMode: 'oauth'`) or a
+ *     schema-driven credential form — and for OAuth providers, both
+ *   - SANDBOX/PRODUCTION environment switch (both credential sets kept)
+ *   - save / verify ("test connection") / enable (join or leave the chain)
+ *   - the provider's own onboarding walkthrough
+ *
+ * The host provides only the authenticated `client` and (optionally) the
+ * connect-state minting for OAuth providers.
+ */
+export interface PaymentProviderSettingsProps {
+  client: PaymentsSettingsClient;
+  /** Called after any state-changing action, e.g. to refresh host UI. */
+  onChanged?: (config: MaskedProviderConfig) => void;
+  /**
+   * Required to render `authMode: 'oauth'` providers: the host mints and
+   * persists the CSRF state against the admin session and returns it with
+   * the callback URL. Omit it and OAuth providers fall back to their
+   * credential form instead of showing a connect button that cannot work.
+   */
+  prepareConnect?: PrepareConnect;
+  /**
+   * Provider to open on mount instead of the list.
+   *
+   * The OAuth callback comes back to this page having just connected one — and
+   * landing on the provider LIST at that moment hides the very thing that
+   * changed, along with the switch that still has to be flipped. The host knows
+   * which provider it was (its own callback said so); the package does not read
+   * the URL.
+   */
+  initialProvider?: string | null;
+  /**
+   * Which provider is open, when the HOST owns that state (e.g. it lives in
+   * the URL, so each provider is its own linkable page).
+   *
+   * Passing it — `null` included — switches this component to controlled mode:
+   * it stops keeping its own selection and `initialProvider` no longer applies,
+   * because the host's value is now the single source of truth. Leave it
+   * `undefined` and nothing changes: selection stays internal, as every
+   * existing caller expects.
+   */
+  selectedProvider?: string | null;
+  /**
+   * Fired when the owner picks a provider (or leaves one, with `null`).
+   *
+   * Independent of `selectedProvider`: an uncontrolled host can use this purely
+   * to observe, while a controlled host uses it to write the new selection
+   * wherever it keeps it.
+   */
+  onProviderChange?: (provider: string | null) => void;
+  /**
+   * The activation step, rendered under the connection card.
+   *
+   * "Connected" and "can charge" are different facts, and only the HOST can
+   * prove the second one: it owns the endpoint that puts a real R$0,01 through
+   * the store's own account and enables the provider when it lands (FUT-463).
+   * The package decides only WHERE that step appears, never how it works — the
+   * same split as `prepareConnect`.
+   *
+   * `onVerified` refreshes this screen, so a passing charge immediately shows
+   * the provider as active.
+   */
+  renderVerification?: (context: {
+    provider: string;
+    /**
+     * The provider's human name ("InfinitePay").
+     *
+     * The activation step tells the owner who refused what, and "o provedor
+     * recusou criar a cobrança" is the same sentence with the one word that
+     * makes it actionable removed — an owner reading it on a screen that lists
+     * three providers has to work out which one is being talked about.
+     */
+    displayName: string;
+    /** A stored connection exists — there is something to charge through. */
+    connected: boolean;
+    /**
+     * A real charge through this connection has already succeeded
+     * (`chargeVerifiedAt` is stamped). The step renders a confirmation instead
+     * of demanding another payment: an owner who has ALREADY paid the R$0,01
+     * and reloads must be told it worked, not shown the pay button again — the
+     * button that being shown again is what made one owner pay four times.
+     */
+    proven: boolean;
+    /**
+     * An earlier step is still outstanding, so a NEW charge must not be
+     * offered yet — the owner has not confirmed the provider-side switch
+     * without which no link can be minted at all.
+     *
+     * It withholds the pay BUTTON and nothing else. The step itself must go on
+     * rendering whatever its state: it is what resumes an outstanding charge on
+     * mount and what reads the `transaction_nsu` a returning payer arrives
+     * with, so not rendering it is how a payment that HAS been made stops being
+     * confirmable. A blocked screen may cost a click; an unmounted one costs
+     * the money.
+     */
+    blocked: boolean;
+    /**
+     * The walkthrough has an EARLIER step open, so this one is not the current
+     * step. It must still render whatever it has already settled.
+     *
+     * The same lesson as `blocked`, one turn further. Unmounting was how the
+     * one sentence explaining why step 2 had just reopened disappeared in the
+     * same frame that reopened it: the provider refuses to mint a link, the
+     * step-2 confirmation is withdrawn on that evidence, the guide goes back a
+     * step — and the panel carrying "the provider refused, here is why" is
+     * taken off screen by its own report. The owner is returned to a step they
+     * believed they had done, with nothing saying so.
+     */
+    hidden: boolean;
+    onVerified: () => void;
+    /**
+     * The provider refused to create the charge — the strongest evidence
+     * available that the step the owner ticked off is not in fact done. Undoes
+     * the confirmation and puts them back on it.
+     */
+    onSetupIncomplete: () => void;
+  }) => ReactNode;
+}
+
+/** Everything the activation step needs that only this screen knows. */
+interface VerificationInputs {
+  render: PaymentProviderSettingsProps['renderVerification'];
+  provider: string;
+  displayName: string;
+  config: MaskedProviderConfig | null;
+  /** An earlier step is unfinished: withhold the pay button, render the rest. */
+  blocked: boolean;
+  /** The walkthrough is on an earlier step; this one is not on screen at all. */
+  hidden: boolean;
+  onVerified: () => void;
+  onSetupIncomplete: () => void;
+}
+
+/** The activation step's context, built from what this screen already knows. */
+function verificationFor(io: VerificationInputs): ReactNode {
+  // `enabled` is deliberately NOT passed: the step used it to show a standing
+  // "provider is active" banner, which kept reassuring a store whose every
+  // charge was being refused. `proven` is a different kind of fact — it is
+  // stamped only by a real charge landing, which is exactly what this step
+  // exists to observe.
+  return io.render?.({
+    provider: io.provider,
+    displayName: io.displayName,
+    connected: canAttemptCharge(io.config),
+    proven: Boolean(io.config?.chargeVerifiedAt),
+    blocked: io.blocked,
+    // Never `hidden` once the charge has landed: then this step IS the
+    // confirmation, and the guide has nothing left to show anyway.
+    hidden: io.hidden && !io.config?.chargeVerifiedAt,
+    onVerified: io.onVerified,
+    onSetupIncomplete: io.onSetupIncomplete,
+  });
+}
+
+interface ProviderScreenProps extends ActivePanelProps {
+  onBack: () => void;
+}
+
+/** One provider's configuration, with the way back to the list. */
+function ProviderScreen({ onBack, ...panel }: ProviderScreenProps) {
+  return (
+    <Box data-testid="payments-provider-settings">
+      <Button
+        size="small"
+        onClick={onBack}
+        data-testid="payments-provider-back"
+        sx={{ mb: 2, textTransform: 'none' }}
+      >
+        ← Voltar aos provedores
+      </Button>
+      <ActivePanel {...panel} />
+    </Box>
+  );
+}
+
+export function PaymentProviderSettings({
+  client,
+  onChanged,
+  prepareConnect,
+  initialProvider = null,
+  selectedProvider,
+  onProviderChange,
+  renderVerification,
+}: PaymentProviderSettingsProps) {
+  const { view, error, reload } = useSettingsState(client);
+  const { selected, setSelected } = useSelectedProvider(
+    initialProvider,
+    selectedProvider,
+    onProviderChange,
+  );
+  // Resolved above the early returns, because the guide hook depends on both.
+  const { active, activeConfig } = useOpenProvider(view, selected);
+  const { guide, loaded } = useSetupGuide(client, active?.name ?? null, progressKeyOf(activeConfig));
+  const ack = useSetupConfirmation(client, active, activeConfig);
+
+  if (error) return <Alert severity="error">{error}</Alert>;
+  if (!view) return <CircularProgress data-testid="payments-settings-loading" />;
+
+  if (!active) {
+    return <ProviderList view={view} client={client} reload={reload} onSelect={setSelected} />;
+  }
+
+  return (
+    <ProviderScreen
+      descriptor={active}
+      config={activeConfig}
+      client={client}
+      onChanged={onChanged}
+      reload={() => void reload()}
+      prepareConnect={prepareConnect}
+      onBack={() => setSelected(null)}
+      // A new credential may name a DIFFERENT InfinitePay account, and the
+      // owner's "Checkout Integrado is on" was said about the old one. The
+      // server already drops its own verdict and its proof on any credential
+      // change; this drops the half it cannot see.
+      onCredentialsReplaced={ack.withdraw}
+      verification={verificationFor({
+        render: renderVerification,
+        provider: active.name,
+        displayName: active.displayName,
+        config: activeConfig,
+        blocked: guideAwaitsConfirmation(guide, ack.confirmed, loaded),
+        // The walkthrough still has a step to show ⇒ this is not that step.
+        hidden: !loaded || openSection(guide, ack.confirmed, false) !== null,
+        onVerified: () => void reload(),
+        onSetupIncomplete: ack.withdraw,
+      })}
+      guide={(slots) => (
+        <SetupGuideSection
+          guide={guide}
+          confirmed={ack.confirmed}
+          onConfirm={ack.confirm}
+          onReopen={ack.withdraw}
+          {...slots}
+        />
+      )}
+    />
+  );
+}