@12-apps/payments-frontend 2.0.0 → 3.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "2.0.0",
+  "version": "3.0.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": "^3.0.0",
+    "@12-apps/payments-backend": "^4.0.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

package/src/client.ts

@@ -60,6 +60,36 @@ export interface PaymentsClientOptions {
   fetchImpl?: typeof fetch;
 }
 
+/**
+ * The sentence a failed request carries, rather than the response body.
+ *
+ * The body is a JSON envelope, and throwing it verbatim put
+ * `{"error":"CredentialsError","message":"No platform OAuth application
+ * credentials configured for stripe/SANDBOX"}` on a store owner's settings
+ * screen, inside a red alert, as the entire explanation of why a button did
+ * nothing. Unwrapping `message` is the floor: it is the only field written to
+ * be read, and an error class name is never the owner's problem.
+ *
+ * That message may still be developer English — the surfaces that can do better
+ * translate it (see `ProviderConnection`). This function's job is only to stop
+ * shipping the envelope.
+ */
+function failureMessage(body: string, status: number): string {
+  const fallback = `Payments request failed (${status})`;
+  if (!body) return fallback;
+  try {
+    const parsed: unknown = JSON.parse(body);
+    if (parsed !== null && typeof parsed === 'object' && 'message' in parsed) {
+      const { message } = parsed as { message?: unknown };
+      if (typeof message === 'string' && message.trim() !== '') return message;
+    }
+  } catch {
+    // Not JSON — a proxy's HTML error page, a gateway timeout. The raw text is
+    // still the most informative thing available.
+  }
+  return body;
+}
+
 function makeRequest(options: PaymentsClientOptions) {
   const fetchImpl = options.fetchImpl ?? fetch;
   return async function request<T>(path: string, init?: RequestInit): Promise<T> {
@@ -69,7 +99,7 @@ function makeRequest(options: PaymentsClientOptions) {
     });
     if (!res.ok) {
       const body = await res.text().catch(() => '');
-      throw new PaymentsClientError(res.status, body || `Payments request failed (${res.status})`);
+      throw new PaymentsClientError(res.status, failureMessage(body, res.status));
     }
     return (await res.json()) as T;
   };

package/src/components/ConnectionCard.tsx

