@12-apps/payments-frontend 1.0.0

package/src/components/rich-text.tsx

@@ -0,0 +1,27 @@
+'use client';
+
+import { Fragment, type ReactNode } from 'react';
+
+/**
+ * `**bold**`, and nothing else.
+ *
+ * Adapters author their walkthrough as plain strings — the content crosses an
+ * HTTP boundary, so it cannot carry markup — but the emphasis is load-bearing
+ * copy rather than decoration: `alterar` and `qual conta` are the words that
+ * say what the sentence is warning ABOUT. Shouting them in capitals was the
+ * workaround, and it reads as a raised voice while being harder to scan.
+ *
+ * Deliberately not a markdown library. Two asterisks is the entire grammar, an
+ * unmatched pair renders verbatim, and nothing here can emit HTML — the text is
+ * provider-authored, and a renderer that interpreted more would be an injection
+ * surface on a payments screen.
+ */
+export function richText(text: string): ReactNode {
+  return text.split(/\*\*(.+?)\*\*/g).map((chunk, index) =>
+    index % 2 === 1 ? (
+      <strong key={index}>{chunk}</strong>
+    ) : (
+      <Fragment key={index}>{chunk}</Fragment>
+    ),
+  );
+}

package/src/components/settings-state.ts

@@ -0,0 +1,211 @@
+'use client';
+
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import type {
+  MaskedProviderConfig,
+  MerchantSettingsView,
+  ProviderDescriptor,
+  ProviderSetupGuide as Guide,
+} from '@12-apps/payments-backend';
+
+import type { PaymentsSettingsClient } from '../client';
+import { useCheckoutAck } from './checkout-ack';
+import { CHECKOUT_CONFIRM_ACTION } from './SetupGuideSection';
+
+/**
+ * Everything the settings screen KNOWS, separated from what it draws.
+ *
+ * The component had accumulated five hooks and three derivations above its
+ * early returns — the position where a React component is least readable,
+ * because none of it can be moved and all of it has to be understood before
+ * the first line of markup. Split out, that file is about layout and this one
+ * is about state.
+ */
+
+/**
+ * Fetch the selected provider's walkthrough.
+ *
+ * `progressKey` exists because a guide is no longer a constant per provider:
+ * the server decides which step to show from what the store has already done,
+ * so the walkthrough goes stale the moment the connection changes. Keyed on
+ * the provider alone, saving a credential left the owner reading the step they
+ * had just completed — the screen said "informe sua InfiniteTag" underneath
+ * the tag they had saved a second earlier.
+ *
+ * A derived STRING rather than the config object: the settings view is
+ * replaced on every reload, so an object dependency would refetch the guide
+ * after any action at all, including ones that cannot change it.
+ */
+export function useSetupGuide(
+  client: PaymentsSettingsClient,
+  provider: string | null,
+  progressKey: string,
+): { guide: Guide | null; loaded: boolean } {
+  const [state, setState] = useState<{ guide: Guide | null; loaded: boolean }>({
+    guide: null,
+    loaded: false,
+  });
+  useEffect(() => {
+    setState({ guide: null, loaded: false });
+    if (!provider) return;
+    client
+      .getSetupGuide(provider)
+      // `loaded` is not cosmetic. "No guide yet" and "this provider ships no
+      // guide" are the same `null`, and the difference decides whether a REAL
+      // payment button is on screen — so for one frame after every load, a
+      // store mid-setup was offered the charge before anything knew which step
+      // it was on.
+      .then((guide) => setState({ guide, loaded: true }))
+      .catch(() => setState({ guide: null, loaded: true }));
+  }, [client, provider, progressKey]);
+  return state;
+}
+
+/**
+ * The facts a guide branches on, flattened to a comparable string: which
+ * credential fields are filled in the active environment, whether the probe
+ * passed, and whether a charge has proved it.
+ */
+export function progressKeyOf(config: MaskedProviderConfig | null): string {
+  if (!config) return 'none';
+  const configured = Object.entries(config.environments[config.environment] ?? {})
+    .filter(([, field]) => field.configured)
+    .map(([key]) => key)
+    .sort()
+    .join(',');
+  return `${config.environment}|${config.status}|${config.chargeVerifiedAt ?? ''}|${configured}`;
+}
+
+/**
+ * Is the walkthrough still waiting on the owner to confirm something?
+ *
+ * The one input to `blocked`. It lives with the guide rather than inside the
+ * activation step because the guide is what knows a confirmable section is
+ * still on screen; the step only knows about charges.
+ */
+export function guideAwaitsConfirmation(
+  guide: Guide | null,
+  confirmed: boolean,
+  loaded: boolean,
+): boolean {
+  if (confirmed) return false;
+  // Withheld until we know. Erring towards blocked costs at most a moment's
+  // wait on a button; erring the other way puts "Pagar e ativar" in front of an
+  // owner whose setup we have not read yet, and that one is paid for in money.
+  if (!loaded) return true;
+  if (!guide) return false;
+  return guide.sections.some((section) =>
+    section.steps.some((step) => step.action === CHECKOUT_CONFIRM_ACTION),
+  );
+}
+
+/**
+ * Has the store settled the setup step that only it can see?
+ *
+ * Two sources, in order of authority. A charge that LANDED proves the
+ * provider-side switch is on far better than any answer could, so a store that
+ * reconnects from a machine holding no stored confirmation is never sent back
+ * through step 2. Failing that, the owner's own word — scoped to this client's
+ * tenant-specific base URL, so an owner who runs two stores answers for each.
+ */
+export function useSetupConfirmation(
+  client: PaymentsSettingsClient,
+  active: ProviderDescriptor | null,
+  config: MaskedProviderConfig | null,
+): { confirmed: boolean; confirm: () => void; withdraw: () => void } {
+  const ack = useCheckoutAck(client.baseUrl, active ? active.name : null);
+  const proven = Boolean(config?.chargeVerifiedAt);
+  return { ...ack, confirmed: proven ? true : ack.confirmed };
+}
+
+/**
+ * The provider the owner has open, and the config row that belongs to it.
+ *
+ * One hook rather than two `useMemo`s inline, because both have to be resolved
+ * BEFORE the loading and error returns — the guide hook depends on them — and
+ * that is exactly the position where a component accumulates the branches that
+ * make it unreadable.
+ */
+export function useOpenProvider(
+  view: MerchantSettingsView | null,
+  selected: string | null,
+): { active: ProviderDescriptor | null; activeConfig: MaskedProviderConfig | null } {
+  // Nothing is open until the owner picks: the landing view is the list of
+  // providers, not one arbitrary provider's configuration.
+  const active = useMemo(() => {
+    if (!view || !selected) return null;
+    return view.providers.find((p) => p.name === selected) ?? null;
+  }, [view, selected]);
+
+  // A stored connection is what makes the manual walkthrough steps redundant —
+  // and, since the guide branches on it, what decides which step is shown.
+  const activeConfig = useMemo(() => {
+    if (!view || !active) return null;
+    return view.configs.find((c) => c.provider === active.name) ?? null;
+  }, [view, active]);
+
+  return { active, activeConfig };
+}
+
+export function useSettingsState(client: PaymentsSettingsClient) {
+  const [view, setView] = useState<MerchantSettingsView | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const reload = useCallback(async () => {
+    try {
+      setView(await client.getSettings());
+      setError(null);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    }
+  }, [client]);
+  useEffect(() => {
+    void reload();
+  }, [reload]);
+  return { view, error, reload };
+}
+
+/**
+ * Which provider is open, and the once-only handover from the host.
+ *
+ * Seeding `useState` with `initialProvider` is not enough: the host reads the
+ * provider from the OAuth callback's query string in an EFFECT, so on first
+ * render it is still null — and `useState` keeps that null forever. The owner
+ * therefore landed on the list after authorizing, which is the bug this fixed
+ * twice.
+ *
+ * Applied ONCE. The host holds the outcome for the page's lifetime, so
+ * re-applying it would make "Voltar aos provedores" bounce straight back into
+ * the provider and trap the owner on one screen.
+ *
+ * None of that applies when the host is CONTROLLING the selection: there is no
+ * handover to make, because the host's value already is the answer on every
+ * render. `controlled === undefined` is the only test for that — `null` is a
+ * controlled host legitimately saying "the list", and treating it as absent
+ * would strand the owner in whichever provider they last opened.
+ */
+export function useSelectedProvider(
+  initialProvider: string | null,
+  controlled: string | null | undefined,
+  onProviderChange: ((provider: string | null) => void) | undefined,
+) {
+  const isControlled = controlled !== undefined;
+  const [internal, setInternal] = useState<string | null>(initialProvider);
+  const honoredInitial = useRef(false);
+
+  useEffect(() => {
+    if (isControlled || honoredInitial.current || !initialProvider) return;
+    honoredInitial.current = true;
+    setInternal(initialProvider);
+  }, [initialProvider, isControlled]);
+
+  const setSelected = useCallback(
+    (provider: string | null) => {
+      if (!isControlled) setInternal(provider);
+      onProviderChange?.(provider);
+    },
+    [isControlled, onProviderChange],
+  );
+
+  return { selected: isControlled ? controlled : internal, setSelected };
+}

