@12-apps/payments-frontend 1.0.0

package/src/components/CheckoutPayment.tsx

@@ -0,0 +1,379 @@
+'use client';
+
+import {
+  Alert,
+  Box,
+  Button,
+  CircularProgress,
+  FormControlLabel,
+  Radio,
+  RadioGroup,
+  Stack,
+  TextField,
+  Typography,
+} from '@mui/material';
+import { useCallback, useEffect, useState } from 'react';
+
+import type { ClientChargeView, CustomerInfo, Money } from '@12-apps/payments-backend';
+
+import type { ClientPaymentsConfig, PaymentsClient } from '../client';
+import { useChargeStatus, useCreateCharge, usePaymentsClient } from '../context';
+
+/**
+ * Plug-and-play checkout payment step — the reusable equivalent of the
+ * buyer-facing payment screen. Renders the right flow for the merchant's
+ * ACTIVE provider by switching on its client config and the created charge:
+ *
+ *   - PIX: create → show copy-paste QR payload (+ image when the provider
+ *     returns one) → poll until PAID → `onPaid`
+ *   - CARD: collect via a host-injected `tokenizeCard` (each provider's
+ *     tokenization differs — Stripe SDK, public-key encryption, ...); only
+ *     the resulting TOKEN reaches the backend
+ *   - REDIRECT (hosted checkout, e.g. InfinitePay): send the buyer to
+ *     `hostedCheckoutUrl`, poll on return
+ *
+ * Must be rendered inside a `<PaymentsProvider>`. The host owns totals,
+ * order creation, and what happens on `onPaid` — this component owns only
+ * the payment interaction.
+ */
+export interface CardFormValues {
+  number: string;
+  holder: string;
+  expiry: string;
+  cvv: string;
+}
+
+/** A provider-vaulted card the buyer may reuse ("Mastercard •••• 7599"). */
+export interface SavedCardOption {
+  savedCardToken: string;
+  brand: string;
+  last4: string;
+  /** e.g. "02/2034" — shown as "Validade 02/2034". */
+  expiry?: string;
+}
+
+export interface CheckoutPaymentProps {
+  /**
+   * Opaque host-side handle for what is being paid (cart/order id). Sent as
+   * a LOOKUP KEY only — the server resolves the authoritative amount and
+   * reference from its own records, never from this component.
+   */
+  reference: string;
+  /** Display total. Shown to the buyer; the server recomputes what is charged. */
+  amount: Money;
+  customer: CustomerInfo;
+  /**
+   * Provider-specific client-side tokenization, injected by the host using
+   * `config.tokenization`/`config.publicKey` (SDK or public-key flows).
+   * Required for providers whose config declares CARD support.
+   */
+  tokenizeCard?: (values: CardFormValues, config: ClientPaymentsConfig) => Promise<string>;
+  /** Provider-vaulted cards for one-tap reuse (host loads them). */
+  savedCards?: SavedCardOption[];
+  onPaid: (charge: ClientChargeView) => void;
+  onFailed?: (charge: ClientChargeView) => void;
+}
+
+function formatBRL(amount: Money): string {
+  return (amount.amountCents / 100).toLocaleString('pt-BR', {
+    style: 'currency',
+    currency: amount.currency,
+  });
+}
+
+function firstError(...messages: (string | null | undefined)[]): string | null {
+  for (const message of messages) if (message) return message;
+  return null;
+}
+
+/** Card charges can settle synchronously on create (no polling needed). */
+function isFinalOnCreate(charge: ClientChargeView): boolean {
+  return charge.status !== 'PENDING' && charge.status !== 'AUTHORIZED';
+}
+
+/** Load the merchant's client-safe payment config once. */
+function useClientConfig(client: PaymentsClient) {
+  const [config, setConfig] = useState<ClientPaymentsConfig | null | undefined>(undefined);
+  const [error, setError] = useState<string | null>(null);
+  useEffect(() => {
+    client
+      .getConfig()
+      .then(setConfig)
+      .catch((err: unknown) => setError(err instanceof Error ? err.message : String(err)));
+  }, [client]);
+  return { config, error };
+}
+
+/** Fire onPaid/onFailed exactly when the charge reaches its outcome. */
+function useChargeOutcome(
+  current: ClientChargeView | null,
+  settled: boolean,
+  onPaid: (charge: ClientChargeView) => void,
+  onFailed?: (charge: ClientChargeView) => void,
+) {
+  useEffect(() => {
+    if (!current) return;
+    if (current.status === 'PAID') onPaid(current);
+    else if (settled || isFinalOnCreate(current)) onFailed?.(current);
+  }, [current, settled, onPaid, onFailed]);
+}
+
+function PixPanel({ charge }: { charge: ClientChargeView }) {
+  const [copied, setCopied] = useState(false);
+  if (!charge.pix) return null;
+  return (
+    <Stack spacing={1} alignItems="flex-start">
+      {charge.pix.qrImageUrl ? (
+        <Box component="img" src={charge.pix.qrImageUrl} alt="QR Code PIX" sx={{ width: 220 }} />
+      ) : null}
+      <TextField fullWidth multiline size="small" label="PIX copia e cola" value={charge.pix.qrText} />
+      <Button
+        size="small"
+        onClick={() => {
+          void navigator.clipboard.writeText(charge.pix?.qrText ?? '').then(() => setCopied(true));
+        }}
+      >
+        {copied ? 'Copiado!' : 'Copiar código'}
+      </Button>
+      <Stack direction="row" spacing={1} alignItems="center">
+        <CircularProgress size={16} />
+        <Typography variant="body2">Aguardando pagamento…</Typography>
+      </Stack>
+    </Stack>
+  );
+}
+
+function CardPanel({ disabled, onSubmit }: { disabled: boolean; onSubmit: (values: CardFormValues) => void }) {
+  const [values, setValues] = useState<CardFormValues>({ number: '', holder: '', expiry: '', cvv: '' });
+  const field = (key: keyof CardFormValues, label: string, width?: number) => (
+    <TextField
+      size="small"
+      label={label}
+      value={values[key]}
+      sx={width ? { width } : undefined}
+      onChange={(e) => setValues((v) => ({ ...v, [key]: e.target.value }))}
+    />
+  );
+  return (
+    <Stack spacing={2}>
+      {field('number', 'Número do cartão')}
+      {field('holder', 'Nome impresso no cartão')}
+      <Stack direction="row" spacing={2}>
+        {field('expiry', 'Validade (MM/AA)', 140)}
+        {field('cvv', 'CVV', 100)}
+      </Stack>
+      <Button variant="contained" disabled={disabled} onClick={() => onSubmit(values)}>
+        Pagar com cartão
+      </Button>
+    </Stack>
+  );
+}
+
+interface CardSectionProps {
+  amount: Money;
+  savedCards: SavedCardOption[];
+  disabled: boolean;
+  onNewCard: (values: CardFormValues) => void;
+  onSavedCard: (card: SavedCardOption) => void;
+}
+
+/** "Pague com cartão": saved cards as radios + "Novo cartão" fallback. */
+function CardSection({ amount, savedCards, disabled, onNewCard, onSavedCard }: CardSectionProps) {
+  const [selected, setSelected] = useState(savedCards[0]?.savedCardToken ?? 'new');
+  const chosen = savedCards.find((c) => c.savedCardToken === selected);
+  if (savedCards.length === 0) return <CardPanel disabled={disabled} onSubmit={onNewCard} />;
+  return (
+    <Stack spacing={2}>
+      <Typography variant="subtitle2">Pague com cartão</Typography>
+      <RadioGroup value={selected} onChange={(_, v) => setSelected(v)}>
+        {savedCards.map((card) => (
+          <FormControlLabel
+            key={card.savedCardToken}
+            value={card.savedCardToken}
+            control={<Radio />}
+            label={`${card.brand} •••• ${card.last4}${card.expiry ? ` — Validade ${card.expiry}` : ''}`}
+          />
+        ))}
+        <FormControlLabel value="new" control={<Radio />} label="Novo cartão — inserir outro cartão" />
+      </RadioGroup>
+      {chosen ? (
+        <Button variant="contained" disabled={disabled} onClick={() => onSavedCard(chosen)}>
+          Pagar {formatBRL(amount)}
+        </Button>
+      ) : (
+        <CardPanel disabled={disabled} onSubmit={onNewCard} />
+      )}
+    </Stack>
+  );
+}
+
+interface MethodChooserProps {
+  config: ClientPaymentsConfig;
+  amount: Money;
+  savedCards: SavedCardOption[];
+  loading: boolean;
+  startPix: () => void;
+  startCard: (values: CardFormValues) => void;
+  startSavedCard: (card: SavedCardOption) => void;
+}
+
+/** One "Forma de pagamento" option card (PIX / Cartão). */
+function MethodCard(props: { title: string; subtitle: string; selected: boolean; onClick: () => void }) {
+  return (
+    <Button
+      variant="outlined"
+      onClick={props.onClick}
+      sx={{ flex: 1, justifyContent: 'flex-start', textAlign: 'left', borderWidth: props.selected ? 2 : 1 }}
+    >
+      <Stack alignItems="flex-start">
+        <Typography variant="subtitle2">{props.title}</Typography>
+        <Typography variant="caption" color="text.secondary">
+          {props.subtitle}
+        </Typography>
+      </Stack>
+    </Button>
+  );
+}
+
+/** Pre-charge phase: "Forma de pagamento" method cards, then the flow. */
+function MethodChooser(props: MethodChooserProps) {
+  const { config, amount, savedCards, loading, startPix, startCard, startSavedCard } = props;
+  const [method, setMethod] = useState<'PIX' | 'CARD'>('PIX');
+  if (config.tokenization === 'REDIRECT') {
+    return (
+      <Button variant="contained" disabled={loading} onClick={startPix}>
+        Continuar para o pagamento
+      </Button>
+    );
+  }
+  return (
+    <>
+      <Typography variant="subtitle2">Forma de pagamento</Typography>
+      <Stack direction="row" spacing={2}>
+        <MethodCard title="PIX" subtitle="Aprovação imediata" selected={method === 'PIX'} onClick={() => setMethod('PIX')} />
+        <MethodCard title="Cartão" subtitle="Crédito à vista" selected={method === 'CARD'} onClick={() => setMethod('CARD')} />
+      </Stack>
+      {method === 'PIX' ? (
+        <Button variant="contained" disabled={loading} onClick={startPix}>
+          Gerar QR Code PIX
+        </Button>
+      ) : (
+        <CardSection
+          amount={amount}
+          savedCards={savedCards}
+          disabled={loading}
+          onNewCard={startCard}
+          onSavedCard={startSavedCard}
+        />
+      )}
+    </>
+  );
+}
+
+/** Poll target: only charges that can still change server-side. */
+function pollRefOf(charge: ClientChargeView | null) {
+  if (!charge || isFinalOnCreate(charge)) return null;
+  return { provider: charge.provider, providerChargeId: charge.providerChargeId };
+}
+
+interface CheckoutGateProps {
+  errorMessage: string | null;
+  config: ClientPaymentsConfig | null | undefined;
+}
+
+/** Error / loading / payments-disabled gates ahead of the payment UI. */
+function checkoutGate({ errorMessage, config }: CheckoutGateProps) {
+  if (errorMessage) return <Alert severity="error">{errorMessage}</Alert>;
+  if (config === undefined) return <CircularProgress data-testid="checkout-payment-loading" />;
+  if (config === null) {
+    return <Alert severity="warning">Esta loja ainda não aceita pagamentos online.</Alert>;
+  }
+  return null;
+}
+
+/** In-flight phase: the created charge decides what the buyer sees. */
+function ChargePhase({ charge, amount }: { charge: ClientChargeView; amount: Money }) {
+  if (charge.hostedCheckoutUrl && charge.status === 'PENDING') {
+    return (
+      <Stack spacing={2}>
+        <Typography>Você será direcionado para concluir o pagamento com segurança.</Typography>
+        <Button variant="contained" href={charge.hostedCheckoutUrl}>
+          Pagar {formatBRL(amount)}
+        </Button>
+      </Stack>
+    );
+  }
+  if (charge.method === 'PIX' && charge.status === 'PENDING') return <PixPanel charge={charge} />;
+  return null;
+}
+
+export function CheckoutPayment(props: CheckoutPaymentProps) {
+  const { reference, amount, customer, tokenizeCard, savedCards = [], onPaid, onFailed } = props;
+  const client = usePaymentsClient();
+  const { config, error: configError } = useClientConfig(client);
+  const [tokenizeError, setTokenizeError] = useState<string | null>(null);
+  const { charge, loading, create, error: createError } = useCreateCharge();
+  const { charge: live, settled } = useChargeStatus(pollRefOf(charge));
+  const current = live ?? charge;
+  useChargeOutcome(current, settled, onPaid, onFailed);
+
+  const startPix = useCallback(
+    () => void create({ method: 'PIX', customer, orderRef: reference }),
+    [create, reference, customer],
+  );
+
+  const startCard = useCallback(
+    async (values: CardFormValues) => {
+      if (!config || !tokenizeCard) {
+        setTokenizeError('Pagamento com cartão indisponível.');
+        return;
+      }
+      try {
+        const token = await tokenizeCard(values, config);
+        await create({
+          method: 'CARD',
+          customer,
+          orderRef: reference,
+          card: { token, holder: values.holder },
+        });
+      } catch (err) {
+        setTokenizeError(err instanceof Error ? err.message : String(err));
+      }
+    },
+    [config, tokenizeCard, create, reference, customer],
+  );
+
+  const startSavedCard = useCallback(
+    (card: SavedCardOption) =>
+      void create({
+        method: 'CARD',
+        customer,
+        orderRef: reference,
+        card: { savedCardToken: card.savedCardToken },
+      }),
+    [create, reference, customer],
+  );
+
+  const errorMessage = firstError(configError, tokenizeError, createError && createError.message);
+  const gate = checkoutGate({ errorMessage, config });
+  if (gate || config === undefined || config === null) return gate;
+
+  return (
+    <Stack spacing={2}>
+      <Typography variant="h6">Total: {formatBRL(amount)}</Typography>
+      {current ? (
+        <ChargePhase charge={current} amount={amount} />
+      ) : (
+        <MethodChooser
+          config={config}
+          amount={amount}
+          savedCards={savedCards}
+          loading={loading}
+          startPix={startPix}
+          startCard={(values) => void startCard(values)}
+          startSavedCard={startSavedCard}
+        />
+      )}
+    </Stack>
+  );
+}