@@ -0,0 +1,234 @@
+'use client';
+
+import {
+  Box,
+  Button,
+  CircularProgress,
+  Dialog,
+  DialogActions,
+  DialogContent,
+  DialogContentText,
+  DialogTitle,
+  Stack,
+  Typography,
+} from '@mui/material';
+import type { ReactNode } from 'react';
+
+import type { ConnectedOAuthAccount, PaymentEnvironment } from '@12-apps/payments-backend';
+
+import { BTN_PRIMARY_SX, BTN_SECONDARY_SX, LINKISH_SX, T } from './panel-tokens';
+
+/**
+ * The connect card's own pieces: what a connection IS, what authorizing
+ * involves, and what removing it costs.
+ *
+ * Split from `ProviderConnection`, which is about the connection's STATE
+ * MACHINE — one in-flight action, its failure, the grant's expiry. These four
+ * are about what the owner reads while deciding, and keeping them here is what
+ * holds both files inside the size gate.
+ */
+
+/**
+ * What this connection IS, as four labelled facts.
+ *
+ * A connected store's screen used to answer "connected?" and stop. The
+ * questions an owner actually returns with are which account, how it was
+ * connected, which environment, and what it can take — and every one of them
+ * was either absent or buried in a sentence. Read as a grid they are checkable
+ * at a glance, which is the whole reason to come back to this screen at all.
+ */
+export function ConnectionFacts({
+  environment,
+  account,
+  displayName,
+}: {
+  environment: PaymentEnvironment;
+  account: ConnectedOAuthAccount | null;
+  displayName: string;
+}) {
+  // A fact's testid names its VALUE, not its row: the environment is asserted
+  // with an exact `toHaveText`, so hanging the id on the grid — or even on the
+  // row, which also carries the "AMBIENTE" label — makes that assertion read
+  // the whole card. Every consumer of this id wants the one string.
+  const facts: { key: string; value: string; testId?: string }[] = [
+    { key: 'Conta', value: account?.accountLabel ?? account?.accountId ?? `Conta ${displayName}` },
+    { key: 'Conexão', value: `Autorizada no ${displayName}` },
+    {
+      key: 'Ambiente',
+      value: environment === 'PRODUCTION' ? 'Produção' : 'Sandbox (testes)',
+      testId: 'payments-connected-environment',
+    },
+  ];
+  if (account?.connectedAt) {
+    facts.push({
+      key: 'Conectada em',
+      value: new Date(account.connectedAt).toLocaleString('pt-BR'),
+    });
+  }
+  return (
+    <Box
+      sx={{
+        display: 'grid',
+        gridTemplateColumns: { xs: '1fr', sm: '1fr 1fr' },
+        gap: '12px 22px',
+      }}
+    >
+      {facts.map(({ key, value, testId }) => (
+        <Stack key={key} spacing={0.4} sx={{ borderLeft: `2px solid ${T.line2}`, pl: '11px' }}>
+          <Typography
+            sx={{
+              fontSize: '11px',
+              letterSpacing: '.05em',
+              textTransform: 'uppercase',
+              color: T.ink4,
+              fontWeight: 700,
+            }}
+          >
+            {key}
+          </Typography>
+          <Typography
+            data-testid={testId}
+            sx={{ fontSize: '13px', color: T.ink2, fontFamily: T.mono }}
+          >
+            {value}
+          </Typography>
+        </Stack>
+      ))}
+    </Box>
+  );
+}
+
+/**
+ * What authorizing actually involves, in three numbered steps.
+ *
+ * The card used to be one sentence and a button, which asks the owner to click
+ * something that navigates away from their store to a site they will be asked
+ * to log into. Numbering the three moments — sign in, authorize, come back —
+ * makes the trip finite and says the one thing that most reduces hesitation:
+ * you end up back here.
+ */
+export function ConnectSteps({ displayName }: { displayName: string }) {
+  const steps = [
+    `Entre na sua conta ${displayName} — dá para criar uma na hora, se ainda não tiver.`,
+    'Autorize o acesso na tela do provedor.',
+    'Você volta para cá com a conta conectada.',
+  ];
+  return (
+    <Stack component="ol" spacing={1.1} sx={{ listStyle: 'none', m: 0, p: 0 }}>
+      {steps.map((text, index) => (
+        <Stack component="li" key={text} direction="row" gap="9px">
+          <Box
+            aria-hidden
+            sx={{
+              width: 19,
+              height: 19,
+              borderRadius: '50%',
+              background: T.brandSoft,
+              color: T.brandInk,
+              fontSize: '11px',
+              fontWeight: 700,
+              display: 'grid',
+              placeItems: 'center',
+              flex: '0 0 auto',
+              mt: '1px',
+            }}
+          >
+            {index + 1}
+          </Box>
+          <Typography sx={{ fontSize: '13px', color: T.ink2, lineHeight: 1.5 }}>{text}</Typography>
+        </Stack>
+      ))}
+    </Stack>
+  );
+}
+
+/**
+ * Confirmation for Desconectar, which is destructive and irreversible from
+ * here: it revokes the grant at the provider, so the store stops being able to
+ * charge immediately and getting back requires the owner to authorize again on
+ * the provider's site. It also sat one careless click from "Reconectar".
+ */
+export function DisconnectDialog(props: {
+  open: boolean;
+  displayName: string;
+  busy: boolean;
+  /** The store is live on this provider — removing it stops checkout NOW. */
+  receiving: boolean;
+  onCancel: () => void;
+  onConfirm: () => void;
+  /** The softer path: keep the connection, stop taking orders through it. */
+  onPauseInstead?: () => void;
+}) {
+  const { displayName, receiving } = props;
+  return (
+    <Dialog open={props.open} onClose={props.onCancel} data-testid="payments-disconnect-confirm">
+      <DialogTitle sx={{ fontSize: '16.5px', fontWeight: 700, letterSpacing: '-.01em', pb: '8px' }}>
+        Remover a conexão com {displayName}?
+      </DialogTitle>
+      <DialogContent sx={{ pb: '4px' }}>
+        <DialogContentText sx={{ fontSize: '13px', color: T.ink2, lineHeight: 1.55 }}>
+          {receiving
+            ? 'A loja para de receber na hora e fica sem provedor ativo — pedidos novos não conseguem ser pagos até você conectar outro.'
+            : 'Esta conexão sai da loja. Você pode conectar de novo depois.'}
+        </DialogContentText>
+        {/* The consequences, itemised. A single paragraph makes the reversible
+            facts and the irreversible one weigh the same, and the one that
+            costs money is the one an owner skims past. */}
+        <Stack component="ul" spacing={1} sx={{ listStyle: 'none', m: 0, mt: '14px', p: 0 }}>
+          {receiving ? (
+            <Consequence tone="bad">Pedidos novos deixam de ser cobrados imediatamente.</Consequence>
+          ) : null}
+          <Consequence>
+            {`A autorização é revogada no ${displayName}. Sua conta e seu histórico continuam lá, intactos.`}
+          </Consequence>
+          <Consequence>
+            {`Pagamentos já aprovados e estornos em andamento seguem normalmente pelo ${displayName}.`}
+          </Consequence>
+          <Consequence>Para reconectar, os passos recomeçam do zero.</Consequence>
+        </Stack>
+      </DialogContent>
+      <DialogActions sx={{ display: 'flex', flexDirection: 'column', gap: '8px', p: '18px 22px 20px' }}>
+        {/* Offered FIRST, and only when it is a real alternative. An owner who
+            came here to stop taking orders wants the switch, not the removal —
+            and reaching for the destructive control is how they got here. */}
+        {receiving && props.onPauseInstead ? (
+          <Button
+            fullWidth
+            onClick={props.onPauseInstead}
+            disabled={props.busy}
+            sx={BTN_SECONDARY_SX}
+            data-testid="payments-pause-instead"
+          >
+            Só pausar o recebimento
+          </Button>
+        ) : null}
+        <Button
+          fullWidth
+          variant="contained"
+          disableElevation
+          onClick={props.onConfirm}
+          disabled={props.busy}
+          data-testid="payments-disconnect-confirm-action"
+          sx={{ ...BTN_PRIMARY_SX, background: T.bad, '&:hover': { background: '#a51f1f' } }}
+        >
+          {props.busy ? <CircularProgress size={18} sx={{ color: '#fff' }} /> : 'Remover conexão'}
+        </Button>
+        <Button fullWidth onClick={props.onCancel} disabled={props.busy} sx={LINKISH_SX}>
+          Cancelar
+        </Button>
+      </DialogActions>
+    </Dialog>
+  );
+}
+
+/** One consequence of removing the connection, marked by how much it costs. */
+function Consequence({ children, tone }: { children: ReactNode; tone?: 'bad' }) {
+  return (
+    <Stack component="li" direction="row" gap="9px">
+      <Box component="span" aria-hidden sx={{ fontWeight: 800, color: tone ? T.bad : T.ink4 }}>
+        {tone ? '✕' : '·'}
+      </Box>
+      <Typography sx={{ fontSize: '12.5px', color: T.ink2, lineHeight: 1.5 }}>{children}</Typography>
+    </Stack>
+  );
+}

