@tribe-nest/forge 3.2.0 → 3.9.0

package/src/data/queries/useEventWaitlist.ts

@@ -0,0 +1,429 @@
+import { useMemo, useSyncExternalStore } from "react";
+import { useMutation, useQueries, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useForge } from "../../provider/ForgeProvider";
+import { useEvents } from "./useEvents";
+import type { IEvent, ITicket } from "../../types/models";
+
+/**
+ * Events 2.6 — the buyer's side of the ticket waitlist.
+ *
+ * Lives in Forge rather than in either app because both rendering surfaces —
+ * the client PWA and code websites — need exactly this, and a second copy is
+ * how the two drift (the same reason `useMyTickets` lives here).
+ *
+ * ## The endpoints
+ *
+ * ```
+ * POST   /public/events/:eventId/waitlist              join      → WaitlistEntry (201)
+ * GET    /public/events/:eventId/waitlist              mine      → WaitlistEntry[]  (401 if anonymous)
+ * GET    /public/events/:eventId/waitlist/:entryId     one       → WaitlistEntry
+ * DELETE /public/events/:eventId/waitlist/:entryId     leave     → { id, status, leftAt }
+ * ```
+ *
+ * `:eventId` is the event's **UUID**, not its slug — the waitlist service
+ * resolves the event by id only (unlike `GET /public/events/:idOrSlug`). Every
+ * hook here therefore takes an id, and the UI passes `event.id` off an event it
+ * already loaded.
+ *
+ * ## Three rules the server owns, which this file deliberately does not mirror
+ *
+ * 1. **Eligibility.** Joining is refused unless the tier has no seats left. The
+ *    UI decides where to *draw* a join control (see `isTicketSoldOut`) but never
+ *    pre-judges the answer — a refusal comes back as the server's own message.
+ * 2. **Idempotence.** Re-submitting a join returns the EXISTING place, with its
+ *    ORIGINAL quantity, and a 201. That is a success, not a duplicate error, and
+ *    callers must present it as "you're on the list".
+ * 3. **Position.** `position` is 1-based while queueing and `null` once the row
+ *    leaves the queue — which includes holding an open offer. An offer is not a
+ *    queue place; never render a position for one.
+ */
+
+/** The lifecycle, restated (Forge cannot import from the API). */
+export type WaitlistStatus = "waiting" | "notified" | "converted" | "left" | "expired";
+
+/** What an offer looks like to the person holding it. Computed server-side. */
+export type WaitlistOffer = {
+  /** The buyer may buy RIGHT NOW. */
+  offerOpen: boolean;
+  /** Whole seconds left when the server answered. `null` when there is no offer. */
+  secondsRemaining: number | null;
+  /** The instant the offer lapses — the single most important field here. */
+  claimExpiresAt: string | null;
+};
+
+export type WaitlistEntry = {
+  id: string;
+  eventId: string;
+  eventTicketId: string;
+  status: WaitlistStatus | string;
+  quantity: number;
+  /** 1-based while queueing; `null` once the row leaves the queue (offer, buy, exit). */
+  position: number | null;
+  createdAt: string;
+  offer: WaitlistOffer;
+};
+
+export type JoinWaitlistInput = {
+  eventTicketId: string;
+  /**
+   * Required for an anonymous join, IGNORED for a signed-in one — the server
+   * takes a signed-in caller's address from their account. Callers should omit
+   * it entirely when signed in rather than send a value that cannot take effect.
+   */
+  email?: string;
+  firstName?: string;
+  lastName?: string;
+  /** 1–20. Bounded server-side; the form mirrors the bounds as input limits only. */
+  quantity?: number;
+};
+
+export type LeaveWaitlistResult = { id: string; status: string; leftAt: string | null };
+
+/** Still in play — neither bought nor dropped out. Matches the API's `LIVE_WAITLIST_STATUSES`. */
+export const LIVE_WAITLIST_STATUSES: WaitlistStatus[] = ["waiting", "notified"];
+
+export const isLiveWaitlistEntry = (entry: Pick<WaitlistEntry, "status">): boolean =>
+  (LIVE_WAITLIST_STATUSES as string[]).includes(entry.status);
+
+// ── Where a join control may be DRAWN ────────────────────────────────────────
+
+/**
+ * Seats a buyer can still take, by the same arithmetic the purchase UI uses.
+ *
+ * Deliberately ignores `held` (units inside somebody else's live checkout) even
+ * though the server's waitlist rule subtracts it. The difference only ever makes
+ * this stricter: `quantity - sold <= 0` implies `quantity - sold - held <= 0`,
+ * so a tier this calls sold out is always one the server will accept a join for.
+ * Including `held` would do the opposite — offer a waitlist beside a "+" button
+ * the buyer can still press, on a tier that unfreezes minutes later.
+ */
+export const ticketSeatsRemaining = (ticket: Pick<ITicket, "quantity" | "sold">): number =>
+  Math.max(0, (ticket.quantity ?? 0) - (ticket.sold ?? 0));
+
+/**
+ * Should a waitlist join control be OFFERED for this tier?
+ *
+ * Presentation only. The server decides whether a join succeeds; this decides
+ * where it is worth asking, and is intentionally a subset of what the server
+ * would accept (see `ticketSeatsRemaining`, and the expiry note below).
+ *
+ * A tier whose sale window has closed is excluded: queueing for something that
+ * can no longer be sold means waiting for an email that will never arrive.
+ */
+export const isTicketSoldOut = (
+  ticket: Pick<ITicket, "quantity" | "sold" | "expiresAt" | "archivedAt">,
+  now: Date = new Date(),
+): boolean => {
+  if (ticket.archivedAt) return false;
+  if (ticket.expiresAt && new Date(ticket.expiresAt) <= now) return false;
+  return ticketSeatsRemaining(ticket) === 0;
+};
+
+/** Events whose waitlist can still take a sign-up. Mirrors the API's joinable set. */
+const JOINABLE_EVENT_STATUSES = ["scheduled", "on_sale", "sold_out"];
+
+export const isEventWaitlistOpen = (event: Pick<IEvent, "status">): boolean =>
+  JOINABLE_EVENT_STATUSES.includes(event.status);
+
+// ── The anonymous joiner's capability, remembered locally ────────────────────
+
+/**
+ * An anonymous entry is addressed by its id alone — an unguessable UUID, the
+ * same shape as an unsubscribe link. The durable copy is the email the server
+ * sends; this is a convenience so the browser that joined can show the place
+ * back on the next visit, and it is the ONLY reason a local store exists here.
+ *
+ * Signed-in callers never need it: their entries come from the list endpoint.
+ */
+const STORAGE_KEY = "tn.waitlist.entries";
+
+export type RememberedWaitlistEntry = { eventId: string; entryId: string };
+
+const readRemembered = (): RememberedWaitlistEntry[] => {
+  if (typeof window === "undefined") return [];
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY);
+    if (!raw) return [];
+    const parsed: unknown = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return [];
+    return parsed.filter(
+      (item): item is RememberedWaitlistEntry =>
+        !!item &&
+        typeof (item as RememberedWaitlistEntry).eventId === "string" &&
+        typeof (item as RememberedWaitlistEntry).entryId === "string",
+    );
+  } catch {
+    return [];
+  }
+};
+
+/**
+ * Cached so `useSyncExternalStore` gets a STABLE snapshot — returning a fresh
+ * array from every read would re-render forever. Invalidated on every write.
+ */
+let cache: RememberedWaitlistEntry[] | null = null;
+const listeners = new Set<() => void>();
+
+const snapshot = (): RememberedWaitlistEntry[] => {
+  if (!cache) cache = readRemembered();
+  return cache;
+};
+
+/** The server-rendered pass has no browser store; it must be empty and stable. */
+const EMPTY: RememberedWaitlistEntry[] = [];
+const serverSnapshot = (): RememberedWaitlistEntry[] => EMPTY;
+
+const subscribe = (listener: () => void) => {
+  listeners.add(listener);
+  return () => {
+    listeners.delete(listener);
+  };
+};
+
+const writeRemembered = (entries: RememberedWaitlistEntry[]) => {
+  cache = entries;
+  if (typeof window !== "undefined") {
+    try {
+      window.localStorage.setItem(STORAGE_KEY, JSON.stringify(entries));
+    } catch {
+      /* private mode / quota — the email is still the durable copy. */
+    }
+  }
+  listeners.forEach((listener) => listener());
+};
+
+/** Entry ids this browser joined with, optionally narrowed to one event. */
+export const getRememberedWaitlistEntries = (eventId?: string): RememberedWaitlistEntry[] => {
+  const all = snapshot();
+  return eventId ? all.filter((entry) => entry.eventId === eventId) : all;
+};
+
+export const rememberWaitlistEntry = (entry: RememberedWaitlistEntry) => {
+  const all = snapshot();
+  if (all.some((item) => item.entryId === entry.entryId)) return;
+  writeRemembered([...all, entry]);
+};
+
+export const forgetWaitlistEntry = (entryId: string) => {
+  const all = snapshot();
+  if (!all.some((item) => item.entryId === entryId)) return;
+  writeRemembered(all.filter((item) => item.entryId !== entryId));
+};
+
+/**
+ * The remembered ids, as a REACTIVE read.
+ *
+ * An anonymous joiner has no list endpoint to invalidate, so the local store is
+ * the only thing that changes when they join — a plain read would leave their
+ * new place invisible until a reload.
+ */
+export function useRememberedWaitlistEntries(eventId?: string): RememberedWaitlistEntry[] {
+  const all = useSyncExternalStore(subscribe, snapshot, serverSnapshot);
+  return useMemo(() => (eventId ? all.filter((entry) => entry.eventId === eventId) : all), [all, eventId]);
+}
+
+// ── Hooks ────────────────────────────────────────────────────────────────────
+
+const waitlistKey = (eventId?: string) => ["event-waitlist", eventId] as const;
+
+/**
+ * Join the queue for a sold-out tier.
+ *
+ * Anonymous is allowed and is the common case. The returned entry id is
+ * remembered locally so this browser can read its place back; a signed-in
+ * caller gets the same row from the list endpoint regardless.
+ *
+ * Re-joining is not an error — the server hands back the existing place with
+ * its original quantity, so callers should render the result, not a warning.
+ */
+export function useJoinEventWaitlist(eventId?: string) {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+
+  return useMutation<WaitlistEntry, unknown, JoinWaitlistInput>({
+    mutationFn: async (input) => {
+      const res = await client.post(`/public/events/${eventId}/waitlist`, {
+        profileId,
+        eventTicketId: input.eventTicketId,
+        // Sent only when there is one — the server ignores it for a signed-in
+        // caller, and an empty string would fail email validation.
+        ...(input.email ? { email: input.email } : {}),
+        ...(input.firstName ? { firstName: input.firstName } : {}),
+        ...(input.lastName ? { lastName: input.lastName } : {}),
+        quantity: input.quantity ?? 1,
+      });
+      return res.data;
+    },
+    onSuccess: (entry) => {
+      rememberWaitlistEntry({ eventId: entry.eventId, entryId: entry.id });
+      void queryClient.invalidateQueries({ queryKey: ["event-waitlist"] });
+    },
+  });
+}
+
+/**
+ * The signed-in buyer's own live entries for one event.
+ *
+ * `accountId` gates the query on being signed in and keys the cache; it is never
+ * sent. The server refuses an anonymous caller outright rather than returning an
+ * empty list, because "you are on no waitlist" is a different and wrong answer.
+ */
+export function useMyEventWaitlist(eventId?: string, accountId?: string) {
+  const { client, profileId } = useForge();
+
+  return useQuery<WaitlistEntry[]>({
+    queryKey: [...waitlistKey(eventId), "mine", accountId, profileId],
+    queryFn: async () => {
+      const res = await client.get(`/public/events/${eventId}/waitlist`, { params: { profileId } });
+      return res.data;
+    },
+    enabled: !!eventId && !!accountId && !!profileId && !!client,
+  });
+}
+
+/** One entry's place and offer state, addressed by the id that IS its capability. */
+export function useEventWaitlistEntry(eventId?: string, entryId?: string) {
+  const { client, profileId } = useForge();
+
+  return useQuery<WaitlistEntry>({
+    queryKey: [...waitlistKey(eventId), "entry", entryId, profileId],
+    queryFn: async () => {
+      const res = await client.get(`/public/events/${eventId}/waitlist/${entryId}`, { params: { profileId } });
+      return res.data;
+    },
+    enabled: !!eventId && !!entryId && !!profileId && !!client,
+  });
+}
+
+/**
+ * Leave the queue. Terminal, but not a ban — the same person may rejoin.
+ *
+ * Leaving twice, or leaving after converting, is a 400 by design: the server's
+ * conditional update IS the state machine, and a silent success would tell the
+ * buyer a place was removed that no longer existed.
+ */
+export function useLeaveEventWaitlist(eventId?: string) {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+
+  return useMutation<LeaveWaitlistResult, unknown, { entryId: string }>({
+    mutationFn: async ({ entryId }) => {
+      const res = await client.delete(`/public/events/${eventId}/waitlist/${entryId}`, { params: { profileId } });
+      return res.data;
+    },
+    onSuccess: (result) => {
+      forgetWaitlistEntry(result.id);
+      void queryClient.invalidateQueries({ queryKey: ["event-waitlist"] });
+    },
+  });
+}
+
+/**
+ * Every place this visitor holds on ONE event, signed in or not.
+ *
+ * Two sources, merged and de-duplicated by entry id:
+ *   - the list endpoint, when signed in (authoritative, cross-device);
+ *   - this browser's remembered capability ids, which is the only way an
+ *     anonymous joiner can be shown their own place.
+ *
+ * A signed-in visitor who joined anonymously earlier in the same browser sees
+ * both, which is exactly right: the anonymous entry is bound to no account and
+ * the list endpoint cannot know about it.
+ */
+export function useEventWaitlistPlaces(eventId?: string, accountId?: string) {
+  const { client, profileId } = useForge();
+  const mine = useMyEventWaitlist(eventId, accountId);
+  const remembered = useRememberedWaitlistEntries(eventId);
+
+  const entryQueries = useQueries({
+    queries: remembered.map((item) => ({
+      queryKey: [...waitlistKey(eventId), "entry", item.entryId, profileId],
+      queryFn: async () => {
+        const res = await client.get(`/public/events/${eventId}/waitlist/${item.entryId}`, { params: { profileId } });
+        return res.data as WaitlistEntry;
+      },
+      enabled: !!eventId && !!profileId && !!client,
+      // A remembered id can 404 (another tenant's site, a purged row) — that is
+      // an answer, not a fault worth retrying.
+      retry: false,
+    })),
+  });
+
+  // `useQueries` returns a new array identity every render, so the memo is
+  // keyed on when its members last changed rather than on the array itself.
+  const entryStamp = entryQueries.map((query) => query.dataUpdatedAt).join(",");
+  const entries = useMemo(() => {
+    const byId = new Map<string, WaitlistEntry>();
+    for (const entry of mine.data ?? []) byId.set(entry.id, entry);
+    for (const query of entryQueries) {
+      const entry = query.data;
+      if (entry && !byId.has(entry.id)) byId.set(entry.id, entry);
+    }
+    return [...byId.values()];
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [mine.data, entryStamp]);
+
+  return {
+    entries,
+    /** Only the LIVE ones — what "am I on the waitlist?" means to a buyer. */
+    liveEntries: useMemo(() => entries.filter(isLiveWaitlistEntry), [entries]),
+    isLoading: mine.isLoading || entryQueries.some((query) => query.isLoading),
+  };
+}
+
+export type WaitlistPlace = WaitlistEntry & {
+  /** The event this place is on, when it is one of the visitor's upcoming events. */
+  event?: IEvent;
+  /** The tier queued for, when the event payload still lists it. */
+  ticket?: ITicket;
+};
+
+/**
+ * Every live place the SIGNED-IN buyer holds, across upcoming events.
+ *
+ * There is no cross-event "my waitlist entries" endpoint, so this fans out the
+ * per-event list over the events the artist is currently showing — which is
+ * also the only set where a place still means anything, since a queue for a
+ * finished show can never be called.
+ *
+ * The fan-out is the cost of the missing endpoint and is bounded by that
+ * listing (20 events today). It is not used on the event page, where a single
+ * per-event read answers the same question.
+ */
+export function useMyWaitlistPlaces(accountId?: string) {
+  const { client, profileId } = useForge();
+  const { data: events, isLoading: eventsLoading } = useEvents();
+
+  const eventList = useMemo(() => events ?? [], [events]);
+
+  const listQueries = useQueries({
+    queries: eventList.map((event) => ({
+      queryKey: ["event-waitlist", event.id, "mine", accountId, profileId],
+      queryFn: async () => {
+        const res = await client.get(`/public/events/${event.id}/waitlist`, { params: { profileId } });
+        return res.data as WaitlistEntry[];
+      },
+      enabled: !!accountId && !!profileId && !!client,
+    })),
+  });
+
+  const listStamp = listQueries.map((query) => query.dataUpdatedAt).join(",");
+  const places = useMemo(() => {
+    const out: WaitlistPlace[] = [];
+    listQueries.forEach((query, index) => {
+      const event = eventList[index];
+      for (const entry of query.data ?? []) {
+        if (!isLiveWaitlistEntry(entry)) continue;
+        out.push({ ...entry, event, ticket: event?.tickets?.find((t) => t.id === entry.eventTicketId) });
+      }
+    });
+    // An open offer is the only thing here with a deadline, so it sorts first.
+    return out.sort((a, b) => Number(b.offer.offerOpen) - Number(a.offer.offerOpen));
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [eventList, listStamp]);
+
+  return {
+    places,
+    isLoading: eventsLoading || listQueries.some((query) => query.isLoading),
+  };
+}

package/src/data/queries/useEvents.ts

@@ -1,4 +1,4 @@
-import type { IEvent } from "../../types/models";
+import type { AppliedDiscountCoupon, IEvent } from "../../types/models";
 import { useForge } from "../../provider/ForgeProvider";
 import { useMutation, useQuery } from "@tanstack/react-query";
 
@@ -48,12 +48,26 @@ export type CreateEventOrderInput = {
   lastName?: string;
   questionnaire?: unknown;
   attributionRefId?: string;
+  /**
+   * The code the buyer typed. Tickets have no apply-coupon endpoint — this call
+   * IS where a code is redeemed, so a refused one fails the whole request with
+   * the reason as its message and no order is created.
+   */
+  couponCode?: string;
 };
 
 export type CreateEventOrderResult = {
   orderId: string;
   isFreeCheckout?: boolean;
+  /** NET of any discount. */
   totalAmount?: number;
+  // Additive (S.3) — present on every response, discounted or not.
+  /** GROSS, before any discount. */
+  subTotal?: number;
+  discountAmount?: number;
+  couponId?: string | null;
+  /** Every discount that applied, entered OR automatic. */
+  appliedCoupons?: AppliedDiscountCoupon[];
 };
 
 /** Create an event ticket order (the step before start-payment). */

package/src/data/queries/useMyBookings.ts

@@ -0,0 +1,211 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useForge } from "../../provider/ForgeProvider";
+import type { PaginatedData } from "../../types/models";
+
+/**
+ * The signed-in buyer's own coaching sessions, moving one and cancelling one
+ * (S.6 / bookings § 1.4).
+ *
+ * Session buyers had NO purchase surface at all before this — a booking's only
+ * artefacts were a confirmation email and a one-shot finalise page. Lives in
+ * Forge rather than in either app because both rendering surfaces need exactly
+ * this, and a second copy is how the two drift (as with `useMyTickets`).
+ *
+ * ## The endpoints
+ *
+ * ```
+ * GET  /public/coaching/bookings/mine                   → PaginatedData<MyBooking>  (401 if anonymous)
+ * POST /public/coaching/bookings/:bookingId/reschedule  { profileId, slotId }  → RescheduleResult
+ * POST /public/coaching/bookings/:bookingId/cancel      { profileId }          → CancelBookingResult
+ * ```
+ *
+ * The target slot comes from `useCoachingAvailability(coachingProductId, …)`,
+ * which already excludes slots that are taken and hours the coach is busy on
+ * ANY of their services. It is the same grid the original purchase used.
+ *
+ * ## What the server owns and this file does not mirror
+ *
+ * - **Identity.** The buyer is resolved from the SESSION and is never a
+ *   parameter; `accountId` here only gates the query on being signed in and
+ *   keys the cache. Not-yours is answered 404, never 403.
+ * - **Whether a session may be moved.** `canReschedule` / `rescheduleReason`
+ *   come back on every row. Re-deriving "has it started yet" in the UI would
+ *   give two answers to one question, and the wrong one is the one the buyer
+ *   acts on. Draw the control from the flag; surface the refusal verbatim.
+ * - **Which slot is acceptable.** Same product, not the current slot, not in
+ *   the past, and the coach actually free — the last of which is decided by a
+ *   database EXCLUDE constraint, so two buyers racing for one hour is settled
+ *   there and comes back as a 409 with the server's wording.
+ *
+ * ## Cancellation
+ *
+ * `cancellation` is present on every row and comes from the POLICY SNAPSHOT
+ * taken on the booking at purchase — never the coach's current setting, which
+ * is the whole reason the snapshot exists. `canCancel` is the only thing that
+ * decides whether a cancel control is drawn.
+ *
+ * The cancel itself is idempotent server-side: a single conditional UPDATE
+ * claims the cancellation before any provider call, so a double-clicked cancel
+ * refunds ONCE. `outcome` says what actually happened to the money
+ * (`refunded`, `voided_free`, `manual_refund_required`, …) and is worth showing
+ * — "cancelled" alone leaves a buyer wondering where their payment went.
+ */
+
+/** Why the buyer cannot cancel, when they cannot. Mirrors the shared evaluator. */
+export type BookingCancellationReason = "no_policy" | "not_allowed" | "window_closed" | "event_started";
+
+export type BookingCancellation = {
+  policy: "none" | "until" | "anytime" | null;
+  cutoffHours: number | null;
+  terms: string | null;
+  /** One sentence, already phrased for a buyer. Null when no policy was set. */
+  description: string | null;
+  canCancel: boolean;
+  reason: BookingCancellationReason | null;
+  /** The instant the window shuts. */
+  deadline: string | null;
+};
+
+/**
+ * Why the buyer cannot move this session, when they cannot.
+ *
+ * `window_closed` is the operator's NOTICE PERIOD, shared with the cancel path
+ * so "up to 24 hours before" means one thing across the pillar.
+ */
+export type RescheduleRefusal = "not_allowed" | "session_started" | "window_closed";
+
+export type MyBooking = {
+  id: string;
+  /** `confirmed` or `canceled` — holds and lapsed holds are never listed. */
+  status: string;
+  email: string;
+  firstName: string | null;
+  lastName: string | null;
+  /** Already a number (or null for a free session), not a decimal string. */
+  totalAmount: number | null;
+  totalAmountInChargedCurrency: string | number | null;
+  currency: string | null;
+  chargedCurrency: string | null;
+  refundState: string | null;
+  refundedAmountCents: string | number | null;
+  /** Set once the BUYER cancelled it themselves (as opposed to the operator). */
+  selfCancelledAt: string | null;
+  /** What became of the money: `refunded`, `voided_free`, `manual_refund_required`, … */
+  cancellationOutcome: string | null;
+  createdAt: string;
+  /** The slot the booking currently points at — what a reschedule moves. */
+  coachingBookingSlotId: string;
+  /**
+   * The authoritative session times: the SLOT's, not the booking's denormalised
+   * copy. After a move the two agree; on a row written before `start_time`
+   * existed only the slot has an answer at all.
+   */
+  sessionStartTime: string;
+  sessionEndTime: string;
+  coachingProductId: string;
+  coachingProductSlug: string | null;
+  coachingProductTitle: string;
+  coachingProductTimezone: string | null;
+  coachingProductDurationMinutes: number | null;
+  cancellation: BookingCancellation;
+  /** The server's answer. Never recomputed here. */
+  canReschedule: boolean;
+  rescheduleReason: RescheduleRefusal | null;
+};
+
+export type CancelBookingResult = {
+  bookingId: string;
+  /** True when money actually went back; false for a free or already-refunded session. */
+  refunded: boolean;
+  outcome: string;
+};
+
+export type RescheduleBookingResult = {
+  bookingId: string;
+  coachingProductId: string;
+  previousSlotId: string;
+  slotId: string;
+  sessionStartTime: string;
+  sessionEndTime: string;
+  timezone: string | null;
+};
+
+/** Sessions that have not happened yet, by the server's own session time. */
+export const isUpcomingBooking = (booking: Pick<MyBooking, "sessionStartTime">, now: Date = new Date()): boolean =>
+  new Date(booking.sessionStartTime).getTime() > now.getTime();
+
+/**
+ * The buyer's sessions with this artist, newest session first.
+ *
+ * `accountId` gates the query on being signed in and keys the cache; it is
+ * never sent. The server refuses an anonymous caller with a 401 rather than an
+ * empty list, because "you have no sessions" is a different and wrong answer.
+ */
+export function useMyBookings(accountId?: string, page = 1, limit = 20) {
+  const { client, profileId } = useForge();
+
+  return useQuery<PaginatedData<MyBooking>>({
+    queryKey: ["my-bookings", accountId, profileId, page, limit],
+    queryFn: async () => {
+      const res = await client.get("/public/coaching/bookings/mine", {
+        params: { profileId, page, limit },
+      });
+      return res.data;
+    },
+    enabled: !!accountId && !!profileId && !!client,
+  });
+}
+
+/**
+ * Move one of the buyer's own sessions to another slot.
+ *
+ * Invalidates the list AND the availability grid on success: the old hour is
+ * free again and the new one is not, so a stale grid would offer a time the
+ * server has just refused. Re-reading is cheaper than mirroring the rules.
+ */
+export function useRescheduleBooking() {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+
+  return useMutation<RescheduleBookingResult, unknown, { bookingId: string; slotId: string }>({
+    mutationFn: async ({ bookingId, slotId }) => {
+      const res = await client.post(`/public/coaching/bookings/${bookingId}/reschedule`, {
+        profileId,
+        slotId,
+      });
+      return res.data;
+    },
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: ["my-bookings"] });
+      void queryClient.invalidateQueries({ queryKey: ["coaching-availability"] });
+    },
+  });
+}
+
+/**
+ * Cancel one of the buyer's own sessions, inside the policy they booked under.
+ *
+ * Routed server-side through the same refund service an operator-issued refund
+ * uses, so the ledger, the tax reversal and the freeing of the coach's hour are
+ * identical — only `initiated_by` differs. Eligibility is the server's
+ * (`cancellation.canCancel`); this hook never pre-judges it, and a refusal comes
+ * back with the server's own wording for the rule that stopped it.
+ *
+ * The list and the availability grid are both invalidated: the row's state has
+ * changed and the hour is bookable again.
+ */
+export function useCancelMyBooking() {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+
+  return useMutation<CancelBookingResult, unknown, { bookingId: string }>({
+    mutationFn: async ({ bookingId }) => {
+      const res = await client.post(`/public/coaching/bookings/${bookingId}/cancel`, { profileId });
+      return res.data;
+    },
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: ["my-bookings"] });
+      void queryClient.invalidateQueries({ queryKey: ["coaching-availability"] });
+    },
+  });
+}