@12-apps/payments-frontend 1.0.0 → 1.2.0

package/src/components/checkout/use-card-checkout.ts

@@ -0,0 +1,346 @@
+import { useEffect, useState } from "react";
+
+import {
+  NEW_CARD,
+  detectBrand,
+  onlyDigits,
+  tokenizeForCheckout,
+  tokenizerFor,
+  validateCardNumber,
+  validateCvv,
+  validateExpiry,
+  validateHolder,
+  type CardBrand,
+  type CardDetails,
+  type CardFieldErrors,
+  type CardTokenizationConfig,
+  type CardToken,
+  type SavedCard,
+} from "../../card";
+import { ok, type Result } from "../../result";
+
+import {
+  chargeCard,
+  listSavedCards,
+  refreshCardPublicKey,
+} from "./client";
+import { rememberHostedOrder } from "./hosted-return";
+import type {
+  BuyerInfo,
+  CheckoutOrder,
+  OrderStatus,
+  SavedCardMeta,
+} from "./types";
+import { usePaymentPolling } from "./use-payment-polling";
+
+const EMPTY_CARD: CardDetails = { number: "", holder: "", expiry: "", cvv: "" };
+
+/**
+ * Tokenize a new card in the ACTIVE provider's protocol (FUT-697), self-healing
+ * a rotated public key (FUT-174): the card has already passed local validation,
+ * so a real-key encryption failure most likely means the store's key rotated.
+ * Refresh the store's key once and retry before surfacing the error;
+ * `onKeyRefreshed` caches the new key for the session. The refresh is scoped to
+ * the buyer's OWN `orderId` (the route derives the store from it server-side),
+ * never a client-supplied store id — and only PagBank can mint a key on demand,
+ * so the self-heal is gated on its scheme.
+ */
+async function tokenizeNewCard(
+  card: CardDetails,
+  config: CardTokenizationConfig,
+  orderId: string,
+  onKeyRefreshed: (key: string) => void,
+): Promise<Result<CardToken>> {
+  const first = await tokenizeForCheckout(card, config);
+  if (first.ok || !config.publicKey) return first;
+  if (config.provider === null || tokenizerFor(config.provider) !== "pagbank-sdk") return first;
+
+  const refreshed = await refreshCardPublicKey({ orderId });
+  if (refreshed.ok && refreshed.data.publicKey && refreshed.data.publicKey !== config.publicKey) {
+    onKeyRefreshed(refreshed.data.publicKey);
+    return tokenizeForCheckout(card, { ...config, publicKey: refreshed.data.publicKey });
+  }
+  return first;
+}
+
+/** Non-sensitive display metadata for saving a card (the PAN never leaves the form). */
+function toCardMeta(card: CardDetails, token: CardToken): SavedCardMeta {
+  const [mm = "", yy = ""] = card.expiry.split("/");
+  return {
+    brand: token.brand,
+    last4: token.last4,
+    expMonth: Number(mm),
+    expYear: 2000 + Number(yy),
+    holder: card.holder.trim(),
+  };
+}
+
+/** The charge token for a new card (tokenize + self-heal), plus optional save-meta. */
+async function resolveNewCardToken(
+  card: CardDetails,
+  config: CardTokenizationConfig,
+  orderId: string,
+  onKeyRefreshed: (key: string) => void,
+  saveCard: boolean,
+): Promise<Result<{ token: string; cardMeta?: SavedCardMeta }>> {
+  const tokenized = await tokenizeNewCard(card, config, orderId, onKeyRefreshed);
+  if (!tokenized.ok) return tokenized;
+  return ok({
+    token: tokenized.data.token,
+    ...(saveCard ? { cardMeta: toCardMeta(card, tokenized.data) } : {}),
+  });
+}
+
+/**
+ * Saved-card list + current selection, loaded once on mount — scoped to the
+ * current store (FUT-697), so only cards the store's active provider can
+ * actually charge are offered. The slug arrives as an argument (the host's
+ * routing owns it); absent, the list is unscoped, exactly as before FUT-697.
+ */
+function useSavedCards(tenantSlug: string | undefined): {
+  savedCards: SavedCard[];
+  selection: string;
+  setSelection: (id: string) => void;
+} {
+  const [savedCards, setSavedCards] = useState<SavedCard[]>([]);
+  const [selection, setSelection] = useState<string>(NEW_CARD);
+
+  useEffect(() => {
+    let active = true;
+    void listSavedCards(tenantSlug).then((cards) => {
+      if (!active) return;
+      setSavedCards(cards);
+      const first = cards[0];
+      if (first) setSelection(first.id);
+    });
+    return () => {
+      active = false;
+    };
+  }, [tenantSlug]);
+
+  return { savedCards, selection, setSelection };
+}
+
+/**
+ * The store's card public key for this order. The checkout config resolved the
+ * initial key server-side (`GET /api/checkout/config`, FUT-697); the SPA
+ * fetches through the order-scoped refresh route only when the ACTIVE provider
+ * is PagBank — the sole provider that can mint a key on demand — and the
+ * config arrived without one. A `null` key never means "mock": stub permission
+ * travels separately as `mockTokenization`.
+ */
+function useCardPublicKey(
+  orderId: string,
+  config: CardTokenizationConfig,
+): {
+  publicKey: string | null;
+  setPublicKey: (key: string) => void;
+} {
+  const [publicKey, setPublicKey] = useState<string | null>(config.publicKey);
+  const refreshable =
+    config.provider !== null && tokenizerFor(config.provider) === "pagbank-sdk";
+
+  useEffect(() => {
+    if (config.publicKey !== null || !refreshable) return undefined;
+    let active = true;
+    void refreshCardPublicKey({ orderId }).then((result) => {
+      if (active && result.ok && result.data.publicKey) setPublicKey(result.data.publicKey);
+    });
+    return () => {
+      active = false;
+    };
+  }, [orderId, config.publicKey, refreshable]);
+
+  return { publicKey, setPublicKey };
+}
+
+/** Everything the card view renders — all checkout state + the submit handler. */
+interface CardCheckout {
+  savedCards: SavedCard[];
+  selection: string;
+  setSelection: (id: string) => void;
+  usingNewCard: boolean;
+  card: CardDetails;
+  setCard: React.Dispatch<React.SetStateAction<CardDetails>>;
+  fieldErrors: CardFieldErrors;
+  setFieldErrors: React.Dispatch<React.SetStateAction<CardFieldErrors>>;
+  brand: CardBrand;
+  saveCard: boolean;
+  setSaveCard: (checked: boolean) => void;
+  error: string | null;
+  submitting: boolean;
+  submitted: boolean;
+  pollError: string | null;
+  /** The healthy-poll cap elapsed while still AWAITING (FUT-191 bounded wait). */
+  pollTimedOut: boolean;
+  handlePay: () => Promise<void>;
+}
+
+/** The form inputs the submit handler reads (owned by {@link useCardCheckout}). */
+interface CardFormState {
+  card: CardDetails;
+  usingNewCard: boolean;
+  selection: string;
+  saveCard: boolean;
+  validate: () => CardFieldErrors;
+  setFieldErrors: React.Dispatch<React.SetStateAction<CardFieldErrors>>;
+}
+
+/** The submit slice of {@link useCardCheckout}. */
+type CardSubmit = Pick<
+  CardCheckout,
+  "submitting" | "submitted" | "error" | "pollError" | "pollTimedOut" | "handlePay"
+>;
+
+/**
+ * Healthy-poll cap for the card AWAITING wait: 36 polls ≈ 90 s at the 2500 ms
+ * default interval (FUT-191). PIX passes no cap and keeps today's behavior.
+ */
+const CARD_AWAITING_POLL_CAP = 36;
+
+/**
+ * Hand the buyer to the provider's authentication page (FUT-698) — Stripe's
+ * redirect-based 3-D Secure. Park the order and navigate, the same trip a
+ * redirect provider's link takes (FUT-556): the return lands back on this
+ * checkout route, where the hosted-resume machinery polls the parked order.
+ */
+function handOverToChallenge(order: CheckoutOrder, url: string): void {
+  rememberHostedOrder(order);
+  window.location.assign(url);
+}
+
+/**
+ * The submit state machine (FUT-58): validate → tokenize (self-heal) → charge →
+ * poll for the async confirmation, bubbling the terminal status up via
+ * {@link onResolved}.
+ */
+function useCardSubmit(
+  order: CheckoutOrder,
+  buyer: BuyerInfo,
+  providerConfig: CardTokenizationConfig,
+  onResolved: (status: OrderStatus) => void,
+  pollIntervalMs: number,
+  form: CardFormState,
+): CardSubmit {
+  const [submitting, setSubmitting] = useState(false);
+  const [submitted, setSubmitted] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  // The active key: resolved by the checkout config, overridden by the
+  // rotated-key self-heal for the rest of the session.
+  const { publicKey, setPublicKey } = useCardPublicKey(order.orderId, providerConfig);
+
+  const { status, error: pollError, timedOut: pollTimedOut } = usePaymentPolling(order.orderId, {
+    enabled: submitted,
+    intervalMs: pollIntervalMs,
+    maxHealthyPolls: CARD_AWAITING_POLL_CAP,
+  });
+
+  useEffect(() => {
+    if (status && status !== "AWAITING_PAYMENT") onResolved(status);
+  }, [status, onResolved]);
+
+  async function resolveToken(): Promise<Result<{ token: string; cardMeta?: SavedCardMeta }>> {
+    if (!form.usingNewCard) return ok({ token: form.selection }); // reuse saved card's token id
+    return resolveNewCardToken(
+      form.card,
+      { ...providerConfig, publicKey },
+      order.orderId,
+      setPublicKey,
+      form.saveCard,
+    );
+  }
+
+  const handlePay = async (): Promise<void> => {
+    setError(null);
+    if (form.usingNewCard) {
+      const errors = form.validate();
+      form.setFieldErrors(errors);
+      if (Object.values(errors).some(Boolean)) return; // block submit until valid
+    }
+    setSubmitting(true);
+
+    const resolved = await resolveToken();
+    if (!resolved.ok) {
+      setError(resolved.error);
+      setSubmitting(false);
+      return;
+    }
+
+    const charged = await chargeCard({
+      orderId: order.orderId,
+      token: resolved.data.token,
+      saveCard: form.usingNewCard && form.saveCard,
+      cardMeta: resolved.data.cardMeta,
+      taxId: buyer.taxId,
+    });
+    if (!charged.ok) {
+      setError(charged.error); // transport/validation problem — stay on the form
+      setSubmitting(false);
+      return;
+    }
+    // 3-D Secure (FUT-698): the buyer must finish on the provider's page.
+    // `submitting` stays true on purpose — the tab is navigating away.
+    if (charged.data.hostedCheckoutUrl) {
+      return handOverToChallenge(order, charged.data.hostedCheckoutUrl);
+    }
+    // A business outcome (e.g. declined → FAILED) shows the status screen;
+    // an accepted charge begins polling for the async confirmation.
+    if (charged.data.status !== "AWAITING_PAYMENT") onResolved(charged.data.status);
+    else setSubmitted(true);
+  };
+
+  return { submitting, submitted, error, pollError, pollTimedOut, handlePay };
+}
+
+/**
+ * All card-payment state + the async submit handler (FUT-58), extracted so the
+ * card view stays presentational.
+ */
+export function useCardCheckout(
+  order: CheckoutOrder,
+  buyer: BuyerInfo,
+  providerConfig: CardTokenizationConfig,
+  onResolved: (status: OrderStatus) => void,
+  pollIntervalMs: number,
+  /** The store whose saved cards may be offered (host routing owns the slug). */
+  tenantSlug?: string,
+): CardCheckout {
+  const { savedCards, selection, setSelection } = useSavedCards(tenantSlug);
+  const [card, setCard] = useState<CardDetails>(EMPTY_CARD);
+  const [fieldErrors, setFieldErrors] = useState<CardFieldErrors>({});
+  const [saveCard, setSaveCard] = useState(false);
+
+  const brand = detectBrand(onlyDigits(card.number));
+  const usingNewCard = selection === NEW_CARD;
+
+  const validate = (): CardFieldErrors => ({
+    number: validateCardNumber(card.number),
+    holder: validateHolder(card.holder),
+    expiry: validateExpiry(card.expiry),
+    cvv: validateCvv(card.cvv, brand),
+  });
+
+  const submit = useCardSubmit(order, buyer, providerConfig, onResolved, pollIntervalMs, {
+    card,
+    usingNewCard,
+    selection,
+    saveCard,
+    validate,
+    setFieldErrors,
+  });
+
+  return {
+    savedCards,
+    selection,
+    setSelection,
+    usingNewCard,
+    card,
+    setCard,
+    fieldErrors,
+    setFieldErrors,
+    brand,
+    saveCard,
+    setSaveCard,
+    ...submit,
+  };
+}

