@12-apps/payments-frontend 1.7.1 → 1.8.1

package/package.json

@@ -1,21 +1,23 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "1.7.1",
+  "version": "1.8.1",
   "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": {
     ".": "./src/index.ts"
   },
   "scripts": {
-    "clean": "rm -rf node_modules coverage",
+    "clean": "rm -rf node_modules coverage storybook-static",
     "test": "node ../../../scripts/vitest-with-teardown.mjs run",
     "test:watch": "vitest watch",
     "lint": "eslint src --max-warnings 0",
     "check-types": "tsc --noEmit",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "dev": "storybook dev -p 6007",
+    "storybook:build": "storybook build"
   },
   "dependencies": {
-    "@12-apps/payments-backend": "^1.7.1",
+    "@12-apps/payments-backend": "^1.8.1",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {
@@ -26,20 +28,27 @@
     "react-dom": ">=19.0.0"
   },
   "devDependencies": {
+    "@12-apps/eslint-config": "^1.9.1",
+    "@12-apps/typescript-config": "^1.9.1",
     "@emotion/react": "^11.14.0",
     "@emotion/styled": "^11.14.0",
     "@mui/material": "^6.5.0",
-    "@12-apps/eslint-config": "^1.8.1",
-    "@12-apps/typescript-config": "^1.8.1",
+    "@storybook/addon-docs": "^9.1.10",
+    "@storybook/addon-links": "^9.1.10",
+    "@storybook/builder-vite": "^9.1.10",
+    "@storybook/react-vite": "^9.1.10",
     "@testing-library/react": "^16.1.0",
     "@types/react": "19.2.2",
     "@types/react-dom": "19.2.2",
     "eslint": "^9.39.1",
+    "eslint-plugin-storybook": "9.1.10",
     "eslint-plugin-test-flakiness": "^1.4.0",
     "jsdom": "^25.0.1",
     "react": "^19.2.0",
     "react-dom": "^19.2.0",
+    "storybook": "^9.1.10",
     "typescript": "^5.9.2",
+    "vite": "^6.4.1",
     "vitest": "^3.2.4"
   },
   "engines": {
@@ -63,6 +72,8 @@
     "*.mjs",
     "*.md",
     "!eslint.config.js",
+    "!.storybook/**",
+    "!src/stories/**",
     "!**/__tests__/**",
     "!**/tests/**",
     "!**/*.test.*",

package/src/components/checkout/buyer-fields.ts

@@ -0,0 +1,117 @@
+/**
+ * WHAT THE BUYER MUST BE ASKED, derived from the chain's own declaration
+ * (FUT-595, wired into the browser by FUT-741).
+ *
+ * The backend has published `customerSchema` per chain entry since FUT-740 and
+ * validates every charge against it. The browser ignored it and asked for a CPF
+ * and nothing else — right for one provider, wrong for a store whose provider
+ * wants a mobile, and wrong in the expensive direction: the buyer finishes the
+ * form, presses Pagar, and gets a 400 naming a field there was never an input
+ * for. That is the third FUT-740 critical, one layer up.
+ *
+ * ## The degrade direction is the whole safety property
+ *
+ * A chain that declares nothing is NOT a chain that asks for nothing. An older
+ * host, a hand-written config, a config that failed to load — all of them
+ * arrive here as "no declaration", and the honest reading of that is "I do not
+ * know", not "nothing is needed". So the fallback is today's behaviour: CPF,
+ * required. Over-asking costs the buyer one field they may not have needed;
+ * under-asking costs them a completed form and a refused charge.
+ *
+ * ## The union, not the head
+ *
+ * Every entry the walk may reach gets a vote, because the form is filled ONCE,
+ * before the first attempt. `required` takes the strictest answer and the TYPE
+ * takes the narrower rule (`MOBILE` ⊂ `PHONE`) for the same reason: a value
+ * that satisfies only the laxer member strands the buyer on the stricter one.
+ * This mirrors the server's `unionCustomerFields` exactly — deliberately, since
+ * the two must not disagree about what a chain needs.
+ */
+
+import { validateCpf } from "../../card";
+
+import type { CheckoutChainLink, CheckoutCustomerField, PaymentMethod } from "./types";
+
+/** What a chain that declared nothing is assumed to need — today's behaviour. */
+const CPF_REQUIRED: CheckoutCustomerField = { key: "taxId", type: "CPF", required: true };
+
+/** The fields one entry asks for when charging via `method`. */
+function fieldsOf(
+  link: CheckoutChainLink,
+  method: PaymentMethod | null,
+): readonly CheckoutCustomerField[] {
+  const declared = link.customerSchema ?? [];
+  // No method chosen yet (the Dados step opens before the picker): collect the
+  // union across every method, which is the up-front collection FUT-595 asks
+  // for — a form that has to be re-opened after the method is picked is the
+  // double typing this exists to remove.
+  if (method === null) return declared;
+  return declared.filter((field) => !field.methods || field.methods.includes(method));
+}
+
+/** Which type accepts a SUBSET of the other's values. `MOBILE` ⊂ `PHONE`. */
+function narrowerType(
+  a: CheckoutCustomerField["type"],
+  b: CheckoutCustomerField["type"],
+): CheckoutCustomerField["type"] {
+  if (a === "PHONE" && b === "MOBILE") return "MOBILE";
+  return a;
+}
+
+/** Merge one declaration into the running union. */
+function absorb(
+  byKey: Map<CheckoutCustomerField["key"], CheckoutCustomerField>,
+  field: CheckoutCustomerField,
+): void {
+  const existing = byKey.get(field.key);
+  if (!existing) {
+    byKey.set(field.key, { key: field.key, type: field.type, required: field.required });
+    return;
+  }
+  byKey.set(field.key, {
+    ...existing,
+    type: narrowerType(existing.type, field.type),
+    required: existing.required || field.required,
+  });
+}
+
+/**
+ * The buyer fields to collect for this chain and method.
+ *
+ * An entry with NO declaration makes the answer uncertain, so the CPF is folded
+ * in as required — see the module doc. That is deliberately not the same as
+ * "the chain is empty": an empty chain means the store cannot charge at all,
+ * and the caller renders the unavailable screen rather than a form.
+ */
+export function buyerFieldsFor(
+  chain: readonly CheckoutChainLink[] | undefined,
+  method: PaymentMethod | null,
+): CheckoutCustomerField[] {
+  if (!chain || chain.length === 0) return [CPF_REQUIRED];
+  const byKey = new Map<CheckoutCustomerField["key"], CheckoutCustomerField>();
+  // An UNDECLARED entry is not a silent one. It is an entry whose requirements
+  // this browser cannot see, and the safe reading of that is the pre-FUT-595
+  // rule it would have been charged under.
+  if (chain.some((link) => link.customerSchema === undefined)) absorb(byKey, CPF_REQUIRED);
+  for (const field of chain.flatMap((link) => fieldsOf(link, method))) absorb(byKey, field);
+  return [...byKey.values()];
+}
+
+/** Whether a value satisfies one field's declared rule. */
+const RULES: Record<CheckoutCustomerField["type"], (value: string) => boolean> = {
+  NAME: (value) => value.trim().length >= 2,
+  EMAIL: (value) => /^[^\s@]+@[^\s@]+$/.test(value) && /\.[^\s@.]+$/.test(value),
+  // DDD + an 8-digit landline or a 9-digit mobile, mirroring the server's rule.
+  PHONE: (value) => /^\d{10,11}$/.test(value.replace(/\D/g, "")),
+  MOBILE: (value) => /^\d{2}9\d{8}$/.test(value.replace(/\D/g, "")),
+  // The real check-digit rule, not a length test: the same validator the CPF
+  // input has always used, so the form and the gate cannot disagree.
+  CPF: (value) => validateCpf(value) === undefined,
+};
+
+/** Whether a declared field is satisfied by what the buyer typed. */
+export function fieldSatisfied(field: CheckoutCustomerField, value: string | undefined): boolean {
+  const typed = (value ?? "").trim();
+  if (!typed) return !field.required;
+  return RULES[field.type](typed);
+}

package/src/components/checkout/buyer-info-form.tsx

@@ -3,7 +3,8 @@ import type { JSX } from "react";
 
 import { formatCpf, validateCpf } from "../../card";
 
-import type { BuyerField, BuyerInfo } from "./types";
+import { fieldSatisfied } from "./buyer-fields";
+import type { BuyerField, BuyerInfo, CheckoutCustomerField } from "./types";
 import { useCheckoutComponents } from "./ui";
 
 const EMAIL_PATTERN = /^[^\s@]+@[^\s@]+\.[^\s@]+$/;
@@ -18,121 +19,189 @@ interface BuyerFieldErrors {
   phone?: string;
 }
 
+/** The four inputs this form can render, keyed by the schema's own key. */
+const INPUTS = {
+  taxId: {
+    label: "CPF",
+    testId: "buyer-cpf",
+    errorKey: "cpf",
+    props: {
+      type: "text",
+      inputMode: "numeric",
+      autoComplete: "off",
+      placeholder: "000.000.000-00",
+    },
+  },
+  name: { label: "Nome", testId: "buyer-name", errorKey: "name", props: { type: "text", autoComplete: "name" } },
+  email: { label: "E-mail", testId: "buyer-email", errorKey: "email", props: { type: "email", autoComplete: "email" } },
+  phone: { label: "Telefone", testId: "buyer-phone", errorKey: "phone", props: { type: "tel", autoComplete: "tel" } },
+} as const;
+
+type InputKey = keyof typeof INPUTS;
+
+/** The order the inputs are shown in — CPF first, as it always has been. */
+const FIELD_ORDER: readonly InputKey[] = ["taxId", "name", "email", "phone"];
+
+/**
+ * The contact fields the checkout offers regardless of what any provider asks
+ * for: they are the RECEIPT's, not the charge's. A chain that requires none of
+ * them still gets them as optional inputs, which is what they have always been.
+ */
+const RECEIPT_FIELDS: readonly InputKey[] = ["name", "email", "phone"];
+
+/** What the buyer typed for one key. */
+function valueOf(buyer: BuyerInfo, key: InputKey): string {
+  return buyer[key] ?? "";
+}
+
 /**
  * Per-field error, overlaying any server-flagged error on top of the local format
  * checks — so a failed "pay" attempt highlights the exact input.
  */
-function deriveErrors(value: BuyerInfo, fieldError: FieldError): BuyerFieldErrors {
+function deriveErrors(
+  value: BuyerInfo,
+  fieldError: FieldError,
+  required: ReadonlySet<InputKey>,
+): BuyerFieldErrors {
   const override = (field: BuyerField): string | undefined =>
     fieldError?.field === field ? fieldError.message : undefined;
   const localEmail =
     value.email && !EMAIL_PATTERN.test(value.email) ? "E-mail inválido." : undefined;
+  const missing = (key: InputKey, message: string): string | undefined =>
+    required.has(key) && !valueOf(value, key).trim() ? message : undefined;
   return {
     cpf: override("cpf") ?? (value.taxId ? validateCpf(value.taxId) : undefined),
-    email: override("email") ?? localEmail,
-    name: override("name"),
-    phone: override("phone"),
+    email: override("email") ?? localEmail ?? missing("email", "E-mail obrigatório."),
+    name: override("name") ?? missing("name", "Nome obrigatório."),
+    phone: override("phone") ?? missing("phone", "Telefone obrigatório."),
   };
 }
 
 /**
- * Buyer contact at checkout. CPF is REQUIRED (PagBank needs it for the charge);
- * name, e-mail and phone are optional and only used for the receipt. A provided
- * e-mail is format-checked. Fully controlled by the parent checkout state.
+ * The instruction line above the inputs, worded from what the chain actually
+ * declared. It used to name the CPF unconditionally, which is wrong the moment
+ * a store's provider wants something else (or nothing).
  */
-export function BuyerInfoForm({
+function instructionFor(required: ReadonlySet<InputKey>): string {
+  const names = FIELD_ORDER.filter((key) => required.has(key)).map((key) =>
+    key === "taxId" ? "CPF" : INPUTS[key].label.toLowerCase(),
+  );
+  if (names.length === 0) {
+    return "Nome, e-mail e telefone são opcionais — usados apenas para o comprovante.";
+  }
+  return (
+    `Informe seu ${names.join(", ")} (${names.length === 1 ? "obrigatório" : "obrigatórios"} ` +
+    "para o pagamento). Os demais campos são opcionais — usados apenas para o comprovante."
+  );
+}
+
+/** Which inputs to render, and which of them are required. */
+function resolveShape(fields: readonly CheckoutCustomerField[] | undefined): {
+  shown: InputKey[];
+  required: Set<InputKey>;
+} {
+  // No declaration reaching this component means the pre-FUT-595 form: CPF
+  // required, receipt fields optional. `buyerFieldsFor` degrades the same way,
+  // so a caller that derived its fields from a chain lands here too.
+  const declared = fields ?? [{ key: "taxId" as const, type: "CPF" as const, required: true }];
+  const required = new Set<InputKey>(
+    declared.filter((field) => field.required).map((field) => field.key),
+  );
+  const declaredKeys = new Set<InputKey>(declared.map((field) => field.key));
+  const shown = FIELD_ORDER.filter(
+    (key) => declaredKeys.has(key) || RECEIPT_FIELDS.includes(key),
+  );
+  return { shown, required };
+}
+
+/** Whether every declared requirement is met — the "Continuar" gate's question. */
+export function buyerFormComplete(
+  buyer: BuyerInfo,
+  fields: readonly CheckoutCustomerField[],
+): CheckoutCustomerField | null {
+  return fields.find((field) => !fieldSatisfied(field, buyer[field.key])) ?? null;
+}
+
+/** One declaration-driven input, rendered through the host's slot. */
+function BuyerInput({
+  fieldKey,
   value,
+  required,
+  error,
   onChange,
-  fieldError,
 }: {
+  fieldKey: InputKey;
   value: BuyerInfo;
+  required: boolean;
+  error?: string;
   onChange: (buyer: BuyerInfo) => void;
-  fieldError?: FieldError;
 }): JSX.Element {
-  const { Input, Text } = useCheckoutComponents();
-  const errors = deriveErrors(value, fieldError ?? null);
-
+  const { Input } = useCheckoutComponents();
+  const spec = INPUTS[fieldKey];
   return (
-    <Box sx={{ display: "flex", flexDirection: "column", gap: 2 }}>
-      <Text variant="caption" size="xs" color="secondary" as="p">
-        Informe seu CPF (obrigatório para o pagamento). Nome, e-mail e telefone são
-        opcionais — usados apenas para o comprovante.
-      </Text>
-
-      <Input
-        label="CPF"
-        type="text"
-        inputMode="numeric"
-        variant="outlined"
-        size="md"
-        fullWidth
-        required
-        autoComplete="off"
-        placeholder="000.000.000-00"
-        value={value.taxId ?? ""}
-        error={Boolean(errors.cpf)}
-        helperText={errors.cpf}
-        onChange={(event) => onChange({ ...value, taxId: formatCpf(event.target.value) })}
-        data-testid="buyer-cpf"
-      />
-
-      <OptionalContactFields value={value} onChange={onChange} errors={errors} />
-    </Box>
+    <Input
+      label={spec.label}
+      variant="outlined"
+      size="md"
+      fullWidth
+      required={required}
+      {...spec.props}
+      value={valueOf(value, fieldKey)}
+      error={Boolean(error)}
+      helperText={error}
+      onChange={(event) =>
+        onChange({
+          ...value,
+          // The CPF keeps its progressive mask; everything else is taken as typed.
+          [fieldKey]: fieldKey === "taxId" ? formatCpf(event.target.value) : event.target.value,
+        })
+      }
+      data-testid={spec.testId}
+    />
   );
 }
 
-/** The optional receipt fields (name / e-mail / phone). */
-function OptionalContactFields({
+/**
+ * Buyer contact at checkout, with WHICH fields are required decided by the
+ * store's provider chain (FUT-595) rather than hard-coded.
+ *
+ * Passing no `fields` is the pre-FUT-595 form, verbatim: CPF required, name /
+ * e-mail / telefone optional and used only for the receipt. That is also what
+ * `buyerFieldsFor` produces for a chain that declares nothing, so a caller
+ * cannot accidentally land on "ask nothing".
+ */
+export function BuyerInfoForm({
   value,
   onChange,
-  errors,
+  fieldError,
+  fields,
 }: {
   value: BuyerInfo;
   onChange: (buyer: BuyerInfo) => void;
-  errors: BuyerFieldErrors;
+  fieldError?: FieldError;
+  /** The chain's resolved declaration; absent ⇒ CPF-required (never "nothing"). */
+  fields?: readonly CheckoutCustomerField[];
 }): JSX.Element {
-  const { Input } = useCheckoutComponents();
+  const { Text } = useCheckoutComponents();
+  const { shown, required } = resolveShape(fields);
+  const errors = deriveErrors(value, fieldError ?? null, required);
+
   return (
-    <>
-      <Input
-        label="Nome"
-        type="text"
-        variant="outlined"
-        size="md"
-        fullWidth
-        autoComplete="name"
-        value={value.name ?? ""}
-        error={Boolean(errors.name)}
-        helperText={errors.name}
-        onChange={(event) => onChange({ ...value, name: event.target.value })}
-        data-testid="buyer-name"
-      />
-      <Input
-        label="E-mail"
-        type="email"
-        variant="outlined"
-        size="md"
-        fullWidth
-        autoComplete="email"
-        value={value.email ?? ""}
-        error={Boolean(errors.email)}
-        helperText={errors.email}
-        onChange={(event) => onChange({ ...value, email: event.target.value })}
-        data-testid="buyer-email"
-      />
-      <Input
-        label="Telefone"
-        type="tel"
-        variant="outlined"
-        size="md"
-        fullWidth
-        autoComplete="tel"
-        value={value.phone ?? ""}
-        error={Boolean(errors.phone)}
-        helperText={errors.phone}
-        onChange={(event) => onChange({ ...value, phone: event.target.value })}
-        data-testid="buyer-phone"
-      />
-    </>
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 2 }}>
+      <Text variant="caption" size="xs" color="secondary" as="p">
+        {instructionFor(required)}
+      </Text>
+
+      {shown.map((key) => (
+        <BuyerInput
+          key={key}
+          fieldKey={key}
+          value={value}
+          required={required.has(key)}
+          error={errors[INPUTS[key].errorKey]}
+          onChange={onChange}
+        />
+      ))}
+    </Box>
   );
 }

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

@@ -11,6 +11,17 @@ import { refreshCardPublicKey } from "./client";
 import type { CardChainLink } from "./method-capability";
 import type { SavedCardMeta } from "./types";
 
+/**
+ * The order-scoped key refresh, as a parameter (FUT-741).
+ *
+ * The self-heal is a call to OUR OWN mount, so it has to go through whichever
+ * transport the surrounding checkout was bound to. Defaulted to the unbound
+ * module function, which is exactly what it always called.
+ */
+export type RefreshBrowserKey = (input: {
+  orderId: string;
+}) => Promise<Result<{ publicKey: string | null }>>;
+
 /**
  * TOKENIZATION for the buyer's card — one instrument per provider the charge
  * may reach (FUT-563).
@@ -39,12 +50,13 @@ async function tokenizeNewCard(
   config: CardTokenizationConfig,
   orderId: string,
   onKeyRefreshed: (key: string) => void,
+  refreshKey: RefreshBrowserKey,
 ): 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 });
+  const refreshed = await refreshKey({ orderId });
   if (refreshed.ok && refreshed.data.publicKey && refreshed.data.publicKey !== config.publicKey) {
     onKeyRefreshed(refreshed.data.publicKey);
     return tokenizeForCheckout(card, { ...config, publicKey: refreshed.data.publicKey });
@@ -166,6 +178,46 @@ function mintingConfig(
   return mintable.some((link) => link.provider === config.provider) ? config : mintable[0]!;
 }
 
+/**
+ * Mint for the whole chain at once, and say which entry the bare token is from.
+ *
+ * Head and tail mint CONCURRENTLY. Sequentially, one unreachable backup
+ * acquirer held a healthy head's charge for as long as the network stack
+ * allowed — the failover feature blocking on the provider it exists to fall
+ * back to. The head keeps no deadline: it is the provider being paid, and its
+ * self-heal is a second round trip of our own. That self-heal also stays
+ * PagBank-only — `tokenizeNewCard` gates on the scheme — so a chain headed
+ * elsewhere cannot ask for somebody else's key.
+ */
+async function mintEveryEntry(input: {
+  card: CardDetails;
+  entries: readonly CardChainLink[];
+  config: CardTokenizationConfig;
+  orderId: string;
+  onKeyRefreshed: (key: string) => void;
+  refreshKey: RefreshBrowserKey;
+  timeoutMs: number;
+}): Promise<{ headToken: Result<CardToken>; minted: Record<string, CardToken> }> {
+  const head = mintingConfig(input.config, input.entries);
+  const rest = input.entries.filter((link) => link.provider !== head.provider);
+  const [headToken, tail] = await Promise.all([
+    tokenizeNewCard(input.card, head, input.orderId, input.onKeyRefreshed, input.refreshKey),
+    mintChainInstruments(input.card, rest, input.timeoutMs),
+  ]);
+  // A failure in the tail is not fatal: that provider is simply one the walk
+  // will skip.
+  const minted = { ...tail };
+  if (headToken.ok && head.provider) minted[head.provider] = headToken.data;
+  return { headToken, minted };
+}
+
+/** The instruments, reduced to the provider→token map the charge body carries. */
+function tokenMapOf(minted: Record<string, CardToken>): Record<string, string> {
+  return Object.fromEntries(
+    Object.entries(minted).map(([provider, instrument]) => [provider, instrument.token]),
+  );
+}
+
 /** The charge token for a new card (tokenize + self-heal), plus optional save-meta. */
 export async function resolveNewCardToken(
   card: CardDetails,
@@ -176,36 +228,28 @@ export async function resolveNewCardToken(
   chain: readonly CardChainLink[],
   /** Per-entry mint deadline. Overridable so tests need not wait it out. */
   timeoutMs: number = MINT_TIMEOUT_MS,
+  /** The bound key refresh (FUT-741); defaults to the unbound module call. */
+  refreshKey: RefreshBrowserKey = refreshCardPublicKey,
 ): Promise<Result<CardInstruments>> {
   // No chain served (an older host, or a fetch blip): the active provider
   // alone, exactly the pre-FUT-563 behaviour.
   const entries = chain.length > 0 ? chain : [{ ...config, mintable: true }];
-  const head = mintingConfig(config, entries);
-  // The self-heal rides along and stays PagBank-only — `tokenizeNewCard` gates
-  // on its scheme, so a chain headed elsewhere cannot ask for someone's key.
-  // Head and tail mint CONCURRENTLY. Sequentially, one unreachable backup
-  // acquirer held a healthy head's charge for as long as the network stack
-  // allowed — the failover feature blocking on the provider it exists to fall
-  // back to. The head keeps no deadline: it is the provider being paid, and
-  // its self-heal is a second round trip of our own.
-  const rest = entries.filter((link) => link.provider !== head.provider);
-  const [headToken, tail] = await Promise.all([
-    tokenizeNewCard(card, head, orderId, onKeyRefreshed),
-    mintChainInstruments(card, rest, timeoutMs),
-  ]);
-  // A failure in the tail is not fatal: that provider is simply one the walk
-  // will skip.
-  const minted = { ...tail };
-  if (headToken.ok && head.provider) minted[head.provider] = headToken.data;
+  const { headToken, minted } = await mintEveryEntry({
+    card,
+    entries,
+    config,
+    orderId,
+    onKeyRefreshed,
+    refreshKey,
+    timeoutMs,
+  });
 
   // Refused only when NO entry could be minted for. While one still can, the
   // charge goes out and the entries we hold nothing for are skipped by name.
   const anyMinted = Object.values(minted);
   if (!headToken.ok && anyMinted.length === 0) return headToken;
   const primary = headToken.ok ? headToken.data : anyMinted[0]!;
-  const tokensByProvider = Object.fromEntries(
-    Object.entries(minted).map(([provider, instrument]) => [provider, instrument.token]),
-  );
+  const tokensByProvider = tokenMapOf(minted);
   return ok({
     token: primary.token,
     // Sent whenever the WALK has more than one provider to reach — counted on

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

@@ -1,6 +1,7 @@
 import { Box } from "@mui/material";
-import type { JSX, ReactNode } from "react";
+import { useMemo, type JSX, type ReactNode } from "react";
 
+import { buyerFieldsFor } from "./buyer-fields";
 import { DadosStep, EmptyCart, PaymentStep } from "./checkout-steps";
 import { ArrowBackIcon } from "./icons";
 import { PaymentStatus } from "./payment-status";
@@ -118,7 +119,12 @@ function ProgressHeader({ step, completed }: { step: string; completed: Set<stri
  */
 function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Element {
   const { cart, defaultBuyer, comanda, taxIdOnFile = false, providerConfig, tenantSlug, confirmationExtra, ...ports } = props;
-  const c = useCheckoutController(ports, defaultBuyer, taxIdOnFile);
+  // Resolved for NO method on purpose (FUT-595): the Dados step opens before
+  // the picker, and the form is filled once — so it asks for the union of what
+  // any chain member may need rather than re-opening after the choice. A chain
+  // that declares nothing degrades to CPF-required, never to "ask nothing".
+  const buyerFields = useMemo(() => buyerFieldsFor(providerConfig?.chain, null), [providerConfig]);
+  const c = useCheckoutController(ports, defaultBuyer, taxIdOnFile, buyerFields);
 
   // A comanda settlement pays already-sent kitchen items — the cart is
   // legitimately empty here, so the empty-cart guard only applies to cart mode.
@@ -147,6 +153,7 @@ function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Ele
           errorField={c.errorField}
           onContinue={c.goToPayment}
           cartTotals={cart}
+          buyerFields={buyerFields}
           discountLines={cart.discountLines}
           totalOverride={comandaTotalOverride(comanda)}
         />