@tribe-nest/forge 3.26.0 → 3.31.0

package/src/ui/media/_tests/fakeNode.ts

@@ -0,0 +1,178 @@
+/**
+ * An in-process media node, small enough to read in one sitting.
+ *
+ * The SDK has a fuller one (`media-client/src/core/_tests/fakeSignalServer.ts`,
+ * which validates every frame against the contract schema), and this is
+ * deliberately NOT that: it cannot be imported here. `@tribe-nest/media-client`
+ * publishes an exports map with four subpaths and none of them reaches into
+ * `src/core/_tests`, so an import of it would resolve inside this monorepo
+ * (npm workspaces symlink everything) and nowhere else. The same trap
+ * `_tests/publishedResolvability.spec.ts` exists for.
+ *
+ * What it has to do is exactly enough to get `<MediaRoomProvider>` to
+ * "connected" and then push frames at it: accept a join, answer a transport,
+ * answer a consume, and deliver whatever event a spec wants.
+ */
+
+/**
+ * Restated rather than imported: `SocketEventMap` is internal to
+ * `media-client/src/core/socket.ts` and no published subpath reaches it. The
+ * shape has to match structurally or `webSocket={node.factory}` does not
+ * type-check, which is the point of writing it out.
+ */
+type SocketEventMap = {
+  open: { type: "open" };
+  message: { type: "message"; data: unknown };
+  error: { type: "error"; error?: unknown };
+  close: { type: "close"; code?: number; reason?: string };
+};
+
+type SocketEvent = SocketEventMap[keyof SocketEventMap];
+type Listener = (event: never) => void;
+
+const OPEN = 1;
+const CLOSED = 3;
+
+export class FakeSocket {
+  readyState = 0;
+  private readonly listeners = new Map<string, Set<Listener>>();
+
+  constructor(private readonly node: FakeNode) {}
+
+  addEventListener<K extends keyof SocketEventMap>(type: K, listener: (event: SocketEventMap[K]) => void): void {
+    const set = this.listeners.get(type) ?? new Set<Listener>();
+    set.add(listener as Listener);
+    this.listeners.set(type, set);
+  }
+
+  removeEventListener<K extends keyof SocketEventMap>(type: K, listener: (event: SocketEventMap[K]) => void): void {
+    this.listeners.get(type)?.delete(listener as Listener);
+  }
+
+  send(data: string): void {
+    this.node.receive(this, JSON.parse(data) as Record<string, unknown>);
+  }
+
+  close(): void {
+    if (this.readyState === CLOSED) return;
+    this.readyState = CLOSED;
+    this.emit("close", { type: "close", code: 1000 });
+  }
+
+  open(): void {
+    this.readyState = OPEN;
+    this.emit("open", { type: "open" });
+  }
+
+  deliver(frame: unknown): void {
+    if (this.readyState !== OPEN) return;
+    this.emit("message", { type: "message", data: JSON.stringify(frame) });
+  }
+
+  /** The node going away underneath us, which is a reconnect and not a leave. */
+  drop(code = 1006): void {
+    if (this.readyState === CLOSED) return;
+    this.readyState = CLOSED;
+    this.emit("close", { type: "close", code, reason: "node closed" });
+  }
+
+  private emit(type: keyof SocketEventMap, event: SocketEvent): void {
+    for (const listener of [...(this.listeners.get(type) ?? [])]) {
+      queueMicrotask(() => (listener as (e: SocketEvent) => void)(event));
+    }
+  }
+}
+
+export type FakeProducer = { producerId: string; identity: string; kind: "audio" | "video" };
+
+export type FakeNodeOptions = {
+  identity?: string;
+  peers?: { identity: string; name?: string; kind?: "human" | "agent" | "egress" | "sip" | "ingress" }[];
+  producers?: FakeProducer[];
+  recording?: boolean;
+  grants?: Record<string, unknown>;
+  /** Refuse the join with this code instead of accepting it. */
+  refuseWith?: string;
+};
+
+export class FakeNode {
+  readonly sockets: FakeSocket[] = [];
+  readonly received: Record<string, unknown>[] = [];
+
+  constructor(private readonly options: FakeNodeOptions = {}) {}
+
+  /** Pass as `webSocket` to `<MediaRoomProvider>`. */
+  readonly factory = (): FakeSocket => {
+    const socket = new FakeSocket(this);
+    this.sockets.push(socket);
+    queueMicrotask(() => socket.open());
+    return socket;
+  };
+
+  get socket(): FakeSocket {
+    const socket = this.sockets[this.sockets.length - 1];
+    if (!socket) throw new Error("no socket has been opened");
+    return socket;
+  }
+
+  receive(socket: FakeSocket, frame: Record<string, unknown>): void {
+    this.received.push(frame);
+    const id = frame.id as number;
+
+    if (frame.method === "join") {
+      if (this.options.refuseWith) {
+        socket.deliver({ id, ok: false, code: this.options.refuseWith });
+        return;
+      }
+      socket.deliver({ id, ok: true, data: { accepted: true } });
+      socket.deliver(this.joinedFrame());
+      return;
+    }
+
+    if (frame.method === "createTransport") {
+      socket.deliver({
+        id,
+        ok: true,
+        data: { transportId: "t-1", iceParameters: {}, iceCandidates: [], dtlsParameters: {} },
+      });
+      return;
+    }
+
+    if (frame.method === "consume") {
+      const producerId = frame.producerId as string;
+      const known = (this.options.producers ?? []).find((p) => p.producerId === producerId);
+      socket.deliver({
+        id,
+        ok: true,
+        data: { consumerId: `c-${producerId}`, producerId, kind: known?.kind ?? "video", rtpParameters: {} },
+      });
+      return;
+    }
+
+    socket.deliver({ id, ok: true, data: {} });
+  }
+
+  joinedFrame(): Record<string, unknown> {
+    return {
+      event: "joined",
+      identity: this.options.identity ?? "me",
+      room: "booking-1",
+      routerRtpCapabilities: { codecs: [] },
+      peers: (this.options.peers ?? []).map((p) => ({ kind: "human", ...p })),
+      producers: this.options.producers ?? [],
+      iceServers: [],
+      recording: this.options.recording ?? false,
+      grants: this.options.grants ?? { canPublish: true, canSubscribe: true, canPublishData: false },
+    };
+  }
+
+  /** Push any event frame at the live socket. */
+  event(frame: Record<string, unknown>): void {
+    this.socket.deliver(frame);
+  }
+}
+
+/** Let the fake socket's queued microtasks land. */
+export const settle = async (ms = 150): Promise<void> => {
+  await new Promise((resolve) => setTimeout(resolve, ms));
+};

