@12-apps/payments-frontend 1.7.1 → 1.8.1

package/src/flows/screens-pay.tsx

@@ -0,0 +1,178 @@
+/**
+ * The factory's payment screens (FUT-741), part two: taking the money, saying
+ * how it went, and saying plainly when the store cannot take it at all.
+ */
+import { Box } from "@mui/material";
+import type { JSX } from "react";
+
+import { CardView } from "../components/checkout/card-view";
+import {
+  cardChain,
+  cardTokenization,
+} from "../components/checkout/method-capability";
+import { PaymentStatus as PaymentStatusView } from "../components/checkout/payment-status";
+import { PixView } from "../components/checkout/pix-view";
+import type { CheckoutOrder, OrderStatus } from "../components/checkout/types";
+import { useCheckoutComponents } from "../components/checkout/ui";
+
+import { FlowsShell, useResolvedConfig, type FlowsRuntime } from "./runtime";
+import type { CheckoutScreens } from "./types";
+
+function buildCardEntry(runtime: FlowsRuntime): CheckoutScreens["CardEntry"] {
+  function CardEntryBody({
+    payable,
+    onResolved,
+  }: {
+    payable: CheckoutOrder;
+    onResolved: (status: OrderStatus) => void;
+  }): JSX.Element {
+    const { config } = useResolvedConfig(runtime);
+    return (
+      <CardView
+        order={payable}
+        providerConfig={cardTokenization(config)}
+        // The chain VERBATIM (FUT-563). Nothing here filters, sorts or
+        // de-duplicates it: `tokensByProvider` is sent iff the SERVER-published
+        // chain has more than one entry, so any tidying done at this layer
+        // silently disables failover for the store it exists for.
+        providerChain={cardChain(config)}
+        tenantSlug={runtime.useTenantSlug()}
+        onResolved={onResolved}
+        pollIntervalMs={runtime.config.polling?.intervalMs}
+      />
+    );
+  }
+  return function CardEntry(props) {
+    return (
+      <FlowsShell runtime={runtime}>
+        <CardEntryBody {...props} />
+      </FlowsShell>
+    );
+  };
+}
+
+function buildPixPayment(runtime: FlowsRuntime): CheckoutScreens["PixPayment"] {
+  return function PixPayment({
+    payable,
+    onResolved,
+  }: {
+    payable: CheckoutOrder;
+    onResolved: (status: OrderStatus) => void;
+  }) {
+    return (
+      <FlowsShell runtime={runtime}>
+        <PixView
+          order={payable}
+          onResolved={onResolved}
+          pollIntervalMs={runtime.config.polling?.intervalMs}
+        />
+      </FlowsShell>
+    );
+  };
+}
+
+function buildPaymentStatus(runtime: FlowsRuntime): CheckoutScreens["PaymentStatus"] {
+  return function PaymentStatus({
+    status,
+    payable,
+  }: {
+    status: OrderStatus | null;
+    payable?: CheckoutOrder | null;
+  }) {
+    return (
+      <FlowsShell runtime={runtime}>
+        <PaymentStatusView
+          status={status}
+          totalLabel={payable?.totalLabel ?? ""}
+          orderId={payable?.orderId}
+          onBackToMenu={runtime.config.ports.exitToCatalog}
+          paidExtra={runtime.config.confirmation?.extra}
+        />
+      </FlowsShell>
+    );
+  };
+}
+
+/**
+ * Whether this store can take money at all.
+ *
+ * An OR, never a swap. `chain.length === 0` is the library's own fact — the
+ * server published no enabled provider. The host's veto is a DIFFERENT fact: a
+ * store with a perfectly good chain that has switched online payments off. Move
+ * the decision entirely to the chain and that store starts offering a checkout
+ * it will not honour; move it entirely to the host and a store that simply
+ * never connected a provider gets the payment step it cannot serve.
+ *
+ * While the config is still in flight, neither fact is known — so nothing is
+ * refused. The unavailable screen is a statement about the store, and stating
+ * it early would be a lie a spinner never tells.
+ */
+export function storeCannotCharge(
+  config: { chain?: unknown[] } | null,
+  pending: boolean,
+  hostSaysPayable: boolean,
+): boolean {
+  if (pending) return false;
+  if (!hostSaysPayable) return true;
+  return config !== null && (config.chain?.length ?? 0) === 0;
+}
+
+function buildPaymentsUnavailable(
+  runtime: FlowsRuntime,
+): CheckoutScreens["PaymentsUnavailable"] {
+  function PaymentsUnavailableBody(): JSX.Element {
+    const { Alert, Button } = useCheckoutComponents();
+    const { remedy } = runtime.useAvailability();
+    const copy = runtime.copy;
+    if (!remedy) {
+      return (
+        <Box
+          sx={{ display: "flex", flexDirection: "column", gap: 2 }}
+          data-testid="checkout-payments-disabled"
+        >
+          <Alert
+            variant="info"
+            title={copy.unavailableTitle}
+            description={copy.unavailableBody}
+            showIcon
+          />
+        </Box>
+      );
+    }
+    return (
+      <Box
+        sx={{ display: "flex", flexDirection: "column", gap: 2 }}
+        data-testid="checkout-payments-remedy"
+      >
+        <Alert
+          variant="info"
+          title={copy.unavailableWithRemedyTitle}
+          description={copy.unavailableWithRemedyBody}
+          showIcon
+        />
+        <Button
+          variant="solid"
+          size="lg"
+          onClick={remedy.onSelect}
+          dataTestId="checkout-payments-remedy-action"
+        >
+          {remedy.label}
+        </Button>
+      </Box>
+    );
+  }
+  return function PaymentsUnavailable() {
+    return (
+      <FlowsShell runtime={runtime}>
+        <PaymentsUnavailableBody />
+      </FlowsShell>
+    );
+  };
+}
+
+export const payScreens = {
+  buildCardEntry,
+  buildPixPayment,
+  buildPaymentStatus,
+  buildPaymentsUnavailable,
+};

