@12-apps/payments-frontend 3.21.4 → 3.23.0

package/src/flows/pipeline/engine-actions.ts

@@ -0,0 +1,257 @@
+/**
+ * WHAT THE ENGINE DOES WHEN A STEP ASKS (FUT-1240).
+ *
+ * One writer per fact, and every one of them here: choosing a method, raising
+ * the payable, passing the buyer-details gate, reporting a terminal status,
+ * navigating back and leaving. A step calls these; nothing else writes.
+ *
+ * The payable is raised in ONE place, for every settlement method. What
+ * differs for a method that raises no charge is not the call — it is that the
+ * engine parks nothing and treats the placement itself as the settlement, so
+ * the walk goes straight to the confirmation with no pane in between.
+ */
+import { useCallback, useMemo } from "react";
+
+import { buyerFieldsFor } from "../../components/checkout/buyer-fields";
+import { buyerGateError } from "../../components/checkout/buyer-gate";
+import { parkedBasket } from "../../components/checkout/basket";
+import type { CheckoutDecline } from "../../components/checkout/decline";
+import { forgetHostedOrder, rememberHostedOrder } from "../../components/checkout/hosted-return";
+import { handOffMethod, offeredMethods } from "../../components/checkout/method-capability";
+import type {
+  BuyerInfo,
+  CheckoutOrder,
+  CreateOrderRequest,
+  OrderStatus,
+  PaymentMethod,
+} from "../../components/checkout/types";
+import { useCatalogExit } from "../catalog-exit";
+import type { FlowsRuntime } from "../runtime";
+
+import { applyingSteps, raisesCharge, sliceFor } from "./derive-step";
+import type { EngineStore } from "./engine-state";
+import { isPackageMethod } from "./methods";
+import {
+  BUYER_FIELD_CODE,
+  DADOS_STEP_ID,
+  METHOD_STEP_ID,
+  dadosSliceOf,
+} from "./steps";
+import type {
+  AnyCheckoutGate,
+  AnyCheckoutStep,
+  AnySettlementMethod,
+  CheckoutContext,
+} from "./types";
+
+/** Everything one factory's engine closes over. Built once, never per render. */
+export interface PipelineWiring {
+  steps: readonly AnyCheckoutStep[];
+  gates: readonly AnyCheckoutGate[];
+  methods: readonly AnySettlementMethod[];
+}
+
+/**
+ * The `method` the WIRE carries for a settlement this package cannot name.
+ *
+ * `method` is what the CHAIN can be asked to charge, so a host's registered id
+ * is never one of its values: the chain's own hand-off method is what the
+ * server will honour, exactly as it is for a store whose buyer was never asked.
+ *
+ * WHICH settlement the buyer actually chose rides {@link settlementOnWire}
+ * beside it. It has to: `method` alone makes a courier, a waiter and a Pix
+ * charge the same request, and `raisesCharge: false` is the capability this
+ * step exists for.
+ */
+function wireMethod(id: string, ctx: CheckoutContext): PaymentMethod {
+  return isPackageMethod(id) ? id : handOffMethod(offeredMethods(ctx.config));
+}
+
+/**
+ * The chosen id, for a settlement the two package methods do not cover.
+ *
+ * ABSENT for `PIX` and `CARD` — a host reading only `method` reads exactly the
+ * request it read before this field existed, which is the whole of the wire
+ * staying additive. A step that wants to say something else still can: its
+ * `contribute` returns `Partial<CreateOrderRequest>`, and the contributions are
+ * folded over this base.
+ */
+function settlementOnWire(id: string): Pick<CreateOrderRequest, "settlementMethod"> {
+  return isPackageMethod(id) ? {} : { settlementMethod: id };
+}
+
+/** The create request: the method, the buyer, and whatever each step contributes. */
+function createRequest(input: {
+  ctx: CheckoutContext;
+  applying: readonly AnyCheckoutStep[];
+  stepFacts: Readonly<Record<string, unknown>>;
+  saveProfile: boolean;
+  methodId: string;
+}): CreateOrderRequest {
+  const base: CreateOrderRequest = {
+    method: wireMethod(input.methodId, input.ctx),
+    buyer: input.ctx.buyer,
+    saveProfile: input.saveProfile,
+    ...settlementOnWire(input.methodId),
+  };
+  return input.applying.reduce<CreateOrderRequest>(
+    (request, step) => ({
+      ...request,
+      ...step.contribute?.(input.ctx, input.stepFacts[step.id], sliceFor(step, input.ctx)),
+    }),
+    base,
+  );
+}
+
+/** What the writers need from the render they were built in. */
+interface EngineWritersInput {
+  runtime: FlowsRuntime;
+  wiring: PipelineWiring;
+  store: EngineStore;
+  ctx: CheckoutContext;
+  stepFacts: Readonly<Record<string, unknown>>;
+}
+
+/** The engine's writers. */
+interface EngineWriters {
+  choose(methodId: string): void;
+  place(): void;
+  continueFromDados(): void;
+  setBuyer(buyer: BuyerInfo): void;
+  setSaveProfile(save: boolean): void;
+  resolve(status: OrderStatus, decline?: CheckoutDecline | null): void;
+  adoptOrder(order: CheckoutOrder): void;
+  exitToCatalog(): void;
+  reopen(stepId: string): void;
+  openDados(): void;
+  retry(): void;
+}
+
+/** Raise the payable, park it when it can be resumed, and record what came back. */
+function usePlaceOrder(input: EngineWritersInput): (methodId?: string) => Promise<void> {
+  const { runtime, store, ctx, wiring, stepFacts } = input;
+  const saveProfile = store.state.saveProfile;
+  return useCallback(
+    async (methodId?: string) => {
+      const chosen = methodId ?? ctx.method;
+      if (chosen === null) return;
+      store.patch({ placing: true, error: null, decline: null });
+      // The walk is re-derived FOR THE CHOSEN METHOD, not read off the render
+      // that offered the picker: a step whose `applies` asks which settlement
+      // this is would otherwise be absent from the request that settles it.
+      // ONE context, used for both halves. Deriving the walk against the chosen
+      // method and then building the request against the un-overridden `ctx` let
+      // a step's `contribute` read `ctx.method === null` on the immediate-place
+      // path, which is the path a method with no Review takes — so the field
+      // ADOPTING.md says a step may set "when the settlement has a finer name
+      // than the tile does" was written from a context that did not know it.
+      const applyingCtx = { ...ctx, method: chosen };
+      const applying = applyingSteps({
+        steps: wiring.steps,
+        ctx: applyingCtx,
+        facts: stepFacts,
+        methods: wiring.methods,
+      });
+      const request = createRequest({
+        ctx: applyingCtx,
+        applying,
+        stepFacts,
+        saveProfile,
+        methodId: chosen,
+      });
+      const result = await runtime.config.ports.createPayable(request);
+      if (!result.ok) {
+        store.patch({ placing: false, error: result.error });
+        return;
+      }
+      const charges = raisesCharge(chosen, wiring.methods);
+      // PARKED ON EVERY RAISE (FUT-1140), with the STORE and the BASKET — a
+      // low-memory phone discards this tab while the shopper is in their bank
+      // app. A settlement that raises no charge has nothing to come back to.
+      if (charges) {
+        rememberHostedOrder(result.data, {
+          ...(ctx.tenantSlug === undefined ? {} : { tenantSlug: ctx.tenantSlug }),
+          basket: parkedBasket(ctx.cart.identity),
+          handoff: false,
+        });
+      }
+      store.patch({
+        placing: false,
+        order: result.data,
+        // Placing IS the settlement for a no-charge method, so its own status
+        // is already the outcome — there is no pane and no poll to wait for.
+        outcome: charges ? null : result.data.status,
+      });
+    },
+    [runtime, store, ctx, wiring, stepFacts, saveProfile],
+  );
+}
+
+/** "Continuar" on the buyer-details step: gate on the chain's demands, then persist. */
+function useContinueFromDados(input: EngineWritersInput): () => void {
+  const { runtime, store, ctx } = input;
+  const copy = runtime.config.copy.views.screens.screens.validation;
+  const fields = useMemo(() => buyerFieldsFor(ctx.config?.chain, null), [ctx.config]);
+  return useCallback(() => {
+    const complaint = buyerGateError(copy, ctx.buyer, fields, ctx.taxIdOnFile);
+    if (complaint) {
+      store.patch({
+        error: { code: BUYER_FIELD_CODE, message: complaint.message, field: complaint.field },
+      });
+      return;
+    }
+    // The write happens HERE and not when a payment is raised: everything after
+    // this step can fail, and the details must survive all of it (FUT-465).
+    if (store.state.saveProfile) {
+      runtime.config.ports.saveBuyerContact?.({
+        ...(ctx.buyer.name === undefined ? {} : { name: ctx.buyer.name }),
+        ...(ctx.buyer.phone === undefined ? {} : { phone: ctx.buyer.phone }),
+        ...(ctx.buyer.taxId === undefined ? {} : { taxId: ctx.buyer.taxId }),
+      });
+    }
+    store.setSlice(DADOS_STEP_ID, { ...dadosSliceOf(ctx), done: true });
+    store.patch({ reopened: null, error: null });
+  }, [copy, ctx, fields, runtime, store]);
+}
+
+/** Every writer, bound to this render's context. */
+export function useEngineWriters(input: EngineWritersInput): EngineWriters {
+  const { runtime, store, ctx, wiring } = input;
+  const placeOrder = usePlaceOrder(input);
+  const continueFromDados = useContinueFromDados(input);
+  const exitToCatalog = useCatalogExit(runtime);
+  const choose = useCallback(
+    (methodId: string) => {
+      // A different method means the order raised for the previous one is
+      // gone — and the parked entry with it, scoped to THIS store so another
+      // store's checkout in the same tab keeps its own.
+      store.setSlice(METHOD_STEP_ID, { chosen: methodId });
+      store.patch({ order: null, error: null, decline: null, reopened: null });
+      forgetHostedOrder(ctx.tenantSlug);
+      const descriptor = wiring.methods.find((entry) => entry.id === methodId);
+      if (!descriptor?.Review) void placeOrder(methodId);
+    },
+    [store, ctx.tenantSlug, wiring.methods, placeOrder],
+  );
+  return useMemo(
+    () => ({
+      choose,
+      continueFromDados,
+      exitToCatalog,
+      place: () => void placeOrder(),
+      setBuyer: (buyer: BuyerInfo) =>
+        store.patch({ buyer, buyerTouched: true, error: null }),
+      setSaveProfile: (saveProfile: boolean) => store.patch({ saveProfile }),
+      resolve: (status: OrderStatus, decline?: CheckoutDecline | null) =>
+        store.patch({ outcome: status, decline: decline ?? null, reopened: null, error: null }),
+      adoptOrder: (order: CheckoutOrder) => store.patch({ order, error: null }),
+      reopen: (stepId: string) => store.patch({ reopened: stepId }),
+      openDados: () => {
+        store.setSlice(DADOS_STEP_ID, { opened: true, done: false });
+        store.patch({ reopened: null, error: null });
+      },
+      retry: () => store.patch({ error: null, decline: null, reopened: null }),
+    }),
+    [choose, continueFromDados, exitToCatalog, placeOrder, store],
+  );
+}

