@tribe-nest/forge 3.21.0 → 3.22.0

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

@@ -0,0 +1,83 @@
+/**
+ * The inventory hold, as a buyer experiences it.
+ *
+ * The server reserves stock while a buyer is on the card form and reports when
+ * that reservation lapses (`holdExpiresAt`, ISO-8601, on every checkout-create
+ * and every `start-payment` response). When it lapses before the payment lands,
+ * `start-payment` answers **409 `INVENTORY_HOLD_EXPIRED`** — deliberately NOT
+ * the sold-out error, because "your reservation ran out" and "there are none
+ * left" lead the buyer to different next actions and only the first one has a
+ * retry that works.
+ *
+ * None of that was rendered anywhere. This module is the shared, provider-free
+ * half of rendering it, so both stacks (the client PWA and Forge's own styled
+ * drop-ins) count the same clock and read the same error.
+ *
+ * Everything here is pure — no React, no provider tree — so it is unit-testable
+ * on its own, the same reason `bundleCoupon.ts` sits beside it.
+ */
+
+/** The machine-readable code the API stamps on an expired-hold refusal. */
+export const HOLD_EXPIRED_CODE = "INVENTORY_HOLD_EXPIRED";
+
+type MaybeApiError = {
+  response?: { status?: number; data?: { code?: string; message?: string } };
+};
+
+/**
+ * Is this failure "your reservation lapsed" rather than anything else?
+ *
+ * Switches on `code`, never on prose and never on the bare 409 — a 409 alone is
+ * a generic conflict a future endpoint could reuse, and treating one as an
+ * expired hold would offer a retry that cannot help.
+ */
+export function isHoldExpiredError(error: unknown): boolean {
+  return (error as MaybeApiError)?.response?.data?.code === HOLD_EXPIRED_CODE;
+}
+
+/**
+ * The API's own words for a lapsed hold, already localised server-side
+ * (`errors.order.hold_expired` / `errors.event.hold_expired`).
+ *
+ * The fallback is only reached if the response carried no message at all; it is
+ * never used to *replace* the server's message, which is the one that names the
+ * right noun ("basket" vs "tickets").
+ */
+export function holdExpiredMessage(error: unknown, fallback: string): string {
+  return (error as MaybeApiError)?.response?.data?.message || fallback;
+}
+
+/**
+ * Milliseconds until the hold lapses, or `null` when there is no hold.
+ *
+ * `null` and `0` are different facts and the UI must not conflate them:
+ * `holdExpiresAt` is absent for a free/already-settled order and for every
+ * profile with the holds switch off, and inventing a countdown there would
+ * promise a reservation nobody took. Zero means a real hold that has run out.
+ *
+ * Clamped at zero so a stale or clock-skewed instant reads as lapsed rather
+ * than as a negative timer.
+ */
+export function holdMsRemaining(holdExpiresAt: string | null | undefined, now: number): number | null {
+  if (!holdExpiresAt) return null;
+  const ms = Date.parse(holdExpiresAt);
+  if (Number.isNaN(ms)) return null;
+  return Math.max(0, ms - now);
+}
+
+/**
+ * `m:ss` for the countdown, and `h:mm:ss` above an hour.
+ *
+ * Rounds UP, so a hold with 1ms left reads "0:01" and the timer only shows
+ * "0:00" at the instant it is genuinely over — a countdown that sits on zero
+ * for a whole second while payment is still accepted is a small lie the buyer
+ * acts on.
+ */
+export function formatHoldRemaining(msRemaining: number): string {
+  const total = Math.ceil(Math.max(0, msRemaining) / 1000);
+  const seconds = total % 60;
+  const minutes = Math.floor(total / 60) % 60;
+  const hours = Math.floor(total / 3600);
+  const mm = hours > 0 ? String(minutes).padStart(2, "0") : String(minutes);
+  return `${hours > 0 ? `${hours}:` : ""}${mm}:${String(seconds).padStart(2, "0")}`;
+}

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

@@ -18,6 +18,8 @@ import {
   type ApplyCheckoutCouponResult,
 } from "../../../data/queries/useCheckouts";
 import { bundleCouponSummary, bundleReturnUrl } from "./bundleCoupon";
