@12-apps/payments-frontend 1.0.0 → 1.2.1

package/src/components/checkout/__tests__/card-3ds-handover.test.tsx

@@ -0,0 +1,147 @@
+// @vitest-environment jsdom
+/**
+ * FUT-698 — "Dado uma loja Stripe, quando o comprador paga com um cartão que
+ * exige 3DS, então ele é levado ao desafio" — the browser-unreachable half of
+ * that scenario (the stub adapter settles cards inline, so no e2e journey can
+ * produce a real challenge). The return half — "e volta com o pedido pago
+ * exatamente uma vez" — is the hosted-return machinery, pinned in
+ * hosted-return.test.ts and settled server-side by the idempotent webhook path.
+ *
+ * The charge answers `hostedCheckoutUrl` and the card hook must hand the buyer
+ * over exactly as a redirect provider's link does (FUT-556): park the order,
+ * navigate, and start NO poll in a tab that is being torn down.
+ */
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import type { JSX } from "react";
+
+const client = vi.hoisted(() => ({
+  chargeCard: vi.fn(),
+  listSavedCards: vi.fn(),
+  refreshCardPublicKey: vi.fn(),
+  pollOrderStatus: vi.fn(),
+  fetchCheckoutConfig: vi.fn(),
+}));
+
+vi.mock("../client", () => client);
+
+import type { CardTokenizationConfig } from "../../../card";
+import type { CheckoutOrder, OrderStatus } from "../types";
+import { useCardCheckout } from "../use-card-checkout";
+
+const ORDER: CheckoutOrder = {
+  orderId: "o1",
+  status: "AWAITING_PAYMENT",
+  method: "CARD",
+  totalCents: 1250,
+  subtotalCents: 1250,
+  discountTotalCents: 0,
+  appliedDiscounts: [],
+  totalLabel: "R$ 12,50",
+};
+
+const STRIPE_CONFIG: CardTokenizationConfig = {
+  provider: "stripe",
+  publicKey: "pk_test_1",
+  mockTokenization: false,
+};
+
+/** A saved card, so paying skips tokenization and goes straight to the charge. */
+const SAVED_CARD = {
+  id: "card-1",
+  brand: "visa",
+  last4: "4242",
+  expMonth: 12,
+  expYear: 2033,
+  holder: "OLGA STONE",
+};
+
+function Harness({ onResolved }: { onResolved: (status: OrderStatus) => void }): JSX.Element {
+  const cc = useCardCheckout(ORDER, {}, STRIPE_CONFIG, onResolved, 10, "acme");
+  return (
+    <div>
+      <span data-testid="submitted">{String(cc.submitted)}</span>
+      <span data-testid="selection">{cc.selection}</span>
+      <button type="button" data-testid="pay" onClick={() => void cc.handlePay()}>
+        Pagar
+      </button>
+    </div>
+  );
+}
+
+/** Render, wait for the saved card to be SELECTED, and tap Pagar. */
+async function pay(onResolved = vi.fn()): Promise<void> {
+  render(<Harness onResolved={onResolved} />);
+  // Selection — not merely the fetch — is what routes handlePay past the
+  // empty new-card form; clicking earlier validates that form and stops.
+  await waitFor(() => {
+    expect(screen.getByTestId("selection").textContent).toBe("card-1");
+  });
+  fireEvent.click(screen.getByTestId("pay"));
+}
+
+const assign = vi.fn();
+
+beforeEach(() => {
+  vi.clearAllMocks();
+  window.sessionStorage.clear();
+  client.listSavedCards.mockResolvedValue([SAVED_CARD]);
+  client.pollOrderStatus.mockResolvedValue({ ok: true, data: "AWAITING_PAYMENT" });
+  vi.stubGlobal("location", { search: "", assign });
+});
+
+afterEach(() => {
+  cleanup();
+  vi.unstubAllGlobals();
+  window.sessionStorage.clear();
+});
+
+describe("card charge → 3DS handover (FUT-698)", () => {
+  it("hands the buyer to the challenge page with the order parked for the return trip", async () => {
+    client.chargeCard.mockResolvedValue({
+      ok: true,
+      data: { status: "AWAITING_PAYMENT", hostedCheckoutUrl: "https://hooks.stripe.com/3ds/x" },
+    });
+    const onResolved = vi.fn();
+
+    await pay(onResolved);
+
+    await waitFor(() => {
+      expect(assign).toHaveBeenCalledWith("https://hooks.stripe.com/3ds/x");
+    });
+    // Parked exactly as the redirect-provider handoff parks (FUT-556), so the
+    // return trip resumes THIS order's confirmation screen.
+    const parked = window.sessionStorage.getItem("futurepay.checkout.hostedOrder");
+    expect(parked).not.toBeNull();
+    expect((JSON.parse(parked as string) as { orderId: string }).orderId).toBe("o1");
+    // The tab is navigating away: nothing resolved, no poll started here.
+    expect(onResolved).not.toHaveBeenCalled();
+    expect(client.pollOrderStatus).not.toHaveBeenCalled();
+    expect(screen.getByTestId("submitted").textContent).toBe("false");
+  });
+
+  it("an accepted charge WITHOUT a challenge begins polling instead of navigating", async () => {
+    client.chargeCard.mockResolvedValue({ ok: true, data: { status: "AWAITING_PAYMENT" } });
+
+    await pay();
+
+    await waitFor(() => {
+      expect(screen.getByTestId("submitted").textContent).toBe("true");
+    });
+    expect(assign).not.toHaveBeenCalled();
+    expect(window.sessionStorage.getItem("futurepay.checkout.hostedOrder")).toBeNull();
+  });
+
+  it("a decline resolves to the status screen, never a handover", async () => {
+    client.chargeCard.mockResolvedValue({ ok: true, data: { status: "FAILED" } });
+    const onResolved = vi.fn();
+
+    await pay(onResolved);
+
+    await waitFor(() => {
+      expect(onResolved).toHaveBeenCalledWith("FAILED");
+    });
+    expect(assign).not.toHaveBeenCalled();
+  });
+});

