@tribe-nest/forge 3.53.0 → 3.57.0

package/src/ui/headless/event/_tests/ticketApproval.spec.ts

@@ -0,0 +1,137 @@
+import { describe, it, expect } from "vitest";
+import {
+  eventHasApprovalTiers,
+  nextStepAfterTicketOrder,
+  selectionMode,
+  selectionRequiresApproval,
+  tierBlockedByApprovalMix,
+  tierRequiresApproval,
+} from "../ticketApproval";
+import type { IEvent, ITicket } from "../../../../types/models";
+
+/**
+ * Ticket requests (curated access, feature 3): the pure decisions the picker
+ * and the checkout make. Two rules are load-bearing and both are here:
+ *
+ *  1. ONE ORDER IS A REQUEST OR A PURCHASE, NEVER BOTH. The API refuses a
+ *     mixed cart; the picker must stop one being built.
+ *  2. A FREE REQUEST HAS NO PAYMENT STEP. It comes back `pending_approval`
+ *     with `isFreeCheckout: false`, so the old "free means isFreeCheckout"
+ *     test alone would send it to a card form for a charge of nothing.
+ */
+const tier = (overrides: Partial<ITicket> = {}): ITicket =>
+  ({
+    id: "t-ga",
+    title: "General admission",
+    description: "",
+    price: 25,
+    quantity: 100,
+    order: 0,
+    sold: 0,
+    maxPerPerson: 4,
+    ...overrides,
+  }) as ITicket;
+
+const ga = tier();
+const vip = tier({ id: "t-vip", title: "Front row", requiresApproval: true });
+const backstage = tier({ id: "t-back", title: "Backstage", requiresApproval: true, price: 0 });
+const tiers = [ga, vip, backstage];
+
+describe("tierRequiresApproval / eventHasApprovalTiers", () => {
+  it("reads the flag, and treats its absence (an older API) as an ordinary tier", () => {
+    expect(tierRequiresApproval(vip)).toBe(true);
+    expect(tierRequiresApproval(ga)).toBe(false);
+    expect(tierRequiresApproval(undefined)).toBe(false);
+  });
+
+  it("finds an approval tier on the event even when the event-level flag did not come", () => {
+    expect(eventHasApprovalTiers({ tickets: [ga, vip] } as IEvent)).toBe(true);
+    expect(eventHasApprovalTiers({ tickets: [ga] } as IEvent)).toBe(false);
+    expect(eventHasApprovalTiers({ tickets: [], hasApprovalTiers: true } as unknown as IEvent)).toBe(true);
+    expect(eventHasApprovalTiers(undefined)).toBe(false);
+  });
+});
+
+describe("selectionMode / selectionRequiresApproval", () => {
+  it("is null while nothing is selected, so either kind is still addable", () => {
+    expect(selectionMode(tiers, {})).toBeNull();
+    expect(selectionMode(tiers, { "t-ga": 0 })).toBeNull();
+    expect(selectionRequiresApproval(tiers, {})).toBe(false);
+  });
+
+  it("is a request once an approval tier is in", () => {
+    expect(selectionMode(tiers, { "t-vip": 1 })).toBe("request");
+    expect(selectionRequiresApproval(tiers, { "t-vip": 2 })).toBe(true);
+  });
+
+  it("is a purchase once an ordinary tier is in", () => {
+    expect(selectionMode(tiers, { "t-ga": 1 })).toBe("purchase");
+    expect(selectionRequiresApproval(tiers, { "t-ga": 1 })).toBe(false);
+  });
+
+  it("reads a mixed selection as a request, the kind the server will refuse rather than silently sell", () => {
+    expect(selectionMode(tiers, { "t-ga": 1, "t-vip": 1 })).toBe("request");
+  });
+
+  it("ignores quantities for tiers the event no longer lists", () => {
+    expect(selectionMode(tiers, { "t-gone": 3 })).toBeNull();
+  });
+});
+
+describe("tierBlockedByApprovalMix: one order is a request or a purchase", () => {
+  it("blocks nothing on an empty selection", () => {
+    expect(tierBlockedByApprovalMix(ga, tiers, {})).toBe(false);
+    expect(tierBlockedByApprovalMix(vip, tiers, {})).toBe(false);
+  });
+
+  it("blocks an ordinary tier once an approval tier is selected, and the reverse", () => {
+    expect(tierBlockedByApprovalMix(ga, tiers, { "t-vip": 1 })).toBe(true);
+    expect(tierBlockedByApprovalMix(vip, tiers, { "t-ga": 1 })).toBe(true);
+  });
+
+  it("lets two approval tiers share a request, and two ordinary tiers share a purchase", () => {
+    expect(tierBlockedByApprovalMix(backstage, tiers, { "t-vip": 1 })).toBe(false);
+    expect(tierBlockedByApprovalMix(ga, tiers, { "t-ga": 1 })).toBe(false);
+  });
+
+  it("never blocks a tier that is already in the selection, so its own stepper keeps working", () => {
+    // If it were blocked, a fan holding one seat could not add a second, and
+    // the `+` would go dark on the very tier that set the mode.
+    expect(tierBlockedByApprovalMix(vip, tiers, { "t-vip": 1 })).toBe(false);
+    expect(tierBlockedByApprovalMix(ga, tiers, { "t-ga": 2 })).toBe(false);
+  });
+});
+
+describe("nextStepAfterTicketOrder: where the checkout goes once the order exists", () => {
+  it("completes a free purchase, exactly as before", () => {
+    expect(nextStepAfterTicketOrder({ isFreeCheckout: true, totalAmount: 0 })).toBe("complete");
+  });
+
+  it("REGRESSION: completes a FREE REQUEST, which is not a free checkout", () => {
+    // The server has already put it in `pending_approval` and minted nothing,
+    // so `isFreeCheckout` is false. There is no card to show.
+    expect(nextStepAfterTicketOrder({ isFreeCheckout: false, awaitingApproval: true, totalAmount: 0 })).toBe(
+      "complete",
+    );
+    // A bigint-ish string total, which is what some responses carry.
+    expect(nextStepAfterTicketOrder({ awaitingApproval: true, totalAmount: "0" })).toBe("complete");
+    expect(nextStepAfterTicketOrder({ awaitingApproval: true, totalAmount: null })).toBe("complete");
+  });
+
+  it("sends a PRICED request to payment, like any sale", () => {
+    // The card is authorised rather than charged, but the fan still has to
+    // present it; only start-payment's wording differs.
+    expect(nextStepAfterTicketOrder({ isFreeCheckout: false, awaitingApproval: true, totalAmount: 40 })).toBe(
+      "payment",
+    );
+    expect(nextStepAfterTicketOrder({ awaitingApproval: true, totalAmount: "12.50" })).toBe("payment");
+  });
+
+  it("sends an ordinary priced sale to payment, and never completes on a zero total alone", () => {
+    expect(nextStepAfterTicketOrder({ isFreeCheckout: false, totalAmount: 40 })).toBe("payment");
+    // A zero total without `isFreeCheckout` and without `awaitingApproval` is
+    // the old behaviour: the server did not say it was free, so start payment.
+    expect(nextStepAfterTicketOrder({ isFreeCheckout: false, totalAmount: 0 })).toBe("payment");
+    expect(nextStepAfterTicketOrder({})).toBe("payment");
+  });
+});

