@tribe-nest/forge 3.26.0 → 3.31.0

package/src/contexts/PublicAuthContext.tsx

@@ -245,9 +245,35 @@ function PublicAuthProvider({ children }: AuthProviderProps) {
     await client.post("/public/sessions/resend-code", { email, profileId });
   };
 
+  /**
+   * Re-read the signed-in member from the PUBLIC lane.
+   *
+   * ## `/public/accounts/me`, never `/accounts/me`
+   *
+   * This used to call the dashboard endpoint, which signed a fan out every time
+   * it ran. A fan session is minted by `mintAssociationSession` and its JWT
+   * carries an `associationId`; `requireAuthentication` rejects any token
+   * carrying one outright, by design, because honouring it on the admin surface
+   * would hand the caller that account's full dashboard permissions. So the
+   * call could only ever 401, the catch below read that as "not signed in", and
+   * the member was thrown back to the login page while a perfectly good token
+   * sat in localStorage. It bit hardest right after joining a membership, where
+   * the account page refetches on arrival.
+   *
+   * The 401 was also charged twice: the axios refresh interceptor treated it as
+   * an expired access token, spent a refresh-token rotation on it, and retried
+   * into the same 401.
+   *
+   * ## A failed refetch is not a logout
+   *
+   * Only an authentication failure clears the session now. A network blip or a
+   * 500 leaves the member exactly as they were, because dropping someone's
+   * session over a flaky response is a worse answer than showing them slightly
+   * stale details.
+   */
   const refetchUser = async () => {
     try {
-      const response = await client.get("/accounts/me", {
+      const response = await client.get("/public/accounts/me", {
         params: {
           profileId: profileId,
         },
@@ -258,10 +284,13 @@ function PublicAuthProvider({ children }: AuthProviderProps) {
       });
     } catch (error: unknown) {
       console.error(error);
-      dispatch({
-        type: Types.Initial,
-        payload: { isAuthenticated: false, user: null },
-      });
+      const status = (error as { response?: { status?: number } })?.response?.status;
+      if (status === 401 || status === 403) {
+        dispatch({
+          type: Types.Initial,
+          payload: { isAuthenticated: false, user: null },
+        });
+      }
     }
   };
 

package/src/contexts/_tests/CartContext.spec.tsx

@@ -0,0 +1,210 @@
+// @vitest-environment jsdom
+import { describe, it, expect, beforeEach } from "vitest";
+import { act, renderHook } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { CartProvider, useCart, type CartItem, type TicketCartItem } from "../CartContext";
+import { ProductDeliveryType } from "../../types/models";
+
+/**
+ * `restoreCart`, the one entry point that writes the WHOLE basket at once.
+ *
+ * It exists for the recovery link, and it is the only cart mutation that runs
+ * without the visitor pressing anything: they click a link in an email and the
+ * basket changes underneath them. So the thing worth asserting is not that the
+ * restored lines arrive, it is that nothing the visitor put in the basket
+ * THEMSELVES leaves while that happens. A restore that quietly drops a tier is
+ * indistinguishable, to the buyer, from a shop that lost their basket twice.
+ *
+ * jsdom rather than `renderToStaticMarkup`, because a provider that hydrates in
+ * a mount effect and persists in another has no behaviour at all without
+ * effects and without `localStorage`.
+ */
+
+const wrapper = ({ children }: { children: ReactNode }) => <CartProvider>{children}</CartProvider>;
+
+const item = (overrides: Partial<CartItem> = {}): CartItem => ({
+  productId: "prod-1",
+  productVariantId: "var-1",
+  title: "Tour Tee",
+  price: 25,
+  isGift: false,
+  canIncreaseQuantity: true,
+  quantity: 1,
+  payWhatYouWant: false,
+  deliveryType: ProductDeliveryType.Physical,
+  ...overrides,
+});
+
+const selection = (overrides: Partial<TicketCartItem> = {}): TicketCartItem => ({
+  eventId: "event-1",
+  eventSlug: "spring-tour",
+  eventTitle: "Spring Tour",
+  tickets: { "tier-ga": 1 },
+  ticketMeta: { "tier-ga": { title: "General Admission", price: 25 } },
+  bookingFee: null,
+  ...overrides,
+});
+
+const mount = () => renderHook(() => useCart(), { wrapper });
+
+beforeEach(() => {
+  localStorage.clear();
+});
+
+describe("restoreCart: tickets", () => {
+  it("REGRESSION: keeps a tier the visitor picked in this session when the same event is restored", () => {
+    // The defect this replaces overwrote the event's whole selection, so a
+    // visitor holding two tiers who clicked a recovery email for one of them
+    // was left with one. Nothing on the page said so and the total simply
+    // shrank.
+    const { result } = mount();
+
+    act(() => {
+      result.current.setTickets(
+        selection({
+          tickets: { "tier-ga": 2, "tier-vip": 1 },
+          ticketMeta: {
+            "tier-ga": { title: "General Admission", price: 25 },
+            "tier-vip": { title: "VIP", price: 80 },
+          },
+        }),
+      );
+    });
+
+    act(() => {
+      result.current.restoreCart({
+        tickets: [
+          selection({
+            tickets: { "tier-early": 3 },
+            ticketMeta: { "tier-early": { title: "Early bird", price: 15 } },
+          }),
+        ],
+      });
+    });
+
+    expect(result.current.ticketItems).toHaveLength(1);
+    expect(result.current.ticketItems[0].tickets).toEqual({
+      "tier-ga": 2,
+      "tier-vip": 1,
+      "tier-early": 3,
+    });
+    expect(Object.keys(result.current.ticketItems[0].ticketMeta).sort()).toEqual([
+      "tier-early",
+      "tier-ga",
+      "tier-vip",
+    ]);
+    // The badge counts every unit, so a lost tier is visible there too.
+    expect(result.current.itemCount).toBe(6);
+  });
+
+  it("takes the restored quantity on a tier both sides name, rather than adding to it", () => {
+    // Both sides describe the same intent. Summing would hand the buyer five
+    // tickets they never asked for, and the resumed figure is the one the
+    // server has just re-checked, so it wins outright.
+    const { result } = mount();
+
+    act(() => result.current.setTickets(selection({ tickets: { "tier-ga": 3 } })));
+    act(() => result.current.restoreCart({ tickets: [selection({ tickets: { "tier-ga": 2 } })] }));
+
+    expect(result.current.ticketItems[0].tickets).toEqual({ "tier-ga": 2 });
+  });
+
+  it("takes the restored display data for a tier both sides name", () => {
+    const { result } = mount();
+
+    act(() => result.current.setTickets(selection()));
+    act(() =>
+      result.current.restoreCart({
+        tickets: [selection({ ticketMeta: { "tier-ga": { title: "General Admission", price: 30 } } })],
+      }),
+    );
+
+    expect(result.current.ticketItems[0].ticketMeta["tier-ga"]).toEqual({
+      title: "General Admission",
+      price: 30,
+    });
+  });
+
+  it("does not erase a captured booking fee when the resumed payload carries none", () => {
+    // A payload saved before booking fees existed answers `null`, and the fee
+    // the modal captured is what the cart shows the buyer they will pay.
+    const fee = { feeAmount: 1.5, feeBps: 250, currency: "USD", minorUnitFactor: 100 };
+    const { result } = mount();
+
+    act(() => result.current.setTickets(selection({ bookingFee: fee })));
+    act(() => result.current.restoreCart({ tickets: [selection({ bookingFee: null })] }));
+
+    expect(result.current.ticketItems[0].bookingFee).toEqual(fee);
+  });
+
+  it("leaves an event the recovery link says nothing about alone, and appends a new one", () => {
+    const { result } = mount();
+
+    act(() => result.current.setTickets(selection({ eventId: "event-9", eventTitle: "Autumn" })));
+    act(() => result.current.restoreCart({ tickets: [selection({ eventId: "event-1" })] }));
+
+    expect(result.current.ticketItems.map((t) => t.eventId)).toEqual(["event-9", "event-1"]);
+  });
+});
+
+describe("restoreCart: products", () => {
+  it("replaces a matching line rather than appending a duplicate of it", () => {
+    const { result } = mount();
+
+    act(() => void result.current.addToCart(item({ quantity: 1, price: 25 })));
+    act(() => result.current.restoreCart({ items: [item({ quantity: 3, price: 30 })] }));
+
+    expect(result.current.cartItems).toHaveLength(1);
+    expect(result.current.cartItems[0]).toMatchObject({ quantity: 3, price: 30 });
+  });
+
+  it("keeps a line the recovery link does not name", () => {
+    const { result } = mount();
+
+    act(() => void result.current.addToCart(item({ productId: "prod-9", productVariantId: "var-9" })));
+    act(() => result.current.restoreCart({ items: [item()] }));
+
+    expect(result.current.cartItems.map((i) => i.productId)).toEqual(["prod-9", "prod-1"]);
+  });
+
+  it("treats a gift to a different recipient as its own line", () => {
+    // The line identity `addToCart` already uses. Collapsing these would send
+    // one of two presents.
+    const { result } = mount();
+
+    act(() => void result.current.addToCart(item({ isGift: true, recipientEmail: "ada@test.com" })));
+    act(() =>
+      result.current.restoreCart({ items: [item({ isGift: true, recipientEmail: "grace@test.com" })] }),
+    );
+
+    expect(result.current.cartItems).toHaveLength(2);
+  });
+
+  it("does not open the drawer, because the resume page IS the surface", () => {
+    const { result } = mount();
+    act(() => result.current.restoreCart({ items: [item()], tickets: [selection()] }));
+    expect(result.current.isCartOpen).toBe(false);
+  });
+});
+
+describe("removeTickets", () => {
+  it("takes every add-on attached to the event with it", () => {
+    // The server refuses a bundle whose add-on has no base, so an orphan left
+    // behind here is a checkout that fails with nothing on screen saying why.
+    const { result } = mount();
+
+    act(() => {
+      result.current.restoreCart({
+        items: [
+          item({ attachedTo: { type: "event", entityId: "event-1" } }),
+          item({ productId: "prod-2", productVariantId: "var-2" }),
+        ],
+        tickets: [selection()],
+      });
+    });
+    act(() => result.current.removeTickets("event-1"));
+
+    expect(result.current.ticketItems).toEqual([]);
+    expect(result.current.cartItems.map((i) => i.productId)).toEqual(["prod-2"]);
+  });
+});

package/src/contexts/_tests/PublicAuthRefetch.spec.tsx

@@ -0,0 +1,147 @@
+// @vitest-environment jsdom
+import { describe, it, expect, beforeEach, afterEach } 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, usePublicAuth, PUBLIC_ACCESS_TOKEN_KEY } from "../PublicAuthContext";
+
+/**
+ * `refetchUser`, which used to sign the member out every time it ran.
+ *
+ * A fan session is minted by the public surface and its JWT carries an
+ * `associationId`. `requireAuthentication` refuses any token carrying one, on
+ * purpose: honouring it on the admin surface would hand the caller that
+ * account's whole dashboard. So `GET /accounts/me` could only ever answer 401
+ * for a fan, and `refetchUser`'s catch read that as "not signed in".
+ *
+ * It bit hardest immediately after joining a membership, because the account
+ * page refetches the member on arrival: finish signup, land on the account
+ * page, get bounced to login with a perfectly good token still in localStorage.
+ *
+ * The adapter is swapped rather than the module mocked, so the assertion is on
+ * the URL that actually went out.
+ */
+
+const PROFILE_ID = "profile-1";
+
+const member = {
+  id: "account-1",
+  email: "fan@example.com",
+  firstName: "Fan",
+  lastName: "Person",
+  kind: "fan",
+  status: "active",
+  createdAt: "2026-01-01T00:00:00.000Z",
+  updatedAt: "2026-01-01T00:00:00.000Z",
+  membership: { id: "m-1", membershipTierId: "tier-1", status: "active" },
+};
+
+let requested: string[] = [];
+let realAdapter: AxiosAdapter | undefined;
+
+/**
+ * Answers the member on the PUBLIC endpoint and refuses the admin one exactly
+ * as the backend does, so a spec cannot pass by calling the wrong one.
+ *
+ * `refetchStatus` applies from the SECOND `/public/accounts/me` onwards: the
+ * first is the provider's own `initialize`, and failing that would sign the
+ * member out before `refetchUser` was ever reached, which is a different test.
+ */
+function installAdapter(opts: { refetchStatus?: number } = {}) {
+  requested = [];
+  let meCalls = 0;
+  const adapter: AxiosAdapter = async (config: InternalAxiosRequestConfig) => {
+    const url = config.url ?? "";
+    requested.push(url);
+    const ok = (data: unknown) =>
+      Promise.resolve({ data, status: 200, statusText: "OK", headers: {}, config } as never);
+    const fail = (status: number) =>
+      Promise.reject(
+        Object.assign(new Error(`Request failed with status code ${status}`), {
+          response: { status, data: { message: "nope" }, headers: {}, config },
+          config,
+          isAxiosError: true,
+        }),
+      );
+
+    if (url.includes("/public/accounts/me")) {
+      meCalls += 1;
+      return opts.refetchStatus && meCalls > 1 ? fail(opts.refetchStatus) : ok(member);
+    }
+    // The dashboard lane. A fan token is rejected here by design.
+    if (url.includes("/accounts/me")) return fail(401);
+    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 } } })}>
+    <ForgeClientProvider apiUrl="http://api.test" profileId={PROFILE_ID}>
+      <PublicAuthProvider>{children}</PublicAuthProvider>
+    </ForgeClientProvider>
+  </QueryClientProvider>
+);
+
+beforeEach(() => {
+  localStorage.clear();
+  localStorage.setItem(PUBLIC_ACCESS_TOKEN_KEY, "fan-access-token");
+});
+
+afterEach(() => {
+  if (realAdapter) axios.defaults.adapter = realAdapter;
+  localStorage.clear();
+});
+
+describe("refetchUser", () => {
+  it("REGRESSION: re-reads the member from the public lane and keeps them signed in", async () => {
+    installAdapter();
+    const { result } = renderHook(() => usePublicAuth(), { wrapper });
+
+    await waitFor(() => expect(result.current.isInitialized).toBe(true));
+    await act(async () => {
+      await result.current.refetchUser();
+    });
+
+    expect(requested.some((url) => url.includes("/public/accounts/me"))).toBe(true);
+    // The dashboard endpoint is never touched: it 401s a fan token by design,
+    // which is exactly how this became a logout.
+    expect(requested.some((url) => url === "/accounts/me")).toBe(false);
+    expect(result.current.isAuthenticated).toBe(true);
+    expect(result.current.user?.email).toBe("fan@example.com");
+  });
+
+  it("keeps the member signed in when the refetch fails for a reason that is not auth", async () => {
+    // A 500 or a dropped connection is not evidence that anyone is signed out.
+    // Showing slightly stale details beats throwing someone back to the login
+    // page because one request wobbled.
+    installAdapter({ refetchStatus: 500 });
+    const { result } = renderHook(() => usePublicAuth(), { wrapper });
+
+    await waitFor(() => expect(result.current.isInitialized).toBe(true));
+    await act(async () => {
+      await result.current.refetchUser();
+    });
+
+    expect(result.current.isAuthenticated).toBe(true);
+  });
+
+  it("does sign the member out when the server actually rejects the token", async () => {
+    installAdapter({ refetchStatus: 401 });
+    const { result } = renderHook(() => usePublicAuth(), { wrapper });
+
+    await waitFor(() => expect(result.current.isInitialized).toBe(true));
+    await act(async () => {
+      await result.current.refetchUser();
+    });
+
+    expect(result.current.isAuthenticated).toBe(false);
+    expect(result.current.user).toBeNull();
+  });
+});

