@12-apps/payments-frontend 1.0.0

package/src/__tests__/verification-slot.test.tsx

@@ -0,0 +1,125 @@
+// @vitest-environment jsdom
+import { cleanup, render, screen, waitFor } from '@testing-library/react';
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import type { MerchantSettingsView } from '@12-apps/payments-backend';
+
+import type { PaymentsSettingsClient } from '../client';
+import { PaymentProviderSettings } from '../components/PaymentProviderSettings';
+
+/**
+ * The activation step's slot.
+ *
+ * "Connected" and "can charge" are different facts, and only the HOST can prove
+ * the second — it owns the endpoint that puts a real cent through the store's
+ * account. This package's job is narrower and worth pinning: place that step
+ * where an owner will actually find it, and tell the host which provider is
+ * open and whether it is already live.
+ */
+
+const PROVIDERS = [
+  { name: 'pagbank', displayName: 'PagBank', authMode: 'oauth', credentialSchema: [] },
+];
+
+function viewWith(config: Record<string, unknown> | null): MerchantSettingsView {
+  return {
+    providers: PROVIDERS,
+    configs: config ? [config] : [],
+    activeProvider: null,
+  } as unknown as MerchantSettingsView;
+}
+
+function fakeClient(view: MerchantSettingsView): PaymentsSettingsClient {
+  return {
+    getSettings: vi.fn().mockResolvedValue(view),
+    getSetupGuide: vi.fn().mockResolvedValue(null),
+    setEnabled: vi.fn(),
+    saveCredentials: vi.fn(),
+  } as unknown as PaymentsSettingsClient;
+}
+
+afterEach(cleanup);
+
+describe('PaymentProviderSettings — the verification slot', () => {
+  it('is not rendered while the owner is still on the provider list', async () => {
+    const renderVerification = vi.fn(() => <div data-testid="slot" />);
+    render(
+      <PaymentProviderSettings
+        client={fakeClient(viewWith(null))}
+        renderVerification={renderVerification}
+      />,
+    );
+
+    await screen.findByTestId('payments-provider-picker');
+    expect(renderVerification).not.toHaveBeenCalled();
+  });
+
+  it('hands the host the open provider and its connection state', async () => {
+    const renderVerification = vi.fn(() => <div data-testid="slot" />);
+    render(
+      <PaymentProviderSettings
+        client={fakeClient(
+          viewWith({ provider: 'pagbank', status: 'VERIFIED', enabled: true, environments: {} }),
+        )}
+        initialProvider="pagbank"
+        renderVerification={renderVerification}
+      />,
+    );
+
+    await screen.findByTestId('slot');
+    expect(renderVerification).toHaveBeenCalledWith(
+      expect.objectContaining({ provider: 'pagbank', connected: true }),
+    );
+    /**
+     * `enabled` is deliberately withheld. The step used it to render a
+     * standing "Provedor ativo" banner, which went on reassuring a store whose
+     * every charge was refused — the banner and the refusal were on screen
+     * together. The step reports what it observes, nothing else.
+     */
+    expect(renderVerification).not.toHaveBeenCalledWith(
+      expect.objectContaining({ enabled: expect.anything() }),
+    );
+  });
+
+  /**
+   * A provider with no stored row yet still renders the slot — the host decides
+   * to show nothing. Reporting `connected: false` is what lets it.
+   */
+  it('reports a provider with no stored connection as not connected', async () => {
+    const renderVerification = vi.fn(() => <div data-testid="slot" />);
+    render(
+      <PaymentProviderSettings
+        client={fakeClient(viewWith(null))}
+        initialProvider="pagbank"
+        renderVerification={renderVerification}
+      />,
+    );
+
+    await screen.findByTestId('slot');
+    expect(renderVerification).toHaveBeenCalledWith(
+      expect.objectContaining({ connected: false }),
+    );
+  });
+
+  /**
+   * Placement, not just presence: the step must sit OUTSIDE the manual
+   * credentials disclosure. An owner who connected by OAuth is told no key
+   * needs copying, so they have no reason to open it — and the step that
+   * actually turns the store on would be hidden in there.
+   */
+  it('places the step outside the manual-credentials disclosure', async () => {
+    render(
+      <PaymentProviderSettings
+        client={fakeClient(
+          viewWith({ provider: 'pagbank', status: 'VERIFIED', enabled: false, environments: {} }),
+        )}
+        initialProvider="pagbank"
+        renderVerification={() => <div data-testid="slot" />}
+      />,
+    );
+
+    const slot = await screen.findByTestId('slot');
+    await waitFor(() => expect(screen.queryByTestId('payments-manual-fallback')).toBeNull());
+    expect(slot.closest('[data-testid="payments-manual-fallback"]')).toBeNull();
+  });
+});

