@tribe-nest/forge 3.26.0 → 3.31.0

package/src/ui/headless/checkout/_tests/cartResume.spec.ts

@@ -0,0 +1,291 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import {
+  partitionResumeLines,
+  resumeLineToCartItem,
+  resumeLinesToTicketItems,
+  effectiveUnitCents,
+  type ResumeLine,
+} from "../useCartResume";
+import { rememberResumedCoupon, takeResumedCoupon } from "../resumedCoupon";
+import { ProductDeliveryType } from "../../../../types/models";
+
+/**
+ * The translation from a resumed line to a cart line, which is where a recovery
+ * link either restores the basket the buyer left or a subtly different one.
+ *
+ * Pure functions, so these run in the package's existing node environment with
+ * no jsdom and no network.
+ *
+ * The hook AROUND them lives in `useCartResume.spec.tsx`, in jsdom, where the
+ * exchange and the cart are both stubbed: which lines reach `restoreCart`, and
+ * when, is a question effects answer and a pure function cannot. What the two
+ * storefronts then DRAW is `ResumeCart.spec.tsx` here and `resume.spec.tsx` in
+ * `apps/client`. (This docblock previously claimed the hook was covered "end to
+ * end by the backend spec plus the two storefront pages", and none of those
+ * three existed.)
+ */
+
+const productLine = (overrides: Partial<ResumeLine> = {}): ResumeLine => ({
+  type: "product",
+  quantity: 2,
+  title: "Tour Tee",
+  coverImage: "https://cdn.test/tee.jpg",
+  price: 25,
+  unitPriceCents: 2500,
+  quotedUnitPriceCents: 2000,
+  priceChanged: true,
+  available: true,
+  unavailableReason: null,
+  productId: "prod-1",
+  productVariantId: "var-1",
+  deliveryType: ProductDeliveryType.Physical,
+  payWhatYouWant: false,
+  options: [{ axis: "Size", value: "L", swatchHex: null }],
+  isGift: false,
+  ...overrides,
+});
+
+const ticketLine = (overrides: Partial<ResumeLine> = {}): ResumeLine => ({
+  type: "event_ticket",
+  quantity: 3,
+  title: "General Admission",
+  coverImage: null,
+  price: 25,
+  unitPriceCents: 2500,
+  quotedUnitPriceCents: 2500,
+  priceChanged: false,
+  available: true,
+  unavailableReason: null,
+  eventId: "event-1",
+  ticketId: "tier-1",
+  eventSlug: "spring-tour",
+  eventTitle: "Spring Tour",
+  pwywAmount: null,
+  bookingFee: null,
+  ...overrides,
+});
+
+describe("resumeLineToCartItem", () => {
+  it("should carry the delivery type through rather than defaulting it", () => {
+    // The whole reason the payload has the field: a physical line restored as
+    // non-physical means checkout never asks where to send the record, and a
+    // missing address is not recoverable after payment.
+    const item = resumeLineToCartItem(productLine());
+    expect(item?.deliveryType).toBe(ProductDeliveryType.Physical);
+  });
+
+  it("should restore the quantity the buyer chose, not one", () => {
+    expect(resumeLineToCartItem(productLine({ quantity: 4 }))?.quantity).toBe(4);
+  });
+
+  it("should quote today's price, never the one the buyer was shown", () => {
+    const item = resumeLineToCartItem(productLine({ price: 25, quotedUnitPriceCents: 2000 }));
+    expect(item?.price).toBe(25);
+  });
+
+  it("should keep a gift a gift, with its recipient", () => {
+    const item = resumeLineToCartItem(
+      productLine({
+        isGift: true,
+        recipientName: "Ada",
+        recipientEmail: "ada@test.com",
+        recipientMessage: "Happy birthday",
+      }),
+    );
+    expect(item).toMatchObject({
+      isGift: true,
+      recipientName: "Ada",
+      recipientEmail: "ada@test.com",
+      recipientMessage: "Happy birthday",
+    });
+  });
+
+  it("should keep an add-on bound to the event it hangs off", () => {
+    // Without this the rebuilt bundle has an add-on with no base and the server
+    // refuses the whole checkout, with nothing on screen explaining why.
+    const item = resumeLineToCartItem(
+      productLine({ attachedTo: { type: "event", entityId: "event-1" } }),
+    );
+    expect(item?.attachedTo).toEqual({ type: "event", entityId: "event-1" });
+  });
+
+  it("should carry the chosen variant's options so the cart can name it", () => {
+    expect(resumeLineToCartItem(productLine())?.options).toEqual([
+      { axis: "Size", value: "L", swatchHex: null },
+    ]);
+  });
+
+  it("should refuse a line with no variant rather than invent one", () => {
+    expect(resumeLineToCartItem(productLine({ productVariantId: undefined }))).toBeNull();
+    expect(resumeLineToCartItem(productLine({ productId: undefined }))).toBeNull();
+  });
+});
+
+describe("resumeLinesToTicketItems", () => {
+  it("should group tiers of one event into a single selection", () => {
+    const items = resumeLinesToTicketItems([
+      ticketLine({ ticketId: "tier-1", quantity: 2, title: "GA" }),
+      ticketLine({ ticketId: "tier-2", quantity: 1, title: "VIP", price: 80, unitPriceCents: 8000 }),
+    ]);
+
+    expect(items).toHaveLength(1);
+    expect(items[0]).toMatchObject({
+      eventId: "event-1",
+      eventSlug: "spring-tour",
+      eventTitle: "Spring Tour",
+      tickets: { "tier-1": 2, "tier-2": 1 },
+    });
+    expect(items[0].ticketMeta["tier-2"]).toMatchObject({ title: "VIP", price: 80 });
+  });
+
+  it("should keep two events apart", () => {
+    const items = resumeLinesToTicketItems([
+      ticketLine({ eventId: "event-1" }),
+      ticketLine({ eventId: "event-2", eventSlug: "autumn", eventTitle: "Autumn" }),
+    ]);
+    expect(items.map((item) => item.eventId)).toEqual(["event-1", "event-2"]);
+  });
+
+  it("should show a pay-what-you-want tier the buyer's own amount, and send it", () => {
+    // The bundle endpoint treats `price` as display-only and charges
+    // `pwywAmount`. Dropping the second field would silently undercharge to the
+    // tier's floor and still answer 200.
+    const items = resumeLinesToTicketItems([ticketLine({ price: 10, pwywAmount: 42 })]);
+    expect(items[0].ticketMeta["tier-1"]).toMatchObject({ price: 42, pwywAmount: 42 });
+  });
+
+  it("should carry the event's booking fee so the estimate matches the charge", () => {
+    const fee = { feeAmount: 1.5, feeBps: 250, currency: "USD", minorUnitFactor: 100 };
+    expect(resumeLinesToTicketItems([ticketLine({ bookingFee: fee })])[0].bookingFee).toEqual(fee);
+  });
+
+  it("should skip a line with no tier id", () => {
+    expect(resumeLinesToTicketItems([ticketLine({ ticketId: undefined })])).toEqual([]);
+  });
+});
+
+describe("partitionResumeLines", () => {
+  const courseLine = (): ResumeLine => ({
+    ...productLine(),
+    type: "course",
+    title: "Songwriting",
+    courseSlug: "songwriting",
+  });
+
+  it("sends a course onward rather than into the basket", () => {
+    const parts = partitionResumeLines([productLine(), courseLine()]);
+    expect(parts.restoredLines.map((line) => line.title)).toEqual(["Tour Tee"]);
+    expect(parts.continueLines.map((line) => line.title)).toEqual(["Songwriting"]);
+  });
+
+  it("keeps every line the server refused, with its reason intact", () => {
+    const gone = productLine({ available: false, unavailableReason: "removed", title: "Vinyl" });
+    const parts = partitionResumeLines([productLine(), gone]);
+    expect(parts.unavailableLines).toEqual([gone]);
+    expect(parts.restoredLines.map((line) => line.title)).toEqual(["Tour Tee"]);
+  });
+
+  it("REGRESSION: drops an add-on whose base ticket is not being restored", () => {
+    // The server refuses a bundle whose add-on has no base, so restoring it
+    // alone builds a basket that can only fail at the payment screen.
+    const poster = productLine({
+      title: "Tour poster",
+      attachedTo: { type: "event", entityId: "event-1" },
+    });
+    const parts = partitionResumeLines([
+      ticketLine({ available: false, unavailableReason: "sold_out" }),
+      poster,
+    ]);
+
+    expect(parts.restoredLines).toEqual([]);
+    expect(parts.droppedLines).toEqual([poster]);
+  });
+
+  it("keeps the add-on when its base ticket is restored", () => {
+    const poster = productLine({ attachedTo: { type: "event", entityId: "event-1" } });
+    const parts = partitionResumeLines([ticketLine(), poster]);
+    expect(parts.droppedLines).toEqual([]);
+    expect(parts.restoredLines).toContain(poster);
+  });
+
+  it("counts only the event the add-on names as its base", () => {
+    const poster = productLine({ attachedTo: { type: "event", entityId: "event-2" } });
+    const parts = partitionResumeLines([ticketLine({ eventId: "event-1" }), poster]);
+    expect(parts.droppedLines).toEqual([poster]);
+  });
+
+  it("does not accept a ticket line the cart would skip as a base", () => {
+    // `resumeLinesToTicketItems` needs both ids and silently skips a line
+    // missing either, so such a line is not a base that will exist.
+    const poster = productLine({ attachedTo: { type: "event", entityId: "event-1" } });
+    const parts = partitionResumeLines([ticketLine({ ticketId: undefined }), poster]);
+    expect(parts.droppedLines).toEqual([poster]);
+  });
+
+  it("leaves a product attached to nothing alone", () => {
+    // Attachment describes how a line was ADDED, not what the product is: the
+    // same poster bought from the shop sells on its own as always.
+    const parts = partitionResumeLines([productLine({ attachedTo: null })]);
+    expect(parts.droppedLines).toEqual([]);
+    expect(parts.restoredLines).toHaveLength(1);
+  });
+});
+
+describe("effectiveUnitCents", () => {
+  it("should use the catalogue price when nothing was chosen", () => {
+    expect(effectiveUnitCents(ticketLine())).toBe(2500);
+  });
+
+  it("should use the chosen amount on a pay-what-you-want tier", () => {
+    expect(effectiveUnitCents(ticketLine({ pwywAmount: 42 }))).toBe(4200);
+  });
+
+  it("should treat a chosen zero as a choice, not as absent", () => {
+    expect(effectiveUnitCents(ticketLine({ pwywAmount: 0 }))).toBe(0);
+  });
+});
+
+describe("the resumed coupon stash", () => {
+  const store = new Map<string, string>();
+
+  beforeEach(() => {
+    store.clear();
+    (globalThis as { window?: unknown }).window = {
+      sessionStorage: {
+        getItem: (key: string) => store.get(key) ?? null,
+        setItem: (key: string, value: string) => void store.set(key, value),
+        removeItem: (key: string) => void store.delete(key),
+      },
+    };
+    rememberResumedCoupon(null);
+  });
+
+  afterEach(() => {
+    delete (globalThis as { window?: unknown }).window;
+  });
+
+  it("should hand the code to the checkout page once", () => {
+    rememberResumedCoupon("SUMMER10");
+    expect(takeResumedCoupon()).toBe("SUMMER10");
+    expect(store.has("tribenest-resumed-coupon")).toBe(false);
+  });
+
+  it("should survive a second read in the same page load", () => {
+    // React StrictMode invokes a lazy `useState` initialiser twice in
+    // development. Without the memo the field would come up blank on exactly
+    // the builds a developer tests against.
+    rememberResumedCoupon("SUMMER10");
+    expect(takeResumedCoupon()).toBe("SUMMER10");
+    expect(takeResumedCoupon()).toBe("SUMMER10");
+  });
+
+  it("should answer empty when no link was followed", () => {
+    expect(takeResumedCoupon()).toBe("");
+  });
+
+  it("should forget a code when the next resume carries none", () => {
+    rememberResumedCoupon("SUMMER10");
+    rememberResumedCoupon(null);
+    expect(takeResumedCoupon()).toBe("");
+  });
+});

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 "";
+  }
+}