@12-apps/payments-frontend 3.21.4 → 3.23.0

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

@@ -22,6 +22,8 @@ import { createCheckoutClient } from "../components/checkout/transport";
 import type { CheckoutProviderConfig, SettlementCheckout } from "../components/checkout/types";
 import { useCheckoutController } from "../components/checkout/use-checkout-controller";
 
+import { buildPipeline } from "./pipeline/engine";
+import { pipelineRequested } from "./pipeline/types";
 import { FlowsProvider, useResolvedConfig, type FlowsRuntime } from "./runtime";
 import { buyerScreens } from "./screens-buyer";
 import { hostedScreens } from "./screens-hosted";
@@ -150,6 +152,8 @@ function buildUseCheckout(runtime: FlowsRuntime): () => CheckoutController {
   return function useCheckout(): CheckoutController {
     const { config } = useResolvedConfig(runtime);
     const defaults = runtime.config.useBuyerDefaults?.() ?? {};
+    const cart = runtime.config.useCart();
+    const scope = { tenantSlug: runtime.useTenantSlug() };
     return useCheckoutController(
       {
         createOrder: ports.createPayable,
@@ -162,6 +166,11 @@ function buildUseCheckout(runtime: FlowsRuntime): () => CheckoutController {
       // Resolved for NO method: the gate runs on the Dados step, before the
       // picker, and FUT-595's rule is to collect the union up front.
       buyerFieldsFor(config?.chain, null),
+      scope.tenantSlug,
+      // WHICH basket, so a payment raised from another one cannot resume itself
+      // over it (FUT-1213). The host answers on its cart view; a host that does
+      // not gets the pre-1213 behaviour.
+      cart.identity,
     );
   };
 }
@@ -196,12 +205,21 @@ export function createPaymentFlows(config: PaymentFlowsConfig): PaymentFlows {
     );
   }
 
+  // THE ADDITIVE SWITCH (FUT-1240). A host that registered a step, a gate, a
+  // settlement method, an intent, an open payable, an exit or a settle
+  // callback gets the pipeline; a host that registered none gets the flat
+  // three-step flow, unchanged, down to its test ids. `useAdmission` is built
+  // either way — with no gates registered it passes, which is the honest
+  // answer for a host that has declared no admission rules.
+  const pipeline = buildPipeline(runtime, screens);
+
   return {
-    Checkout: buildCheckout(runtime, screens),
+    Checkout: pipelineRequested(config) ? pipeline.Checkout : buildCheckout(runtime, screens),
     Provider,
     screens,
     useCheckout: buildUseCheckout(runtime),
     useCheckoutConfig: () => useResolvedConfig(runtime),
+    useAdmission: pipeline.useAdmission,
     client: runtime.client,
   };
 }

package/src/flows/pipeline/actions.tsx