package/src/components/checkout/__tests__/clear-cart-on-paid.test.tsx

@@ -0,0 +1,64 @@
+// @vitest-environment jsdom
+/**
+ * A buyer who paid must not be handed their cart back.
+ *
+ * FUT-601 fixed the SERVER half: the cart is emptied inside the confirmation
+ * transaction, for the delivery that won the claim. Nothing told the SPA — its
+ * cart provider survives every checkout route change and kept the snapshot it
+ * seeded on mount, so the buyer pressed "Voltar ao cardápio" and found the
+ * badge still counting the items they had just bought.
+ *
+ * Since FUT-564 the flow lives in this package and the cart lives in the host,
+ * so the client half of that fix is a PORT: `onPaid` fires when — and only
+ * when — the order settles PAID. The host re-reads its server-emptied cart
+ * there; a payment that did not go through fires nothing, because that shopper
+ * still has a basket to retry with.
+ */
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { useCheckoutController, type CheckoutHostPorts } from "../use-checkout-controller";
+
+/** One test's own port set — every callback a fresh spy. */
+function makePorts(): CheckoutHostPorts & { onPaid: ReturnType<typeof vi.fn> } {
+  return {
+    createOrder: vi.fn(),
+    saveBuyerContact: vi.fn(),
+    onExitToMenu: vi.fn(),
+    onPaid: vi.fn(),
+  };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe("the host's onPaid port after a checkout settles", () => {
+  it("fires once the order is PAID", async () => {
+    const ports = makePorts();
+    const { result } = renderHook(() => useCheckoutController(ports));
+
+    act(() => {
+      result.current.handleResolved("PAID");
+    });
+
+    await waitFor(() => {
+      expect(ports.onPaid).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  it("stays silent when the payment failed", async () => {
+    const ports = makePorts();
+    const { result } = renderHook(() => useCheckoutController(ports));
+
+    act(() => {
+      result.current.handleResolved("FAILED");
+    });
+
+    // The step advanced, so the effect has had its chance to run.
+    await waitFor(() => {
+      expect(result.current.finalStatus).toBe("FAILED");
+    });
+    expect(ports.onPaid).not.toHaveBeenCalled();
+  });
+});

package/src/components/checkout/__tests__/hosted-return.test.ts

@@ -0,0 +1,109 @@
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import { rememberHostedOrder, takeHostedOrder } from "../hosted-return";
+import type { CheckoutOrder } from "../types";
+
+/**
+ * FUT-556 — surviving the trip to a hosted checkout.
+ *
+ * A redirect provider tears the SPA down. These pin the two rules that keep the
+ * return from landing on a blank payment step, and keep an ABANDONED payment
+ * from resurfacing as if it had happened: the parked order is handed back only
+ * on a return trip, and only once.
+ */
+
+const ORDER: CheckoutOrder = {
+  orderId: "o1",
+  status: "AWAITING_PAYMENT",
+  method: "PIX",
+  totalCents: 550,
+  subtotalCents: 550,
+  discountTotalCents: 0,
+  appliedDiscounts: [],
+  totalLabel: "R$ 5,50",
+};
+
+/** Put the tab on `search`, the way the provider's redirect leaves it. */
+function land(search: string): void {
+  window.history.replaceState({}, "", `/future-drink/menu/checkout${search}`);
+}
+
+describe("hosted-return", () => {
+  beforeEach(() => {
+    window.sessionStorage.clear();
+    land("");
+  });
+  afterEach(() => {
+    window.sessionStorage.clear();
+  });
+
+  it("hands the order back when the provider sent the buyer home", () => {
+    rememberHostedOrder(ORDER);
+    land("?transaction_nsu=123&slug=abc");
+
+    expect(takeHostedOrder()).toEqual(ORDER);
+  });
+
+  it("recognises a return that carries only one of the markers", () => {
+    rememberHostedOrder(ORDER);
+    land("?slug=abc");
+
+    expect(takeHostedOrder()?.orderId).toBe("o1");
+  });
+
+  it("recognises a buyer coming back from a Stripe 3DS challenge (FUT-698)", () => {
+    // What Stripe appends to the card confirm's `return_url` after the issuer
+    // page: the intent id, its client secret and the redirect verdict.
+    rememberHostedOrder(ORDER);
+    land("?payment_intent=pi_1&payment_intent_client_secret=pi_1_secret&redirect_status=succeeded");
+
+    expect(takeHostedOrder()?.orderId).toBe("o1");
+  });
+
+  it("still recognises the hosted-store return exactly as before (FUT-556)", () => {
+    // The InfinitePay handoff must keep working with the Stripe markers added:
+    // "loja hospedada continua com o hand-off e retorno de hoje".
+    rememberHostedOrder(ORDER);
+    land("?transaction_nsu=123&slug=abc&order_nsu=o1");
+
+    expect(takeHostedOrder()?.orderId).toBe("o1");
+  });
+
+  it("ignores a parked order when this is not a return trip", () => {
+    rememberHostedOrder(ORDER);
+    land("");
+
+    // A buyer who abandoned the provider's page and came back to checkout later
+    // must start a fresh order, not resume one they never paid.
+    expect(takeHostedOrder()).toBeNull();
+  });
+
+  it("hands the order back exactly once", () => {
+    rememberHostedOrder(ORDER);
+    land("?transaction_nsu=123");
+
+    expect(takeHostedOrder()).not.toBeNull();
+    expect(takeHostedOrder()).toBeNull();
+  });
+
+  it("answers null for a value that is not an order", () => {
+    window.sessionStorage.setItem("futurepay.checkout.hostedOrder", '{"nonsense":true}');
+    land("?transaction_nsu=123");
+
+    expect(takeHostedOrder()).toBeNull();
+  });
+
+  it("answers null for unparseable storage rather than throwing", () => {
+    window.sessionStorage.setItem("futurepay.checkout.hostedOrder", "{not json");
+    land("?transaction_nsu=123");
+
+    expect(takeHostedOrder()).toBeNull();
+  });
+
+  it("answers null when nothing was parked", () => {
+    land("?transaction_nsu=123");
+
+    expect(takeHostedOrder()).toBeNull();
+  });
+});

package/src/components/checkout/__tests__/method-capability.test.tsx

@@ -0,0 +1,120 @@
+// @vitest-environment jsdom
+/**
+ * FUT-698 — the method picker derives its options from the chain's declared
+ * capabilities (`capabilities.methods`, surfaced by `GET /api/checkout/config`).
+ *
+ * These are the browser-unreachable halves of the ticket's "método sem suporte
+ * na cadeia não aparece no picker" scenario: every adapter shipped today
+ * declares PIX and CARD, so the missing-method case only exists synthetically.
+ * Test names keep the scenario's Given/When/Then. Rendered with NO slot
+ * provider on purpose (raw-MUI defaults carry the load-bearing test ids);
+ * jest-dom is not a dependency here — DOM properties are asserted directly.
+ */
+import { cleanup, render, screen } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { PaymentStep } from "../checkout-steps";
+import { MethodPicker } from "../method-picker";
+import type { CheckoutProviderConfig } from "../types";
+
+afterEach(() => {
+  cleanup();
+});
+
+function config(methods: CheckoutProviderConfig["methods"]): CheckoutProviderConfig {
+  return {
+    provider: "stone",
+    tokenization: "PUBLIC_KEY",
+    publicKey: "pk_stone",
+    mockTokenization: false,
+    methods,
+  };
+}
+
+/** Render the Pagamento step with no order raised — just the picker. */
+function renderPaymentStep(providerConfig: CheckoutProviderConfig | null): void {
+  render(
+    <PaymentStep
+      method={null}
+      onMethodChange={vi.fn()}
+      order={null}
+      buyer={{}}
+      creating={false}
+      createError={null}
+      errorField={null}
+      onGenerate={vi.fn()}
+      onUseEmail={vi.fn()}
+      providerConfig={providerConfig}
+      onResolved={vi.fn()}
+    />,
+  );
+}
+
+/** The offered methods, read off the rendered radiogroup's testids. */
+function offeredTestIds(): string[] {
+  return Array.from(
+    screen.getByTestId("checkout-method").querySelectorAll("[data-testid^='checkout-method-']"),
+  ).map((option) => option.getAttribute("data-testid") ?? "");
+}
+
+describe("MethodPicker — method by capability (FUT-698)", () => {
+  it("given the chain cannot PIX, when the picker renders, then PIX is not offered", () => {
+    render(<MethodPicker value={null} onChange={vi.fn()} offered={["CARD"]} />);
+
+    expect(offeredTestIds()).toEqual(["checkout-method-CARD"]);
+  });
+
+  it("given the chain cannot CARD, when the picker renders, then CARD is not offered", () => {
+    render(<MethodPicker value={null} onChange={vi.fn()} offered={["PIX"]} />);
+
+    expect(offeredTestIds()).toEqual(["checkout-method-PIX"]);
+  });
+
+  it("given the config has not answered yet, then every method renders (fail open)", () => {
+    render(<MethodPicker value={null} onChange={vi.fn()} offered={null} />);
+
+    expect(offeredTestIds()).toEqual(["checkout-method-PIX", "checkout-method-CARD"]);
+  });
+
+  it("card-path gating still wins over a chain that declares CARD", () => {
+    // The chain CAN charge cards, but this browser has no way to mint one
+    // (no scheme/key/stub) — the tile stays visible but DISABLED with a caption
+    // (FUT-697 review): a removed tile would leave an unexplained one-option
+    // "choice", while a disabled one says why.
+    render(
+      <MethodPicker value={null} onChange={vi.fn()} offered={["PIX", "CARD"]} cardUnavailable />,
+    );
+
+    expect(offeredTestIds()).toEqual(["checkout-method-PIX", "checkout-method-CARD"]);
+    const cardTile = screen.getByTestId("checkout-method-CARD") as HTMLButtonElement;
+    expect(cardTile.disabled).toBe(true);
+    expect(screen.getByText("Indisponível nesta loja")).toBeTruthy();
+  });
+});
+
+describe("PaymentStep — the config's methods reach the picker (FUT-698)", () => {
+  it("given a chain that only PIXes, when Pagamento renders, then card is never offered", () => {
+    renderPaymentStep(config(["PIX"]));
+
+    expect(offeredTestIds()).toEqual(["checkout-method-PIX"]);
+  });
+
+  it("given a chain that declares BOLETO, then only methods the checkout can drive appear", () => {
+    renderPaymentStep(config(["PIX", "CARD", "BOLETO"]));
+
+    // Stone/Stripe declare BOLETO server-side (true), but this checkout has no
+    // boleto UI yet (phase 2) — the picker offers only what it can honour.
+    expect(screen.getByTestId("checkout-method-PIX")).toBeTruthy();
+    expect(screen.getByTestId("checkout-method-CARD")).toBeTruthy();
+    expect(screen.getByTestId("checkout-method").querySelectorAll("[role='radio']")).toHaveLength(
+      2,
+    );
+  });
+
+  it("given no config yet, then Pagamento offers both methods as before", () => {
+    renderPaymentStep(null);
+
+    expect(screen.getByTestId("checkout-method-PIX")).toBeTruthy();
+    expect(screen.getByTestId("checkout-method-CARD")).toBeTruthy();
+  });
+});

package/src/components/checkout/__tests__/payments-unavailable.test.tsx

@@ -0,0 +1,53 @@
+// @vitest-environment jsdom
+import { cleanup, fireEvent, render, screen, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { PaymentsUnavailable } from "../payments-unavailable";
+
+/**
+ * A store with no active payment provider used to render the full payment step
+ * — PIX and Cartão — and fail only at order creation, telling the shopper
+ * "tente novamente em instantes": retry advice for a condition retrying never
+ * fixes. These pin the two honest answers instead.
+ *
+ * Rendered with NO slot provider on purpose: outside a
+ * `CheckoutComponentsProvider` the component falls back to the raw-MUI
+ * defaults, so this suite also pins that the default slots carry the
+ * load-bearing test ids. jest-dom is not a dependency here — DOM properties
+ * are asserted directly.
+ */
+
+afterEach(cleanup);
+
+describe("checkout — store cannot charge online", () => {
+  it("offers the waiter when the shopper has a mesa", async () => {
+    const onCallWaiter = vi.fn();
+    render(<PaymentsUnavailable waiterAvailable onCallWaiter={onCallWaiter} />);
+
+    expect(screen.getByTestId("checkout-call-waiter")).toBeTruthy();
+    fireEvent.click(screen.getByTestId("checkout-call-waiter-button"));
+    expect(onCallWaiter).toHaveBeenCalledTimes(1);
+
+    // Never the dead end: the shopper is not told to retry.
+    await waitFor(() => expect(screen.queryByText(/tente novamente/i)).toBeNull());
+  });
+
+  it("says plainly that the store does not charge online with no waiter to call", async () => {
+    render(<PaymentsUnavailable waiterAvailable={false} />);
+
+    expect(screen.getByTestId("checkout-payments-disabled")).toBeTruthy();
+    // No waiter reachable — offering one would be a dead button.
+    await waitFor(() => expect(screen.queryByTestId("checkout-call-waiter-button")).toBeNull());
+  });
+
+  it("renders no waiter button when the host supplies no handler", async () => {
+    render(<PaymentsUnavailable waiterAvailable />);
+    await waitFor(() => expect(screen.queryByTestId("checkout-call-waiter-button")).toBeNull());
+  });
+
+  it("disables the waiter button while the request is in flight", () => {
+    render(<PaymentsUnavailable waiterAvailable onCallWaiter={vi.fn()} calling />);
+    const button = screen.getByTestId("checkout-call-waiter-button") as HTMLButtonElement;
+    expect(button.disabled).toBe(true);
+  });
+});

package/src/components/checkout/__tests__/save-on-continue.test.tsx

@@ -0,0 +1,165 @@
+// @vitest-environment jsdom
+/**
+ * The buyer's details must be persisted when they press "Continuar" on the
+ * "Dados" step — NOT when a payment is raised.
+ *
+ * This is a regression test with a history: the save used to live only in the
+ * order-creation path, which runs a whole step later, only once a payment
+ * method is chosen, and which deliberately never writes the CPF. A buyer who
+ * filled the form and then hit anything at all on the payment screen — no
+ * provider configured, a declined card, an abandoned PIX, a closed tab — had
+ * nothing stored.
+ *
+ * Since FUT-564 the write itself belongs to the host (`saveBuyerContact` port;
+ * the storefront's implementation owns the wire shape and the blank-CPF-never-
+ * clears rule, pinned in its own suite). What THIS suite pins is the flow's
+ * side of the contract — TIMING, CONSENT and INDEPENDENCE: the port fires on
+ * "Continuar", carries the CPF, respects the LGPD checkbox, and the step
+ * advances no matter what the host does with the call.
+ */
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { useCheckoutController, type CheckoutHostPorts } from "../use-checkout-controller";
+import type { BuyerContact } from "../types";
+
+/** A valid CPF (passes the client-side check digits). */
+const VALID_CPF = "52998224725";
+
+/**
+ * One test's own port set + recorder. Everything is a local — no module-level
+ * mutable state, so the tests carry no order dependency between them
+ * (`test-flakiness/no-test-isolation`). The stub only ever PUSHES onto its
+ * container, never reassigns a closed-over binding (`no-global-state-mutation`).
+ */
+function makePorts(): {
+  ports: CheckoutHostPorts;
+  savedContacts: () => BuyerContact[];
+  orderRequested: () => boolean;
+} {
+  const recorded: BuyerContact[] = [];
+  const createOrder = vi.fn();
+  return {
+    ports: {
+      createOrder,
+      saveBuyerContact: (contact) => {
+        recorded.push(contact);
+      },
+      onExitToMenu: vi.fn(),
+    },
+    savedContacts: () => recorded,
+    orderRequested: () => createOrder.mock.calls.length > 0,
+  };
+}
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('"Dados" step persists the buyer on Continuar', () => {
+  it("saves name, phone and CPF the moment Continuar is pressed", async () => {
+    const { ports, savedContacts, orderRequested } = makePorts();
+    const { result } = renderHook(() => useCheckoutController(ports));
+
+    act(() => {
+      result.current.setBuyer({ name: "Ana", phone: "11999999999", taxId: VALID_CPF });
+    });
+    act(() => {
+      result.current.goToPayment();
+    });
+
+    await waitFor(() => expect(savedContacts()).toHaveLength(1));
+    expect(savedContacts()[0]).toEqual({
+      name: "Ana",
+      phone: "11999999999",
+      taxId: VALID_CPF,
+    });
+    // The whole point: no order was created, and none needed to be.
+    expect(orderRequested()).toBe(false);
+  });
+
+  it("advances to Pagamento without waiting on the save", async () => {
+    const { ports, savedContacts } = makePorts();
+    // A host whose save blows up must not trap the buyer on the Dados step —
+    // the port is fire-and-forget, so the flow never sees the failure at all.
+    const { result } = renderHook(() => useCheckoutController(ports));
+
+    act(() => {
+      result.current.setBuyer({ name: "Ana", taxId: VALID_CPF });
+    });
+    act(() => {
+      result.current.goToPayment();
+    });
+
+    await waitFor(() => expect(savedContacts()).toHaveLength(1));
+    expect(result.current.step).toBe("payment");
+  });
+
+  it("does not save when the buyer declined the consent checkbox", async () => {
+    const { ports, savedContacts } = makePorts();
+    const { result } = renderHook(() => useCheckoutController(ports));
+
+    act(() => {
+      result.current.setBuyer({ name: "Ana", taxId: VALID_CPF });
+      result.current.setSaveProfile(false);
+    });
+    act(() => {
+      result.current.goToPayment();
+    });
+
+    await waitFor(() => expect(result.current.step).toBe("payment"));
+    expect(savedContacts()).toHaveLength(0);
+  });
+
+  it("does not save — or advance — when the CPF is invalid", async () => {
+    const { ports, savedContacts } = makePorts();
+    const { result } = renderHook(() => useCheckoutController(ports));
+
+    act(() => {
+      result.current.setBuyer({ name: "Ana", taxId: "11111111111" });
+    });
+    act(() => {
+      result.current.goToPayment();
+    });
+
+    await waitFor(() => expect(result.current.errorField).toBe("cpf"));
+    expect(result.current.step).toBe("dados");
+    expect(savedContacts()).toHaveLength(0);
+  });
+
+  it("lets a buyer with a CPF on file continue without retyping it", async () => {
+    const { ports, savedContacts } = makePorts();
+    // Third argument: the buyer already gave the store a CPF, so Dados was
+    // skipped and they reopened it through "Alterar". The field starts empty
+    // (the client never receives the saved value) — requiring one here stranded
+    // them on a form they had no way to satisfy.
+    const { result } = renderHook(() => useCheckoutController(ports, undefined, true));
+
+    act(() => {
+      result.current.setStep("dados");
+    });
+    act(() => {
+      result.current.goToPayment();
+    });
+
+    await waitFor(() => expect(result.current.step).toBe("payment"));
+    expect(result.current.errorField).toBeNull();
+    // Nothing typed ⇒ the port carries no values at all. What the HOST must do
+    // with a blank CPF (omit it so it can never clear the stored one) is the
+    // host's contract, pinned beside its `saveBuyerContact` implementation.
+    expect(savedContacts()[0]).toEqual({ name: undefined, phone: undefined, taxId: undefined });
+  });
+
+  it("still demands a CPF from a buyer who has none on file", async () => {
+    const { ports, savedContacts } = makePorts();
+    const { result } = renderHook(() => useCheckoutController(ports));
+
+    act(() => {
+      result.current.goToPayment();
+    });
+
+    await waitFor(() => expect(result.current.errorField).toBe("cpf"));
+    expect(result.current.step).toBe("dados");
+    expect(savedContacts()).toHaveLength(0);
+  });
+});