@12-apps/payments-frontend 3.42.0 → 3.43.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.42.0",
+  "version": "3.43.1",
   "type": "module",
   "sideEffects": false,
   "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.",
@@ -23,7 +23,7 @@
     "storybook:build": "storybook build"
   },
   "dependencies": {
-    "@12-apps/payments-backend": "^4.32.0",
+    "@12-apps/payments-backend": "^4.33.1",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

package/src/card/pagbank-test-cards.ts

@@ -0,0 +1,50 @@
+/**
+ * PagBank's OFFICIAL sandbox test cards (developer.pagbank.com.br, "Cartões de
+ * teste") — the only cards the homologação evidence may use (FUT-3696).
+ *
+ * Public test data, published by PagBank for exactly this: they authorize
+ * nothing outside the sandbox. They are never sent to our server — the browser
+ * encrypts them and only the encrypted blob leaves it.
+ */
+interface PagBankTestCard {
+  scenario: "approved" | "declined";
+  brand: string;
+  number: string;
+  holder: string;
+  expMonth: string;
+  expYear: string;
+  securityCode: string;
+}
+
+/**
+ * December of NEXT year. PagBank's page prints 12/2026 as the example expiry,
+ * and the sandbox accepts any future date; a literal would turn every run
+ * after that month into a "card expired" evidence for a reason nobody chose.
+ */
+const TEST_EXPIRY_YEAR = String(new Date().getFullYear() + 1);
+
+export const PAGBANK_TEST_CARDS: readonly PagBankTestCard[] = [
+  {
+    scenario: "approved",
+    brand: "VISA",
+    number: "4539620659922097",
+    holder: "Jose da Silva",
+    expMonth: "12",
+    expYear: TEST_EXPIRY_YEAR,
+    securityCode: "123",
+  },
+  {
+    scenario: "declined",
+    brand: "VISA",
+    number: "4929291898380766",
+    holder: "Jose da Silva",
+    expMonth: "12",
+    expYear: TEST_EXPIRY_YEAR,
+    securityCode: "123",
+  },
+];
+
+/** `4539 62** **** 2097` — the first six and last four, as a receipt prints them. */
+export function maskTestCard(number: string): string {
+  return `${number.slice(0, 4)} ${number.slice(4, 6)}** **** ${number.slice(-4)}`;
+}

package/src/card/tokenize.ts

@@ -335,3 +335,29 @@ function mintToken(prefix: string): string {
   tokenCounter += 1;
   return `${prefix}_${Date.now().toString(36)}${tokenCounter.toString(36)}`;
 }
+
+/** Why {@link encryptPagBankCard} produced no blob. */
+type PagBankEncryptFailure = "SDK_UNAVAILABLE" | "NOT_PROCESSED";
+
+/**
+ * Encrypt a card with PagBank's own browser SDK — the same script and the same
+ * `PagSeguro.encryptCard` call the checkout's {@link tokenizeCard} makes, minus
+ * the buyer-form validation and copy. For the homologação evidence (FUT-3696),
+ * which encrypts PagBank's official TEST cards and must prove the flow the
+ * checkout really uses: the PAN never leaves the browser, only the blob does.
+ */
+export async function encryptPagBankCard(params: {
+  publicKey: string;
+  holder: string;
+  number: string;
+  expMonth: string;
+  expYear: string;
+  securityCode: string;
+}): Promise<{ encrypted: string } | { failure: PagBankEncryptFailure }> {
+  if (!(await ensurePagBankSdk()) || !window.PagSeguro?.encryptCard) {
+    return { failure: "SDK_UNAVAILABLE" };
+  }
+  const result = window.PagSeguro.encryptCard(params);
+  if (result.hasErrors || !result.encryptedCard) return { failure: "NOT_PROCESSED" };
+  return { encrypted: result.encryptedCard };
+}

package/src/components/checkout/poll-live.ts

@@ -23,7 +23,13 @@
  * - A wait given {@link LiveCadence.liveIntervalMs} keeps that floor. The hook
  *   gives it one only on a hosted-checkout return carrying the settlement pair
  *   (`carriesSettlementPair`), where the buyer's own read is what confirms the
- *   payment and no server sweep can stand in for it.
+ *   payment and no server sweep can stand in for it. That floor is a timed
+ *   read on a live channel — a bounded wait on a THIRD PARTY, the provider the
+ *   buyer just paid — and it is recorded as one: the origin host's realtime
+ *   doc lists it under "Allowed exceptions", beside the redirect activation's
+ *   verify (`../../activation/use-redirect-activation.ts`), with the decision
+ *   that admits the class. If the provider's webhook ever settles every
+ *   return, the floor goes and the return waits on the channel like the rest.
  *
  * Split out of `poll-loop.ts` so the loop stays one question: WHEN to ask. This
  * file answers only how being live changes that answer.

package/src/components/platform/HomologacaoEvidenceCard.tsx

@@ -0,0 +1,277 @@
+'use client';
+
+import { Alert, Box, Button, LinearProgress, Stack, Typography } from '@mui/material';
+import { useState, type ReactNode } from 'react';
+
+import type {
+  BrowserCardResult,
+  EvidenceSummary,
+  PaymentEnvironment,
+} from '@12-apps/payments-backend';
+
+import { maskTestCard, PAGBANK_TEST_CARDS } from '../../card/pagbank-test-cards';
+import { encryptPagBankCard } from '../../card/tokenize';
+import { CARD_SX, TAP_SX } from './ConnectEnvironmentCard';
+import type { PlatformHomologacaoCopy } from './copy';
+import { PlatformCopyProvider, usePlatformCopy } from './copy-context';
+
+/**
+ * The homologação EVIDENCE card (FUT-3696): connect a sandbox test seller,
+ * then run the real scenarios and download the TXT PagBank's form takes.
+ *
+ * The one thing this card does itself is the part that has to happen in a
+ * browser: encrypting PagBank's official TEST cards with the seller's public
+ * key, through the same SDK call the checkout makes. Everything else is the
+ * host's — each callback is a call to its own mounted routes — and what the
+ * file says is decided by the server, from what was recorded. This card shows
+ * the counts it answered and never infers a result of its own.
+ */
+
+/** The test seller's connection, as the host reads it back. */
+export interface HomologacaoSellerView {
+  connected: boolean;
+  environment: PaymentEnvironment | null;
+  /** UNVERIFIED | VERIFIED | FAILED | RECONNECT_REQUIRED. */
+  status: string | null;
+  connectedAt: string | null;
+  accountId: string | null;
+  /** Why the latest authorization did not complete, as the evidence recorded it. */
+  lastConnectProblem?: string | null;
+}
+
+export interface HomologacaoEvidenceCardProps {
+  copy: PlatformHomologacaoCopy;
+  /** Null while the host is still reading it. */
+  seller: HomologacaoSellerView | null;
+  /** How the last return from PagBank ended, when the page was opened by one. */
+  connectOutcome?: 'connected' | 'failed' | null;
+  /** Start the authorization: the host mints the state and navigates away. */
+  onConnect: () => Promise<void>;
+  /** Phase 1 — the seller's public key, null when it could not be minted. */
+  onPrepare: () => Promise<{ runId: string; publicKey: string | null }>;
+  /** Phase 2 — raise the orders with the encrypted cards. */
+  onRun: (runId: string, cards: BrowserCardResult[]) => Promise<void>;
+  /** Build and deliver the file; resolves to the counts it holds. */
+  onDownload: () => Promise<EvidenceSummary>;
+}
+
+type Phase = 'idle' | 'preparing' | 'encrypting' | 'running' | 'downloading';
+type ActivePhase = Exclude<Phase, 'idle'>;
+
+/** Each official test card, encrypted — or the code saying why it is not. */
+async function encryptTestCards(publicKey: string | null): Promise<BrowserCardResult[]> {
+  const results: BrowserCardResult[] = [];
+  for (const card of PAGBANK_TEST_CARDS) {
+    const base = { scenario: card.scenario, brand: card.brand, masked: maskTestCard(card.number) };
+    if (!publicKey) {
+      results.push({ ...base, encrypted: null, failure: 'NO_PUBLIC_KEY' });
+      continue;
+    }
+    const encrypted = await encryptPagBankCard({
+      publicKey,
+      holder: card.holder,
+      number: card.number,
+      expMonth: card.expMonth,
+      expYear: card.expYear,
+      securityCode: card.securityCode,
+    });
+    results.push(
+      'encrypted' in encrypted
+        ? { ...base, encrypted: encrypted.encrypted }
+        : { ...base, encrypted: null, failure: encrypted.failure },
+    );
+  }
+  return results;
+}
+
+export function HomologacaoEvidenceCard(props: HomologacaoEvidenceCardProps): ReactNode {
+  return (
+    <PlatformCopyProvider copy={props.copy}>
+      <EvidenceBody {...props} />
+    </PlatformCopyProvider>
+  );
+}
+
+/** The seller's one-line state — null while the host is still reading it. */
+function sellerLine(copy: PlatformHomologacaoCopy['evidence'], seller: HomologacaoSellerView | null): string | null {
+  if (!seller) return null;
+  if (seller.status === 'RECONNECT_REQUIRED') return copy.sellerReconnect;
+  return seller.connected ? copy.sellerConnected(seller.connectedAt, seller.accountId) : copy.sellerNotConnected;
+}
+
+function SellerBlock({
+  seller,
+  onConnect,
+}: Pick<HomologacaoEvidenceCardProps, 'seller' | 'onConnect'>): ReactNode {
+  const copy = usePlatformCopy().evidence;
+  const [failed, setFailed] = useState(false);
+  const [busy, setBusy] = useState(false);
+  const line = sellerLine(copy, seller);
+  const offerReconnect = Boolean(seller?.connected) && seller?.status !== 'RECONNECT_REQUIRED';
+  const connect = (): void => {
+    setBusy(true);
+    setFailed(false);
+    onConnect()
+      .catch(() => setFailed(true))
+      .finally(() => setBusy(false));
+  };
+  return (
+    <Stack spacing={1} data-testid="evidence-seller">
+      <Typography variant="body2" fontWeight={600}>
+        {copy.sellerHeading}
+      </Typography>
+      {line ? (
+        <Typography variant="body2" data-testid="evidence-seller-state">
+          {line}
+        </Typography>
+      ) : null}
+      <Typography variant="caption" component="p" color="text.secondary">
+        {copy.connectHint}
+      </Typography>
+      <Box>
+        <Button
+          // The next step until a seller is connected; secondary once one is.
+          variant={offerReconnect ? 'outlined' : 'contained'}
+          size="small"
+          disabled={!seller || busy}
+          onClick={connect}
+          data-testid="evidence-connect"
+          sx={TAP_SX}
+        >
+          {offerReconnect ? copy.reconnect : copy.connect}
+        </Button>
+      </Box>
+      {failed ? (
+        <Alert severity="error" data-testid="evidence-connect-failed">
+          {copy.connectFailed}
+        </Alert>
+      ) : null}
+    </Stack>
+  );
+}
+
+/** One run at a time: which phase it is in, what it answered, where it failed. */
+function useEvidenceRun({ onPrepare, onRun, onDownload }: Pick<HomologacaoEvidenceCardProps, 'onPrepare' | 'onRun' | 'onDownload'>) {
+  const [phase, setPhase] = useState<Phase>('idle');
+  const [summary, setSummary] = useState<EvidenceSummary | null>(null);
+  const [failed, setFailed] = useState<ActivePhase | null>(null);
+  const run = async (full: boolean): Promise<void> => {
+    setFailed(null);
+    setSummary(null);
+    // The phase that throws is the one the operator is told about.
+    let current: ActivePhase = full ? 'preparing' : 'downloading';
+    const enter = (next: ActivePhase): void => {
+      current = next;
+      setPhase(next);
+    };
+    try {
+      if (full) {
+        enter('preparing');
+        const prepared = await onPrepare();
+        enter('encrypting');
+        const cards = await encryptTestCards(prepared.publicKey);
+        enter('running');
+        await onRun(prepared.runId, cards);
+      }
+      enter('downloading');
+      setSummary(await onDownload());
+    } catch {
+      setFailed(current);
+    } finally {
+      setPhase('idle');
+    }
+  };
+  return { phase, busy: phase !== 'idle', summary, failed, run };
+}
+
+/** How the last return from PagBank ended — with the recorded reason when it failed. */
+function ConnectOutcome({ seller, connectOutcome }: Pick<HomologacaoEvidenceCardProps, 'seller' | 'connectOutcome'>): ReactNode {
+  const copy = usePlatformCopy().evidence;
+  // The URL only says PagBank came back; the seller's own row says whether it
+  // connected. A "connected" the row does not confirm is not announced.
+  const outcome = connectOutcome === 'connected' && !seller?.connected ? null : connectOutcome;
+  if (!outcome) return null;
+  return (
+    <Alert severity={outcome === 'connected' ? 'success' : 'warning'} data-testid="evidence-connect-outcome">
+      {outcome === 'connected' ? copy.returnedConnected : (seller?.lastConnectProblem ?? copy.returnedFailed)}
+    </Alert>
+  );
+}
+
+function EvidenceBody(props: HomologacaoEvidenceCardProps): ReactNode {
+  const { seller, onConnect } = props;
+  const copy = usePlatformCopy().evidence;
+  const { phase, busy, summary, failed, run } = useEvidenceRun(props);
+  return (
+    <Stack spacing={1.5} data-testid="homologacao-evidence-card" sx={CARD_SX}>
+      <Typography variant="body2" fontWeight={600}>
+        {copy.heading}
+      </Typography>
+      <Typography variant="caption" component="p">
+        {copy.lede}
+      </Typography>
+      <ConnectOutcome seller={seller} connectOutcome={props.connectOutcome} />
+      <SellerBlock seller={seller} onConnect={onConnect} />
+      <Stack direction={{ xs: 'column', sm: 'row' }} spacing={1} sx={{ alignItems: { sm: 'center' } }}>
+        <Button
+          variant={seller?.connected ? 'contained' : 'outlined'}
+          size="small"
+          disabled={busy}
+          onClick={() => void run(true)}
+          data-testid="evidence-generate"
+          sx={TAP_SX}
+        >
+          {copy.generate}
+        </Button>
+        <Button
+          variant="text"
+          size="small"
+          disabled={busy}
+          onClick={() => void run(false)}
+          data-testid="evidence-download-latest"
+          sx={TAP_SX}
+        >
+          {copy.downloadLatest}
+        </Button>
+      </Stack>
+      {busy ? (
+        <Stack spacing={0.5} role="status" aria-busy="true" data-testid="evidence-phase">
+          <Typography variant="body2">{copy.phases[phase as ActivePhase]}</Typography>
+          <LinearProgress />
+        </Stack>
+      ) : null}
+      <EvidenceResult summary={summary} failed={failed} />
+    </Stack>
+  );
+}
+
+/** The server's counts — never inferred here — or the failure line. */
+function EvidenceResult({
+  summary,
+  failed,
+}: {
+  summary: EvidenceSummary | null;
+  failed: ActivePhase | null;
+}): ReactNode {
+  const copy = usePlatformCopy().evidence;
+  if (failed) {
+    return (
+      <Alert severity="error" data-testid="evidence-generate-failed">
+        {copy.generateFailed(failed)}
+      </Alert>
+    );
+  }
+  if (!summary) return null;
+  return (
+    <Stack spacing={0.5} role="status" data-testid="evidence-summary">
+      <Typography variant="body2" fontWeight={600} data-testid="evidence-summary-counts">
+        {copy.summary(summary)}
+      </Typography>
+      {summary.failed + summary.pending > 0 ? (
+        <Typography variant="caption" component="p" data-testid="evidence-incomplete">
+          {copy.incomplete}
+        </Typography>
+      ) : null}
+    </Stack>
+  );
+}

package/src/components/platform/copy.ts

@@ -130,10 +130,35 @@ export interface ConnectApplicationCopy {
   };
 }
 
