@tribe-nest/forge 3.31.0 → 3.34.0

package/src/ui/media/bookingWindow.ts

@@ -0,0 +1,81 @@
+/**
+ * When a coaching session's video room is open, computed WITHOUT the media SDK.
+ *
+ * This module deliberately imports nothing from `@tribe-nest/media-client`.
+ * `AccountDashboard` lives in the `./ui` entry that every code website loads,
+ * and it needs to know whether to draw a Join control long before anybody
+ * presses it. Keeping the window pure means that decision costs the site
+ * nothing; the call UI itself is loaded on the click (see `BookingCallScreen`).
+ * `@tribe-nest/forge/media` re-exports everything here, so a site that already
+ * imports from that barrel sees no difference.
+ */
+
+/**
+ * How early the room opens, and how long it stays open.
+ *
+ * A MIRROR of the server's `SESSION_JOIN_OPENS_MINUTES_BEFORE` and
+ * `SESSION_JOIN_CLOSES_MINUTES_AFTER` (`apps/backend/src/services/public/
+ * coaching/commands/bookingSession.ts`), and a mirror is the most this side
+ * can hold. The server's own `roomOpensAt` / `roomClosesAt` arrive only with a
+ * join ticket, and a ticket is only minted INSIDE the window, so the one moment
+ * a site needs "opens at" copy (before the window) is the one moment the
+ * server's timestamps are unreachable. These constants exist for that pre-join
+ * draw and nothing else: the decision is the server's, its refusal names the
+ * real window, and `<CallStage>` shows that refusal verbatim. Change the server
+ * and this pair together.
+ */
+export const BOOKING_CALL_OPENS_MINUTES_BEFORE = 15;
+export const BOOKING_CALL_CLOSES_MINUTES_AFTER = 120;
+
+const MINUTE = 60_000;
+
+/** What a booking has to carry for the window to be computable. */
+export type BookingCallSubject = {
+  status: string;
+  sessionStartTime: string;
+  sessionEndTime: string;
+  location?: { type: string } | null;
+};
+
+export type BookingCallWindow = {
+  /** Does this session happen on a platform video call at all? */
+  isVideo: boolean;
+  /** May a ticket be minted right now? Draw the Join control from this. */
+  isOpen: boolean;
+  /** Before the window, so the answer is "come back at". */
+  opensAt: Date;
+  /** After it the server refuses new tickets. */
+  closesAt: Date;
+};
+
+/**
+ * Is this session's room open, and when does it open?
+ *
+ * For DRAWING the control and nothing else. The server applies the same window
+ * and its refusal is the decision: a clock that is ten minutes fast must not be
+ * able to talk itself into a room, and a clock that is ten minutes slow must
+ * not hide a session that has already started. Show the server's refusal
+ * verbatim when a join fails rather than pre-judging it here.
+ *
+ * `now` is a parameter so a caller can drive it from a ticking value and get a
+ * re-render at the moment the window opens; a hook reading the clock itself
+ * would be stale until something else happened to re-render.
+ */
+export function bookingCallWindow(booking: BookingCallSubject, now: Date = new Date()): BookingCallWindow {
+  const startsAt = new Date(booking.sessionStartTime);
+  const endsAt = new Date(booking.sessionEndTime);
+  const opensAt = new Date(startsAt.getTime() - BOOKING_CALL_OPENS_MINUTES_BEFORE * MINUTE);
+  const closesAt = new Date(endsAt.getTime() + BOOKING_CALL_CLOSES_MINUTES_AFTER * MINUTE);
+
+  // A cancelled session has no room to enter, which is also why the server
+  // withholds `location` for anything that is not confirmed - so this reads
+  // `isVideo: false` for one, rather than offering a button that 409s.
+  const isVideo = booking.status === "confirmed" && booking.location?.type === "video";
+
+  return {
+    isVideo,
+    isOpen: isVideo && now.getTime() >= opensAt.getTime() && now.getTime() <= closesAt.getTime(),
+    opensAt,
+    closesAt,
+  };
+}

package/src/ui/media/callState.ts