+import { holdExpiredMessage, isHoldExpiredError } from "./inventoryHold";
+import { useInventoryHold } from "./useInventoryHold";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
 import { ProductDeliveryType, PaymentProviderName, type ApiError, type PublicTaxQuote } from "../../../types/models";
@@ -289,6 +291,58 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
 
   const orderId = created?.orderId ?? null;
 
+  // ── Inventory hold ──────────────────────────────────────────────────────────
+  /**
+   * The reservation clock the buyer is counting down.
+   *
+   * `start-payment` RESTARTS the hold and reports the new instant, so its figure
+   * supersedes the one `createOrder` returned — that one was measured before the
+   * buyer had even seen a payment field. The create-time value bridges the
+   * moment in between, which for a slow `start-payment` is the whole of the
+   * buyer's first impression of the page.
+   *
+   * A bundle has no create-time figure at all (`POST /public/checkouts` takes
+   * the holds but does not report a window), so it is start-payment or nothing —
+   * which is fine, because a bundle always starts payment immediately.
+   *
+   * `undefined` on an older API and `null` whenever no hold was taken; both mean
+   * "render nothing", which is exactly today's behaviour.
+   */
+  const holdExpiresAt = flow.result?.holdExpiresAt ?? created?.holdExpiresAt ?? null;
+  const hold = useInventoryHold(holdExpiresAt);
+
+  /**
+   * The reservation ran out before the payment landed (409
+   * `INVENTORY_HOLD_EXPIRED`), which is NOT sold-out — the items may well still
+   * be there, and re-running `start-payment` re-acquires the very same units
+   * when they are. Told apart from every other start failure so the buyer is
+   * offered the retry that actually works instead of a dead end.
+   */
+  const isHoldExpired = isHoldExpiredError(flow.error);
+  const holdExpiredError = isHoldExpired
+    ? holdExpiredMessage(flow.error, "Your basket reservation expired before payment finished. Please try again.")
+    : "";
+
+  /**
+   * Take the reservation again on the SAME order or bundle.
+   *
+   * The cheapest recovery there is: nothing about the cart has changed, so if
+   * the units are still free the buyer gets a fresh window and the card form
+   * they were already looking at. If they are genuinely gone, another 409 says
+   * so — and that is the point at which "change your selection" is the honest
+   * next step, not before.
+   */
+  const retryHold = useCallback(async () => {
+    if (!created?.orderId && !checkoutId) return;
+    try {
+      await flow.start();
+    } catch {
+      // The refusal is already on `flow.error`; a rethrow here would only turn a
+      // handled state into an unhandled rejection.
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [created?.orderId, checkoutId]);
+
   // A coupon re-issues the payment intent, so its update supersedes the initial
   // start-payment result. Otherwise use the started payment once both the order
   // and start-payment have resolved.
@@ -589,6 +643,24 @@ export function useCheckout(opts: UseCheckoutOptions = {}) {
     ticketItems,
     isCreatingOrder: createOrder.isPending || flow.isStarting,
     startError,
+    // ── Inventory hold ─────────────────────────────────────────────────────────
+    /**
+     * The live reservation: `isHeld` + `label` while it runs, `hasLapsed` once
+     * the clock hits zero. Every field is null/false when no hold was taken, so
+     * a surface guarding on `isHeld || hasLapsed` is unchanged for the profiles
+     * that have holds switched off.
+     */
+    hold,
+    /**
+     * The server said the reservation expired (409 `INVENTORY_HOLD_EXPIRED`) —
+     * its own words, already localised. Empty for every other failure, so this
+     * can never be mistaken for sold-out.
+     */
+    holdExpiredError,
+    isHoldExpired,
+    /** Re-take the reservation on the same order/bundle. See `retryHold`. */
+    retryHold,
+    isRetryingHold: flow.isStarting,
     provider,
     isPaystack: provider === PaymentProviderName.Paystack,
     paymentSecret: effectivePayment?.paymentSecret,

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

@@ -0,0 +1,104 @@
+import { useEffect, useRef, useState } from "react";
+import { formatHoldRemaining, holdMsRemaining } from "./inventoryHold";
+
+export interface InventoryHoldState {
+  /**
+   * True only while a real reservation is running. False both when there is no
+   * hold at all and once one has run out — the two are told apart by
+   * `hasLapsed`, and no surface should draw a timer off this alone.
+   */
+  isHeld: boolean;
+  /** True when a hold existed and its clock reached zero on this device. */
+  hasLapsed: boolean;
+  /** The instant the API reported, unchanged; `null` when no hold was taken. */
+  expiresAt: string | null;
+  /** Milliseconds left, or `null` when there is no hold. */
+  msRemaining: number | null;
+  /** Whole seconds left, or `null` when there is no hold. */
+  secondsRemaining: number | null;
+  /** `m:ss` (or `h:mm:ss`) for display; `null` when there is nothing to count. */
+  label: string | null;
+  /** Under two minutes — the point at which a surface should stop being subtle. */
+  isUrgent: boolean;
+}
+
+export interface UseInventoryHoldOptions {
+  /**
+   * Fired once, when a running clock reaches zero. For telling a flow to stop
+   * describing the reservation as live; NOT for tearing the payment form down.
+   */
+  onLapse?: () => void;
+  /** Tick interval, ms. Only for tests — a second is what a countdown means. */
+  intervalMs?: number;
+}
+
+/**
+ * Count down an inventory hold.
+ *
+ * ## What it does at zero, and why
+ *
+ * It stops, and it flips `hasLapsed`. A timer that reaches 0:00 and then keeps
+ * sitting there is worse than no timer: it has told the buyer something has
+ * happened and then refuses to say what. So the honest end state is a *changed
+ * statement* — "your reservation has ended" — which the calling surface renders
+ * in place of the clock, with the same recovery action a 409 gets.
+ *
+ * It deliberately does **not** hide or disable the payment form. This clock is
+ * the buyer's device clock against an instant the server chose; it can be
+ * skewed, and the server may still accept the payment (`start-payment`
+ * re-acquires the same units when they are still free). Refusing a charge the
+ * server would have taken loses a real sale to defend a display detail. The
+ * authority stays where it belongs — the 409, when it comes.
+ *
+ * ## Degrading to today's behaviour
+ *
+ * Holds are behind a per-profile switch that most profiles have off, and a free
+ * or already-settled order never carries one either. In all of those cases
+ * `holdExpiresAt` is `null`/absent, every field here is null/false, and a
+ * surface that guards on `isHeld || hasLapsed` renders exactly what it renders
+ * today.
+ */
+export function useInventoryHold(
+  holdExpiresAt: string | null | undefined,
+  opts: UseInventoryHoldOptions = {},
+): InventoryHoldState {
+  const { onLapse, intervalMs = 1000 } = opts;
+  const [msRemaining, setMsRemaining] = useState<number | null>(() => holdMsRemaining(holdExpiresAt, Date.now()));
+  // Keeps the callback out of the effect's dependencies, so an inline arrow
+  // from the caller does not restart the interval on every render.
+  const onLapseRef = useRef(onLapse);
+  onLapseRef.current = onLapse;
+
+  useEffect(() => {
+    const initial = holdMsRemaining(holdExpiresAt, Date.now());
+    setMsRemaining(initial);
+    // No hold, or one that was already over when we first saw it (a resumed tab,
+    // a skewed clock): nothing to tick. The already-over case still reports
+    // `hasLapsed` below — it just never animated down to it.
+    if (initial === null || initial <= 0) return;
+
+    const id = setInterval(() => {
+      const next = holdMsRemaining(holdExpiresAt, Date.now());
+      setMsRemaining(next);
+      if (next !== null && next <= 0) {
+        clearInterval(id);
+        onLapseRef.current?.();
+      }
+    }, intervalMs);
+    return () => clearInterval(id);
+  }, [holdExpiresAt, intervalMs]);
+
+  const hasHold = msRemaining !== null;
+  const hasLapsed = hasHold && msRemaining <= 0;
+  const isHeld = hasHold && msRemaining > 0;
+
+  return {
+    isHeld,
+    hasLapsed,
+    expiresAt: holdExpiresAt ?? null,
+    msRemaining,
+    secondsRemaining: hasHold ? Math.ceil(msRemaining / 1000) : null,
+    label: isHeld ? formatHoldRemaining(msRemaining) : null,
+    isUrgent: isHeld && msRemaining <= 120_000,
+  };
+}

package/src/ui/headless/event/useEventCheckout.ts

@@ -1,11 +1,24 @@
 import { useMemo, useState } from "react";
 import { usePublicAuth } from "../../../contexts/PublicAuthContext";
 import { useCart } from "../../../contexts/CartContext";
-import { useEvent, useCreateEventOrder } from "../../../data/queries/useEvents";
+import { useCreateEventOrder } from "../../../data/queries/useEvents";
 import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
 import { useCouponField } from "../coupon/useCouponField";
+import { usePresaleCode } from "./usePresaleCode";
+import {
+  buildAttendeeSlots,
+  setAttendeeName,
+  validateAttendeeNames,
+  attendeesPayload,
+  collectsAttendees,
+  buyerFullName,
+  type AttendeeNames,
+} from "../../format/attendees";
+import { holdExpiredMessage, isHoldExpiredError } from "../checkout/inventoryHold";
+import { useInventoryHold } from "../checkout/useInventoryHold";
 import { computeBookingFeeAmount } from "../../format/bookingFee";
 import { isPayWhatYouWant, pwywDefaultAmount, resolveUnitPrice, ticketSubtotals } from "../../format/pwyw";
+import { parseMembershipGateError, type MembershipGateRefusal } from "../../format/membershipGate";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
 
@@ -36,7 +49,13 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
   const { setTickets, hasTicketsFor } = useCart();
   // The detail is resolved by slug; the order is created against the real event
   // id (the orders endpoint looks the event up by id, not slug).
-  const { data: event, isLoading } = useEvent(slug);
+  // Read THROUGH the presale field rather than calling `useEvent` directly: it
+  // is the same React Query entry, but it is the one fetched with whatever
+  // presale code this buyer has applied, so `event.tickets` already contains the
+  // tiers that code unlocked. Calling `useEvent(slug)` here instead would give a
+  // tier list that silently omits what the buyer just unlocked access to.
+  const presale = usePresaleCode(slug);
+  const { event, isLoading } = presale;
   const eventId = event?.id;
   const createOrder = useCreateEventOrder(eventId);
   const flow = usePaymentFlow({ path: `/public/events/${eventId}/start-payment`, autoStart: false });
@@ -53,8 +72,31 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
   const [lastName, setLastName] = useState(user?.lastName ?? "");
   const [email, setEmail] = useState(user?.email ?? "");
   const [questionnaire, setQuestionnaire] = useState<unknown>(undefined);
+  /**
+   * ticketId → per-seat names, positional.
+   *
+   * `collectAttendeeDetails` is an event setting an artist turns on for a
+   * guest-list show. It shipped with an admin toggle, a backend that accepts a
+   * per-ticket attendees map, and NO storefront asking for anything — so every
+   * pass printed the buyer's name and the door list was wrong, with nothing
+   * explaining why the setting did nothing. Both stacks render this component,
+   * so collecting it here is what makes the toggle real.
+   */
+  const [attendeeNames, setAttendeeNames] = useState<AttendeeNames>({});
   const [returnUrl, setReturnUrl] = useState("");
   const [error, setError] = useState<string | null>(null);
+  /**
+   * A `MEMBERSHIP_GATE` refusal, STRUCTURED — which tier, and whether the buyer
+   * needs to sign in or to join.
+   *
+   * The gate should have been visible on the tier long before this (the read
+   * announces it), so reaching here means either the buyer's membership lapsed
+   * mid-checkout or the page rendered from a stale cache. Either way the useful
+   * response is the badge's: name the tier and offer the way in. Kept as state
+   * rather than a message because a sentence alone turns a silent failure into a
+   * visible dead end.
+   */
+  const [gateRefusal, setGateRefusal] = useState<MembershipGateRefusal | null>(null);
   /**
    * The booking fee the SERVER charged, once an order exists.
    *
@@ -232,6 +274,7 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
 
   const continueToPayment = async () => {
     setError(null);
+    setGateRefusal(null);
     if (!slug || !eventId) return;
     if (!firstName.trim() || !lastName.trim() || !/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
       setError("Please enter your name and a valid email.");
@@ -247,7 +290,17 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
         firstName,
         lastName,
         questionnaire,
+        // Omitted entirely when the event does not collect them, so an ordinary
+        // purchase posts the body it always did.
+        ...(attendeesPayload(attendeeSlots) ? { attendees: attendeesPayload(attendeeSlots) } : {}),
         couponCode: coupon.submittedCode,
+        // The presale code, not a discount. The sell guard re-checks it on the
+        // ORDER, so it has to travel with the purchase and not just with the
+        // read that revealed the tier — otherwise a buyer unlocks a presale,
+        // fills in their details, and is refused at the card step for want of
+        // the code they already typed. Omitted when there is none, so an
+        // ordinary purchase posts the body it always did.
+        ...(presale.code ? { accessCode: presale.code } : {}),
         attributionRefId: readAttributionRef() ?? undefined,
         ...(readLanding() ?? {}),
       });
@@ -279,10 +332,36 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
       if (result.provider && result.provider !== "stripe") return; // Paystack redirected
       setStep("payment");
     } catch (e) {
+      /**
+       * A members-only tier the buyer cannot have. Checked BEFORE the coupon
+       * branch: a buyer who happened to type a discount code would otherwise be
+       * told the CODE was refused and sent to fix a code that was never the
+       * problem.
+       */
+      const gate = parseMembershipGateError(e);
+      if (gate) {
+        setGateRefusal(gate);
+        return;
+      }
       // A refused code fails the whole request, so with one entered the message
       // belongs next to the field the buyer just used. The message is the API's
       // own — "This coupon has expired", "…does not reach this coupon's minimum
       // spend" — never a house "invalid code" that hides which it was.
+      /**
+       * The reservation lapsed mid-payment (409 `INVENTORY_HOLD_EXPIRED`) —
+       * NOT sold out, and emphatically not a bad coupon. Checked before the
+       * coupon branch for the same reason the gate is: a buyer who happened to
+       * type a discount code would otherwise be sent to fix a code that was
+       * never the problem, while the one action that works — retry — is not
+       * offered at all.
+       *
+       * Event ticket holds are taken UNCONDITIONALLY (no feature switch), so
+       * unlike the product cart this path is live for every profile.
+       */
+      if (isHoldExpiredError(e)) {
+        setError(holdExpiredMessage(e, "Your ticket reservation expired before payment finished. Please try again."));
+        return;
+      }
       if (coupon.submittedCode) coupon.fail(e);
       else setError(errMessage(e));
     }
@@ -306,9 +385,47 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     setStep("details");
   };
 
+  /**
+   * One slot per seat, in cart order, with the buyer pre-filled into the first.
+   * Empty when the event does not ask — so a normal event renders and posts
+   * exactly what it always did.
+   */
+  /**
+   * The reservation clock. `undefined` on an older API and `null` when no hold
+   * was taken or the order is already paid — both render nothing, i.e. exactly
+   * the behaviour before holds existed.
+   */
+  const holdExpiresAt = (flow.result as { holdExpiresAt?: string | null } | undefined)?.holdExpiresAt ?? null;
+  const hold = useInventoryHold(holdExpiresAt);
+
+  const attendeeSlots = useMemo(
+    () =>
+      collectsAttendees(event)
+        ? buildAttendeeSlots({
+            tickets: (event?.tickets ?? []).filter((t) => (selectedTickets[t.id] ?? 0) > 0),
+            quantities: selectedTickets,
+            names: attendeeNames,
+            buyerName: buyerFullName({ firstName, lastName }),
+          })
+        : [],
+    [event, selectedTickets, attendeeNames, firstName, lastName],
+  );
+
+  const attendeeCheck = useMemo(() => validateAttendeeNames(attendeeSlots), [attendeeSlots]);
+
+  const setAttendee = (ticketId: string, index: number, value: string) =>
+    setAttendeeNames((prev) => setAttendeeName(prev, ticketId, index, value));
+
   return {
     event,
     isLoading,
+    /** Countdown on the ticket reservation. `active:false` when there is none. */
+    hold,
+    /** Per-seat name inputs. Empty array when the event does not collect them. */
+    attendeeSlots,
+    setAttendee,
+    /** `{ok:false}` while a required seat name is missing or too long. */
+    attendeeCheck,
     step,
     setStep,
     selectedTickets,
@@ -354,6 +471,12 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     /** Discount code state + the server's quote. See `useCouponField`. */
     coupon,
     clearCoupon,
+    /**
+     * Presale-code state (1.2) — a DIFFERENT code from `coupon`: it buys access
+     * to a tier, it does not change a price. `presale.visible` is false on every
+     * event without a coded tier, so a surface can render it unconditionally.
+     */
+    presale,
     /** Authoritative sales-tax quote from start-payment (display only). */
     taxQuote: flow.result?.taxQuote ?? null,
     firstName,
@@ -373,5 +496,13 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     returnUrl,
     isProcessing: createOrder.isPending || flow.isStarting,
     error,
+    /**
+     * A `MEMBERSHIP_GATE` refusal, structured — pass it to
+     * `<MembershipGateNotice refusal={…}>` (or `useMembershipGateNotice`) rather
+     * than printing `error`, which is deliberately NOT set for this case: the
+     * buyer needs the tier's name and a way in, and a generic red line gives
+     * them neither.
+     */
+    gateRefusal,
   };
 }