package/src/context.tsx

@@ -0,0 +1,144 @@
+'use client';
+
+import {
+  createContext,
+  useCallback,
+  useContext,
+  useEffect,
+  useRef,
+  useState,
+  type ReactNode,
+} from 'react';
+
+import type { ClientChargeView } from '@12-apps/payments-backend';
+
+import { isSettled, type ClientChargeRequest, type PaymentsClient } from './client';
+
+/**
+ * Headless React bindings — state and flow only, ZERO UI. Visual checkout
+ * components belong to each host's design system (`@12-apps/ui` here); these
+ * hooks make every such UI provider-agnostic: the same `useCreateCharge` +
+ * `useChargeStatus` pair drives a PIX QR screen, a card form, or an
+ * InfinitePay redirect, switching on `charge.method` / `hostedCheckoutUrl`.
+ */
+
+const PaymentsContext = createContext<PaymentsClient | null>(null);
+
+export interface PaymentsProviderProps {
+  client: PaymentsClient;
+  children: ReactNode;
+}
+
+export function PaymentsProvider({ client, children }: PaymentsProviderProps): ReactNode {
+  return <PaymentsContext.Provider value={client}>{children}</PaymentsContext.Provider>;
+}
+
+export function usePaymentsClient(): PaymentsClient {
+  const client = useContext(PaymentsContext);
+  if (!client) {
+    throw new Error('usePaymentsClient must be used inside a <PaymentsProvider>');
+  }
+  return client;
+}
+
+export interface CreateChargeState {
+  charge: ClientChargeView | null;
+  loading: boolean;
+  error: Error | null;
+  create(request: ClientChargeRequest): Promise<ClientChargeView | null>;
+  reset(): void;
+}
+
+/** Imperative charge creation with loading/error state. */
+export function useCreateCharge(): CreateChargeState {
+  const client = usePaymentsClient();
+  const [charge, setCharge] = useState<ClientChargeView | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const create = useCallback(
+    async (request: ClientChargeRequest) => {
+      setLoading(true);
+      setError(null);
+      try {
+        const created = await client.createCharge(request);
+        setCharge(created);
+        return created;
+      } catch (err) {
+        setError(err instanceof Error ? err : new Error(String(err)));
+        return null;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [client],
+  );
+
+  const reset = useCallback(() => {
+    setCharge(null);
+    setError(null);
+  }, []);
+
+  return { charge, loading, error, create, reset };
+}
+
+export interface ChargeStatusOptions {
+  /** Poll interval; default 4000ms. Polling stops on settled states. */
+  intervalMs?: number;
+}
+
+export interface ChargeStatusState {
+  charge: ClientChargeView | null;
+  /** True once the charge reached a state that will not change by waiting. */
+  settled: boolean;
+  error: Error | null;
+}
+
+/** Identifies one charge to poll: which provider, which provider-side id. */
+export interface ChargeRef {
+  provider: string;
+  providerChargeId: string;
+}
+
+/**
+ * Polls the host for a charge until it settles (webhooks update the server;
+ * the browser polls the server — never the provider). Pass `null` to idle.
+ */
+export function useChargeStatus(
+  ref: ChargeRef | null,
+  options: ChargeStatusOptions = {},
+): ChargeStatusState {
+  const client = usePaymentsClient();
+  const intervalMs = options.intervalMs ?? 4000;
+  const [charge, setCharge] = useState<ClientChargeView | null>(null);
+  const [error, setError] = useState<Error | null>(null);
+  const settled = charge !== null && isSettled(charge.status);
+  const settledRef = useRef(settled);
+  settledRef.current = settled;
+  const provider = ref?.provider ?? null;
+  const providerChargeId = ref?.providerChargeId ?? null;
+
+  useEffect(() => {
+    if (!provider || !providerChargeId) return undefined;
+    let disposed = false;
+
+    const tick = async (): Promise<void> => {
+      if (disposed || settledRef.current) return;
+      try {
+        const fresh = await client.getCharge(provider, providerChargeId);
+        if (!disposed) setCharge(fresh);
+      } catch (err) {
+        if (!disposed) setError(err instanceof Error ? err : new Error(String(err)));
+      }
+    };
+
+    void tick();
+    const timer = setInterval(() => void tick(), intervalMs);
+    return () => {
+      disposed = true;
+      clearInterval(timer);
+    };
+  }, [client, provider, providerChargeId, intervalMs]);
+
+  return { charge, settled, error };
+}

package/src/index.ts

@@ -0,0 +1,69 @@
+/**
+ * `@12-apps/payments-frontend` — the browser half of the payments platform.
+ *
+ * Plug-and-play MUI components for the two payment surfaces (per-provider
+ * settings page, checkout payment step), plus the headless hooks and fetch
+ * clients they are built on for hosts that want their own pixels. Imports
+ * only TYPES from `@12-apps/payments-backend`; talks exclusively to the host's
+ * mounted payments HTTP surface.
+ */
+export {
+  createPaymentsClient,
+  createPaymentsSettingsClient,
+  isSettled,
+  PaymentsClientError,
+  type ClientChargeRequest,
+  type ClientPaymentsConfig,
+  type PaymentsClient,
+  type PaymentsClientOptions,
+  type PaymentsSettingsClient,
+} from './client';
+
+export {
+  PaymentsProvider,
+  useChargeStatus,
+  useCreateCharge,
+  usePaymentsClient,
+  type ChargeRef,
+  type ChargeStatusOptions,
+  type ChargeStatusState,
+  type CreateChargeState,
+  type PaymentsProviderProps,
+} from './context';
+
+export {
+  CheckoutPayment,
+  type CardFormValues,
+  type CheckoutPaymentProps,
+  type SavedCardOption,
+} from './components/CheckoutPayment';
+export { CheckoutFlow, type CheckoutFlowProps } from './components/CheckoutFlow';
+export {
+  ProviderConnection,
+  type ProviderConnectionProps,
+} from './components/ProviderConnection';
+export {
+  ProviderPriorityList,
+  type ProviderPriorityListProps,
+} from './components/ProviderPriorityList';
+export {
+  ProviderSetupGuide,
+  type ProviderSetupGuideProps,
+} from './components/ProviderSetupGuide';
+export {
+  CHECKOUT_CONFIRM_ACTION,
+  SetupGuideSection,
+  type SetupGuideSectionProps,
+} from './components/SetupGuideSection';
+export { ProviderStatusBar, statusBadge } from './components/ProviderStatusBar';
+export {
+  PaymentProviderSettings,
+  type PaymentProviderSettingsProps,
+} from './components/PaymentProviderSettings';
+
+/**
+ * Re-exported because it appears in the `prepareConnect` prop a host must
+ * implement: without it the host could not type its own callback without
+ * taking a direct dependency on the backend package.
+ */
+export type { PaymentEnvironment } from '@12-apps/payments-backend';