@@ -0,0 +1,104 @@
+/**
+ * WHAT A STEP CAN DO, as a context (FUT-1240).
+ *
+ * A step's `render` is handed only what §4.2 declares — its context, its
+ * facts, its slice, and the two navigations. Everything a step needs to CHANGE
+ * (choose a method, place the order, report a terminal status, edit the buyer)
+ * belongs to the engine, and the engine is the only writer of each.
+ *
+ * It arrives as a React context rather than as a closure, for one mechanical
+ * reason: the registered arrays must be identity-stable across renders (see
+ * `stable-plugins.ts`), so a step object cannot be rebuilt each render to
+ * capture this render's callbacks. A context is read where it is used, in a
+ * component, and leaves the step objects frozen.
+ */
+import { createContext, useContext, type JSX, type ReactNode } from "react";
+
+import type { CheckoutDecline } from "../../components/checkout/decline";
+import type {
+  BuyerInfo,
+  CheckoutError,
+  CheckoutOrder,
+  OrderStatus,
+} from "../../components/checkout/types";
+import type { CheckoutViewCopy } from "../../components/checkout/view-copy";
+import type { CheckoutScreens } from "../types";
+
+import type { AnySettlementMethod, CheckoutContext } from "./types";
+
+/** The engine's writers, plus the two tables a step renders from. */
+export interface PipelineActions {
+  /** Every screen the factory built, already bound to transport and slots. */
+  screens: CheckoutScreens;
+  /** The words. The engine's own two live under `copy.pipeline`. */
+  copy: CheckoutViewCopy;
+  /** Every registered settlement method, in picker order. */
+  methods: readonly AnySettlementMethod[];
+  /** The subset this shopper is actually offered, in the same order. */
+  offered: readonly AnySettlementMethod[];
+  /** The shopper picked a way to settle. Raises the payable unless a Review owns that. */
+  choose(methodId: string): void;
+  /** Raise the payable for the chosen method — a `Review`'s own action. */
+  place(): void;
+  /** A payable is being raised right now. */
+  placing: boolean;
+  /** "Continuar" on the buyer-details step: gate, persist, advance. */
+  continueFromDados(): void;
+  setBuyer(buyer: BuyerInfo): void;
+  saveProfile: boolean;
+  setSaveProfile(save: boolean): void;
+  /** A terminal status, carrying the refusal when the charge produced one. */
+  resolve(status: OrderStatus, decline?: CheckoutDecline | null): void;
+  /**
+   * Take up an order this visit did not raise — a resumed on-page charge.
+   * Separate from {@link PipelineActions.place} because nothing is being
+   * created: the charge exists, and what changes is only which order the walk
+   * is about.
+   */
+  adoptOrder(order: CheckoutOrder): void;
+  /** Leave for the host's catalog. */
+  exitToCatalog(): void;
+  /** The refusal the engine currently holds, whoever claimed it. */
+  error: CheckoutError | null;
+  /** Reopen the buyer-details step — the payer block's "alterar". */
+  editBuyer: (() => void) | undefined;
+}
+
+const PipelineActionsContext = createContext<PipelineActions | null>(null);
+
+/** The engine's actions. Throws outside the engine, on purpose. */
+export function usePipelineActions(): PipelineActions {
+  const actions = useContext(PipelineActionsContext);
+  if (!actions) {
+    throw new Error(
+      "usePipelineActions() was called outside the checkout pipeline. A step's " +
+        "render only runs inside <Checkout />; mounting one on its own is what " +
+        "`flows.screens.*` is for.",
+    );
+  }
+  return actions;
+}
+
+/** Supplied once by the engine, above every step. */
+export function PipelineActionsProvider({
+  actions,
+  children,
+}: {
+  actions: PipelineActions;
+  children: ReactNode;
+}): JSX.Element {
+  return (
+    <PipelineActionsContext.Provider value={actions}>
+      {children}
+    </PipelineActionsContext.Provider>
+  );
+}
+
+/** The descriptor for a chosen method, or `undefined` when nobody registered it. */
+export function descriptorFor(
+  methods: readonly AnySettlementMethod[],
+  ctx: CheckoutContext,
+): AnySettlementMethod | undefined {
+  if (ctx.method === null) return undefined;
+  return methods.find((entry) => entry.id === ctx.method);
+}

package/src/flows/pipeline/admission.ts

@@ -0,0 +1,55 @@
+/**
+ * MAY THIS SHOPPER CHECK OUT — one answer, offered headless (FUT-1240).
+ *
+ * The gates run in ARRAY ORDER and the first non-`pass` verdict wins. Order
+ * matters and is the host's to choose: a gate that would curtain the screen
+ * must not speak before the gate that is still waiting for the cart, or a
+ * shopper meets "loja fechada" because a fact had not arrived yet.
+ *
+ * Exported as `flows.useAdmission()` so the cart drawer's CTA and a
+ * buy-now button consume the SAME list the checkout does. Two surfaces
+ * deciding this separately is how a storefront ends up with a drawer that
+ * offers a checkout the checkout itself refuses.
+ */
+import { hostedCheckoutReturnPending } from "../../components/checkout/hosted-return";
+
+import type { AnyCheckoutGate, CheckoutContext, GateVerdict } from "./types";
+
+/** Nothing said otherwise. */
+const PASS: GateVerdict = { kind: "pass" };
+
+/**
+ * The gates' verdict, given the facts each of them returned.
+ *
+ * Pure: the hooks run in the caller's body, in array order, and their answers
+ * arrive here as a list. That is what makes this testable without a renderer
+ * and what keeps hook order a property of the ARRAY rather than of the
+ * verdicts.
+ */
+export function decideAdmission(input: {
+  gates: readonly AnyCheckoutGate[];
+  facts: readonly unknown[];
+  ctx: CheckoutContext;
+  /** A hand-off from this tab is still waiting — see `standsAsideForResume`. */
+  resuming: boolean;
+}): GateVerdict {
+  for (const [at, gate] of input.gates.entries()) {
+    // A gate that stands aside for a resume is standing aside from the one
+    // route where money gets confirmed. Skipped for that visit only.
+    if (input.resuming && gate.standsAsideForResume) continue;
+    const verdict = gate.decide(input.ctx, input.facts[at]);
+    if (verdict.kind !== "pass") return verdict;
+  }
+  return PASS;
+}
+
+/**
+ * Whether a hand-off from this tab is still waiting to be resolved.
+ *
+ * Asked with the SAME slug and basket the resume asks with, so a gate and the
+ * flow behind it cannot disagree about whose return this is — the property
+ * `hostedCheckoutReturnPending`'s own doc argues for at length.
+ */
+export function resumePending(ctx: CheckoutContext): boolean {
+  return hostedCheckoutReturnPending(ctx.tenantSlug, ctx.cart.identity);
+}