package/src/ui/headless/event/_tests/useEventCheckoutApproval.spec.tsx

@@ -0,0 +1,250 @@
+// @vitest-environment jsdom
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { act, renderHook, waitFor } from "@testing-library/react";
+import axios, { type AxiosAdapter, type InternalAxiosRequestConfig } from "axios";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import type { ReactNode } from "react";
+import { ForgeClientProvider } from "../../../../provider/ForgeProvider";
+import { PublicAuthProvider } from "../../../../contexts/PublicAuthContext";
+import { CartProvider } from "../../../../contexts/CartContext";
+import { useEventCheckout } from "../useEventCheckout";
+
+/**
+ * Ticket requests (curated access, feature 3), end to end through the REAL
+ * hook with only the network faked.
+ *
+ * The case that matters most is the free request. The server answers it with
+ * `isFreeCheckout: false` (no passes were minted: the order is
+ * `pending_approval`) and `awaitingApproval: true`, so the branch that used to
+ * decide "free means done" would have sent the fan to a card form for a charge
+ * of nothing. The hook has to hand the order id to `onComplete` exactly as it
+ * does for a free purchase, and never call start-payment.
+ *
+ * Providers are real and the axios adapter is swapped, so the assertion is on
+ * what actually went over the wire.
+ */
+
+const PROFILE_ID = "profile-1";
+const SLUG = "summer-show";
+
+const event = {
+  id: "ev-1",
+  slug: SLUG,
+  title: "Summer show",
+  dateTime: "2026-12-01T19:00:00.000Z",
+  type: "in_person",
+  status: "published",
+  tickets: [
+    { id: "t-ga", title: "General admission", description: "", price: 25, quantity: 100, order: 0, sold: 0, maxPerPerson: 4 },
+    {
+      id: "t-vip",
+      title: "Front row",
+      description: "",
+      price: 0,
+      quantity: 10,
+      order: 1,
+      sold: 0,
+      maxPerPerson: 2,
+      requiresApproval: true,
+      approvalWindowHours: 72,
+    },
+    {
+      id: "t-priced",
+      title: "Backstage",
+      description: "",
+      price: 40,
+      quantity: 10,
+      order: 2,
+      sold: 0,
+      maxPerPerson: 2,
+      requiresApproval: true,
+      approvalWindowHours: null,
+    },
+  ],
+  media: [],
+  questionnaire: [],
+  bookingFee: null,
+};
+
+type Sent = { method: string; url: string; body: Record<string, unknown> };
+let sent: Sent[] = [];
+let realAdapter: AxiosAdapter | undefined;
+let orderResponse: Record<string, unknown> = {};
+
+function installAdapter() {
+  sent = [];
+  const adapter: AxiosAdapter = async (config: InternalAxiosRequestConfig) => {
+    const url = config.url ?? "";
+    const body = typeof config.data === "string" ? (JSON.parse(config.data) as Record<string, unknown>) : {};
+    sent.push({ method: (config.method ?? "get").toLowerCase(), url, body });
+    const ok = (data: unknown) => ({ data, status: 200, statusText: "OK", headers: {}, config }) as never;
+
+    if (url.includes(`/public/events/${SLUG}`)) return ok(event);
+    if (url.includes(`/public/events/${event.id}/orders`)) return ok(orderResponse);
+    if (url.includes(`/public/events/${event.id}/start-payment`)) {
+      return ok({
+        paymentSecret: "pi_secret",
+        paymentId: "pi_1",
+        paymentProvider: "stripe",
+        totalAmount: 40,
+        settlement: "deferred",
+        deferredStrategy: "authorization",
+      });
+    }
+    if (url.includes("/public/currencies")) {
+      return ok({ supportedCurrencies: ["USD"], userCurrency: "USD", exchangeRates: {} });
+    }
+    return ok({});
+  };
+  realAdapter = axios.defaults.adapter as AxiosAdapter | undefined;
+  axios.defaults.adapter = adapter;
+}
+
+const wrapper = ({ children }: { children: ReactNode }) => (
+  <QueryClientProvider client={new QueryClient({ defaultOptions: { queries: { retry: false }, mutations: { retry: false } } })}>
+    <ForgeClientProvider apiUrl="http://api.test" profileId={PROFILE_ID}>
+      <PublicAuthProvider>
+        <CartProvider>{children}</CartProvider>
+      </PublicAuthProvider>
+    </ForgeClientProvider>
+  </QueryClientProvider>
+);
+
+const mount = (onComplete?: (info: { slug: string; orderId: string }) => void) =>
+  renderHook(() => useEventCheckout(SLUG, { onComplete }), { wrapper });
+
+const fillDetails = (result: { current: ReturnType<typeof useEventCheckout> }) =>
+  act(() => {
+    result.current.setFirstName("Fan");
+    result.current.setLastName("Person");
+    result.current.setEmail("fan@example.com");
+  });
+
+beforeEach(() => {
+  localStorage.clear();
+  installAdapter();
+});
+
+afterEach(() => {
+  if (realAdapter) axios.defaults.adapter = realAdapter;
+  localStorage.clear();
+});
+
+describe("useEventCheckout: a ticket request", () => {
+  it("REGRESSION: a FREE request completes with the order id and never starts a payment", async () => {
+    orderResponse = {
+      orderId: "order-free-request",
+      isFreeCheckout: false,
+      awaitingApproval: true,
+      totalAmount: 0,
+      subTotal: 0,
+      discountAmount: 0,
+      feeAmount: 0,
+      requestExpiresAt: "2026-09-19T12:00:00.000Z",
+      holdExpiresAt: null,
+    };
+    const onComplete = vi.fn();
+    const { result } = mount(onComplete);
+    await waitFor(() => expect(result.current.event?.id).toBe("ev-1"));
+
+    act(() => result.current.setTicketQty("t-vip", 1));
+    expect(result.current.awaitingApproval).toBe(true);
+    expect(result.current.hasApprovalTiers).toBe(true);
+    await fillDetails(result);
+
+    await act(async () => {
+      await result.current.continueToPayment();
+    });
+
+    expect(onComplete).toHaveBeenCalledTimes(1);
+    expect(onComplete).toHaveBeenCalledWith({ slug: SLUG, orderId: "order-free-request" });
+    // The order was posted, the charge was not.
+    expect(sent.some((r) => r.method === "post" && r.url.includes("/orders"))).toBe(true);
+    expect(sent.some((r) => r.url.includes("/start-payment"))).toBe(false);
+    // Still on details: no payment step was entered for a charge of nothing.
+    expect(result.current.step).not.toBe("payment");
+    expect(result.current.requestExpiresAt).toBe("2026-09-19T12:00:00.000Z");
+  });
+
+  it("a PRICED request still goes to payment, and carries the deferred settlement through", async () => {
+    orderResponse = {
+      orderId: "order-priced-request",
+      isFreeCheckout: false,
+      awaitingApproval: true,
+      totalAmount: 40,
+      subTotal: 40,
+      discountAmount: 0,
+      feeAmount: 0,
+      requestExpiresAt: "2026-09-19T12:00:00.000Z",
+      holdExpiresAt: "2026-09-16T12:15:00.000Z",
+    };
+    const onComplete = vi.fn();
+    const { result } = mount(onComplete);
+    await waitFor(() => expect(result.current.event?.id).toBe("ev-1"));
+
+    act(() => result.current.setTicketQty("t-priced", 1));
+    await fillDetails(result);
+    await act(async () => {
+      await result.current.continueToPayment();
+    });
+
+    expect(onComplete).not.toHaveBeenCalled();
+    const start = sent.find((r) => r.url.includes("/start-payment"));
+    expect(start).toBeDefined();
+    expect(start?.body).toMatchObject({ orderId: "order-priced-request", profileId: PROFILE_ID });
+    await waitFor(() => expect(result.current.step).toBe("payment"));
+    expect(result.current.clientSecret).toBe("pi_secret");
+    // What the payment renderer reads to say "Authorize" and "a hold will show".
+    expect(result.current.settlement).toBe("deferred");
+    expect(result.current.deferredStrategy).toBe("authorization");
+  });
+
+  it("an ordinary free purchase completes exactly as it always did", async () => {
+    orderResponse = { orderId: "order-free", isFreeCheckout: true, totalAmount: 0, feeAmount: 0, holdExpiresAt: null };
+    const onComplete = vi.fn();
+    const { result } = mount(onComplete);
+    await waitFor(() => expect(result.current.event?.id).toBe("ev-1"));
+
+    act(() => result.current.setTicketQty("t-ga", 1));
+    expect(result.current.awaitingApproval).toBe(false);
+    await fillDetails(result);
+    await act(async () => {
+      await result.current.continueToPayment();
+    });
+
+    expect(onComplete).toHaveBeenCalledWith({ slug: SLUG, orderId: "order-free" });
+    expect(sent.some((r) => r.url.includes("/start-payment"))).toBe(false);
+  });
+
+  it("refuses to mix a request and a purchase in one selection", async () => {
+    const { result } = mount();
+    await waitFor(() => expect(result.current.event?.id).toBe("ev-1"));
+
+    act(() => result.current.setTicketQty("t-vip", 1));
+    expect(result.current.isTierBlockedByApprovalMix("t-ga")).toBe(true);
+    expect(result.current.isTierBlockedByApprovalMix("t-priced")).toBe(false);
+    // A host driving the hook from its own UI cannot build the cart either.
+    act(() => result.current.setTicketQty("t-ga", 1));
+    expect(result.current.selectedTickets).toEqual({ "t-vip": 1 });
+
+    // Clearing the request frees the ordinary tier again.
+    act(() => result.current.setTicketQty("t-vip", 0));
+    expect(result.current.isTierBlockedByApprovalMix("t-ga")).toBe(false);
+    act(() => result.current.setTicketQty("t-ga", 2));
+    expect(result.current.selectedTickets).toEqual({ "t-ga": 2 });
+    expect(result.current.isTierBlockedByApprovalMix("t-vip")).toBe(true);
+  });
+
+  it("does not send a request to the cart", async () => {
+    const { result } = mount();
+    await waitFor(() => expect(result.current.event?.id).toBe("ev-1"));
+
+    act(() => result.current.setTicketQty("t-vip", 1));
+    let added: boolean | undefined;
+    act(() => {
+      added = result.current.addTicketsToCart();
+    });
+    expect(added).toBe(false);
+    expect(result.current.ticketsInCart).toBe(false);
+  });
+});

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

