@12-apps/payments-frontend 1.17.0 → 1.19.0

package/src/components/platform/PlatformHomologacao.tsx

@@ -0,0 +1,107 @@
+'use client';
+
+import { Alert, Box, Button, Stack, Typography } from '@mui/material';
+import { useState, type ReactNode } from 'react';
+
+import type { HomologacaoGuide } from '@12-apps/payments-backend';
+
+import { CARD_SX } from './ConnectEnvironmentCard';
+import { HomologacaoGuideCard } from './HomologacaoGuideCard';
+import {
+  HomologacaoOutcomeCard,
+  type HomologacaoSaveInput,
+  type HomologacaoSaveState,
+  type PlatformHomologationRecordView,
+} from './HomologacaoOutcomeCard';
+
+/**
+ * The PLATFORM's PagBank homologação screen (FUT-483, packaged by FUT-573).
+ *
+ * The platform is the direct integrator, so the homologação is the
+ * platform's, once — store owners are platform users and are exempt. The
+ * screen carries the three halves: the recorded outcome (so "is the platform
+ * homologated?" stops being a question for a person), the Pipefy form with
+ * paste-ready answers (BOTH services — Order and Connect), and the evidence
+ * generator running on the platform's own sandbox credentials.
+ *
+ * Dumb by design: data and mutations arrive via props from the host's own
+ * mounted routes (`platformHomologacaoGuide`, `createHomologationRecordService`
+ * and `buildPlatformHomologacaoAnexo` in `@12-apps/payments-backend`), so the
+ * host page is a thin mount.
+ */
+export interface PlatformHomologacaoProps {
+  /** The recorded outcome; null renders the honest "não solicitada". */
+  record: PlatformHomologationRecordView | null;
+  /** The paste-ready answers, computed by the host's backend. */
+  guide: HomologacaoGuide;
+  /** Record the outcome — the host PUTs it and refreshes `record`. */
+  onSaveRecord: (input: HomologacaoSaveInput) => void;
+  /** The host's save-mutation state. */
+  save: HomologacaoSaveState;
+  /**
+   * Generate AND deliver the evidence file (the host downloads what its anexo
+   * route answers). Reject with an Error whose message names the reason —
+   * e.g. the missing platform sandbox token and where to fix it — and the
+   * card shows it verbatim.
+   */
+  onGenerateAnexo: () => Promise<void>;
+}
+
+/** The evidence-file half: real sandbox calls, downloaded as a text file. */
+function AnexoCard({ onGenerate }: { onGenerate: () => Promise<void> }): ReactNode {
+  const [error, setError] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  const generate = async (): Promise<void> => {
+    setBusy(true);
+    setError(null);
+    try {
+      await onGenerate();
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : 'Não foi possível gerar o anexo.');
+    } finally {
+      setBusy(false);
+    }
+  };
+
+  return (
+    <Stack spacing={1.5} data-testid="homologacao-anexo-card" sx={CARD_SX}>
+      <Typography variant="body2" fontWeight={600}>
+        Anexo de evidências
+      </Typography>
+      <Typography variant="body2" color="text.secondary" component="p">
+        O formulário exige os requests e responses das requisições enviadas às APIs do
+        PagBank. O botão abaixo faz as chamadas reais no ambiente de testes (Sandbox) com o
+        token da própria plataforma — nada é cobrado de verdade — e baixa o arquivo pronto
+        para anexar, com o token redigido.
+      </Typography>
+      <Box>
+        <Button
+          variant="outlined"
+          size="small"
+          disabled={busy}
+          onClick={() => void generate()}
+          data-testid="homologacao-anexo-button"
+        >
+          Gerar anexo
+        </Button>
+      </Box>
+      {error !== null ? (
+        <Alert severity="error" data-testid="homologacao-anexo-error">
+          {error}
+        </Alert>
+      ) : null}
+    </Stack>
+  );
+}
+
+export function PlatformHomologacao(props: PlatformHomologacaoProps): ReactNode {
+  const { record, guide, onSaveRecord, save, onGenerateAnexo } = props;
+  return (
+    <Stack spacing={2} data-testid="platform-homologacao">
+      <HomologacaoOutcomeCard record={record} onSave={onSaveRecord} save={save} />
+      <HomologacaoGuideCard guide={guide} />
+      <AnexoCard onGenerate={onGenerateAnexo} />
+    </Stack>
+  );
+}

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,
@@ -96,6 +97,7 @@ function buildCheckout(
         providerConfig={config}
         tenantSlug={tenantSlug}
         confirmationExtra={runtime.config.confirmation?.extra}
+        validateApplePayMerchant={ports.validateApplePayMerchant}
       />
     );
   }
@@ -116,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),
@@ -130,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";
 
@@ -74,6 +74,13 @@ export interface CheckoutPorts {
    * some hosts must log or confirm the departure.
    */
   navigate?(url: string): void;
+  /**
+   * Apple Pay merchant validation (FUT-472): exchange the session's
+   * `validationURL` for an Apple merchant session, SERVER-SIDE — the merchant
+   * identity certificate must never reach a browser. Optional; without it the
+   * Apple Pay sheet cannot start and the card form remains the way to pay.
+   */
+  validateApplePayMerchant?(validationURL: string): Promise<unknown>;
   /** The remedy shown on the no-provider screen, AND the host's veto. */
   useAvailability?(): CheckoutAvailability;
 }
@@ -157,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. */