@tribe-nest/forge 3.21.0 → 3.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.21.0",
+  "version": "3.23.0",
   "publishConfig": {
     "access": "public"
   },
@@ -20,6 +20,7 @@
     "test:watch": "vitest"
   },
   "dependencies": {
+    "@paystack/inline-js": "^2.24.0",
     "@radix-ui/react-dialog": "^1.1.14",
     "@radix-ui/react-slot": "^1.2.3",
     "@stripe/react-stripe-js": "^3.8.0",

package/src/data/queries/_tests/eventWaitlist.spec.ts

@@ -6,6 +6,7 @@ import {
   isLiveWaitlistEntry,
   isTicketSoldOut,
   rememberWaitlistEntry,
+  readWaitlistClaimFromUrl,
   ticketSeatsRemaining,
 } from "../useEventWaitlist";
 import type { IEvent, ITicket } from "../../../types/models";
@@ -120,3 +121,40 @@ describe("the anonymous joiner's remembered capability ids", () => {
     expect(getRememberedWaitlistEntries("e1")).toEqual([]);
   });
 });
+
+/**
+ * Events 2.6b — the offer email's claim link.
+ *
+ * `?waitlistEntry=<uuid>&waitlistClaim=<64 hex>`. The parse is deliberately
+ * strict about the token's shape so a junk query string never becomes a request,
+ * and a link missing either half is simply not a claim — the visitor gets the
+ * ordinary page rather than a broken one.
+ */
+describe("readWaitlistClaimFromUrl", () => {
+  const token = "a".repeat(64);
+
+  it("reads a well-formed claim", () => {
+    expect(readWaitlistClaimFromUrl(`?waitlistEntry=entry-1&waitlistClaim=${token}`)).toEqual({
+      entryId: "entry-1",
+      token,
+    });
+  });
+
+  it("survives the other query parameters an email link picks up", () => {
+    expect(
+      readWaitlistClaimFromUrl(`?utm_source=email&waitlistClaim=${token}&waitlistEntry=entry-9&ref=x`),
+    ).toEqual({ entryId: "entry-9", token });
+  });
+
+  it("is null when either half is missing", () => {
+    expect(readWaitlistClaimFromUrl(`?waitlistClaim=${token}`)).toBeNull();
+    expect(readWaitlistClaimFromUrl("?waitlistEntry=entry-1")).toBeNull();
+    expect(readWaitlistClaimFromUrl("")).toBeNull();
+  });
+
+  it("rejects a token that is not exactly 64 lowercase hex characters", () => {
+    for (const bad of ["nope", "A".repeat(64), "a".repeat(63), "a".repeat(65), "../../etc"]) {
+      expect(readWaitlistClaimFromUrl(`?waitlistEntry=entry-1&waitlistClaim=${bad}`)).toBeNull();
+    }
+  });
+});

package/src/data/queries/_tests/passTransfers.spec.ts

@@ -3,18 +3,19 @@ import {
   forgetPassTransfer,
   getRememberedPassTransfers,
   isPendingPassTransfer,
+  mergePendingTransfer,
   rememberPassTransfer,
 } from "../usePassTransfers";
-import { myTicketPassIds } from "../useMyTickets";
+import { myTicketHeldPassIds, myTicketPassIds, type MyTicket } from "../useMyTickets";
 
 /**
  * Events 2.2 — the pure decisions behind the buyer-facing transfer surface.
  *
  * Only the total functions are exercised; the hooks themselves are thin
  * transport whose behaviour belongs to the API's own specs. The local store is
- * the one thing here with real logic, and it exists because there is NO
- * buyer-readable list endpoint — the transfer history is operator-only — so a
- * bug in it is a pending transfer the sender can never withdraw.
+ * the one thing here with real logic; it used to be the ONLY record a buyer had
+ * of their own send, and is now demoted to a bridge across the refetch that
+ * follows one, with `my-tickets`' `pendingTransfer` as the source of truth.
  */
 
 const clear = () => {
@@ -87,3 +88,98 @@ describe("the ids a transfer can be addressed by", () => {
     expect(myTicketPassIds({ items: [{ id: "i", quantity: 1, price: 10, ticketTitle: null }] })).toEqual([]);
   });
 });