package/src/components/CredentialFieldStack.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+import { Stack } from '@mui/material';
+
+import type { ProviderDescriptor } from '@12-apps/payments-backend';
+
+import { CredentialField } from './CredentialFields';
+import { saveLabel } from './credential-rules';
+import { FormActions, ReverifyWarning } from './CredentialFormAlerts';
+import type { CredentialFormState } from './ProviderCredentialForm';
+
+/**
+ * The live inputs for the step still owed, plus the one button that commits
+ * them — and, on a store that has already proved it can receive, the warning
+ * that saving will undo that.
+ *
+ * Its own component so `ProviderForm` stays about WHICH of the two shapes is on
+ * screen (the collapsed row, or this) rather than about what each contains.
+ */
+export function CredentialFields({
+  descriptor,
+  form,
+  proven,
+}: {
+  descriptor: ProviderDescriptor;
+  form: CredentialFormState;
+  /** A real charge has landed through this connection — see `ReverifyWarning`. */
+  proven: boolean;
+}) {
+  return (
+    <Stack spacing={2}>
+      {proven ? <ReverifyWarning /> : null}
+      {descriptor.credentialSchema.map((spec) => (
+        <CredentialField
+          key={spec.key}
+          spec={spec}
+          state={form.masked[spec.key]}
+          value={form.values[spec.key]}
+          // The probe's own verdict for THIS credential, keyed by the same
+          // field id the adapter checked. Shown at the box rather than in a
+          // list below the form, where the owner had to match four sentences
+          // to four boxes by eye.
+          check={form.probe?.checks?.find((entry) => entry.key === spec.key)}
+          onChange={(value) => form.edit(spec.key, value)}
+        />
+      ))}
+      <FormActions
+        busy={form.busy}
+        label={saveLabel(descriptor, form.complete)}
+        disabled={form.nothingEdited || !form.valid}
+        onSave={form.requestSave}
+      />
+    </Stack>
+  );
+}

