@12-apps/payments-frontend 1.0.0

package/src/__tests__/credential-confirm.test.tsx

@@ -0,0 +1,193 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { useState } from 'react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type { MaskedProviderConfig, ProviderDescriptor } from '@12-apps/payments-backend';
+
+import type { PaymentsSettingsClient } from '../client';
+import { ProviderForm } from '../components/ProviderCredentialForm';
+import { statusBadge } from '../components/ProviderStatusBar';
+
+// jest-dom is not a dependency here — assert DOM properties directly.
+
+/**
+ * The last look at the value that decides who gets paid, and the words the
+ * screen uses for how far a store has actually got.
+ *
+ * Both exist because of the same mistake in two forms: a screen saying more
+ * than it can back. `VERIFIED` was a claim about credentials authenticating,
+ * read by owners as "my store can take money"; and Salvar wrote an InfiniteTag
+ * — one unchecksummed string that routes every payment the store will ever
+ * receive — with no more ceremony than a display name.
+ */
+
+const DESCRIPTOR = {
+  name: 'infinitepay',
+  displayName: 'InfinitePay',
+  authMode: 'credentials',
+  credentialSchema: [
+    {
+      key: 'handle',
+      label: 'InfiniteTag ($usuario)',
+      secret: false,
+      required: true,
+      mono: true,
+      confirmOnSave: true,
+    },
+  ],
+} as unknown as ProviderDescriptor;
+
+function configWith(hint: string | null, status = 'UNVERIFIED'): MaskedProviderConfig {
+  return {
+    provider: 'infinitepay',
+    status,
+    enabled: false,
+    chargeVerifiedAt: null,
+    environment: 'SANDBOX',
+    environments: {
+      SANDBOX: hint ? { handle: { configured: true, hint } } : {},
+      PRODUCTION: {},
+    },
+  } as unknown as MaskedProviderConfig;
+}
+
+function fakeClient(): PaymentsSettingsClient {
+  return {
+    baseUrl: '/api/admin/acme/payments',
+    saveCredentials: vi.fn().mockResolvedValue(configWith('$loja')),
+    verify: vi.fn(),
+  } as unknown as PaymentsSettingsClient;
+}
+
+/**
+ * `editing` is owned by the PANEL in the real screen — reopening a finished
+ * step also has to take step 3 off the page — so the harness plays that part.
+ */
+function Harness({
+  config,
+  client,
+}: {
+  config: MaskedProviderConfig | null;
+  client: PaymentsSettingsClient;
+}) {
+  const [editing, setEditing] = useState(false);
+  return (
+    <ProviderForm
+      descriptor={DESCRIPTOR}
+      config={config}
+      client={client}
+      environment="SANDBOX"
+      editing={editing}
+      onEditingChange={setEditing}
+      onSaved={() => undefined}
+    />
+  );
+}
+
+function renderForm(config: MaskedProviderConfig | null, client = fakeClient()) {
+  render(<Harness config={config} client={client} />);
+  return client;
+}
+
+afterEach(cleanup);
+
+describe('saving a credential that decides where the money goes', () => {
+  it('quotes the new value back before writing it', async () => {
+    const client = renderForm(configWith(null));
+
+    fireEvent.change(screen.getByLabelText(/^InfiniteTag/), { target: { value: '$loja-nova' } });
+    fireEvent.click(screen.getByTestId('payments-save'));
+
+    // Nothing is written while the question is open — the point is the reading,
+    // and a dialog that appears after the write would be decoration.
+    expect(screen.getByTestId('payments-confirm-credential-value').textContent).toBe('$loja-nova');
+    expect(client.saveCredentials).not.toHaveBeenCalled();
+
+    fireEvent.click(screen.getByTestId('payments-confirm-credential-confirm'));
+    await waitFor(() => expect(client.saveCredentials).toHaveBeenCalled());
+  });
+
+  it('lets the owner back out without writing anything', async () => {
+    const client = renderForm(configWith(null));
+
+    fireEvent.change(screen.getByLabelText(/^InfiniteTag/), { target: { value: '$errada' } });
+    fireEvent.click(screen.getByTestId('payments-save'));
+    fireEvent.click(screen.getByTestId('payments-confirm-credential-cancel'));
+
+    await waitFor(() =>
+      expect(screen.queryByTestId('payments-confirm-credential-value')).toBeNull(),
+    );
+    expect(client.saveCredentials).not.toHaveBeenCalled();
+  });
+
+  /**
+   * The exemption that keeps the dialog meaningful.
+   *
+   * Re-typing the value already stored cannot introduce a wrong one, so there
+   * is nothing to re-read. Asking anyway would train the owner to click through
+   * it, which is the one way to make a confirmation useless on the occasion it
+   * matters.
+   */
+  it('does not ask when the value is not changing', async () => {
+    const client = renderForm(configWith('$loja'));
+
+    const field = screen.getByLabelText(/^InfiniteTag/);
+    fireEvent.change(field, { target: { value: '$loj' } });
+    fireEvent.change(field, { target: { value: '$loja' } });
+    fireEvent.click(screen.getByTestId('payments-save'));
+
+    await waitFor(() => expect(client.saveCredentials).toHaveBeenCalled());
+    await waitFor(() =>
+      expect(screen.queryByTestId('payments-confirm-credential-value')).toBeNull(),
+    );
+  });
+
+  /**
+   * A finished step is a line, not a form. Leaving the field editable meant the
+   * value that routes the store's money sat one stray keystroke from changing,
+   * in front of an owner who had come back to check something else.
+   */
+  it('folds a proven-connection credential into a summary row', async () => {
+    renderForm(configWith('$loja', 'VERIFIED'));
+
+    const summary = await screen.findByTestId('payments-credential-summary');
+    expect(summary.textContent).toContain('$loja');
+    await waitFor(() => expect(screen.queryByLabelText(/^InfiniteTag/)).toBeNull());
+
+    fireEvent.click(screen.getByTestId('payments-credential-summary-edit'));
+    expect(await screen.findByLabelText(/^InfiniteTag/)).toBeTruthy();
+  });
+});
+
+/**
+ * Three different facts used to share one word, and the green one was the
+ * least earned. `VERIFIED` comes from the credential probe: PagBank answers
+ * yes to it while refusing every charge until homologação, and InfinitePay
+ * answers yes with Checkout Integrado switched off, which mints no links at
+ * all. Only `chargeVerifiedAt` is a payment that actually landed.
+ */
+describe('what the status chip is allowed to claim', () => {
+  it('separates reaching the account from being able to charge', () => {
+    expect(statusBadge(null).label).toBe('NÃO VERIFICADO');
+    expect(statusBadge(configWith('$loja')).label).toBe('NÃO VERIFICADO');
+
+    const probed = statusBadge(configWith('$loja', 'VERIFIED'));
+    expect(probed.label).toBe('CONEXÃO OK');
+    expect(probed.color).not.toBe('success');
+
+    const paid = {
+      ...configWith('$loja', 'VERIFIED'),
+      chargeVerifiedAt: '2026-07-30T12:00:00.000Z',
+    } as MaskedProviderConfig;
+    expect(statusBadge(paid)).toEqual({ label: 'VERIFICADO', color: 'success' });
+  });
+
+  it('says RECONECTAR rather than a bare failure when a grant lapsed', () => {
+    expect(statusBadge(configWith('$loja', 'RECONNECT_REQUIRED')).label).toBe('RECONECTAR');
+    // A failed probe is NOT a third state: the store cannot take money yet,
+    // which is what NÃO VERIFICADO already says. The probe's own sentence
+    // beneath the chip is what names the tag and the fix.
+    expect(statusBadge(configWith('$loja', 'FAILED')).label).toBe('NÃO VERIFICADO');
+  });
+});

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