+/** The homologação evidence card (FUT-3696) — the sandbox test seller and the TXT. */
+export interface HomologacaoEvidenceCardCopy {
+  heading: string;
+  lede: string;
+  sellerHeading: string;
+  /** `connectedAt` is ISO-8601; the pack formats it in its own locale. */
+  sellerConnected: (connectedAt: string | null, accountId: string | null) => string;
+  sellerNotConnected: string;
+  sellerReconnect: string;
+  connectHint: string;
+  connect: string;
+  reconnect: string;
+  connectFailed: string;
+  returnedConnected: string;
+  returnedFailed: string;
+  generate: string;
+  downloadLatest: string;
+  phases: { preparing: string; encrypting: string; running: string; downloading: string };
+  summary: (counts: { executed: number; failed: number; pending: number }) => string;
+  incomplete: string;
+  /** Which phase failed — and that the latest recorded file can still be downloaded. */
+  generateFailed: (phase: 'preparing' | 'encrypting' | 'running' | 'downloading') => string;
+}
+
 /** The whole platform surface, in one object a host passes at the mount. */
 export interface PlatformHomologacaoCopy {
   outcome: HomologacaoOutcomeCopy;
   guide: HomologacaoGuideCopy;
   anexo: HomologacaoAnexoCopy;
   connect: ConnectApplicationCopy;
+  evidence: HomologacaoEvidenceCardCopy;
 }

