@12-apps/payments-frontend 3.21.4 → 3.23.0

package/src/flows/pipeline/types.ts

@@ -0,0 +1,232 @@
+/**
+ * THE CHECKOUT PIPELINE'S VOCABULARY (FUT-1240, step 4 of FUT-1216).
+ *
+ * A checkout is a list of STEPS, a list of GATES and a list of SETTLEMENT
+ * METHODS. Each is a plain object in an array; registration is array
+ * membership and nothing else. The engine derives which step the shopper is
+ * on rather than remembering it, so a reload, a torn-down tab and a hand-off
+ * return all land where the server's own facts say they should.
+ *
+ * ## Two properties this file exists to keep
+ *
+ * 1. **Method syntax, never arrow properties.** Under `strictFunctionTypes` a
+ *    method's parameters are BIVARIANT while a property holding a function is
+ *    contravariant — so `CheckoutStep<S, F>` is assignable to
+ *    {@link AnyCheckoutStep} with no `any` and no cast. Written as
+ *    `applies: (ctx, facts) => boolean` instead, every registration would need
+ *    a cast, and this repo forbids `any`.
+ * 2. **The package names no host.** Nothing here imports a host, a sibling
+ *    workspace package or a domain word. A mode, a mesa, a comanda and a
+ *    delivery address are all host concepts and reach the engine as a
+ *    registered step or a registered method, never as a field.
+ */
+import type { ComponentType, ReactNode } from "react";
+
+import type { CheckoutCartView } from "../../components/checkout/checkout-flow";
+import type {
+  BuyerInfo,
+  CheckoutError,
+  CheckoutOrder,
+  CheckoutProviderConfig,
+  CreateOrderRequest,
+  OrderStatus,
+  SettlementCheckout,
+} from "../../components/checkout/types";
+import type {
+  CheckoutStepperCopy,
+  CheckoutViewCopy,
+} from "../../components/checkout/view-copy";
+
+/**
+ * Where a step sits in the walk. The engine sorts by this first and by
+ * {@link CheckoutStep.order} second, so a host appends a step without knowing
+ * what else is registered.
+ *
+ * `pay` is the phase the no-charge rule is stated over: a settlement method
+ * that raises no charge mounts NO `pay` step, ever — see
+ * {@link SettlementMethodDescriptor.raisesCharge}.
+ */
+export type CheckoutStepPhase = "details" | "before-pay" | "pay" | "after-pay";
+
+/** Everything a step, a gate or a method may read. All of it server-owned or parked. */
+export interface CheckoutContext {
+  tenantSlug?: string;
+  /** `GET /config`: chain, methods, tokenization. */
+  config: CheckoutProviderConfig | null;
+  configPending: boolean;
+  cart: CheckoutCartView;
+  /** Host-resolved balance, opaque scope. */
+  settlement: SettlementCheckout | null;
+  buyer: BuyerInfo;
+  taxIdOnFile: boolean;
+  /** A {@link SettlementMethodDescriptor.id}, or `null` before a choice. */
+  method: string | null;
+  /** Raised now, resumed from the server, or parked by a hand-off. */
+  order: CheckoutOrder | null;
+  outcome: OrderStatus | null;
+  intent: { oneClick: boolean; resuming: boolean; presetMethod: string | null };
+  /** Every step's declared slice, by step id. */
+  slices: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * A step's own scrap of state, DECLARED rather than held.
+ *
+ * The engine owns the storage, which is what makes a reload survivable: a
+ * `session` slice is parked under `payments.checkout.<slug>.<stepId>` and
+ * rehydrated on mount. Nothing money-shaped belongs here — that is the order.
+ */
+export interface StepSlice<S> {
+  initial(ctx: CheckoutContext): S;
+  /** `"session"` ⇒ `payments.checkout.<slug>.<stepId>`, rehydrated on mount. */
+  persist: "none" | "session";
+  /**
+   * Trust nothing that came back out of storage — the `hosted-return.ts` rule.
+   * A `session` slice with NO parser is never rehydrated: the engine cannot
+   * check a shape it has not been told, and a half-written value reaching a
+   * step as its state is exactly what that rule exists to stop.
+   */
+  parse?(raw: unknown): S | null;
+}
+
+/** What a step's `render` is handed. Its own type so the method syntax stays readable. */
+export interface CheckoutStepRender<S> {
+  ctx: CheckoutContext;
+  slice: S;
+  setSlice(s: S): void;
+  /** Done here — clear any back-navigation and let the walk move on. */
+  advance(): void;
+  /** The previous applying step, or the host's catalog when there is none. */
+  back(): void;
+  /** A server refusal THIS step claimed through {@link CheckoutStep.answersCodes}. */
+  error: CheckoutError | null;
+}
+
+/** One step of the walk. */
+export interface CheckoutStep<S = void, F = void> {
+  id: string;
+  phase: CheckoutStepPhase;
+  order?: number;
+  /** Host hook; runs EVERY render, in array order. */
+  useFacts?(): F;
+  /** Pure. */
+  applies(ctx: CheckoutContext, facts: F): boolean;
+  /** Pure — the current step is the first applying step whose answer is `false`. */
+  complete(ctx: CheckoutContext, facts: F, slice: S): boolean;
+  slice?: StepSlice<S>;
+  render(p: CheckoutStepRender<S> & { facts: F }): ReactNode;
+  /** Server refusal codes re-rendered HERE, never as a generic retry. */
+  answersCodes?: readonly string[];
+  contribute?(ctx: CheckoutContext, facts: F, slice: S): Partial<CreateOrderRequest>;
+  /** Absent ⇒ an interstitial, not a stepper node. */
+  label?: keyof CheckoutStepperCopy | null;
+}
+
+/** Any registered step. Reachable with no cast because every member above is a method. */
+export type AnyCheckoutStep = CheckoutStep<unknown, unknown>;
+
+/** What a gate decided about this shopper. */
+export type GateVerdict =
+  | { kind: "pass" }
+  | { kind: "pending" }
+  | {
+      kind: "refuse";
+      Screen: ComponentType<{
+        ctx: CheckoutContext;
+        error: CheckoutError | null;
+        retry(): void;
+      }>;
+    };
+
+/** Something that must be true before ANY step renders. */
+export interface CheckoutGate<F = void> {
+  id: string;
+  useFacts?(): F;
+  /** Pure. */
+  decide(ctx: CheckoutContext, facts: F): GateVerdict;
+  answersCodes?: readonly string[];
+  /** Bypassed when a hand-off from this tab is still waiting to be resolved. */
+  standsAsideForResume?: boolean;
+}
+
+/** Any registered gate. */
+export type AnyCheckoutGate = CheckoutGate<unknown>;
+
+/**
+ * A way of settling — the seam a no-charge settlement never had.
+ *
+ * `raisesCharge: false` is the whole reason this type exists: placing the
+ * order IS the settlement, so there is no `/charge`, no poll, and no payment
+ * surface after the method is chosen. The engine enforces that ONCE, over the
+ * `pay` phase, so no lane can forget it.
+ */
+export interface SettlementMethodDescriptor<F = void> {
+  /** `"PIX"`, `"CARD"`, `"ON_DELIVERY"`, `"WAITER"`, `"BOLETO"`… */
+  id: string;
+  /** `false` ⇒ no `/charge`, no poll; placing the order IS the settlement. */
+  raisesCharge: boolean;
+  /** The `pay`-phase step id shown once the order exists; `null` ⇒ Confirmation. */
+  pane: string | null;
+  useFacts?(): F;
+  offered(ctx: CheckoutContext, facts: F): boolean;
+  Review?: ComponentType<{
+    ctx: CheckoutContext;
+    place(): void;
+    placing: boolean;
+    error: CheckoutError | null;
+  }>;
+  /** Default: the package's own `PaymentStatus`. */
+  Confirmation?: ComponentType<{ ctx: CheckoutContext; order: CheckoutOrder }>;
+  tile(copy: CheckoutViewCopy): { label: string; hint?: string };
+}
+
+/** Any registered settlement method. */
+export type AnySettlementMethod = SettlementMethodDescriptor<unknown>;
+
+/**
+ * Where the shopper leaves for, and how.
+ *
+ * A hook for the label because it is the host's router that knows which
+ * catalog this checkout came from, and a value would freeze the first one.
+ */
+export interface CheckoutExit {
+  useCatalog(): { to: string; label: string };
+  navigate(to: string): void;
+}
+
+/**
+ * The engine's half of `PaymentFlowsConfig` — every key OPTIONAL.
+ *
+ * Setting ANY of them switches `Checkout` onto the pipeline. Setting NONE
+ * leaves it rendering exactly today's `CheckoutFlow`, which is the whole
+ * meaning of this step being additive.
+ */
+export interface CheckoutPipelineConfig {
+  /** Merged with the package's own, by phase then `order`. */
+  steps?: readonly AnyCheckoutStep[];
+  /** Evaluated in order before any step renders. */
+  gates?: readonly AnyCheckoutGate[];
+  /** Merged with the package's PIX + CARD. */
+  settlementMethods?: readonly AnySettlementMethod[];
+  /** The HOST reads its own URL; the package reads nothing. */
+  useIntent?(): CheckoutContext["intent"];
+  /** Resume from the SERVER, not only from a parked hand-off. */
+  useOpenPayable?(): { order: CheckoutOrder | null; pending: boolean };
+  /** Absent ⇒ `ports.exitToCatalog()`, which is what every host wires today. */
+  exit?: CheckoutExit;
+  /** The host invalidates ITS keys. */
+  onSettled?(outcome: OrderStatus, order: CheckoutOrder): void;
+}
+
+/** Whether a config asked for the pipeline at all. */
+export function pipelineRequested(config: CheckoutPipelineConfig): boolean {
+  return (
+    config.steps !== undefined ||
+    config.gates !== undefined ||
+    config.settlementMethods !== undefined ||
+    config.useIntent !== undefined ||
+    config.useOpenPayable !== undefined ||
+    config.exit !== undefined ||
+    config.onSettled !== undefined
+  );
+}

package/src/flows/public.ts

@@ -0,0 +1,78 @@
+/**
+ * THE FACTORY'S PUBLIC SURFACE — `createPaymentFlows` (FUT-741) and the
+ * checkout pipeline it can now run (FUT-1240).
+ *
+ * Listed here rather than inline in `src/index.ts` for the reason
+ * `./activation/public.ts` already gives: the root barrel is at its size gate,
+ * and a surface that grows with every plugin type is one that will keep
+ * growing. Everything below is re-exported verbatim by the root.
+ */
+
+// ---------------------------------------------------------------------------
+// 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: the hand-composing path is unchanged.
+// ---------------------------------------------------------------------------
+export { createPaymentFlows } from './create-payment-flows';
+// A type and nothing else now: `DEFAULT_CHECKOUT_COPY_FE` used to sit beside it
+// and was the only value this module ever published (FUT-760).
+export type { CheckoutCopyFE } from './copy';
+export {
+  type BoundCheckoutClient,
+  type BuyerDetailsProps,
+  type CheckoutAvailability,
+  type CheckoutConfigState,
+  type CheckoutController,
+  type CheckoutPorts,
+  type CheckoutScreens,
+  type PaymentFlows,
+  type PaymentFlowsConfig,
+} from './types';
+
+// ---------------------------------------------------------------------------
+// The checkout PIPELINE (FUT-1240) — steps, gates and settlement methods as
+// registered plugins, with the current step DERIVED from the server's own
+// facts rather than held in a `useState` a reload forgets.
+//
+// ADDITIVE: a host that registers none of these gets exactly the flat
+// three-step `CheckoutFlow`, unchanged, down to its test ids. What the types
+// below buy is the ability to say "this store has a step of its own", "this
+// shopper may not check out yet", and "this settlement raises no charge" — the
+// last of which the package had no seam for at all, so every in-person payment
+// path was written beside the checkout instead of inside it.
+// ---------------------------------------------------------------------------
+export type {
+  AnyCheckoutGate,
+  AnyCheckoutStep,
+  AnySettlementMethod,
+  CheckoutContext,
+  CheckoutExit,
+  CheckoutGate,
+  CheckoutPipelineConfig,
+  CheckoutStep,
+  CheckoutStepPhase,
+  CheckoutStepRender,
+  GateVerdict,
+  SettlementMethodDescriptor,
+  StepSlice,
+} from './pipeline/types';
+/**
+ * The step ids the PACKAGE registers, so a host ordering its own steps around
+ * them names a constant instead of retyping a string that can change.
+ */
+export {
+  DADOS_STEP_ID,
+  HANDOFF_STEP_ID,
+  METHOD_STEP_ID,
+  RESUME_STEP_ID,
+  STATUS_STEP_ID,
+} from './pipeline/steps';
+export { CARD_PANE_STEP, PIX_PANE_STEP } from './pipeline/methods';
+/**
+ * Where a step's parked slice lives — `payments.checkout.<slug>.<stepId>`.
+ * Public for the same reason `HOSTED_ORDER_STORAGE_KEY` is: a host clearing
+ * storage on sign-out, or a spec asserting a resume, otherwise retypes it.
+ */
+export { sliceKey } from './pipeline/slices';
+/** Whose plugin answers a refusal code — the routing, without the renderer. */
+export { refusalOwner, type RefusalOwner } from './pipeline/refusal-routing';

package/src/flows/screens-hosted.tsx

@@ -23,6 +23,7 @@
 import { Box } from "@mui/material";
 import { useEffect, useState, type JSX } from "react";
 
+import { parkedBasket, type CheckoutBasketIdentity } from "../components/checkout/basket";
 import { rememberHostedOrder, takeHostedOrder } from "../components/checkout/hosted-return";
 import type { CheckoutOrder, OrderStatus } from "../components/checkout/types";
 import { useCheckoutComponents } from "../components/checkout/ui";
@@ -31,15 +32,45 @@ import { usePaymentPolling } from "../components/checkout/use-payment-polling";
 import { FlowsShell, type FlowsRuntime } from "./runtime";
 import type { CheckoutScreens } from "./types";
 
+/** Whose store and which basket this hand-off belongs to. */
+interface HandoverScope {
+  tenantSlug?: string;
+  basket?: CheckoutBasketIdentity;
+}
+
 /** Park the order, then navigate — exactly once, even under StrictMode. */
-function useHandover(payable: CheckoutOrder, url: string, navigate: (url: string) => void): void {
+function useHandover(
+  payable: CheckoutOrder,
+  url: string,
+  navigate: (url: string) => void,
+  /**
+   * PARKED WITH THE STORE AND THE BASKET (FUT-1240).
+   *
+   * This call site named neither, and both absences are read as "no opinion"
+   * by the resume: `belongsHere` passes a slug-less entry at ANY store and the
+   * basket rule passes a basket-less entry against ANY basket. So the one
+   * hand-off screen this package ships was exempt from the multi-tenant
+   * scoping (FUT-556) and from the basket binding (FUT-1213) — it resumed over
+   * whatever checkout mounted next. The other three parks were fixed one at a
+   * time; this is the last of them.
+   */
+  scope: HandoverScope,
+): void {
   const [done, setDone] = useState(false);
   useEffect(() => {
     if (done) return;
     setDone(true);
-    rememberHostedOrder(payable);
+    const basket = parkedBasket(scope.basket);
+    // `handoff: true` is what tells the return leg this order was finished on
+    // ANOTHER SITE (FUT-1140): only such an order resumes onto the confirmation
+    // screen, because only such an order has nothing left on our page to show.
+    rememberHostedOrder(payable, {
+      ...(scope.tenantSlug === undefined ? {} : { tenantSlug: scope.tenantSlug }),
+      ...(basket === undefined ? {} : { basket }),
+      handoff: true,
+    });
     navigate(url);
-  }, [done, payable, url, navigate]);
+  }, [done, payable, url, navigate, scope.tenantSlug, scope.basket]);
 }
 
 function buildHostedHandoff(runtime: FlowsRuntime): CheckoutScreens["HostedHandoff"] {
@@ -54,7 +85,12 @@ function buildHostedHandoff(runtime: FlowsRuntime): CheckoutScreens["HostedHando
   }): JSX.Element {
     const { Button, LoadingState, Text } = useCheckoutComponents();
     const copy = runtime.copy;
-    useHandover(payable, url, runtime.navigate);
+    const tenantSlug = runtime.useTenantSlug();
+    const cart = runtime.config.useCart();
+    useHandover(payable, url, runtime.navigate, {
+      ...(tenantSlug === undefined ? {} : { tenantSlug }),
+      ...(cart.identity === undefined ? {} : { basket: cart.identity }),
+    });
     return (
       <Box
         data-testid="checkout-hosted-handoff"
@@ -163,6 +199,20 @@ function ReturnStalled({
   );
 }
 
+/**
+ * The parked order this return trip is for, or null.
+ *
+ * This screen is mounted at the host's RETURN route, so it carries no basket to
+ * weigh the entry against and the FUT-1213 rule cannot ask for one: with no
+ * basket named the decision is the pre-1213 one — resume what was parked —
+ * which is the right answer for a URL that exists only for buyers coming back
+ * from a payment. `ASK` is unreachable from here.
+ */
+function resumeParked(): CheckoutOrder | null {
+  const decision = takeHostedOrder();
+  return decision.verdict === "RESUME" ? decision.order : null;
+}
+
 function buildHostedReturn(runtime: FlowsRuntime): CheckoutScreens["HostedReturn"] {
   function HostedReturnBody({
     onResolved,
@@ -172,7 +222,7 @@ function buildHostedReturn(runtime: FlowsRuntime): CheckoutScreens["HostedReturn
     const { Alert, LoadingState } = useCheckoutComponents();
     // Read-and-clear, once, on first render: the resumed view belongs to
     // exactly one return trip.
-    const [parked] = useState(takeHostedOrder);
+    const [parked] = useState(resumeParked);
     // Bounded, for the reason on RETURN_WINDOW_MS: nothing here can ever reach a
     // terminal state on its own, so an unbounded poll is a spinner the buyer
     // watches until they close the tab.

package/src/flows/screens-pay.tsx

@@ -15,6 +15,7 @@ import { PixView } from "../components/checkout/pix-view";
 import type { CheckoutOrder, OrderStatus } from "../components/checkout/types";
 import { useCheckoutComponents } from "../components/checkout/ui";
 
+import { useCatalogExit } from "./catalog-exit";
 import { FlowsShell, useResolvedConfig, type FlowsRuntime } from "./runtime";
 import type { CheckoutScreens } from "./types";
 
@@ -79,6 +80,10 @@ function buildPaymentStatus(runtime: FlowsRuntime): CheckoutScreens["PaymentStat
     status: OrderStatus | null;
     payable?: CheckoutOrder | null;
   }) {
+    // The SAME door the chrome's back link takes (FUT-1240). Bound straight to
+    // the port, this control ignored a registered `exit` — so one host got its
+    // router from one way out of the checkout and a page load from the other.
+    const backToMenu = useCatalogExit(runtime);
     return (
       <FlowsShell runtime={runtime}>
         <PaymentStatusView
@@ -86,7 +91,7 @@ function buildPaymentStatus(runtime: FlowsRuntime): CheckoutScreens["PaymentStat
           status={status}
           totalLabel={payable?.totalLabel ?? ""}
           orderId={payable?.orderId}
-          onBackToMenu={runtime.config.ports.exitToCatalog}
+          onBackToMenu={backToMenu}
           paidExtra={runtime.config.confirmation?.extra}
         />
       </FlowsShell>

package/src/flows/types.ts

@@ -45,6 +45,7 @@ import type { useCheckoutController } from "../components/checkout/use-checkout-
 import type { Result } from "../result";
 
 import type { CheckoutCopyFE } from "./copy";
+import type { CheckoutPipelineConfig, GateVerdict } from "./pipeline/types";
 
 /** The host's remedy on the unavailable screen, and its veto over a live chain. */
 export interface CheckoutAvailability {
@@ -88,8 +89,17 @@ export interface CheckoutPorts {
   useAvailability?(): CheckoutAvailability;
 }
 
-/** What `createPaymentFlows` is configured with. */
-export interface PaymentFlowsConfig {
+/**
+ * What `createPaymentFlows` is configured with.
+ *
+ * It extends {@link CheckoutPipelineConfig}, whose every key is OPTIONAL: set
+ * one and `Checkout` renders through the checkout PIPELINE (FUT-1240); set
+ * none and it renders exactly the `CheckoutFlow` it always did, with the same
+ * pixels and the same test ids. That is the whole meaning of the pipeline
+ * landing additively — a host adopts it when it has a step, a gate or a
+ * settlement method of its own to register, and not a release earlier.
+ */
+export interface PaymentFlowsConfig extends CheckoutPipelineConfig {
   /** Where the `createPaymentFlowsBE` mount lives. Default `/api/checkout`. */
   transport?: CheckoutTransportBinding;
 
@@ -209,6 +219,19 @@ export interface PaymentFlows {
   screens: CheckoutScreens;
   /** The flow controller, pre-bound to the ports — the easy path is not the only path. */
   useCheckout(): CheckoutController;
+  /**
+   * MAY THIS SHOPPER CHECK OUT — the registered gate list, headless (FUT-1240).
+   *
+   * The same list, in the same order, that `Checkout` runs before it renders
+   * anything. Exported so the surfaces that OFFER a checkout — a cart
+   * drawer's CTA, a buy-now button — consume the answer the checkout will
+   * give rather than a second one of their own. Two surfaces deciding this
+   * separately is how a storefront ends up offering a checkout the checkout
+   * itself refuses.
+   *
+   * A host that registered no gates always passes.
+   */
+  useAdmission(): GateVerdict;
   useCheckoutConfig(): CheckoutConfigState;
   client: BoundCheckoutClient;
 }

package/src/index.ts

@@ -61,26 +61,14 @@ export {
 } 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.
+// The MOUNTED buyer checkout (FUT-741) and the checkout PIPELINE (FUT-1240).
+//
+// Listed in `./flows/public` rather than inline, on the `./activation/public`
+// precedent below: this barrel is at its size gate, and a surface that grows
+// with every plugin type belongs beside the plugins.
 // ---------------------------------------------------------------------------
-export { createPaymentFlows } from './flows/create-payment-flows';
-// A type and nothing else now: `DEFAULT_CHECKOUT_COPY_FE` used to sit beside it
-// and was the only value this module ever published (FUT-760).
-export 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 * from './flows/public';
+
 export {
   buyerFieldsFor,
   fieldSatisfied,
@@ -198,6 +186,28 @@ export {
   type CheckoutStepperStep,
   type CheckoutTextProps,
 } from './components/checkout/ui';
+/**
+ * WHICH basket a checkout is for (FUT-1213).
+ *
+ * A host computes the signature from its own cart lines and hands it to the
+ * flow on `cart.identity`, so a payment raised from an ABANDONED basket cannot
+ * resume itself over the one the shopper is holding now. Exported because the
+ * host owns the cart and therefore has to build it — see `basket.ts` for why
+ * the identity is the lines and never the cart's id.
+ */
+export {
+  basketSignature,
+  type CheckoutBasketIdentity,
+  type CheckoutBasketLine,
+} from './components/checkout/basket';
+/**
+ * WHY a card was refused, and whether another attempt could work (FUT-1145).
+ * A host wiring the confirmation screen's per-reason copy names these.
+ */
+export type {
+  CheckoutDecline,
+  CheckoutDeclineReason,
+} from './components/checkout/decline';
 export {
   type BuyerContact,
   type BuyerField,