@@ -0,0 +1,109 @@
+import type { IEvent, ITicket } from "../../../types/models";
+
+/**
+ * Ticket requests (curated access, feature 3): the pure decisions behind the
+ * picker and the checkout, kept out of the hook so they can be tested without
+ * standing up the providers the hook needs.
+ *
+ * A tier with `requiresApproval` is not sold, it is REQUESTED: the card is
+ * committed (authorised) and the seat held, and the organiser has a window to
+ * approve or decline. One order is either a request or a purchase, never
+ * both: the API refuses a mixed cart (`errors.event.mixed_approval_cart`), and
+ * the picker stops the fan building one in the first place.
+ */
+
+/** Does this tier need the organiser's approval? Absent on an older API build means no. */
+export function tierRequiresApproval(ticket: Pick<ITicket, "requiresApproval"> | undefined): boolean {
+  return ticket?.requiresApproval === true;
+}
+
+/** Does this event carry any approval-required tier at all? Read off the tiers, not the flag, so a partial payload still answers. */
+export function eventHasApprovalTiers(event: Pick<IEvent, "tickets" | "hasApprovalTiers"> | undefined): boolean {
+  if (!event) return false;
+  if (event.hasApprovalTiers === true) return true;
+  return (event.tickets ?? []).some(tierRequiresApproval);
+}
+
+/**
+ * Which kind of order the current selection would make. `null` while nothing
+ * is selected (either kind is still addable), `"request"` once an approval
+ * tier is in, `"purchase"` once an ordinary one is. A mixed selection cannot
+ * arise through `tierBlockedByApprovalMix`, but if one is handed in (a stale
+ * cache, a tier that changed mode underneath the fan) it reads as a request,
+ * because that is the button the server will refuse rather than the one it
+ * will silently sell.
+ */
+export function selectionMode(
+  tickets: readonly Pick<ITicket, "id" | "requiresApproval">[],
+  quantities: Record<string, number>,
+): "request" | "purchase" | null {
+  let approval = false;
+  let ordinary = false;
+  for (const ticket of tickets) {
+    if ((quantities[ticket.id] ?? 0) <= 0) continue;
+    if (tierRequiresApproval(ticket)) approval = true;
+    else ordinary = true;
+  }
+  if (approval) return "request";
+  if (ordinary) return "purchase";
+  return null;
+}
+
+/** The selection contains at least one approval tier, so submitting it lodges a request. */
+export function selectionRequiresApproval(
+  tickets: readonly Pick<ITicket, "id" | "requiresApproval">[],
+  quantities: Record<string, number>,
+): boolean {
+  return selectionMode(tickets, quantities) === "request";
+}
+
+/**
+ * May this tier be added to the current selection?
+ *
+ * Blocked when the selection already holds the OTHER kind: an approval tier
+ * beside a purchase, or a purchase beside a request. A tier that is already in
+ * the selection is never blocked (it is the kind that set the mode), and an
+ * empty selection blocks nothing.
+ */
+export function tierBlockedByApprovalMix(
+  ticket: Pick<ITicket, "id" | "requiresApproval">,
+  tickets: readonly Pick<ITicket, "id" | "requiresApproval">[],
+  quantities: Record<string, number>,
+): boolean {
+  if ((quantities[ticket.id] ?? 0) > 0) return false;
+  const mode = selectionMode(tickets, quantities);
+  if (mode === null) return false;
+  return tierRequiresApproval(ticket) ? mode === "purchase" : mode === "request";
+}
+
+/** The fields of a `POST /public/events/:id/orders` response the routing reads. */
+export interface TicketOrderRoutingInput {
+  isFreeCheckout?: boolean;
+  awaitingApproval?: boolean;
+  totalAmount?: number | string | null;
+}
+
+/**
+ * Where the checkout goes once the order row exists.
+ *
+ *   complete  nothing to pay: a free purchase (passes minted, `isFreeCheckout`)
+ *             or a FREE REQUEST (already `pending_approval`, `isFreeCheckout`
+ *             false, `awaitingApproval` true, total 0). Both hand the order id
+ *             to `onComplete`, and the host navigates to the finalise page,
+ *             which renders the right outcome off the order's own status.
+ *   payment   there is money on it: start the charge. A priced request runs
+ *             the payment step exactly as a sale does; only the wording and
+ *             the settlement differ, and start-payment says which.
+ *
+ * `isFreeCheckout` wins outright, as it always has. The free-request branch is
+ * keyed on the TOTAL, not on `awaitingApproval` alone, because a priced
+ * request also carries `awaitingApproval: true` and must still reach the card.
+ */
+export function nextStepAfterTicketOrder(order: TicketOrderRoutingInput): "complete" | "payment" {
+  if (order.isFreeCheckout) return "complete";
+  if (order.awaitingApproval === true) {
+    const total = Number(order.totalAmount ?? 0);
+    if (!Number.isFinite(total) || total <= 0) return "complete";
+  }
+  return "payment";
+}

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