@@ -0,0 +1,81 @@
+// @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';
+
+/**
+ * Landing after an OAuth connect.
+ *
+ * This shipped broken TWICE, and the second time only because the test was
+ * shaped around the code instead of the failure. The host reads the connected
+ * provider from the callback's query string in an EFFECT, so it is null on
+ * first render and arrives a tick later — and `useState(initialProvider)` keeps
+ * the null forever. A test that renders with the prop already set passes
+ * happily and proves nothing; the prop has to ARRIVE.
+ */
+
+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 — landing after a connect', () => {
+  it('lands on the provider list when nothing was just connected', async () => {
+    render(<PaymentProviderSettings client={fakeClient()} />);
+    expect(await screen.findByTestId('payments-provider-picker')).toBeDefined();
+  });
+
+  /**
+   * The regression: the prop is null at mount and supplied afterwards, exactly
+   * as the host does it. Seeding `useState` with it passes the OTHER test and
+   * fails this one.
+   */
+  it('opens the provider when the host supplies it AFTER mount', async () => {
+    const client = fakeClient();
+    const { rerender } = render(<PaymentProviderSettings client={client} initialProvider={null} />);
+    await screen.findByTestId('payments-provider-picker');
+
+    rerender(<PaymentProviderSettings client={client} initialProvider="pagbank" />);
+
+    // The picker is replaced by that provider's own panel.
+    await waitFor(() => expect(screen.queryByTestId('payments-provider-picker')).toBeNull());
+    expect(screen.getByTestId('payments-provider-back')).toBeDefined();
+  });
+
+  /**
+   * Applied once, not on every render: the host holds the outcome for the
+   * page's lifetime, so re-applying would make "Voltar aos provedores" bounce
+   * straight back into the provider and trap the owner on one screen.
+   */
+  it('does not re-open the provider after the owner goes back', async () => {
+    const client = fakeClient();
+    const { rerender } = render(<PaymentProviderSettings client={client} initialProvider={null} />);
+    await screen.findByTestId('payments-provider-picker');
+
+    rerender(<PaymentProviderSettings client={client} initialProvider="pagbank" />);
+    const back = await screen.findByTestId('payments-provider-back');
+
+    back.click();
+
+    // A rerender with the SAME still-set prop must not drag them back in.
+    rerender(<PaymentProviderSettings client={client} initialProvider="pagbank" />);
+    expect(await screen.findByTestId('payments-provider-picker')).toBeDefined();
+  });
+});

