@12-apps/payments-frontend 3.22.0 → 3.23.0

package/src/flows/pipeline/slices.ts

@@ -0,0 +1,110 @@
+/**
+ * WHERE A STEP'S OWN SCRAP OF STATE LIVES (FUT-1240).
+ *
+ * A step DECLARES its slice — the initial value, whether it survives a reload,
+ * and how to read one back — and the engine owns the storage. That split is
+ * what stops each step growing its own `sessionStorage` key with its own
+ * spelling and its own idea of who it belongs to, which is how three of the
+ * four hosted-order parks ended up unscoped.
+ *
+ * ## Scoped to the store, always
+ *
+ * The key is `payments.checkout.<slug>.<stepId>`. On a multi-tenant storefront
+ * every store shares one origin, so an unscoped key is one slot every store
+ * writes over: the shape that let store A's abandoned hand-off resume on store
+ * B's checkout. A host with no slug gets `-`, which is the single-tenant case
+ * and the only place there is nothing to confuse it with.
+ *
+ * ## Trust nothing that came back out
+ *
+ * Storage is the one input that did not come from this render. It is a string
+ * a shopper can edit, a half-written value a killed tab left behind, or an
+ * older bundle's shape. So a slice is rehydrated ONLY when the step declared a
+ * `parse` and that parser accepts what was there; everything else falls back
+ * to `initial(ctx)`. Same rule as `hosted-return.ts`'s `isCheckoutOrder`.
+ */
+import type { AnyCheckoutStep, CheckoutContext } from "./types";
+
+/** The one place the key is spelled. */
+export function sliceKey(tenantSlug: string | undefined, stepId: string): string {
+  return `payments.checkout.${tenantSlug ?? "-"}.${stepId}`;
+}
+
+/** The parked value, or `null` — never a throw, and never an unparsed one. */
+export function readSlice(
+  step: AnyCheckoutStep,
+  tenantSlug: string | undefined,
+): unknown {
+  const slice = step.slice;
+  if (!slice || slice.persist !== "session" || !slice.parse) return null;
+  let raw: string | null = null;
+  try {
+    raw = window.sessionStorage?.getItem(sliceKey(tenantSlug, step.id)) ?? null;
+  } catch {
+    // Storage disabled or unavailable — the same "nothing parked" as an empty
+    // slot. A checkout that cannot remember a step still works; one that
+    // throws on a private-mode browser does not.
+    return null;
+  }
+  if (raw === null) return null;
+  try {
+    return slice.parse(JSON.parse(raw) as unknown);
+  } catch {
+    return null;
+  }
+}
+
+/** Park a slice, or drop it when the step does not persist. */
+export function writeSlice(
+  step: AnyCheckoutStep,
+  tenantSlug: string | undefined,
+  value: unknown,
+): void {
+  if (step.slice?.persist !== "session") return;
+  try {
+    window.sessionStorage?.setItem(
+      sliceKey(tenantSlug, step.id),
+      JSON.stringify(value),
+    );
+  } catch {
+    // Storage full or disabled. The slice still lives in React for this visit;
+    // only its survival across a reload is lost, and refusing to advance the
+    // checkout over that would be the worse failure.
+  }
+}
+
+/** Drop every registered step's parked slice — the end of one checkout. */
+export function clearSlices(
+  steps: readonly AnyCheckoutStep[],
+  tenantSlug: string | undefined,
+): void {
+  for (const step of steps) {
+    if (step.slice?.persist !== "session") continue;
+    try {
+      window.sessionStorage?.removeItem(sliceKey(tenantSlug, step.id));
+    } catch {
+      // Nothing to clear on a browser that refuses storage.
+    }
+  }
+}
+
+/**
+ * Every step's slice at mount: what was parked when it can be trusted, and the
+ * step's own `initial(ctx)` when it cannot.
+ *
+ * `ctx` here is the context BEFORE any slice is known, which is why
+ * `CheckoutContext.slices` is empty on this pass — an `initial` that read its
+ * own slice would be asking what it is about to answer.
+ */
+export function initialSlices(
+  steps: readonly AnyCheckoutStep[],
+  ctx: CheckoutContext,
+): Record<string, unknown> {
+  const slices: Record<string, unknown> = {};
+  for (const step of steps) {
+    if (!step.slice) continue;
+    const parked = readSlice(step, ctx.tenantSlug);
+    slices[step.id] = parked === null ? step.slice.initial(ctx) : parked;
+  }
+  return slices;
+}

