@12-apps/payments-frontend 1.0.0

package/eslint.config.js

@@ -0,0 +1,34 @@
+import { config as baseConfig } from '@12-apps/eslint-config/base';
+import testFlakiness from 'eslint-plugin-test-flakiness';
+
+/**
+ * The everyday DX lint for this package.
+ *
+ * It registers `eslint-plugin-test-flakiness` with every rule left OFF. Those
+ * rules are enforced by the repo-root CI lane (`eslint.flakiness.config.mjs`),
+ * not here — but a test file that legitimately suppresses one carries an inline
+ * `// eslint-disable-next-line test-flakiness/...` directive, and ESLint reports
+ * "Definition for rule not found" for a directive naming a plugin it has never
+ * heard of. Registering the plugin lets those directives RESOLVE without this
+ * config enforcing anything.
+ *
+ * Same trick, same reason as the root `eslint.complexity.config.mjs`, which
+ * registers `@typescript-eslint` (rules off) so source-file directives resolve
+ * inside that isolated gate.
+ */
+
+/** @type {import("eslint").Linter.Config[]} */
+export default [
+  ...baseConfig,
+  {
+    files: ['**/__tests__/**', '**/*.test.{ts,tsx}'],
+    plugins: { 'test-flakiness': testFlakiness },
+    // Registered-but-off means the rule never fires here, which would make
+    // every legitimate directive read as "unused". Scoped to test files so the
+    // rest of the package still gets dead-directive hygiene.
+    linterOptions: { reportUnusedDisableDirectives: 'off' },
+  },
+  {
+    ignores: ['dist/**', 'node_modules/**', 'coverage/**'],
+  },
+];

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@12-apps/payments-frontend",
+  "version": "1.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": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "clean": "rm -rf node_modules coverage",
+    "test": "node ../../../scripts/vitest-with-teardown.mjs run",
+    "test:watch": "vitest watch",
+    "lint": "eslint src --max-warnings 0",
+    "check-types": "tsc --noEmit",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@emotion/react": ">=11.0.0",
+    "@emotion/styled": ">=11.0.0",
+    "@mui/material": ">=6.0.0",
+    "react": ">=19.0.0",
+    "react-dom": ">=19.0.0"
+  },
+  "devDependencies": {
+    "@emotion/react": "^11.14.0",
+    "@emotion/styled": "^11.14.0",
+    "@mui/material": "^6.5.0",
+    "@12-apps/eslint-config": "^1.1.0",
+    "@12-apps/payments-backend": "^1.0.0",
+    "@12-apps/typescript-config": "^1.1.0",
+    "@testing-library/react": "^16.1.0",
+    "@types/react": "19.2.2",
+    "@types/react-dom": "19.2.2",
+    "eslint": "^9.39.1",
+    "eslint-plugin-test-flakiness": "^1.4.0",
+    "jsdom": "^25.0.1",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "typescript": "^5.9.2",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/12-apps/shared-packages.git",
+    "directory": "packages/payments/frontend"
+  },
+  "files": [
+    "src",
+    "dist",
+    "prisma",
+    "*.js",
+    "*.mjs",
+    "*.md"
+  ]
+}

package/src/__tests__/checkout-confirmation.test.tsx