@@ -177,13 +177,27 @@ export function remoteAudioProducerIds(input: {
 
 export type CallStatusTone = "connecting" | "live" | "reconnecting" | "ended" | "failed";
 
+/**
+ * The connection, as KEYS into Forge's bundles.
+ *
+ * `callStatus` is pure and has no locale, so it names copy rather than
+ * carrying it: `CallStage` puts the keys through `useForgeT()`, and a site
+ * laying out its own status line does the same. Returning English sentences
+ * from here was how the whole call screen shipped in one language on sites
+ * whose every other word was German.
+ *
+ * `detailText` is the exception, on purpose: it is the SERVER'S own sentence
+ * (a refusal message, a close reason) and is shown verbatim, never translated
+ * into a friendlier lie.
+ */
 export type CallStatus = {
   tone: CallStatusTone;
-  /** Always shown. Connection state is CONTENT, never a help hint. */
-  headline: string;
-  /** The server's own words when it has any. Shown verbatim rather than
-   * translated into a friendlier lie. */
-  detail?: string;
+  /** Always shown. Connection state is CONTENT, never a help hint. `forge.call_stage.*`. */
+  headlineKey: string;
+  /** Our own second line, when there is one. `forge.call_stage.*`. */
+  detailKey?: string;
+  /** The server's own words when it has any. Shown verbatim. */
+  detailText?: string;
   /** Is pressing something the right response? Only when waiting will not fix it. */
   canRetry: boolean;
 };
@@ -205,6 +219,9 @@ export type CallStatusInput = {
   recovering?: boolean;
 };
 
+const ENDED = "forge.call_stage.status_ended";
+const LEFT = "forge.call_stage.status_left";
+
 /**
  * The room's states, told honestly.
  *
@@ -235,23 +252,25 @@ export function callStatus(input: CallStatusInput): CallStatus {
   if (input.phase === "closed") {
     return {
       tone: "ended",
-      headline: "The call has ended",
-      ...(input.closedReason ? { detail: input.closedReason } : {}),
+      headlineKey: ENDED,
+      ...(input.closedReason ? { detailText: input.closedReason } : {}),
       canRetry: false,
     };
   }
 
-  if (connectionState === "connected") return { tone: "live", headline: "Connected", canRetry: false };
+  if (connectionState === "connected") {
+    return { tone: "live", headlineKey: "forge.call_stage.status_connected", canRetry: false };
+  }
 
   if (connectionState === "idle" || connectionState === "connecting") {
-    return { tone: "connecting", headline: "Connecting to the call", canRetry: false };
+    return { tone: "connecting", headlineKey: "forge.call_stage.status_connecting", canRetry: false };
   }
 
   if (connectionState === "closed") {
     if (error?.type === "room_closed") {
-      return { tone: "ended", headline: "The call has ended", detail: error.reason, canRetry: false };
+      return { tone: "ended", headlineKey: ENDED, detailText: error.reason, canRetry: false };
     }
-    return { tone: "ended", headline: "You have left the call", canRetry: false };
+    return { tone: "ended", headlineKey: LEFT, canRetry: false };
   }
 
   // Everything below is `reconnecting`, where the cause is the whole story.
@@ -259,12 +278,12 @@ export function callStatus(input: CallStatusInput): CallStatus {
     case "refused":
       return {
         tone: "failed",
-        headline: "Could not join this call",
-        detail: error.message ?? error.code,
+        headlineKey: "forge.call_stage.status_refused",
+        detailText: error.message ?? error.code,
         canRetry: true,
       };
     case "room_closed":
-      return { tone: "ended", headline: "The call has ended", detail: error.reason, canRetry: false };
+      return { tone: "ended", headlineKey: ENDED, detailText: error.reason, canRetry: false };
     case "draining":
       // A drain is the node asking to be left, so the move is the SDK's job and
       // a button would only get in its way - as long as the move is actually
@@ -274,30 +293,30 @@ export function callStatus(input: CallStatusInput): CallStatus {
       return recovering
         ? {
             tone: "reconnecting",
-            headline: "Moving you to another server",
-            detail: "This takes a few seconds and nobody else is dropped.",
+            headlineKey: "forge.call_stage.status_moving",
+            detailKey: "forge.call_stage.status_moving_detail",
             canRetry: false,
           }
         : {
             tone: "failed",
-            headline: "Could not move you to another server",
-            detail: "Nobody else was dropped. Try again to rejoin.",
+            headlineKey: "forge.call_stage.status_move_failed",
+            detailKey: "forge.call_stage.status_move_failed_detail",
             canRetry: true,
           };
     case "closed_by_client":
-      return { tone: "ended", headline: "You have left the call", canRetry: false };
+      return { tone: "ended", headlineKey: LEFT, canRetry: false };
     default:
       return recovering
         ? {
             tone: "reconnecting",
-            headline: "Connection lost, reconnecting",
-            detail: "Everyone else is still in the call.",
+            headlineKey: "forge.call_stage.status_reconnecting",
+            detailKey: "forge.call_stage.status_reconnecting_detail",
             canRetry: true,
           }
         : {
             tone: "failed",
-            headline: "Connection lost",
-            detail: "Everyone else is still in the call. Try again to rejoin.",
+            headlineKey: "forge.call_stage.status_lost",
+            detailKey: "forge.call_stage.status_lost_detail",
             canRetry: true,
           };
   }

package/src/ui/styled/AccountDashboard.tsx

@@ -1,4 +1,4 @@
-import { useEffect, useState } from "react";
+import { lazy, Suspense, useEffect, useState } from "react";
 import {
   usePublicAuth,
   useUserOrders,
@@ -36,6 +36,7 @@ import { useThemeTokens } from "../theme/ForgeThemeProvider";
 import { useSiteConfig } from "../../data/queries/useWebsite";
 import { useAmountFormatter } from "../format/useFormatCurrency";
 import { Loading } from "./Loading";
+import { bookingCallWindow } from "../media/bookingWindow";
 import { formatCountdown } from "./EventWaitlist";
 import { AddToCalendar } from "./AddToCalendar";
 import { WalletPassButtons } from "./WalletPassButtons";
@@ -930,13 +931,13 @@ function BookingLocationLine({
   }
 
   /**
-   * A call on the platform's own media network. A LINE, never the call itself.
+   * A call on the platform's own media network. A LINE, and the way in is the
+   * `BookingCallEntry` control the row renders below it.
    *
    * There is no URL to render and there never will be: entry is a ticket minted
-   * per attempt and valid for minutes. Mounting the room here is also the wrong
-   * place mechanically - the call UI lives behind `@tribe-nest/forge/media`,
-   * whose media-client dependency is an OPTIONAL peer, and importing it from
-   * this entry point would break every site that has not installed it.
+   * per attempt and valid for minutes, so the Join control mints one on the
+   * click and mounts the call in place (`BookingCallEntry`, loaded lazily so a
+   * site pays for the SDK only when somebody presses it).
    */
   if (location.type === "video") {
     return (
@@ -1073,6 +1074,105 @@ function BookingRow({ booking, ctx }: { booking: MyBooking; ctx: TabContext }) {
       </div>
 
       {picking && <RescheduleSlotPicker booking={booking} onDone={() => setPicking(false)} />}
+
+      {/* The way INTO a video session: a Join control while the room is open,
+          the call itself once pressed. Nothing for any other kind of session. */}
+      {!cancelled && <BookingCallEntry booking={booking} />}
+    </div>
+  );
+}
+
+/**
+ * The call UI, fetched on the click. `import()` splits it (and the media SDK
+ * with mediasoup underneath) out of the `./ui` bundle, so a visitor who never
+ * joins a call never downloads it. `bookingCallWindow` is deliberately in a
+ * module with no such dependency, which is what lets the CONTROL be decided
+ * here without loading the SDK.
+ */
+const LazyBookingCallScreen = lazy(() => import("../media/BookingCallScreen"));
+
+/**
+ * The buyer's way into a coaching video call, on a code website.
+ *
+ * The room, the hooks, the credential endpoint and `BookingCallProvider` all
+ * shipped before this control existed, and none of it was reachable from the
+ * one place a client looks: the row for their session printed "Video call on
+ * this site" and offered nothing to press. Admin's own help text told coaches
+ * the client joins "from their account on your site", so this is where it has
+ * to be. It renders the SAME `<CallStage>` the coach sees in admin.
+ *
+ * ## Why the call is mounted only after a click
+ *
+ * The provider connects on mount and closes on unmount. Rendering it for every
+ * row in a list of sessions would open a media connection per row, against
+ * rooms the server would then have to provision. So it lives behind Join, and
+ * leaving unmounts it.
+ *
+ * ## Why the window ticks
+ *
+ * `bookingCallWindow` takes `now` as an argument rather than reading the clock,
+ * so a portal left open across the opening minute has to be told. A minute is
+ * fine: the server applies the same window and refuses a ticket outside it,
+ * and its refusal is what `<CallStage>` shows rather than a pre-judgement here.
+ */
+function BookingCallEntry({ booking }: { booking: MyBooking }) {
+  const { button } = useCardStyles();
+  const tr = useForgeT();
+  const [now, setNow] = useState(() => new Date());
+  const [joined, setJoined] = useState(false);
+
+  useEffect(() => {
+    const timer = setInterval(() => setNow(new Date()), 30_000);
+    return () => clearInterval(timer);
+  }, []);
+
+  const call = bookingCallWindow(booking, now);
+  if (!call.isVideo) return null;
+
+  if (joined) {
+    // The provider's lifetime is exactly the call's: unmounting this subtree is
+    // what closes the socket, stops the local tracks and puts the camera light
+    // out. Leaving therefore goes through state, not through a `close()` that
+    // leaves a live provider mounted to reconnect on its next render.
+    return (
+      <div style={{ marginTop: 12 }}>
+        <Suspense fallback={<Loading />}>
+          <LazyBookingCallScreen
+            bookingId={booking.id}
+            title={booking.coachingProductTitle}
+            onLeave={() => setJoined(false)}
+          />
+        </Suspense>
+      </div>
+    );
+  }
+
+  if (!call.isOpen) {
+    // State the buyer has to act on, so it is content and stays visible: the
+    // room is not open yet, and this is when to come back.
+    return (
+      <div style={{ fontSize: 13, opacity: 0.7, marginTop: 12 }}>
+        {now < call.opensAt
+          ? tr("forge.account_dashboard.booking_video_opens_at", {
+              datetime: call.opensAt.toLocaleString(undefined, {
+                weekday: "short",
+                day: "numeric",
+                month: "short",
+                hour: "numeric",
+                minute: "2-digit",
+                timeZone: booking.coachingProductTimezone ?? undefined,
+              }),
+            })
+          : tr("forge.account_dashboard.booking_video_closed")}
+      </div>
+    );
+  }
+
+  return (
+    <div style={{ marginTop: 12 }}>
+      <button type="button" onClick={() => setJoined(true)} style={button}>
+        {tr("forge.account_dashboard.booking_join_video")}
+      </button>
     </div>
   );
 }

package/src/ui/styled/_tests/AccountDashboardBookingCall.spec.tsx

@@ -0,0 +1,166 @@
+import { describe, it, expect } from "vitest";
+import { renderToStaticMarkup } from "react-dom/server";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { ForgeClientProvider } from "../../../provider/ForgeProvider";
+import { PublicAuthContext } from "../../../contexts/PublicAuthContext";
+import { ForgeThemeProvider } from "../../theme/ForgeThemeProvider";
+import type { MyBooking } from "../../../data/queries/useMyBookings";
+import { AccountDashboard } from "../AccountDashboard";
+
+/**
+ * The account page's way INTO a coaching video call.
+ *
+ * The room, the hooks, the credential endpoint and `BookingCallProvider` all
+ * shipped, and on a code website none of it was reachable: the row for a
+ * video session printed "Video call on this site" and offered nothing to
+ * press, while admin's help text told coaches the client joins "from their
+ * account on your site". This pins the control the row now draws.
+ *
+ * Rendered through `react-dom/server`: no DOM, no effects, so the bookings
+ * query is SEEDED into the react-query cache. That keeps the real
+ * `useMyBookings` in the path, and a rename of its query key fails here. The
+ * call itself is behind a click and a `React.lazy`, so nothing here ever
+ * touches the media SDK: the spec is about the CONTROL, and it proves the SDK
+ * is not needed to decide whether to draw it.
+ */
+
+const PROFILE_ID = "profile-1";
+const ACCOUNT_ID = "account-1";
+const MINUTE = 60_000;
+
+const member = {
+  id: ACCOUNT_ID,
+  email: "client@example.com",
+  firstName: "Client",
+  lastName: "Person",
+  kind: "fan",
+  status: "active",
+  createdAt: "2026-01-01T00:00:00.000Z",
+  updatedAt: "2026-01-01T00:00:00.000Z",
+  membership: null,
+};
+
+const booking = (overrides: Partial<MyBooking> = {}): MyBooking => {
+  const start = new Date(Date.now() + 5 * MINUTE);
+  const end = new Date(start.getTime() + 60 * MINUTE);
+  return {
+    id: "booking-1",
+    status: "confirmed",
+    email: "client@example.com",
+    firstName: "Client",
+    lastName: "Person",
+    totalAmount: 40,
+    totalAmountInChargedCurrency: null,
+    currency: "USD",
+    chargedCurrency: null,
+    refundState: null,
+    refundedAmountCents: null,
+    selfCancelledAt: null,
+    cancellationOutcome: null,
+    createdAt: "2026-01-01T00:00:00.000Z",
+    coachingBookingSlotId: "slot-1",
+    sessionStartTime: start.toISOString(),
+    sessionEndTime: end.toISOString(),
+    coachingProductId: "product-1",
+    coachingProductSlug: "video-session",
+    coachingProductTitle: "Video session",
+    coachingProductTimezone: null,
+    coachingProductDurationMinutes: 60,
+    cancellation: {
+      policy: null,
+      cutoffHours: null,
+      terms: null,
+      description: null,
+      canCancel: false,
+      reason: null,
+      deadline: null,
+    },
+    location: { type: "video" } as MyBooking["location"],
+    canReschedule: false,
+    rescheduleReason: null,
+    calendarUrl: null,
+    calendarWebcalUrl: null,
+    ...overrides,
+  };
+};
+
+function render(rows: MyBooking[]): string {
+  const queryClient = new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  queryClient.setQueryData(["my-bookings", ACCOUNT_ID, PROFILE_ID, 1, 20], {
+    data: rows,
+    total: rows.length,
+    page: 1,
+    limit: 20,
+  });
+
+  return renderToStaticMarkup(
+    <QueryClientProvider client={queryClient}>
+      <ForgeClientProvider apiUrl="http://api.test" profileId={PROFILE_ID}>
+        <PublicAuthContext.Provider
+          value={{ user: member, currencies: null, userSelectedCurrency: "USD", logout: () => {} } as never}
+        >
+          <ForgeThemeProvider
+            theme={{ colors: { text: "#111111", background: "#ffffff", primary: "#6d28d9" }, cornerRadius: 8 }}
+          >
+            <AccountDashboard tab="bookings" onNavigateMembership={() => {}} />
+          </ForgeThemeProvider>
+        </PublicAuthContext.Provider>
+      </ForgeClientProvider>
+    </QueryClientProvider>,
+  );
+}
+
+describe("AccountDashboard: the way into a coaching video call", () => {
+  it("REGRESSION: offers Join for a video session whose room is open", () => {
+    // Starts in 5 minutes: inside the 15-minutes-early window.
+    const html = render([booking()]);
+
+    expect(html).toContain("Video session");
+    expect(html).toContain("Join video call");
+    // The line still says where the session is; the control is in addition.
+    expect(html).toContain("Video call on this site");
+  });
+
+  it("says when the room opens, rather than offering a Join that would 409", () => {
+    const start = new Date(Date.now() + 3 * 60 * MINUTE);
+    const html = render([
+      booking({
+        sessionStartTime: start.toISOString(),
+        sessionEndTime: new Date(start.getTime() + 60 * MINUTE).toISOString(),
+      }),
+    ]);
+
+    expect(html).not.toContain("Join video call");
+    expect(html).toContain("the room opens");
+  });
+
+  it("says the room has closed once the window is over", () => {
+    const start = new Date(Date.now() - 5 * 60 * MINUTE);
+    const html = render([
+      booking({
+        sessionStartTime: start.toISOString(),
+        sessionEndTime: new Date(start.getTime() + 60 * MINUTE).toISOString(),
+      }),
+    ]);
+
+    expect(html).not.toContain("Join video call");
+    expect(html).toContain("room has closed");
+  });
+
+  it("draws nothing for a session that is not a video call", () => {
+    const html = render([
+      booking({ location: { type: "online", url: "https://meet.example.com/x" } as MyBooking["location"] }),
+    ]);
+
+    expect(html).not.toContain("Join video call");
+    expect(html).not.toContain("the room opens");
+    expect(html).toContain("https://meet.example.com/x");
+  });
+
+  it("draws nothing for a cancelled session, whose room the server withholds", () => {
+    const html = render([booking({ status: "canceled", selfCancelledAt: "2026-01-02T00:00:00.000Z", location: null })]);
+
+    expect(html).not.toContain("Join video call");
+    expect(html).not.toContain("the room opens");
+  });
+});