package/src/__tests__/provider-priority-list.test.tsx

@@ -0,0 +1,159 @@
+// @vitest-environment jsdom
+// fireEvent/render from @testing-library/react (act()-wrapped) — same choice
+// and reasoning as the context tests: user-event is not a dependency here.
+import { fireEvent, render, screen, waitFor } from '@testing-library/react';
+import { describe, expect, it, vi } from 'vitest';
+
+import type { MaskedProviderConfig, MerchantSettingsView } from '@12-apps/payments-backend';
+
+import type { PaymentsSettingsClient } from '../client';
+import { ProviderPriorityList, chainOf } from '../components/ProviderPriorityList';
+
+/**
+ * The failover-chain editor. What matters here is not the drag mechanics but
+ * that the order the merchant sees is the order checkout will use, and that a
+ * failed save never leaves the screen claiming an order the server rejected.
+ */
+
+function config(provider: string, enabled: boolean, priority: number): MaskedProviderConfig {
+  return {
+    provider,
+    enabled,
+    priority,
+    environment: 'SANDBOX',
+    status: 'VERIFIED',
+    lastVerifiedAt: null,
+    // Every row in the chain editor is by definition already proven — only a
+    // successful charge can put a provider in the chain at all.
+    chargeVerifiedAt: '2026-07-30T12:00:00.000Z',
+    expiresAt: null,
+    stub: false,
+    environments: { SANDBOX: {}, PRODUCTION: {} },
+  };
+}
+
+function viewOf(configs: MaskedProviderConfig[]): MerchantSettingsView {
+  const chain = configs.filter((c) => c.enabled).map((c) => c.provider);
+  return {
+    providers: [
+      { name: 'stone', displayName: 'Stone', authMode: 'credentials', capabilities: CAPS, credentialSchema: [] },
+      { name: 'stripe', displayName: 'Stripe', authMode: 'oauth', capabilities: CAPS, credentialSchema: [] },
+    ],
+    configs,
+    providerChain: chain,
+    activeProvider: chain[0] ?? null,
+    failoverPolicy: 'TECHNICAL',
+  };
+}
+
+const CAPS = {
+  methods: ['PIX'] as const,
+  savedCards: false,
+  refunds: false,
+  partialRefunds: false,
+  splits: false,
+  webhooks: true,
+  tokenization: 'NONE' as const,
+};
+
+function fakeClient(overrides: Partial<PaymentsSettingsClient> = {}): PaymentsSettingsClient {
+  return {
+    getSettings: vi.fn(),
+    saveCredentials: vi.fn(),
+    setEnabled: vi.fn(),
+    setPriorities: vi.fn(),
+    setFailoverPolicy: vi.fn(),
+    verify: vi.fn(),
+    getSetupGuide: vi.fn(),
+    beginOAuth: vi.fn(),
+    disconnectOAuth: vi.fn(),
+    ...overrides,
+  } as PaymentsSettingsClient;
+}
+
+/** The rendered chain order, read off the list rows. */
+function rowOrder(): string[] {
+  return Array.from(document.querySelectorAll('[data-testid^="payments-priority-item-"]')).map(
+    (el) => el.getAttribute('data-testid')!.replace('payments-priority-item-', ''),
+  );
+}
+
+describe('chainOf', () => {
+  it('derives the chain from configs, ordered by rank', () => {
+    const view = viewOf([config('stripe', true, 1), config('stone', true, 0)]);
+    expect(chainOf(view)).toEqual(['stone', 'stripe']);
+  });
+
+  it('ignores providers that are configured but out of rotation', () => {
+    const view = viewOf([config('stone', true, 0), config('stripe', false, 0)]);
+    expect(chainOf(view)).toEqual(['stone']);
+  });
+});
+
+describe('ProviderPriorityList', () => {
+  it('names the provider checkout will try first', () => {
+    render(
+      <ProviderPriorityList
+        view={viewOf([config('stone', true, 0), config('stripe', true, 1)])}
+        client={fakeClient()}
+      />,
+    );
+    // The intro names it in prose AND the row is first in the list; assert on
+    // the list, which is the thing that actually encodes routing order.
+    expect(screen.getByTestId('payments-priority-first')).toBeTruthy();
+    expect(rowOrder()).toEqual(['stone', 'stripe']);
+  });
+
+  it('warns when nothing is in rotation, because checkout cannot charge', () => {
+    render(<ProviderPriorityList view={viewOf([config('stone', false, 0)])} client={fakeClient()} />);
+    expect(screen.getByTestId('payments-priority-empty')).toBeTruthy();
+  });
+
+  it('saves the WHOLE reordered chain, not a per-provider delta', async () => {
+    const reordered = viewOf([config('stripe', true, 0), config('stone', true, 1)]);
+    const setPriorities = vi.fn().mockResolvedValue(reordered);
+    render(
+      <ProviderPriorityList
+        view={viewOf([config('stone', true, 0), config('stripe', true, 1)])}
+        client={fakeClient({ setPriorities })}
+      />,
+    );
+
+    fireEvent.click(screen.getByLabelText('Mover Stone para baixo'));
+
+    await waitFor(() => {
+      expect(setPriorities).toHaveBeenCalledWith(['stripe', 'stone']);
+    });
+  });
+
+  it('rolls the list back when the save fails, and says why', async () => {
+    const setPriorities = vi.fn().mockRejectedValue(new Error('conflito de ordem'));
+    render(
+      <ProviderPriorityList
+        view={viewOf([config('stone', true, 0), config('stripe', true, 1)])}
+        client={fakeClient({ setPriorities })}
+      />,
+    );
+
+    fireEvent.click(screen.getByLabelText('Mover Stone para baixo'));
+
+    await waitFor(() => {
+      expect(screen.getByTestId('payments-priority-error').textContent).toContain(
+        'conflito de ordem',
+      );
+    });
+    // The screen must not keep showing an order the server refused.
+    expect(rowOrder()).toEqual(['stone', 'stripe']);
+  });
+
+  it('cannot move the first provider up or the last one down', () => {
+    render(
+      <ProviderPriorityList
+        view={viewOf([config('stone', true, 0), config('stripe', true, 1)])}
+        client={fakeClient()}
+      />,
+    );
+    expect(screen.getByLabelText('Mover Stone para cima').hasAttribute('disabled')).toBe(true);
+    expect(screen.getByLabelText('Mover Stripe para baixo').hasAttribute('disabled')).toBe(true);
+  });
+});