@@ -0,0 +1,177 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import type { MerchantSettingsView, ProviderSetupGuide } from '@12-apps/payments-backend';
+
+import type { PaymentsSettingsClient } from '../client';
+import { PaymentProviderSettings } from '../components/PaymentProviderSettings';
+import { CHECKOUT_CONFIRM_ACTION } from '../components/SetupGuideSection';
+
+/**
+ * The setup step no API can answer, and what it holds back.
+ *
+ * InfinitePay ships Checkout Integrado disabled and publishes nothing that
+ * reports its state, so a store can pass the probe, read `CONEXÃO OK`, and
+ * still be unable to mint a single payment link. The only reading available is
+ * the owner's.
+ *
+ * Until they give it, the walkthrough stays on that step and the activation
+ * step is not on screen at all — one step at a time is the whole shape of this
+ * flow, and a card offering to charge R$ 1,01 sitting under "Passo 2" is two
+ * steps at once, the costly one unasked for.
+ *
+ * The exception is the case that must never regress: a store that has ALREADY
+ * paid sees the step regardless of what the guide would show, because that
+ * panel is what reports the confirmed charge — and, on a return trip, what
+ * reads the `transaction_nsu` the provider sends the payer back with.
+ */
+
+const GUIDE: ProviderSetupGuide = {
+  stages: [
+    { id: 'handle', label: 'Informar InfiniteTag' },
+    { id: 'enable', label: 'Habilitar o Checkout' },
+    { id: 'activate', label: 'Ativar vendas' },
+  ],
+  sections: [
+    {
+      id: 'enable',
+      title: 'Habilitar o Checkout Integrado',
+      steps: [{ text: 'Confirme que está ligado.', action: CHECKOUT_CONFIRM_ACTION }],
+    },
+  ],
+  activeStage: 2,
+};
+
+function viewWith(chargeVerifiedAt: string | null): MerchantSettingsView {
+  return {
+    providers: [
+      {
+        name: 'infinitepay',
+        displayName: 'InfinitePay',
+        authMode: 'credentials',
+        credentialSchema: [
+          { key: 'handle', label: 'InfiniteTag ($usuario)', secret: false, required: true },
+        ],
+      },
+    ],
+    configs: [
+      {
+        provider: 'infinitepay',
+        status: 'VERIFIED',
+        enabled: false,
+        chargeVerifiedAt,
+        environment: 'SANDBOX',
+        environments: { SANDBOX: { handle: { configured: true, hint: '$loja' } } },
+      },
+    ],
+    activeProvider: null,
+  } as unknown as MerchantSettingsView;
+}
+
+function fakeClient(view: MerchantSettingsView): PaymentsSettingsClient {
+  return {
+    baseUrl: '/api/admin/acme/payments',
+    getSettings: vi.fn().mockResolvedValue(view),
+    getSetupGuide: vi.fn().mockResolvedValue(GUIDE),
+    setEnabled: vi.fn(),
+    saveCredentials: vi.fn(),
+  } as unknown as PaymentsSettingsClient;
+}
+
+/** The host's step 3, reduced to the two facts this file is about. */
+function renderSettings(chargeVerifiedAt: string | null = null) {
+  const seen: Array<{ blocked: boolean; hidden: boolean }> = [];
+  render(
+    <PaymentProviderSettings
+      client={fakeClient(viewWith(chargeVerifiedAt))}
+      initialProvider="infinitepay"
+      renderVerification={({ blocked, hidden }) => {
+        seen.push({ blocked, hidden });
+        return (
+          <div data-testid="step-three" data-hidden={hidden}>
+            {blocked ? 'blocked' : 'ready'}
+          </div>
+        );
+      }}
+    />,
+  );
+  return seen;
+}
+
+/**
+ * How long the FIRST assertion of a test may take.
+ *
+ * It is not asserting a render — it is absorbing the screen's whole async
+ * boot: the settings fetch, then the setup-guide fetch keyed on what that
+ * returned, then the effects both settle. Every later assertion in the same
+ * test is a warm re-render and keeps the default.
+ *
+ * The default 1000ms was enough on a quiet machine and not on CI, where this
+ * package's tests run beside twenty others' — the lane went red on the landing
+ * line with the correct DOM already in the failure dump, which is the exact
+ * signature of a budget that is too tight rather than a screen that is wrong.
+ */
+const LANDED = { timeout: 10_000 };
+
+beforeEach(() => window.localStorage.clear());
+afterEach(cleanup);
+
+describe('the step only the owner can report', () => {
+  /**
+   * The step is told it is not the current one; it is not UNMOUNTED.
+   *
+   * The difference is load-bearing and was learned the hard way. A provider
+   * refusing to mint a link is the evidence that withdraws the owner's
+   * "Checkout Integrado is on" — so the guide goes back a step in the same
+   * render that produced the explanation, and unmounting the panel took the
+   * explanation off screen with it. The owner was returned to a step they
+   * believed they had finished, with nothing saying why.
+   *
+   * So the host is handed `hidden` and decides. With nothing settled it draws
+   * nothing (the pay button must not appear); with a refusal in hand it keeps
+   * saying so.
+   */
+  it('tells the activation step it is not the current one until Step 2 is confirmed', async () => {
+    renderSettings();
+
+    await screen.findByTestId('payments-setup-section-enable', undefined, LANDED);
+    const step = await screen.findByTestId('step-three', undefined, LANDED);
+    await waitFor(() => expect(step.dataset['hidden']).toBe('true'));
+    // And blocked with it: not the current step AND no pay button, which are
+    // two different withholdings that happen to coincide here.
+    expect(step.textContent).toBe('blocked');
+  });
+
+  it('releases the charge once the owner confirms, and remembers it', async () => {
+    renderSettings();
+
+    await screen.findByTestId('payments-setup-section-enable', undefined, LANDED);
+    fireEvent.click(screen.getByRole('button', { name: /Já habilitei o Checkout Integrado/i }));
+
+    await waitFor(() => expect(screen.getByTestId('step-three').textContent).toBe('ready'));
+    expect(screen.getByTestId('step-three').dataset['hidden']).toBe('false');
+    // Collapsed to a row rather than removed: it is the claim step 3 is about
+    // to test, and the owner needs somewhere to press Revisar when it fails.
+    expect(screen.getByTestId('payments-setup-confirmed')).toBeTruthy();
+
+    cleanup();
+    // The flow deliberately LEAVES the page — the owner pays on the provider's
+    // site and comes back. An answer that did not survive that round trip would
+    // bounce them to step 2, hiding the panel polling the payment they just
+    // made.
+    renderSettings();
+    await waitFor(() => expect(screen.getByTestId('step-three').textContent).toBe('ready'), LANDED);
+  });
+
+  /**
+   * A charge that landed proves the setting is on far better than the owner's
+   * word could, so a store reconnecting from a machine with no stored answer is
+   * never sent back through step 2.
+   */
+  it('never asks a store that has already been paid through', async () => {
+    renderSettings('2026-07-30T12:00:00.000Z');
+
+    await waitFor(() => expect(screen.getByTestId('step-three').textContent).toBe('ready'), LANDED);
+  });
+});