package/src/flows/types.ts

@@ -0,0 +1,179 @@
+/**
+ * The `createPaymentFlows` vocabulary (FUT-741).
+ *
+ * `@12-apps/payments-frontend` exported a FLAT list — components, headless
+ * hooks and fetch clients — and every host composed them by hand: six named
+ * imports, a local slot table, a local fetch client, and its own answer to
+ * "can this store charge?". Three hosts wrote that glue; the FUT-740 review
+ * found its criticals in exactly the seam that glue spans.
+ *
+ * So there is now an easy path: call this ONCE at module scope, mount what
+ * comes back. The flat exports stay — they are the escape hatch, and the
+ * headless story proves they still work.
+ *
+ * ## Zero provider names
+ *
+ * Nothing in this file, or in anything it returns, names a vendor. Every branch
+ * is decided by the server-published `tokenization` / `methods` /
+ * `customerSchema`. The only place a name exists at all is as an OPAQUE KEY:
+ * `chain[].provider`, looked up in the tokenizer registry and used verbatim as
+ * a `tokensByProvider` key. A host never types one.
+ */
+import type { ComponentType, ReactNode } from "react";
+
+import type { SavedCard } from "../card";
+import type { CheckoutComponents } from "../components/checkout/ui";
+import type { CheckoutCartView } from "../components/checkout/checkout-flow";
+import type {
+  BuyerContact,
+  BuyerInfo,
+  ChargeCardInput,
+  ChargeOutcome,
+  CheckoutOrder,
+  CheckoutProviderConfig,
+  ComandaCheckout,
+  CreateOrderRequest,
+  CreateOrderResult,
+  OrderStatus,
+  PaymentMethod,
+} from "../components/checkout/types";
+import type { CheckoutTransport } from "../components/checkout/transport";
+import type { useCheckoutController } from "../components/checkout/use-checkout-controller";
+import type { Result } from "../result";
+
+import type { CheckoutCopyFE } from "./copy";
+
+/** The host's remedy on the unavailable screen, and its veto over a live chain. */
+export interface CheckoutAvailability {
+  /**
+   * The host's own answer to "may this store take money right now?".
+   *
+   * OR'd with the chain, never swapped for it. A store with a working provider
+   * chain that has switched online payments OFF is invisible to `/config` —
+   * the chain is non-empty and the checkout would happily offer a picker it
+   * will not honour. That fact lives in the host, so the host votes.
+   */
+  payable: boolean;
+  /** What the buyer can do instead, when there is something. */
+  remedy?: { label: string; onSelect(): void };
+}
+
+/** Everything the flow needs FROM its host that is not a money rule. */
+export interface CheckoutPorts {
+  /** Raise the payable + first charge. Same contract as today's `createOrder`. */
+  createPayable(input: CreateOrderRequest): Promise<CreateOrderResult>;
+  /** Persist the buyer's contact under the "salvar meus dados" consent. */
+  saveBuyerContact?(contact: BuyerContact): void;
+  /** Leave checkout for the host's menu/catalog. */
+  exitToCatalog(): void;
+  /** The payable settled PAID — the host re-reads whatever the server emptied. */
+  onPaid?(): void;
+  /**
+   * Hosted handover / 3-DS. Defaults to `window.location.assign`. A port
+   * because the destination is ANOTHER ORIGIN — never the host's router — and
+   * some hosts must log or confirm the departure.
+   */
+  navigate?(url: string): void;
+  /** The remedy shown on the no-provider screen, AND the host's veto. */
+  useAvailability?(): CheckoutAvailability;
+}
+
+/** What `createPaymentFlows` is configured with. */
+export interface PaymentFlowsConfig {
+  /** Where the `createPaymentFlowsBE` mount lives. Default `/api/checkout`. */
+  transport?: CheckoutTransport;
+
+  /**
+   * The store being paid. A HOOK because the host's router owns it: taking a
+   * value here would freeze the slug of whichever store loaded first onto every
+   * checkout the page ever renders.
+   */
+  useScope?(): { tenantSlug?: string };
+  /** The cart, reduced to display facts. Never money math. */
+  useCart(): CheckoutCartView;
+  /** The buyer's saved details, and whether a CPF is already on file. */
+  useBuyerDefaults?(): { buyer?: BuyerInfo; taxIdOnFile?: boolean; pending?: boolean };
+  /** Present ⇒ this checkout settles a comanda rather than the cart. */
+  useComanda?(): ComandaCheckout | null;
+
+  /** Design-system slots, filled ONCE instead of per screen. */
+  components?: Partial<CheckoutComponents>;
+
+  /** The host's domain, as ports. Nothing here is a money rule. */
+  ports: CheckoutPorts;
+
+  polling?: { intervalMs?: number; cardMaxPolls?: number };
+  // NO `tokenization: { mintTimeoutMs }` here yet, deliberately. It was
+  // declared and never threaded to the mint path, so a host could set a
+  // deadline, believe the chain honoured it, and get none — config that lies is
+  // worse than config that is absent. Landing it for real needs the answer to
+  // "what happens WHEN it fires": a timed-out mint must decide whether the walk
+  // advances to the next entry or the whole charge refuses, and that is a money
+  // rule (FUT-563), not a wire-up.
+  copy?: Partial<CheckoutCopyFE>;
+  /** Host content under the paid receipt (the storefront's PWA install invite). */
+  confirmation?: { extra?: ReactNode };
+  /**
+   * Warnings the host reports (Sentry). Default SILENT — never `console`: a
+   * library that writes to a buyer's console tells them nothing and tells the
+   * host nothing either.
+   */
+  onWarning?(line: string, context?: Record<string, unknown>): void;
+}
+
+/** The flow controller a hand-composing host drives itself. */
+export type CheckoutController = ReturnType<typeof useCheckoutController>;
+
+/** The pre-bound fetch clients — same shapes as the free functions. */
+export interface BoundCheckoutClient {
+  getConfig(tenantSlug: string): Promise<Result<CheckoutProviderConfig>>;
+  getStatus(ref: string): Promise<Result<OrderStatus>>;
+  charge(input: ChargeCardInput): Promise<Result<ChargeOutcome>>;
+  listInstruments(tenantSlug?: string): Promise<SavedCard[]>;
+  refreshBrowserKey(input: { orderId: string }): Promise<Result<{ publicKey: string | null }>>;
+}
+
+/** What the schema-derived buyer form renders. */
+export interface BuyerDetailsProps {
+  value: BuyerInfo;
+  onChange(b: BuyerInfo): void;
+  /** Narrows the chain's declaration to this method (FUT-595); `null` ⇒ union. */
+  method: PaymentMethod | null;
+  onContinue(): void;
+  /** A server refusal to echo onto the offending input (MISSING_BUYER_FIELD). */
+  error?: { field: "cpf" | "email" | "name" | "phone"; message: string } | null;
+}
+
+/** The screens a host may nest itself. Every one works standalone. */
+export interface CheckoutScreens {
+  MethodChoice: ComponentType<{ value: PaymentMethod | null; onChange(m: PaymentMethod): void }>;
+  BuyerDetails: ComponentType<BuyerDetailsProps>;
+  CardEntry: ComponentType<{ payable: CheckoutOrder; onResolved(s: OrderStatus): void }>;
+  PixPayment: ComponentType<{ payable: CheckoutOrder; onResolved(s: OrderStatus): void }>;
+  HostedHandoff: ComponentType<{ url: string; payable: CheckoutOrder; onCancel?(): void }>;
+  HostedReturn: ComponentType<{ onResolved(s: OrderStatus): void }>;
+  PaymentStatus: ComponentType<{ status: OrderStatus | null; payable?: CheckoutOrder | null }>;
+  PaymentsUnavailable: ComponentType<Record<string, never>>;
+  PayerSummary: ComponentType<{ buyer: BuyerInfo; onEdit?(): void }>;
+  SavedCards: ComponentType<{ selection: string; onSelect(id: string): void }>;
+  EmptyCart: ComponentType<Record<string, never>>;
+}
+
+/** The fetched store protocol, plus whether it is still in flight. */
+export interface CheckoutConfigState {
+  config: CheckoutProviderConfig | null;
+  pending: boolean;
+}
+
+/** What `createPaymentFlows` returns. */
+export interface PaymentFlows {
+  /** THE mount: a complete buyer checkout in one line. */
+  Checkout: ComponentType<{ comanda?: ComandaCheckout | null }>;
+  /** Slots + transport + scope + the fetched config, for a nesting host. */
+  Provider: ComponentType<{ children: ReactNode; config?: CheckoutProviderConfig | null }>;
+  screens: CheckoutScreens;
+  /** The flow controller, pre-bound to the ports — the easy path is not the only path. */
+  useCheckout(): CheckoutController;
+  useCheckoutConfig(): CheckoutConfigState;
+  client: BoundCheckoutClient;
+}