package/src/flows/pipeline/engine-chrome.tsx

@@ -0,0 +1,123 @@
+/**
+ * THE ENGINE'S OWN CHROME (FUT-1240) — the two things that are not a step.
+ *
+ * A back control and a progress header, at the flat flow's own TEST IDS:
+ * `checkout-back` and `checkout-stepper` are the hooks the storefront journeys
+ * click, and a walk that renders different ones would be a rewrite wearing a
+ * refactor's clothes.
+ *
+ * ## What is NOT the flat flow's, and deliberately
+ *
+ * The flat `ProgressHeader` renders three FIXED nodes — Dados, Pagamento,
+ * Confirmação — for every shopper. Here the nodes are DERIVED like everything
+ * else: the applying steps that named a label, in walk order. So a shopper with
+ * a CPF on file, whose Dados step is not part of their walk at all (FUT-465),
+ * sees the steps they will actually be asked for rather than one they will
+ * never be shown. The same derivation is what lets a host's registered step
+ * appear in the stepper without the header knowing it exists.
+ *
+ * A step with no label is an interstitial — the hand-off and the resume are not
+ * places a shopper is asked to be — so those draw no node either.
+ *
+ * The back link's wording follows the same derivation: it offers "keep
+ * shopping" on the FIRST applying step, where back leaves for the catalog,
+ * rather than on the id `dados` specifically.
+ */
+import { Box } from "@mui/material";
+import type { JSX } from "react";
+
+import { ArrowBackIcon } from "../../components/checkout/icons";
+import { useCheckoutComponents } from "../../components/checkout/ui";
+import type { CheckoutViewCopy } from "../../components/checkout/view-copy";
+
+import type { AnyCheckoutStep } from "./types";
+
+/** The stepper nodes: applying steps that named a label, already worded. */
+function stepperNodes(
+  applying: readonly AnyCheckoutStep[],
+  copy: CheckoutViewCopy,
+): { id: string; label: string }[] {
+  const nodes: { id: string; label: string }[] = [];
+  for (const step of applying) {
+    const label = step.label;
+    if (typeof label !== "string") continue;
+    nodes.push({ id: step.id, label: copy.steps[label] });
+  }
+  return nodes;
+}
+
+/** The slim header: the walk's only nav, and it is step-aware. */
+export function EngineChrome({
+  copy,
+  applying,
+  currentId,
+  first,
+  onBack,
+}: {
+  copy: CheckoutViewCopy;
+  applying: readonly AnyCheckoutStep[];
+  currentId: string | null;
+  /**
+   * The shopper is on the first applying step, which is where the link is
+   * worded "continuar comprando" rather than "voltar".
+   *
+   * It is about the WORDING only. Where back actually goes is `deriveNav`'s,
+   * and it leaves for the catalog from a settled confirmation too — where the
+   * flat flow also says "voltar" and also goes to the menu.
+   */
+  first: boolean;
+  onBack(): void;
+}): JSX.Element {
+  const { Button, Stepper } = useCheckoutComponents();
+  const nodes = stepperNodes(applying, copy);
+  const at = nodes.findIndex((node) => node.id === currentId);
+  const completed = new Set(nodes.slice(0, Math.max(at, 0)).map((node) => node.id));
+  return (
+    <>
+      <Box sx={{ minHeight: 36, display: "flex", alignItems: "center", gap: 1 }}>
+        <Button
+          variant="text"
+          color="neutral"
+          size="sm"
+          icon={<ArrowBackIcon fontSize="small" />}
+          iconPosition="left"
+          onClick={onBack}
+          dataTestId="checkout-back"
+        >
+          {first ? copy.dados.keepShopping : copy.dados.back}
+        </Button>
+      </Box>
+      {nodes.length === 0 ? null : (
+        <Box sx={{ height: 50, display: "flex", flexDirection: "column", justifyContent: "center" }}>
+          <Stepper
+            steps={nodes}
+            activeId={currentId ?? ""}
+            completed={completed}
+            orientation="horizontal"
+            size="sm"
+            data-testid="checkout-stepper"
+          />
+        </Box>
+      )}
+    </>
+  );
+}
+
+/**
+ * Nothing to show yet — a gate still deciding, the store's protocol still in
+ * flight, or a walk with no applying step.
+ *
+ * It exists because the alternative is a blank frame, and a shopper who taps
+ * "pagar" and gets an empty page taps again.
+ */
+export function EngineLoading({ copy }: { copy: CheckoutViewCopy }): JSX.Element {
+  const { LoadingState } = useCheckoutComponents();
+  return (
+    <LoadingState
+      variant="spinner"
+      size="md"
+      message={copy.pipeline.loading}
+      dataTestId="checkout-pipeline-loading"
+    />
+  );
+}

