@tribe-nest/forge 3.20.0 → 3.22.0

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

package/src/ui/headless/index.ts

@@ -4,6 +4,11 @@ export * from "./dialog";
 export * from "./donation";
 export * from "./offer";
 export { MembershipGate, type MembershipGateProps, type MembershipGateState } from "./membership/MembershipGate";
+// S.4 members-only gates: the notice a storefront draws BEFORE the buyer pays.
+export {
+  useMembershipGateNotice,
+  type UseMembershipGateNoticeInput,
+} from "./membership/useMembershipGateNotice";
 export { useEmailListForm, type UseEmailListFormOptions, type FormStatus } from "./forms/useEmailListForm";
 export { useContactForm } from "./forms/useContactForm";
 export { useSectionedForm } from "./forms/useSectionedForm";
@@ -17,12 +22,32 @@ export {
   type CheckoutShippingData,
   type SelectedShippingRate,
 } from "./checkout/useCheckout";
+// Inventory holds — the reservation a buyer is given while they pay, and the
+// 409 they get when it lapses. Shared by both rendering stacks.
+export {
+  useInventoryHold,
+  type InventoryHoldState,
+  type UseInventoryHoldOptions,
+} from "./checkout/useInventoryHold";
+export {
+  isHoldExpiredError,
+  holdExpiredMessage,
+  holdMsRemaining,
+  formatHoldRemaining,
+  HOLD_EXPIRED_CODE,
+} from "./checkout/inventoryHold";
 export { useLoginFlow, type LoginStep } from "./auth/useLoginFlow";
 export { useSignupForm, type UseSignupFormOptions } from "./auth/useSignupForm";
 
 // Flow primitives (Part A2) — multi-step purchase/booking/subscribe/chat flows,
 // each composed from the data hooks so a creator can rebuild any page.
 export { useEventCheckout, type UseEventCheckoutOptions, type EventCheckoutStep } from "./event/useEventCheckout";