package/src/data/queries/useBroadcasts.ts

@@ -29,3 +29,154 @@ export function useValidateBroadcastPass() {
     },
   });
 }
+
+/**
+ * ONE broadcast, by id.
+ *
+ * Not the same thing as picking the id out of `useLiveBroadcasts()`: the list is
+ * what is on now, and a broadcast that has ENDED still has to render its own
+ * page (the "broadcast ended, keep this tab open" screen). Reading the detail
+ * endpoint is what makes that page survive the end of the stream.
+ */
+export function useLiveBroadcast(broadcastId?: string) {
+  const { client, profileId } = useForge();
+
+  return useQuery<ILiveBroadcast>({
+    queryKey: ["live-broadcast", profileId, broadcastId],
+    queryFn: async () => {
+      const res = await client.get(`/public/broadcasts/${broadcastId}`, {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!broadcastId,
+  });
+}
+
+/**
+ * The same broadcast, re-read on an interval, purely to notice that it ended.
+ *
+ * A separate query from `useLiveBroadcast` on purpose. The page keeps rendering
+ * the broadcast it opened with, and only the END is allowed to come from the
+ * poll, so a mid-stream edit to the title or the thumbnail cannot swap the
+ * player out from under someone who is watching.
+ */
+export function useLiveBroadcastPoll(broadcastId?: string, intervalMs = 5000) {
+  const { client, profileId } = useForge();
+
+  return useQuery<ILiveBroadcast>({
+    queryKey: ["live-broadcast-poll", profileId, broadcastId],
+    queryFn: async () => {
+      const res = await client.get(`/public/broadcasts/${broadcastId}`, {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!broadcastId,
+    refetchInterval: intervalMs,
+  });
+}
+
+/** How many people are watching right now. Polled while the broadcast is on. */
+export function useBroadcastAudience(broadcastId?: string, enabled = true, intervalMs = 3000) {
+  const { client, profileId } = useForge();
+
+  return useQuery<{ count: number }>({
+    queryKey: ["broadcast-audience", broadcastId],
+    queryFn: async () => {
+      const res = await client.get(`/public/broadcasts/${broadcastId}/audience`, {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!broadcastId && enabled,
+    refetchInterval: intervalMs,
+  });
+}
+
+/** Which chat surface a broadcast comment arrived from. */
+export const BroadcastChannelProvider = {
+  Youtube: "youtube",
+  Twitch: "twitch",
+  Website: "website",
+  CustomRTMP: "custom_rtmp",
+} as const;
+
+export type BroadcastChannelProviderValue =
+  (typeof BroadcastChannelProvider)[keyof typeof BroadcastChannelProvider];
+
+/** One message in a broadcast's live chat. */
+export type BroadcastComment = {
+  id: string;
+  name: string;
+  content: string;
+  publishedAt: string;
+  channelProvider: BroadcastChannelProviderValue;
+};
+
+/** The chat backlog a viewer sees when they join. Realtime arrives over the socket. */
+export function useBroadcastComments(broadcastId?: string) {
+  const { client, profileId } = useForge();
+
+  return useQuery<BroadcastComment[]>({
+    queryKey: ["broadcast-comments", profileId, broadcastId],
+    queryFn: async () => {
+      const res = await client.get(`/public/broadcasts/${broadcastId}/comments`, {
+        params: { profileId },
+      });
+      return res.data;
+    },
+    enabled: !!profileId && !!client && !!broadcastId,
+  });
+}
+
+/** The offer/answer exchange that subscribes a viewer to a WebRTC broadcast. */
+export type BroadcastSubscribeAnswer = {
+  requiresImmediateRenegotiation: boolean;
+  sessionId: string;
+  tracks: { trackName: string; mid: string; trackSid: string }[];
+  sessionDescription: { sdp: string; type: string };
+};
+
+/**
+ * The imperative half of watching a broadcast: the calls that are made in
+ * response to something happening (a pass validated, a heartbeat, a viewer
+ * closing the tab), not on a render.
+ *
+ * They live here rather than inline in a component so both rendering stacks make
+ * the SAME call to the same address. A session that is pinged on one stack and
+ * not the other reports a different audience count for the same room.
+ */
+export function useBroadcastSessionApi() {
+  const { client } = useForge();
+
+  return {
+    /** Re-open a session held in storage from an earlier visit. */
+    validateSession: async (broadcastId: string, sessionId: string): Promise<IBroadcastPass> => {
+      const res = await client.post(`/public/broadcasts/${broadcastId}/validate-session`, { sessionId });
+      return res.data;
+    },
+    /** Heartbeat. Silence is what marks a viewer as gone. */
+    sessionPing: async (broadcastId: string, sessionId: string): Promise<void> => {
+      await client.post(`/public/broadcasts/${broadcastId}/session-ping`, { sessionId });
+    },
+    /** Leave deliberately, so the count drops now rather than on a timeout. */
+    leave: async (broadcastId: string, sessionId?: string): Promise<void> => {
+      await client.post(`/public/broadcasts/${broadcastId}/leave`, { sessionId });
+    },
+    /** Subscribe to the WebRTC tracks of a realtime broadcast. */
+    subscribe: async (payload: {
+      sdp?: string;
+      type?: string;
+      trackIds?: string[];
+      sessionId?: string;
+    }): Promise<BroadcastSubscribeAnswer> => {
+      const res = await client.post(`/public/broadcasts/subscribe`, payload);
+      return res.data;
+    },
+    /** Pin the viewer to one simulcast layer, or back to auto. */
+    switchQuality: async (payload: { track: Record<string, unknown>; sessionId?: string }): Promise<void> => {
+      await client.post(`/public/broadcasts/switch-quality`, payload);
+    },
+  };
+}

package/src/data/queries/useCheckouts.ts

@@ -2,6 +2,7 @@ import { useMutation } from "@tanstack/react-query";
 import { useForge } from "../../provider/ForgeProvider";
 import { bundleCouponRequestBody } from "../../ui/headless/checkout/bundleCoupon";
 import type { CartItem, TicketCartItem } from "../../contexts/CartContext";
+import type { IBookingFee, ProductDeliveryType } from "../../types/models";
 
 /** One line of a bundle, in the shape `POST /public/checkouts` expects. */
 export type CheckoutLineInput =
@@ -201,3 +202,85 @@ export function useFinalizeCheckout() {
     },
   });
 }
+
+// ── The recovery link ─────────────────────────────────────────────────────────
+
+/** Why a resumed line cannot go back in the basket. `null` when it can. */
+export type ResumeLineUnavailableReason = "removed" | "unavailable" | "sold_out";
+
+export type ResumeLineOption = { axis: string; value: string; swatchHex: string | null };
+
+/**
+ * One line of an abandoned basket, as `POST /public/checkouts/resume` answers.
+ *
+ * Every line comes back, including the ones that cannot be bought: the server
+ * re-reads the catalogue and reports WHY rather than shrinking the basket
+ * behind the buyer's back. `price` is today's figure in MAJOR units;
+ * `quotedUnitPriceCents` is what they were quoted when they left, in minor
+ * units, and is display-only.
+ */
+export type ResumeLine = {
+  type: "product" | "event_ticket" | "course" | "coaching";
+  quantity: number;
+  title: string;
+  coverImage: string | null;
+  price: number;
+  unitPriceCents: number;
+  quotedUnitPriceCents: number | null;
+  priceChanged: boolean;
+  available: boolean;
+  unavailableReason: ResumeLineUnavailableReason | null;
+  productId?: string;
+  productVariantId?: string;
+  deliveryType?: ProductDeliveryType;
+  payWhatYouWant?: boolean;
+  options?: ResumeLineOption[];
+  isGift?: boolean;
+  recipientName?: string | null;
+  recipientEmail?: string | null;
+  recipientMessage?: string | null;
+  attachedTo?: { type: "event"; entityId: string } | null;
+  eventId?: string;
+  ticketId?: string;
+  eventSlug?: string;
+  eventTitle?: string;
+  pwywAmount?: number | null;
+  bookingFee?: IBookingFee | null;
+  courseId?: string;
+  courseSlug?: string;
+  coachingProductId?: string;
+  coachingProductSlug?: string;
+};
+
+export type ResumedCheckout = {
+  checkoutId: string;
+  profileId: string;
+  source: "product" | "checkout" | "event" | "course" | "coaching" | "membership";
+  currency: string;
+  buyer: { firstName: string | null; lastName: string | null; email: string | null };
+  /** A code to re-apply at checkout, never an amount. */
+  couponCode: string | null;
+  lines: ResumeLine[];
+  /** Units across AVAILABLE lines only. */
+  itemCount: number;
+  /** Minor units, AVAILABLE lines only, at today's prices and before discount. */
+  subtotalCents: number;
+};
+
+/**
+ * Exchange a recovery-email token for the basket it names.
+ *
+ * A POST rather than a GET so the token stays out of access logs and `Referer`
+ * headers on the API hop. Anonymous by design: the recipient is usually a guest
+ * who never had an account, and the token IS the credential.
+ */
+export function useResumeCheckout() {
+  const { client, profileId } = useForge();
+
+  return useMutation<ResumedCheckout, unknown, { token: string }>({
+    mutationFn: async ({ token }) => {
+      const res = await client.post("/public/checkouts/resume", { profileId, token });
+      return res.data;
+    },
+  });
+}

package/src/data/queries/useMyBookings.ts

@@ -148,7 +148,15 @@ export type MyBooking = {
  */
 export type BookingLocation =
   | { type: "in_person"; address: string }
-  | { type: "online"; url: string };
+  | { type: "online"; url: string }
+  /**
+   * A call on the platform's own media network. No payload, and there never
+   * will be one: entry is a ticket minted per attempt and valid for minutes, so
+   * a URL here would be a forwardable key to somebody else's session. Draw the
+   * Join control from `bookingCallWindow` in `@tribe-nest/forge/media` and let
+   * `<BookingCallProvider>` fetch the ticket.
+   */
+  | { type: "video" };
 
 export type CancelBookingResult = {
   bookingId: string;