@tribe-nest/forge 3.21.0 → 3.22.0

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>;

package/src/ui/index.ts

@@ -51,6 +51,7 @@ export {
   DiscountSummaryLines,
   type DiscountSummaryLinesProps,
 } from "./styled/DiscountCode";
+export { PresaleCodeField, type PresaleCodeFieldProps } from "./styled/PresaleCode";
 export { MembershipCheckout, type MembershipCheckoutProps } from "./styled/MembershipCheckout";
 export { ForgeStripePayment } from "./payment/ForgeStripePayment";
 export { Cart, type CartProps } from "./styled/Cart";
@@ -109,6 +110,8 @@ export { ForgeAnalytics, type ForgeAnalyticsProps } from "./analytics/ForgeAnaly
 export { PageMetaPixel, usePageMetaPixel, type PageMetaPixelProps } from "./analytics/PageMetaPixel";
 export { CookieConsent, type CookieConsentProps } from "./styled/CookieConsent";
 export { Loading, type LoadingProps } from "./styled/Loading";
+/** The inventory-hold countdown + its lapsed/409 state. See `useInventoryHold`. */
+export { HoldNotice, type HoldNoticeProps } from "./styled/HoldNotice";
 export {
   ConfirmationStage,
   ConfirmationCard,
@@ -170,6 +173,45 @@ export {
   resolveUnitPrice,
   ticketSubtotals,
 } from "./format/pwyw";
+// Per-attendee names at checkout. Exported for a site rendering its own ticket
+// UI — and used by `apps/client`, which has its own event checkout: the request
+// shape is positional per tier and a length mismatch is refused server-side, so
+// neither stack derives it for itself.
+export {
+  MAX_ATTENDEE_NAME_LENGTH,
+  normalizeAttendeeName,
+  collectsAttendees,
+  buyerFullName,
+  buildAttendeeSlots,
+  setAttendeeName,
+  validateAttendeeNames,
+  attendeesPayload,
+  type AttendeeNames,
+  type AttendeeSlot,
+  type AttendeeCheck,
+  type AttendeeProblem,
+} from "./format/attendees";
+// Members-only gates (S.4). The wording and the resolving ACTION are decided
+// purely, in one place, because BOTH rendering stacks draw this — `apps/client`
+// imports these directly, exactly as it does the PWYW arithmetic. A members-only
+// badge that says one thing on an artist's PWA and another on their website is
+// the same bug twice.
+export {
+  MEMBERSHIP_GATE_CODE,
+  MEMBERSHIP_GATE_LOGIN_PATH,
+  MEMBERSHIP_GATE_MEMBERSHIP_PATH,
+  parseMembershipGateError,
+  isMembershipGateLocked,
+  buildMembershipGateNotice,
+  joinTierNames,
+  membershipSignInHref,
+  type MembershipGateNotice as MembershipGateNoticeModel,
+  type MembershipGateRefusal,
+  type MembershipGateReason,
+  type PublicMembershipGate,
+  type BuildMembershipGateNoticeInput,
+} from "./format/membershipGate";
+export { MembershipGateNotice, type MembershipGateNoticeProps } from "./styled/MembershipGateNotice";
 export { usePricesIncludeTax } from "../data/queries/useWebsite";
 
 // PWA (installable code sites) — SW registration + install/push UX (Tier 2).

package/src/ui/styled/AccountDashboard.tsx

@@ -4,7 +4,8 @@ import {
   useUserOrders,
   useMyTickets,
   useCancelMyTicket,
-  myTicketPassIds,
+  myTicketHeldPassIds,
+  myTicketPasses,
   type MyTicket,
   useMyWaitlistPlaces,
   useLeaveEventWaitlist,
@@ -34,6 +35,7 @@ import { useSiteConfig } from "../../data/queries/useWebsite";
 import { useAmountFormatter } from "../format/useFormatCurrency";
 import { Loading } from "./Loading";
 import { formatCountdown } from "./EventWaitlist";
+import { AddToCalendar } from "./AddToCalendar";
 import { WalletPassButtons } from "./WalletPassButtons";
 import { TicketTransferPanel } from "./TicketTransfer";
 import { CartLineOptions } from "./CartLineOptions";
@@ -340,6 +342,14 @@ function MembershipTab({ ctx }: { ctx: TabContext }) {
  * come from the server, which reads the snapshot on the order; mirroring the
  * date arithmetic in the UI would give two answers to the same question and the
  * wrong one would be the one the buyer sees.
+ *
+ * ## Two kinds of row
+ *
+ * `role` says whether the caller PAID for this order or merely HOLDS a pass out
+ * of it — a ticket somebody transferred to them, which until now reached them
+ * nowhere at all. A holder's row is scrubbed server-side (no totals, no line
+ * prices, no other seats, no cancel), and this renders that difference rather
+ * than printing "$0.00" over somebody else's purchase.
  */
 function TicketsTab({ ctx }: { ctx: TabContext }) {
   const { user } = usePublicAuth();
@@ -381,6 +391,8 @@ function TicketsTab({ ctx }: { ctx: TabContext }) {
         <div style={{ display: "flex", flexDirection: "column", gap: 16 }}>
           {tickets.map((ticket) => {
             const cancelled = !!ticket.selfCancelledAt;
+            // Absent on an older API build, where every row WAS a purchase.
+            const gifted = ticket.role === "holder";
             return (
               <div
                 key={ticket.id}
@@ -392,6 +404,12 @@ function TicketsTab({ ctx }: { ctx: TabContext }) {
                     <div style={{ fontSize: 13, opacity: 0.7 }}>{formatDate(ticket.eventDateTime)}</div>
                   </div>
                   {cancelled && <span style={{ fontSize: 13, color: t.primary }}>Cancelled</span>}
+                  {/* Says WHY this is in the list at all. Without it a
+                      transferred ticket looks like a purchase the buyer cannot
+                      remember making, with no prices on it. */}
+                  {!cancelled && gifted && (
+                    <span style={{ fontSize: 13, color: t.primary }}>Sent to you</span>
+                  )}
                 </div>
 
                 {ticket.items.map((item) => (
@@ -399,14 +417,34 @@ function TicketsTab({ ctx }: { ctx: TabContext }) {
                     <span>
                       {item.ticketTitle ?? "Ticket"} × {item.quantity}
                     </span>
-                    <span>{formatAmount(Number(item.price) * item.quantity, ticket.currency || currency)}</span>
+                    {/* A holder is not shown a price, because the server did
+                        not send one — `Number(null)` is 0, and a confident
+                        "$0.00" on somebody else's purchase is a lie. */}
+                    {!gifted && (
+                      <span>{formatAmount(Number(item.price) * item.quantity, ticket.currency || currency)}</span>
+                    )}
                   </div>
                 ))}
 
-                <div style={{ display: "flex", justifyContent: "space-between", fontWeight: 700, marginTop: 12, paddingTop: 12, borderTop: `1px solid ${t.primary}20` }}>
-                  <span>Total</span>
-                  <span style={{ color: t.primary }}>{formatAmount(Number(ticket.totalAmount), ticket.currency || currency)}</span>
-                </div>
+                {!gifted && (
+                  <div style={{ display: "flex", justifyContent: "space-between", fontWeight: 700, marginTop: 12, paddingTop: 12, borderTop: `1px solid ${t.primary}20` }}>
+                    <span>Total</span>
+                    <span style={{ color: t.primary }}>{formatAmount(Number(ticket.totalAmount), ticket.currency || currency)}</span>
+                  </div>
+                )}
+
+                {/* Diarise it — including the Apple option, which needs the
+                    platform's own `.ics` and so could not exist before. Null
+                    for a called-off show, and the component draws nothing. */}
+                <AddToCalendar
+                  variant="compact"
+                  title={ticket.eventTitle}
+                  start={ticket.eventDateTime}
+                  end={ticket.eventEndDateTime}
+                  icsUrl={ticket.calendarUrl}
+                  webcalUrl={ticket.calendarWebcalUrl}
+                  style={{ marginTop: 12 }}
+                />
 
                 {/*
                   Wallet passes (2.3). Renders NOTHING unless the API offers a
@@ -419,7 +457,7 @@ function TicketsTab({ ctx }: { ctx: TabContext }) {
                   Eligibility (cancelled order, rotating QR) is the server's
                   call, exactly as it is for cancellation above.
                 */}
-                <WalletPassButtons passIds={myTicketPassIds(ticket)} variant="compact" style={{ marginTop: 12 }} />
+                <WalletPassButtons passIds={myTicketHeldPassIds(ticket)} variant="compact" style={{ marginTop: 12 }} />
 
                 {/*
                   Transfer (2.2). The email a transfer sends points at
@@ -432,8 +470,19 @@ function TicketsTab({ ctx }: { ctx: TabContext }) {
                   404. Whether THIS pass may be handed on is the server's call,
                   answered on submit in its own words — not hidden behind a
                   guess here.
+
+                  HELD passes only: the endpoints resolve the current holder, so
+                  a control on a named guest's seat or on a ticket already
+                  claimed by somebody else could answer nothing but 404. The
+                  pass objects go through too, because each carries the caller's
+                  own `pendingTransfer` — which is what lets a sender withdraw
+                  from a device that is not the one they sent from.
                 */}
-                <TicketTransferPanel passIds={myTicketPassIds(ticket)} style={{ marginTop: 12 }} />
+                <TicketTransferPanel
+                  passIds={myTicketHeldPassIds(ticket)}
+                  passes={myTicketPasses(ticket)}
+                  style={{ marginTop: 12 }}
+                />
 
                 {/* The terms they agreed to, in the artist's own words where given. */}
                 {ticket.cancellation.description && (
@@ -735,6 +784,19 @@ function BookingRow({ booking, ctx }: { booking: MyBooking; ctx: TabContext }) {
         </div>
       </div>
 
+      {/* Diarise it — including Apple, which needs the platform's own `.ics`.
+          Null unless the session is confirmed, and the component draws nothing. */}
+      <AddToCalendar
+        variant="compact"
+        title={booking.coachingProductTitle}
+        start={booking.sessionStartTime}
+        end={booking.sessionEndTime}
+        defaultDurationMinutes={booking.coachingProductDurationMinutes ?? undefined}
+        icsUrl={booking.calendarUrl}
+        webcalUrl={booking.calendarWebcalUrl}
+        style={{ marginTop: 12 }}
+      />
+
       {/* The terms they booked under, in the artist's own words where given. */}
       {booking.cancellation.description && (
         <div style={{ fontSize: 13, opacity: 0.75, marginTop: 12 }}>{booking.cancellation.description}</div>

package/src/ui/styled/AddToCalendar.tsx

@@ -17,9 +17,30 @@ export interface AddToCalendarProps extends AddToCalendarInput {
 }
 
 /**
- * "Add to calendar" — deep links that prefill Google / Outlook / Microsoft 365
- * with the event, plus an `.ics` download when the host supplies one (that is
- * the Apple Calendar route; there is no Apple web endpoint to link to).
+ * "Add to calendar" — deep links that prefill Google / Outlook / Microsoft 365,
+ * plus the two Apple-shaped options once the host supplies the platform's
+ * `.ics` address.
+ *
+ * ## Why Apple needs two entries and the others need none
+ *
+ * Google and Microsoft publish TEMPLATE URLs: the whole event travels in the
+ * query string and no server is involved. Apple publishes nothing of the kind —
+ * Calendar takes a FILE. So for as long as this component had no `.ics` to
+ * point at, an iPhone user had no option at all, which is precisely the state
+ * the product shipped in.
+ *
+ *  - **Apple Calendar** → `webcal://`. The scheme is what iOS and macOS route
+ *    to the Calendar app; it must be a plain same-window navigation, so it
+ *    carries neither `target="_blank"` (the OS handler, not a tab) nor
+ *    `download` (there is no file to save — the OS is opening an app).
+ *  - **Download .ics** → the https address, with `download`. Outlook desktop,
+ *    Thunderbird, Android calendar apps and anyone who would simply rather have
+ *    the file.
+ *
+ * Both are offered because `webcal:` has no handler on much of the desktop web,
+ * and a lone Apple button on Windows is a dead link. Neither appears at all
+ * when the host passes no URL — a site pinned to an older API build degrades to
+ * exactly the three-provider row it had before.
  *
  * Purely presentational: every URL comes from `useAddToCalendar`. Renders
  * nothing at all when the start time is missing or unparseable.
@@ -38,12 +59,14 @@ export function AddToCalendar({
 
   const compact = variant === "compact";
 
-  const options: { key: string; text: string; href: string; download?: boolean }[] = [
-    { key: "google", text: "Google", href: links.google },
-    { key: "outlook", text: "Outlook", href: links.outlook },
-    { key: "office365", text: "Microsoft 365", href: links.office365 },
+  const options: { key: string; text: string; href: string; download?: boolean; newTab?: boolean }[] = [
+    { key: "google", text: "Google", href: links.google, newTab: true },
+    { key: "outlook", text: "Outlook", href: links.outlook, newTab: true },
+    { key: "office365", text: "Microsoft 365", href: links.office365, newTab: true },
   ];
-  if (links.ics) options.push({ key: "ics", text: "Apple / .ics", href: links.ics, download: true });
+  // Apple first among the file-based options: it is the one a phone will use.
+  if (links.webcal) options.push({ key: "apple", text: "Apple Calendar", href: links.webcal });
+  if (links.ics) options.push({ key: "ics", text: "Download .ics", href: links.ics, download: true });
 
   const chip: React.CSSProperties = {
     display: "inline-flex",
@@ -89,8 +112,9 @@ export function AddToCalendar({
           <a
             key={o.key}
             href={o.href}
-            target="_blank"
-            rel="noopener noreferrer"
+            // `webcal:` hands off to the OS — a new tab would leave a blank one
+            // behind, and `rel` is meaningless for a non-http scheme.
+            {...(o.newTab ? { target: "_blank", rel: "noopener noreferrer" } : {})}
             data-testid={`add-to-calendar-${o.key}`}
             {...(o.download ? { download: "" } : {})}
             style={chip}

package/src/ui/styled/Checkout.tsx

@@ -12,6 +12,7 @@ import { usePricesIncludeTax } from "../../data/queries/useWebsite";
 import { usePaymentRenderer } from "../payment/ForgePaymentProvider";
 import { Loading } from "./Loading";
 import { CartLineOptions } from "./CartLineOptions";
+import { HoldNotice } from "./HoldNotice";
 
 export interface CheckoutProps {
   /** Path used to build the post-payment return URL. Defaults to `/checkout/finalise`. */
@@ -814,6 +815,7 @@ function PaymentSection({
   const { formatCurrency } = useFormatCurrency();
   const renderPay = usePaymentRenderer();
   const { paymentSecret, chargedAmount, chargedCurrency, returnUrl, isPaystack, isCreatingOrder, startError } = checkout;
+  const { hold, holdExpiredError, isHoldExpired, retryHold, isRetryingHold } = checkout;
 
   // Paystack has no in-app form — send the buyer to the hosted checkout as soon
   // as the redirect URL (paymentSecret) is ready. The button below is a manual
@@ -880,7 +882,22 @@ function PaymentSection({
         </p>
       )}
 
-      {isCreatingOrder && !paymentSecret && <Loading label="Preparing payment…" size={22} />}
+      {/* The reservation — a countdown while it runs, and at zero (or on a 409)
+          the lapsed state with the retry that re-acquires the same units.
+          Renders nothing at all when no hold was taken, which is the ordinary
+          case for the profiles that have inventory holds switched off. */}
+      <HoldNotice
+        hold={hold}
+        expiredMessage={holdExpiredError || undefined}
+        onRetry={retryHold}
+        isRetrying={isRetryingHold}
+        secondaryAction={onBack ? { label: "Change your order", onClick: onBack } : undefined}
+      />
+
+      {/* Suppressed once the server has refused: there is no intent coming, so a
+          "Preparing payment…" spinner would sit there forever under a notice
+          that has already explained what happened. */}
+      {isCreatingOrder && !paymentSecret && !isHoldExpired && <Loading label="Preparing payment…" size={22} />}
 
       {isPaystack
         ? paymentSecret &&

package/src/ui/styled/CoachingConfirmation.tsx

@@ -173,6 +173,10 @@ export function CoachingConfirmation({
               start={data.sessionStartTime}
               end={data.sessionEndTime}
               defaultDurationMinutes={data.durationMinutes ?? undefined}
+              // The finalise response carries these only for a CONFIRMED
+              // booking, which is the same condition this block renders under.
+              icsUrl={data.calendarUrl}
+              webcalUrl={data.calendarWebcalUrl}
               style={{ marginTop: 18 }}
             />
           )}

package/src/ui/styled/CourseDetail.tsx

@@ -1,5 +1,6 @@
 import type { PublicCourse } from "../../types/models";
 import { useGetCourse } from "../../data/queries/useCourses";
+import { MembershipGateNotice } from "./MembershipGateNotice";
 import { useThemeTokens } from "../theme/ForgeThemeProvider";
 import { useAmountFormatter } from "../format/useFormatCurrency";
 import { PriceDisplay } from "../format/PriceDisplay";
@@ -23,6 +24,10 @@ export interface CourseDetailProps {
   finalisePath?: (slug: string, bookingId: string) => string;
   /** Host-owned navigation on FREE completion (forwarded to the enroll flow). */
   onComplete?: (info: { slug: string; bookingId: string }) => void;
+  /** Where a members-only course sends a signed-OUT visitor. Default `/login`. */
+  loginPath?: string;
+  /** Where a members-only course sends a signed-in NON-member. Default `/membership`. */
+  membershipPath?: string;
 }
 
 export function CourseDetail({
@@ -33,6 +38,8 @@ export function CourseDetail({
   initialCourse,
   finalisePath,
   onComplete,
+  loginPath,
+  membershipPath,
 }: CourseDetailProps) {
   const t = useThemeTokens();
   const fmt = useAmountFormatter(formatAmount);
@@ -42,6 +49,11 @@ export function CourseDetail({
   if (isLoading) return <Loading fullPage />;
   if (!course) return <p>Course not found.</p>;
 
+  /**
+   * Members-only course (S.4). Announced by the detail read, which is why the
+   * page can say so BEFORE the buyer opens a checkout that would refuse them.
+   */
+  const isGated = !!course.membershipGate && !course.membershipGate.allowed;
   const cover = course.media?.find((m) => m.type === "image")?.url ?? course.media?.[0]?.url;
   const introVideo = course.media?.find((m) => m.type === "video")?.url;
   const modules = course.modules ?? [];
@@ -129,7 +141,24 @@ export function CourseDetail({
               <PriceDisplay amount={Number(course.price)} pricesIncludeTax={pricesIncludeTax} formatAmount={fmt} mutedColor={t.text} captionStyle={{ opacity: 0.65 }} />
             )}
           </span>
-          <CourseCheckout slug={slug} formatAmount={fmt} finalisePath={finalisePath} onComplete={onComplete} />
+          {/*
+            A live gate locks the course even for someone who already bought it —
+            "this course is part of Gold" is a CONDITION for access, not a
+            one-off unlock — so a lapsed member lands here too and needs the way
+            back in, not a purchase button that will be refused.
+           */}
+          {isGated ? (
+            <MembershipGateNotice
+              gate={course.membershipGate}
+              variant="card"
+              itemLabel="This course"
+              loginPath={loginPath}
+              membershipPath={membershipPath}
+              style={{ padding: 0, border: "none", background: "transparent" }}
+            />
+          ) : (
+            <CourseCheckout slug={slug} formatAmount={fmt} finalisePath={finalisePath} onComplete={onComplete} />
+          )}
         </aside>
       </div>
 

package/src/ui/styled/EventConfirmation.tsx

@@ -148,6 +148,8 @@ export function EventConfirmation({
               end={event.endDateTime}
               description={event.description}
               location={location}
+              icsUrl={event.calendarUrl}
+              webcalUrl={event.calendarWebcalUrl}
               style={{ marginTop: 12 }}
             />
           )}