+export {
+  usePresaleCode,
+  type PresaleCodeField,
+  type PresaleCodeStatus,
+  type UsePresaleCodeOptions,
+} from "./event/usePresaleCode";
 export {
   useCouponField,
   apiErrorMessage,

package/src/ui/headless/membership/useMembershipGateNotice.ts

@@ -0,0 +1,83 @@
+import { useMemo } from "react";
+import type { PublicMembershipGate } from "../../../types/models";
+import { useGetMembershipTiers } from "../../../data/queries/useMembership";
+import {
+  buildMembershipGateNotice,
+  isMembershipGateLocked,
+  type MembershipGateNotice,
+  type MembershipGateRefusal,
+} from "../../format/membershipGate";
+
+export interface UseMembershipGateNoticeInput {
+  /** The gate announced by the read (`ticket.membershipGate`, `product.membershipGate`, …). */
+  gate?: PublicMembershipGate | null;
+  /** A `MEMBERSHIP_GATE` refusal from a failed purchase. Wins over `gate`. */
+  refusal?: MembershipGateRefusal | null;
+  /** What the thing is, in the buyer's words — "This ticket", "This course". */
+  itemLabel?: string;
+  /** Where a signed-out visitor signs in. Code sites mount theirs under `/i`. */
+  loginPath?: string;
+  /** Where a signed-in non-member goes to join — the tier listing. */
+  membershipPath?: string;
+}
+
+/**
+ * The members-only notice for one gated thing, tier names and all.
+ *
+ * ## Why the names are fetched here and not sent by the API
+ *
+ * A gate comes down as `requiredTierIds`, and "you need tier 8f3c-…" is not a
+ * sentence anyone can act on. The public tier list is already loaded by every
+ * storefront that sells memberships, is cached by React Query under one key per
+ * profile, and — unlike an id embedded in a ticket payload — stays correct when
+ * the artist renames a tier. So the ids are resolved against it here, once, for
+ * every surface.
+ *
+ * The names are best-effort by design: the query can be in flight, and a gating
+ * tier can be one the public list does not carry (an archived or unlisted tier
+ * still gates). `buildMembershipGateNotice` therefore degrades to "is for
+ * members" rather than showing an id or rendering nothing — a badge with slightly
+ * vaguer wording is a working funnel; a blank space is the bug this closes.
+ *
+ * Returns `null` when nothing is gated, which is also what every surface sees
+ * while the gates feature switch is off.
+ */
+export function useMembershipGateNotice(input: UseMembershipGateNoticeInput): MembershipGateNotice | null {
+  const locked = isMembershipGateLocked(input.gate) || !!input.refusal;
+  // Only pulled once something is actually locked — an ungated storefront must
+  // not acquire a request it never needed.
+  const { data: tiers } = useGetMembershipTiers({ enabled: locked });
+
+  const requiredTierIds = input.refusal?.requiredTierIds ?? input.gate?.requiredTierIds ?? [];
+
+  return useMemo(() => {
+    if (!locked) return null;
+    const byId = new Map((tiers ?? []).map((tier) => [tier.id, tier.name]));
+    return buildMembershipGateNotice({
+      gate: input.gate,
+      refusal: input.refusal,
+      tierNames: requiredTierIds.map((id) => byId.get(id) ?? "").filter(Boolean),
+      itemLabel: input.itemLabel,
+      loginPath: input.loginPath,
+      membershipPath: input.membershipPath,
+      currentPath: currentPath(),
+    });
+    // `requiredTierIds` is a fresh array each render; its CONTENTS are the input.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [
+    locked,
+    tiers,
+    requiredTierIds.join(","),
+    input.gate?.reason,
+    input.refusal?.reason,
+    input.itemLabel,
+    input.loginPath,
+    input.membershipPath,
+  ]);
+}
+
+/** Where the buyer is standing, so signing in returns them to it. Empty during SSR. */
+function currentPath(): string {
+  if (typeof window === "undefined") return "";
+  return `${window.location.pathname}${window.location.search}`;
+}

package/src/ui/headless/offer/OfferContext.tsx

@@ -3,6 +3,8 @@ import type { IPublicProduct, IPublicProductVariant } from "../../../types/model
 import { useGetProduct } from "../../../data/queries/useProducts";
 import { useCreateOrder } from "../../../data/queries/useOrders";
 import { usePaymentFlow } from "../../../data/queries/usePaymentFlow";
+import { holdExpiredMessage, isHoldExpiredError } from "../checkout/inventoryHold";
+import { useInventoryHold, type InventoryHoldState } from "../checkout/useInventoryHold";
 
 export type OfferStep = "details" | "payment";
 
@@ -38,6 +40,13 @@ export interface OfferContextValue {
   clientSecret?: string;
   returnUrl: string;
   continueToPayment: () => Promise<void>;
+  /** The stock reservation held while the buyer pays. All-null when none was taken. */
+  hold: InventoryHoldState;
+  /** The server's 409 `INVENTORY_HOLD_EXPIRED` message — never sold-out. */
+  holdExpiredError: string | null;
+  /** Re-take the reservation on the same order. */
+  retryHold: () => Promise<void>;
+  isRetryingHold: boolean;
 }
 
 const OfferContext = createContext<OfferContextValue | null>(null);
@@ -72,6 +81,10 @@ export function OfferProvider({ productId, children, finalisePath }: OfferProvid
   const [confirmEmail, setConfirmEmail] = useState("");
   const [error, setError] = useState<string | null>(null);
   const [returnUrl, setReturnUrl] = useState("");
+  const [orderId, setOrderId] = useState<string | null>(null);
+  /** The window the ORDER reported, until start-payment restarts it. */
+  const [orderHoldExpiresAt, setOrderHoldExpiresAt] = useState<string | null>(null);
+  const [holdExpiredError, setHoldExpiredError] = useState<string | null>(null);
 
   const selectedVariant = useMemo(
     () => variants.find((v) => v.id === selectedVariantId) ?? variants[0],
@@ -82,6 +95,7 @@ export function OfferProvider({ productId, children, finalisePath }: OfferProvid
 
   const continueToPayment = async () => {
     setError(null);
+    setHoldExpiredError(null);
     if (!product || !selectedVariant) return;
     if (!firstName.trim() || !lastName.trim()) {
       setError("Please enter your name.");
@@ -114,6 +128,10 @@ export function OfferProvider({ productId, children, finalisePath }: OfferProvid
       });
       const ru = `${typeof window !== "undefined" ? window.location.origin : ""}${finalisePath ?? "/checkout/finalise"}?orderId=${created.orderId}`;
       setReturnUrl(ru);
+      setOrderId(created.orderId);
+      // Absent/null for a digital item, a free order, or a profile with holds
+      // switched off — every one of which must render no countdown at all.
+      setOrderHoldExpiresAt(created.holdExpiresAt ?? null);
       // Free checkout — skip payment.
       if (created.subTotal === 0 && typeof window !== "undefined") {
         window.location.href = ru;
@@ -124,11 +142,44 @@ export function OfferProvider({ productId, children, finalisePath }: OfferProvid
       if (result.provider && result.provider !== "stripe") return;
       setStep("payment");
     } catch (e) {
+      // A lapsed reservation gets its own state so the buyer is offered the
+      // retry that re-acquires the same unit, rather than a bare error that
+      // reads like the item is gone.
+      if (isHoldExpiredError(e)) {
+        setHoldExpiredError(
+          holdExpiredMessage(e, "Your reservation expired before payment finished. Please try again."),
+        );
+        return;
+      }
       const message = (e as { response?: { data?: { message?: string } } })?.response?.data?.message;
       setError(message || "Something went wrong.");
     }
   };
 
+  /** Take the same unit again on the same order. */
+  const retryHold = async () => {
+    if (!orderId || !returnUrl) return;
+    setHoldExpiredError(null);
+    try {
+      const result = await flow.start({ orderId, returnUrl });
+      if (result.provider && result.provider !== "stripe") return; // Paystack redirected
+      setStep("payment");
+    } catch (e) {
+      if (isHoldExpiredError(e)) {
+        setHoldExpiredError(
+          holdExpiredMessage(e, "Your reservation expired before payment finished. Please try again."),
+        );
+        return;
+      }
+      const message = (e as { response?: { data?: { message?: string } } })?.response?.data?.message;
+      setError(message || "Something went wrong.");
+    }
+  };
+
+  // start-payment restarts the clock and reports the newer instant, so it wins
+  // over the create-time one.
+  const hold = useInventoryHold(flow.result?.holdExpiresAt ?? orderHoldExpiresAt);
+
   const value: OfferContextValue = {
     product,
     isLoading,
@@ -156,6 +207,10 @@ export function OfferProvider({ productId, children, finalisePath }: OfferProvid
     clientSecret: flow.result?.paymentSecret,
     returnUrl,
     continueToPayment,
+    hold,
+    holdExpiredError,
+    retryHold,
+    isRetryingHold: flow.isStarting,
   };
 
   return <OfferContext.Provider value={value}>{children}</OfferContext.Provider>;