package/src/flows/pipeline/stable-plugins.ts

@@ -0,0 +1,72 @@
+/**
+ * THE DEV-MODE ASSERTION THAT KEEPS HOOK ORDER HONEST (FUT-1216 risk 1).
+ *
+ * Every registered step, gate and settlement method may declare a `useFacts()`,
+ * and the engine calls them in ARRAY ORDER on every render. React's hook
+ * identity is positional, so the order — and therefore the membership — of
+ * those arrays is part of the component's hook signature.
+ *
+ * A host that builds them inline (`steps={[scheduleStep, addressStep]}` in
+ * JSX, or `const GATES = gates.filter(...)` in a component body) hands the
+ * engine a NEW array every render. Today that usually still works, which is
+ * the danger: it works right up until a filter's answer changes and a
+ * `useFacts` disappears from the middle of the list, at which point React
+ * silently pairs the wrong state with the wrong plugin. There is no error, no
+ * warning, and the symptom is a checkout that reads another plugin's facts.
+ *
+ * So this refuses the shape rather than the symptom. In a development build a
+ * plugin array that is not identity-stable across renders THROWS, naming the
+ * array and the fix: hoist it to module scope, or memoise it. In production it
+ * does nothing at all — a live checkout must never be taken down by a wiring
+ * complaint, and by then the shape has been provable for the host's whole dev
+ * and test cycle.
+ */
+import { useRef } from "react";
+
+/** Whether this bundle is a development one. */
+function inDevelopment(): boolean {
+  // `process` is absent in a plain browser and replaced at build time by every
+  // bundler a host is likely to use; both readings are guarded so neither can
+  // throw inside a render.
+  try {
+    return typeof process !== "undefined" && process.env?.["NODE_ENV"] !== "production";
+  } catch {
+    return false;
+  }
+}
+
+/** What a host is told when it rebuilds an array per render. */
+function unstablePluginMessage(name: string): string {
+  return (
+    `createPaymentFlows: \`${name}\` must be the SAME array on every render. ` +
+    "Every registered plugin's `useFacts()` runs in array order, so React's hook " +
+    "order is a function of this array's membership — a fresh array per render " +
+    "will eventually pair one plugin's state with another's, silently. Hoist it " +
+    "to module scope (`const STEPS = [...]`) or memoise it. This check runs in " +
+    "development builds only."
+  );
+}
+
+/**
+ * Assert one plugin array is the same object it was last render.
+ *
+ * `undefined` is stable by definition — a host that registers nothing has
+ * nothing to keep still — and the FIRST render has nothing to compare with.
+ */
+export function useStablePluginArray(
+  name: string,
+  array: readonly unknown[] | undefined,
+): void {
+  const seen = useRef<readonly unknown[] | undefined>(array);
+  if (array === undefined || seen.current === undefined) return;
+  if (seen.current === array) return;
+  // THROWN BEFORE THE REF MOVES, and that ordering is the whole assertion.
+  // React answers a failed concurrent render by retrying the root
+  // synchronously; a check that had already recorded the new array would pass
+  // on that retry, React would report itself recovered, and the misconfigured
+  // host would see nothing at all. Refusing again is what puts the complaint
+  // in front of an error boundary — and what keeps it there until the array is
+  // actually hoisted.
+  if (inDevelopment()) throw new Error(unstablePluginMessage(name));
+  seen.current = array;
+}

package/src/flows/pipeline/steps/buyer-steps.tsx