package/src/flows/pipeline/context.ts

@@ -0,0 +1,140 @@
+/**
+ * THE CONTEXT EVERY PLUGIN READS, built once from the host's own hooks
+ * (FUT-1240).
+ *
+ * One builder, used by BOTH the engine and `flows.useAdmission()`, so the
+ * headless admission the cart drawer asks and the checkout the shopper reaches
+ * cannot disagree about the same shopper. That was the whole harm behind
+ * "three exemption sets": every surface answered "may this store take money"
+ * from its own reading of its own facts.
+ *
+ * Every field is server-owned or parked. Nothing here is React state the
+ * engine happens to hold — the engine layers its own on top with
+ * {@link withCheckoutState}, and only there.
+ */
+import type { CheckoutOrder } from "../../components/checkout/types";
+
+import { useResolvedConfig, type FlowsRuntime } from "../runtime";
+
+import type { CheckoutContext, CheckoutPipelineConfig } from "./types";
+
+/** No host `useIntent` ⇒ no one-click, no resume request, no preset method. */
+const NO_INTENT: CheckoutContext["intent"] = Object.freeze({
+  oneClick: false,
+  resuming: false,
+  presetMethod: null,
+});
+
+/** No host `useOpenPayable` ⇒ the server is never asked; the park still answers. */
+const NO_OPEN_PAYABLE: { order: CheckoutOrder | null; pending: boolean } = Object.freeze({
+  order: null,
+  pending: false,
+});
+
+/**
+ * The two reads only a HOST can answer: what the address bar asked for, and
+ * what the server says is already in flight.
+ *
+ * Its own function so the defaulting stays in one place — and so the base
+ * builder below reads as a list of facts rather than as a chain of `??`.
+ */
+function usePipelineReads(pipeline: CheckoutPipelineConfig): {
+  intent: CheckoutContext["intent"];
+  openPayable: { order: CheckoutOrder | null; pending: boolean };
+} {
+  const intent = pipeline.useIntent?.() ?? NO_INTENT;
+  const openPayable = pipeline.useOpenPayable?.() ?? NO_OPEN_PAYABLE;
+  return { intent, openPayable };
+}
+
+/** The base context plus the two reads a caller may need on their own. */
+interface CheckoutBase {
+  ctx: CheckoutContext;
+  openPayable: { order: CheckoutOrder | null; pending: boolean };
+  /** The buyer's saved details are still being fetched. */
+  buyerPending: boolean;
+}
+
+/**
+ * The host's facts, as a context.
+ *
+ * `method`, `order`, `outcome` and `slices` are at their resting values here:
+ * an admission decision is about the SHOPPER and the STORE, never about how
+ * far into a payment somebody is. The engine supplies the rest.
+ */
+export function useCheckoutBase(
+  runtime: FlowsRuntime,
+  pipeline: CheckoutPipelineConfig,
+): CheckoutBase {
+  const cart = runtime.config.useCart();
+  const defaults = runtime.config.useBuyerDefaults?.() ?? {};
+  const settlement = runtime.config.useSettlement?.() ?? null;
+  const { config, pending } = useResolvedConfig(runtime);
+  const tenantSlug = runtime.useTenantSlug();
+  const { intent, openPayable } = usePipelineReads(pipeline);
+  return {
+    ctx: {
+      ...(tenantSlug === undefined ? {} : { tenantSlug }),
+      config,
+      configPending: pending,
+      cart,
+      settlement,
+      ...buyerFacts(defaults),
+      ...AT_REST,
+      order: openPayable.order,
+      intent,
+    },
+    openPayable,
+    buyerPending: defaults.pending ?? false,
+  };
+}
+
+/** Nothing has been chosen, raised or answered yet. */
+const AT_REST = Object.freeze({
+  method: null,
+  outcome: null,
+  slices: Object.freeze({}),
+} as const);
+
+/** The buyer half, with the two absences that mean "the host wired none". */
+function buyerFacts(defaults: {
+  buyer?: CheckoutContext["buyer"];
+  taxIdOnFile?: boolean;
+}): Pick<CheckoutContext, "buyer" | "taxIdOnFile"> {
+  return {
+    buyer: defaults.buyer ?? {},
+    taxIdOnFile: defaults.taxIdOnFile ?? false,
+  };
+}
+
+/** What the ENGINE knows and the base does not. */
+interface CheckoutEngineState {
+  buyer: CheckoutContext["buyer"];
+  method: string | null;
+  order: CheckoutOrder | null;
+  outcome: CheckoutContext["outcome"];
+  slices: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * The base context with the engine's own state laid over it.
+ *
+ * The BUYER is overlaid rather than merged: the shopper may have typed a CPF
+ * for this purchase over the one on file, and the whole of `checkout-skip-dados`
+ * turns on that replacement being visible to every later step.
+ */
+export function withCheckoutState(
+  base: CheckoutContext,
+  state: CheckoutEngineState,
+): CheckoutContext {
+  return {
+    ...base,
+    buyer: state.buyer,
+    method: state.method,
+    // The just-raised order wins over whatever the server or the park offered:
+    // it is the one this visit is actually paying.
+    order: state.order ?? base.order,
+    outcome: state.outcome,
+    slices: state.slices,
+  };
+}

package/src/flows/pipeline/derive-step.ts

@@ -0,0 +1,234 @@
+/**
+ * WHICH STEP THE SHOPPER IS ON — derived, never remembered (FUT-1240).
+ *
+ * The flat controller holds `useState<Step>`, so a reload, a discarded tab or
+ * a return from a provider's own page all forget where the shopper was. Here
+ * the answer is a function of facts the SERVER owns (the cart, the buyer's
+ * `hasTaxId`, the open payable) plus the steps' own declared slices, so it is
+ * the same answer before and after the page goes away.
+ *
+ * ## It reproduces `useCheckoutNav` exactly, and that is the point
+ *
+ * `checkout-actions.ts`'s nav has three rules that look like details and are
+ * not, because the money path walks through them:
+ *
+ *  - back off the payment step lands on Dados — UNLESS the buyer has a CPF on
+ *    file and has never opened Dados, in which case that step is not part of
+ *    their flow and the only honest destination is the catalog;
+ *  - "alterar" (`editBuyer`) exists ONLY for a buyer whose Dados was skipped,
+ *    and opening it makes Dados part of their flow from then on;
+ *  - back off the CONFIRMATION is the catalog, always. The flat nav maps back
+ *    to Dados only from `payment`; every other step goes to the menu.
+ *
+ * The first two fall out of one general rule here: **back re-opens the PREVIOUS
+ * APPLYING step, and exits when there is none.** A skipped Dados does not
+ * apply, so it is not the previous applying step, so back exits — which is the
+ * second rule verbatim. `editBuyer` flips the Dados slice's `opened`, after
+ * which Dados applies and back returns to it — which is the first.
+ *
+ * The third does NOT, and stating it separately is the whole of {@link
+ * deriveNav}'s `terminal`. A paid Pix order leaves its pane APPLYING — an order
+ * exists, nothing handed over — and merely COMPLETE, so the previous applying
+ * step behind the confirmation is the payment surface for money that already
+ * moved. Re-opening it puts a live pay button in front of a shopper who has
+ * paid, which is the hazard `ADOPTING.md` records under one owner paying four
+ * times.
+ */
+import type {
+  AnyCheckoutStep,
+  AnySettlementMethod,
+  CheckoutContext,
+  CheckoutStepPhase,
+} from "./types";
+
+/** Phases in walk order. A step's `order` breaks ties inside one phase. */
+const PHASE_ORDER: readonly CheckoutStepPhase[] = [
+  "details",
+  "before-pay",
+  "pay",
+  "after-pay",
+];
+
+/** Facts, by step id — the engine runs every `useFacts()` once, in array order. */
+type StepFacts = Readonly<Record<string, unknown>>;
+
+/** What a walk over the registered steps produced. */
+interface DerivedStep {
+  /** The step to render, or `null` when nothing applies yet. */
+  step: AnyCheckoutStep | null;
+  /** Every step that applies to THIS shopper, in walk order. */
+  applying: readonly AnyCheckoutStep[];
+  /** `step`'s index in {@link applying}, or `-1`. */
+  index: number;
+}
+
+/**
+ * The registered steps in walk order.
+ *
+ * Sorted stably: two steps in the same phase with the same `order` keep the
+ * order their arrays were merged in, so a host appending a step never reshuffles
+ * the package's own.
+ */
+function orderedSteps(steps: readonly AnyCheckoutStep[]): AnyCheckoutStep[] {
+  return steps
+    .map((step, at) => ({ step, at }))
+    .sort((left, right) => {
+      const phase =
+        PHASE_ORDER.indexOf(left.step.phase) - PHASE_ORDER.indexOf(right.step.phase);
+      if (phase !== 0) return phase;
+      const order = (left.step.order ?? 0) - (right.step.order ?? 0);
+      return order !== 0 ? order : left.at - right.at;
+    })
+    .map((entry) => entry.step);
+}
+
+/**
+ * THE NO-CHARGE RULE, stated once.
+ *
+ * A settlement method whose `raisesCharge` is `false` mounts no payment
+ * surface after it is chosen: no Dados-for-the-charge, no method pane, no
+ * poll. Enforced here rather than in each lane, because "each lane" is exactly
+ * how a delivery checkout ended up rendering a PIX pane for a shopper paying
+ * the courier.
+ *
+ * Unknown method ⇒ the rule does not fire. An id nobody registered cannot be
+ * asserted to raise no charge, and refusing the pay phase on a guess would
+ * strand a shopper mid-payment.
+ */
+export function raisesCharge(
+  method: string | null,
+  methods: readonly AnySettlementMethod[],
+): boolean {
+  if (method === null) return true;
+  const descriptor = methods.find((entry) => entry.id === method);
+  return descriptor ? descriptor.raisesCharge : true;
+}
+
+/**
+ * A step's slice, with the step's own `initial` standing in when the context
+ * carries none.
+ *
+ * The engine seeds every slice at mount, so in a live checkout this fallback
+ * never fires. It exists because `complete()` is a step author's function and
+ * must never be handed `undefined` where its type says `S` — a walk that
+ * throws while deciding where the shopper is would take the whole checkout
+ * with it, and the cause would be an absent key.
+ */
+export function sliceFor(step: AnyCheckoutStep, ctx: CheckoutContext): unknown {
+  const value = ctx.slices[step.id];
+  if (value !== undefined) return value;
+  return step.slice ? step.slice.initial(ctx) : undefined;
+}
+
+/** What `deriveStep` is asked. */
+interface DeriveStepInput {
+  steps: readonly AnyCheckoutStep[];
+  ctx: CheckoutContext;
+  facts: StepFacts;
+  methods: readonly AnySettlementMethod[];
+  /** A step the shopper navigated BACK to; it wins while it still applies. */
+  reopened?: string | null;
+}
+
+/**
+ * THE PANE RULE, stated once — the other half of the no-charge one.
+ *
+ * A `pay`-phase step that some registered method named as its
+ * {@link AnySettlementMethod.pane} belongs to THAT method: it applies while
+ * that method is the chosen one and never otherwise. A `pay` step nobody named
+ * — the hand-off interstitial, which is about the ORDER rather than about the
+ * method — is untouched by this.
+ *
+ * Stated here rather than as a `ctx.method === "PIX"` inside each pane, because
+ * a descriptor field that decides nothing is config that lies: `pane` was
+ * declared, documented and read nowhere while the two panes hard-coded the very
+ * ids it names.
+ */
+function paneApplies(
+  step: AnyCheckoutStep,
+  ctx: CheckoutContext,
+  methods: readonly AnySettlementMethod[],
+): boolean {
+  if (!methods.some((entry) => entry.pane === step.id)) return true;
+  const chosen = methods.find((entry) => entry.id === ctx.method);
+  return chosen?.pane === step.id;
+}
+
+/** The steps that apply to this shopper, with the no-charge rule already applied. */
+export function applyingSteps(input: DeriveStepInput): AnyCheckoutStep[] {
+  const { ctx, facts, methods } = input;
+  const charges = raisesCharge(ctx.method, methods);
+  return orderedSteps(input.steps).filter((step) => {
+    if (step.phase === "pay") {
+      if (!charges) return false;
+      if (!paneApplies(step, ctx, methods)) return false;
+    }
+    return step.applies(ctx, facts[step.id]);
+  });
+}
+
+/**
+ * The current step: the first applying step whose `complete()` is false, plus
+ * the one explicit override — a step the shopper pressed back into.
+ *
+ * All complete ⇒ the LAST applying step, which is the terminal one. The
+ * package's own confirmation answers `complete: false` forever, so this is a
+ * safety net rather than a path: a walk whose every step is finished has
+ * nowhere else to put the shopper.
+ */
+export function deriveStep(input: DeriveStepInput): DerivedStep {
+  const applying = applyingSteps(input);
+  const reopened = input.reopened ?? null;
+  const back = reopened === null ? -1 : applying.findIndex((step) => step.id === reopened);
+  if (back !== -1) return { step: applying[back] ?? null, applying, index: back };
+  const at = applying.findIndex(
+    (step) => !step.complete(input.ctx, input.facts[step.id], sliceFor(step, input.ctx)),
+  );
+  if (at !== -1) return { step: applying[at] ?? null, applying, index: at };
+  const last = applying.length - 1;
+  return { step: applying[last] ?? null, applying, index: last };
+}
+
+/** The ports `deriveNav` drives — the engine's own writers, named. */
+interface NavPorts {
+  /** Mark a step as the one the shopper went back to. */
+  reopen(stepId: string): void;
+  /** Open the buyer-details step for a shopper whose CPF made it skippable. */
+  openDados(): void;
+  /** Leave checkout for the host's catalog. */
+  exitToCatalog(): void;
+}
+
+/**
+ * `back` and `editBuyer`, reproducing `useCheckoutNav` (FUT-465, FUT-1216
+ * risk 2).
+ *
+ * `editBuyer` is `undefined` unless Dados was SKIPPED — the payer block keys
+ * off its presence, so the decision lives here rather than being re-derived by
+ * every caller, exactly as it did in the flat controller.
+ *
+ * `terminal` is `ctx.outcome !== null`, and it is the flat nav's "from `status`
+ * you go to the menu" — see the third rule at the top of this file. It is asked
+ * of the OUTCOME rather than of the last step's identity so that a host's own
+ * confirmation, and a FAILED or EXPIRED one, answer the same way: once this
+ * checkout has an outcome there is nothing behind it a shopper should be sent
+ * back into.
+ */
+export function deriveNav(input: {
+  applying: readonly AnyCheckoutStep[];
+  index: number;
+  taxIdOnFile: boolean;
+  /** The walk has an outcome — `ctx.outcome !== null`. */
+  terminal: boolean;
+  ports: NavPorts;
+}): { back(): void; editBuyer: (() => void) | undefined } {
+  const { applying, index, ports } = input;
+  const previous = input.terminal || index <= 0 ? undefined : applying[index - 1];
+  return {
+    back() {
+      if (previous) ports.reopen(previous.id);
+      else ports.exitToCatalog();
+    },
+    editBuyer: input.taxIdOnFile ? ports.openDados : undefined,
+  };
+}