package/src/index.ts

@@ -48,6 +48,39 @@ export {
   type CheckoutCartView,
   type CheckoutFlowProps,
 } from './components/checkout/checkout-flow';
+
+// ---------------------------------------------------------------------------
+// The MOUNTED buyer checkout (FUT-741) — `createPaymentFlows` returns every
+// screen pre-bound to one transport, one scope, one slot table and one set of
+// host ports. Additive: everything above and below stays exported, and the
+// hand-composing path is unchanged.
+// ---------------------------------------------------------------------------
+export { createPaymentFlows } from './flows/create-payment-flows';
+export {
+  DEFAULT_CHECKOUT_COPY_FE,
+  type CheckoutCopyFE,
+} from './flows/copy';
+export {
+  type BoundCheckoutClient,
+  type BuyerDetailsProps,
+  type CheckoutAvailability,
+  type CheckoutConfigState,
+  type CheckoutController,
+  type CheckoutPorts,
+  type CheckoutScreens,
+  type PaymentFlows,
+  type PaymentFlowsConfig,
+} from './flows/types';
+export {
+  buyerFieldsFor,
+  fieldSatisfied,
+} from './components/checkout/buyer-fields';
+export {
+  createCheckoutClient,
+  DEFAULT_CHECKOUT_BASE_URL,
+  type CheckoutClient,
+  type CheckoutTransport,
+} from './components/checkout/transport';
 export { type CheckoutHostPorts } from './components/checkout/use-checkout-controller';
 export { PaymentsUnavailable } from './components/checkout/payments-unavailable';
 export { fetchCheckoutConfig } from './components/checkout/client';
@@ -70,6 +103,8 @@ export {
   type BuyerContact,
   type BuyerField,
   type BuyerInfo,
+  type CheckoutChainLink,
+  type CheckoutCustomerField,
   type CheckoutError,
   type CheckoutOrder,
   type CheckoutProviderConfig,