package/src/components/platform/en-US.ts

@@ -106,4 +106,43 @@ export const EN_US_PLATFORM_HOMOLOGACAO_COPY: PlatformHomologacaoCopy = {
         'PagBank does not check the client_secret in this lookup — only the client_id and the token. A wrong client_secret only shows at the first store authorization.',
     },
   },
+  evidence: {
+    heading: 'Homologation evidence (sandbox)',
+    lede: "Runs the real scenarios in PagBank's sandbox and builds the TXT for the form. Nothing is charged.",
+    sellerHeading: 'Test seller',
+    sellerConnected: (connectedAt, accountId) =>
+      `Connected${connectedAt ? ` on ${new Date(connectedAt).toLocaleString('en-US')}` : ''}` +
+      (accountId ? ` · account ${accountId}` : ''),
+    sellerNotConnected:
+      'No test seller connected. Without one, the Connect, Pix and card scenarios stay pending in the file.',
+    sellerReconnect: "The test seller's connection must be authorized again.",
+    connectHint:
+      "You will sign in to PagBank's sandbox with a test seller account and approve the consent. Sandbox only.",
+    connect: 'Connect test seller',
+    reconnect: 'Reconnect test seller',
+    connectFailed: 'Could not start the test seller connection.',
+    returnedConnected: 'Test seller connected. The callback and the code exchange were recorded in the evidence.',
+    returnedFailed: 'The test seller connection did not complete. Try connecting again.',
+    generate: 'Generate evidence file\u00a0(TXT)',
+    downloadLatest: 'Download the latest recorded',
+    phases: {
+      preparing: 'Consulting the application, renewing the token and minting the public key…',
+      encrypting: 'Encrypting the test cards in the browser…',
+      running: 'Creating the Pix and card orders in the sandbox — this can take up to a minute…',
+      downloading: 'Building the file…',
+    },
+    summary: ({ executed, failed, pending }) =>
+      `✓\u00a0${executed}\u00a0executed · ✗\u00a0${failed}\u00a0failed · ⧗\u00a0${pending}\u00a0pending`,
+    incomplete:
+      'The file lists what is missing under Pendências. Do not submit it as complete. Notifications that arrive later show up when you download the latest recorded.',
+    generateFailed: (phase) =>
+      `${
+        {
+          preparing: 'Consulting the application and preparing the test seller failed.',
+          encrypting: 'Encrypting the test cards in the browser failed.',
+          running: 'Creating the orders in the sandbox failed.',
+          downloading: 'Building the file failed.',
+        }[phase]
+      } Try again; "Download the latest recorded" still returns what was recorded.`,
+  },
 };

