@12-apps/payments-frontend 1.7.1 → 1.8.1

package/src/components/checkout/checkout-steps.tsx

@@ -9,6 +9,7 @@ import {
   cardPathAvailable,
   cardTokenization,
   offeredMethods,
+  selectableMethods,
   usePreselectSoleMethod,
 } from "./method-capability";
 import { MethodPicker } from "./method-picker";
@@ -18,6 +19,7 @@ import { PixView } from "./pix-view";
 import type {
   BuyerField,
   BuyerInfo,
+  CheckoutCustomerField,
   CheckoutOrder,
   CheckoutProviderConfig,
   OrderStatus,
@@ -155,6 +157,7 @@ export function DadosStep({
   errorField,
   onContinue,
   cartTotals,
+  buyerFields,
   discountLines,
   totalOverride,
 }: {
@@ -167,6 +170,8 @@ export function DadosStep({
   onContinue: () => void;
   /** The host cart's own totals — what the pay bar shows in cart mode. */
   cartTotals: { totalLabel: string; totalItems: number };
+  /** What the store's chain declares it needs (FUT-595); absent ⇒ CPF-required. */
+  buyerFields?: readonly CheckoutCustomerField[];
   /**
    * The saving, itemized under the total the buyer is about to authorize
    * (FUT-246) — RENDERED BY THE HOST from its cart (the storefront passes its
@@ -177,7 +182,7 @@ export function DadosStep({
   /** Comanda settlement (FUT-comandas): totals come from the comanda, not the cart. */
   totalOverride?: { label: string; items: number };
 }): JSX.Element {
-  const { ActionBar, Alert, Button, Checkbox, Text } = useCheckoutComponents();
+  const { Checkbox } = useCheckoutComponents();
   const { label: totalLabel, items: totalItems } = displayTotals(totalOverride, cartTotals);
 
   return (
@@ -186,6 +191,7 @@ export function DadosStep({
         <BuyerInfoForm
           value={buyer}
           onChange={onBuyerChange}
+          fields={buyerFields}
           fieldError={errorField && createError ? { field: errorField, message: createError } : null}
         />
         <Checkbox
@@ -196,32 +202,57 @@ export function DadosStep({
         />
       </Box>
 
-      <ActionBar dataTestId="checkout-pay-bar">
-        <Box sx={{ width: "100%", display: "flex", flexDirection: "column", gap: 1.5 }}>
-          {createError ? (
-            <Alert variant="danger" title="Não foi possível continuar" description={createError} showIcon data-testid="checkout-error" />
-          ) : null}
-          <Box sx={{ display: "flex", alignItems: "center", gap: 2 }}>
-            <PayBarTotal totalLabel={totalLabel} totalItems={totalItems}>
-              {/* Suppressed while settling a comanda: those totals come from
-                  the frozen ticket, not the cart. */}
-              {totalOverride ? null : discountLines}
-            </PayBarTotal>
-            <Box sx={{ flex: 1, display: "flex", flexDirection: "column", alignItems: "flex-end", gap: 0.5, minWidth: 0 }}>
-              <Button variant="solid" color="primary" size="lg" fullWidth onClick={onContinue} dataTestId="checkout-continue">
-                Continuar
-              </Button>
-              <Box sx={{ display: "flex", alignItems: "center", gap: 0.5, color: "text.secondary" }}>
-                <LockOutlinedIcon sx={{ fontSize: 13 }} />
-                <Text variant="caption" size="xs" color="secondary" as="span">
-                  Pagamento seguro
-                </Text>
-              </Box>
+      <DadosPayBar
+        totalLabel={totalLabel}
+        totalItems={totalItems}
+        createError={createError}
+        onContinue={onContinue}
+      >
+        {/* Suppressed while settling a comanda: those totals come from the
+            frozen ticket, not the cart. */}
+        {totalOverride ? null : discountLines}
+      </DadosPayBar>
+    </>
+  );
+}
+
+/** The sticky "Continuar" bar: the refusal, the money, and the one action. */
+function DadosPayBar({
+  totalLabel,
+  totalItems,
+  createError,
+  onContinue,
+  children,
+}: {
+  totalLabel: string;
+  totalItems: number;
+  createError: string | null;
+  onContinue: () => void;
+  children?: ReactNode;
+}): JSX.Element {
+  const { ActionBar, Alert, Button, Text } = useCheckoutComponents();
+  return (
+    <ActionBar dataTestId="checkout-pay-bar">
+      <Box sx={{ width: "100%", display: "flex", flexDirection: "column", gap: 1.5 }}>
+        {createError ? (
+          <Alert variant="danger" title="Não foi possível continuar" description={createError} showIcon data-testid="checkout-error" />
+        ) : null}
+        <Box sx={{ display: "flex", alignItems: "center", gap: 2 }}>
+          <PayBarTotal totalLabel={totalLabel} totalItems={totalItems}>{children}</PayBarTotal>
+          <Box sx={{ flex: 1, display: "flex", flexDirection: "column", alignItems: "flex-end", gap: 0.5, minWidth: 0 }}>
+            <Button variant="solid" color="primary" size="lg" fullWidth onClick={onContinue} dataTestId="checkout-continue">
+              Continuar
+            </Button>
+            <Box sx={{ display: "flex", alignItems: "center", gap: 0.5, color: "text.secondary" }}>
+              <LockOutlinedIcon sx={{ fontSize: 13 }} />
+              <Text variant="caption" size="xs" color="secondary" as="span">
+                Pagamento seguro
+              </Text>
             </Box>
           </Box>
         </Box>
-      </ActionBar>
-    </>
+      </Box>
+    </ActionBar>
   );
 }
 
@@ -283,8 +314,9 @@ export function PaymentStep({
 }: PaymentStepProps): JSX.Element {
   const { LoadingState } = useCheckoutComponents();
   const cardUnavailable = !cardPathAvailable(providerConfig ?? null);
+  const offered = offeredMethods(providerConfig ?? null);
   useAutoRaiseOrder(order, method, creating, createError, onGenerate);
-  usePreselectSoleMethod(cardUnavailable, method, onMethodChange);
+  usePreselectSoleMethod(selectableMethods(offered, cardUnavailable), method, onMethodChange);
 
   return (
     <Box sx={{ display: "flex", flexDirection: "column", gap: 3 }}>
@@ -295,7 +327,7 @@ export function PaymentStep({
         value={method}
         onChange={onMethodChange}
         cardUnavailable={cardUnavailable}
-        offered={offeredMethods(providerConfig ?? null)}
+        offered={offered}
       />
 
       <PaymentBody

package/src/components/checkout/client-context.tsx

@@ -0,0 +1,57 @@
+/**
+ * WHICH client the checkout screens talk through (FUT-741).
+ *
+ * Before this, every screen imported the free functions in `client.ts`
+ * directly, so the mount they reach was a module-level constant: one prefix,
+ * the ambient `fetch`, no headers. That is right for the shipped storefront
+ * and impossible for anything else — a story, a harness page or a second host
+ * on a different mount could only get at the wire by replacing `globalThis.
+ * fetch`, which is a mock of OUR OWN client and the exact blind spot the
+ * FUT-740 review's three criticals lived in.
+ *
+ * So the client is context now, with the module-level one as the default. A
+ * tree with no provider behaves exactly as it did; a tree under
+ * `createPaymentFlows`'s provider talks through the bound transport.
+ *
+ * The default is built from the `client.ts` bindings LAZILY (inside each
+ * arrow), so a suite that `vi.mock`s that module still intercepts the call.
+ */
+import { createContext, useContext, type JSX, type ReactNode } from "react";
+
+import {
+  chargeCard,
+  fetchCheckoutConfig,
+  listSavedCards,
+  pollOrderStatus,
+  refreshCardPublicKey,
+} from "./client";
+import type { CheckoutClient } from "./transport";
+
+/** The unbound client: `/api/checkout` on the ambient `fetch`. */
+const DEFAULT_CLIENT: CheckoutClient = {
+  getConfig: (tenantSlug) => fetchCheckoutConfig(tenantSlug),
+  getStatus: (ref) => pollOrderStatus(ref),
+  charge: (input) => chargeCard(input),
+  listInstruments: (tenantSlug) => listSavedCards(tenantSlug),
+  refreshBrowserKey: (input) => refreshCardPublicKey(input),
+};
+
+const CheckoutClientContext = createContext<CheckoutClient | null>(null);
+
+/** Point everything below at one bound {@link CheckoutClient}. */
+export function CheckoutClientProvider({
+  client,
+  children,
+}: {
+  client: CheckoutClient;
+  children: ReactNode;
+}): JSX.Element {
+  return (
+    <CheckoutClientContext.Provider value={client}>{children}</CheckoutClientContext.Provider>
+  );
+}
+
+/** The bound client, or the module default when no provider sits above. */
+export function useCheckoutClientApi(): CheckoutClient {
+  return useContext(CheckoutClientContext) ?? DEFAULT_CLIENT;
+}

package/src/components/checkout/client.ts

@@ -4,6 +4,14 @@
  * provider-protocol read, against the host-mounted `/api/checkout*` surface
  * (documented in `packages/payments/ADOPTING.md` §3).
  *
+ * Since FUT-741 these are the UNBOUND door onto `createCheckoutClient` — the
+ * same five calls, on the default `/api/checkout` prefix and the ambient
+ * `fetch`. They stay exported, and stay byte-identical on the wire, because
+ * they are what is already running in buyers' browsers and what both pinned
+ * wire suites drive. A host that needs a different mount, its own headers or an
+ * injected `fetch` reaches for `createPaymentFlows({ transport })` instead;
+ * nothing about these functions changes when it does.
+ *
  * Order CREATION and the buyer-profile save are deliberately NOT here: both
  * are host domain (the cart, the account) and reach the flow as ports
  * (`createOrder` / `saveBuyerContact` on `CheckoutFlowProps`).
@@ -14,8 +22,9 @@
  */
 
 import type { SavedCard } from "../../card";
-import { err, ok, type Result } from "../../result";
+import type { Result } from "../../result";
 
+import { createCheckoutClient } from "./transport";
 import type {
   ChargeCardInput,
   ChargeOutcome,
@@ -23,91 +32,15 @@ import type {
   OrderStatus,
 } from "./types";
 
-// ---------------------------------------------------------------------------
-// Transport
-// ---------------------------------------------------------------------------
-
-/** Envelope the API routes return: `{ data }` on success, `{ error }` on failure. */
-interface ApiEnvelope<T> {
-  data?: T;
-  error?: string;
-  /**
-   * Stable machine code for the failure (`checkoutErrorResponse` always sends
-   * one). Carried through so a surface can PRESENT a refusal for what it is —
-   * an unresolved charge is not a decline, and rendering it under "não foi
-   * possível pagar" with a live pay button invites the second payment its own
-   * text forbids.
-   */
-  code?: string;
-}
-
-/**
- * A non-2xx envelope as a {@link Result} failure, carrying its machine CODE.
- * The message is what the buyer reads; the code is what a surface uses to
- * decide how to PRESENT it, which a message cannot be parsed for.
- */
-function refused<T>(json: ApiEnvelope<T> | null): Result<T> {
-  return err(json?.error ?? "Não foi possível concluir a operação. Tente novamente.", json?.code);
-}
-
-/** Call an API route and normalize the response into a {@link Result}. */
-async function requestResult<T>(input: string, init?: RequestInit): Promise<Result<T>> {
-  try {
-    const res = await fetch(input, {
-      ...init,
-      headers: { "Content-Type": "application/json", ...init?.headers },
-    });
-    const json = (await res.json().catch(() => null)) as ApiEnvelope<T> | null;
-    if (!res.ok) return refused(json);
-    if (!json || json.data === undefined) {
-      return err(json?.error ?? "Resposta inválida do servidor.");
-    }
-    return ok(json.data);
-  } catch {
-    return err("Não foi possível conectar. Verifique sua conexão e tente novamente.");
-  }
-}
-
-// ---------------------------------------------------------------------------
-// Public API
-// ---------------------------------------------------------------------------
-
 /**
- * What a hosted checkout appended to the return URL when it sent the buyer
- * back, or undefined.
- *
- * InfinitePay's `payment_check` refuses to confirm without BOTH the
- * `transaction_nsu` and the invoice `slug`, and neither exists until somebody
- * has actually paid — they arrive here, on the redirect. Left in the URL: the
- * server treats them as hints, so re-sending them on later polls is harmless.
- *
- * Note the buyer has to press "Continuar" on the provider's receipt for this
- * redirect to happen at all, which is exactly why it is a hint and never the
- * mechanism: the webhook, and the server-side reconciliation behind it, are
- * what must work when they simply close the tab.
+ * The default binding: `/api/checkout` on the ambient `fetch`. Built once, but
+ * it resolves `fetch` per call, so a suite that stubs the global still wins.
  */
-function returnedSettlement(): Record<string, string> {
-  if (typeof window === "undefined") return {};
-  const params = new URLSearchParams(window.location.search);
-  // BOTH. Measured against the live API: handle + order_nsu +
-  // transaction_nsu + slug answers {"success":true,"paid":true,…}, and the
-  // same call missing EITHER answers {"success":false}. Neither exists before
-  // the payment, and the slug is not in the link-creation response — the
-  // redirect and the webhook are the only places both appear together.
-  const transactionNsu = params.get("transaction_nsu") ?? params.get("transaction_id") ?? "";
-  const slug = params.get("slug") ?? "";
-  return {
-    ...(transactionNsu ? { transactionNsu } : {}),
-    ...(slug ? { slug } : {}),
-  };
-}
+const defaultClient = createCheckoutClient();
 
 /** Poll an order's reconciled status (async provider webhook confirmation). */
 export async function pollOrderStatus(orderId: string): Promise<Result<OrderStatus>> {
-  const params = new URLSearchParams({ orderId, ...returnedSettlement() });
-  return requestResult<OrderStatus>(`/api/checkout/status?${params.toString()}`, {
-    method: "GET",
-  });
+  return defaultClient.getStatus(orderId);
 }
 
 /**
@@ -119,10 +52,7 @@ export async function pollOrderStatus(orderId: string): Promise<Result<OrderStat
 export async function fetchCheckoutConfig(
   tenantSlug: string,
 ): Promise<Result<CheckoutProviderConfig>> {
-  return requestResult<CheckoutProviderConfig>(
-    `/api/checkout/config?tenantSlug=${encodeURIComponent(tenantSlug)}`,
-    { method: "GET" },
-  );
+  return defaultClient.getConfig(tenantSlug);
 }
 
 /**
@@ -135,10 +65,7 @@ export async function fetchCheckoutConfig(
 export async function refreshCardPublicKey(input: {
   orderId: string;
 }): Promise<Result<{ publicKey: string | null }>> {
-  return requestResult<{ publicKey: string | null }>("/api/checkout/refresh-key", {
-    method: "POST",
-    body: JSON.stringify({ orderId: input.orderId }),
-  });
+  return defaultClient.refreshBrowserKey(input);
 }
 
 /**
@@ -147,29 +74,10 @@ export async function refreshCardPublicKey(input: {
  * page (3-D Secure, FUT-698) — the caller then hands the buyer over.
  */
 export async function chargeCard(input: ChargeCardInput): Promise<Result<ChargeOutcome>> {
-  return requestResult<ChargeOutcome>("/api/checkout/charge", {
-    method: "POST",
-    body: JSON.stringify({
-      orderId: input.orderId,
-      token: input.token,
-      // One instrument per provider (FUT-563) — the server hands each provider
-      // in the chain its own, which is what lets a card charge fail over.
-      ...(input.tokensByProvider ? { tokensByProvider: input.tokensByProvider } : {}),
-      saveCard: input.saveCard,
-      cardMeta: input.cardMeta,
-      taxId: input.taxId,
-    }),
-  });
+  return defaultClient.charge(input);
 }
 
 /** List saved cards available for reuse (empty on any error — non-blocking). */
 export async function listSavedCards(tenantSlug?: string): Promise<SavedCard[]> {
-  // Scoped to the store when known (FUT-697): only cards the store's ACTIVE
-  // provider can actually charge come back — a PagBank-vaulted card is not
-  // offered for a Stone charge it would fail (or misroute).
-  const query = tenantSlug ? `?tenantSlug=${encodeURIComponent(tenantSlug)}` : "";
-  const result = await requestResult<SavedCard[]>(`/api/checkout/cards${query}`, {
-    method: "GET",
-  });
-  return result.ok ? result.data : [];
+  return defaultClient.listInstruments(tenantSlug);
 }

package/src/components/checkout/method-capability.ts

@@ -9,7 +9,7 @@ import { useEffect } from "react";
 
 import { tokenizerFor, type CardTokenizationConfig } from "../../card";
 
-import type { CheckoutProviderConfig, PaymentMethod } from "./types";
+import type { CheckoutChainLink, CheckoutProviderConfig, PaymentMethod } from "./types";
 
 /**
  * Whether the store's CHAIN gives this browser a card path (FUT-697/563).
@@ -26,16 +26,39 @@ import type { CheckoutProviderConfig, PaymentMethod } from "./types";
  * Answering "yes, it is REDIRECT" off the head alone is what let the picker
  * offer a card the submit could never tokenize.
  *
+ * Asked only of the entries that DECLARE `CARD` (FUT-747), for the same reason
+ * the server's predicate is: tokenization is a card fact, so a PIX-only entry
+ * has nothing to say about the card path and must not be read as "this store
+ * hands the buyer over". A store with no card-capable entry at all has no card
+ * path — `offeredMethods` is already not offering one, and saying so here is
+ * what lets {@link usePreselectSoleMethod} pick the store's only method.
+ *
  * `null` config (still loading / fetch blip) fails OPEN for the UI — the
  * tokenizer itself still fails CLOSED.
  */
 export function cardPathAvailable(config: CheckoutProviderConfig | null): boolean {
   if (!config) return true;
-  const chain = cardChain(config);
+  const chain = cardCapableChain(config);
+  if (chain.length === 0) return false;
   if (!chain.some((link) => link.mintable)) return true;
   return chain.some(canMintFor);
 }
 
+/**
+ * The published chain narrowed to the entries that declare `CARD` — the same
+ * subset the server's walk will attempt, since it skips a provider whose
+ * capabilities exclude the method.
+ *
+ * A store that served NO chain (an older host, or a mocked config) has no
+ * per-entry `methods` to narrow on, so it degrades to {@link cardChain}'s head
+ * triple and behaves exactly as it did before.
+ */
+function cardCapableChain(config: CheckoutProviderConfig): CardChainLink[] {
+  const chain = config.chain;
+  if (!chain || chain.length === 0) return cardChain(config);
+  return chain.filter((link) => link.methods.includes("CARD")).map(toCardLink);
+}
+
 /** Whether this browser can really produce an instrument for ONE chain entry. */
 function canMintFor(link: CardChainLink): boolean {
   if (!link.mintable) return false;
@@ -104,12 +127,17 @@ export function cardChain(config: CheckoutProviderConfig | null): CardChainLink[
     const mintable = config.tokenization === null || MINTABLE.has(config.tokenization);
     return [{ ...cardTokenization(config), mintable }];
   }
-  return chain.map((link) => ({
+  return chain.map(toCardLink);
+}
+
+/** ONE published chain entry, as the card path sees it. */
+function toCardLink(link: CheckoutChainLink): CardChainLink {
+  return {
     provider: link.provider,
     publicKey: link.publicKey,
     mockTokenization: link.mockTokenization,
     mintable: MINTABLE.has(link.tokenization),
-  }));
+  };
 }
 
 /**
@@ -128,16 +156,38 @@ export function offeredMethods(config: CheckoutProviderConfig | null): PaymentMe
 }
 
 /**
- * When the card path is unavailable, PIX is the only choice left — choose it
- * (FUT-697 review): a one-option radiogroup that still demands a tap is a
- * click that buys the buyer nothing.
+ * The methods a buyer can actually pick right now.
+ *
+ * `null` offered — still loading, or a fetch blip — fails OPEN and offers both;
+ * the server still refuses the charge closed. A CARD tile with no in-browser
+ * path is not selectable, so it does not count towards a "sole" method either.
  */
-export function usePreselectSoleMethod(
+export function selectableMethods(
+  offered: PaymentMethod[] | null,
   cardUnavailable: boolean,
+): PaymentMethod[] {
+  return (offered ?? ["PIX", "CARD"]).filter(
+    (method) => !(method === "CARD" && cardUnavailable),
+  );
+}
+
+/**
+ * A SOLE remaining method is not a choice — take it (FUT-697 review, widened by
+ * FUT-741).
+ *
+ * A one-option radiogroup that still demands a tap is a click that buys the
+ * buyer nothing. It used to fire only when the CARD tile was disabled, which
+ * missed the other shape entirely: a store whose chain declares PIX alone
+ * renders one tile, nothing preselects it, and the buyer sits on a picker with
+ * a single option and no payment below it.
+ */
+export function usePreselectSoleMethod(
+  selectable: readonly PaymentMethod[],
   method: PaymentMethod | null,
   onMethodChange: (method: PaymentMethod) => void,
 ): void {
+  const sole = selectable.length === 1 ? selectable[0] : undefined;
   useEffect(() => {
-    if (cardUnavailable && method === null) onMethodChange("PIX");
-  }, [cardUnavailable, method, onMethodChange]);
+    if (method === null && sole) onMethodChange(sole);
+  }, [sole, method, onMethodChange]);
 }

package/src/components/checkout/navigate-context.tsx

@@ -0,0 +1,40 @@
+/**
+ * WHERE a hosted handover sends the buyer (FUT-741).
+ *
+ * The handover is a full navigation to ANOTHER ORIGIN — a redirect provider's
+ * page, or a 3-DS challenge — so it can never be the host's router. But it is
+ * still a thing some hosts must observe: log it, confirm it, or render an
+ * interstitial around it. Left as a bare `window.location.assign` inside the
+ * controller it was none of those, and a browser that blocks or stalls the
+ * navigation left the buyer on a page with nothing on it.
+ *
+ * So it is a port with a default. No provider ⇒ exactly today's behaviour.
+ */
+import { createContext, useContext, type JSX, type ReactNode } from "react";
+
+/** Take the buyer to another origin. */
+export type CheckoutNavigate = (url: string) => void;
+
+/** The unchanged default: a full navigation, in this tab. */
+const DEFAULT_NAVIGATE: CheckoutNavigate = (url) => {
+  window.location.assign(url);
+};
+
+const CheckoutNavigateContext = createContext<CheckoutNavigate | null>(null);
+
+export function CheckoutNavigateProvider({
+  navigate,
+  children,
+}: {
+  navigate: CheckoutNavigate;
+  children: ReactNode;
+}): JSX.Element {
+  return (
+    <CheckoutNavigateContext.Provider value={navigate}>{children}</CheckoutNavigateContext.Provider>
+  );
+}
+
+/** The host's navigate port, or `window.location.assign`. */
+export function useCheckoutNavigate(): CheckoutNavigate {
+  return useContext(CheckoutNavigateContext) ?? DEFAULT_NAVIGATE;
+}