@@ -22,6 +22,12 @@ import { checkoutAmounts, isPayWhatYouWant, resolveUnitPrice, ticketSubtotals }
 import { parseMembershipGateError, type MembershipGateRefusal } from "../../format/membershipGate";
 import { readAttributionRef } from "../../../utils/attribution";
 import { readLanding } from "../../../utils/landing";
+import {
+  eventHasApprovalTiers,
+  nextStepAfterTicketOrder,
+  selectionRequiresApproval,
+  tierBlockedByApprovalMix,
+} from "./ticketApproval";
 
 export type EventCheckoutStep = "tickets" | "details" | "payment";
 
@@ -32,7 +38,10 @@ export interface UseEventCheckoutOptions {
   finalisePath?: (slug: string, orderId: string) => string;
   /** Called when a FREE order completes in-app — the host navigates however it
    * wants (e.g. its router), instead of Forge doing a `window.location` redirect.
-   * Omit to keep the default redirect. */
+   * Omit to keep the default redirect. Also fired for a FREE TICKET REQUEST
+   * (`awaitingApproval` with nothing to pay), which has no payment step either:
+   * the finalise page it lands on reads the order's status and renders
+   * "request received". */
   onComplete?: (info: { slug: string; orderId: string }) => void;
 }
 
@@ -179,6 +188,27 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     [selectedTickets],
   );
 