package/src/components/platform/pt-BR.ts

@@ -85,4 +85,48 @@ export const PT_BR_PLATFORM_HOMOLOGACAO_COPY: PlatformHomologacaoCopy = {
         'O PagBank não verifica o client_secret nesta consulta — só o client_id e o token. Um client_secret errado só aparece na primeira autorização de loja.',
     },
   },
+  evidence: {
+    heading: 'Evidências para homologação (sandbox)',
+    lede: 'Executa os cenários reais no sandbox do PagBank e gera o TXT para o formulário. Nada é cobrado.',
+    sellerHeading: 'Lojista de teste',
+    sellerConnected: (connectedAt, accountId) =>
+      `Conectado${connectedAt ? ` em ${new Date(connectedAt).toLocaleString('pt-BR', { timeZone: 'America/Sao_Paulo' })}` : ''}` +
+      (accountId ? ` · conta ${accountId}` : ''),
+    sellerNotConnected:
+      'Nenhum lojista de teste conectado. Sem ele, os cenários de Connect, Pix e cartão ficam pendentes no arquivo.',
+    sellerReconnect: 'A conexão do lojista de teste precisa ser autorizada de novo.',
+    connectHint:
+      'Você fará login no sandbox do PagBank com uma conta de vendedor de teste e aprovará o consentimento. Somente sandbox.',
+    connect: 'Conectar lojista de teste',
+    reconnect: 'Reconectar lojista de teste',
+    connectFailed: 'Não foi possível iniciar a conexão do lojista de teste.',
+    returnedConnected:
+      'Lojista de teste conectado. O callback e a troca do código foram registrados nas evidências.',
+    returnedFailed:
+      'A conexão do lojista de teste não foi concluída. Tente conectar de novo.',
+    generate: 'Gerar arquivo de evidências\u00a0(TXT)',
+    downloadLatest: 'Baixar o último registrado',
+    phases: {
+      preparing: 'Consultando a aplicação, renovando o token e gerando a chave pública…',
+      encrypting: 'Criptografando os cartões de teste no navegador…',
+      running: 'Criando os pedidos Pix e cartão no sandbox — pode levar até um minuto…',
+      downloading: 'Montando o arquivo…',
+    },
+    summary: ({ executed, failed, pending }) =>
+      // Non-breaking inside each count, so only the separators may wrap.
+      `✓\u00a0${executed}\u00a0${executed === 1 ? 'executado' : 'executados'} · ` +
+      `✗\u00a0${failed}\u00a0${failed === 1 ? 'falhou' : 'falharam'} · ` +
+      `⧗\u00a0${pending}\u00a0${pending === 1 ? 'pendente' : 'pendentes'}`,
+    incomplete:
+      'O arquivo lista o que falta na seção Pendências. Não o envie como completo. Notificações que chegarem depois aparecem ao baixar o último registrado.',
+    generateFailed: (phase) =>
+      `${
+        {
+          preparing: 'Falhou ao consultar a aplicação e preparar o lojista de teste.',
+          encrypting: 'Falhou ao criptografar os cartões de teste no navegador.',
+          running: 'Falhou ao criar os pedidos no sandbox.',
+          downloading: 'Falhou ao montar o arquivo.',
+        }[phase]
+      } Tente de novo; "Baixar o último registrado" ainda traz o que já foi registrado.`,
+  },
 };

package/src/index.ts

@@ -337,6 +337,7 @@ export {
   type ConnectApplicationPanelProps,
 } from './components/platform/ConnectApplicationPanel';
 export { PlatformHomologacao, type PlatformHomologacaoProps } from './components/platform/PlatformHomologacao';
+export * from './components/platform/HomologacaoEvidenceCard';
 export {
   type HomologacaoSaveInput,
   type HomologacaoSaveState,