package/src/components/checkout/use-checkout-controller.ts

@@ -0,0 +1,252 @@
+import { useCallback, useEffect, useMemo, useState, type Dispatch, type SetStateAction } from "react";
+
+import { validateCpf } from "../../card";
+
+import { rememberHostedOrder, takeHostedOrder } from "./hosted-return";
+import type {
+  BuyerContact,
+  BuyerField,
+  BuyerInfo,
+  CheckoutOrder,
+  CreateOrderRequest,
+  CreateOrderResult,
+  OrderStatus,
+  PaymentMethod,
+} from "./types";
+import { usePaymentPolling } from "./use-payment-polling";
+
+type Step = "dados" | "payment" | "status";
+
+const STEP_ORDER: Step[] = ["dados", "payment", "status"];
+
+/**
+ * Everything the flow needs FROM its host, as explicit ports (FUT-564). The
+ * package owns the payment surface; the host owns the cart, the catalog,
+ * order creation and its own routing — these callbacks are the entire seam
+ * between the two, which is what lets the package import nothing from any app.
+ */
+export interface CheckoutHostPorts {
+  /**
+   * Raise the order (and its first charge). The host closes over everything
+   * the flow must not know: WHICH cart, WHICH tenant, WHICH comanda scope.
+   */
+  createOrder: (input: CreateOrderRequest) => Promise<CreateOrderResult>;
+  /**
+   * Persist the buyer's contact when they press "Continuar" on Dados — the
+   * host's account surface owns the write (and the blank-CPF-never-clears
+   * rule). Fire-and-forget by contract: the flow advances regardless of the
+   * outcome, and only calls this under the "salvar meus dados" consent.
+   */
+  saveBuyerContact?: (contact: BuyerContact) => void;
+  /** Leave checkout for the host's menu/catalog. */
+  onExitToMenu: () => void;
+  /**
+   * The order settled PAID. The storefront re-reads its cart here — the
+   * server emptied it inside the confirmation transaction (FUT-601) and
+   * nothing else tells the SPA. Never fired for FAILED/EXPIRED: that shopper
+   * still has a basket to retry with.
+   */
+  onPaid?: () => void;
+}
+
+/**
+ * The flow's navigation actions, split out of {@link useCheckoutController} for
+ * the 80-line per-function gate.
+ *
+ * `back` is where "the Dados step was skipped" has to be honoured: going back
+ * off Pagamento normally lands on Dados, but for a buyer with a CPF on file
+ * that step is not part of their flow, so the menu is the only honest
+ * destination — until they open it themselves via `editBuyer` ("alterar" on the
+ * payer block), after which it IS part of their flow and back returns to it.
+ */
+function useCheckoutNav(
+  taxIdOnFile: boolean,
+  goToMenu: () => void,
+  setStep: Dispatch<SetStateAction<Step>>,
+): { back: () => void; editBuyer: (() => void) | undefined } {
+  const [dadosOpened, setDadosOpened] = useState(false);
+  const openDados = useCallback(() => {
+    setDadosOpened(true);
+    setStep("dados");
+  }, [setStep]);
+  const back = useCallback(() => {
+    setStep((current) => {
+      if (current === "payment" && (!taxIdOnFile || dadosOpened)) return "dados";
+      goToMenu();
+      return current;
+    });
+  }, [dadosOpened, goToMenu, setStep, taxIdOnFile]);
+  // Undefined unless Dados was skipped — the payer block keys off its presence,
+  // so the decision lives here rather than being re-derived by every caller.
+  return { back, editBuyer: taxIdOnFile ? openDados : undefined };
+}
+
+/**
+ * What the "Continuar" gate objects to about the CPF, or undefined to advance.
+ *
+ * A blank field is only an error when the store has NO CPF for this buyer. With
+ * one on file the field starts empty by design (the client is never sent the
+ * saved CPF), so demanding one here trapped a returning buyer who opened Dados
+ * through "Alterar" and changed their mind: they could not reach Pagamento
+ * again, and back only led out to the menu. Leaving it blank means "charge me
+ * as before", which is exactly what the server's `resolveBuyerTaxId` does.
+ */
+function cpfGateError(typed: string, taxIdOnFile: boolean): string | undefined {
+  if (!typed && taxIdOnFile) return undefined;
+  return validateCpf(typed);
+}
+
+/**
+ * Where checkout opens: on the outcome for a buyer returning from a hosted
+ * provider, on Pagamento when their CPF is already on file, else on Dados.
+ */
+function initialStep(resuming: boolean, taxIdOnFile: boolean): Step {
+  if (resuming) return "status";
+  return taxIdOnFile ? "payment" : "dados";
+}
+
+/**
+ * Hand the buyer to a redirect provider's own page, if that is where this
+ * charge settles (FUT-556).
+ *
+ * Called BEFORE the order is stored: storing it first would render the PIX or
+ * card step for a provider that returned neither, which is the dead end this
+ * fixes.
+ *
+ * A full navigation rather than the host's router, because the destination is
+ * another origin. The return trip comes back to this same checkout route
+ * carrying `transaction_nsu` + `slug`, which the status poll already reads.
+ *
+ * @returns true when the buyer is on their way and the caller must stop.
+ */
+function handOverToProvider(order: CheckoutOrder): boolean {
+  if (!order.hostedCheckoutUrl) return false;
+  rememberHostedOrder(order);
+  window.location.assign(order.hostedCheckoutUrl);
+  return true;
+}
+
+/**
+ * The leg of checkout that resumes after a hosted provider sent the buyer back
+ * (FUT-556).
+ *
+ * The SPA was torn down by the redirect, so the order is rehydrated from the
+ * parked copy — once, on first render — and polled here rather than in a PIX or
+ * card view, because a redirect provider produced neither. The webhook is still
+ * what settles the order; this only tells the buyer that it did.
+ */
+function useHostedResume(): { order: CheckoutOrder | null; status: OrderStatus | null } {
+  const [order] = useState(takeHostedOrder);
+  const { status } = usePaymentPolling(order?.orderId ?? null, { enabled: Boolean(order) });
+  return { order, status };
+}
+
+/**
+ * Fire the host's `onPaid` port once the order settles PAID.
+ *
+ * FUT-601 made the SERVER empty the cart inside the confirmation transaction —
+ * but nothing told the SPA, whose cart provider survives every checkout route
+ * change and kept counting the items the buyer had just bought. The server was
+ * right and the screen was stale; this is where the host is told to catch up.
+ *
+ * PAID only. A FAILED or EXPIRED order fires nothing — that shopper still has
+ * a basket to retry with, and the host must not be told otherwise.
+ */
+function usePaidPort(settled: OrderStatus | null, onPaid: (() => void) | undefined): void {
+  useEffect(() => {
+    if (settled !== "PAID") return;
+    onPaid?.();
+  }, [settled, onPaid]);
+}
+
+/**
+ * All checkout state + handlers, so the checkout flow stays presentational.
+ * - `setMethod` drops any order raised for the previous method (no stale QR/form).
+ * - `back` is step-aware: Pagamento → Dados, else to the menu. With a CPF on
+ *   file the flow never has a Dados step, so Pagamento goes back to the menu.
+ * - `goToPayment` gates on the CPF (required for every charge) and PERSISTS the
+ *   buyer's contact — through the host port — before advancing; nothing
+ *   downstream of this step is allowed to be a precondition for their details
+ *   being saved.
+ * - `startPayment` raises the order (PIX → QR, CARD → chargeable); `payWithEmail`
+ *   re-raises with a corrected e-mail for the merchant-email rejection.
+ */
+export function useCheckoutController(
+  ports: CheckoutHostPorts,
+  defaultBuyer?: BuyerInfo,
+  /**
+   * The buyer already has a CPF saved (FUT-465) ⇒ the Dados step has nothing
+   * left to ask, so checkout opens on Pagamento and `back` goes to the menu
+   * rather than to a form the buyer never saw. The CPF itself is never in the
+   * client's hands — the server reads it from the encrypted profile when the
+   * charge is raised.
+   */
+  taxIdOnFile = false,
+) {
+  const { createOrder, saveBuyerContact, onExitToMenu, onPaid } = ports;
+  const resume = useHostedResume();
+  const [step, setStep] = useState<Step>(initialStep(Boolean(resume.order), taxIdOnFile));
+  // No method pre-selected: the Pagamento step shows just the picker until the
+  // buyer chooses PIX or card, then that method's order is raised and its UI
+  // revealed. Avoids raising a throwaway PIX charge for a buyer who wants card.
+  const [method, setMethodState] = useState<PaymentMethod | null>(null);
+  const [buyer, setBuyerState] = useState<BuyerInfo>(defaultBuyer ?? {});
+  const [saveProfile, setSaveProfile] = useState(true);
+  const [order, setOrder] = useState<CheckoutOrder | null>(resume.order);
+  const [finalStatus, setFinalStatus] = useState<OrderStatus | null>(null);
+  const [creating, setCreating] = useState(false);
+  const [createError, setCreateError] = useState<string | null>(null);
+  const [errorField, setErrorField] = useState<BuyerField | null>(null);
+
+  const clearError = useCallback(() => { setCreateError(null); setErrorField(null); }, []);
+  const setBuyer = useCallback((next: BuyerInfo) => { setBuyerState(next); clearError(); }, [clearError]);
+  const { back, editBuyer } = useCheckoutNav(taxIdOnFile, onExitToMenu, setStep);
+  const setMethod = useCallback((next: PaymentMethod) => {
+    setMethodState((prev) => { if (prev !== next) { setOrder(null); clearError(); } return next; });
+  }, [clearError]);
+  const goToPayment = useCallback(() => {
+    clearError();
+    const cpfError = cpfGateError(buyer.taxId?.trim() ?? "", taxIdOnFile);
+    if (cpfError) { setCreateError(cpfError); setErrorField("cpf"); return; }
+    // Persist the buyer's details HERE, on "Continuar" — not when a payment is
+    // raised. Everything after this step can fail (no provider configured, a
+    // declined card, an abandoned PIX, a closed tab) and the details must
+    // survive all of it. Fire-and-forget on purpose: making the buyer wait on
+    // the write — or blocking them when it fails — would trade the bug for a
+    // worse one. Gated on the "salvar meus dados" consent (LGPD), which is
+    // what the checkbox means.
+    if (saveProfile) {
+      saveBuyerContact?.({ name: buyer.name, phone: buyer.phone, taxId: buyer.taxId });
+    }
+    setStep("payment");
+  }, [buyer.name, buyer.phone, buyer.taxId, saveProfile, taxIdOnFile, clearError, saveBuyerContact]);
+  const startPayment = useCallback(async (chosen: PaymentMethod, override?: BuyerInfo) => {
+    clearError();
+    setCreating(true);
+    const result = await createOrder({ method: chosen, buyer: override ?? buyer, saveProfile });
+    setCreating(false);
+    if (!result.ok) { setCreateError(result.error.message); setErrorField(result.error.field); return; }
+    if (handOverToProvider(result.data)) return;
+    setOrder(result.data);
+    setFinalStatus(null);
+  }, [buyer, saveProfile, createOrder, clearError]);
+  const payWithEmail = useCallback((email: string) => {
+    if (!method) return;
+    const next = { ...buyer, email };
+    setBuyerState(next);
+    void startPayment(method, next);
+  }, [buyer, method, startPayment]);
+  const handleResolved = useCallback((s: OrderStatus) => { setFinalStatus(s); setStep("status"); }, []);
+  const retry = useCallback(() => {
+    setOrder(null); setFinalStatus(null); clearError(); setStep("payment");
+  }, [clearError]);
+  const completed = useMemo(() => new Set(STEP_ORDER.slice(0, STEP_ORDER.indexOf(step))), [step]);
+  usePaidPort(finalStatus ?? resume.status, onPaid);
+
+  return {
+    step, setStep, method, setMethod, buyer, setBuyer, saveProfile, setSaveProfile,
+    order, finalStatus: finalStatus ?? resume.status, creating, createError, errorField,
+    goToMenu: onExitToMenu, back, editBuyer,
+    goToPayment, startPayment, payWithEmail, handleResolved, retry, completed,
+  };
+}

