@12-apps/payments-frontend 3.23.1 → 3.24.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.23.1",
+  "version": "3.24.1",
   "type": "module",
   "sideEffects": false,
   "description": "Browser half of the vendor-agnostic payments platform: plug-and-play MUI components for the per-provider settings page (credential form from each provider's schema, masked hints, verify/enable) and the checkout page (PIX QR + polling, card tokenization, hosted-checkout redirect), plus the headless hooks and fetch clients they build on. Talks only to the host's payments HTTP surface — never to a provider directly. Microfrontend-ready: no app coupling, host injects theme and auth.",

package/src/components/checkout/checkout-actions.ts

@@ -3,9 +3,7 @@ import { useCallback, useEffect, useState, type Dispatch, type SetStateAction }
 import { buyerGateError } from "./buyer-gate";
 import type { ConfirmationWait } from "./confirmation-wait";
 import type { CheckoutDecline } from "./decline";
-import { forgetHostedOrder, rememberHostedOrder } from "./hosted-return";
-import { parkedBasket, type CheckoutBasketIdentity } from "./basket";
-import type { CheckoutNavigate } from "./navigate-context";
+import { forgetHostedOrder } from "./hosted-return";
 import type { CheckoutScreensCopy } from "./screens-copy";
 import type {
   BuyerContact,
@@ -13,8 +11,6 @@ import type {
   BuyerInfo,
   CheckoutCustomerField,
   CheckoutOrder,
-  CreateOrderRequest,
-  CreateOrderResult,
   OrderStatus,
   PaymentMethod,
 } from "./types";
@@ -282,106 +278,3 @@ export function useRetryAction(input: {
     clearError, decline, order, setDecline, setFinalStatus, setFreshInstrument, setOrder, setStep,
   ]);
 }