@@ -0,0 +1,297 @@
+/**
+ * THE TWO STEPS BEFORE ANY MONEY MOVES (FUT-1240): who is paying, and how.
+ *
+ * Both are thin wrappers over screens this package already ships — exactly as
+ * `flows/screens-*.tsx` wrap the components today. What is new is that their
+ * PLACE in the walk is declared rather than switched on, and that the
+ * buyer-details step's "was it skipped, and has it been opened since" lives in
+ * a slice the engine parks instead of in a `useState` a reload forgets.
+ */
+import { Box } from "@mui/material";
+import type { JSX } from "react";
+
+import { PaymentErrorPanel } from "../../../components/checkout/payment-error-panel";
+import { useCheckoutComponents } from "../../../components/checkout/ui";
+import type { PaymentMethod } from "../../../components/checkout/types";
+import { usePipelineActions } from "../actions";
+import { isPackageMethod } from "../methods";
+import type {
+  AnySettlementMethod,
+  CheckoutContext,
+  CheckoutStep,
+  CheckoutStepRender,
+} from "../types";
+
+export const DADOS_STEP_ID = "dados";
+export const METHOD_STEP_ID = "method";
+
+/**
+ * The server's own code for "the chain asked for a field this buyer has not
+ * given" — and the code the local gate raises, so a refusal the browser can
+ * see and one the server sends land on the same step, worded the same way.
+ */
+export const BUYER_FIELD_CODE = "MISSING_BUYER_FIELD";
+
+/** Whether the shopper has opened the buyer-details step, and finished it. */
+interface DadosSlice {
+  /**
+   * A shopper whose CPF is on file never sees this step — until they press
+   * "alterar", after which it IS part of their flow and back returns to it.
+   * That is the whole of `useCheckoutNav`'s `dadosOpened`.
+   */
+  opened: boolean;
+  done: boolean;
+}
+
+const DADOS_INITIAL: DadosSlice = Object.freeze({ opened: false, done: false });
+
+/** Trust nothing out of storage: two booleans, or nothing at all. */
+export function parseDadosSlice(raw: unknown): DadosSlice | null {
+  if (typeof raw !== "object" || raw === null) return null;
+  const candidate = raw as Partial<DadosSlice>;
+  if (typeof candidate.opened !== "boolean") return null;
+  if (typeof candidate.done !== "boolean") return null;
+  return { opened: candidate.opened, done: candidate.done };
+}
+
+/** The buyer-details slice as the whole walk reads it. */
+export function dadosSliceOf(ctx: CheckoutContext): DadosSlice {
+  return parseDadosSlice(ctx.slices[DADOS_STEP_ID]) ?? DADOS_INITIAL;
+}
+
+function DadosView({ ctx, error }: CheckoutStepRender<DadosSlice>): JSX.Element {
+  const actions = usePipelineActions();
+  const BuyerDetails = actions.screens.BuyerDetails;
+  const field = error?.field ?? null;
+  return (
+    <BuyerDetails
+      value={ctx.buyer}
+      onChange={actions.setBuyer}
+      method={isPackageMethod(ctx.method) ? ctx.method : null}
+      onContinue={actions.continueFromDados}
+      error={field && error ? { field, message: error.message } : null}
+    />
+  );
+}
+
+/**
+ * WHO IS PAYING.
+ *
+ * `applies` is the FUT-465 skip, stated as a fact rather than as an initial
+ * step: a shopper with a CPF on file has nothing left to answer here, so the
+ * step is not part of their walk — which is also why back off the next step
+ * takes them to the catalog rather than to a form they never saw.
+ */
+export const dadosStep: CheckoutStep<DadosSlice> = {
+  id: DADOS_STEP_ID,
+  phase: "details",
+  order: 0,
+  label: "dados",
+  applies(ctx) {
+    return !ctx.taxIdOnFile || dadosSliceOf(ctx).opened;
+  },
+  complete(_ctx, _facts, slice) {
+    return slice.done;
+  },
+  slice: {
+    initial: () => DADOS_INITIAL,
+    persist: "session",
+    parse: parseDadosSlice,
+  },
+  // The two refusals that are ABOUT a field on this form. Anything else the
+  // create can answer is not something retyping a name will fix.
+  answersCodes: [BUYER_FIELD_CODE, "EMAIL_EQUALS_MERCHANT"],
+  contribute(ctx) {
+    return { buyer: ctx.buyer };
+  },
+  render(props) {
+    return <DadosView {...props} />;
+  },
+};
+
+/** Which settlement method the shopper picked. */
+interface MethodSlice {
+  chosen: string | null;
+}
+
+const METHOD_INITIAL: MethodSlice = Object.freeze({ chosen: null });
+
+/** A method id is a string or nothing — never an object a shopper edited in. */
+function parseMethodSlice(raw: unknown): MethodSlice | null {
+  if (typeof raw !== "object" || raw === null) return null;
+  const chosen = (raw as Partial<MethodSlice>).chosen;
+  if (chosen === null) return { chosen: null };
+  return typeof chosen === "string" ? { chosen } : null;
+}
+
+/** The chosen method, as the engine reads it back out of the slices. */
+export function methodSliceOf(slices: Readonly<Record<string, unknown>>): MethodSlice {
+  return parseMethodSlice(slices[METHOD_STEP_ID]) ?? METHOD_INITIAL;
+}
+
+/** One registered method as a tile, for the methods the package cannot draw. */
+function MethodTiles({ ctx }: { ctx: CheckoutContext }): JSX.Element {
+  const { Button, Text } = useCheckoutComponents();
+  const actions = usePipelineActions();
+  return (
+    <Box role="radiogroup" data-testid="checkout-method" sx={{ display: "flex", gap: 1 }}>
+      {actions.offered.map((method) => {
+        const tile = method.tile(actions.copy);
+        return (
+          <Box key={method.id} sx={{ flex: 1, minWidth: 0 }}>
+            <Button
+              variant={ctx.method === method.id ? "solid" : "outline"}
+              color="primary"
+              size="md"
+              fullWidth
+              onClick={() => actions.choose(method.id)}
+              dataTestId={`checkout-method-${method.id}`}
+            >
+              {tile.label}
+            </Button>
+            {tile.hint === undefined ? null : (
+              <Text variant="caption" size="xs" color="secondary" as="p">
+                {tile.hint}
+              </Text>
+            )}
+          </Box>
+        );
+      })}
+    </Box>
+  );
+}
+
+/**
+ * HOW they are paying.
+ *
+ * The package's own picker renders whenever the offer is the package's own two
+ * methods — with its disabled-card caption and its sole-method preselect
+ * intact, because those are decisions about PIX and CARD specifically. A host
+ * that registers a method of its own gets the generic tiles, which is the only
+ * shape that can draw a method this package has never heard of.
+ */
+function MethodView({ ctx, error }: CheckoutStepRender<MethodSlice>): JSX.Element {
+  const actions = usePipelineActions();
+  const MethodChoice = actions.screens.MethodChoice;
+  const packageOnly = actions.offered.every((method) => isPackageMethod(method.id));
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 2 }}>
+      <PayerBlock ctx={ctx} />
+      {packageOnly ? (
+        <MethodChoice
+          value={isPackageMethod(ctx.method) ? ctx.method : null}
+          onChange={(method: PaymentMethod) => actions.choose(method)}
+        />
+      ) : (
+        <MethodTiles ctx={ctx} />
+      )}
+      <MethodRefusal error={error} />
+    </Box>
+  );
+}
+
+/**
+ * A REFUSAL THE PICKER HAS TO DRAW, because it is where the shopper is.
+ *
+ * The routing hands a step every refusal nobody more specific claimed — the
+ * unclaimed ones, and the ones whose gate is passing and therefore drawing
+ * nothing (`refusal-routing.ts`). Raising the payable fails from HERE, so this
+ * is the step those land on, and a picker that ignored the prop would leave the
+ * shopper tapping a tile that answers nothing.
+ *
+ * `PaymentErrorPanel` rather than a bare Alert: it is the same panel the flat
+ * flow's Pagamento step draws, and it carries the rule that matters most — an
+ * UNRESOLVED charge gets a warning and NO retry, because some provider may be
+ * holding the buyer's money and a retry mints a second order.
+ *
+ * `emailFlagged` is FALSE here and cannot be otherwise: the one refusal that
+ * offer answers, `EMAIL_EQUALS_MERCHANT`, is claimed by the buyer-details step
+ * (`dadosStep.answersCodes`), so the routing sends that shopper to the form
+ * holding the e-mail field instead of offering a second copy of it under a
+ * picker. `onUseEmail` is consequently unreachable, and is the buyer-details
+ * door rather than a no-op so that it stays true if the claim ever moves.
+ */
+function MethodRefusal({ error }: { error: CheckoutStepRender<MethodSlice>["error"] }): JSX.Element | null {
+  const actions = usePipelineActions();
+  const openDados = actions.editBuyer;
+  if (!error) return null;
+  return (
+    <PaymentErrorPanel
+      message={error.message}
+      emailFlagged={false}
+      code={error.code}
+      onUseEmail={() => openDados?.()}
+      onRetry={actions.place}
+    />
+  );
+}
+
+/**
+ * WHO IS BEING CHARGED, and the door back to changing it.
+ *
+ * Drawn only for a shopper whose buyer-details step was SKIPPED — the same
+ * rule the flat flow applies, and for the same reason: a shopper who filled
+ * the form themselves is looking at what they just typed, and a summary of it
+ * is a second copy of the same screen. Its presence is `editBuyer`'s presence,
+ * which the engine derives once (`deriveNav`) rather than each caller guessing.
+ */
+function PayerBlock({ ctx }: { ctx: CheckoutContext }): JSX.Element | null {
+  const actions = usePipelineActions();
+  const PayerSummary = actions.screens.PayerSummary;
+  if (!actions.editBuyer) return null;
+  return <PayerSummary buyer={ctx.buyer} onEdit={actions.editBuyer} />;
+}
+
+/** A chosen method whose descriptor wants a review has not finished this step. */
+function methodSettled(ctx: CheckoutContext, methods: readonly AnySettlementMethod[]): boolean {
+  if (ctx.method === null) return false;
+  const descriptor = methods.find((entry) => entry.id === ctx.method);
+  if (descriptor?.Review && ctx.order === null) return false;
+  return true;
+}
+
+/** Built over the MERGED descriptor list, which is a factory-scope constant. */
+export function buildMethodStep(
+  methods: readonly AnySettlementMethod[],
+): CheckoutStep<MethodSlice> {
+  return {
+    id: METHOD_STEP_ID,
+    phase: "before-pay",
+    order: 0,
+    label: "payment",
+    applies(ctx) {
+      return ctx.outcome === null;
+    },
+    complete(ctx) {
+      return methodSettled(ctx, methods);
+    },
+    slice: {
+      initial: () => METHOD_INITIAL,
+      persist: "session",
+      parse: parseMethodSlice,
+    },
+    render(props) {
+      return <MethodStepBody {...props} methods={methods} />;
+    },
+  };
+}
+
+/** The picker, or the chosen descriptor's own review of what is about to happen. */
+function MethodStepBody(
+  props: CheckoutStepRender<MethodSlice> & { methods: readonly AnySettlementMethod[] },
+): JSX.Element {
+  const actions = usePipelineActions();
+  const descriptor = props.methods.find((entry) => entry.id === props.ctx.method);
+  const Review = descriptor?.Review;
+  if (Review && props.ctx.order === null) {
+    return (
+      <Review
+        ctx={props.ctx}
+        place={actions.place}
+        placing={actions.placing}
+        error={props.error}
+      />
+    );
+  }
+  return <MethodView {...props} />;
+}

