@tribe-nest/forge 3.26.0 → 3.29.0

package/src/ui/headless/checkout/_tests/useCartResume.spec.tsx

@@ -0,0 +1,294 @@
+// @vitest-environment jsdom
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { useSyncExternalStore } from "react";
+import type { ResumeLine, ResumedCheckout } from "../../../../data/queries/useCheckouts";
+import { ProductDeliveryType } from "../../../../types/models";
+
+/**
+ * `useCartResume` end to end: what a recovery link actually puts in the basket.
+ *
+ * The pure translation of a line is asserted in `cartResume.spec.ts`. What is
+ * asserted HERE is the part no pure function can show: which lines reach
+ * `restoreCart`, and WHEN. Both storefronts render this hook, so a defect here
+ * is a defect on every artist's shop at once.
+ *
+ * Two seams, both mocked at the module boundary so nothing touches the network:
+ *
+ * - `useResumeCheckout`, whose `mutateAsync` is the exchange.
+ * - `useCart`, so the spec can hold `isReady` at `false` and release it. A real
+ *   `CartProvider` hydrates inside the first commit, which is exactly the case
+ *   the hook's `isReady` guard is NOT written for.
+ */
+
+const cartStub = vi.hoisted(() => {
+  let ready = false;
+  const listeners = new Set<() => void>();
+  return {
+    restoreCart: vi.fn(),
+    subscribe(listener: () => void) {
+      listeners.add(listener);
+      return () => void listeners.delete(listener);
+    },
+    read: () => ready,
+    setReady(next: boolean) {
+      ready = next;
+      listeners.forEach((listener) => listener());
+    },
+    reset() {
+      ready = false;
+      listeners.clear();
+      cartStub.restoreCart.mockClear();
+    },
+  };
+});
+
+const exchange = vi.hoisted(() => ({ mutateAsync: vi.fn() }));
+
+vi.mock("../../../../contexts/CartContext", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../../../../contexts/CartContext")>()),
+  useCart: () => ({
+    restoreCart: cartStub.restoreCart,
+    isReady: useSyncExternalStore(cartStub.subscribe, cartStub.read, cartStub.read),
+  }),
+}));
+
+vi.mock("../../../../data/queries/useCheckouts", async (importOriginal) => ({
+  ...(await importOriginal<typeof import("../../../../data/queries/useCheckouts")>()),
+  useResumeCheckout: () => exchange,
+}));
+
+import { useCartResume } from "../useCartResume";
+
+const productLine = (overrides: Partial<ResumeLine> = {}): ResumeLine => ({
+  type: "product",
+  quantity: 1,
+  title: "Tour Tee",
+  coverImage: null,
+  price: 25,
+  unitPriceCents: 2500,
+  quotedUnitPriceCents: 2500,
+  priceChanged: false,
+  available: true,
+  unavailableReason: null,
+  productId: "prod-1",
+  productVariantId: "var-1",
+  deliveryType: ProductDeliveryType.Physical,
+  isGift: false,
+  ...overrides,
+});
+
+const ticketLine = (overrides: Partial<ResumeLine> = {}): ResumeLine => ({
+  type: "event_ticket",
+  quantity: 2,
+  title: "General Admission",
+  coverImage: null,
+  price: 25,
+  unitPriceCents: 2500,
+  quotedUnitPriceCents: 2500,
+  priceChanged: false,
+  available: true,
+  unavailableReason: null,
+  eventId: "event-1",
+  ticketId: "tier-ga",
+  eventSlug: "spring-tour",
+  eventTitle: "Spring Tour",
+  pwywAmount: null,
+  bookingFee: null,
+  ...overrides,
+});
+
+const payload = (lines: ResumeLine[]): ResumedCheckout => ({
+  checkoutId: "checkout-1",
+  profileId: "profile-1",
+  source: "checkout",
+  currency: "USD",
+  buyer: { firstName: null, lastName: null, email: null },
+  couponCode: null,
+  lines,
+  itemCount: lines.length,
+  subtotalCents: 0,
+});
+
+const addon = productLine({
+  productId: "prod-addon",
+  productVariantId: "var-addon",
+  title: "Tour poster",
+  attachedTo: { type: "event", entityId: "event-1" },
+});
+
+/** Mount the hook, with the exchange already answering `lines`. */
+const resume = async (lines: ResumeLine[], { ready = true } = {}) => {
+  exchange.mutateAsync.mockResolvedValue(payload(lines));
+  cartStub.setReady(ready);
+  const hook = renderHook(() => useCartResume({ token: "tok-1" }));
+  await waitFor(() => expect(hook.result.current.status).not.toBe("loading"));
+  return hook;
+};
+
+beforeEach(() => {
+  cartStub.reset();
+  exchange.mutateAsync.mockReset();
+});
+
+afterEach(() => {
+  vi.clearAllMocks();
+});
+
+describe("useCartResume: an add-on never lands without its ticket", () => {
+  it("REGRESSION: does not restore an add-on whose event ticket is sold out", async () => {
+    // The basket this used to build is one the server refuses outright: an
+    // add-on with no base. The buyer reached the payment screen, was turned
+    // away, and nothing on the page ever named the poster as the reason.
+    const { result } = await resume([
+      ticketLine({ available: false, unavailableReason: "sold_out" }),
+      addon,
+    ]);
+
+    // Nothing survived, so nothing is written to the basket at all. Before the
+    // fix this was called with the poster as its only item.
+    expect(cartStub.restoreCart).not.toHaveBeenCalled();
+    expect(result.current.restoredLines).toEqual([]);
+  });
+
+  it("tells the buyer the add-on was left out rather than dropping it silently", async () => {
+    const { result } = await resume([
+      ticketLine({ available: false, unavailableReason: "sold_out" }),
+      addon,
+    ]);
+
+    expect(result.current.droppedLines.map((line) => line.title)).toEqual(["Tour poster"]);
+    // Not smuggled into the server's own list: nothing about it is unavailable.
+    expect(result.current.unavailableLines.map((line) => line.title)).toEqual([
+      "General Admission",
+    ]);
+  });
+
+  it("leaves an orphaned add-on out of the count and the subtotal", async () => {
+    // Otherwise the page promises a basket that is one line and $25 heavier
+    // than the one checkout will show.
+    const { result } = await resume([
+      ticketLine({ available: false, unavailableReason: "sold_out" }),
+      addon,
+      productLine({ productId: "prod-9", productVariantId: "var-9", quantity: 2 }),
+    ]);
+
+    expect(result.current.itemCount).toBe(2);
+    expect(result.current.subtotalCents).toBe(5000);
+  });
+
+  it("restores the add-on when its ticket is restored alongside it", async () => {
+    const { result } = await resume([ticketLine(), addon]);
+
+    const [call] = cartStub.restoreCart.mock.calls;
+    expect(call[0].items).toHaveLength(1);
+    expect(call[0].items[0]).toMatchObject({
+      productId: "prod-addon",
+      attachedTo: { type: "event", entityId: "event-1" },
+    });
+    expect(call[0].tickets).toHaveLength(1);
+    expect(call[0].tickets[0].tickets).toEqual({ "tier-ga": 2 });
+    expect(result.current.droppedLines).toEqual([]);
+  });
+
+  it("drops an add-on attached to an event whose ticket is not in the payload at all", async () => {
+    const { result } = await resume([addon]);
+
+    expect(result.current.droppedLines.map((line) => line.title)).toEqual(["Tour poster"]);
+    expect(cartStub.restoreCart).not.toHaveBeenCalled();
+  });
+
+  it("leaves an ordinary product alone, attached to nothing", async () => {
+    // Attachment describes how a line was ADDED, never what the product is. The
+    // same poster bought from the shop sells on its own.
+    const { result } = await resume([productLine({ title: "Tour poster" })]);
+
+    expect(result.current.droppedLines).toEqual([]);
+    expect(result.current.restoredLines.map((line) => line.title)).toEqual(["Tour poster"]);
+  });
+});
+
+describe("useCartResume: what goes back, and when", () => {
+  it("REGRESSION: restores once the cart finishes hydrating, not never", async () => {
+    // The hook waits for `isReady` because `CartProvider` hydrates in a mount
+    // effect that REPLACES the whole list. While `isReady` was missing from the
+    // callback's dependencies, React handed back the same stale closure for
+    // ever and the wait became a permanent refusal: on a slow localStorage read
+    // the buyer landed on "your basket is back" with an empty basket.
+    const { result } = await resume([productLine()], { ready: false });
+
+    expect(result.current.status).toBe("restored");
+    expect(cartStub.restoreCart).not.toHaveBeenCalled();
+
+    act(() => cartStub.setReady(true));
+
+    await waitFor(() => expect(cartStub.restoreCart).toHaveBeenCalledTimes(1));
+  });
+
+  it("restores once, however many times the page re-renders", async () => {
+    // The endpoint stamps the arrival that cart recovery attributes on, and a
+    // second restore would re-inflate a quantity the buyer had just lowered.
+    const { rerender } = await resume([productLine()]);
+
+    rerender();
+    act(() => cartStub.setReady(true));
+    rerender();
+
+    expect(cartStub.restoreCart).toHaveBeenCalledTimes(1);
+  });
+
+  it("asks the exchange once per token, because the request is also an arrival stamp", async () => {
+    const { rerender } = await resume([productLine()]);
+    rerender();
+    expect(exchange.mutateAsync).toHaveBeenCalledTimes(1);
+    expect(exchange.mutateAsync).toHaveBeenCalledWith({ token: "tok-1" });
+  });
+
+  it("sends nothing and reports the link as broken when the token is blank", async () => {
+    cartStub.setReady(true);
+    const { result } = renderHook(() => useCartResume({ token: "   " }));
+
+    await waitFor(() => expect(result.current.status).toBe("error"));
+    expect(result.current.error).toBe("missing_token");
+    expect(exchange.mutateAsync).not.toHaveBeenCalled();
+  });
+
+  it("surfaces the server's refusal without touching the basket", async () => {
+    exchange.mutateAsync.mockRejectedValue({ response: { data: { message: "expired" } } });
+    cartStub.setReady(true);
+    const { result } = renderHook(() => useCartResume({ token: "tok-1" }));
+
+    await waitFor(() => expect(result.current.status).toBe("error"));
+    expect(result.current.error).toBe("expired");
+    expect(cartStub.restoreCart).not.toHaveBeenCalled();
+  });
+
+  it("holds the basket back when the caller draws its own button", async () => {
+    exchange.mutateAsync.mockResolvedValue(payload([productLine()]));
+    cartStub.setReady(true);
+    const { result } = renderHook(() => useCartResume({ token: "tok-1", autoRestore: false }));
+
+    await waitFor(() => expect(result.current.status).toBe("restored"));
+    expect(cartStub.restoreCart).not.toHaveBeenCalled();
+
+    act(() => result.current.restore());
+    expect(cartStub.restoreCart).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps a course out of the basket and hands it back as a link", async () => {
+    const { result } = await resume([
+      { ...productLine(), type: "course", title: "Songwriting", courseSlug: "songwriting" },
+    ]);
+
+    expect(result.current.continueLines.map((line) => line.title)).toEqual(["Songwriting"]);
+    expect(cartStub.restoreCart).not.toHaveBeenCalled();
+    expect(result.current.status).toBe("restored");
+  });
+
+  it("reads as empty when nothing at all survived", async () => {
+    const { result } = await resume([productLine({ available: false, unavailableReason: "removed" })]);
+
+    expect(result.current.status).toBe("empty");
+    expect(cartStub.restoreCart).not.toHaveBeenCalled();
+  });
+});

