@tribe-nest/forge 3.54.0 → 3.58.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.54.0",
+  "version": "3.58.0",
   "publishConfig": {
     "access": "public"
   },
@@ -31,9 +31,11 @@
     "@stripe/react-stripe-js": "^3.8.0",
     "@stripe/stripe-js": "^7.6.1",
     "@tanstack/react-query": "^5.62.7",
-    "@tribe-nest/media-client": "^0.4.0",
+    "@tribe-nest/media-client": "^0.5.0",
     "@tribe-nest/media-protocol": "^1.0.0",
+    "@tribe-nest/seating-core": "^1.0.0",
     "axios": "^1.7.9",
+    "libphonenumber-js": "^1.13.13",
     "lucide-react": "^0.510.0",
     "react-hook-form": "^7.60.0",
     "react-markdown": "^10.1.0",

package/src/_tests/workspaceAliases.ts

@@ -34,6 +34,7 @@ export const WORKSPACE_SOURCE_ALIASES: { find: RegExp; replacement: string }[] =
   ["@tribe-nest/media-client/protocol", "../../../media-client/src/protocol.ts"],
   ["@tribe-nest/media-protocol", "../../../media-protocol/src/index.ts"],
   ["@tribe-nest/media-protocol/token", "../../../media-protocol/src/token.ts"],