package/src/flows/pipeline/engine-state.ts

@@ -0,0 +1,107 @@
+/**
+ * THE ENGINE'S OWN STATE, and the one writer of each fact (FUT-1240).
+ *
+ * Everything here is state a STEP reads and only the engine writes. Which step
+ * the shopper is on is deliberately NOT among them — that is derived (see
+ * `derive-step.ts`), which is the whole point of the pipeline.
+ *
+ * `slices` lives here rather than inside each step because the engine owns the
+ * storage: one `useState` for every step's scrap, so the number of hooks does
+ * not depend on how many steps a host registered.
+ */
+import { useCallback, useMemo, useState } from "react";
+
+import type { CheckoutDecline } from "../../components/checkout/decline";
+import type {
+  BuyerInfo,
+  CheckoutError,
+  CheckoutOrder,
+  OrderStatus,
+} from "../../components/checkout/types";
+
+import { initialSlices, writeSlice } from "./slices";
+import type { AnyCheckoutStep, CheckoutContext } from "./types";
+
+/** What one visit accumulates. */
+export interface EngineState {
+  buyer: BuyerInfo;
+  /**
+   * The shopper has edited the buyer form, so the host's saved defaults must
+   * stop overwriting it. Until they have, the defaults are adopted live —
+   * a profile that arrives after mount still prefills the form it is for.
+   */
+  buyerTouched: boolean;
+  saveProfile: boolean;
+  order: CheckoutOrder | null;
+  outcome: OrderStatus | null;
+  decline: CheckoutDecline | null;
+  /** The refusal the engine holds, routed to whoever claimed its code. */
+  error: CheckoutError | null;
+  placing: boolean;
+  slices: Record<string, unknown>;
+  /** A step the shopper pressed BACK into; it wins while it still applies. */
+  reopened: string | null;
+}
+
+/** The state, plus the only two ways to change it. */
+export interface EngineStore {
+  state: EngineState;
+  patch(next: Partial<EngineState>): void;
+  setSlice(stepId: string, value: unknown): void;
+}
+
+/** Everything at rest, with each step's slice rehydrated or freshly built. */
+function freshState(
+  steps: readonly AnyCheckoutStep[],
+  ctx: CheckoutContext,
+): EngineState {
+  return {
+    buyer: ctx.buyer,
+    buyerTouched: false,
+    // The "salvar meus dados" consent starts checked, exactly as the flat
+    // controller's does — the checkbox is the shopper's way to say otherwise.
+    saveProfile: true,
+    order: null,
+    outcome: null,
+    decline: null,
+    error: null,
+    placing: false,
+    slices: initialSlices(steps, ctx),
+    reopened: null,
+  };
+}
+
+/**
+ * The engine's store.
+ *
+ * `steps` and the initial `ctx` are read ONCE, in the lazy initializer: the
+ * slices a step declared are seeded from storage at mount, and re-seeding them
+ * on a later render would undo whatever the shopper has since done.
+ */
+export function useEngineStore(
+  steps: readonly AnyCheckoutStep[],
+  ctx: CheckoutContext,
+): EngineStore {
+  const [state, setState] = useState<EngineState>(() => freshState(steps, ctx));
+  const tenantSlug = ctx.tenantSlug;
+  const patch = useCallback((next: Partial<EngineState>) => {
+    setState((current) => ({ ...current, ...next }));
+  }, []);
+  const setSlice = useCallback(
+    (stepId: string, value: unknown) => {
+      const step = steps.find((entry) => entry.id === stepId);
+      if (step) writeSlice(step, tenantSlug, value);
+      setState((current) => ({ ...current, slices: { ...current.slices, [stepId]: value } }));
+    },
+    [steps, tenantSlug],
+  );
+  return useMemo(() => ({ state, patch, setSlice }), [state, patch, setSlice]);
+}
+
+/**
+ * The buyer the walk should show: the shopper's own edits once they have made
+ * any, and the host's saved defaults until then.
+ */
+export function effectiveBuyer(state: EngineState, defaults: BuyerInfo): BuyerInfo {
+  return state.buyerTouched ? state.buyer : defaults;
+}