package/src/ui/headless/checkout/resumedCoupon.ts

@@ -0,0 +1,61 @@
+/**
+ * The discount code a recovery link carried, handed from the resume page to
+ * the checkout page.
+ *
+ * ## Why a stash and not a prop
+ *
+ * The two pages are separate route entries on both rendering stacks and the
+ * buyer walks between them through the ordinary cart, sometimes via the store
+ * in between. Threading the code through would mean a query parameter on every
+ * link the resume page can produce, which puts a discount code in browser
+ * history and in any `Referer` the storefront leaks. `sessionStorage` is
+ * per-tab and dies with the tab.
+ *
+ * ## What it does NOT do
+ *
+ * It does not apply anything. The code is only PREFILLED into the discount
+ * field, so the buyer still presses Apply and the server re-evaluates every
+ * condition (window, caps, membership gate, minimum spend) against today. A
+ * code that has since been switched off is already withheld by the resume
+ * endpoint, so the common failure never reaches here at all.
+ *
+ * Consumed on first read, so a reload of the checkout page a week later does
+ * not prefill a code the buyer has long forgotten. It is remembered for the
+ * rest of the PAGE LOAD in a module variable, and that part is load-bearing
+ * rather than an optimisation: `useCheckout` reads it from a lazy `useState`
+ * initialiser, which React StrictMode deliberately invokes twice in
+ * development. Without the memo the second invocation would find the stash
+ * already emptied and the field would come up blank on exactly the builds a
+ * developer tests against.
+ */
+
+const KEY = "tribenest-resumed-coupon";
+
+/** Undefined until the first read of this page load. */
+let taken: string | undefined;
+
+export function rememberResumedCoupon(code: string | null | undefined): void {
+  taken = undefined;
+  if (typeof window === "undefined") return;
+  try {
+    if (code && code.trim()) window.sessionStorage.setItem(KEY, code.trim());
+    else window.sessionStorage.removeItem(KEY);
+  } catch {
+    // Private-mode Safari and locked-down embeds throw here. A missing prefill
+    // is a smaller problem than a checkout page that fails to mount.
+  }
+}
+
+/** Read and clear. Returns "" when there is nothing waiting. */
+export function takeResumedCoupon(): string {
+  if (taken !== undefined) return taken;
+  if (typeof window === "undefined") return "";
+  try {
+    const value = window.sessionStorage.getItem(KEY) ?? "";
+    if (value) window.sessionStorage.removeItem(KEY);
+    taken = value;
+    return value;
+  } catch {
+    return "";
+  }
+}

