@12-apps/payments-frontend 1.17.0 → 1.19.0

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';
@@ -97,7 +100,16 @@ export {
   type GooglePaymentsClient,
   type GooglePayGatewayParams,
 } from './components/checkout/google-pay-button';
-export { googlePayConfig } from './components/checkout/method-capability';
+export {
+  ApplePayButton,
+  applePaySupported,
+  APPLE_PAY_SUPPORTED_NETWORKS,
+  type ApplePayButtonProps,
+  type ApplePayPaymentRequest,
+  type ApplePaySessionClass,
+  type ApplePaySessionLike,
+} from './components/checkout/apple-pay-button';
+export { applePayDeclared, googlePayConfig } from './components/checkout/method-capability';
 export {
   CheckoutComponentsProvider,
   type CheckoutActionBarProps,
@@ -185,6 +197,28 @@ export {
   type PaymentProviderSettingsProps,
 } from './components/PaymentProviderSettings';
 
+// ---------------------------------------------------------------------------
+// The PLATFORM operations screens (FUT-479 / FUT-483, packaged by FUT-573) —
+// the Connect-application consult and the homologação, as dumb components a
+// host page mounts with data + callbacks from its own routes. Their backend
+// halves live in `@12-apps/payments-backend` (`consultConnectApplications`,
+// `platformHomologacaoGuide`, `createHomologationRecordService`,
+// `buildPlatformHomologacaoAnexo`).
+// ---------------------------------------------------------------------------
+export {
+  ConnectApplicationPanel,
+  type ConnectApplicationPanelProps,
+} from './components/platform/ConnectApplicationPanel';
+export {
+  PlatformHomologacao,
+  type PlatformHomologacaoProps,
+} from './components/platform/PlatformHomologacao';
+export {
+  type HomologacaoSaveInput,
+  type HomologacaoSaveState,
+  type PlatformHomologationRecordView,
+} from './components/platform/HomologacaoOutcomeCard';
+
 /**
  * Re-exported because it appears in the `prepareConnect` prop a host must
  * implement: without it the host could not type its own callback without