package/src/client.ts

@@ -0,0 +1,200 @@
+import type {
+  ChargeRequestDraft,
+  ChargeStatus,
+  ClientChargeView,
+  ClientTokenization,
+  MaskedProviderConfig,
+  MerchantFailoverPolicy,
+  MerchantSettingsView,
+  PaymentEnvironment,
+  ProviderName,
+  ProviderSetupGuide,
+  SaveCredentialsInput,
+  VerifiedProviderConfig,
+} from '@12-apps/payments-backend';
+
+/**
+ * Browser-side API clients. They talk to the HOST's endpoints (which mount
+ * `@12-apps/payments-backend`'s HTTP handlers) — never to a provider directly.
+ * Endpoint paths are injected so every app can mount its routes wherever it
+ * likes; the shapes are fixed so the components work identically everywhere.
+ *
+ * Only TYPES are imported from the backend package — no server code ever
+ * enters a browser bundle.
+ */
+
+/** Charge states the frontend should stop polling on. */
+export function isSettled(status: ChargeStatus): boolean {
+  return status !== 'PENDING' && status !== 'AUTHORIZED';
+}
+
+/**
+ * What the browser sends to create a charge. Card data is TOKENS ONLY, and
+ * there is deliberately no `amount`/`reference`: the SERVER resolves what is
+ * owed and for which order (see the backend's `resolveChargeRequest`), so a
+ * tampered client cannot underpay or point a payment at someone else's order.
+ */
+export type ClientChargeRequest = ChargeRequestDraft;
+
+/** Client-safe tokenization config (see the backend's `clientConfig`). */
+export interface ClientPaymentsConfig {
+  provider: ProviderName;
+  tokenization: ClientTokenization;
+  publicKey?: string;
+}
+
+export class PaymentsClientError extends Error {
+  constructor(
+    readonly status: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = 'PaymentsClientError';
+  }
+}
+
+export interface PaymentsClientOptions {
+  /** e.g. `/api/payments` — host route prefix wrapping the gateway. */
+  baseUrl: string;
+  /** Injectable for tests; defaults to the global `fetch`. */
+  fetchImpl?: typeof fetch;
+}
+
+function makeRequest(options: PaymentsClientOptions) {
+  const fetchImpl = options.fetchImpl ?? fetch;
+  return async function request<T>(path: string, init?: RequestInit): Promise<T> {
+    const res = await fetchImpl(`${options.baseUrl}${path}`, {
+      headers: { 'content-type': 'application/json' },
+      ...init,
+    });
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      throw new PaymentsClientError(res.status, body || `Payments request failed (${res.status})`);
+    }
+    return (await res.json()) as T;
+  };
+}
+
+/** Checkout-surface client (buyer-facing). */
+export interface PaymentsClient {
+  getConfig(): Promise<ClientPaymentsConfig | null>;
+  createCharge(request: ClientChargeRequest): Promise<ClientChargeView>;
+  getCharge(provider: ProviderName, providerChargeId: string): Promise<ClientChargeView>;
+}
+
+export function createPaymentsClient(options: PaymentsClientOptions): PaymentsClient {
+  const request = makeRequest(options);
+  return {
+    getConfig: () => request<ClientPaymentsConfig | null>('/config'),
+    createCharge: (body) =>
+      request<ClientChargeView>('/charges', { method: 'POST', body: JSON.stringify(body) }),
+    getCharge: (provider, providerChargeId) =>
+      request<ClientChargeView>(
+        `/charges/${encodeURIComponent(provider)}/${encodeURIComponent(providerChargeId)}`,
+      ),
+  };
+}
+
+/** Settings-surface client (merchant-admin-facing). */
+export interface PaymentsSettingsClient {
+  /**
+   * The host prefix this client was built on, echoed back.
+   *
+   * Exposed because it is the only MERCHANT-SCOPED identifier the components
+   * have: the package is deliberately ignorant of tenants, and a host mounts
+   * one client per store (`/api/admin/<slug>/payments`). Anything the browser
+   * remembers per store — a setup step the owner has ticked off — has to be
+   * keyed on something, and this is it. Read-only; nothing derives a request
+   * path from it.
+   */
+  readonly baseUrl: string;
+  getSettings(): Promise<MerchantSettingsView>;
+  saveCredentials(provider: ProviderName, input: SaveCredentialsInput): Promise<MaskedProviderConfig>;
+  setEnabled(provider: ProviderName, enabled: boolean): Promise<MaskedProviderConfig>;
+  /**
+   * Replace the whole failover chain in priority order. Sends the COMPLETE
+   * enabled set, not a delta — a reorder is one intent, and splitting it into
+   * per-provider writes is what allows a half-applied order.
+   */
+  setPriorities(ordered: readonly ProviderName[]): Promise<MerchantSettingsView>;
+  /** Whether a declined card may be retried on the next acquirer. */
+  setFailoverPolicy(policy: MerchantFailoverPolicy): Promise<MerchantSettingsView>;
+  /**
+   * Probe the stored credentials for `environment` (default: the active one).
+   *
+   * The reply carries `probe` because the stored `status` answers only for the
+   * ACTIVE environment — testing the other tab reports its result without
+   * overwriting a verdict that describes different credentials.
+   */
+  verify(
+    provider: ProviderName,
+    environment?: PaymentEnvironment,
+  ): Promise<VerifiedProviderConfig>;
+  /** Null when the provider ships no walkthrough (endpoint 404s). */
+  getSetupGuide(provider: ProviderName): Promise<ProviderSetupGuide | null>;
+  /**
+   * Start an OAuth connect. `state` is minted and stored SERVER-side by the
+   * host against the admin session; the browser only carries it onward.
+   */
+  beginOAuth(
+    provider: ProviderName,
+    body: { state: string; redirectUri: string; environment?: 'SANDBOX' | 'PRODUCTION' },
+  ): Promise<{ url: string; state: string }>;
+  disconnectOAuth(provider: ProviderName): Promise<{ disconnected: boolean }>;
+}
+
+export function createPaymentsSettingsClient(
+  options: PaymentsClientOptions,
+): PaymentsSettingsClient {
+  const request = makeRequest(options);
+  const providerPath = (provider: ProviderName, suffix = ''): string =>
+    `/settings/providers/${encodeURIComponent(provider)}${suffix}`;
+  return {
+    baseUrl: options.baseUrl,
+    getSettings: () => request<MerchantSettingsView>('/settings'),
+    saveCredentials: (provider, input) =>
+      request<MaskedProviderConfig>(providerPath(provider), {
+        method: 'PUT',
+        body: JSON.stringify(input),
+      }),
+    setEnabled: (provider, enabled) =>
+      request<MaskedProviderConfig>(providerPath(provider, '/enabled'), {
+        method: 'PUT',
+        body: JSON.stringify({ enabled }),
+      }),
+    setFailoverPolicy: (policy) =>
+      request<MerchantSettingsView>('/settings/failover-policy', {
+        method: 'PUT',
+        body: JSON.stringify({ policy }),
+      }),
+    setPriorities: (ordered) =>
+      request<MerchantSettingsView>('/settings/priorities', {
+        method: 'PUT',
+        body: JSON.stringify({ providers: ordered }),
+      }),
+    verify: (provider, environment) =>
+      request<VerifiedProviderConfig>(
+        providerPath(provider, environment ? `/verify?environment=${environment}` : '/verify'),
+        { method: 'POST' },
+      ),
+    // Deliberately NOT under `/providers/...`: the guide is READ-ONLY public
+    // content, while everything under `/providers` writes or tests a
+    // credential. Hosts gate the two differently (this repo's agent surface
+    // exposes the guide and forbids the writes), which a shared prefix would
+    // make impossible to express.
+    getSetupGuide: (provider) =>
+      request<ProviderSetupGuide>(`/settings/guides/${encodeURIComponent(provider)}`).catch((err: unknown) => {
+        if (err instanceof PaymentsClientError && err.status === 404) return null;
+        throw err;
+      }),
+    beginOAuth: (provider, body) =>
+      request<{ url: string; state: string }>(providerPath(provider, '/oauth/begin'), {
+        method: 'POST',
+        body: JSON.stringify(body),
+      }),
+    disconnectOAuth: (provider) =>
+      request<{ disconnected: boolean }>(providerPath(provider, '/oauth/disconnect'), {
+        method: 'POST',
+      }),
+  };
+}