package/src/__tests__/provider-status-bar.test.tsx

@@ -0,0 +1,152 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type { MaskedProviderConfig, ProviderDescriptor } from '@12-apps/payments-backend';
+
+import { ProviderStatusBar } from '../components/ProviderStatusBar';
+
+/**
+ * "Ativo" decides whether checkout routes real buyers to this provider, so it
+ * must not be offerable before there is anything to route to. The screen shipped
+ * showing `PagBank [UNVERIFIED] [on] Ativo` — a provider that had never proved
+ * it could charge, presented as live.
+ */
+
+/** A provider that CAN run the activation charge, so the strict rule applies. */
+const DESCRIPTOR = {
+  name: 'pagbank',
+  displayName: 'PagBank',
+  capabilities: { activationCharge: true },
+} as unknown as ProviderDescriptor;
+
+/**
+ * One that cannot: no browser tokenization is written for it, so there is no
+ * way to earn `chargeVerifiedAt`. Holding it to the charge would not make
+ * "Ativo" honest — it would make the provider permanently unactivatable.
+ */
+const NO_CHARGE_PATH = {
+  name: 'stripe',
+  displayName: 'Stripe',
+  capabilities: { activationCharge: false },
+} as unknown as ProviderDescriptor;
+
+function configWith(
+  status: string,
+  enabled = false,
+  chargeVerifiedAt: string | null = null,
+): MaskedProviderConfig {
+  return {
+    provider: 'pagbank',
+    status,
+    enabled,
+    chargeVerifiedAt,
+  } as unknown as MaskedProviderConfig;
+}
+
+const PROVEN = '2026-07-30T12:00:00.000Z';
+
+/**
+ * jest-dom is not a dependency here, so assert the DOM property directly. The
+ * testid lands on MUI's Switch ROOT; the thing that carries `disabled` is the
+ * checkbox input inside it.
+ */
+function toggle(): HTMLInputElement {
+  const root = screen.getByTestId('payments-enabled-toggle');
+  const input = root.querySelector('input[type="checkbox"]');
+  if (!input) throw new Error('switch input not found');
+  return input as HTMLInputElement;
+}
+
+afterEach(cleanup);
+
+describe('ProviderStatusBar — the Ativo switch', () => {
+  it('cannot be switched on with no connection at all', () => {
+    render(<ProviderStatusBar descriptor={DESCRIPTOR} config={null} busy={false} onToggle={vi.fn()} />);
+    expect(toggle().disabled).toBe(true);
+  });
+
+  it('cannot be switched on while the provider is UNVERIFIED', () => {
+    render(
+      <ProviderStatusBar
+        descriptor={DESCRIPTOR}
+        config={configWith('UNVERIFIED')}
+        busy={false}
+        onToggle={vi.fn()}
+      />,
+    );
+    expect(toggle().disabled).toBe(true);
+  });
+
+  /**
+   * The one this exists for. `VERIFIED` comes from the credential probe, which
+   * only asks whether the keys authenticate — PagBank answers yes to that and
+   * still refuses every real charge until the integration is homologated. A
+   * store sat at `PagBank [VERIFIED] [on] Ativo` while declining every shopper.
+   */
+  it('stays locked at VERIFIED — authenticating is not being able to charge', () => {
+    render(
+      <ProviderStatusBar
+        descriptor={DESCRIPTOR}
+        config={configWith('VERIFIED')}
+        busy={false}
+        onToggle={vi.fn()}
+      />,
+    );
+    expect(toggle().disabled).toBe(true);
+  });
+
+  it('unlocks once a real charge has succeeded', () => {
+    render(
+      <ProviderStatusBar
+        descriptor={DESCRIPTOR}
+        config={configWith('VERIFIED', false, PROVEN)}
+        busy={false}
+        onToggle={vi.fn()}
+      />,
+    );
+    expect(toggle().disabled).toBe(false);
+  });
+
+  /**
+   * Turning OFF is never gated. A row enabled before this rule existed — or a
+   * store in RECONNECT_REQUIRED that demonstrably worked — must be pullable out
+   * of rotation at once, or the switch traps an owner with a broken provider
+   * live in the chain.
+   */
+  it('lets an enabled-but-unproven provider be switched off', () => {
+    render(
+      <ProviderStatusBar
+        descriptor={DESCRIPTOR}
+        config={configWith('RECONNECT_REQUIRED', true)}
+        busy={false}
+        onToggle={vi.fn()}
+      />,
+    );
+    expect(toggle().disabled).toBe(false);
+  });
+
+  it('falls back to VERIFIED for a provider that cannot run the charge', () => {
+    render(
+      <ProviderStatusBar
+        descriptor={NO_CHARGE_PATH}
+        config={configWith('VERIFIED')}
+        busy={false}
+        onToggle={vi.fn()}
+      />,
+    );
+    expect(toggle().disabled).toBe(false);
+  });
+
+  it('is locked while another action is in flight', () => {
+    render(
+      <ProviderStatusBar
+        descriptor={DESCRIPTOR}
+        config={configWith('VERIFIED', false, PROVEN)}
+        busy
+        onToggle={vi.fn()}
+      />,
+    );
+    expect(toggle().disabled).toBe(true);
+  });
+});