-
-/**
- * Hand the buyer to a redirect provider's own page, if that is where this
- * charge settles (FUT-556).
- *
- * Called BEFORE the order is stored: storing it first would render the PIX or
- * card step for a provider that returned neither, which is the dead end this
- * fixes.
- *
- * A full navigation rather than the host's router, because the destination is
- * another origin. The return trip comes back to this same checkout route
- * carrying `transaction_nsu` + `slug`, which the status poll already reads.
- *
- * @returns true when the buyer is on their way and the caller must stop.
- */
-function handOverToProvider(
-  order: CheckoutOrder,
-  navigate: CheckoutNavigate,
-  tenantSlug?: string,
-  basket?: CheckoutBasketIdentity,
-): boolean {
-  if (!order.hostedCheckoutUrl) return false;
-  // PARK FIRST, navigate second. The order is the only thing the return trip
-  // has to rehydrate from, and the navigation may tear this SPA down before
-  // any later write lands.
-  //
-  // The STORE goes with it: one tab holds one slot, and on a multi-tenant
-  // storefront every store shares an origin. Without the slug, abandoning this
-  // hand-off and opening another store's checkout resumed THIS order there.
-  //
-  // So does the BASKET (FUT-1213): a hand-off nobody completed must not resume
-  // itself over the shopper's next basket, and the only way to tell the two
-  // apart later is to record which basket this one was raised from.
-  rememberHostedOrder(order, {
-    tenantSlug,
-    basket: parkedBasket(basket),
-    handoff: true,
-  });
-  navigate(order.hostedCheckoutUrl);
-  return true;
-}
-
-/**
- * Raise the order for a chosen method, and decide what happens to it.
- *
- * Three outcomes, in order: a refusal the step renders, a HAND-OFF that leaves
- * this page for the provider's own, and an order raised here.
- */
-export function useStartPayment(input: {
-  buyer: BuyerInfo;
-  saveProfile: boolean;
-  createOrder: (request: CreateOrderRequest) => Promise<CreateOrderResult>;
-  navigate: CheckoutNavigate;
-  tenantSlug: string | undefined;
-  basket: CheckoutBasketIdentity | undefined;
-  failure: { clear: () => void; fail: (next: { message: string; field?: BuyerField | null; code?: string }) => void };
-  setCreating: Dispatch<SetStateAction<boolean>>;
-  setDecline: Dispatch<SetStateAction<CheckoutDecline | null>>;
-  setOrder: Dispatch<SetStateAction<CheckoutOrder | null>>;
-  setFinalStatus: Dispatch<SetStateAction<OrderStatus | null>>;
-}): (chosen: PaymentMethod, override?: BuyerInfo) => Promise<void> {
-  const { buyer, saveProfile, createOrder, navigate, tenantSlug, basket, failure } = input;
-  const { setCreating, setDecline, setOrder, setFinalStatus } = input;
-  return useCallback(
-    async (chosen: PaymentMethod, override?: BuyerInfo) => {
-      failure.clear();
-      setDecline(null);
-      // THE CHARGE BEING REPLACED IS DROPPED FIRST (FUT-1170), before the raise
-      // rather than after it. Raising a payment means whatever was on screen is
-      // no longer the one being paid, and a provider round trip is long enough
-      // for the difference to matter: "Gerar novo código" left the expired
-      // charge mounted, so its own view polled it, got the terminal EXPIRED it
-      // was always going to get, and bounced the flow to the confirmation
-      // screen — where the new charge then landed with nothing polling it.
-      //
-      // A no-op on every other caller (the auto-raise, the alternate e-mail and
-      // the retry all run with no order held), which is the point: the clear
-      // belongs to what raising a payment MEANS, not to the one path that
-      // noticed.
-      setOrder(null);
-      setFinalStatus(null);
-      setCreating(true);
-      const result = await createOrder({ method: chosen, buyer: override ?? buyer, saveProfile });
-      setCreating(false);
-      if (!result.ok) {
-        failure.fail(result.error);
-        return;
-      }
-      if (handOverToProvider(result.data, navigate, tenantSlug, basket)) return;
-      // PARKED EVEN THOUGH NOBODY IS LEAVING (FUT-1140). A low-memory phone
-      // discards this tab while the shopper is in their bank app, and the SPA
-      // that comes back has never heard of the order it raised — so the buyer
-      // meets an empty cart and a retry button instead of the confirmation for
-      // the payment they just made.
-      rememberHostedOrder(result.data, { tenantSlug, basket: parkedBasket(basket) });
-      setOrder(result.data);
-    },
-    [
-      buyer, saveProfile, createOrder, failure, navigate, tenantSlug, basket,
-      setCreating, setDecline, setOrder, setFinalStatus,
-    ],
-  );
-}

package/src/components/checkout/checkout-flow.tsx

@@ -7,6 +7,7 @@ import { EmptyCart, PaymentStep } from "./checkout-steps";
 import { DadosStep } from "./dados-step";
 import { ArrowBackIcon } from "./icons";
 import { PaymentStatus } from "./payment-status";
+import type { BackActionEmphasis } from "./payment-status-parts";
 import type { BuyerInfo, CheckoutProviderConfig, SettlementCheckout } from "./types";
 import { CheckoutCopyProvider } from "./copy-context";
 import { OneClickProvider, useOneClick } from "./one-click";
@@ -94,6 +95,10 @@ export interface CheckoutFlowProps extends CheckoutHostPorts {
   validateApplePayMerchant?: (validationURL: string) => Promise<unknown>;
   /** Host content shown on the paid confirmation (the storefront's install invite). */
   confirmationExtra?: ReactNode;
+  /** Host content shown AFTER the confirmation's actions — `PaymentStatusProps.paidFooter`. */
+  confirmationFooter?: ReactNode;
+  /** Whether the way out leads the paid screen — see {@link BackActionEmphasis}. */
+  backActionEmphasis?: BackActionEmphasis;
   /** Design-system slots; unfilled slots render the raw-MUI defaults. */
   components?: Partial<CheckoutComponents>;
 }
