@tribe-nest/forge 3.31.0 → 3.35.0

package/src/ui/media/bookingSession.tsx

@@ -1,7 +1,7 @@
 import { useCallback, type ReactNode } from "react";
 
 import { MediaRoomProvider } from "@tribe-nest/media-client/react";
-import type { MediaGrants } from "@tribe-nest/media-protocol";
+import { MediaError, type MediaErrorCode, type MediaGrants } from "@tribe-nest/media-protocol";
 
 import { useForge } from "../../provider/ForgeProvider";
 
@@ -96,11 +96,42 @@ export function useBookingSessionCredentials(bookingId: string): () => Promise<B
   // function on every parent render, and `<MediaRoomProvider>` holds its
   // options in a ref precisely because that is the default mistake.
   return useCallback(async () => {
-    const res = await client.post(`/public/coaching/bookings/${bookingId}/session/join`, {});
-    return res.data as BookingSessionCredentials;
+    try {
+      const res = await client.post(`/public/coaching/bookings/${bookingId}/session/join`, {});
+      return res.data as BookingSessionCredentials;
+    } catch (error) {
+      throw credentialRefusal(error);
+    }
   }, [client, bookingId]);
 }
 
+/**
+ * The server's refusal, in the SDK's vocabulary, so the screen shows it.
+ *
+ * The join endpoint answers a person who belongs in the call with the REAL
+ * reason when it says no: the room opens in ten minutes, the session is not
+ * confirmed, the window has closed. Left as an axios error, that sentence never
+ * reached the screen: the SDK's `causeFromError` reads a non-`MediaError` as a
+ * dropped socket ("Request failed with status code 409"), and `callStatus`
+ * then says "Connection lost" about a call the person was never in. As a
+ * `MediaError` the cause is `refused`, which the screen renders as "Could not
+ * join this call" with the server's own sentence and a Try again. That is what
+ * every docblock on this surface promised and what the wire could not deliver.
+ *
+ * Only a response with a status is translated. A network failure (no
+ * response) really is a connection problem and keeps its own reading.
+ */
+function credentialRefusal(error: unknown): unknown {
+  const response = (error as { response?: { status?: number; data?: { message?: unknown } } } | null)?.response;
+  const status = response?.status;
+  if (typeof status !== "number") return error;
+
+  const message = typeof response?.data?.message === "string" ? response.data.message : undefined;
+  const code: MediaErrorCode =
+    status === 401 ? "unauthorized" : status === 404 ? "no_such_room" : status >= 500 ? "internal" : "bad_request";
+  return new MediaError(code, message ?? `${status}`, status >= 500);
+}
+
 export type BookingCallProviderProps = {
   bookingId: string;
   /** Rendered while the first connection is in flight. */
@@ -136,59 +167,16 @@ export function BookingCallProvider({
   );
 }
 
-/** How early the room opens, and how long it stays open. Mirrors the server. */
-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.
+ * The window logic lives in `bookingWindow.ts`, a module with NO media
+ * dependency, so `AccountDashboard` (in the `./ui` entry every site loads) can
+ * decide whether to DRAW a Join control without pulling the SDK into that
+ * bundle. Re-exported here so `@tribe-nest/forge/media` keeps its surface.
  */
-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,
-  };
-}
+export {
+  BOOKING_CALL_CLOSES_MINUTES_AFTER,
+  BOOKING_CALL_OPENS_MINUTES_BEFORE,
+  bookingCallWindow,
+  type BookingCallSubject,
+  type BookingCallWindow,
+} from "./bookingWindow";

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/media/index.ts

@@ -93,6 +93,15 @@ export type { MediaGrants, Peer, SubscribeRule } from "@tribe-nest/media-protoco
  * for both.
  */
 export { CallStage, type CallStageProps } from "./CallStage";
+
+/**
+ * What a call page shows OUTSIDE the window, when there is nothing to connect
+ * to. Exported because all three surfaces (admin, the client portal and a
+ * creator site) reached the same dead end: they mounted the call regardless,
+ * failed to connect, and reported "not yet connected", which answers neither of
+ * the two questions somebody arriving from an email is asking.
+ */
+export { CallWindowNotice, type CallWindowNoticeProps } from "./CallWindowNotice";
 export { CallHelpHint, type CallHelpHintProps } from "./CallHelpHint";
 export {
   callHeadCount,

package/src/ui/styled/AccountDashboard.tsx

@@ -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,97 @@ 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 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 this is a LINK and not the call
+ *
+ * It used to mount the room inline, between two rows of a list, at whatever
+ * width the portal happened to be. A call has its own full-screen page now
+ * (`/i/video-calls/:callId`) and it is the SAME address the coach opens from
+ * the dashboard, so both sides of a session meet in the same place instead of
+ * in two different-looking products. Linking also keeps the media SDK out of
+ * this bundle without needing a lazy boundary here: the page that needs
+ * mediasoup is the only thing that loads it.
+ *
+ * A plain anchor rather than a router `Link`, because this component ships to
+ * creator sites and must not assume which router mounted 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());
+
+  useEffect(() => {
+    const timer = setInterval(() => setNow(new Date()), 30_000);
+    return () => clearInterval(timer);
+  }, []);
+
+  const call = bookingCallWindow(booking, now);
+  if (!call.isVideo) return null;
+
+  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>
+    );
+  }
+
+  /**
+   * Open, but no address: nothing to link to, so draw nothing.
+   *
+   * Deliberately AFTER the window branch, so a session that has not opened yet
+   * still says when it does. That copy is about the SESSION and must not
+   * depend on whether a room record exists.
+   *
+   * This is reachable only for a booking confirmed before calls became
+   * addressable, since a confirmation now writes the record. The row above
+   * still says the session is a video call, so the buyer is not left thinking
+   * it is somewhere else; a dead button would be worse than none.
+   */
+  if (!booking.videoCallId) return null;
+
+  return (
+    <div style={{ marginTop: 12 }}>
+      <a href={`/i/video-calls/${booking.videoCallId}`} style={{ ...button, display: "inline-block" }}>
+        {tr("forge.account_dashboard.booking_join_video")}
+      </a>
     </div>
   );
 }