package/src/ui/headless/checkout/useCartResume.ts

@@ -0,0 +1,340 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { useCart, type CartItem, type TicketCartItem } from "../../../contexts/CartContext";
+import { useResumeCheckout, type ResumeLine, type ResumedCheckout } from "../../../data/queries/useCheckouts";
+import { rememberResumedCoupon } from "./resumedCoupon";
+import { ProductDeliveryType } from "../../../types/models";
+
+/**
+ * The landing behaviour of a cart-recovery link, shared by both storefronts.
+ *
+ * `apps/client` and a Forge code website draw this page completely differently
+ * (Tailwind against `themeSettings` on one, inline styles against the Forge
+ * theme on the other) and they must not decide DIFFERENTLY what a resumed
+ * basket does. So the exchange, the restore and the arithmetic live here once
+ * and each stack owns only how it looks, exactly as `ticketAvailability` and
+ * `useClaimPassTransfer` already do.
+ *
+ * ## What lands in the basket, and what does not
+ *
+ * Only the lines the server says can still be bought. Every OTHER line is
+ * still returned to the caller in `unavailableLines`, because the two failure
+ * modes here are asymmetric and both are bad:
+ *
+ * - Silently dropping a line is the worst outcome. The buyer came back for the
+ *   thing they left, the basket is quietly one item lighter, and they find out
+ *   after paying (or never).
+ * - Restoring a line nobody will sell them is the second worst. They reach the
+ *   payment screen and are refused, which reads as a broken shop.
+ *
+ * Showing it, greyed out, with the reason next to it is neither.
+ *
+ * ## An add-on never lands without the ticket it hangs off
+ *
+ * A product line carrying `attachedTo` was added from an event's add-on block
+ * and is only sellable next to that event's own ticket line. If the ticket
+ * cannot be restored (sold out, withdrawn) the add-on cannot either: the server
+ * refuses a bundle whose add-on has no base, so restoring it alone builds a
+ * basket that fails at the payment screen with nothing on the page saying why.
+ *
+ * The base has to come from THIS payload, not from whatever is in the basket
+ * already. The buckets below are derived from the server answer alone, so they
+ * cannot change under the page once the restore has run.
+ *
+ * Those add-ons come back in `droppedLines` rather than disappearing, for the
+ * same reason unavailable lines do: a basket that is quietly one item lighter
+ * is the worst of the outcomes above.
+ *
+ * ## Courses and coaching are not basket items
+ *
+ * The cart holds products and event tickets. A course or a coaching session is
+ * bought through its own page, so those lines come back as `continueLines`:
+ * nothing is restored and the caller draws a link back to the page where the
+ * purchase resumes. Reporting them as "restored" would be a lie, and dropping
+ * them would strand the only recovery path those two pillars have.
+ */
+
+// Re-exported so a caller reaches the whole vocabulary from `forge/ui` without
+// also importing the data layer.
+export type {
+  ResumeLine,
+  ResumedCheckout,
+  ResumeLineOption,
+  ResumeLineUnavailableReason,
+} from "../../../data/queries/useCheckouts";
+
+export type CartResumeStatus = "loading" | "restored" | "empty" | "error";
+
+export type UseCartResumeOptions = {
+  /** The `?token=` from the recovery link. Absent or blank means an invalid link. */
+  token?: string | null;
+  /**
+   * Put the basket back as soon as the exchange answers. On by default: the
+   * point of the link is that the buyer arrives with a full basket, not with a
+   * button that promises one.
+   */
+  autoRestore?: boolean;
+};
+
+export type UseCartResumeResult = {
+  status: CartResumeStatus;
+  /** The whole server answer, for a caller that wants a field this hook does not surface. */
+  resumed: ResumedCheckout | null;
+  /** Lines that went back in the basket. */
+  restoredLines: ResumeLine[];
+  /** Lines that could not, each with its `unavailableReason`. Draw these. */
+  unavailableLines: ResumeLine[];
+  /**
+   * Add-ons the shop would still sell, left out because the event ticket they
+   * hang off was not restored. Draw these too: they were in the basket the
+   * buyer left, and they are not in the one they got back.
+   */
+  droppedLines: ResumeLine[];
+  /** Course and coaching lines: not basket items, link the buyer onward. */
+  continueLines: ResumeLine[];
+  /** Restored lines whose price moved while the buyer was away. */
+  repricedLines: ResumeLine[];
+  /** Units restored. */
+  itemCount: number;
+  /** Minor units, restored lines only, at today's prices and before discount. */
+  subtotalCents: number;
+  currency: string;
+  /** A code to re-apply, already stashed for the checkout page. Display it. */
+  couponCode: string | null;
+  /** Set when the link itself failed (missing, expired, another artist's). */
+  error: string | null;
+  /** Restore by hand. A no-op once the basket has been restored. */
+  restore: () => void;
+};
+
+/**
+ * A resumed product line as the cart stores it.
+ *
+ * Exported so the translation can be tested without a DOM: every field here is
+ * one the checkout later branches on, and getting `deliveryType` wrong ships an
+ * order with nowhere to send it.
+ */
+export function resumeLineToCartItem(line: ResumeLine): CartItem | null {
+  if (!line.productId || !line.productVariantId) return null;
+  return {
+    productId: line.productId,
+    productVariantId: line.productVariantId,
+    title: line.title,
+    price: line.price,
+    coverImage: line.coverImage ?? undefined,
+    isGift: !!line.isGift,
+    recipientName: line.recipientName ?? undefined,
+    recipientEmail: line.recipientEmail ?? undefined,
+    recipientMessage: line.recipientMessage ?? undefined,
+    /**
+     * The buyer chose this quantity once; restoring it as 1 would make them
+     * re-count. `canIncreaseQuantity` follows the ordinary shop default so the
+     * cart's stepper behaves as it does for any other line.
+     */
+    quantity: line.quantity,
+    canIncreaseQuantity: true,
+    payWhatYouWant: !!line.payWhatYouWant,
+    options: line.options ?? undefined,
+    /**
+     * Never guessed. Checkout reads shipping-or-not off this field, and a
+     * physical line restored as non-physical means an order arrives with
+     * nowhere to send it. The server always sends it for a line it declared
+     * available; `Digital` here would be a bug upstream, not a default.
+     */
+    deliveryType: line.deliveryType ?? ProductDeliveryType.Digital,
+    attachedTo: line.attachedTo ?? undefined,
+  };
+}
+
+/** Ticket lines regrouped into the per-event shape the cart holds. */
+export function resumeLinesToTicketItems(lines: ResumeLine[]): TicketCartItem[] {
+  const byEvent = new Map<string, TicketCartItem>();
+  for (const line of lines) {
+    if (!line.eventId || !line.ticketId) continue;
+    const existing = byEvent.get(line.eventId) ?? {
+      eventId: line.eventId,
+      eventSlug: line.eventSlug ?? "",
+      eventTitle: line.eventTitle ?? line.title,
+      coverImage: line.coverImage ?? undefined,
+      tickets: {},
+      ticketMeta: {},
+      bookingFee: line.bookingFee ?? null,
+    };
+    existing.tickets[line.ticketId] = (existing.tickets[line.ticketId] ?? 0) + line.quantity;
+    existing.ticketMeta[line.ticketId] = {
+      title: line.title,
+      // On a pay-what-you-want tier the buyer's own amount is what the cart
+      // shows and what the bundle charges, so it wins over the tier's floor.
+      price: line.pwywAmount ?? line.price,
+      ...(line.pwywAmount != null ? { pwywAmount: line.pwywAmount } : {}),
+    };
+    byEvent.set(line.eventId, existing);
+  }
+  return [...byEvent.values()];
+}
+
+const CONTINUE_TYPES = new Set(["course", "coaching"]);
+
+/** The four buckets a resumed payload splits into. */
+export type ResumePartition = {
+  restoredLines: ResumeLine[];
+  unavailableLines: ResumeLine[];
+  continueLines: ResumeLine[];
+  droppedLines: ResumeLine[];
+};
+
+/**
+ * Split the server's lines into what goes back in the basket and what only gets
+ * drawn. Pure, and exported, because this is the decision the whole page rests
+ * on and it must be assertable without a DOM.
+ *
+ * The subtle bucket is `droppedLines`. An add-on is only sellable next to its
+ * base, so a base that is not itself being restored takes the add-on with it.
+ * "Being restored" is checked against the fields `resumeLinesToTicketItems`
+ * actually needs (`eventId` and `ticketId`), so a ticket line that function
+ * would skip does not count as a base either.
+ */
+export function partitionResumeLines(lines: ResumeLine[]): ResumePartition {
+  const unavailableLines = lines.filter((line) => !line.available);
+  const available = lines.filter((line) => line.available);
+  const continueLines = available.filter((line) => CONTINUE_TYPES.has(line.type));
+  const restorable = available.filter((line) => !CONTINUE_TYPES.has(line.type));
+
+  const baseEventIds = new Set(
+    restorable
+      .filter((line) => line.type === "event_ticket" && line.eventId && line.ticketId)
+      .map((line) => line.eventId as string),
+  );
+  const isOrphanedAddon = (line: ResumeLine) =>
+    line.type === "product" &&
+    line.attachedTo?.type === "event" &&
+    !baseEventIds.has(line.attachedTo.entityId);
+
+  return {
+    restoredLines: restorable.filter((line) => !isOrphanedAddon(line)),
+    unavailableLines,
+    continueLines,
+    droppedLines: restorable.filter(isOrphanedAddon),
+  };
+}
+
+/** What this line will actually cost per unit, in minor units. */
+export function effectiveUnitCents(line: ResumeLine): number {
+  return line.pwywAmount != null ? Math.round(line.pwywAmount * 100) : line.unitPriceCents;
+}
+
+export function useCartResume(options: UseCartResumeOptions): UseCartResumeResult {
+  const { token, autoRestore = true } = options;
+  const { restoreCart, isReady } = useCart();
+  const { mutateAsync } = useResumeCheckout();
+
+  const [resumed, setResumed] = useState<ResumedCheckout | null>(null);
+  const [error, setError] = useState<string | null>(null);
+  const [restored, setRestored] = useState(false);
+  /**
+   * One exchange per token. The endpoint stamps the arrival that cart-recovery
+   * attributes on, so firing it twice is not merely wasteful, and StrictMode
+   * runs every effect twice in development.
+   */
+  const requestedFor = useRef<string | null>(null);
+
+  useEffect(() => {
+    const value = (token ?? "").trim();
+    if (!value) {
+      setError("missing_token");
+      return;
+    }
+    if (requestedFor.current === value) return;
+    requestedFor.current = value;
+
+    let cancelled = false;
+    void mutateAsync({ token: value })
+      .then((data) => {
+        if (cancelled) return;
+        setResumed(data);
+        setError(null);
+        // Stashed even when the caller does not auto-restore, so the code
+        // survives the walk from this page to checkout either way.
+        rememberResumedCoupon(data.couponCode);
+      })
+      .catch((err: unknown) => {
+        if (cancelled) return;
+        setError(
+          (err as { response?: { data?: { message?: string } } })?.response?.data?.message ?? "invalid_link",
+        );
+      });
+
+    return () => {
+      cancelled = true;
+    };
+  }, [token, mutateAsync]);
+
+  const { restoredLines, unavailableLines, continueLines, droppedLines } = useMemo(
+    () => partitionResumeLines(resumed?.lines ?? []),
+    [resumed],
+  );
+
+  const repricedLines = useMemo(
+    () => restoredLines.filter((line) => line.priceChanged),
+    [restoredLines],
+  );
+
+  const restore = useCallback(() => {
+    /**
+     * `isReady` is not belt and braces. `CartProvider` hydrates from
+     * localStorage in a mount effect and that effect REPLACES the whole list,
+     * so anything written before it lands is thrown away. The network round
+     * trip makes that practically impossible, and "practically impossible"
+     * silent data loss is the kind that surfaces once, on somebody's phone, and
+     * is never reproduced.
+     */
+    if (!isReady || restored || restoredLines.length === 0) return;
+    restoreCart({
+      items: restoredLines
+        .filter((line) => line.type === "product")
+        .map(resumeLineToCartItem)
+        .filter((item): item is CartItem => item !== null),
+      tickets: resumeLinesToTicketItems(restoredLines.filter((line) => line.type === "event_ticket")),
+    });
+    setRestored(true);
+    /**
+     * `isReady` belongs here. Without it the callback keeps the `false` it
+     * closed over on the first render, React hands the same stale function back
+     * on every later one, and the effect below never re-runs once hydration
+     * finishes: the guard stops being a wait and becomes a permanent refusal on
+     * exactly the slow load it was written for.
+     */
+  }, [isReady, restored, restoredLines, restoreCart]);
+
+  useEffect(() => {
+    if (autoRestore) restore();
+  }, [autoRestore, restore]);
+
+  const status: CartResumeStatus = error
+    ? "error"
+    : !resumed
+      ? "loading"
+      : restoredLines.length === 0 && continueLines.length === 0
+        ? "empty"
+        : "restored";
+
+  return {
+    status,
+    resumed,
+    restoredLines,
+    unavailableLines,
+    continueLines,
+    droppedLines,
+    repricedLines,
+    itemCount: restoredLines.reduce((sum, line) => sum + line.quantity, 0),
+    // The figure the CART will show, so a pay-what-you-want tier counts the
+    // buyer's own amount rather than the tier's floor.
+    subtotalCents: restoredLines.reduce(
+      (sum, line) => sum + effectiveUnitCents(line) * line.quantity,
+      0,
+    ),
+    currency: resumed?.currency ?? "USD",
+    couponCode: resumed?.couponCode ?? null,
+    error,
+    restore,
+  };
+}