+
+
+/**
+ * One live transfer per pass is a DATABASE guarantee (a partial unique index),
+ * so exactly one row may ever be drawn. Two would be a lie about the ticket's
+ * state and would offer two "withdraw" buttons for one thing.
+ */
+describe("mergePendingTransfer", () => {
+  const remembered = {
+    passId: "TN-1",
+    transferId: "local-1",
+    toEmail: "local@example.com",
+    expiresAt: "2026-04-01T00:00:00.000Z",
+  };
+
+  const fromServer = {
+    id: "server-1",
+    status: "pending",
+    toName: null,
+    toEmail: "server@example.com",
+    expiresAt: "2026-04-02T00:00:00.000Z",
+    createdAt: "2026-03-30T00:00:00.000Z",
+    window: { open: true, secondsRemaining: 3600, expiresAt: "2026-04-02T00:00:00.000Z" },
+  };
+
+  it("is null when nothing is in flight anywhere", () => {
+    expect(mergePendingTransfer(null, [])).toBeNull();
+  });
+
+  it("THE POINT: the server's row is what a second device sees", () => {
+    // `localStorage` is empty here — this browser never sent anything. Before
+    // the API carried `pendingTransfer` this returned nothing, which is why a
+    // sender on another device had no transfer to withdraw.
+    const merged = mergePendingTransfer(fromServer, [])!;
+
+    expect(merged.transferId).toBe("server-1");
+    expect(merged.toEmail).toBe("server@example.com");
+    expect(merged.fromServer).toBe(true);
+    expect(merged.open).toBe(true);
+  });
+
+  it("the server WINS over a stale local record, rather than drawing both", () => {
+    const merged = mergePendingTransfer(fromServer, [remembered])!;
+    expect(merged.transferId).toBe("server-1");
+    expect(merged.fromServer).toBe(true);
+  });
+
+  it("falls back to the local bridge before the refetch lands", () => {
+    const merged = mergePendingTransfer(null, [remembered])!;
+    expect(merged.transferId).toBe("local-1");
+    expect(merged.fromServer).toBe(false);
+    // Optimistic: a just-sent transfer is live by construction, and the server
+    // corrects it on the very next read.
+    expect(merged.open).toBe(true);
+  });
+
+  it("reports a lapsed-but-unswept transfer as closed, and still withdrawable", () => {
+    const lapsed = { ...fromServer, window: { open: false, secondsRemaining: 0, expiresAt: fromServer.expiresAt } };
+    const merged = mergePendingTransfer(lapsed, [])!;
+
+    // Hiding it would put the sender back where they started: a live row they
+    // cannot address. The row stays, the copy changes.
+    expect(merged.open).toBe(false);
+    expect(merged.transferId).toBe("server-1");
+  });
+});
+
+/**
+ * Which passes may an affordance be drawn on?
+ *
+ * Every pass-scoped endpoint — transfer, wallet, QR — resolves the current
+ * HOLDER, and a purchaser sees passes they do not hold: named guests at
+ * checkout, and (until the read was fixed) tickets already claimed by somebody
+ * else. A control on one of those could only ever answer 404.
+ */
+describe("myTicketHeldPassIds", () => {
+  const ticket = (passes: { id: string; isHolder?: boolean }[]) =>
+    ({ items: [{ id: "item-1", quantity: passes.length, price: 10, ticketTitle: "GA", passes }] }) as unknown as MyTicket;
+
+  it("keeps only the passes the caller holds", () => {
+    const t = ticket([
+      { id: "TN-1", isHolder: true },
+      { id: "TN-2", isHolder: false },
+    ]);
+
+    expect(myTicketHeldPassIds(t)).toEqual(["TN-1"]);
+    // The unfiltered helper still reports everything on the order — the wallet
+    // and transfer controls are the things that need narrowing, not the list.
+    expect(myTicketPassIds(t)).toEqual(["TN-1", "TN-2"]);
+  });
+
+  it("treats an ABSENT flag as held, so an older API build is unchanged", () => {
+    expect(myTicketHeldPassIds(ticket([{ id: "TN-9" }]))).toEqual(["TN-9"]);
+  });
+});

package/src/data/queries/useAuthActions.ts