package/src/ui/headless/event/usePresaleCode.ts

@@ -0,0 +1,181 @@
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
+import type { IEvent } from "../../../types/models";
+import { useEvent } from "../../../data/queries/useEvents";
+import {
+  readPresaleCode,
+  readPresaleCodeFromUrl,
+  subscribePresaleCode,
+  writePresaleCode,
+} from "../../../utils/presaleCode";
+
+export type PresaleCodeStatus = "idle" | "checking" | "accepted" | "rejected";
+
+export interface UsePresaleCodeOptions {
+  /**
+   * The event as a route loader already fetched it (uncoded). Seeds the read so
+   * a server-rendered page paints without a spinner, exactly as
+   * `useEvent`'s own `initialData` does.
+   */
+  initialEvent?: IEvent;
+}
+
+export interface PresaleCodeField {
+  /**
+   * The event AS THIS BUYER MAY SEE IT — refetched with the applied code, so
+   * `tickets` already contains whatever that code unlocked.
+   *
+   * Read this rather than calling `useEvent` separately; both resolve to the
+   * same React Query entry, but only this one is guaranteed to be the coded
+   * read.
+   */
+  event?: IEvent;
+  isLoading: boolean;
+  /**
+   * Render a code box at all?
+   *
+   * FALSE for every event with no presale — which is nearly all of them, and
+   * the reason this is a server fact rather than "always show it". A box on an
+   * event with no coded tier sends the buyer hunting for a code that does not
+   * exist.
+   */
+  visible: boolean;
+  /** The text in the input — the applied code until the buyer edits it. */
+  input: string;
+  setInput: (value: string) => void;
+  /**
+   * The code currently APPLIED: what the event above was fetched with, and what
+   * the order must carry. `null` until one is submitted.
+   */
+  code: string | null;
+  status: PresaleCodeStatus;
+  /**
+   * The message to put under the field, or `null` for none.
+   *
+   * A refusal names no tier and confirms no guess: the buyer learns their code
+   * is not one for this event and nothing else, or the box becomes a way to
+   * enumerate codes.
+   */
+  message: string | null;
+  /** Apply what is in the input. No-op on an empty field. */
+  submit: () => void;
+  /** Drop the applied code — re-hides whatever it revealed. */
+  clear: () => void;
+  /** Whether the applied code opened something. */
+  isUnlocked: boolean;
+}
+
+/**
+ * The presale-code entry on an event page (Events 1.2).
+ *
+ * ## The gap this closes
+ *
+ * 1.2 shipped hidden tiers, an access-code column, SQL that reveals a tier to
+ * the right code, and a sell guard that enforces it at checkout — and no
+ * storefront on either rendering stack had an input. An artist could author a
+ * presale and mail the code to their list, and the recipient had nowhere to put
+ * it. The feature was unreachable by the only person it is for.
+ *
+ * ## Two facts, both of which have to come from the server
+ *
+ * `presale.hasCodedTiers` decides whether the box exists. A client cannot work
+ * it out: a hidden tier is filtered out of the response, so a presale-only
+ * event is indistinguishable from an event with no tickets yet.
+ *
+ * `presale.codeAccepted` decides what the box SAYS. Diffing the tier list
+ * before and after would look like it works and then fail on the case that
+ * matters — a tier that is VISIBLE but code-gated is already listed, so the
+ * correct code changes nothing on screen and the diff would call it wrong.
+ *
+ * ## Persistence
+ *
+ * The applied code is stored per event in `sessionStorage` (see
+ * `utils/presaleCode`), so it survives the reload, the payment redirect and the
+ * back button, and so the page and the ticket modal — separate components each
+ * with their own `useEvent` — always agree on it. Without that, a buyer unlocks
+ * a tier, walks to checkout, and the order is refused for want of the code they
+ * already typed. `?accessCode=` on the URL seeds it once, which is what makes a
+ * mailed presale link work on arrival.
+ *
+ * ```tsx
+ * const presale = usePresaleCode(slug);
+ * // presale.event already has the unlocked tiers in it
+ * ```
+ */
+export function usePresaleCode(eventKey?: string, options: UsePresaleCodeOptions = {}): PresaleCodeField {
+  const key = eventKey ?? "";
+
+  const code = useSyncExternalStore(
+    subscribePresaleCode,
+    () => readPresaleCode(key),
+    // Server render: no storage, so nothing is applied. The first client render
+    // picks up a stored code and refetches with it.
+    () => null,
+  );
+
+  /** `null` = untouched, so the field shows the applied code until it is edited. */
+  const [draft, setDraft] = useState<string | null>(null);
+
+  // A mailed presale link lands with the code already on it. Seeded once, and
+  // never over an applied code — a buyer who cleared one did so on purpose.
+  useEffect(() => {
+    if (!key || readPresaleCode(key)) return;
+    const fromUrl = readPresaleCodeFromUrl();
+    if (fromUrl) writePresaleCode(key, fromUrl);
+  }, [key]);
+
+  const { data: event, isLoading, isFetching } = useEvent(eventKey, {
+    accessCode: code,
+    initialData: options.initialEvent,
+  });
+
+  const presale = event?.presale;
+
+  // While a newly applied code is in flight the event on hand is still the
+  // PREVIOUS response (kept deliberately, so the page does not blank), and its
+  // verdict describes the old code. Reporting it would flash "not valid" at a
+  // buyer whose code is about to be accepted.
+  //
+  // `!presale` is an API that does not report presale state at all (an older
+  // deployment, or the list endpoint's shape). Silence, not a spinner that
+  // never resolves.
+  const status: PresaleCodeStatus = !code || !presale
+    ? "idle"
+    : isFetching || presale.codeAccepted === null
+      ? "checking"
+      : presale.codeAccepted
+        ? "accepted"
+        : "rejected";
+
+  const submit = useCallback(() => {
+    const trimmed = (draft ?? "").trim();
+    if (!trimmed || !key) return;
+    writePresaleCode(key, trimmed);
+  }, [draft, key]);
+
+  const clear = useCallback(() => {
+    if (!key) return;
+    setDraft("");
+    writePresaleCode(key, null);
+  }, [key]);
+
+  return {
+    event,
+    isLoading,
+    visible: !!presale?.hasCodedTiers,
+    input: draft ?? code ?? "",
+    setInput: setDraft,
+    code,
+    status,
+    message:
+      status === "accepted"
+        ? "Code applied."
+        : // Says only that the code is not one for this event. Naming a tier, or
+          // hinting that one exists, would turn the box into a way to guess codes.
+          status === "rejected"
+          ? "That code isn't valid for this event."
+          : null,
+    submit,
+    clear,
+    isUnlocked: status === "accepted",
+  };
+}