package/src/ui/media/bookingSession.tsx

@@ -0,0 +1,194 @@
+import { useCallback, type ReactNode } from "react";
+
+import { MediaRoomProvider } from "@tribe-nest/media-client/react";
+import type { MediaGrants } from "@tribe-nest/media-protocol";
+
+import { useForge } from "../../provider/ForgeProvider";
+
+/**
+ * Live video for a coaching session, on the platform's own media network.
+ *
+ * A coaching product whose location is `video` holds its sessions in a room
+ * this platform provisions, rather than on a link the coach pasted in. There is
+ * no URL to render and there deliberately never will be: entry is a signed
+ * ticket minted per attempt and valid for minutes, so anything durable enough
+ * to put in a page or an email would be a forwardable key to somebody else's
+ * session.
+ *
+ * ## What a site does
+ *
+ * ```tsx
+ * const call = bookingCallWindow(booking);
+ *
+ * return call.isOpen ? (
+ *   <BookingCallProvider bookingId={booking.id} fallback={<p>Connecting…</p>}>
+ *     <CallStage />
+ *   </BookingCallProvider>
+ * ) : null;
+ * ```
+ *
+ * Inside the provider the whole surface is `useParticipants()`,
+ * `useRemoteTrack(producerId)`, `useLocalMedia()` and `useMediaRoom()` - the
+ * same hooks every other call surface uses, because there is one call UI.
+ *
+ * ## Why the credential is a CALLBACK
+ *
+ * `getCredentials` is called before EVERY connection attempt, not once. A join
+ * ticket expires in minutes and a session lasts an hour, so a token fetched
+ * once means the first reconnect after a lift or a wifi handover presents an
+ * expired one and the call does not come back. Passing the callback (rather
+ * than a token) is what makes reconnection work at all.
+ *
+ * ## What the server owns and this file does not mirror
+ *
+ * - **Who you are in the room.** Identity, name and grants are all derived
+ *   server-side from the booking: the client who bought it, or the coach who
+ *   holds `coaching.write` on the profile selling it. Nothing here can ask to
+ *   be somebody else, and there is no field through which it could.
+ * - **Whether the room is open.** `bookingCallWindow` below is for DRAWING
+ *   the button; the server refuses a ticket outside the window regardless, and
+ *   its answer is the one that counts.
+ * - **Whether the session is a video session.** Read `booking.location.type`,
+ *   already resolved server-side (this booking's override, else the product's
+ *   default). Re-deriving it in the browser would give two answers to one
+ *   question, and the wrong one sends a client to an empty room.
+ */
+
+/** Which side of the call this viewer is on. Derived by the server, never asked for. */
+export type BookingSessionRole = "host" | "guest";
+
+/**
+ * One join ticket, plus the window it belongs to.
+ *
+ * The first six fields are the flat shape every credential endpoint on this
+ * platform returns and the media SDK consumes; `role` and the two window
+ * timestamps are extras the SDK ignores and a call UI usually wants.
+ */
+export type BookingSessionCredentials = {
+  /** The signalling entrypoint. A load balancer, never a node this client picked. */
+  mediaUrl: string;
+  token: string;
+  /** ISO. When THIS ticket dies, not when the call does. */
+  expiresAt: string;
+  /** This viewer's identity in the room, as the other participants see it. */
+  identity: string;
+  roomId: string;
+  grants: MediaGrants;
+  role: BookingSessionRole;
+  /** ISO. The earliest moment the server will hand out a ticket for this session. */
+  roomOpensAt: string;
+  /** ISO. After this it refuses new tickets; anyone already connected stays. */
+  roomClosesAt: string;
+};
+
+/**
+ * Fetch a fresh join ticket for one booking. Hand this to
+ * `<MediaRoomProvider>`, or use `<BookingCallProvider>` which does it for you.
+ *
+ * The identity of the caller is the SESSION's - the endpoint takes the booking
+ * id and nothing else, and answers 404 for a booking that is not yours rather
+ * than 403, which would confirm the id exists.
+ */
+export function useBookingSessionCredentials(bookingId: string): () => Promise<BookingSessionCredentials> {
+  const { client } = useForge();
+
+  // Stable across renders for a given booking: an inline arrow would be a new
+  // 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;
+  }, [client, bookingId]);
+}
+
+export type BookingCallProviderProps = {
+  bookingId: string;
+  /** Rendered while the first connection is in flight. */
+  fallback?: ReactNode;
+  /**
+   * Follow the node's active speaker set automatically. On by default, and
+   * leaving it on is almost always right: a client that does not follow it
+   * shows black tiles in any room over the threshold.
+   */
+  autoSubscribe?: boolean;
+  children: ReactNode;
+};
+
+/**
+ * The room for one booking, wired to the credential endpoint.
+ *
+ * Mount it only when the call should be live. The provider connects on mount
+ * and closes on unmount, so rendering it behind a "Join" control is what stops
+ * a portal page from opening a media connection for every session in the list.
+ */
+export function BookingCallProvider({
+  bookingId,
+  fallback,
+  autoSubscribe = true,
+  children,
+}: BookingCallProviderProps): ReactNode {
+  const getCredentials = useBookingSessionCredentials(bookingId);
+
+  return (
+    <MediaRoomProvider getCredentials={getCredentials} autoSubscribe={autoSubscribe} fallback={fallback}>
+      {children}
+    </MediaRoomProvider>
+  );
+}
+
+/** 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.
+ */
+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,
+  };
+}