@12-apps/payments-frontend 3.21.4 → 3.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@12-apps/payments-frontend",
-  "version": "3.21.4",
+  "version": "3.23.0",
   "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.",
@@ -22,7 +22,7 @@
     "storybook:build": "storybook build"
   },
   "dependencies": {
-    "@12-apps/payments-backend": "^4.26.1",
+    "@12-apps/payments-backend": "^4.27.1",
     "react-qr-code": "^2.2.0"
   },
   "peerDependencies": {

package/src/components/checkout/basket.ts

@@ -0,0 +1,85 @@
+/**
+ * WHAT IS IN THE BASKET, as one comparable fact (FUT-1213).
+ *
+ * A parked checkout has to be able to ask "is this still the basket the order
+ * was raised from?" when the buyer comes back — and the answer cannot be the
+ * cart's ID. Emptying a cart ("Esvaziar carrinho") keeps the row: the same id
+ * comes back holding nothing, then holding something else entirely, and a
+ * comparison on the id says "same basket" for a shopper who has thrown the old
+ * one away and started again.
+ *
+ * So the identity is the LINES: which ones, and how many of each. Two baskets
+ * with the same lines in a different order are the same basket; one extra unit
+ * of one line is not.
+ *
+ * The HOST computes it, because the host owns the cart — this module only says
+ * what shape the answer takes and how to build one from lines, so that every
+ * adopter's signature is built the same way and a package-side comparison can
+ * mean something.
+ */
+
+/** One line of the host's basket, reduced to what identity depends on. */
+export interface CheckoutBasketLine {
+  /** The line's own stable handle — a cart-line id, never a product id alone. */
+  id: string;
+  quantity: number;
+}
+
+/**
+ * The lines' signature, or `null` for an empty basket.
+ *
+ * `null` rather than `""` because an EMPTY basket is a meaningful state on this
+ * path rather than a missing answer: the server closes a cart when its order is
+ * paid, so an empty basket is exactly what a buyer who paid comes back to.
+ *
+ * Sorted before joining, so the answer does not depend on the order the host
+ * happens to hold its lines in — a re-fetch that returns them differently
+ * sorted must not read as a different basket.
+ *
+ * The id is ENCODED before it is joined. `id + "x" + quantity` on a `|` join is
+ * ambiguous the moment an id can contain either character: `[a×1, b×2]` and the
+ * single line `["ax1|b" × 2]` produce the same string, and two different baskets
+ * that compare equal is a resume over the wrong one. Unreachable with the cuid
+ * and uuid ids every adopter has today — and this is exported for hosts whose
+ * ids nobody here has seen, so it is encoded rather than argued about.
+ */
+export function basketSignature(lines: readonly CheckoutBasketLine[]): string | null {
+  if (lines.length === 0) return null;
+  return lines
+    .map((line) => `${encodeURIComponent(line.id)}x${line.quantity}`)
+    .sort()
+    .join("|");
+}
+
+/**
+ * The basket in front of the checkout right now, as the resume rule reads it.
+ *
+ * `ready` is not a nicety. The host's cart is fetched, so the first render of a
+ * checkout has an EMPTY cart that is merely unloaded — and "empty" is the one
+ * state the rule resumes on unconditionally (it is the paid buyer's normal
+ * state). Deciding against an unseeded cart would resume every abandoned
+ * hand-off on every mount, which is the bug this whole rule exists to remove.
+ * So the decision waits.
+ */
+export interface CheckoutBasketIdentity {
+  /** The lines' signature; `null` ⇒ the basket is empty. */
+  signature: string | null;
+  /** False while the host's cart is still loading — decide nothing yet. */
+  ready: boolean;
+}
+
+/**
+ * The signature to PARK with an order, or nothing.
+ *
+ * `undefined` — meaning "no basket was recorded" — for a host that names none
+ * AND for a cart that has not answered yet. The second is the one worth
+ * stating: a loading cart reports `signature: null`, which is the value that
+ * means EMPTY, and an order parked as "raised from an empty basket" would later
+ * be compared against the real one and read as a different basket. Recording
+ * nothing is honest and degrades to the pre-1213 resume; recording `null` would
+ * be a fact we do not have.
+ */
+export function parkedBasket(basket: CheckoutBasketIdentity | undefined): string | null | undefined {
+  if (!basket || !basket.ready) return undefined;
+  return basket.signature;
+}

package/src/components/checkout/card-outcome.ts

@@ -0,0 +1,81 @@
+import { parkedBasket, type CheckoutBasketIdentity } from "./basket";
+import type { CheckoutDecline } from "./decline";
+import { rememberHostedOrder } from "./hosted-return";
+import type { CheckoutNavigate } from "./navigate-context";
+import type { ChargeOutcome, CheckoutOrder, OnCheckoutResolved } from "./types";
+
+/**
+ * WHAT HAPPENS TO A CHARGE'S ANSWER — the two endings a card submit can have
+ * that are not "keep polling".
+ *
+ * Split out of `./use-card-checkout.ts`, which is at its size ceiling. Both
+ * halves are about the same moment: the provider has answered, and the buyer
+ * is either being sent somewhere or being told something.
+ */
+
+/** Whose store and which basket a challenge's parked order belongs to. */
+export interface ChallengeScope {
+  tenantSlug?: string;
+  basket?: CheckoutBasketIdentity;
+}
+
+/**
+ * Hand the buyer to the provider's authentication page (FUT-698) — Stripe's
+ * redirect-based 3-D Secure. Park the order and navigate, the same trip a
+ * redirect provider's link takes (FUT-556): the return lands back on this
+ * checkout route, where the hosted-resume machinery polls the parked order.
+ *
+ * IT PARKS WITH THE SAME FACTS the other hand-off does, and that is a fix
+ * rather than a tidy-up: this call site named neither the store nor the basket,
+ * and both absences are read as "no opinion" by the resume — `belongsHere`
+ * passes an entry with no slug at ANY store, and the basket rule passes an
+ * entry with no basket against ANY basket. So a 3-D Secure challenge the buyer
+ * abandoned was exempt from both the multi-tenant scoping (FUT-556) and the
+ * basket binding (FUT-1213): it resumed over whatever checkout mounted next.
+ */
+export function handOverToChallenge(
+  order: CheckoutOrder,
+  url: string,
+  navigate: CheckoutNavigate,
+  scope: ChallengeScope = {},
+): void {
+  // PARK FIRST. The navigation may not come back to a live SPA at all, and a
+  // return trip that finds nothing parked lands the buyer on a blank
+  // confirmation after they have paid.
+  const basket = parkedBasket(scope.basket);
+  rememberHostedOrder(order, {
+    ...(scope.tenantSlug ? { tenantSlug: scope.tenantSlug } : {}),
+    ...(basket === undefined ? {} : { basket }),
+    handoff: true,
+  });
+  navigate(url);
+}
+
+/**
+ * The refusal a charge answer carries, or nothing (FUT-1145).
+ *
+ * `undefined` for an outcome with neither field — an older server, a provider
+ * whose adapter classifies nothing — so the caller makes the same one-argument
+ * call it always did and every screen below behaves exactly as before.
+ */
+function declineOf(outcome: ChargeOutcome): CheckoutDecline | undefined {
+  const reason = outcome.declineReason;
+  const retriable = outcome.retriable;
+  if (reason === undefined && retriable === undefined) return undefined;
+  return {
+    ...(reason === undefined ? {} : { reason }),
+    ...(retriable === undefined ? {} : { retriable }),
+  };
+}
+
+/**
+ * Bubble a terminal status up, carrying the refusal when there is one.
+ *
+ * Called with ONE argument when the server said nothing new, so a host on an
+ * older mount produces exactly the call it always did.
+ */
+export function reportResolved(outcome: ChargeOutcome, onResolved: OnCheckoutResolved): void {
+  const refusal = declineOf(outcome);
+  if (refusal) onResolved(outcome.status, refusal);
+  else onResolved(outcome.status);
+}

package/src/components/checkout/card-view.tsx

@@ -11,8 +11,9 @@ import {
 import { useCheckoutCopy } from "./copy-context";
 import { UNRESOLVED_CODE } from "./failure-codes";
 import { StalledWait } from "./stalled-wait";
+import type { CheckoutBasketIdentity } from "./basket";
 import type { CardChainLink } from "./method-capability";
-import type { BuyerInfo, CheckoutOrder, OrderStatus } from "./types";
+import type { BuyerInfo, CheckoutOrder, OnCheckoutResolved } from "./types";
 import { useCheckoutComponents } from "./ui";
 import { useCardCheckout, type CardCheckout } from "./use-card-checkout";
 
@@ -97,6 +98,40 @@ function ChargeFailure({
   );
 }
 
+/**
+ * What the buyer pays WITH: the saved cards they may reuse, and the form for a
+ * new one.
+ *
+ * The picker is absent when there is nothing saved, and the form is absent
+ * while a saved card is selected — so a buyer retrying a refused card (FUT-1145)
+ * lands on the form, because nothing is preselected for them.
+ */
+function CardInstrumentFields({ card }: { card: CardCheckout }): JSX.Element {
+  return (
+    <>
+      {card.savedCards.length > 0 ? (
+        <SavedCardsPicker
+          savedCards={card.savedCards}
+          selection={card.selection}
+          onSelect={card.setSelection}
+        />
+      ) : null}
+
+      {card.usingNewCard ? (
+        <NewCardForm
+          card={card.card}
+          fieldErrors={card.fieldErrors}
+          brand={card.brand}
+          saveCard={card.saveCard}
+          setCard={card.setCard}
+          setFieldErrors={card.setFieldErrors}
+          onSaveCardChange={card.setSaveCard}
+        />
+      ) : null}
+    </>
+  );
+}
+
 /**
  * Card payment view (FUT-58). Card data is validated + formatted client-side, then
  * tokenized (mock PagBank JS SDK) so the PAN never reaches our server; only the
@@ -115,6 +150,8 @@ export function CardView({
   tenantSlug,
   onResolved,
   pollIntervalMs = 2500,
+  freshInstrument = false,
+  basket,
 }: {
   order: CheckoutOrder;
   buyer?: BuyerInfo;
@@ -128,12 +165,33 @@ export function CardView({
   providerChain?: CardChainLink[];
   /** Scopes the saved-card list to cards the store's provider can charge. */
   tenantSlug?: string;
-  onResolved: (status: OrderStatus) => void;
+  onResolved: OnCheckoutResolved;
   pollIntervalMs?: number;
+  /**
+   * Preselect NOTHING from the saved list (FUT-1145): the buyer is back here
+   * because a card was refused, and the card this would otherwise choose for
+   * them is that one.
+   */
+  freshInstrument?: boolean;
+  /**
+   * WHICH basket this checkout is for (FUT-1213) — parked with the order when
+   * a 3-D Secure challenge sends the buyer to the provider's page.
+   */
+  basket?: CheckoutBasketIdentity;
 }): JSX.Element {
   const { Text } = useCheckoutComponents();
   const copy = useCheckoutCopy().screens.card;
-  const cc = useCardCheckout(order, buyer, providerConfig, onResolved, pollIntervalMs, tenantSlug, providerChain);
+  const cc = useCardCheckout(
+    order,
+    buyer,
+    providerConfig,
+    onResolved,
+    pollIntervalMs,
+    tenantSlug,
+    providerChain,
+    freshInstrument,
+    { tenantSlug, basket },
+  );
   // A charge NOBODY can confirm yet is not a decline (FUT-563). Some provider
   // may be holding the buyer's money, so it gets its own presentation: the
   // danger heading "Não foi possível pagar" contradicts the body's "não pague
@@ -150,25 +208,7 @@ export function CardView({
         {copy.heading}
       </Text>
 
-      {cc.savedCards.length > 0 ? (
-        <SavedCardsPicker
-          savedCards={cc.savedCards}
-          selection={cc.selection}
-          onSelect={cc.setSelection}
-        />
-      ) : null}
-
-      {cc.usingNewCard ? (
-        <NewCardForm
-          card={cc.card}
-          fieldErrors={cc.fieldErrors}
-          brand={cc.brand}
-          saveCard={cc.saveCard}
-          setCard={cc.setCard}
-          setFieldErrors={cc.setFieldErrors}
-          onSaveCardChange={cc.setSaveCard}
-        />
-      ) : null}
+      <CardInstrumentFields card={cc} />
 
       {cc.error ? <ChargeFailure message={cc.error} unresolved={unresolved} /> : null}