+  ["@tribe-nest/seating-core", "../../../seating-core/src/index.ts"],
 ].map(([specifier, path]) => ({
   find: new RegExp(`^${specifier!.replace(/[/\\^$*+?.()|[\]{}]/g, "\\$&")}$`),
   replacement: fileURLToPath(new URL(path!, import.meta.url)),

package/src/contexts/CartContext.tsx

@@ -75,6 +75,29 @@ export type CartItem = {
  * whole existing shop, on both rendering stacks, is unaffected; the two places
  * that genuinely need both (the cart panel and checkout) read both lists.
  */
+/** One seat a cart line holds, with the label every surface prints. */
+export type CartSeat = { id: string; label: string };
+
+/**
+ * Display and order data for one tier of a ticket selection.
+ *
+ * `seatIds` and `seats` are present on a RESERVED-SEATING tier only: the
+ * event seat ids the buyer picked on the map (what the bundle checkout sends
+ * as the line's `seatIds`, in this order) and the same seats with the labels
+ * the cart, the checkout summary and the confirmation print ("Stalls · Row A
+ * · Seat 12"). The line's quantity IS `seatIds.length` on such a tier, so the
+ * cart never offers a stepper for it: changing seats happens on the event
+ * page. Absent on a general admission tier, and on carts saved before seats
+ * could ride in them.
+ */
+export type TicketCartLineMeta = {
+  title: string;
+  price: number;
+  pwywAmount?: number;
+  seatIds?: string[];
+  seats?: CartSeat[];
+};
+
 export type TicketCartItem = {
   eventId: string;
   eventSlug: string;
@@ -92,7 +115,7 @@ export type TicketCartItem = {
    * endpoint treats a line's `price` as display-only and never charges it; the
    * chosen amount has to arrive in a field the server actually reads.
    */
-  ticketMeta: Record<string, { title: string; price: number; pwywAmount?: number }>;
+  ticketMeta: Record<string, TicketCartLineMeta>;
   /**
    * The event's RESOLVED booking fee, captured when the modal put the tickets
    * here, so the cart checkout can show the fee line the buyer will be charged
@@ -142,6 +165,17 @@ interface CartContextType {
   setTickets: (item: TicketCartItem) => void;
   /** Drops the selection AND every add-on attached to that event. */
   removeTickets: (eventId: string) => void;
+  /**
+   * Take named seats OUT of an event's selection, without opening the drawer.
+   *
+   * The bundle checkout calls this when seats in the cart were taken by
+   * another buyer: the taken seats leave their tier line (its quantity is its
+   * seat count, so it shrinks with them), a tier left with no seat leaves the
+   * selection, and an event left with no tier leaves the cart with its add-ons,
+   * exactly as `removeTickets` would. Seats are never substituted here: the
+   * buyer goes back to the event's picker to choose again.
+   */
+  removeTicketSeats: (eventId: string, seatIds: string[]) => void;
   hasTicketsFor: (eventId: string) => boolean;
   /** Products + tickets, for the header badge. */
   itemCount: number;
@@ -175,6 +209,40 @@ function readAddonContext(): AttachedTo | undefined {
   }
 }
 
+/**
+ * An event's selection with `seatIds` taken out of it, or `null` when nothing
+ * is left. Pure, so the checkout's tests can assert it without a provider.
+ *
+ * A tier's quantity follows its seat count, because on a seated tier the two
+ * are one number. A general admission tier (no `seatIds` on its meta) is never
+ * touched: the ids belong to a seated tier by construction.
+ */
+export function pruneSeatsFromTicketItem(item: TicketCartItem, seatIds: readonly string[]): TicketCartItem | null {
+  const gone = new Set(seatIds);
+  const tickets: Record<string, number> = {};
+  const ticketMeta: Record<string, TicketCartLineMeta> = {};
+  for (const [ticketId, qty] of Object.entries(item.tickets)) {
+    const meta = item.ticketMeta[ticketId];
+    if (!meta?.seatIds) {
+      if (qty > 0) {
+        tickets[ticketId] = qty;
+        if (meta) ticketMeta[ticketId] = meta;
+      }
+      continue;
+    }
+    const keptIds = meta.seatIds.filter((id) => !gone.has(id));
+    if (keptIds.length === 0) continue;
+    tickets[ticketId] = keptIds.length;
+    ticketMeta[ticketId] = {
+      ...meta,
+      seatIds: keptIds,
+      seats: (meta.seats ?? []).filter((seat) => !gone.has(seat.id)),
+    };
+  }
+  if (Object.keys(tickets).length === 0) return null;
+  return { ...item, tickets, ticketMeta };
+}
+
 export function CartProvider({ children }: { children: ReactNode }) {
   const [cartItems, setCartItems] = useState<CartItem[]>([]);
   const [ticketItems, setTicketItems] = useState<TicketCartItem[]>([]);
@@ -339,10 +407,24 @@ export function CartProvider({ children }: { children: ReactNode }) {
     setCartItems((prev) => prev.filter((i) => i.attachedTo?.entityId !== eventId));
   }, []);
 
-  const hasTicketsFor = useCallback(
-    (eventId: string) => ticketItems.some((t) => t.eventId === eventId),
-    [ticketItems],
-  );
+  const removeTicketSeats = useCallback((eventId: string, seatIds: string[]) => {
+    let emptied = false;
+    setTicketItems((prev) =>
+      prev.flatMap((item) => {
+        if (item.eventId !== eventId) return [item];
+        const next = pruneSeatsFromTicketItem(item, seatIds);
+        if (next) return [next];
+        emptied = true;
+        return [];
+      }),
+    );
+    // The add-ons go with the base, as in `removeTickets`. Read from the
+    // flatMap above rather than from `ticketItems`, so a stale closure cannot
+    // keep an orphaned add-on that the server would refuse.
+    setCartItems((prev) => (emptied ? prev.filter((i) => i.attachedTo?.entityId !== eventId) : prev));
+  }, []);
+
+  const hasTicketsFor = useCallback((eventId: string) => ticketItems.some((t) => t.eventId === eventId), [ticketItems]);
 
   const clearCart = () => {
     setCartItems([]);
@@ -371,6 +453,7 @@ export function CartProvider({ children }: { children: ReactNode }) {
         ticketItems,
         setTickets,
         removeTickets,
+        removeTicketSeats,
         hasTicketsFor,
         itemCount,
         isBundle,

package/src/data/queries/useCallBreakouts.ts

@@ -0,0 +1,112 @@
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { useCallback, useMemo, useState } from "react";
+
+import type { BreakoutParticipant, BreakoutRoomSummary, CallStageBreakouts } from "../../ui/media/callBreakouts";
+import { useForge } from "../../provider/ForgeProvider";
+
+/**
+ * The PUBLIC lane's `CallStageBreakouts` adapter: the reference implementation
+ * of the shape the stage renders.
+ *
+ * Everything hangs off the CALL's address (`/video-calls/:id/breakouts`): one
+ * GET describes the rooms and this seat's place in them, and every mutation
+ * answers with the same describe, so the query is replaced from the response
+ * rather than refetched (a refetch as well would race it). Admin composes its
+ * own adapter against the dashboard's client; the SHAPE is the seam.
+ *
+ * ## Who polls
+ *
+ * The host's view carries live counts that come from the media plane, so the
+ * host polls every few seconds. An attendee's list is a handful of names that
+ * change only when the host acts, and there can be forty of them: they read
+ * once, and the stage calls `refresh()` when the rooms tab is open and after
+ * every reconnect (which is what a move is), so they are never stale where it
+ * matters and never a request per viewer per few seconds where it does not.
+ */
+
+/** The server's describe, the wire shape the adapter is built from. */
+export type CallBreakoutsDescribe = {
+  canManage: boolean;
+  active: boolean;
+  current: { publicId: string; name: string } | null;
+  main: { participantCount: number; participants: BreakoutParticipant[] };
+  rooms: BreakoutRoomSummary[];
+};
+
+export const CALL_BREAKOUTS_POLL_MS = 5000;
+
+/** The server's own sentence when it gave one, else the thrown error's. */
+export const breakoutErrorMessage = (cause: unknown): string => {
+  const response = (cause as { response?: { data?: { message?: unknown } } } | undefined)?.response;
+  const message = response?.data?.message;
+  if (typeof message === "string" && message.trim()) return message;
+  return cause instanceof Error && cause.message ? cause.message : "";
+};
+
+export function useCallBreakouts(callId: string | undefined): CallStageBreakouts | undefined {
+  const { client } = useForge();
+  const queryClient = useQueryClient();
+  const [pending, setPending] = useState(false);
+
+  const queryKey = useMemo(() => ["call-breakouts", callId] as const, [callId]);
+  const base = `/video-calls/${callId}/breakouts`;
+
+  const query = useQuery<CallBreakoutsDescribe>({
+    queryKey,
+    queryFn: async () => (await client.get(base)).data,
+    enabled: !!callId && !!client,
+    // Only the host's view has live numbers in it. See the docblock.
+    refetchInterval: (state) => (state.state.data?.canManage ? CALL_BREAKOUTS_POLL_MS : false),
+  });
+
+  const act = useCallback(
+    async (request: () => Promise<{ data: CallBreakoutsDescribe }>) => {
+      setPending(true);
+      try {
+        const res = await request();
+        queryClient.setQueryData(queryKey, res.data);
+      } catch (cause) {
+        throw new Error(breakoutErrorMessage(cause));
+      } finally {
+        setPending(false);
+      }
+    },
+    [queryClient, queryKey],
+  );
+
+  const create = useCallback(
+    (input: { count: number; assign: "auto" | "manual" }) => act(() => client.post(base, input)),
+    [act, client, base],
+  );
+  const assign = useCallback(
+    (identity: string, roomPublicId: string | null) => act(() => client.put(`${base}/assignment`, { identity, roomPublicId })),
+    [act, client, base],
+  );
+  const moveSelf = useCallback(
+    (roomPublicId: string | null) => act(() => client.put(`${base}/me`, { roomPublicId })),
+    [act, client, base],
+  );
+  const closeAll = useCallback(() => act(() => client.delete(base)), [act, client, base]);
+  const refresh = useCallback(() => {
+    void queryClient.invalidateQueries({ queryKey });
+  }, [queryClient, queryKey]);
+
+  return useMemo<CallStageBreakouts | undefined>(() => {
+    if (!callId) return undefined;
+    const data = query.data;
+    return {
+      ready: !!data,
+      canManage: data?.canManage ?? false,
+      active: data?.active ?? false,
+      current: data?.current ?? null,
+      main: data?.main ?? { participantCount: 0, participants: [] },
+      rooms: data?.rooms ?? [],
+      pending,
+      create,
+      assign,
+      moveSelf,
+      closeAll,
+      refresh,
+    };
+  }, [callId, query.data, pending, create, assign, moveSelf, closeAll, refresh]);
+}

package/src/data/queries/useCheckouts.ts

@@ -34,6 +34,14 @@ export type CheckoutLineInput =
        * server clamps it against the tier's floor).
        */
       pwywAmount?: number;
+      /**
+       * The EVENT seat ids the buyer picked, on a reserved-seating tier only:
+       * exactly `quantity` of them, in the order chosen. The server refuses a
+       * seated tier's line without them (400 `seats_required`) and answers 409
+       * `SEATS_TAKEN` with `details.eventSeatIds` when any has gone to another
+       * buyer since. Absent on a general admission tier.
+       */
+      seatIds?: string[];
       title: string;
       coverImage?: string;
     };
@@ -57,8 +65,13 @@ export function cartToCheckoutLines(cartItems: CartItem[], ticketItems: TicketCa
         // display-only and never charges. This is the field the server forwards
         // into the ticket order — dropping it would charge the tier's floor and
         // still return 200, so the buyer would be quietly undercharged.
-        ...(t.ticketMeta[ticketId]?.pwywAmount != null
-          ? { pwywAmount: t.ticketMeta[ticketId]?.pwywAmount }
+        ...(t.ticketMeta[ticketId]?.pwywAmount != null ? { pwywAmount: t.ticketMeta[ticketId]?.pwywAmount } : {}),
+        // The seats ride on the line: a seated tier's order is created FROM
+        // this, and without them the server would either refuse the line or
+        // (on an older build) seat the buyer anywhere, which is the one thing
+        // a buyer who chose on a map must never get silently.
+        ...((t.ticketMeta[ticketId]?.seatIds?.length ?? 0) > 0
+          ? { seatIds: [...t.ticketMeta[ticketId]!.seatIds!] }
           : {}),
         title: t.ticketMeta[ticketId]?.title ?? t.eventTitle,
         coverImage: t.coverImage,

package/src/data/queries/useCoachingProducts.ts

@@ -7,7 +7,20 @@ export interface GetCoachingProductsParams {
   query?: string;
 }
 
-export function useGetCoachingProducts(params?: GetCoachingProductsParams, enabled = true) {
+export function useGetCoachingProducts(
+  params?: GetCoachingProductsParams,
+  enabled = true,
+  options?: {
+  /**
+   * The page a server render already fetched.
+   *
+   * Seeds the cache so the first client render matches the markup and nothing
+   * is refetched. Must be built with the SAME params as the key below, or the
+   * seed belongs to a different query and is ignored.
+   */
+    initialData?: PaginatedData<CoachingProduct>;
+  },
+) {
   const { client, profileId } = useForge();
 
   return useQuery<PaginatedData<CoachingProduct>>({
@@ -23,6 +36,7 @@ export function useGetCoachingProducts(params?: GetCoachingProductsParams, enabl
       return res.data;
     },
     enabled: !!profileId && !!client && enabled,
+    initialData: options?.initialData,
   });
 }
 

package/src/data/queries/useCourses.ts

@@ -90,7 +90,20 @@ export interface GetCoursesParams {
   query?: string;
 }
 
-export function useGetCourses(params?: GetCoursesParams, enabled = true) {
+export function useGetCourses(
+  params?: GetCoursesParams,
+  enabled = true,
+  options?: {
+  /**
+   * The page a server render already fetched.
+   *
+   * Seeds the cache so the first client render matches the markup and nothing
+   * is refetched. Must be built with the SAME params as the key below, or the
+   * seed belongs to a different query and is ignored.
+   */
+    initialData?: PaginatedData<PublicCourse>;
+  },
+) {
   const { client, profileId } = useForge();
 
   return useQuery<PaginatedData<PublicCourse>>({
@@ -106,6 +119,7 @@ export function useGetCourses(params?: GetCoursesParams, enabled = true) {
       return res.data;
     },
     enabled: !!profileId && !!client && enabled,
+    initialData: options?.initialData,
   });
 }
 

package/src/data/queries/useEvents.ts

@@ -1,9 +1,20 @@
 import type { AppliedDiscountCoupon, IEvent } from "../../types/models";
+import type { SeatAttributes, SeatMapDocument } from "@tribe-nest/seating-core";
 import { useForge } from "../../provider/ForgeProvider";
 import { useMutation, useQuery } from "@tanstack/react-query";
 
 /** All published events for the profile. */
-export function useEvents() {
+export function useEvents(options?: {
+  /**
+   * The list a server render already fetched (`fetchEventsServer`).
+   *
+   * Seeds the cache so the first client render shows the same events as the
+   * markup and nothing is refetched. Without it the list page renders a
+   * spinner on the server, which is what a crawler sees and what a fan sees
+   * for as long as the request takes.
+   */
+  initialData?: IEvent[];
+}) {
   const { client, profileId } = useForge();
 
   return useQuery<IEvent[]>({
@@ -15,6 +26,7 @@ export function useEvents() {
       return res.data;
     },
     enabled: !!profileId && !!client,
+    initialData: options?.initialData,
   });
 }
 
@@ -70,8 +82,75 @@ export function useEvent(
   });
 }
 
+/**
+ * One sellable seat of an event, as the public seating read publishes it.
+ *
+ * `id` is the EVENT seat (what an order names); `sourceSeatId` is the seat's id
+ * inside the frozen layout, which is how a renderer joins it to a `<circle>`.
+ * Held, sold and blocked all read `unavailable`: a buyer must not be able to
+ * tell a house seat from a sold one.
+ */
+export type PublicEventSeat = {
+  id: string;
+  sourceSeatId: string;
+  eventTicketId: string;
+  status: "available" | "unavailable";
+  attributes: SeatAttributes;
+};
+
+/** `GET /public/events/:id/seating`. `null` when the event has no seat map. */
+export type PublicEventSeating = {
+  /** The layout frozen at bind time. Coordinates are absolute and baked. */
+  layout: SeatMapDocument;
+  /** Layout category key -> the ticket tier that prices it for this event. */
+  tierMapping: Record<string, string>;
+  seats: PublicEventSeat[];
+};
+
+/**
+ * The seat map and live availability for a reserved-seating event.
+ *
+ * `Cache-Control: no-store` on the server, and `pollMs` here, because the
+ * whole value of the read is that it is CURRENT: a seat somebody else took ten
+ * seconds ago must not still look free. Disabled (no request at all) unless
+ * `enabled`, so an event page that never opens the picker never polls.
+ */
+export function useEventSeatingQuery(
+  eventId?: string,
+  options: {
+    enabled?: boolean;
+    /** Refetch interval while enabled. `false` (or 0) polls nothing. */
+    pollMs?: number | false;
+  } = {},
+) {
+  const { client, profileId } = useForge();
+  const enabled = (options.enabled ?? true) && !!eventId && !!profileId && !!client;
+  return useQuery<PublicEventSeating | null>({
+    queryKey: ["event-seating", eventId, profileId],
+    queryFn: async () => {
+      const res = await client.get(`/public/events/${eventId}/seating`, { params: { profileId } });
+      // An empty body (204, or an older API with no route) reads as "no map".
+      return (res.data ?? null) as PublicEventSeating | null;
+    },
+    enabled,
+    staleTime: 0,
+    refetchInterval: enabled && options.pollMs ? options.pollMs : false,
+  });
+}
+
 export type CreateEventOrderInput = {
   items: Record<string, number>;
+  /**
+   * ticketId -> the EVENT seat ids (`PublicEventSeat.id`) the buyer picked, for
+   * every tier that sells reserved seats (seating wave 2).
+   *
+   * A seated tier requires exactly `items[ticketId]` seats; a general
+   * admission tier must not carry any. Omit the key entirely on an event with
+   * no seat map, so an ordinary purchase posts the body it always did. A 409
+   * `errors.event.seats_taken` with `details.eventSeatIds` means those seats
+   * went to somebody else between the read and the order.
+   */
+  seats?: Record<string, string[]>;
   /**
    * ticketId → the buyer's chosen amount, PER UNIT, on a pay-what-you-want
    * tier. Ignored server-side for any tier that is not PWYW, and clamped up to

package/src/data/queries/useMembership.ts

@@ -1,22 +1,60 @@
-import type { MembershipTier } from "../../types/models";
+import type {
+  ApplyForMembershipResult,
+  MembershipApplication,
+  MembershipInviteInfo,
+  MembershipTier,
+  QuestionnaireAnswer,
+} from "../../types/models";
 import { useForge } from "../../provider/ForgeProvider";
-import { useQuery } from "@tanstack/react-query";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+
+/**
+ * The membership invite token this visitor arrived holding, read from the
+ * `invite` search param of the CURRENT url (the invite email links to
+ * `/i/membership/checkout?membershipTierId=X&invite=TOKEN`).
+ *
+ * Deliberately not stored anywhere: it is a bearer credential, and the durable
+ * copy is the email. Returns undefined on the server and when absent.
+ */
+export const readMembershipInviteFromUrl = (search?: string): string | undefined => {
+  const raw = search ?? (typeof window === "undefined" ? "" : window.location.search);
+  if (!raw) return undefined;
+  const token = new URLSearchParams(raw).get("invite")?.trim();
+  return token ? token : undefined;
+};
+
+export interface UseGetMembershipTiersOptions {
+  enabled?: boolean;
+  /**
+   * An invite token to forward, so an invite-only tier it unlocks is listed.
+   * Omitted (undefined), the `invite` search param of the current url is used;
+   * `null` forwards nothing even when the url carries one.
+   */
+  inviteToken?: string | null;
+}
 
 /**
  * `opts.enabled` gates the request on top of the usual profile/client checks —
  * for a caller that only needs tier NAMES when something is actually gated, and
  * must not add a request to every ungated storefront. Defaults to on, so every
  * existing caller is unchanged.
+ *
+ * Invite-only tiers are omitted by the server unless the request carries a
+ * live invite token for them, so the token is part of the query key.
  */
-export function useGetMembershipTiers(opts: { enabled?: boolean } = {}) {
+export function useGetMembershipTiers(opts: UseGetMembershipTiersOptions = {}) {
   const { client, profileId } = useForge();
+  const inviteToken = opts.inviteToken === undefined ? readMembershipInviteFromUrl() : (opts.inviteToken ?? undefined);
 
   return useQuery<MembershipTier[]>({
-    queryKey: ["membership-tiers", profileId],
+    // The token is appended only when present, so the no-invite key stays the
+    // one every existing cache seed (SSR, specs) already writes.
+    queryKey: inviteToken ? ["membership-tiers", profileId, inviteToken] : ["membership-tiers", profileId],
     queryFn: async () => {
       const res = await client.get("/public/membership-tiers", {
         params: {
           profileId: profileId,
+          ...(inviteToken ? { inviteToken } : {}),
         },
       });
       return res.data;
@@ -24,3 +62,137 @@ export function useGetMembershipTiers(opts: { enabled?: boolean } = {}) {
     enabled: !!profileId && !!client && opts.enabled !== false,
   });
 }
+
+// ---- Invites -------------------------------------------------------------------
+
+/**
+ * What a membership invite link is for: the tier and the invited email, so the
+ * landing page can name both before asking for anything.
+ *
+ * A dead token (unknown, expired, revoked or already accepted) is a 404, which
+ * is an ANSWER rather than a transient failure, so it is not retried. Tell the
+ * two apart with `isMembershipInviteDead(error)`.
+ */
+export function useMembershipInviteInfo(token?: string | null) {
+  const { client } = useForge();
+
+  return useQuery<MembershipInviteInfo>({
+    queryKey: ["membership-invite-info", token ?? null],
+    queryFn: async () => {
+      const res = await client.get("/public/membership-invites/info", { params: { token } });
+      return res.data;
+    },
+    enabled: !!token && !!client,
+    retry: (count, error) => !isMembershipInviteDead(error) && count < 2,
+  });
+}
+
+/** True when an invite-info error means the invite is gone (404), not that the request failed. */
+export function isMembershipInviteDead(error: unknown): boolean {
+  return (error as { response?: { status?: number } } | null)?.response?.status === 404;
+}
+
+// ---- Applications ----------------------------------------------------------------
+
+export type ApplyForMembershipInput = {
+  membershipTierId: string;
+  /** Required on a paid tier. */
+  billingCycle?: "month" | "year";
+  /** Required on a paid tier; same floor/ceiling rules as a subscription. */
+  amount?: number;
+  /**
+   * A free-text note, up to 1000 characters. Still accepted by the server, but
+   * no current checkout sends it: the tier's questions replaced it.
+   */
+  message?: string;
+  /** Answers to the tier's questions. Required by the server when the tier has any. */
+  questionnaire?: QuestionnaireAnswer[];
+  /** Where Stripe returns after a redirect-based card confirmation. */
+  returnUrl?: string;
+};
+
+/** Invalidate everything an application changes: the tier cards and the fan's list. */
+function useInvalidateApplications() {
+  const queryClient = useQueryClient();
+  return () =>
+    Promise.all([
+      queryClient.invalidateQueries({ queryKey: ["membership-tiers"] }),
+      queryClient.invalidateQueries({ queryKey: ["my-membership-applications"] }),
+    ]);
+}
+
+/**
+ * Apply to join an `application` tier.
+ *
+ * A free tier comes back `pending` with nothing more to do. A paid tier comes
+ * back `card_pending` with `requiresCard` and a SetupIntent `clientSecret`: the
+ * card is saved, not charged, and after the renderer confirms it the caller
+ * calls `useConfirmMembershipApplication`. Applying again while one is open
+ * returns that one.
+ */
+export function useApplyForMembership() {
+  const { client, profileId } = useForge();
+  const invalidate = useInvalidateApplications();
+
+  return useMutation<ApplyForMembershipResult, unknown, ApplyForMembershipInput>({
+    mutationFn: async (body) => {
+      const res = await client.post("/public/membership-applications", { ...body, profileId });
+      return res.data;
+    },
+    onSuccess: () => void invalidate(),
+  });
+}
+
+/**
+ * Tell the server the card step finished. Idempotent. The application comes
+ * back `pending` once the provider shows the card saved, still `card_pending`
+ * if it does not yet, or `withdrawn` with `closedReason: "tier_full"` when the
+ * last seat went in the meantime.
+ */
+export function useConfirmMembershipApplication() {
+  const { client, profileId } = useForge();
+  const invalidate = useInvalidateApplications();
+
+  return useMutation<{ application: MembershipApplication }, unknown, { applicationId: string }>({
+    mutationFn: async ({ applicationId }) => {
+      const res = await client.post(`/public/membership-applications/${encodeURIComponent(applicationId)}/confirm`, {
+        profileId,
+      });
+      return res.data;
+    },
+    onSuccess: () => void invalidate(),
+  });
+}
+
+/** Withdraw an application that is still `card_pending` or `pending`. */
+export function useWithdrawMembershipApplication() {
+  const { client, profileId } = useForge();
+  const invalidate = useInvalidateApplications();
+
+  return useMutation<{ application: MembershipApplication }, unknown, { applicationId: string }>({
+    mutationFn: async ({ applicationId }) => {
+      const res = await client.post(`/public/membership-applications/${encodeURIComponent(applicationId)}/withdraw`, {
+        profileId,
+      });
+      return res.data;
+    },
+    onSuccess: () => void invalidate(),
+  });
+}
+
+/**
+ * The signed-in fan's applications on this profile, newest first. Pass the
+ * account id so the query waits for sign-in and is keyed per account.
+ */
+export function useMyMembershipApplications(accountId?: string) {
+  const { client, profileId } = useForge();
+
+  return useQuery<MembershipApplication[]>({
+    queryKey: ["my-membership-applications", accountId, profileId],
+    queryFn: async () => {
+      const res = await client.get("/public/membership-applications/mine", { params: { profileId } });
+      return res.data;
+    },
+    enabled: !!accountId && !!profileId && !!client,
+  });
+}