+  /**
+   * Ticket requests (curated access, feature 3).
+   *
+   * `hasApprovalTiers` says the event carries one at all; `awaitingApproval`
+   * says THIS selection is a request rather than a purchase, which is what the
+   * primary button ("Request tickets") and the payment wording read. One order
+   * is either, never both: `isTierBlockedByApprovalMix` is what the picker
+   * disables the `+` on, so the server's mixed-cart refusal is never reached.
+   */
+  const hasApprovalTiers = eventHasApprovalTiers(event);
+  const awaitingApproval = useMemo(
+    () => selectionRequiresApproval(event?.tickets ?? [], selectedTickets),
+    [event, selectedTickets],
+  );
+  const isTierBlockedByApprovalMix = (ticketId: string) => {
+    const ticket = event?.tickets.find((t) => t.id === ticketId);
+    return ticket ? tierBlockedByApprovalMix(ticket, event?.tickets ?? [], selectedTickets) : false;
+  };
+  /** When the request lapses if the organiser does not decide, from the order response. */
+  const [requestExpiresAt, setRequestExpiresAt] = useState<string | null>(null);
+
   /**
    * The artist's booking fee (1.4) — the thing the buyer was charged and never
    * told about, on any surface, on either rendering stack.
@@ -212,6 +242,13 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
   // rejects those with "quantity must be positive").
   const setTicketQty = (ticketId: string, qty: number) =>
     setSelectedTickets((prev) => {
+      // A request and a purchase cannot share an order. The picker disables
+      // the control, and this refuses the write too, so a host that drives the
+      // hook from its own UI cannot build the cart the server will refuse.
+      if (qty > 0 && (prev[ticketId] ?? 0) === 0 && event) {
+        const ticket = event.tickets.find((t) => t.id === ticketId);
+        if (ticket && tierBlockedByApprovalMix(ticket, event.tickets, prev)) return prev;
+      }
       const next = { ...prev };
       if (qty > 0) next[ticketId] = qty;
       else delete next[ticketId];
@@ -253,6 +290,14 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
       return false;
     }
     if (!event) return false;
+    // A request is not a purchase and cannot ride in a bundle: the bundle
+    // checkout forces payment and the API refuses approval tiers in one. Sent
+    // to the cart it would fail at the end of a longer journey, so it is
+    // refused here, and the surface hides the exit for a request anyway.
+    if (awaitingApproval) {
+      setError("Tickets that need our approval are requested on their own.");
+      return false;
+    }
     setError(null);
     setTickets({
       eventId: event.id,
@@ -372,12 +417,15 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
       // legitimately reports 0 — falling back to the estimate there would put a
       // fee on a comp.
       setServerFeeAmount(data.feeAmount ?? 0);
+      setRequestExpiresAt(data.requestExpiresAt ?? null);
       const origin = typeof window !== "undefined" ? window.location.origin : "";
       const ru = `${origin}${finalisePath(slug, data.orderId)}`;
       setReturnUrl(ru);
-      if (data.isFreeCheckout) {
-        // Free order — no payment. Hand navigation to the host if it asked, else
-        // default to an in-app redirect to the finalise page.
+      if (nextStepAfterTicketOrder(data) === "complete") {
+        // Nothing to pay: a free order, or a free ticket REQUEST that is already
+        // `pending_approval`. Hand navigation to the host if it asked, else
+        // default to an in-app redirect to the finalise page, which renders the
+        // right outcome off the order's own status.
         if (opts.onComplete) opts.onComplete({ slug, orderId: data.orderId });
         else if (typeof window !== "undefined") window.location.href = ru;
         return;
@@ -436,6 +484,7 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     // subtotal, so keeping it would understate the fee on the fresh, full-price
     // order the next `continueToPayment` creates.
     setServerFeeAmount(null);
+    setRequestExpiresAt(null);
     setStep("details");
   };
 
@@ -493,6 +542,27 @@ export function useEventCheckout(slug?: string, opts: UseEventCheckoutOptions =
     /** What each selected PWYW tier will actually be charged, per unit. */
     effectiveAmounts,
     ticketCount,