package/src/__tests__/connection-state.test.tsx

@@ -0,0 +1,84 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type { MaskedProviderConfig, MerchantSettingsView } from '@12-apps/payments-backend';
+
+import type { PaymentsSettingsClient } from '../client';
+import { connectionBadge, isConnected } from '../components/connection-state';
+import { ProviderList } from '../components/ProviderList';
+
+/**
+ * What "connected" means, in exactly one place.
+ *
+ * The screen shipped with two answers. Disconnecting does not delete the
+ * provider row — it empties every environment's credentials and resets the
+ * status — so the list, which only asked whether a row existed, kept reporting
+ * `Conectado` for a store that had just disconnected, while the panel one click
+ * away correctly offered `Conectar com PagBank`.
+ */
+
+function config(over: Partial<MaskedProviderConfig>): MaskedProviderConfig {
+  return { provider: 'pagbank', status: 'UNVERIFIED', enabled: false, ...over } as MaskedProviderConfig;
+}
+
+describe('isConnected', () => {
+  /** The reported bug: the row survives a disconnect, emptied. */
+  it('is false for the emptied row a disconnect leaves behind', () => {
+    expect(isConnected(config({ status: 'UNVERIFIED', enabled: false }))).toBe(false);
+  });
+
+  it('is false when no row exists at all', () => {
+    expect(isConnected(null)).toBe(false);
+  });
+
+  it('is true once the provider is verified', () => {
+    expect(isConnected(config({ status: 'VERIFIED' }))).toBe(true);
+  });
+
+  /** That store worked and still holds credentials; the grant is what lapsed. */
+  it('is true when a working connection needs reauthorizing', () => {
+    expect(isConnected(config({ status: 'RECONNECT_REQUIRED', enabled: true }))).toBe(true);
+  });
+});
+
+describe('connectionBadge', () => {
+  it('names a disconnected store as not connected', () => {
+    expect(connectionBadge(config({ status: 'UNVERIFIED' })).label).toBe('Não conectado');
+  });
+
+  it('leads with Ativo, the only state where money can move', () => {
+    expect(connectionBadge(config({ status: 'VERIFIED', enabled: true })).label).toBe('Ativo');
+  });
+
+  /**
+   * A lapsed grant is its own state. Folding it into `Conectado` hid the one
+   * card an owner needs to open.
+   */
+  it('calls out a lapsed authorization instead of calling it connected', () => {
+    expect(connectionBadge(config({ status: 'RECONNECT_REQUIRED' })).label).toBe('Reconectar');
+  });
+});
+
+const VIEW = (configs: MaskedProviderConfig[]): MerchantSettingsView =>
+  ({
+    providers: [{ name: 'pagbank', displayName: 'PagBank', authMode: 'oauth', credentialSchema: [] }],
+    configs,
+    activeProvider: null,
+  }) as unknown as MerchantSettingsView;
+
+afterEach(cleanup);
+
+describe('ProviderList — the card badge', () => {
+  it('reports a disconnected provider as not connected', () => {
+    render(
+      <ProviderList
+        view={VIEW([config({ status: 'UNVERIFIED', enabled: false })])}
+        client={{} as unknown as PaymentsSettingsClient}
+        reload={vi.fn()}
+        onSelect={vi.fn()}
+      />,
+    );
+    expect(screen.getByTestId('payments-provider-badge-pagbank').textContent).toBe('Não conectado');
+  });
+});