@@ -39,7 +39,7 @@ export function useForgotPassword() {
       if (!contextId) {
         // Better than posting without it: the endpoint would 400 on schema
         // validation and the form would show "something went wrong".
-        throw new Error("useForgotPassword: no profileId — pass one or render inside a ForgeProvider with profileId");
+        throw new Error("useForgotPassword: no profileId. Pass one or render inside a ForgeProvider with profileId");
       }
       const res = await client.post("/public/sessions/forgot-password", {
         profileId: contextId,

package/src/data/queries/useCheckouts.ts

@@ -143,7 +143,12 @@ export type ApplyCheckoutCouponResult = {
   /** NET = max(0, subtotalCents − discountCents), minor units. */
   totalCents: number;
   appliedCoupons: AppliedBundleCoupon[];
+  /** STRIPE: the re-issued PaymentIntent client secret. */
   paymentSecret: string;
+  /** PAYSTACK: the re-issued inline-checkout session. */
+  accessCode?: string;
+  /** PAYSTACK: the hosted page for the re-issued session (runtime fallback). */
+  checkoutUrl?: string;
   paymentId: string;
   chargedAmount: number;
   chargedCurrency: string;

package/src/data/queries/useEventWaitlist.ts

@@ -17,6 +17,10 @@ import type { IEvent, ITicket } from "../../types/models";
  * 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
+ *        …optionally `&claimToken=<64 hex>` — the offer email's credential (2.6b),
+ *        which is the ONLY way an offered fan can read their place on a device
+ *        that never joined and is not signed in. That is the device the email is
+ *        opened on.
  * DELETE /public/events/:eventId/waitlist/:entryId     leave     → { id, status, leftAt }
  * ```
  *
@@ -49,6 +53,22 @@ export type WaitlistOffer = {
   secondsRemaining: number | null;
   /** The instant the offer lapses — the single most important field here. */
   claimExpiresAt: string | null;
+  /**
+   * Are the offered seats actually HELD for this person until the deadline
+   * (events 2.6b)?
+   *
+   * Distinct from `offerOpen`, and the distinction is the whole change. An offer
+   * used to reserve nothing — the fan raced the open page, and the copy said so.
+   * A reserved offer takes a real inventory hold for the length of the window,
+   * so the tier reads sold out to everybody else. Render "these are yours until
+   * Friday" ONLY when this is true; an unreserved offer (one made before the
+   * reservation existed, or one whose hold a failed payment released) is still a
+   * real offer with a real deadline and must keep the older, weaker promise.
+   *
+   * Optional so a site pinned to an older API build degrades to "not reserved"
+   * rather than claiming a hold that is not there.
+   */
+  seatsReserved?: boolean;
 };
 
 export type WaitlistEntry = {
@@ -88,14 +108,26 @@ export const isLiveWaitlistEntry = (entry: Pick<WaitlistEntry, "status">): boole
 // ── Where a join control may be DRAWN ────────────────────────────────────────
 
 /**
- * Seats a buyer can still take, by the same arithmetic the purchase UI uses.
+ * Seats that are not SOLD — the waitlist's question, which is not the purchase
+ * UI's question.
  *
  * 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.
+ *
+ * The purchase UI DOES subtract `held` — it has to, because that is what the
+ * server sells on (`ticketSeatsAvailable` in `ui/format/ticketAvailability`).
+ * The two are answering different things and the gap between them is deliberate:
+ *
+ *  - a tier with held-but-unsold seats is un-addable and says "ON HOLD", and
+ *    offers no waitlist, because the seats are coming back;
+ *  - a tier with nothing unsold says "SOLD OUT" and offers the queue.
+ *
+ * Collapsing them would put a "join the waitlist" beside a tier that unfreezes
+ * five minutes later, and send a fan an email about a seat they could have had
+ * by waiting. Identical to `waitlistAvailableSeats` on the server only in shape,
+ * not in intent — that one gates OFFERS, this one gates where a join is drawn.
  */
 export const ticketSeatsRemaining = (ticket: Pick<ITicket, "quantity" | "sold">): number =>
   Math.max(0, (ticket.quantity ?? 0) - (ticket.sold ?? 0));
@@ -334,6 +366,16 @@ export function useEventWaitlistPlaces(eventId?: string, accountId?: string) {
   const { client, profileId } = useForge();
   const mine = useMyEventWaitlist(eventId, accountId);
   const remembered = useRememberedWaitlistEntries(eventId);
+  /**
+   * 2.6b — a THIRD source: the offer the visitor arrived holding.
+   *
+   * The other two both assume continuity with the browser that joined — a
+   * session, or a remembered id in this localStorage. An offer email is read on
+   * a phone, and neither holds there, so the fan landed on an ordinary sold-out
+   * page with a "join the waitlist" form beside the seats already reserved for
+   * them. The token in the link is what makes that place readable.
+   */
+  const claim = useEventWaitlistClaim(eventId);
 
   const entryQueries = useQueries({
     queries: remembered.map((item) => ({
@@ -359,15 +401,21 @@ export function useEventWaitlistPlaces(eventId?: string, accountId?: string) {
       const entry = query.data;
       if (entry && !byId.has(entry.id)) byId.set(entry.id, entry);
     }
+    // Last, and unconditionally: an entry the link addresses is the one the
+    // visitor is here about. `set` rather than a has-check so the token-scoped
+    // read wins if the same row arrived by another route.
+    if (claim.entry) byId.set(claim.entry.id, claim.entry);
     return [...byId.values()];
     // eslint-disable-next-line react-hooks/exhaustive-deps
-  }, [mine.data, entryStamp]);
+  }, [mine.data, entryStamp, claim.entry]);
 
   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),
+    /** The claim this visitor arrived with, for the surface that spends it. */
+    claim,
+    isLoading: mine.isLoading || claim.isLoading || entryQueries.some((query) => query.isLoading),
   };
 }
 
@@ -427,3 +475,73 @@ export function useMyWaitlistPlaces(accountId?: string) {
     isLoading: eventsLoading || listQueries.some((query) => query.isLoading),
   };
 }
+
+// ── The offer email's claim link (2.6b) ──────────────────────────────────────
+
+/**
+ * The claim credential an offer email hands out.
+ *
+ * The link used to be the ordinary public event page, which proved nothing about
+ * who was holding it — and once the offer started RESERVING seats it could not
+ * even be used, because the reservation makes the tier read sold out to
+ * everybody, the offeree included. The email now carries
+ * `?waitlistEntry=<id>&waitlistClaim=<64 hex>`: the id addresses the place, the
+ * token proves the holder and is what lets the reserved hold be spent.
+ */
+export type WaitlistClaimLink = { entryId: string; token: string };
+
+/** 64 lowercase hex, matching the server's own shape gate. */
+const isWellFormedClaimToken = (value: string | null): value is string =>
+  !!value && /^[0-9a-f]{64}$/.test(value);
+
+/**
+ * Read the claim out of the CURRENT url.
+ *
+ * Deliberately not stored anywhere. It is a bearer credential with a deadline,
+ * and the durable copy is the email; putting it in localStorage would leave a
+ * spendable token on a shared device long after the offer died, for no benefit
+ * — the fan re-opens the email.
+ */
+export const readWaitlistClaimFromUrl = (search?: string): WaitlistClaimLink | null => {
+  const raw = search ?? (typeof window === "undefined" ? "" : window.location.search);
+  if (!raw) return null;
+  const params = new URLSearchParams(raw);
+  const entryId = params.get("waitlistEntry");
+  const token = params.get("waitlistClaim");
+  if (!entryId || !isWellFormedClaimToken(token)) return null;
+  return { entryId, token };
+};
+
+/**
+ * The offer this visitor arrived holding, if they arrived holding one.
+ *
+ * `enabled` on the token means an ordinary visitor makes no request at all. A
+ * dead or foreign token 404s, which is an ANSWER — the offer is over, or the
+ * link belongs to another artist — so it is not retried and the caller simply
+ * renders the ordinary page.
+ */
+export function useEventWaitlistClaim(eventId?: string, search?: string) {
+  const { client, profileId } = useForge();
+  const link = useMemo(() => readWaitlistClaimFromUrl(search), [search]);
+
+  const query = useQuery<WaitlistEntry>({
+    queryKey: [...waitlistKey(eventId), "claim", link?.entryId, profileId],
+    queryFn: async () => {
+      const res = await client.get(`/public/events/${eventId}/waitlist/${link!.entryId}`, {
+        params: { profileId, claimToken: link!.token },
+      });
+      return res.data;
+    },
+    enabled: !!eventId && !!profileId && !!client && !!link,
+    retry: false,
+  });
+
+  return {
+    /** The raw token, to be posted with the order that spends the reservation. */
+    token: link?.token ?? null,
+    entry: query.data ?? null,
+    /** True only while the seats are genuinely held and the window is open. */
+    isClaimable: !!query.data?.offer?.offerOpen && !!query.data?.offer?.seatsReserved,
+    isLoading: query.isLoading,
+  };
+}

package/src/data/queries/useEvents.ts

@@ -25,19 +25,48 @@ export function useEvents() {
  * seed the query — the hook then returns data on first render with no loading
  * state, so the page can be server-rendered for SEO with no client spinner.
  */
-export function useEvent(id?: string, options?: { initialData?: IEvent }) {
+export function useEvent(
+  id?: string,
+  options?: {
+    initialData?: IEvent;
+    /**
+     * A presale code the buyer holds (1.2). A correct one reveals the hidden
+     * tiers it unlocks, in this same response, and sets `presale.codeAccepted`.
+     *
+     * Part of the query KEY, so entering a code refetches rather than serving
+     * the unrevealed cache — and so the seeded `initialData` (fetched without a
+     * code) is not mistaken for a coded response.
+     */
+    accessCode?: string | null;
+  },
+) {
   const { client, profileId } = useForge();
+  const accessCode = options?.accessCode || undefined;
+  // Only callers that pass the option at all — presale-aware ones — get the
+  // hold-the-last-page behaviour below. Everyone else keeps the old semantics
+  // exactly, including "the event goes undefined while a DIFFERENT event
+  // loads", which is what a router navigation wants.
+  const presaleAware = !!options && "accessCode" in options;
 
   return useQuery<IEvent>({
-    queryKey: ["event", id, profileId],
+    queryKey: ["event", id, profileId, accessCode ?? null],
     queryFn: async () => {
       const res = await client.get(`/public/events/${id}`, {
-        params: { profileId },
+        params: { profileId, ...(accessCode ? { accessCode } : {}) },
       });
       return res.data;
     },
     enabled: !!id && !!profileId && !!client,
-    initialData: options?.initialData,
+    // Seeding only applies to the uncoded query: `initialData` came from a
+    // loader that had no code, so handing it to a coded key would show an
+    // unrevealed tier list and claim the code was applied.
+    initialData: accessCode ? undefined : options?.initialData,
+    // Applying a code changes the query key, which would otherwise blank the
+    // whole event page back to a spinner while the coded read is in flight —
+    // the buyer presses Apply and the show they were reading disappears. Keep
+    // the last event on screen and let `isFetching` drive the field's own
+    // "Checking…".
+    placeholderData: presaleAware ? (previous?: IEvent) => previous : undefined,
   });
 }
 
@@ -49,6 +78,21 @@ export type CreateEventOrderInput = {
    * the tier's own `price` — it can raise what is charged, never lower it.
    */
   amounts?: Record<string, number>;
+  /**
+   * Who is actually coming, keyed by ticket id exactly as `items` is, one entry
+   * per seat of that tier in issue order (Events 2.1).
+   *
+   * Send it only when the event has `collectAttendeeDetails` on — the server
+   * does not read it otherwise. A list whose length does not equal that tier's
+   * quantity is REFUSED (a short list would leave a silent extra pass in the
+   * purchaser's name), so build it with `attendeesPayload` from
+   * `forge/ui`'s attendee helpers rather than by hand.
+   *
+   * `email` is accepted per attendee and deliberately not sent by either
+   * storefront: it is the pass's OWNER, so naming another address hands that
+   * seat away. Handing a ticket to somebody else is what transfer is for.
+   */
+  attendees?: Record<string, { name: string; email?: string }[]>;
   email: string;
   firstName?: string;
   lastName?: string;
@@ -60,6 +104,32 @@ export type CreateEventOrderInput = {
    * the reason as its message and no order is created.
    */
   couponCode?: string;
+  /**
+   * The PRESALE code (1.2) — not the discount code above. It buys access to a
+   * tier, it does not change a price.
+   *
+   * The sell guard runs against the tier's own column on every order, so this
+   * has to travel with the purchase and not merely with the read that revealed
+   * the tier: a buyer who unlocks a presale and then checks out without it gets
+   * their order refused after entering their card details.
+   */
+  accessCode?: string;
+  /**
+   * The waitlist offer's claim token (events 2.6b) — 64 hex from the offer
+   * email's link, NOT a discount and NOT a presale code.
+   *
+   * It is a capability over inventory that is ALREADY reserved: the offer took
+   * a real hold when it was made, so presenting this makes the order spend that
+   * hold rather than acquire a new one. Without it an offeree cannot buy at
+   * all, because their own reservation is what makes the tier read sold out to
+   * them.
+   *
+   * The server refuses a claim it cannot honour (closed window, released
+   * reservation, a cart reaching past the offered tier) rather than quietly
+   * falling back to an ordinary purchase — so a refusal here is the truth about
+   * the offer, not a generic sold-out.
+   */
+  waitlistClaimToken?: string;
 };
 
 export type CreateEventOrderResult = {
@@ -83,6 +153,14 @@ export type CreateEventOrderResult = {
   couponId?: string | null;
   /** Every discount that applied, entered OR automatic. */
   appliedCoupons?: AppliedDiscountCoupon[];
+  /**
+   * When these tickets stop being reserved, ISO-8601.
+   *
+   * `null` for a free order — its hold has already converted by the time this
+   * returns, so a countdown on it would be counting something that no longer
+   * exists — and for a profile with inventory holds switched off.
+   */
+  holdExpiresAt?: string | null;
 };
 
 /** Create an event ticket order (the step before start-payment). */

package/src/data/queries/useMembership.ts

@@ -2,7 +2,13 @@ import type { MembershipTier } from "../../types/models";
 import { useForge } from "../../provider/ForgeProvider";
 import { useQuery } from "@tanstack/react-query";
 
-export function useGetMembershipTiers() {
+/**
+ * `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.
+ */
+export function useGetMembershipTiers(opts: { enabled?: boolean } = {}) {
   const { client, profileId } = useForge();
 
   return useQuery<MembershipTier[]>({
@@ -15,6 +21,6 @@ export function useGetMembershipTiers() {
       });
       return res.data;
     },
-    enabled: !!profileId && !!client,
+    enabled: !!profileId && !!client && opts.enabled !== false,
   });
 }

package/src/data/queries/useMyBookings.ts

@@ -108,11 +108,48 @@ export type MyBooking = {
   coachingProductTimezone: string | null;
   coachingProductDurationMinutes: number | null;
   cancellation: BookingCancellation;
+  /** Already resolved server-side — see {@link BookingLocation}. */
+  location?: BookingLocation | null;
   /** The server's answer. Never recomputed here. */
   canReschedule: boolean;
   rescheduleReason: RescheduleRefusal | null;
+  /**
+   * The session's `.ics`, both forms — what lets the portal offer Apple
+   * Calendar rather than only Google/Outlook/Microsoft 365. `null` unless the
+   * booking is confirmed.
+   *
+   * The address is stable across a RESCHEDULE (it is HMAC(kind:id) and the
+   * booking id does not change), which is the mechanism by which a re-fetch
+   * moves the entry already in the buyer's calendar instead of adding a second
+   * one. Optional: an older API build does not emit it.
+   */
+  calendarUrl?: string | null;
+  calendarWebcalUrl?: string | null;
 };
 
+/**
+ * WHERE the session happens.
+ *
+ * The server has already resolved this — the booking's own override if the
+ * coach set one for this session, otherwise the coaching product's default —
+ * so there is exactly one value and no rule to re-derive in the browser. Two
+ * fields would eventually be rendered in the wrong order by one of the two
+ * rendering stacks, and the consequence of that is not cosmetic: it is a client
+ * dialling into an empty room.
+ *
+ * `null` means the coach has not said where the session is. Draw nothing; the
+ * confirmation email carries the same gap and inventing a placeholder ("Online")
+ * would promise a link that does not exist.
+ *
+ * Withheld for anything not `confirmed`: a cancelled session has no venue to go
+ * to and no call to join.
+ *
+ * Optional on the type because an older API build does not emit it.
+ */
+export type BookingLocation =
+  | { type: "in_person"; address: string }
+  | { type: "online"; url: string };
+
 export type CancelBookingResult = {
   bookingId: string;
   /** True when money actually went back; false for a free or already-refunded session. */