package/src/components/ConfirmCredentialSave.tsx

@@ -0,0 +1,106 @@
+'use client';
+
+import {
+  Box,
+  Button,
+  Dialog,
+  DialogActions,
+  DialogContent,
+  DialogTitle,
+  Typography,
+} from '@mui/material';
+
+import type { CredentialFieldSpec } from '@12-apps/payments-backend';
+
+/**
+ * The last look at the value that decides who gets paid.
+ *
+ * Two real R$ 1,01 payments were lost during this flow's development, both to
+ * things that could be tested and fixed. A mistyped InfiniteTag is the failure
+ * with no such recourse: the charge succeeds, the link works, the buyer is
+ * happy, and the money is in a stranger's account with nothing on our side able
+ * to reverse it. There is no checksum to catch it, no confirmation email, and
+ * the store finds out at the end of the month.
+ *
+ * So the one intervention available is to show the value back, large, in the
+ * face it will be read in, and say what saving it means — after the owner has
+ * decided to save and before the write happens. This is the whole of the
+ * dialog: no new information, one more reading.
+ */
+
+export interface PendingSave {
+  spec: CredentialFieldSpec;
+  value: string;
+}
+
+export function ConfirmCredentialSave({
+  pending,
+  busy,
+  onCancel,
+  onConfirm,
+}: {
+  /** Null while nothing is awaiting confirmation. */
+  pending: PendingSave | null;
+  busy: boolean;
+  onCancel: () => void;
+  onConfirm: () => void;
+}) {
+  return (
+    <Dialog
+      open={pending !== null}
+      onClose={onCancel}
+      maxWidth="xs"
+      fullWidth
+      data-testid="payments-confirm-credential"
+      aria-labelledby="payments-confirm-credential-title"
+    >
+      <DialogTitle id="payments-confirm-credential-title">
+        Confirme para onde vai o dinheiro
+      </DialogTitle>
+      <DialogContent>
+        <Typography variant="body2" color="text.secondary">
+          Todo pagamento recebido por esta loja será depositado na conta desta{' '}
+          {pending?.spec.label ?? 'credencial'}:
+        </Typography>
+        <Box
+          data-testid="payments-confirm-credential-value"
+          sx={{
+            my: 2,
+            py: 2,
+            px: 1,
+            textAlign: 'center',
+            fontFamily: 'monospace',
+            fontSize: '1.5rem',
+            letterSpacing: '0.12em',
+            wordBreak: 'break-all',
+            borderRadius: 1,
+            bgcolor: 'action.hover',
+          }}
+        >
+          {pending?.value}
+        </Box>
+        <Typography variant="caption" color="text.secondary">
+          Um valor errado envia os pagamentos desta loja para outra pessoa, e não há como reverter.
+        </Typography>
+      </DialogContent>
+      <DialogActions>
+        {/*
+          Cancel is the wide, plain, first-reached option and confirm carries
+          the specific verb: an owner who is not sure should find it easier to
+          go back and check than to press on.
+        */}
+        <Button onClick={onCancel} disabled={busy} data-testid="payments-confirm-credential-cancel">
+          Voltar e revisar
+        </Button>
+        <Button
+          variant="contained"
+          onClick={onConfirm}
+          disabled={busy}
+          data-testid="payments-confirm-credential-confirm"
+        >
+          É essa, salvar
+        </Button>
+      </DialogActions>
+    </Dialog>
+  );
+}