package/src/components/CheckoutFlow.tsx

@@ -0,0 +1,169 @@
+'use client';
+
+import {
+  Alert,
+  Button,
+  Checkbox,
+  FormControlLabel,
+  Stack,
+  Step,
+  StepLabel,
+  Stepper,
+  TextField,
+  Typography,
+} from '@mui/material';
+import { useState } from 'react';
+
+import type { ClientChargeView, CustomerInfo, Money } from '@12-apps/payments-backend';
+
+import { CheckoutPayment, type CheckoutPaymentProps } from './CheckoutPayment';
+
+/**
+ * The full plug-and-play checkout: the three-step flow of the buyer-facing
+ * screens — Dados (CPF required; name/email/phone optional, "save my data")
+ * → Pagamento (method cards, saved cards, pay button — `CheckoutPayment`)
+ * → Confirmação. The host supplies cart totals, prefilled customer data,
+ * saved cards, and reacts to `onCustomerConfirmed` / `onPaid`.
+ */
+export interface CheckoutFlowProps
+  extends Omit<CheckoutPaymentProps, 'customer' | 'onPaid'> {
+  initialCustomer?: Partial<CustomerInfo>;
+  /** Default state of the "save my data for next time" checkbox. */
+  saveDataDefault?: boolean;
+  /** Fired when the buyer completes step 1 (persist profile if saveData). */
+  onCustomerConfirmed?: (customer: CustomerInfo, saveData: boolean) => void;
+  onPaid?: (charge: ClientChargeView) => void;
+  /** e.g. "1 item" — shown next to the total in the footer. */
+  itemsLabel?: string;
+}
+
+const STEPS = ['Dados', 'Pagamento', 'Confirmação'];
+
+/** CPF: 11 digits (checksum stays server/provider-side; this is UX-level). */
+function cpfDigits(value: string): string {
+  return value.replace(/\D/g, '');
+}
+
+interface CustomerStepProps {
+  amount: Money;
+  itemsLabel?: string;
+  initial: Partial<CustomerInfo>;
+  saveDataDefault: boolean;
+  onContinue: (customer: CustomerInfo, saveData: boolean) => void;
+}
+
+function CustomerStep({ amount, itemsLabel, initial, saveDataDefault, onContinue }: CustomerStepProps) {
+  const [taxId, setTaxId] = useState(initial.taxId ?? '');
+  const [name, setName] = useState(initial.name ?? '');
+  const [email, setEmail] = useState(initial.email ?? '');
+  const [phone, setPhone] = useState(initial.phone ?? '');
+  const [saveData, setSaveData] = useState(saveDataDefault);
+  const [touched, setTouched] = useState(false);
+  const cpfInvalid = cpfDigits(taxId).length !== 11;
+
+  return (
+    <Stack spacing={2}>
+      <Typography variant="body2" color="text.secondary">
+        Informe seu CPF (obrigatório para o pagamento). Nome, e-mail e telefone são opcionais —
+        usados apenas para o comprovante.
+      </Typography>
+      <TextField
+        size="small"
+        label="CPF"
+        required
+        value={taxId}
+        error={touched && cpfInvalid}
+        helperText={touched && cpfInvalid ? 'Informe um CPF com 11 dígitos.' : undefined}
+        onBlur={() => setTouched(true)}
+        onChange={(e) => setTaxId(e.target.value)}
+      />
+      <TextField size="small" label="Nome" value={name} onChange={(e) => setName(e.target.value)} />
+      <TextField size="small" label="E-mail" value={email} onChange={(e) => setEmail(e.target.value)} />
+      <TextField size="small" label="Telefone" value={phone} onChange={(e) => setPhone(e.target.value)} />
+      <FormControlLabel
+        control={<Checkbox checked={saveData} onChange={(_, v) => setSaveData(v)} />}
+        label="Salvar meus dados para a próxima compra"
+      />
+      <Stack direction="row" spacing={2} alignItems="center">
+        <Typography variant="body2" color="text.secondary">
+          {itemsLabel ? `Total · ${itemsLabel} — ` : 'Total: '}
+          {(amount.amountCents / 100).toLocaleString('pt-BR', { style: 'currency', currency: amount.currency })}
+        </Typography>
+        <Button
+          variant="contained"
+          fullWidth
+          disabled={cpfInvalid}
+          onClick={() => onContinue({ name, email, taxId: cpfDigits(taxId), phone }, saveData)}
+        >
+          Continuar
+        </Button>
+      </Stack>
+      <Typography variant="caption" color="text.secondary" textAlign="right">
+        🔒 Pagamento seguro
+      </Typography>
+    </Stack>
+  );
+}
+
+export function CheckoutFlow(props: CheckoutFlowProps) {
+  const {
+    initialCustomer = {},
+    saveDataDefault = true,
+    onCustomerConfirmed,
+    onPaid,
+    itemsLabel,
+    ...payment
+  } = props;
+  const [step, setStep] = useState(0);
+  const [customer, setCustomer] = useState<CustomerInfo | null>(null);
+  const [paid, setPaid] = useState<ClientChargeView | null>(null);
+
+  return (
+    <Stack spacing={3}>
+      <Stepper activeStep={step} alternativeLabel>
+        {STEPS.map((label) => (
+          <Step key={label}>
+            <StepLabel>{label}</StepLabel>
+          </Step>
+        ))}
+      </Stepper>
+
+      {step === 0 ? (
+        <CustomerStep
+          amount={payment.amount}
+          itemsLabel={itemsLabel}
+          initial={initialCustomer}
+          saveDataDefault={saveDataDefault}
+          onContinue={(confirmed, saveData) => {
+            setCustomer(confirmed);
+            onCustomerConfirmed?.(confirmed, saveData);
+            setStep(1);
+          }}
+        />
+      ) : null}
+
+      {step === 1 && customer ? (
+        <Stack spacing={1}>
+          <Button size="small" sx={{ alignSelf: 'flex-start' }} onClick={() => setStep(0)}>
+            ← Voltar
+          </Button>
+          <CheckoutPayment
+            {...payment}
+            customer={customer}
+            onPaid={(charge) => {
+              setPaid(charge);
+              setStep(2);
+              onPaid?.(charge);
+            }}
+          />
+        </Stack>
+      ) : null}
+
+      {step === 2 && paid ? (
+        <Alert severity="success">
+          Pagamento confirmado — {paid.provider} · {paid.providerChargeId}
+        </Alert>
+      ) : null}
+    </Stack>
+  );
+}