package/src/components/CredentialFields.tsx

@@ -4,6 +4,8 @@ import { Box, Button, Stack, TextField, Typography } from '@mui/material';
 
 import type { CredentialFieldSpec, MaskedFieldState } from '@12-apps/payments-backend';
 
+import { LINKISH_SX, T } from './panel-tokens';
+
 /**
  * The schema-driven credential inputs, and the one-line summary a finished
  * step collapses into.
@@ -67,19 +69,122 @@ interface CredentialFieldProps {
   state: MaskedFieldState | undefined;
   value: string | undefined;
   onChange: (value: string) => void;
+  /**
+   * What the last probe found about THIS credential, when it found anything.
+   *
+   * The adapter has always returned per-credential verdicts; the screen showed
+   * them as a list under the form, which leaves the owner matching four
+   * sentences to four boxes by eye. A verdict about a field belongs at the
+   * field: "chave publicável de produção em conexão de teste" is unactionable
+   * three boxes away from the box it is about.
+   */
+  check?: { status: 'PASS' | 'FAIL' | 'UNCHECKED'; message: string };
 }
 
 /** One schema-driven form field. Secrets are write-only: hint, never value. */
-export function CredentialField({ spec, state, value, onChange }: CredentialFieldProps) {
+export function CredentialField({ spec, state, value, onChange, check }: CredentialFieldProps) {
   const presentation = fieldPresentation(spec, state, value);
+  // Label ABOVE the box, not floating in it. Four credentials whose names are
+  // the only thing distinguishing them (`sk_`, `pk_`, `whsec_`, `acct_`) are
+  // read as a column, and a floating label disappears the moment a value is
+  // pasted — exactly when the owner is checking they pasted into the right one.
+  // `htmlFor`/`id` rather than a bare <label>: lifting the text out of
+  // TextField also lifts it out of MUI's own labelling, and an input whose
+  // label is merely ABOVE it is unlabelled to a screen reader and unfindable by
+  // `getByLabelText`. The association has to be restated by hand.
+  const inputId = `payments-credential-${spec.key}`;
   return (
-    <TextField
-      size="small"
-      label={spec.label}
-      {...presentation}
-      slotProps={spec.mono ? { htmlInput: { sx: MONO_INPUT, spellCheck: false } } : undefined}
-      onChange={(e) => onChange(e.target.value)}
-    />
+    <Box>
+      <Typography
+        component="label"
+        htmlFor={inputId}
+        sx={{ display: 'block', fontSize: '12px', fontWeight: 650, color: T.ink2, mb: '5px' }}
+      >
+        {spec.label}
+        {spec.advanced ? (
+          <Box component="span" sx={{ fontWeight: 500, color: T.ink4 }}>
+            {' · só para plataformas Connect'}
+          </Box>
+        ) : null}
+      </Typography>
+      <TextField
+        size="small"
+        fullWidth
+        id={inputId}
+        {...presentation}
+        helperText={undefined}
+        slotProps={
+          spec.mono ? { htmlInput: { sx: MONO_INPUT, spellCheck: false } } : { htmlInput: {} }
+        }
+        sx={fieldSx(check?.status)}
+        onChange={(e) => onChange(e.target.value)}
+      />
+      <FieldNote
+        check={check}
+        fallback={presentation.helperText ?? spec.helperText}
+        testId={`payments-field-note-${spec.key}`}
+      />
+    </Box>
+  );
+}
+
+/**
+ * The box itself: 8px, hairline, brand focus ring — and the probe's verdict in
+ * its border, so a wrong credential is visible before any sentence is read.
+ */
+function fieldSx(status?: 'PASS' | 'FAIL' | 'UNCHECKED') {
+  const failed = status === 'FAIL';
+  return {
+    '& .MuiOutlinedInput-root': {
+      borderRadius: '8px',
+      fontSize: '13px',
+      background: failed ? '#fffbfb' : undefined,
+      '& fieldset': {
+        borderColor: failed ? T.bad : status === 'PASS' ? T.okLine : T.line,
+      },
+      '&:hover fieldset': { borderColor: failed ? T.bad : T.ink4 },
+      '&.Mui-focused fieldset': { borderColor: T.brand, borderWidth: '2px' },
+    },
+    '& .MuiOutlinedInput-input': { padding: '10px 12px' },
+  } as const;
+}
+
+/**
+ * How each verdict reads under its box. `UNCHECKED` deliberately carries no
+ * mark: a tick would claim it passed and a cross would blame the owner, when
+ * the truth is that nothing could be established either way.
+ */
+const VERDICT = {
+  PASS: { mark: '✓', color: T.ok },
+  FAIL: { mark: '✕', color: T.bad },
+  UNCHECKED: { mark: '', color: T.ink3 },
+  NONE: { mark: '', color: T.ink3 },
+} as const;
+
+/** The line under a box: the probe's verdict when there is one, else the hint. */
+function FieldNote({
+  check,
+  fallback,
+  testId,
+}: {
+  check?: { status: 'PASS' | 'FAIL' | 'UNCHECKED'; message: string };
+  fallback?: string;
+  testId: string;
+}) {
+  const text = check?.message ?? fallback;
+  if (!text) return null;
+  const { mark, color } = VERDICT[check?.status ?? 'NONE'];
+  return (
+    <Stack direction="row" gap="6px" alignItems="flex-start" sx={{ mt: '5px' }} data-testid={testId}>
+      {mark ? (
+        <Box component="span" aria-hidden sx={{ fontWeight: 800, color }}>
+          {mark}
+        </Box>
+      ) : null}
+      <Typography sx={{ fontSize: '11.5px', lineHeight: 1.45, color, fontWeight: mark ? 500 : 400 }}>
+        {text}
+      </Typography>
+    </Stack>
   );
 }
 
@@ -128,29 +233,36 @@ export function DoneRow({
   testId: string;
 }) {
   return (
+    // Green, not grey: a finished step reads as an achievement at a glance, and
+    // the whole point of collapsing it is that the eye can skip it on the way to
+    // the step still owed.
     <Stack
       direction="row"
-      spacing={1.5}
+      spacing={1.25}
       alignItems="center"
       data-testid={testId}
-      sx={{ border: 1, borderColor: 'divider', borderRadius: 1, px: 2, py: 1.25 }}
+      sx={{
+        border: `1px solid ${T.okLine}`,
+        background: T.okSoft,
+        borderRadius: '9px',
+        px: '16px',
+        py: '11px',
+        mx: '20px',
+        mb: '10px',
+        fontSize: '13px',
+      }}
     >
-      <Box aria-hidden sx={{ color: 'success.main', fontWeight: 700 }}>
+      <Box aria-hidden sx={{ color: T.ok, fontWeight: 800 }}>
         ✓
       </Box>
-      <Typography variant="body2" color="text.secondary">
+      <Typography sx={{ fontSize: '13px', fontWeight: 600, color: T.ink }}>
         {stripTrailingParenthetical(label)}
       </Typography>
-      <Typography variant="body2" sx={mono ? MONO_INPUT : undefined}>
+      <Typography sx={{ fontSize: '13px', color: T.ink3, ...(mono ? MONO_INPUT : {}) }}>
         {value}
       </Typography>
       <Box sx={{ flexGrow: 1 }} />
-      <Button
-        size="small"
-        onClick={onEdit}
-        data-testid={`${testId}-edit`}
-        sx={{ textTransform: 'none' }}
-      >
+      <Button size="small" onClick={onEdit} data-testid={`${testId}-edit`} sx={LINKISH_SX}>
         {editLabel}
       </Button>
     </Stack>

package/src/components/CredentialFormAlerts.tsx

@@ -5,6 +5,7 @@ import { Alert, Box, Button, CircularProgress, Stack, Typography } from '@mui/ma
 import type { VerifiedProviderConfig } from '@12-apps/payments-backend';
 
 import { ENVIRONMENT_LABELS } from './EnvironmentTabs';
+import { BAR_MSG_SX, BAR_SX, BTN_PRIMARY_SX } from './panel-tokens';
 
 /**
  * The credential step's alerts and its one button.
@@ -113,11 +114,19 @@ const CHECK_MARKS = {
  * red cross would misattribute — and it tells the owner precisely which part of
  * a passing result not to lean on.
  */
-export function ProbeChecklist({ probe }: { probe: VerifyProbe }) {
-  if (!probe.checks?.length) return null;
+export function ProbeChecklist({
+  probe,
+  only,
+}: {
+  probe: VerifyProbe;
+  /** Keep only the verdicts this predicate accepts — see `ProviderForm`. */
+  only?: (key: string) => boolean;
+}) {
+  const shown = (probe.checks ?? []).filter((check) => only?.(check.key) ?? true);
+  if (shown.length === 0) return null;
   return (
     <Stack spacing={0.5} data-testid="payments-probe-checks">
-      {probe.checks.map((check) => {
+      {shown.map((check) => {
         const { mark, color, label } = CHECK_MARKS[check.status];
         return (
           <Stack
@@ -186,25 +195,38 @@ export function FormActions({
   disabled: boolean;
   onSave: () => void;
 }) {
+  // The bar states what pressing it costs, which is the half a verb cannot
+  // carry: a complete set is sent to the provider on save, and a partial one is
+  // only written down. The owner reads the promise and the button in one line.
+  const message =
+    busy === 'verify'
+      ? 'Testando a conexão…'
+      : label.includes('testar')
+        ? 'Salvamos e testamos as chaves no provedor antes de seguir.'
+        : 'Guardamos o que você já preencheu. Complete os campos para testar.';
+
   return (
-    <Stack spacing={1} alignItems="flex-start">
+    <Box sx={BAR_SX} data-testid="payments-form-bar">
+      <Typography sx={BAR_MSG_SX} data-testid={busy === 'verify' ? 'payments-verifying' : undefined}>
+        {busy === 'verify' ? (
+          <Box component="span" sx={{ display: 'inline-flex', alignItems: 'center', gap: '8px' }}>
+            <CircularProgress size={14} />
+            {message}
+          </Box>
+        ) : (
+          message
+        )}
+      </Typography>
       <Button
         variant="contained"
+        disableElevation
         data-testid="payments-save"
         disabled={busy !== null || disabled}
-        sx={{ textTransform: 'none' }}
+        sx={BTN_PRIMARY_SX}
         onClick={onSave}
       >
-        {busy === 'save' ? <CircularProgress size={18} /> : label}
+        {busy === 'save' ? <CircularProgress size={18} sx={{ color: '#fff' }} /> : 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>
+    </Box>
   );
 }