package/src/components/CredentialFields.tsx

@@ -0,0 +1,158 @@
+'use client';
+
+import { Box, Button, Stack, TextField, Typography } from '@mui/material';
+
+import type { CredentialFieldSpec, MaskedFieldState } from '@12-apps/payments-backend';
+
+/**
+ * The schema-driven credential inputs, and the one-line summary a finished
+ * step collapses into.
+ *
+ * Split out of `ProviderCredentialForm` so that file stays about the ACTIONS
+ * (save, probe, confirm) rather than about rendering a field.
+ */
+
+interface FieldPresentation {
+  type: 'text' | 'password';
+  value: string;
+  required: boolean;
+  placeholder?: string;
+  helperText?: string;
+}
+
+/** Write-only secret field: masked hint as placeholder, value never echoed. */
+function secretPresentation(
+  state: MaskedFieldState | undefined,
+  value: string | undefined,
+  required: boolean,
+): FieldPresentation {
+  const configured = state?.configured ?? false;
+  return {
+    type: 'password',
+    value: value ?? '',
+    required: required && !configured,
+    placeholder: configured ? (state?.hint ?? '') : undefined,
+    helperText: configured ? 'Configurado — deixe em branco para manter o valor atual.' : undefined,
+  };
+}
+
+function fieldPresentation(
+  spec: CredentialFieldSpec,
+  state: MaskedFieldState | undefined,
+  value: string | undefined,
+): FieldPresentation {
+  if (spec.secret) return secretPresentation(state, value, spec.required);
+  const configured = state?.configured ?? false;
+  return {
+    type: 'text',
+    value: value ?? state?.hint ?? '',
+    required: spec.required && !configured,
+    placeholder: spec.placeholder,
+    helperText: spec.helperText,
+  };
+}
+
+/**
+ * A monospace, letter-spaced face for values that must be checked character by
+ * character. The whole reason InfinitePay's handle carries `mono` is that a
+ * wrong one is not rejected — it is a different person's account.
+ */
+const MONO_INPUT = {
+  fontFamily: 'monospace',
+  letterSpacing: '0.08em',
+} as const;
+
+interface CredentialFieldProps {
+  spec: CredentialFieldSpec;
+  state: MaskedFieldState | undefined;
+  value: string | undefined;
+  onChange: (value: string) => void;
+}
+
+/** One schema-driven form field. Secrets are write-only: hint, never value. */
+export function CredentialField({ spec, state, value, onChange }: CredentialFieldProps) {
+  const presentation = fieldPresentation(spec, state, value);
+  return (
+    <TextField
+      size="small"
+      label={spec.label}
+      {...presentation}
+      slotProps={spec.mono ? { htmlInput: { sx: MONO_INPUT, spellCheck: false } } : undefined}
+      onChange={(e) => onChange(e.target.value)}
+    />
+  );
+}
+
+/**
+ * What a completed step collapses to.
+ *
+ * A form that keeps every finished step expanded makes the owner re-read three
+ * cards to find the one thing still outstanding, and — worse for this screen —
+ * leaves the field that decides where the money goes sitting there editable,
+ * one stray keystroke from being changed by someone who came back to check
+ * something else. Collapsed, the value is still legible (that IS the check
+ * they came for) and altering it is a deliberate act.
+ */
+/**
+ * The parenthetical in a field label — "InfiniteTag ($usuario)" — tells you how
+ * to TYPE the value. Beside the value itself it is answered by the thing it
+ * sits next to, so the summary row shows the bare name.
+ */
+// Drops a trailing "(...)" qualifier from a field label. Done by scanning
+// rather than with /\s*\([^)]*\)\s*$/, which is polynomial-time on labels made
+// of many spaces or many open parens (CodeQL: polynomial regular expression
+// used on uncontrolled data) — the label is supplied by the caller.
+function stripTrailingParenthetical(label: string): string {
+  const trimmed = label.trimEnd();
+  if (!trimmed.endsWith(')')) return trimmed;
+
+  const open = trimmed.lastIndexOf('(');
+  if (open === -1) return trimmed;
+
+  return trimmed.slice(0, open).trimEnd();
+}
+
+export function DoneRow({
+  label,
+  value,
+  mono,
+  onEdit,
+  editLabel = 'Alterar',
+  testId,
+}: {
+  label: string;
+  value: string;
+  mono?: boolean;
+  onEdit: () => void;
+  editLabel?: string;
+  testId: string;
+}) {
+  return (
+    <Stack
+      direction="row"
+      spacing={1.5}
+      alignItems="center"
+      data-testid={testId}
+      sx={{ border: 1, borderColor: 'divider', borderRadius: 1, px: 2, py: 1.25 }}
+    >
+      <Box aria-hidden sx={{ color: 'success.main', fontWeight: 700 }}>
+        ✓
+      </Box>
+      <Typography variant="body2" color="text.secondary">
+        {stripTrailingParenthetical(label)}
+      </Typography>
+      <Typography variant="body2" sx={mono ? MONO_INPUT : undefined}>
+        {value}
+      </Typography>
+      <Box sx={{ flexGrow: 1 }} />
+      <Button
+        size="small"
+        onClick={onEdit}
+        data-testid={`${testId}-edit`}
+        sx={{ textTransform: 'none' }}
+      >
+        {editLabel}
+      </Button>
+    </Stack>
+  );
+}