package/src/__tests__/context.test.tsx

@@ -0,0 +1,88 @@
+// @vitest-environment jsdom
+// fireEvent/render from @testing-library/react (act()-wrapped) — same choice
+// and reasoning as @12-apps/entitlements' react tests: user-event is not a
+// dependency of this package.
+import { render, screen, waitFor } from '@testing-library/react';
+import { useEffect } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { ClientChargeView } from '@12-apps/payments-backend';
+import type { PaymentsClient } from '../client';
+import { PaymentsProvider, useChargeStatus, useCreateCharge } from '../context';
+
+function chargeView(status: ClientChargeView['status']): ClientChargeView {
+  return {
+    provider: 'stone',
+    providerChargeId: 'chg-1',
+    status,
+    amount: { amountCents: 12_50, currency: 'BRL' },
+    method: 'PIX',
+    pix: { qrText: 'qr-payload' },
+  };
+}
+
+function fakeClient(overrides: Partial<PaymentsClient> = {}): PaymentsClient {
+  return {
+    getConfig: vi.fn().mockResolvedValue(null),
+    createCharge: vi.fn().mockResolvedValue(chargeView('PENDING')),
+    getCharge: vi.fn().mockResolvedValue(chargeView('PAID')),
+    ...overrides,
+  };
+}
+
+function CreateProbe() {
+  const { charge, create } = useCreateCharge();
+  useEffect(() => {
+    void create({
+      method: 'PIX',
+      customer: { name: 'Ana', email: 'ana@example.com' },
+      orderRef: 'order-1',
+    });
+  }, [create]);
+  if (!charge) return <span>creating</span>;
+  return <span>status:{charge.status}</span>;
+}
+
+function StatusProbe() {
+  const { charge, settled } = useChargeStatus({ provider: 'stone', providerChargeId: 'chg-1' }, { intervalMs: 5 });
+  return (
+    <span>
+      poll:{charge?.status ?? 'none'}:{settled ? 'settled' : 'waiting'}
+    </span>
+  );
+}
+
+describe('payments react bindings', () => {
+  it('useCreateCharge creates via the client and exposes the charge', async () => {
+    const client = fakeClient();
+    render(
+      <PaymentsProvider client={client}>
+        <CreateProbe />
+      </PaymentsProvider>,
+    );
+    await waitFor(() => {
+      expect(screen.getByText('status:PENDING')).toBeDefined();
+    });
+    expect(client.createCharge).toHaveBeenCalledTimes(1);
+  });
+
+  it('useChargeStatus polls until the charge settles', async () => {
+    const client = fakeClient();
+    render(
+      <PaymentsProvider client={client}>
+        <StatusProbe />
+      </PaymentsProvider>,
+    );
+    await waitFor(() => {
+      expect(screen.getByText('poll:PAID:settled')).toBeDefined();
+    });
+    expect(client.getCharge).toHaveBeenCalledWith('stone', 'chg-1');
+  });
+
+  it('hooks throw outside a <PaymentsProvider>', () => {
+    // Silence React's error boundary logging for the expected throw.
+    const spy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    expect(() => render(<StatusProbe />)).toThrow(/PaymentsProvider/);
+    spy.mockRestore();
+  });
+});

package/src/__tests__/controlled-provider.test.tsx