+    /**
+     * Ticket requests (curated access, feature 3). `hasApprovalTiers`: the
+     * event carries at least one tier the organiser approves. `awaitingApproval`:
+     * THIS selection is a request, so the primary button reads "Request
+     * tickets", the pay button "Authorize", and nothing is sold until the
+     * organiser decides. `isTierBlockedByApprovalMix(id)`: the tier cannot join
+     * the current selection because one order is either a request or a
+     * purchase, never both. `requestExpiresAt`: when an undecided request
+     * lapses, once the order exists.
+     */
+    hasApprovalTiers,
+    awaitingApproval,
+    isTierBlockedByApprovalMix,
+    requestExpiresAt,
+    /**
+     * From start-payment: `"deferred"` on a priced request, so the payment
+     * renderer can label the button "Authorize" and say the card is charged
+     * only on approval. Undefined on a sale.
+     */
+    settlement: flow.settlement,
+    deferredStrategy: flow.deferredStrategy,
     // The server's figure wins the moment there is one: start-payment first,
     // then the order response (which is already net of any discount), and only
     // the locally summed ticket prices before either exists.

package/src/ui/headless/index.ts

@@ -53,6 +53,17 @@ 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";
+// Ticket requests (curated access): the pure decisions behind the picker and
+// the post-order routing, for a host that drives the hook from its own UI.
+export {
+  eventHasApprovalTiers,
+  nextStepAfterTicketOrder,
+  selectionMode,
+  selectionRequiresApproval,
+  tierBlockedByApprovalMix,
+  tierRequiresApproval,
+  type TicketOrderRoutingInput,
+} from "./event/ticketApproval";
 export {
   usePresaleCode,
   type PresaleCodeField,
@@ -89,6 +100,29 @@ export {
   type MembershipCheckoutStep,
   type BillingCycle,
 } from "./membership/useMembershipCheckout";
+// Curated access (invite-only and apply-to-join tiers): the pure decisions the
+// tier card, the checkout and the account page share.
+export {
+  canWithdrawMembershipApplication,
+  MEMBERSHIP_APPLICATION_MESSAGE_MAX,
+  membershipApplicationOutcome,
+  tierCardAction,
+  tierUsesApplication,
+  type MembershipApplicationOutcome,
+  type MembershipTierCardAction,
+} from "./membership/membershipApplication";
+export {
+  formatTrialDate,
+  isMembershipInTrial,
+  tierTrialDays,
+  trialEndDate,
+} from "./membership/membershipTrial";
+// Tier questionnaires: which questions a checkout asks and what it sends.
+export {
+  buildQuestionnaireAnswers,
+  firstMissingAnswer,
+  tierQuestionnaire,
+} from "./membership/membershipQuestionnaire";
 export { useInvoicePayment, type UseInvoicePaymentOptions } from "./invoice/useInvoicePayment";
 export { usePaymentLinkPayment, type UsePaymentLinkPaymentOptions } from "./paymentLink/usePaymentLinkPayment";
 export { useBroadcastWatch } from "./broadcast/useBroadcastWatch";