@12-apps/payments-frontend 3.3.0 → 3.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.3.0",
+  "version": "3.4.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": {
@@ -17,7 +17,7 @@
     "storybook:build": "storybook build"
   },
   "dependencies": {
-    "@12-apps/payments-backend": "^4.12.0",
+    "@12-apps/payments-backend": "^4.13.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

package/src/activation/use-activation-charge.ts

@@ -30,9 +30,9 @@ import type { ActivationChargeCopy } from './charge-copy';
  * been homologated.
  *
  * So the owner puts their own card through the SAME path a shopper takes — same
- * fields, same validation, same browser-side encryption — for one cent,
- * refunded immediately. Whatever would break for a buyer breaks here, in front
- * of the person who can fix it.
+ * fields, same validation, same browser-side encryption — for the smallest
+ * amount that provider will actually accept, refunded immediately. Whatever
+ * would break for a buyer breaks here, in front of the person who can fix it.
  *
  * The sibling of `useRedirectActivation`, for the other half of the same step:
  * that one is for a provider whose payer leaves for its own page. Both prove
@@ -86,6 +86,20 @@ export interface ActivationCharge {
   cpf: string;
   setCpf: (value: string) => void;
   cpfError: string | undefined;
+  /**
+   * What this charge will COST, in cents — `null` until the endpoint answers.
+   *
+   * Not always one cent, which is the whole reason it is asked for rather than
+   * assumed: at least one provider refuses a one-cent total outright, so its
+   * verification charge is worth more, and the minimum is a fact about that
+   * provider's API rather than a number this package may pick.
+   *
+   * `null` rather than a fallback for the same reason the copy has no
+   * defaults: what to put on a button before the truth arrives is the host's
+   * sentence to write, and a package guessing here would have the screen
+   * promise one amount and charge another.
+   */
+  amountCents: number | null;
   state: ActivationChargeState;
   submit: () => Promise<void>;
   /** Back to the form from a settled state, to try another card. */
@@ -93,20 +107,54 @@ export interface ActivationCharge {
 }
 
 /**
- * The store's own card public key, fetched through the VERIFICATION endpoint.
+ * What the verification endpoint says about the charge BEFORE it is made.
  *
- * Not the checkout one: that reads credentials through the enabled gate, and a
- * provider being verified is by definition still disabled.
+ * Two facts, one request, because the endpoint answers both in one body and
+ * they are needed on the same screen at the same moment. They were two asks
+ * for the same URL — the key read here, the amount read by the host — which is
+ * one request per render pass more than the truth costs, and two places for
+ * the answer to be interpreted differently.
+ *
+ * The endpoint is the VERIFICATION one, not checkout's: that reads credentials
+ * through the enabled gate, and a provider being verified is by definition
+ * still disabled.
  */
-function usePublicKey(verifyChargeUrl: string): string | null {
-  const [publicKey, setPublicKey] = useState<string | null>(null);
+interface ActivationProbe {
+  publicKey: string | null;
+  amountCents: number | null;
+}
+
+/** Before the endpoint has answered, both facts are simply unknown. */
+const UNKNOWN_PROBE: ActivationProbe = { publicKey: null, amountCents: null };
+
+/** The endpoint's `GET` body — every field optional; a host may answer neither. */
+interface ProbeBody {
+  publicKey?: string | null;
+  amountCents?: number | null;
+}
+
+function readProbe(body: ProbeBody | null): ActivationProbe {
+  return {
+    publicKey: body?.publicKey ? body.publicKey : null,
+    amountCents: typeof body?.amountCents === 'number' ? body.amountCents : null,
+  };
+}
+
+function useActivationProbe(verifyChargeUrl: string): ActivationProbe {
+  const [probe, setProbe] = useState<ActivationProbe>(UNKNOWN_PROBE);
 
   useEffect(() => {
     const alive = { current: true };
+    // Forgotten FIRST, before the new answer is asked for. A screen that moves
+    // between providers keeps this hook mounted, and holding the previous
+    // provider's key across the gap would tokenize the card with one vendor's
+    // key and send the blob to another — which arrives as that second
+    // provider's refusal, reading exactly like a bad card.
+    setProbe(UNKNOWN_PROBE);
     void fetch(verifyChargeUrl)
-      .then((res) => (res.ok ? (res.json() as Promise<{ publicKey?: string | null }>) : null))
+      .then((res) => (res.ok ? (res.json() as Promise<ProbeBody>) : null))
       .then((body) => {
-        if (alive.current && body?.publicKey) setPublicKey(body.publicKey);
+        if (alive.current) setProbe(readProbe(body));
       })
       .catch(() => undefined);
     return () => {
@@ -114,7 +162,7 @@ function usePublicKey(verifyChargeUrl: string): string | null {
     };
   }, [verifyChargeUrl]);
 
-  return publicKey;
+  return probe;
 }
 
 /** Local validation — nothing reaches the provider until the card is well-formed. */
@@ -205,7 +253,7 @@ function useCardForm() {
 
 export function useActivationCharge(options: ActivationChargeOptions): ActivationCharge {
   const { verifyChargeUrl, provider, email, onVerified, copy } = options;
-  const publicKey = usePublicKey(verifyChargeUrl);
+  const probe = useActivationProbe(verifyChargeUrl);
   const form = useCardForm();
   const [state, setState] = useState<ActivationChargeState>({ kind: 'idle' });
   const { card, cpf, setFieldErrors, setCpfError, clear } = form;
@@ -222,7 +270,7 @@ export function useActivationCharge(options: ActivationChargeOptions): Activatio
       provider,
       card,
       cpf,
-      publicKey,
+      publicKey: probe.publicKey,
       email,
       copy,
     });
@@ -235,7 +283,7 @@ export function useActivationCharge(options: ActivationChargeOptions): Activatio
   }, [
     card,
     cpf,
-    publicKey,
+    probe.publicKey,
     verifyChargeUrl,
     provider,
     email,
@@ -260,6 +308,7 @@ export function useActivationCharge(options: ActivationChargeOptions): Activatio
     cpf: form.cpf,
     setCpf: form.setCpf,
     cpfError: form.cpfError,
+    amountCents: probe.amountCents,
     state,
     submit,
     reset,

package/src/components/connect-preparer.ts

@@ -0,0 +1,97 @@
+import type { PaymentEnvironment } from '@12-apps/payments-backend';
+
+import type { PrepareConnect } from './ProviderPanel';
+
+/**
+ * The START of the connect round trip (FUT-763) — the sibling of
+ * `takeConnectReturn`, which owns its end.
+ *
+ * Before an owner is sent to the provider's site, a CSRF state is minted on
+ * the host's server, pinned to an httpOnly cookie there and compared on the
+ * way back. The browser only relays it, so a forged connect cannot start here
+ * — and the environment travels sealed into that same cookie, so a SANDBOX
+ * choice cannot come back as a PRODUCTION grant.
+ *
+ * The ROUTE that mints it is the host's; everything else about the exchange is
+ * this package's, and was being restated by every host that implemented
+ * `prepareConnect` by hand: the method, the content type, what a failure is,
+ * and the shape of the answer. That last one is the reason this exists rather
+ * than a copied snippet — see below.
+ */
+
+/** What the host's prepare endpoint answers. */
+interface PreparedConnect {
+  state: string;
+  redirectUri: string;
+  environment?: PaymentEnvironment;
+}
+
+export interface ConnectPreparerOptions {
+  /**
+   * The host's OAuth-prepare endpoint for one provider and environment.
+   *
+   * A builder rather than a whole URL because the provider is not fixed for
+   * this screen the way it is for a verification charge — the owner picks one,
+   * and the route shape still belongs to the host.
+   */
+  prepareUrl: (provider: string, environment: PaymentEnvironment) => string;
+  /**
+   * What the owner is told when no connect could be started.
+   *
+   * Required and with no default, like every other sentence this package
+   * needs: a fallback compiled in here is how one product's voice reaches
+   * every adopter.
+   */
+  mintFailed: string;
+}
+
+/** The two environments, for checking what came back is one of them. */
+const ENVIRONMENTS: readonly PaymentEnvironment[] = ['SANDBOX', 'PRODUCTION'];
+
+/**
+ * Refuse an answer that cannot start a connect.
+ *
+ * A hand-written preparer casts the body and hands it straight on, so a `200`
+ * carrying the wrong shape sends the owner to the provider with
+ * `state=undefined` in the URL. That does not fail here — it fails on the way
+ * BACK, as `state_mismatch`, two steps and one provider site later, and reads
+ * as "the connection expired" to someone whose connection never started.
+ *
+ * The mint either produced a usable state and a place to send them, or it
+ * failed. There is no third answer worth acting on.
+ */
+function usable(body: unknown): body is PreparedConnect {
+  if (typeof body !== 'object' || body === null) return false;
+  const candidate = body as Partial<PreparedConnect>;
+  return typeof candidate.state === 'string' && candidate.state.length > 0
+    && typeof candidate.redirectUri === 'string' && candidate.redirectUri.length > 0;
+}
+
+/**
+ * Build the `prepareConnect` a host hands to `PaymentProviderSettings`.
+ *
+ * The environment is echoed back only when the answer names one this package
+ * knows. The SERVER is the authority on it — it is what sealed the cookie — so
+ * an unrecognised value is dropped rather than argued with, and the caller
+ * keeps the environment it asked for.
+ */
+export function createConnectPreparer(options: ConnectPreparerOptions): PrepareConnect {
+  return async (provider, environment) => {
+    const response = await fetch(options.prepareUrl(provider, environment), {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+    });
+    if (!response.ok) throw new Error(options.mintFailed);
+
+    const body: unknown = await response.json().catch(() => null);
+    if (!usable(body)) throw new Error(options.mintFailed);
+
+    return {
+      state: body.state,
+      redirectUri: body.redirectUri,
+      environment: ENVIRONMENTS.includes(body.environment as PaymentEnvironment)
+        ? body.environment
+        : undefined,
+    };
+  };
+}

package/src/components/connect-return.ts

@@ -0,0 +1,113 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+/**
+ * What the OAuth connect callback redirected back with — read once, then
+ * erased from the address bar (FUT-763).
+ *
+ * The owner leaves for the provider's site to authorize us and comes back to a
+ * URL carrying the verdict. That round trip is the package's: `OAuthPanel`
+ * starts it, `PaymentProviderSettings` already reads `?connected=` as the raw
+ * provider name to reopen the right panel, and the codes below are the ones a
+ * connect can fail with. A host re-deriving any of it is re-deriving this
+ * package's own contract from the outside.
+ *
+ * What is NOT here is the sentence. `errorCode` comes back as a CODE precisely
+ * so the words stay the host's, which is the same rule the activation copy
+ * follows — a fallback string compiled in here is how one product's voice
+ * reaches every adopter.
+ */
+
+/**
+ * How a connect can fail, as the callback spells it.
+ *
+ * A union rather than a loose string because these five are shared between a
+ * host's callback ROUTE, which emits them, and its copy map, which renders
+ * them — two files that today agree by luck. Typed, a host's
+ * `Record<ConnectErrorCode, string>` is checked for exhaustiveness, and a
+ * provider failure mode nobody wrote a sentence for stops compiling.
+ */
+export type ConnectErrorCode =
+  /** The owner declined on the provider's site. Nothing changed. */
+  | 'access_denied'
+  /** The CSRF state did not match — expired, or started in another tab. */
+  | 'state_mismatch'
+  /** The provider came back without an authorization code. */
+  | 'missing_code'
+  /** The callback did not say which provider it was for. */
+  | 'missing_provider'
+  /** The code could not be exchanged for a grant. */
+  | 'exchange_failed';
+
+export interface ConnectReturn {
+  /**
+   * The provider that was just connected, as the callback spells it — which is
+   * the RAW name, not the URL slug. `PaymentProviderSettings` resolves either.
+   */
+  connected: string | null;
+  /**
+   * Why it failed, as a code — `null` when nothing failed.
+   *
+   * Deliberately widened to `string`: a code outside {@link ConnectErrorCode}
+   * is passed through rather than dropped, because a host that has taught its
+   * own callback a new failure is not wrong — it just has a sentence this
+   * package does not know about. The union is what its copy map is keyed by;
+   * this is what its callback actually said.
+   */
+  errorCode: string | null;
+}
+
+const NOTHING: ConnectReturn = { connected: null, errorCode: null };
+
+/**
+ * The params the connect callback owns. Erased together, and ONLY these — a
+ * host's own query string survives the scrub.
+ */
+const CONNECT_PARAMS = ['connected', 'connectError', 'provider'] as const;
+
+/**
+ * Take the callback's verdict out of the address bar.
+ *
+ * Erasing is the point, not tidiness: the query string is the only place this
+ * state lives, so leaving it there means a reload re-announces a connection
+ * that already happened — and, worse, re-announces a FAILURE the owner has
+ * since fixed.
+ *
+ * Take-once by construction: the second call finds nothing, because the first
+ * removed it. Callers hold the result.
+ */
+export function takeConnectReturn(): ConnectReturn {
+  // Server-rendered, or a test with no DOM: there is no address bar to read.
+  if (typeof window === 'undefined') return NOTHING;
+
+  const params = new URLSearchParams(window.location.search);
+  const connected = params.get('connected');
+  const errorCode = params.get('connectError');
+  if (!connected && !errorCode) return NOTHING;
+
+  for (const key of CONNECT_PARAMS) params.delete(key);
+  const query = params.toString();
+  window.history.replaceState({}, '', `${window.location.pathname}${query ? `?${query}` : ''}`);
+
+  return { connected, errorCode };
+}
+
+/**
+ * {@link takeConnectReturn} for a screen: taken after mount, held across every
+ * later render.
+ *
+ * Only ever SETS when something was found, which is what keeps it correct
+ * under a StrictMode double-mount: the second run finds an already-scrubbed
+ * URL, and must not overwrite the verdict the first one caught.
+ */
+export function useConnectReturn(): ConnectReturn {
+  const [taken, setTaken] = useState<ConnectReturn>(NOTHING);
+
+  useEffect(() => {
+    const outcome = takeConnectReturn();
+    if (outcome.connected || outcome.errorCode) setTaken(outcome);
+  }, []);
+
+  return taken;
+}

package/src/index.ts

@@ -209,6 +209,15 @@ export {
   type SetupGuideSectionProps,
 } from './components/SetupGuideSection';
 export { ProviderStatusBar, statusBadge } from './components/ProviderStatusBar';
+// The START of the connect round trip (FUT-763): the `prepareConnect` a host
+// hands to the settings screen, built from its own prepare route. The route is
+// the host's; the exchange — method, shape, and what counts as a failure — is
+// this package's, and a hand-written one casts the answer instead of checking
+// it.
+export {
+  createConnectPreparer,
+  type ConnectPreparerOptions,
+} from './components/connect-preparer';
 export {
   PaymentProviderSettings,
   type PaymentProviderSettingsProps,
@@ -243,6 +252,19 @@ export {
  */
 export type { PaymentEnvironment } from '@12-apps/payments-backend';
 
+// ---------------------------------------------------------------------------
+// The connect ROUND TRIP's other end (FUT-763): what the OAuth callback
+// redirected back with, taken out of the address bar once. The codes are a
+// union so a host's copy map is exhaustiveness-checked; the sentences stay the
+// host's, as everywhere else in this package.
+// ---------------------------------------------------------------------------
+export {
+  takeConnectReturn,
+  useConnectReturn,
+  type ConnectErrorCode,
+  type ConnectReturn,
+} from './components/connect-return';
+
 // ---------------------------------------------------------------------------
 // The ACTIVATION CHARGE (FUT-463, packaged by FUT-763) — proving a connection
 // can charge, for a provider whose payer pays HERE.