@12-apps/payments-frontend 3.21.4 → 3.22.0

package/src/components/checkout/hosted-store.ts

@@ -0,0 +1,269 @@
+import type { CheckoutOrder } from "./types";
+
+/**
+ * WHERE A CHECKOUT IN FLIGHT IS KEPT while the SPA is not (FUT-556, FUT-1140).
+ *
+ * A redirect provider takes the buyer to ITS OWN site, so the SPA is torn down
+ * and remounts fresh when they come back. A low-memory phone does the same
+ * thing without anybody leaving: the tab is discarded while the shopper is in
+ * their bank app, and the checkout that comes back has never heard of the order
+ * it raised. Everything the checkout held — which order, for how much, against
+ * which basket — is gone, and without it the return lands on an empty payment
+ * step: no confirmation, no total, no sign that the money they just moved
+ * arrived.
+ *
+ * The webhook still settles the order server-side; that is the mechanism and it
+ * does not depend on any of this. What is rescued here is only the buyer's view
+ * of it.
+ *
+ * `sessionStorage`, not `localStorage`: this is one tab's round trip, and a
+ * pending order left in durable storage would resurface in a later, unrelated
+ * session.
+ *
+ * This module is the STORAGE half only. Whether a parked entry may be resumed —
+ * which is a money rule, and the whole of FUT-1213 — lives in
+ * `./hosted-return.ts`.
+ */
+
+/**
+ * Where the parked order lives, namespaced to this PACKAGE.
+ *
+ * It used to carry one adopter's brand as its namespace, written into every
+ * adopter's browser. A storage key is not a private detail: it is observable
+ * surface, asserted on by `@12-apps/payments-e2e` and visible in devtools to
+ * anyone running the host. The sibling handover in this same folder already got
+ * this right with a `payments:` prefix; this one did not.
+ *
+ * Exported so a host or a spec names it rather than retyping it.
+ */
+export const HOSTED_ORDER_STORAGE_KEY = "payments.checkout.hostedOrder";
+
+/**
+ * The key before the 2.0.0 rename, READ ONLY — decoded from base64 so no
+ * spelling of the old brand, whole or split, appears in shipped source (both
+ * brand gates sweep this file), while the RUNTIME string stays exactly what
+ * pre-2.0.0 bundles wrote.
+ *
+ * A buyer who left for the provider's page on a pre-2.0.0 bundle comes back
+ * to a newer one with their order parked under the old name. Without this
+ * they land on the plain return screen — the order still settles, because the
+ * webhook does that and never depended on any of this, but the confirmation
+ * they were promised is missing for a reason they could not possibly
+ * understand.
+ *
+ * DELETE when both hold, and not before:
+ *  1. every adopter's production has served ONLY >= 2.0.0 bundles for at
+ *     least 24 hours (a hosted round trip lasts minutes; a day is
+ *     over-margin) — verified against each consumer's lockfile history, not
+ *     assumed from this package's release date; and
+ *  2. the deletion rides its own release with this note in the body, so an
+ *     adopter still rolling back to a pre-2.0.0 bundle knows the window it
+ *     reopens.
+ * 3.0.0 deleted this shim on the package's clock instead of the hosts' —
+ * consumers still pinned 2.x, so their key-renaming deploy had not happened
+ * yet — which is why it is back.
+ */
+const LEGACY_KEY = atob("ZnV0dXJlcGF5LmNoZWNrb3V0Lmhvc3RlZE9yZGVy");
+
+/**
+ * What is actually parked: the order, WHOSE STORE it belongs to, WHICH BASKET
+ * it was raised from, whether the buyer was sent away for it, and when.
+ *
+ * `CheckoutOrder` carries no tenant, and on a multi-tenant storefront every
+ * store shares one origin — so one tab holds one slot for all of them. Without
+ * the slug, a buyer who abandoned store A's hand-off and opened store B's
+ * checkout resumed A's order on B's screen: a confirmation for an unrelated
+ * order, and B's own checkout skipped.
+ *
+ * `basket` is the axis FUT-1213 added, and it is the one that decides whether
+ * this entry is still ABOUT anything: an order raised from a basket the shopper
+ * has since emptied and refilled is an order they are no longer placing. See
+ * `./basket.ts` for why it is a signature of the lines rather than a cart id.
+ *
+ * `handoff` records whether the buyer was sent to another site for this order.
+ * It decides WHERE a resume lands rather than whether one happens: a hand-off
+ * can only be confirmed by asking, so it resumes on the confirmation screen,
+ * while a PIX code raised on our own page is still the thing the buyer needs to
+ * look at.
+ *
+ * IT IS WRITTEN EXPLICITLY, both ways, and that is a compatibility rule rather
+ * than a style: every entry parked by a PRE-1140 bundle is a hand-off — those
+ * were the only two things that parked anything — so an ABSENT flag has to mean
+ * "hand-off", and a new entry that merely omitted `false` would be read as one
+ * too. A buyer resumed onto the payment step for a hand-off meets a spinner
+ * that never navigates and no poll, having had their parked entry consumed:
+ * the way out they actually take is a second order on a closed cart.
+ *
+ * `parkedAt` bounds the other axis. A checkout in flight is minutes; an entry
+ * older than {@link MAX_PARKED_AGE_MS} belongs to a session the buyer has long
+ * since abandoned, and resuming it tells them about an order they are no longer
+ * trying to place.
+ */
+export interface ParkedHostedOrder {
+  order: CheckoutOrder;
+  /** The store this checkout belongs to; absent for an unscoped host. */
+  tenantSlug?: string;
+  /**
+   * The basket the order was raised from — `null` for an empty one, and ABSENT
+   * when the host supplied no identity at all (an older bundle, a host that has
+   * not wired it). Absent and `null` are deliberately different: absent means
+   * "unknown", which the rule treats as today's behaviour.
+   */
+  basket?: string | null;
+  /**
+   * The buyer was sent to the provider's own page for this order.
+   *
+   * ABSENT means an entry from a bundle that predates the flag, and every one
+   * of those IS a hand-off — see the note above. `false` is written out for a
+   * charge raised on our own page precisely so the two stay distinguishable.
+   */
+  handoff?: boolean;
+  parkedAt: number;
+}
+
+/**
+ * How long a parked checkout stays resumable.
+ *
+ * Thirty minutes: a hosted payment takes minutes, and the window has to cover a
+ * buyer who fetches their card, not one who comes back tomorrow. Beyond it the
+ * entry is dropped on read rather than resumed.
+ */
+const MAX_PARKED_AGE_MS = 30 * 60_000;
+
+/** What a caller states about the checkout it is parking. */
+interface ParkedContext {
+  /** The store being paid. */
+  tenantSlug?: string;
+  /** The basket's signature — see {@link ParkedHostedOrder.basket}. */
+  basket?: string | null;
+  /** The buyer is being sent to the provider's own page. */
+  handoff?: boolean;
+}
+
+/** Park the raised order — before a hand-off, and on every raise (FUT-1140). */
+export function rememberHostedOrder(order: CheckoutOrder, context: ParkedContext = {}): void {
+  try {
+    const parked: ParkedHostedOrder = {
+      order,
+      ...(context.tenantSlug ? { tenantSlug: context.tenantSlug } : {}),
+      ...(context.basket === undefined ? {} : { basket: context.basket }),
+      // ALWAYS written, both ways: an absent flag is reserved for entries this
+      // version did not write, and those are all hand-offs.
+      handoff: context.handoff === true,
+      parkedAt: Date.now(),
+    };
+    window.sessionStorage?.setItem(HOSTED_ORDER_STORAGE_KEY, JSON.stringify(parked));
+  } catch {
+    // Storage disabled or full. The redirect must still happen: the webhook
+    // settles the order either way, and refusing to send the buyer to pay
+    // would be a far worse failure than a plain return screen.
+  }
+}
+
+/**
+ * The raw parked payload under either key.
+ *
+ * Split from the parsing so the two halves stay separately readable — they fail
+ * for unrelated reasons anyway (storage disabled vs. a value that is not an
+ * order).
+ */
+function peekParkedPayload(): string | null {
+  try {
+    return (
+      window.sessionStorage?.getItem(HOSTED_ORDER_STORAGE_KEY) ??
+      window.sessionStorage?.getItem(LEGACY_KEY) ??
+      null
+    );
+  } catch {
+    // Storage disabled or unavailable — the same "no parked order" as an empty
+    // slot, and the webhook still settles the order regardless.
+    return null;
+  }
+}
+
+/**
+ * The parked entry, parsed, or null. Tolerates the PRE-SCOPE shape — a bare
+ * `CheckoutOrder` — so a buyer mid-flight across the deploy still comes back
+ * to their confirmation.
+ */
+export function readParked(): ParkedHostedOrder | null {
+  const raw = peekParkedPayload();
+  if (!raw) return null;
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    if (isCheckoutOrder(parsed)) return { order: parsed, parkedAt: Date.now() };
+    if (typeof parsed !== "object" || parsed === null) return null;
+    return scopedEntry(parsed as Partial<ParkedHostedOrder>);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * The SCOPED shape, field by field, with every absent one left absent.
+ *
+ * Absence is meaningful on two of these — a basket that was never recorded is
+ * not the same as an empty one, and a hand-off flag that is missing means a
+ * charge raised on our own page — so nothing here defaults a field into
+ * existence.
+ */
+function scopedEntry(candidate: Partial<ParkedHostedOrder>): ParkedHostedOrder | null {
+  if (!isCheckoutOrder(candidate.order)) return null;
+  return {
+    order: candidate.order,
+    ...(candidate.tenantSlug ? { tenantSlug: candidate.tenantSlug } : {}),
+    ...(candidate.basket === undefined ? {} : { basket: candidate.basket }),
+    // Preserved as WRITTEN, `false` included — dropping it here would turn
+    // every on-page charge back into the legacy shape and resume it on the
+    // confirmation screen.
+    ...(candidate.handoff === undefined ? {} : { handoff: candidate.handoff === true }),
+    parkedAt: typeof candidate.parkedAt === "number" ? candidate.parkedAt : Date.now(),
+  };
+}
+
+/**
+ * Trust nothing that came back out of storage: it is the only input here that
+ * did not come from this render, and a half-written or hand-edited value would
+ * otherwise reach the status view as an order.
+ */
+function isCheckoutOrder(value: unknown): value is CheckoutOrder {
+  if (typeof value !== "object" || value === null) return false;
+  const candidate = value as Partial<CheckoutOrder>;
+  return typeof candidate.orderId === "string" && typeof candidate.totalLabel === "string";
+}
+
+/** Whether a parked checkout is this store's. */
+export function belongsHere(parked: ParkedHostedOrder, tenantSlug?: string): boolean {
+  // An unscoped entry (a host that passes no slug, or one parked by an older
+  // bundle) stays readable by anyone — the single-tenant case, where there is
+  // no other store to confuse it with.
+  if (!parked.tenantSlug || !tenantSlug) return true;
+  return parked.tenantSlug === tenantSlug;
+}
+
+/** Whether it has been sitting long enough to no longer be this trip's. */
+export function isStale(parked: ParkedHostedOrder): boolean {
+  if (typeof parked.parkedAt !== "number") return false;
+  return Date.now() - parked.parkedAt > MAX_PARKED_AGE_MS;
+}
+
+/**
+ * Drop the parked entry. Split from the read because the READ has to decide
+ * whose it is first — consuming another store's checkout was the bug the
+ * scoping exists to stop.
+ *
+ * BOTH keys, whichever answered: a legacy entry left behind would let a later
+ * return trip resume an order that was already consumed.
+ *
+ * Exported because the entry now outlives a single read (FUT-1213's deferred
+ * ask, FUT-1146's release, and the settle that ends a checkout normally), so
+ * callers other than the read need a way to say "this one is finished".
+ */
+export function forgetHostedOrder(): void {
+  try {
+    window.sessionStorage?.removeItem(HOSTED_ORDER_STORAGE_KEY);
+    window.sessionStorage?.removeItem(LEGACY_KEY);
+  } catch {
+    // Storage disabled — there was nothing to clear.
+  }
+}

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

@@ -0,0 +1,311 @@
+import { Box } from "@mui/material";
+import type { JSX } from "react";
+
+import { CheckCircleOutlineIcon, ErrorOutlineIcon, ScheduleIcon } from "./icons";
+import type { CheckoutDecline } from "./decline";
+import type { OrderStatus } from "./types";
+import { useCheckoutComponents } from "./ui";
+import type { PaymentStatusCopy, StatusOutcomeCopy } from "./view-copy";
+
+/**
+ * The BLOCKS the last screen of checkout is made of — its headline, its paid
+ * receipt and its action row.
+ *
+ * Split out of `./payment-status.tsx` when the classified decline (FUT-1145)
+ * and the buyer's own release (FUT-1146) took that file past its size gate.
+ * The split is along the seam the screen already had: this module renders,
+ * `payment-status.tsx` decides WHICH of these a status and a wait add up to.
+ */
+
+/**
+ * The per-outcome VISUAL grammar — icon and semantic tone. The heading and
+ * supporting line beside them come from {@link PaymentStatusCopy}: an icon is
+ * the component's own vocabulary, a sentence never is. (The FAILED support
+ * line's job — say "nothing was charged" plainly and first — and the
+ * timed-out wait's "do not pay again" now live with the host's words, where
+ * FUT-556's reasoning is documented on the copy port.)
+ */
+interface OutcomeVisual {
+  icon: JSX.Element;
+  /** Semantic theme token — never a raw colour. */
+  tone: "success" | "danger" | "warning" | "neutral";
+}
+
+const OUTCOME_VISUAL: Record<OrderStatus, OutcomeVisual> = {
+  PAID: { icon: <CheckCircleOutlineIcon fontSize="large" />, tone: "success" },
+  AWAITING_PAYMENT: { icon: <ScheduleIcon fontSize="large" />, tone: "neutral" },
+  FAILED: { icon: <ErrorOutlineIcon fontSize="large" />, tone: "danger" },
+  EXPIRED: { icon: <ScheduleIcon fontSize="large" />, tone: "warning" },
+};
+
+const OUTCOME_COPY_KEY: Record<OrderStatus, keyof Pick<
+  PaymentStatusCopy,
+  "paid" | "awaiting" | "failed" | "expired"
+>> = {
+  PAID: "paid",
+  AWAITING_PAYMENT: "awaiting",
+  FAILED: "failed",
+  EXPIRED: "expired",
+};
+
+const TONE_COLOR: Record<OutcomeVisual["tone"], string> = {
+  success: "success.main",
+  danger: "error.main",
+  warning: "warning.main",
+  neutral: "text.secondary",
+};
+
+/**
+ * The buyer's quotable reference.
+ *
+ * The order id is a uuid — unreadable over a phone call and impossible to copy
+ * by eye — so the screen shows its first block, uppercased. It is the real id's
+ * own prefix rather than a second number, so support can still find the order
+ * from what the buyer reads out.
+ */
+function orderReference(orderId: string): string {
+  return orderId.replace(/-/g, "").slice(0, 8).toUpperCase();
+}
+
+/** How the wait itself is going, when it has not resolved into an outcome. */
+export interface WaitState {
+  /** The bounded wall-clock wait elapsed — nothing further is scheduled. */
+  timedOut: boolean;
+  /** The last poll failed, and the wait is still running (FUT-1144). */
+  unreachable: boolean;
+}
+
+/**
+ * Which of AWAITING's three faces this is.
+ *
+ * STOPPED beats STILL TRYING, and the order is the whole honesty of the screen.
+ * A wait that ran its clock out while failing carries BOTH flags — the last
+ * poll's error is still the last thing that happened — and saying "we keep
+ * trying" over a wait nothing is scheduled for is precisely the lie this ticket
+ * exists to remove. The elapsed state is also the one carrying "não pague de
+ * novo", which is the sentence that matters most when we have stopped looking.
+ *
+ * Both keep AWAITING's neutral clock icon and take WARNING's tone: the order is
+ * not resolved, and calm-but-alert is the visual for that.
+ */
+function awaitingFace(
+  copy: PaymentStatusCopy,
+  wait: WaitState,
+): { outcome: StatusOutcomeCopy; tone: OutcomeVisual["tone"]; testId: string } | null {
+  if (wait.timedOut) {
+    return { outcome: copy.awaitingTimedOut, tone: "warning", testId: "payment-awaiting-timeout" };
+  }
+  if (wait.unreachable) {
+    return { outcome: copy.awaitingUnreachable, tone: "warning", testId: "payment-awaiting-unreachable" };
+  }
+  return null;
+}
+
+/**
+ * What a REFUSED card says, as specifically as the server let us be (FUT-1145).
+ *
+ * Falls back to the generic refusal for a reason the host wrote no sentence for
+ * — including one this bundle has never heard of, which is an ordinary state
+ * when the server is a release ahead. The fallback is exactly the screen this
+ * ticket started from, so the worst case is no worse than before.
+ */
+function failedOutcome(copy: PaymentStatusCopy, decline: CheckoutDecline | null): StatusOutcomeCopy {
+  const reason = decline?.reason;
+  // `?.` on the TABLE as well as the row: a host that has not written the block
+  // at all lands on `failed`, which is a sentence it did write. The optional
+  // chain is not a copy default — nothing is invented here — it is the
+  // difference between one unworded refusal and a `TypeError` that unmounts a
+  // live checkout. The type still REQUIRES the key, so a host that typechecks
+  // is told; the ones that do not are the reason this is defensive at all.
+  return (reason ? copy.declined?.[reason] : undefined) ?? copy.failed;
+}
+
+/** The headline block: icon, outcome, and one supporting line. */
+export function OutcomeHero({
+  copy,
+  status,
+  wait,
+  decline,
+}: {
+  copy: PaymentStatusCopy;
+  status: OrderStatus;
+  wait: WaitState;
+  decline: CheckoutDecline | null;
+}): JSX.Element {
+  const { Text } = useCheckoutComponents();
+  const face = status === "AWAITING_PAYMENT" ? awaitingFace(copy, wait) : null;
+  const visual = face
+    ? { icon: OUTCOME_VISUAL.AWAITING_PAYMENT.icon, tone: face.tone }
+    : OUTCOME_VISUAL[status];
+  const outcome = face
+    ? face.outcome
+    : status === "FAILED"
+      ? failedOutcome(copy, decline)
+      : copy[OUTCOME_COPY_KEY[status]];
+  return (
+    <Box
+      // `payment-paid` is load-bearing for the storefront journeys — it is how
+      // they assert the buyer actually got there. Each unsettled wait gets its
+      // OWN id rather than reusing `payment-awaiting_payment`: a test that
+      // cannot tell "still asking" from "stopped asking" from "cannot reach the
+      // payment" is a test that would pass against the spinner this replaced.
+      data-testid={
+        face ? face.testId : status === "PAID" ? "payment-paid" : `payment-${status.toLowerCase()}`
+      }
+      sx={{ display: "flex", flexDirection: "column", alignItems: "center", gap: 1, textAlign: "center" }}
+    >
+      <Box sx={{ color: TONE_COLOR[visual.tone], display: "flex" }}>{visual.icon}</Box>
+      <Text variant="heading" size="md" weight="bold" as="h2">
+        {outcome.heading}
+      </Text>
+      <Text variant="body" size="sm" as="p" style={{ opacity: 0.75 }}>
+        {outcome.support}
+      </Text>
+    </Box>
+  );
+}
+
+/** One label/value row of the paid receipt block. */
+function Fact({ label, value, testId }: { label: string; value: string; testId?: string }): JSX.Element {
+  const { Text } = useCheckoutComponents();
+  return (
+    <Box sx={{ display: "flex", justifyContent: "space-between", alignItems: "baseline", gap: 2 }}>
+      <Text variant="body" size="sm" as="span" style={{ opacity: 0.75 }}>
+        {label}
+      </Text>
+      <Text variant="body" size="sm" weight="bold" as="span" data-testid={testId}>
+        {value}
+      </Text>
+    </Box>
+  );
+}
+
+/**
+ * What a paid buyer will want later: how much left their account, which order
+ * it was, and where the receipt went. Rendered only for PAID — on any other
+ * outcome these facts are either untrue or not yet knowable.
+ */
+export function PaidFacts({
+  copy,
+  totalLabel,
+  orderId,
+  buyerEmail,
+}: {
+  copy: PaymentStatusCopy;
+  totalLabel: string;
+  orderId?: string;
+  buyerEmail?: string;
+}): JSX.Element {
+  return (
+    <Box
+      data-testid="payment-receipt"
+      sx={{
+        display: "flex",
+        flexDirection: "column",
+        gap: 1,
+        p: 2,
+        borderRadius: 2,
+        bgcolor: "action.hover",
+      }}
+    >
+      <Fact label={copy.amountLabel} value={totalLabel} testId="payment-amount" />
+      {orderId ? (
+        <Fact label={copy.referenceLabel} value={`#${orderReference(orderId)}`} testId="payment-reference" />
+      ) : null}
+      {buyerEmail ? <Fact label={copy.receiptEmailLabel} value={buyerEmail} /> : null}
+    </Box>
+  );
+}
+
+/**
+ * Whether "Tentar novamente" may be offered for a refusal (FUT-1145).
+ *
+ * `retriable === false` is the provider's OWN verdict that another attempt with
+ * this instrument cannot succeed — attempts exhausted (10001), a cancelled
+ * recurring mandate (20118), a malformed request. Offering a retry there is
+ * offering a button that mints another failed order and shows the same screen
+ * again; on a card the issuer is already counting, it is worse than useless.
+ *
+ * SILENCE MEANS YES. An undefined verdict is a provider that offered no
+ * guidance, not a refusal to retry, and withholding the button on silence
+ * would strand a buyer whose card is fine.
+ */
+function retryable(decline: CheckoutDecline | null): boolean {
+  return decline?.retriable !== false;
+}
+
+/** The next-action row: retry / regenerate / check-again, always back-to-menu. */
+export function StatusActions({
+  copy,
+  status,
+  decline,
+  onRetry,
+  onRegenerate,
+  onCheckAgain,
+  onNotPaid,
+  onBackToMenu,
+}: {
+  copy: PaymentStatusCopy;
+  status: OrderStatus;
+  decline: CheckoutDecline | null;
+  onRetry?: () => void;
+  onRegenerate?: () => void;
+  /**
+   * Offered only while the wait is unsettled AND not visibly working — the
+   * caller decides that; here it is simply present or absent. A button under a
+   * healthy spinner would invite a tap that changes nothing.
+   */
+  onCheckAgain?: () => void;
+  /** The buyer's "I did not pay" (FUT-1146) — present only while it applies. */
+  onNotPaid?: () => void;
+  onBackToMenu: () => void;
+}): JSX.Element {
+  const { Button } = useCheckoutComponents();
+  return (
+    <Box sx={{ display: "flex", flexDirection: "column", gap: 1 }}>
+      {onCheckAgain ? (
+        <Button
+          variant="solid"
+          color="primary"
+          size="lg"
+          onClick={onCheckAgain}
+          dataTestId="payment-check-again"
+        >
+          {copy.checkAgainAction}
+        </Button>
+      ) : null}
+      {onNotPaid ? (
+        <Button
+          variant="outline"
+          color="neutral"
+          size="lg"
+          onClick={onNotPaid}
+          dataTestId="payment-not-paid"
+        >
+          {copy.notPaidAction}
+        </Button>
+      ) : null}
+      {status === "FAILED" && onRetry && retryable(decline) ? (
+        <Button variant="solid" color="primary" size="lg" onClick={onRetry} dataTestId="payment-retry">
+          {copy.retryAction}
+        </Button>
+      ) : null}
+      {status === "EXPIRED" && onRegenerate ? (
+        <Button variant="solid" color="primary" size="lg" onClick={onRegenerate} dataTestId="payment-regenerate">
+          {copy.regenerateAction}
+        </Button>
+      ) : null}
+      <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"}
+        size="lg"
+        onClick={onBackToMenu}
+        dataTestId="payment-back-to-menu"
+      >
+        {copy.backAction}
+      </Button>
+    </Box>
+  );
+}