@@ -0,0 +1,116 @@
+// @vitest-environment jsdom
+import { render, screen, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { MerchantSettingsView } from '@12-apps/payments-backend';
+
+import type { PaymentsSettingsClient } from '../client';
+import { PaymentProviderSettings } from '../components/PaymentProviderSettings';
+
+/**
+ * Controlled selection — the mode a host uses when the open provider lives in
+ * the URL, so each one is its own page.
+ *
+ * The failure this guards is the component quietly keeping its own copy of the
+ * selection: the screen would still LOOK right on a click (internal state moved
+ * too), and only a reload, a shared link or the browser's back button would
+ * show the two had drifted. So these assert on the direction of travel — the
+ * host's value wins, and the component only ever ASKS to change it.
+ */
+
+const VIEW: MerchantSettingsView = {
+  providers: [
+    { name: 'pagbank', displayName: 'PagBank', authMode: 'oauth', credentialSchema: [] },
+    { name: 'stripe', displayName: 'Stripe', authMode: 'credentials', credentialSchema: [] },
+  ],
+  configs: [],
+  activeProvider: null,
+} as unknown as MerchantSettingsView;
+
+function fakeClient(): PaymentsSettingsClient {
+  return {
+    getSettings: vi.fn().mockResolvedValue(VIEW),
+    getSetupGuide: vi.fn().mockResolvedValue(null),
+    setEnabled: vi.fn(),
+    saveCredentials: vi.fn(),
+  } as unknown as PaymentsSettingsClient;
+}
+
+describe('PaymentProviderSettings — host-controlled selection', () => {
+  it('opens the provider the host names, on the first render', async () => {
+    render(<PaymentProviderSettings client={fakeClient()} selectedProvider="pagbank" />);
+
+    // No handover tick to wait for: a controlled host has the answer at mount.
+    expect(await screen.findByTestId('payments-provider-back')).toBeDefined();
+    await waitFor(() => expect(screen.queryByTestId('payments-provider-picker')).toBeNull());
+  });
+
+  /**
+   * `null` is an answer, not a missing prop. Read as "unset" it would fall back
+   * to internal state and strand the owner in the provider they last opened.
+   */
+  it('shows the list when the host says null', async () => {
+    render(<PaymentProviderSettings client={fakeClient()} selectedProvider={null} />);
+    expect(await screen.findByTestId('payments-provider-picker')).toBeDefined();
+  });
+
+  /**
+   * The core of controlled mode: a click must not move the view on its own.
+   * If it does, the URL and the screen disagree the moment either is reloaded.
+   */
+  it('does not change the open provider by itself — it asks', async () => {
+    const onProviderChange = vi.fn();
+    render(
+      <PaymentProviderSettings
+        client={fakeClient()}
+        selectedProvider="pagbank"
+        onProviderChange={onProviderChange}
+      />,
+    );
+    const back = await screen.findByTestId('payments-provider-back');
+
+    back.click();
+
+    await waitFor(() => expect(onProviderChange).toHaveBeenCalledWith(null));
+    // Still on pagbank: the host has not said otherwise yet.
+    expect(screen.getByTestId('payments-provider-back')).toBeDefined();
+    await waitFor(() => expect(screen.queryByTestId('payments-provider-picker')).toBeNull());
+  });
+
+  /** The host's later value is honoured every time — not once, as with initialProvider. */
+  it('follows the host on each change, in both directions', async () => {
+    const client = fakeClient();
+    const { rerender } = render(
+      <PaymentProviderSettings client={client} selectedProvider="pagbank" />,
+    );
+    await screen.findByTestId('payments-provider-back');
+
+    rerender(<PaymentProviderSettings client={client} selectedProvider={null} />);
+    expect(await screen.findByTestId('payments-provider-picker')).toBeDefined();
+
+    rerender(<PaymentProviderSettings client={client} selectedProvider="stripe" />);
+    await waitFor(() => expect(screen.queryByTestId('payments-provider-picker')).toBeNull());
+  });
+
+  /**
+   * Uncontrolled hosts predate this prop and must be untouched: selection stays
+   * internal, and `onProviderChange` is only an observer.
+   */
+  it('still keeps its own selection when the host does not control it', async () => {
+    const onProviderChange = vi.fn();
+    render(
+      <PaymentProviderSettings
+        client={fakeClient()}
+        initialProvider="pagbank"
+        onProviderChange={onProviderChange}
+      />,
+    );
+    const back = await screen.findByTestId('payments-provider-back');
+
+    back.click();
+
+    const picker = await screen.findByTestId('payments-provider-picker');
+    expect(picker).toBeDefined();
+    await waitFor(() => expect(onProviderChange).toHaveBeenCalledWith(null));
+  });
+});