package/src/flows/pipeline/steps/index.ts

@@ -0,0 +1,54 @@
+/**
+ * The SEVEN screens this package already shipped, wrapped as steps (FUT-1240).
+ *
+ * Buyer details, the method picker, the Pix pane, the card pane, the hand-off
+ * interstitial, the return from one, and the confirmation. Each wrapper is
+ * thin by design: the behaviour stays in `components/checkout/*` and in the
+ * screens `flows/screens-*.tsx` already binds, and what is added here is only
+ * WHERE each one sits in a walk that is derived rather than switched on.
+ *
+ * The RETURN step is the one that is not a bare wrapper, and the reason is
+ * worth stating: `screens.HostedReturn` owns its own read of the parked entry,
+ * which is right for a host mounting it at a dedicated return route and wrong
+ * inside a checkout that already knows the slug and the basket. So the step
+ * runs `useHostedResume` — the package's own FUT-1213 rule, deferral and
+ * server ASK included — and renders the confirmation while it waits.
+ */
+import type { FlowsRuntime } from "../../runtime";
+import type { AnyCheckoutStep, AnySettlementMethod } from "../types";
+
+import { buildMethodStep, dadosStep } from "./buyer-steps";
+import { buildResumeStep, cardStep, handoffStep, pixStep } from "./pay-steps";
+import { statusStep } from "./status-step";
+
+export {
+  BUYER_FIELD_CODE,
+  DADOS_STEP_ID,
+  METHOD_STEP_ID,
+  dadosSliceOf,
+  methodSliceOf,
+} from "./buyer-steps";
+export { HANDOFF_STEP_ID, RESUME_STEP_ID } from "./pay-steps";
+export { STATUS_STEP_ID } from "./status-step";
+
+/**
+ * The package's own steps, built once per factory.
+ *
+ * The returned array is a factory-scope constant — never rebuilt — because
+ * every registered plugin's `useFacts()` runs in array order and React's hook
+ * identity is positional. See `stable-plugins.ts`.
+ */
+export function packageSteps(
+  runtime: FlowsRuntime,
+  methods: readonly AnySettlementMethod[],
+): readonly AnyCheckoutStep[] {
+  return Object.freeze([
+    buildResumeStep(runtime),
+    dadosStep,
+    buildMethodStep(methods),
+    pixStep,
+    cardStep,
+    handoffStep,
+    statusStep,
+  ]);
+}