@@ -180,12 +185,16 @@ function StatusStep({
   settlement,
   cart,
   confirmationExtra,
+  confirmationFooter,
+  backActionEmphasis,
 }: {
   copy: CheckoutViewCopy;
   c: ReturnType<typeof useCheckoutController>;
   settlement: SettlementCheckout | null | undefined;
   cart: CheckoutCartView;
   confirmationExtra: ReactNode;
+  confirmationFooter: ReactNode;
+  backActionEmphasis: BackActionEmphasis | undefined;
 }): JSX.Element {
   return (
     <PaymentStatus
@@ -197,6 +206,8 @@ function StatusStep({
       onRegenerate={() => { c.setStep("payment"); void c.startPayment("PIX"); }}
       onBackToMenu={c.goToMenu}
       paidExtra={confirmationExtra}
+      paidFooter={confirmationFooter}
+      backActionEmphasis={backActionEmphasis}
       awaitingTimedOut={c.awaitingTimedOut}
       // How the wait behind this screen is going, and the way out of it
       // (FUT-1144). It is the resumed leg's wait for a checkout that came back
@@ -297,7 +308,7 @@ function PagamentoStep({
 }
 
 function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Element {
-  const { copy, cart, defaultBuyer, settlement, taxIdOnFile = false, providerConfig, tenantSlug, confirmationExtra, validateApplePayMerchant, oneClick = false, ...ports } = props;
+  const { copy, cart, defaultBuyer, settlement, taxIdOnFile = false, providerConfig, tenantSlug, confirmationExtra, confirmationFooter, backActionEmphasis, validateApplePayMerchant, oneClick = false, ...ports } = props;
   // Resolved for NO method on purpose (FUT-595): the Dados step opens before
   // the picker, and the form is filled once — so it asks for the union of what
   // any chain member may need rather than re-opening after the choice. A chain
@@ -354,7 +365,7 @@ function CheckoutFlowBody(props: Omit<CheckoutFlowProps, "components">): JSX.Ele
       ) : null}
 
       {c.step === "status" ? (
-        <StatusStep copy={copy} c={c} settlement={settlement} cart={cart} confirmationExtra={confirmationExtra} />
+        <StatusStep copy={copy} c={c} settlement={settlement} cart={cart} confirmationExtra={confirmationExtra} confirmationFooter={confirmationFooter} backActionEmphasis={backActionEmphasis} />
       ) : null}
     </Box>
   );

package/src/components/checkout/payment-status-parts.tsx

@@ -234,6 +234,38 @@ function retryable(decline: CheckoutDecline | null): boolean {
   return decline?.retriable !== false;
 }
 
+/**
+ * How much of the eye the way out asks for on a PAID confirmation.
+ *
+ * `"primary"` is the default and the historical look: back-to-menu is the only
+ * control a settled screen carries, so it wears the solid fill. A host that
+ * renders an action of its OWN in {@link PaymentStatusProps.paidExtra} — a
+ * route to the order it just raised, say — has two controls on one screen, and
+ * only one of them may lead. `"secondary"` is how such a host says which.
+ *
+ * A prop rather than a guess, because the package cannot make it: whether the
+ * buyer's next move is "look at the pedido" or "buy something else" is a fact
+ * about the way this shop serves people, and nothing in a payment knows it.
+ * Every other status is unaffected — an unsettled screen already paints this
+ * button as the quiet way out, and the retry beside it is the lead.
+ */
+export type BackActionEmphasis = "primary" | "secondary";
+
+/**
+ * The back-to-menu button's look, from the outcome and the host's emphasis.
+ *
+ * Its own function so the two attributes cannot disagree: they moved together
+ * as a pair of inline ternaries, and a third condition would have made that
+ * four places to keep in step.
+ */
+function backLook(
+  status: OrderStatus,
+  emphasis: BackActionEmphasis,
+): { variant: "solid" | "outline"; color: "primary" | "neutral" } {
+  const leads = status === "PAID" && emphasis === "primary";
+  return leads ? { variant: "solid", color: "primary" } : { variant: "outline", color: "neutral" };
+}
+
 /** The next-action row: retry / regenerate / check-again, always back-to-menu. */
 export function StatusActions({
   copy,
@@ -244,6 +276,7 @@ export function StatusActions({
   onCheckAgain,
   onNotPaid,
   onBackToMenu,
+  backActionEmphasis = "primary",
 }: {
   copy: PaymentStatusCopy;
   status: OrderStatus;
@@ -259,8 +292,11 @@ export function StatusActions({
   /** The buyer's "I did not pay" (FUT-1146) — present only while it applies. */
   onNotPaid?: () => void;
   onBackToMenu: () => void;
+  /** Whether back-to-menu leads a PAID screen. See {@link BackActionEmphasis}. */
+  backActionEmphasis?: BackActionEmphasis;
 }): JSX.Element {
   const { Button } = useCheckoutComponents();
+  const back = backLook(status, backActionEmphasis);
   return (
     <Box sx={{ display: "flex", flexDirection: "column", gap: 1 }}>
       {onCheckAgain ? (
@@ -298,8 +334,8 @@ export function StatusActions({
       <Button
         // Full width and last, so the thumb lands on the same place in every
         // outcome instead of hunting a button that moves with the state.
-        variant={status === "PAID" ? "solid" : "outline"}
-        color={status === "PAID" ? "primary" : "neutral"}
+        variant={back.variant}
+        color={back.color}
         size="lg"
         onClick={onBackToMenu}
         dataTestId="payment-back-to-menu"

package/src/components/checkout/payment-status.tsx

@@ -2,7 +2,13 @@ import { Box } from "@mui/material";
 import type { JSX, ReactNode } from "react";
 
 import type { CheckoutDecline } from "./decline";
-import { OutcomeHero, PaidFacts, StatusActions, type WaitState } from "./payment-status-parts";
+import {
+  OutcomeHero,
+  PaidFacts,
+  StatusActions,
+  type BackActionEmphasis,
+  type WaitState,
+} from "./payment-status-parts";
 import type { OrderStatus } from "./types";
 import { useCheckoutComponents } from "./ui";
 import type { PaymentStatusCopy } from "./view-copy";
@@ -50,6 +56,23 @@ interface PaymentStatusProps {
    * is the difference between an offer and an interruption.
    */
   paidExtra?: ReactNode;
+  /**
+   * Host content rendered AFTER the action row, and ONLY on PAID.
+   *
+   * The other half of {@link paidExtra}, and the difference between them is the
+   * actions. What a buyer has to DO next belongs beside the way out, in one
+   * block: a panel dropped between two controls splits the only decision on the
+   * screen in half. What is merely OFFERED — an install invite, an ask to turn
+   * on alerts — belongs after that block, because it is about everything that
+   * happens once this screen is closed and must not come between a shopper and
+   * the order they just paid for.
+   */
+  paidFooter?: ReactNode;
+  /**
+   * Whether back-to-menu leads a PAID screen (default) or stands down for an
+   * action the host renders in {@link paidExtra}. See {@link BackActionEmphasis}.
+   */
+  backActionEmphasis?: BackActionEmphasis;
   /**
    * The wait has been given up on. Only meaningful while AWAITING_PAYMENT;
    * every other status has already resolved, so a stale flag cannot change what
@@ -180,7 +203,10 @@ export function PaymentStatus(props: PaymentStatusProps): JSX.Element {
         onCheckAgain={view.checkAgain}
         onNotPaid={view.notPaid}
         onBackToMenu={onBackToMenu}
+        backActionEmphasis={props.backActionEmphasis}
       />
+
+      {view.paid ? props.paidFooter : null}
     </Box>
   );
 }

package/src/components/checkout/start-payment.ts

@@ -0,0 +1,151 @@
+import { useCallback, type Dispatch, type SetStateAction } from "react";
+
+import { parkedBasket, type CheckoutBasketIdentity } from "./basket";
+import type { Step } from "./checkout-actions";
+import type { CheckoutDecline } from "./decline";
+import { rememberHostedOrder } from "./hosted-return";
+import type { CheckoutNavigate } from "./navigate-context";
+import type {
+  BuyerField,
+  BuyerInfo,
+  CheckoutOrder,
+  CreateOrderRequest,
+  CreateOrderResult,
+  OrderStatus,
+  PaymentMethod,
+} from "./types";
+
+/**
+ * RAISING the order, and what becomes of it.
+ *
+ * Split out of `./checkout-actions.ts` when that file reached its 400-line gate
+ * — the same seam it was itself split along. What is here is the one moment the
+ * flow asks the host for an order and then has to decide, from the answer
+ * alone, which of four things is true: it was refused, it is already finished,
+ * it is payable somewhere else, or it is payable here.
+ */
+
+/**
+ * Hand the buyer to a redirect provider's own page, if that is where this
+ * charge settles (FUT-556).
+ *
+ * Called BEFORE the order is stored: storing it first would render the PIX or
+ * card step for a provider that returned neither, which is the dead end this
+ * fixes.
+ *
+ * A full navigation rather than the host's router, because the destination is
+ * another origin. The return trip comes back to this same checkout route
+ * carrying `transaction_nsu` + `slug`, which the status poll already reads.
+ *
+ * @returns true when the buyer is on their way and the caller must stop.
+ */
+function handOverToProvider(
+  order: CheckoutOrder,
+  navigate: CheckoutNavigate,
+  tenantSlug?: string,
+  basket?: CheckoutBasketIdentity,
+): boolean {
+  if (!order.hostedCheckoutUrl) return false;
+  // PARK FIRST, navigate second. The order is the only thing the return trip
+  // has to rehydrate from, and the navigation may tear this SPA down before
+  // any later write lands.
+  //
+  // The STORE goes with it: one tab holds one slot, and on a multi-tenant
+  // storefront every store shares an origin. Without the slug, abandoning this
+  // hand-off and opening another store's checkout resumed THIS order there.
+  //
+  // So does the BASKET (FUT-1213): a hand-off nobody completed must not resume
+  // itself over the shopper's next basket, and the only way to tell the two
+  // apart later is to record which basket this one was raised from.
+  rememberHostedOrder(order, {
+    tenantSlug,
+    basket: parkedBasket(basket),
+    handoff: true,
+  });
+  navigate(order.hostedCheckoutUrl);
+  return true;
+}
+
+/**
+ * Raise the order for a chosen method, and decide what happens to it.
+ *
+ * FOUR outcomes, in order: a refusal the step renders, an order that came back
+ * ALREADY RESOLVED, a HAND-OFF to the provider's own page, and an order raised
+ * here to be paid on this one.
+ *
+ * The resolved case is first because a raise does not always leave something to
+ * pay: a host whose buyer spends a stored balance settles a fully covered
+ * pedido server-side and answers PAID with no payable at all. That used to fall
+ * through and merely `setOrder`, leaving the flow on Pagamento holding a paid
+ * pedido — invisible on the PIX/card screen, which polls and resolves itself,
+ * and a dead end on the hand-off screen, which polls nothing and so offered a
+ * provider a charge that no longer existed. Reading `status` rather than the
+ * absence of a payable is what tells that apart from a failed raise.
+ */
+export function useStartPayment(input: {
+  buyer: BuyerInfo;
+  saveProfile: boolean;
+  createOrder: (request: CreateOrderRequest) => Promise<CreateOrderResult>;
+  navigate: CheckoutNavigate;
+  tenantSlug: string | undefined;
+  basket: CheckoutBasketIdentity | undefined;
+  failure: { clear: () => void; fail: (next: { message: string; field?: BuyerField | null; code?: string }) => void };
+  setCreating: Dispatch<SetStateAction<boolean>>;
+  setDecline: Dispatch<SetStateAction<CheckoutDecline | null>>;
+  setOrder: Dispatch<SetStateAction<CheckoutOrder | null>>;
+  setFinalStatus: Dispatch<SetStateAction<OrderStatus | null>>;
+  /** Moves the flow to Confirmação for an order that needs no payment. */
+  setStep: Dispatch<SetStateAction<Step>>;
+}): (chosen: PaymentMethod, override?: BuyerInfo) => Promise<void> {
+  const { buyer, saveProfile, createOrder, navigate, tenantSlug, basket, failure } = input;
+  const { setCreating, setDecline, setOrder, setFinalStatus, setStep } = input;
+  return useCallback(
+    async (chosen: PaymentMethod, override?: BuyerInfo) => {
+      failure.clear();
+      setDecline(null);
+      // THE CHARGE BEING REPLACED IS DROPPED FIRST (FUT-1170), before the raise
+      // rather than after it. Raising a payment means whatever was on screen is
+      // no longer the one being paid, and a provider round trip is long enough
+      // for the difference to matter: "Gerar novo código" left the expired
+      // charge mounted, so its own view polled it, got the terminal EXPIRED it
+      // was always going to get, and bounced the flow to the confirmation
+      // screen — where the new charge then landed with nothing polling it.
+      //
+      // A no-op on every other caller (the auto-raise, the alternate e-mail and
+      // the retry all run with no order held), which is the point: the clear
+      // belongs to what raising a payment MEANS, not to the one path that
+      // noticed.
+      setOrder(null);
+      setFinalStatus(null);
+      setCreating(true);
+      const result = await createOrder({ method: chosen, buyer: override ?? buyer, saveProfile });
+      setCreating(false);
+      if (!result.ok) {
+        failure.fail(result.error);
+        return;
+      }
+      // NOTHING LEFT TO PAY — see the docblock. Parked first for the same
+      // reason every other raised order is: the confirmation this is about to
+      // show has to survive a tab the phone discards on the way to it.
+      if (result.data.status !== "AWAITING_PAYMENT") {
+        rememberHostedOrder(result.data, { tenantSlug, basket: parkedBasket(basket) });
+        setOrder(result.data);
+        setFinalStatus(result.data.status);
+        setStep("status");
+        return;
+      }
+      if (handOverToProvider(result.data, navigate, tenantSlug, basket)) return;
+      // PARKED EVEN THOUGH NOBODY IS LEAVING (FUT-1140). A low-memory phone
+      // discards this tab while the shopper is in their bank app, and the SPA
+      // that comes back has never heard of the order it raised — so the buyer
+      // meets an empty cart and a retry button instead of the confirmation for
+      // the payment they just made.
+      rememberHostedOrder(result.data, { tenantSlug, basket: parkedBasket(basket) });
+      setOrder(result.data);
+    },
+    [
+      buyer, saveProfile, createOrder, failure, navigate, tenantSlug, basket,
+      setCreating, setDecline, setOrder, setFinalStatus, setStep,
+    ],
+  );
+}

package/src/components/checkout/use-checkout-controller.ts

@@ -9,9 +9,9 @@ import {
   useResumedCheckout,
   useRetryAction,
   useSettledPort,
-  useStartPayment,
   type Step,
 } from "./checkout-actions";
+import { useStartPayment } from "./start-payment";
 import { useConfirmationWait } from "./confirmation-wait";
 import { useCheckoutCopy } from "./copy-context";
 
@@ -139,7 +139,7 @@ export function useCheckoutController(
   });
   const startPayment = useStartPayment({
     buyer, saveProfile, createOrder, navigate, tenantSlug, basket, failure,
-    setCreating, setDecline, setOrder, setFinalStatus,
+    setCreating, setDecline, setOrder, setFinalStatus, setStep,
   });
   const { payWithEmail, handleResolved } = useResolutionActions({
     buyer, method, startPayment, setBuyerState, setDecline, setFinalStatus, setStep,

package/src/index.ts

@@ -59,6 +59,7 @@ export {
   type CheckoutCartView,
   type CheckoutFlowProps,
 } from './components/checkout/checkout-flow';
+export type { BackActionEmphasis } from './components/checkout/payment-status-parts';
 
 // ---------------------------------------------------------------------------
 // The MOUNTED buyer checkout (FUT-741) and the checkout PIPELINE (FUT-1240).