package/src/components/checkout/use-payment-polling.ts

@@ -0,0 +1,93 @@
+import { useEffect, useState } from "react";
+
+import { pollOrderStatus } from "./client";
+import { TERMINAL_STATUSES, type OrderStatus } from "./types";
+
+interface PollingOptions {
+  /** Delay between polls (ms). */
+  intervalMs?: number;
+  /** Poll only while `true` (e.g. after a card charge is submitted). */
+  enabled?: boolean;
+  /**
+   * Opt-in bound on successful non-terminal polls (FUT-191): stop scheduling and
+   * report `timedOut` once this many healthy AWAITING responses arrive.
+   * Undefined ⇒ unbounded, today's behavior (the PIX consumer passes no cap).
+   */
+  maxHealthyPolls?: number;
+}
+
+/** Consecutive poll errors tolerated before giving up (avoids an infinite spinner). */
+const MAX_POLL_ERRORS = 4;
+
+/**
+ * Poll an order's payment status until it reaches a terminal state.
+ *
+ * Uses a self-scheduling `setTimeout` (never overlapping requests) that stops as
+ * soon as the order is PAID/FAILED/EXPIRED, and tears down on unmount or when the
+ * order id changes. This is the client half of the async confirmation the
+ * PagSeguro webhook drives on the server.
+ */
+export function usePaymentPolling(
+  orderId: string | null,
+  { intervalMs = 2500, enabled = true, maxHealthyPolls }: PollingOptions = {},
+): { status: OrderStatus | null; error: string | null; timedOut: boolean } {
+  const [status, setStatus] = useState<OrderStatus | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [timedOut, setTimedOut] = useState(false);
+
+  useEffect(() => {
+    if (!orderId || !enabled) {
+      return;
+    }
+
+    let cancelled = false;
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let errorCount = 0;
+    let healthyCount = 0;
+    setTimedOut(false);
+    setError(null);
+
+    const tick = async (): Promise<void> => {
+      const result = await pollOrderStatus(orderId);
+      if (cancelled) {
+        return;
+      }
+      if (result.ok) {
+        errorCount = 0;
+        setStatus(result.data);
+        if (TERMINAL_STATUSES.includes(result.data)) {
+          return; // terminal — stop polling
+        }
+        healthyCount += 1;
+        if (maxHealthyPolls !== undefined && healthyCount >= maxHealthyPolls) {
+          // A healthy-but-still-AWAITING stream never trips the error cap, so
+          // bound it separately (FUT-191): stop scheduling and let the consumer
+          // show a "taking longer" state instead of an infinite spinner.
+          setTimedOut(true);
+          return;
+        }
+      } else {
+        errorCount += 1;
+        if (errorCount >= MAX_POLL_ERRORS) {
+          // Give up rather than spin forever; surface the error to the consumer.
+          setError(result.error);
+          return;
+        }
+      }
+      timer = setTimeout(() => {
+        void tick();
+      }, intervalMs);
+    };
+
+    void tick();
+
+    return () => {
+      cancelled = true;
+      if (timer) {
+        clearTimeout(timer);
+      }
+    };
+  }, [orderId, intervalMs, enabled, maxHealthyPolls]);
+
+  return { status, error, timedOut };
+}