@12-apps/payments-frontend 1.18.0 → 1.19.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "1.18.0",
+  "version": "1.19.0",
   "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": {
@@ -17,7 +17,7 @@
     "storybook:build": "storybook build"
   },
   "dependencies": {
-    "@12-apps/payments-backend": "^1.18.0",
+    "@12-apps/payments-backend": "^1.22.0",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

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

@@ -26,7 +26,7 @@ import {
   pollOrderStatus,
   refreshCardPublicKey,
 } from "./client";
-import type { CheckoutClient } from "./transport";
+import { createCheckoutClient, type CheckoutClient } from "./transport";
 
 /** The unbound client: `/api/checkout` on the ambient `fetch`. */
 const DEFAULT_CLIENT: CheckoutClient = {
@@ -35,6 +35,11 @@ const DEFAULT_CLIENT: CheckoutClient = {
   charge: (input) => chargeCard(input),
   chargeWallet: (input) => chargeWallet(input),
   listInstruments: (tenantSlug) => listSavedCards(tenantSlug),
+  // The vault pair (FUT-183) has no `client.ts` free function to bind — it is
+  // newer than that module. Built lazily from the default transport instead,
+  // which is the same wire: `/api/checkout`, ambient `fetch` resolved per call.
+  beginVault: () => createCheckoutClient().beginVault(),
+  completeVault: (input) => createCheckoutClient().completeVault(input),
   refreshBrowserKey: (input) => refreshCardPublicKey(input),
 };
 

package/src/components/checkout/transport.ts

@@ -2,7 +2,7 @@
  * The checkout's HTTP transport, as a bound client (FUT-741).
  *
  * Everything `client.ts` used to do with a hard-coded prefix and the ambient
- * `fetch` now lives here behind {@link createCheckoutClient}, so the same five
+ * `fetch` now lives here behind {@link createCheckoutClient}, so the same
  * calls can be pointed at a different mount, carry a host's auth headers, or —
  * the reason this exists — be driven through an injected `fetch` that routes
  * straight into a real `createPaymentFlowsBE` mount. A story or a harness page
@@ -15,6 +15,8 @@
  * shipped contract in the same release that introduces the factory.
  */
 
+import type { BuyerVaultSession, VaultedCardDisplay } from "@12-apps/payments-backend";
+
 import type { SavedCard } from "../../card";
 import { err, ok, type Result } from "../../result";
 
@@ -26,6 +28,28 @@ import type {
   OrderStatus,
 } from "./types";
 
+/**
+ * The two buyer-vault answer shapes (FUT-478/FUT-183), imported as TYPES from
+ * the backend package rather than mirrored: `/cards/begin` and `/cards/complete`
+ * are new rows with no older-host degrade story to encode, so a mirror here
+ * would only be a copy that can drift from the wire it names. Re-exported for
+ * the same reason `PaymentEnvironment` is on the barrel — a host typing its
+ * own callback must not need a direct backend dependency.
+ */
+export type { BuyerVaultSession, VaultedCardDisplay };
+
+/**
+ * The browser's two legitimate contributions to `POST /cards/complete`: the
+ * session it confirmed, and — for a sessionless PUBLIC_KEY provider — the
+ * encrypted card blob. The ownership facts (`reference`, `customerRef`) are
+ * answered server-side by the host's vault port and are NOT here on purpose:
+ * a body naming them is ignored by the mount.
+ */
+export interface CompleteVaultInput {
+  sessionId?: string;
+  token?: string;
+}
+
 /**
  * The prefix every shipped buyer checkout posts to today. Exported so a host
  * (or a test) can state it rather than re-type it, and so a change to it is a
@@ -35,7 +59,10 @@ export const DEFAULT_CHECKOUT_BASE_URL = "/api/checkout";
 
 /** Where the `createPaymentFlowsBE` mount lives, and how to reach it. */
 export interface CheckoutTransport {
-  /** Prefix for `/config`, `/status`, `/charge`, `/cards`, `/refresh-key`. */
+  /**
+   * Prefix for `/config`, `/status`, `/charge`, `/cards`, `/cards/begin`,
+   * `/cards/complete`, `/refresh-key`.
+   */
   baseUrl?: string;
   /**
    * The `fetch` to call. Omitted ⇒ the ambient one, resolved PER CALL so a
@@ -46,7 +73,7 @@ export interface CheckoutTransport {
   headers?: () => HeadersInit | Promise<HeadersInit>;
 }
 
-/** The six calls the buyer checkout makes, pre-bound to a {@link CheckoutTransport}. */
+/** The eight calls the buyer checkout makes, pre-bound to a {@link CheckoutTransport}. */
 export interface CheckoutClient {
   getConfig(tenantSlug: string): Promise<Result<CheckoutProviderConfig>>;
   getStatus(ref: string): Promise<Result<OrderStatus>>;
@@ -54,6 +81,18 @@ export interface CheckoutClient {
   /** A wallet instrument against the same `/charge` route (FUT-471/472). */
   chargeWallet(input: ChargeWalletInput): Promise<Result<ChargeOutcome>>;
   listInstruments(tenantSlug?: string): Promise<SavedCard[]>;
+  /**
+   * `POST /cards/begin` (FUT-478): equip the browser to mint an instrument
+   * OUTSIDE a purchase. The answer names the tokenization scheme, the public
+   * key when the provider has one, and the session to echo to `completeVault`.
+   */
+  beginVault(): Promise<Result<BuyerVaultSession>>;
+  /**
+   * `POST /cards/complete`: the provider accepted the card — the server stores
+   * the vault token against the caller and answers DISPLAY metadata only. The
+   * token that can charge never reaches the browser.
+   */
+  completeVault(input: CompleteVaultInput): Promise<Result<VaultedCardDisplay>>;
   refreshBrowserKey(input: { orderId: string }): Promise<Result<{ publicKey: string | null }>>;
 }
 
@@ -146,7 +185,20 @@ function flatWalletBody(input: ChargeWalletInput): string {
 }
 
 /**
- * The five checkout calls, bound to one transport.
+ * The wire body of `POST /cards/complete` — ONLY the browser's two facts, and
+ * each present only when it exists. `flows-vault.ts` reads exactly these two
+ * string fields (`browserVaultFacts`) and ignores everything else, so a field
+ * added here without a backend reader would be silently dropped.
+ */
+function completeVaultBody(input: CompleteVaultInput): string {
+  return JSON.stringify({
+    ...(input.sessionId ? { sessionId: input.sessionId } : {}),
+    ...(input.token ? { token: input.token } : {}),
+  });
+}
+
+/**
+ * The checkout calls, bound to one transport.
  *
  * Passing no transport reproduces exactly what the free functions in
  * `client.ts` have always done: `/api/checkout/**` on the ambient `fetch`.
@@ -203,6 +255,14 @@ export function createCheckoutClient(transport: CheckoutTransport = {}): Checkou
       return result.ok ? result.data : [];
     },
 
+    beginVault: () => call<BuyerVaultSession>("/cards/begin", { method: "POST" }),
+
+    completeVault: (input) =>
+      call<VaultedCardDisplay>("/cards/complete", {
+        method: "POST",
+        body: completeVaultBody(input),
+      }),
+
     refreshBrowserKey: (input) =>
       call<{ publicKey: string | null }>("/refresh-key", {
         method: "POST",

package/src/flows/copy.ts

@@ -3,10 +3,11 @@
  *
  * Scope is deliberately narrow and stated rather than implied: this covers the
  * copy the FACTORY owns — the unavailable screen's two remedies, the hosted
- * handover and its fallback link, the empty cart, and the buyer form's continue
- * action. The screens that already carried their own product copy before this
- * ticket (PIX, card, status) keep it; moving all of it here in the same change
- * that introduces the factory would be a copy rewrite disguised as an API.
+ * handover and its fallback link, the empty cart, the buyer form's continue
+ * action, and the add-card / manage-cards screens (FUT-183). The screens that
+ * already carried their own product copy before this ticket (PIX, card, status)
+ * keep it; moving all of it here in the same change that introduces the factory
+ * would be a copy rewrite disguised as an API.
  *
  * Every default below is today's pt-BR, verbatim — a host that passes no `copy`
  * reads exactly what a buyer reads now.
@@ -34,6 +35,19 @@ export interface CheckoutCopyFE {
   emptyCartAction: string;
   /** The Dados step's primary action. */
   continueAction: string;
+  /** The add-card screen (FUT-183): putting a card on file outside a purchase. */
+  addCardTitle: string;
+  addCardAction: string;
+  addCardPreparing: string;
+  addCardSavedTitle: string;
+  addCardSavedBody: string;
+  addCardFailedTitle: string;
+  /** The host wired no vaulting, or the provider cannot vault — the buyer can fix neither. */
+  addCardUnavailable: string;
+  /** The manage-cards screen: the buyer's cards on file, and the door to add one. */
+  manageCardsTitle: string;
+  manageCardsEmpty: string;
+  manageCardsAdd: string;
 }
 
 export const DEFAULT_CHECKOUT_COPY_FE: CheckoutCopyFE = {
@@ -54,4 +68,14 @@ export const DEFAULT_CHECKOUT_COPY_FE: CheckoutCopyFE = {
   emptyCartTitle: "Seu carrinho está vazio.",
   emptyCartAction: "Ver cardápio",
   continueAction: "Continuar",
+  addCardTitle: "Adicionar cartão",
+  addCardAction: "Salvar cartão",
+  addCardPreparing: "Preparando o formulário…",
+  addCardSavedTitle: "Cartão salvo",
+  addCardSavedBody: "Você poderá usá-lo nas próximas compras.",
+  addCardFailedTitle: "Não foi possível salvar o cartão",
+  addCardUnavailable: "Esta loja não aceita salvar cartões no momento.",
+  manageCardsTitle: "Meus cartões",
+  manageCardsEmpty: "Você ainda não tem cartões salvos.",
+  manageCardsAdd: "Adicionar cartão",
 };

package/src/flows/create-payment-flows.tsx

@@ -27,6 +27,7 @@ import { FlowsProvider, useResolvedConfig, type FlowsRuntime } from "./runtime";
 import { buyerScreens } from "./screens-buyer";
 import { hostedScreens } from "./screens-hosted";
 import { payScreens, storeCannotCharge } from "./screens-pay";
+import { vaultScreens } from "./screens-vault";
 import type {
   CheckoutAvailability,
   CheckoutController,
@@ -117,7 +118,7 @@ function buildCheckout(
   };
 }
 
-/** Assemble the eleven screens from their builders. */
+/** Assemble the thirteen screens from their builders. */
 function buildScreens(runtime: FlowsRuntime): CheckoutScreens {
   return {
     MethodChoice: buyerScreens.buildMethodChoice(runtime),
@@ -131,6 +132,8 @@ function buildScreens(runtime: FlowsRuntime): CheckoutScreens {
     PayerSummary: buyerScreens.buildPayerSummary(runtime),
     SavedCards: buyerScreens.buildSavedCards(runtime),
     EmptyCart: buyerScreens.buildEmptyCart(runtime),
+    AddCard: vaultScreens.buildAddCard(runtime),
+    ManageCards: vaultScreens.buildManageCards(runtime),
   };
 }
 

package/src/flows/screens-vault.tsx

@@ -0,0 +1,280 @@
+/**
+ * The factory's vault screens (FUT-183), the buyer half of FUT-478: adding a
+ * card OUTSIDE a purchase, and seeing the cards already on file.
+ *
+ * Same shape as every other factory screen: thin bindings over the shared
+ * card primitives, rendered through the `CheckoutComponents` slots, wrapped in
+ * `FlowsShell` so each one works standalone. The state machine lives in
+ * `use-add-card.ts`; the views here take its controller, which is also what
+ * lets a story stage any phase as a literal without touching a network.
+ *
+ * There is deliberately NO delete affordance on the manage screen: PagBank
+ * publishes no endpoint that deletes a stored card token, so a buyer-facing
+ * "remover cartão" could only fake the removal at the provider that most needs
+ * it. Taking a card off file stays a merchant/host concern, on the admin
+ * surface's named-provider `vault/:provider/forget` row (see the backend's
+ * `checkout/flows-vault.ts`) — which is also why S2 exposes no buyer forget
+ * for this screen to call.
+ */
+import { Box } from "@mui/material";
+import { useEffect, useState, type JSX } from "react";
+
+import { NewCardForm, type SavedCard } from "../card";
+import type { VaultedCardDisplay } from "../components/checkout/transport";
+import { useCheckoutComponents } from "../components/checkout/ui";
+
+import type { CheckoutCopyFE } from "./copy";
+import { FlowsShell, type FlowsRuntime } from "./runtime";
+import type { CheckoutScreens } from "./types";
+import { useAddCard, type AddCardController } from "./use-add-card";
+
+/** `visa •••• 4242`, or just the brand when the provider shared no last4. */
+function displayLabel(display: VaultedCardDisplay): string {
+  const brand = display.brand ?? "Cartão";
+  return display.last4 ? `${brand} •••• ${display.last4}` : brand;
+}
+
+/** `Validade 12/2031`, or nothing when the provider shared no expiry. */
+function expiryLabel(display: VaultedCardDisplay): string | null {
+  if (display.expMonth === null || display.expYear === null) return null;
+  return `Validade ${String(display.expMonth).padStart(2, "0")}/${display.expYear}`;
+}
+
+/** The card is on file — display metadata only, never the vault token. */
+function SavedConfirmation({
+  display,
+  copy,
+}: {
+  display: VaultedCardDisplay;
+  copy: CheckoutCopyFE;
+}): JSX.Element {
+  const { Alert, Text } = useCheckoutComponents();
+  const expiry = expiryLabel(display);
+  return (
+    <Box data-testid="add-card-saved" sx={{ display: "flex", flexDirection: "column", gap: 2 }}>
+      <Alert
+        variant="info"
+        title={copy.addCardSavedTitle}
+        description={copy.addCardSavedBody}
+        showIcon
+      />
+      <Box>
+        <Text variant="body" size="sm" weight="semibold" as="p">
+          {displayLabel(display)}
+        </Text>
+        {expiry ? (
+          <Text variant="caption" size="xs" color="secondary" as="p">
+            {expiry}
+          </Text>
+        ) : null}
+      </Box>
+    </Box>
+  );
+}
+
+/** The form phase: the shared card fields, the refusal, the save action. */
+function AddCardForm({
+  controller,
+  copy,
+}: {
+  controller: AddCardController;
+  copy: CheckoutCopyFE;
+}): JSX.Element {
+  const { Alert, Button, Text } = useCheckoutComponents();
+  return (
+    <Box data-testid="add-card" sx={{ display: "flex", flexDirection: "column", gap: 2 }}>
+      <Text variant="heading" size="md" weight="bold" as="h2">
+        {copy.addCardTitle}
+      </Text>
+      {/* No save-card opt-in: this screen IS the opt-in, so a checkbox here
+          would be a second question about the same consent. */}
+      <NewCardForm
+        card={controller.card}
+        fieldErrors={controller.fieldErrors}
+        brand={controller.brand}
+        setCard={controller.setCard}
+        setFieldErrors={controller.setFieldErrors}
+      />
+      {controller.error ? (
+        <Alert
+          variant="danger"
+          title={copy.addCardFailedTitle}
+          description={controller.error}
+          showIcon
+          data-testid="add-card-error"
+        />
+      ) : null}
+      <Button
+        variant="solid"
+        color="primary"
+        size="lg"
+        fullWidth
+        loading={controller.saving}
+        disabled={controller.saving}
+        onClick={() => void controller.submit()}
+        dataTestId="add-card-save"
+      >
+        {copy.addCardAction}
+      </Button>
+    </Box>
+  );
+}
+
+/** The add-card screen body, one branch per {@link AddCardController} phase. */
+export function AddCardView({
+  controller,
+  copy,
+}: {
+  controller: AddCardController;
+  copy: CheckoutCopyFE;
+}): JSX.Element {
+  const { Alert, LoadingState } = useCheckoutComponents();
+  const { phase } = controller;
+  if (phase.kind === "preparing") {
+    return (
+      <LoadingState
+        variant="spinner"
+        size="md"
+        message={copy.addCardPreparing}
+        dataTestId="add-card-preparing"
+      />
+    );
+  }
+  if (phase.kind === "unavailable") {
+    return (
+      <Alert
+        variant="info"
+        title={copy.addCardTitle}
+        description={phase.message}
+        showIcon
+        data-testid="add-card-unavailable"
+      />
+    );
+  }
+  if (phase.kind === "saved") {
+    return <SavedConfirmation display={phase.display} copy={copy} />;
+  }
+  return <AddCardForm controller={controller} copy={copy} />;
+}
+
+/** The live add-card flow — the hook and the view, bound to one runtime. */
+function AddCardSection({
+  runtime,
+  onSaved,
+}: {
+  runtime: FlowsRuntime;
+  onSaved?: (display: VaultedCardDisplay) => void;
+}): JSX.Element {
+  const controller = useAddCard(runtime, onSaved);
+  return <AddCardView controller={controller} copy={runtime.copy} />;
+}
+
+/**
+ * The caller's instruments at this store (FUT-697 scoping), with a pending
+ * flag so the empty-state sentence never flashes while the list is in flight.
+ */
+function useInstrumentList(
+  runtime: FlowsRuntime,
+  refresh: number,
+): { cards: SavedCard[]; pending: boolean } {
+  const tenantSlug = runtime.useTenantSlug();
+  const [state, setState] = useState<{ cards: SavedCard[]; pending: boolean }>({
+    cards: [],
+    pending: true,
+  });
+  useEffect(() => {
+    let active = true;
+    void runtime.client.listInstruments(tenantSlug).then((cards) => {
+      if (active) setState({ cards, pending: false });
+    });
+    return () => {
+      active = false;
+    };
+  }, [runtime, tenantSlug, refresh]);
+  return state;
+}
+
+/** The list itself, or the empty-state sentence. Read-only by design. */
+function CardList({ cards, emptyCopy }: { cards: SavedCard[]; emptyCopy: string }): JSX.Element {
+  const { Text } = useCheckoutComponents();
+  if (cards.length === 0) {
+    return (
+      <Text variant="body" size="sm" color="secondary" as="p" data-testid="manage-cards-empty">
+        {emptyCopy}
+      </Text>
+    );
+  }
+  return (
+    <Box data-testid="manage-cards-list" sx={{ display: "flex", flexDirection: "column", gap: 1.5 }}>
+      {cards.map((card) => (
+        <Box key={card.id} data-testid={`manage-cards-item-${card.id}`}>
+          <Text variant="body" size="sm" weight="semibold" as="p">
+            {`${card.brand} •••• ${card.last4}`}
+          </Text>
+          {card.expMonth && card.expYear ? (
+            <Text variant="caption" size="xs" color="secondary" as="p">
+              {`Validade ${String(card.expMonth).padStart(2, "0")}/${card.expYear}`}
+            </Text>
+          ) : null}
+        </Box>
+      ))}
+    </Box>
+  );
+}
+
+/** The manage screen: the list, and the door into the add flow. */
+function ManageCardsBody({ runtime }: { runtime: FlowsRuntime }): JSX.Element {
+  const { Button, Text } = useCheckoutComponents();
+  const copy = runtime.copy;
+  const [adding, setAdding] = useState(false);
+  // Bumped when the add flow saves, so the list re-reads what is now on file.
+  const [refresh, setRefresh] = useState(0);
+  const { cards, pending } = useInstrumentList(runtime, refresh);
+  return (
+    <Box data-testid="manage-cards" sx={{ display: "flex", flexDirection: "column", gap: 2 }}>
+      <Text variant="heading" size="md" weight="bold" as="h2">
+        {copy.manageCardsTitle}
+      </Text>
+      {pending ? null : <CardList cards={cards} emptyCopy={copy.manageCardsEmpty} />}
+      {adding ? (
+        <AddCardSection runtime={runtime} onSaved={() => setRefresh((count) => count + 1)} />
+      ) : (
+        <Button
+          variant="outline"
+          color="primary"
+          size="lg"
+          fullWidth
+          onClick={() => setAdding(true)}
+          dataTestId="manage-cards-add"
+        >
+          {copy.manageCardsAdd}
+        </Button>
+      )}
+    </Box>
+  );
+}
+
+function buildAddCard(runtime: FlowsRuntime): CheckoutScreens["AddCard"] {
+  return function AddCard({ onSaved }) {
+    return (
+      <FlowsShell runtime={runtime}>
+        <AddCardSection runtime={runtime} onSaved={onSaved} />
+      </FlowsShell>
+    );
+  };
+}
+
+function buildManageCards(runtime: FlowsRuntime): CheckoutScreens["ManageCards"] {
+  return function ManageCards() {
+    return (
+      <FlowsShell runtime={runtime}>
+        <ManageCardsBody runtime={runtime} />
+      </FlowsShell>
+    );
+  };
+}
+
+export const vaultScreens = {
+  buildAddCard,
+  buildManageCards,
+};

package/src/flows/types.ts

@@ -37,7 +37,7 @@ import type {
   OrderStatus,
   PaymentMethod,
 } from "../components/checkout/types";
-import type { CheckoutTransport } from "../components/checkout/transport";
+import type { CheckoutTransport, VaultedCardDisplay } from "../components/checkout/transport";
 import type { useCheckoutController } from "../components/checkout/use-checkout-controller";
 import type { Result } from "../result";
 
@@ -164,6 +164,18 @@ export interface CheckoutScreens {
   PayerSummary: ComponentType<{ buyer: BuyerInfo; onEdit?(): void }>;
   SavedCards: ComponentType<{ selection: string; onSelect(id: string): void }>;
   EmptyCart: ComponentType<Record<string, never>>;
+  /**
+   * Put a card on file OUTSIDE a purchase (FUT-183, over FUT-478's
+   * `/cards/begin` + `/cards/complete`). `onSaved` fires with display metadata
+   * only — the vault token never reaches the browser.
+   */
+  AddCard: ComponentType<{ onSaved?(display: VaultedCardDisplay): void }>;
+  /**
+   * The buyer's saved cards, plus the door into {@link CheckoutScreens.AddCard}.
+   * Read-only beyond that: there is no buyer-side delete (PagBank publishes no
+   * token-delete endpoint — see `flows/screens-vault.tsx`).
+   */
+  ManageCards: ComponentType<Record<string, never>>;
 }
 
 /** The fetched store protocol, plus whether it is still in flight. */

package/src/flows/use-add-card.ts

@@ -0,0 +1,183 @@
+/**
+ * The add-card state machine (FUT-183) — the buyer half of the FUT-478 vault
+ * surface: `POST /cards/begin` equips this browser, the shared card form and
+ * tokenizer mint the instrument, `POST /cards/complete` stores it and answers
+ * display metadata. Extracted from the view for the same reason
+ * `use-card-checkout.ts` is: the screen stays presentational, and a story can
+ * stage any phase by building a {@link AddCardController} literal.
+ *
+ * What never appears here is as deliberate as what does:
+ *
+ *   - no ownership facts. `reference`/`customerRef` are the HOST's answer to
+ *     the mount's vault port; the browser contributes only the session it was
+ *     handed and the token it minted.
+ *   - no vault token on the way back. `complete` answers display metadata
+ *     only, and that is all the saved phase holds.
+ */
+import {
+  useEffect,
+  useState,
+  type Dispatch,
+  type SetStateAction,
+} from "react";
+
+import {
+  detectBrand,
+  onlyDigits,
+  tokenizeForCheckout,
+  validateCardNumber,
+  validateCvv,
+  validateExpiry,
+  validateHolder,
+  type CardBrand,
+  type CardDetails,
+  type CardFieldErrors,
+  type CardTokenizationConfig,
+} from "../card";
+import type {
+  BuyerVaultSession,
+  VaultedCardDisplay,
+} from "../components/checkout/transport";
+import type { CheckoutProviderConfig } from "../components/checkout/types";
+import type { Result } from "../result";
+
+import { useResolvedConfig, type FlowsRuntime } from "./runtime";
+
+const EMPTY_CARD: CardDetails = { number: "", holder: "", expiry: "", cvv: "" };
+
+/** Where the add-card flow is, from first paint to a card on file. */
+export type AddCardPhase =
+  | { kind: "preparing" }
+  /** `begin` refused — a state the buyer cannot fix, said plainly. */
+  | { kind: "unavailable"; message: string }
+  | { kind: "form"; session: BuyerVaultSession }
+  | { kind: "saved"; display: VaultedCardDisplay };
+
+/** Everything the add-card view renders. A story stages one as a literal. */
+export interface AddCardController {
+  phase: AddCardPhase;
+  card: CardDetails;
+  setCard: Dispatch<SetStateAction<CardDetails>>;
+  fieldErrors: CardFieldErrors;
+  setFieldErrors: Dispatch<SetStateAction<CardFieldErrors>>;
+  brand: CardBrand;
+  /** A tokenize + complete round trip is in flight. */
+  saving: boolean;
+  /** The refusal the buyer reads — the endpoint's own reason, form kept editable. */
+  error: string | null;
+  submit(): Promise<void>;
+}
+
+/**
+ * Word a refused `begin`. `VAULT_NOT_ENABLED` is the mount's machine-level
+ * convention (a deliberately English sentence — a host wiring gap no buyer can
+ * fix), so the factory's own pt-BR stands in for it; every other refusal
+ * (`PAYMENT_NOT_CONFIGURED`, a transport failure) already carries the pt-BR
+ * message the host's copy table worded.
+ */
+function beginRefusalMessage(
+  runtime: FlowsRuntime,
+  refusal: { error: string; code?: string },
+): string {
+  return refusal.code === "VAULT_NOT_ENABLED" ? runtime.copy.addCardUnavailable : refusal.error;
+}
+
+/**
+ * The tokenization triple for THIS vault session. Provider and key come from
+ * the `begin` answer — the session's own facts. The stub grant does not travel
+ * on it: `GET /config` is the ONLY sanctioned source for `mockTokenization`
+ * (FUT-697), so it is read off the published chain entry for the session's
+ * provider, and absent that, off the config head. No config ⇒ no grant.
+ */
+function sessionTokenization(
+  session: BuyerVaultSession,
+  config: CheckoutProviderConfig | null,
+): CardTokenizationConfig {
+  const link = config?.chain?.find((entry) => entry.provider === session.provider);
+  const mockTokenization =
+    link?.mockTokenization ??
+    (config?.provider === session.provider ? config.mockTokenization : false);
+  return { provider: session.provider, publicKey: session.publicKey, mockTokenization };
+}
+
+/** Fetch the vault session once on mount; the phases follow the answer. */
+function useVaultSession(runtime: FlowsRuntime): {
+  phase: AddCardPhase;
+  setPhase: Dispatch<SetStateAction<AddCardPhase>>;
+} {
+  const [phase, setPhase] = useState<AddCardPhase>({ kind: "preparing" });
+  useEffect(() => {
+    let active = true;
+    void runtime.client.beginVault().then((result: Result<BuyerVaultSession>) => {
+      if (!active) return;
+      if (!result.ok) {
+        setPhase({ kind: "unavailable", message: beginRefusalMessage(runtime, result) });
+        return;
+      }
+      setPhase({ kind: "form", session: result.data });
+    });
+    return () => {
+      active = false;
+    };
+  }, [runtime]);
+  return { phase, setPhase };
+}
+
+/**
+ * The add-card flow: begin → (buyer types) → tokenize → complete → saved.
+ *
+ * A refused `complete` sets {@link AddCardController.error} and stays on the
+ * form — the endpoint's reason is the buyer's cue to fix the card, and wiping
+ * their input to say it would be the screen working against them.
+ */
+export function useAddCard(
+  runtime: FlowsRuntime,
+  onSaved?: (display: VaultedCardDisplay) => void,
+): AddCardController {
+  const { config } = useResolvedConfig(runtime);
+  const { phase, setPhase } = useVaultSession(runtime);
+  const [card, setCard] = useState<CardDetails>(EMPTY_CARD);
+  const [fieldErrors, setFieldErrors] = useState<CardFieldErrors>({});
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+
+  const brand = detectBrand(onlyDigits(card.number));
+
+  const validate = (): CardFieldErrors => ({
+    number: validateCardNumber(card.number),
+    holder: validateHolder(card.holder),
+    expiry: validateExpiry(card.expiry),
+    cvv: validateCvv(card.cvv, brand),
+  });
+
+  const submit = async (): Promise<void> => {
+    if (phase.kind !== "form" || saving) return;
+    setError(null);
+    const errors = validate();
+    setFieldErrors(errors);
+    if (Object.values(errors).some(Boolean)) return;
+
+    setSaving(true);
+    const minted = await tokenizeForCheckout(card, sessionTokenization(phase.session, config));
+    if (!minted.ok) {
+      setError(minted.error);
+      setSaving(false);
+      return;
+    }
+    // The browser's two legitimate facts, and nothing else: the session it is
+    // completing and the instrument it minted. Ownership rides server-side.
+    const completed = await runtime.client.completeVault({
+      ...(phase.session.sessionId ? { sessionId: phase.session.sessionId } : {}),
+      token: minted.data.token,
+    });
+    setSaving(false);
+    if (!completed.ok) {
+      setError(completed.error);
+      return;
+    }
+    setPhase({ kind: "saved", display: completed.data });
+    onSaved?.(completed.data);
+  };
+
+  return { phase, card, setCard, fieldErrors, setFieldErrors, brand, saving, error, submit };
+}

package/src/index.ts

@@ -78,8 +78,11 @@ export {
 export {
   createCheckoutClient,
   DEFAULT_CHECKOUT_BASE_URL,
+  type BuyerVaultSession,
   type CheckoutClient,
   type CheckoutTransport,
+  type CompleteVaultInput,
+  type VaultedCardDisplay,
 } from './components/checkout/transport';
 export { type CheckoutHostPorts } from './components/checkout/use-checkout-controller';
 export { PaymentsUnavailable } from './components/checkout/payments-unavailable';