@tribe-nest/forge 3.37.0 → 3.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tribe-nest/forge",
-  "version": "3.37.0",
+  "version": "3.39.0",
   "publishConfig": {
     "access": "public"
   },

package/src/data/queries/useBroadcasts.ts

@@ -38,14 +38,24 @@ export function useValidateBroadcastPass() {
  * 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) {
+/**
+ * The viewer's validated pass, sent on every read that can return playback
+ * credentials.
+ *
+ * A gated broadcast withholds `liveUrl` and `realtimeConfig` from a caller who
+ * cannot show one, because the paywall used to be drawn in the browser only:
+ * the public read handed the manifest and the realtime session to anybody who
+ * asked, and the ticket box in front of it was decoration. Passing it here is
+ * what keeps a paying viewer playing.
+ */
+export function useLiveBroadcast(broadcastId?: string, passId?: string) {
   const { client, profileId } = useForge();
 
   return useQuery<ILiveBroadcast>({
-    queryKey: ["live-broadcast", profileId, broadcastId],
+    queryKey: ["live-broadcast", profileId, broadcastId, passId ?? null],
     queryFn: async () => {
       const res = await client.get(`/public/broadcasts/${broadcastId}`, {
-        params: { profileId },
+        params: { profileId, ...(passId ? { passId } : {}) },
       });
       return res.data;
     },
@@ -61,14 +71,14 @@ export function useLiveBroadcast(broadcastId?: string) {
  * 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) {
+export function useLiveBroadcastPoll(broadcastId?: string, intervalMs = 5000, passId?: string) {
   const { client, profileId } = useForge();
 
   return useQuery<ILiveBroadcast>({
-    queryKey: ["live-broadcast-poll", profileId, broadcastId],
+    queryKey: ["live-broadcast-poll", profileId, broadcastId, passId ?? null],
     queryFn: async () => {
       const res = await client.get(`/public/broadcasts/${broadcastId}`, {
-        params: { profileId },
+        params: { profileId, ...(passId ? { passId } : {}) },
       });
       return res.data;
     },
@@ -138,6 +148,30 @@ export type BroadcastSubscribeAnswer = {
   sessionDescription: { sdp: string; type: string };
 };
 
+/**
+ * A join ticket for a broadcast's live room on the platform's media plane.
+ *
+ * A superset of what the media SDK reads (`mediaUrl` and `token` are the only
+ * two it touches). The rest is what the server says about the ticket it just
+ * minted, useful to a site that wants to show it and ignored by the room.
+ *
+ * Written out here rather than imported from `@tribe-nest/media-client` on
+ * purpose: this module is loaded by every page of every site, and the media
+ * SDK is browser-only. A type import would be erased, but the next person to
+ * reach for a value from that package would not notice they had crossed the
+ * line.
+ */
+export type BroadcastViewerCredentials = {
+  /** The signalling entrypoint. A load balancer, never a node the client picked. */
+  mediaUrl: string;
+  token: string;
+  /** ISO. When THIS ticket dies, not when the broadcast does. */
+  expiresAt?: string;
+  /** This viewer's identity in the live room. Minted per viewer, never reused. */
+  identity?: string;
+  roomId?: 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
@@ -164,18 +198,39 @@ export function useBroadcastSessionApi() {
     leave: async (broadcastId: string, sessionId?: string): Promise<void> => {
       await client.post(`/public/broadcasts/${broadcastId}/leave`, { sessionId });
     },
+    /**
+     * Mint a viewer credential for the broadcast's live room on the media plane.
+     *
+     * The PASS is the credential here: the endpoint is public and takes no
+     * bearer token, and it validates the pass exactly as `validate-session`
+     * does before minting anything for a gated broadcast.
+     *
+     * It answers 409 when the room is full, when realtime is switched off, or
+     * when nothing is live. That is a designed answer rather than a fault, and
+     * the caller's whole response to it is to watch the HLS stream instead.
+     */
+    viewerToken: async (payload: { broadcastId: string; passId?: string }): Promise<BroadcastViewerCredentials> => {
+      const res = await client.post(`/streams/v2/public/viewer-token`, payload);
+      return res.data;
+    },
     /** Subscribe to the WebRTC tracks of a realtime broadcast. */
     subscribe: async (payload: {
       sdp?: string;
       type?: string;
       trackIds?: string[];
       sessionId?: string;
+      /** The validated pass. A gated broadcast refuses a subscribe without it. */
+      passId?: 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> => {
+    switchQuality: async (payload: {
+      track: Record<string, unknown>;
+      sessionId?: string;
+      passId?: string;
+    }): Promise<void> => {
       await client.post(`/public/broadcasts/switch-quality`, payload);
     },
   };

package/src/i18n/de.json

@@ -159,6 +159,9 @@
   "forge.broadcast_pass_validation.validating": "Wird geprüft…",
   "forge.broadcast_player.anonymous": "Anonym",
   "forge.broadcast_player.chat": "Chat",
+  "forge.broadcast_player.fallback_help": "Der Stream mit geringer Verzögerung hat nur begrenzt Plätze und ist gerade entweder voll oder nicht aktiv. Der Standard-Stream zeigt dieselbe Übertragung einige Sekunden später. Sonst ändert sich nichts an der Seite.",
+  "forge.broadcast_player.fallback_help_label": "Warum ist das nicht der Stream mit geringer Verzögerung?",
+  "forge.broadcast_player.fallback_notice": "Du siehst den Standard-Stream",
   "forge.broadcast_player.fullscreen": "Vollbild",
   "forge.broadcast_player.message_label": "Nachricht",
   "forge.broadcast_player.pinned": "Angepinnt",
@@ -168,6 +171,8 @@
   "forge.broadcast_player.quality_low": "Niedrig",
   "forge.broadcast_player.quality_medium": "Mittel",
   "forge.broadcast_player.send": "Senden",
+  "forge.broadcast_player.sound_off": "Ton ausschalten",
+  "forge.broadcast_player.sound_on": "Ton einschalten",
   "forge.broadcast_player.started": "Vor {duration} gestartet",
   "forge.broadcast_player.watching_now": "{count} schauen gerade zu",
   "forge.broadcast_ticket_purchase.buy_tickets": "Tickets kaufen",

package/src/i18n/en.json

@@ -159,6 +159,9 @@
   "forge.broadcast_pass_validation.validating": "Validating…",
   "forge.broadcast_player.anonymous": "Anonymous",
   "forge.broadcast_player.chat": "Chat",
+  "forge.broadcast_player.fallback_help": "The low-latency stream holds a limited number of viewers, and right now it is either full or not running. The standard stream carries the same broadcast a few seconds behind. Nothing else about the page changes.",
+  "forge.broadcast_player.fallback_help_label": "Why is this not the low-latency stream?",
+  "forge.broadcast_player.fallback_notice": "Watching the standard stream",
   "forge.broadcast_player.fullscreen": "Fullscreen",
   "forge.broadcast_player.message_label": "Message",
   "forge.broadcast_player.pinned": "Pinned",
@@ -168,6 +171,8 @@
   "forge.broadcast_player.quality_low": "Low",
   "forge.broadcast_player.quality_medium": "Medium",
   "forge.broadcast_player.send": "Send",
+  "forge.broadcast_player.sound_off": "Turn sound off",
+  "forge.broadcast_player.sound_on": "Turn sound on",
   "forge.broadcast_player.started": "Started {duration} ago",
   "forge.broadcast_player.watching_now": "{count} watching now",
   "forge.broadcast_ticket_purchase.buy_tickets": "Buy tickets",

package/src/types/models.ts

@@ -1709,6 +1709,11 @@ export type ILiveEvent = {
 
 export type ILiveBroadcast = {
   id: string;
+  /**
+   * The v1 realtime path, over Cloudflare Calls. Kept exactly as it is until v1
+   * itself is retired. Not the same thing as `realtime` below, and a broadcast
+   * carries one or the other, never both.
+   */
   realtimeConfig?: {
     sessionId: string;
     tracks: {
@@ -1716,6 +1721,19 @@ export type ILiveBroadcast = {
       trackName: string;
     }[];
   };
+  /**
+   * Can this broadcast be watched over the platform's own media plane?
+   *
+   * `available` says the live room exists and the feature is on, and it says
+   * nothing about whether THIS viewer will get in: the room has a hard cap and
+   * the token endpoint is the only thing that knows how full it is. So it is a
+   * flag to ATTEMPT the plane on, never a promise, and a player that treats it
+   * as one leaves the hundred-and-first viewer on a black rectangle.
+   *
+   * It deliberately carries no room id and no token. The read that returns it
+   * is unauthenticated, so everything in it is public.
+   */
+  realtime?: { available: boolean };
   events: {
     eventId: string;
     eventTitle: string;

package/src/ui/headless/broadcast/useBroadcastWatch.ts

@@ -38,8 +38,12 @@ const readSessionId = (broadcastId?: string): string | null => {
  * be checked without a browser.
  */
 export function useBroadcastWatch(broadcastId?: string) {
-  const broadcastQuery = useLiveBroadcast(broadcastId);
-  const pollQuery = useLiveBroadcastPoll(broadcastId);
+  // The stored pass rides along on both reads: a gated broadcast withholds its
+  // playback credentials from a caller who cannot show one, so a read without
+  // it comes back playable-looking and empty.
+  const storedSessionId = readSessionId(broadcastId) ?? undefined;
+  const broadcastQuery = useLiveBroadcast(broadcastId, storedSessionId);
+  const pollQuery = useLiveBroadcastPoll(broadcastId, 5000, storedSessionId);
   const validatePass = useValidateBroadcastPass();
   const sessionApi = useBroadcastSessionApi();
 

package/src/ui/headless/work/index.ts

@@ -8,6 +8,9 @@ export {
   useWorkInvite,
   useAcceptWorkInvite,
   useWorkProjectInvoices,
+  useWorkSharedDocuments,
+  useWorkOpenSharedDocument,
+  useUploadWorkDocument,
   formatWorkMoney,
   formatWorkDate,
   type WorkProjectSummary,
@@ -21,5 +24,6 @@ export {
   type WorkInviteContext,
   type WorkInviteAcceptResult,
   type WorkProjectInvoice,
+  type WorkSharedDocument,
   type UseWorkTaskCommentsResult,
 } from "./useWorkPortal";

package/src/ui/headless/work/useWorkPortal.ts

@@ -1,4 +1,5 @@
 import { useMutation, useQuery, useQueryClient, type UseQueryResult } from "@tanstack/react-query";
+import axios from "axios";
 import { useForge } from "../../../provider/ForgeProvider";
 
 /**
@@ -89,6 +90,25 @@ export interface WorkTaskAttachment {
   size: number | null;
 }
 
+/**
+ * A case-file document the firm has shared with the client, or one the client
+ * put there themselves. A file document describes itself but never carries an
+ * address: the bytes come only through `useWorkOpenSharedDocument`.
+ */
+export interface WorkSharedDocument {
+  id: string;
+  title: string;
+  docType: "page" | "file";
+  updatedAt: string;
+  sharedAt: string;
+  file: {
+    mediaId: string;
+    filename: string | null;
+    size: number;
+    type: string;
+  } | null;
+}
+
 export interface WorkProjectInvoice {
   id: string;
   invoiceNumber: string;
@@ -110,7 +130,7 @@ export interface WorkInviteContext {
   firstName: string | null;
   /**
    * The invited address already has an account, so the invite grants portal
-   * access but cannot set a credential — render "sign in", not a password
+   * access but cannot set a credential: render "sign in", not a password
    * form (C10).
    */
   requiresExistingLogin?: boolean;
@@ -124,7 +144,7 @@ export interface WorkInviteAcceptResult {
    */
   requiresLogin?: boolean;
   token?: string;
-  /** Rotating refresh token for the portal session (backend §7) — persist it. */
+  /** Rotating refresh token for the portal session (backend §7). Persist it. */
   refreshToken?: string;
   projectId: string;
   account: { id: string; email: string; firstName: string | null; lastName: string | null };
@@ -142,12 +162,14 @@ const keys = {
     ["work-portal-task-attachments", profileId, projectId, taskId] as const,
   projectInvoices: (profileId: string | undefined, projectId: string) =>
     ["work-portal-project-invoices", profileId, projectId] as const,
+  sharedDocuments: (profileId: string | undefined, projectId: string) =>
+    ["work-portal-shared-documents", profileId, projectId] as const,
 };
 
 // ── Authed client's projects ─────────────────────────────────────────────────
 
 /** The authenticated client's (non-archived) client projects with a task/done
- * summary — GET /public/work/projects. The token is the identity. */
+ * summary: GET /public/work/projects. The token is the identity. */
 export function useWorkPortalProjects(): UseQueryResult<WorkProjectSummary[]> {
   const { client, profileId } = useForge();
   return useQuery<WorkProjectSummary[]>({
@@ -163,7 +185,7 @@ export function useWorkPortalProjects(): UseQueryResult<WorkProjectSummary[]> {
 // ── Authed client's single-project report ────────────────────────────────────
 
 /** The authenticated client's overview + billable-only time report for one of
- * their projects — GET /public/work/projects/:id/report. */
+ * their projects: GET /public/work/projects/:id/report. */
 export function useWorkProjectReport(projectId: string): UseQueryResult<WorkProjectReportData> {
   const { client, profileId } = useForge();
   return useQuery<WorkProjectReportData>({
@@ -180,7 +202,7 @@ export function useWorkProjectReport(projectId: string): UseQueryResult<WorkProj
 
 // ── Public tokenized report (no login) ───────────────────────────────────────
 
-/** Login-free tokenized share of a project's time report — GET
+/** Login-free tokenized share of a project's time report: GET
  * /public/work/time-report/:token. The signed token IS the authorization. */
 export function useWorkTokenReport(token: string): UseQueryResult<WorkProjectReportData> {
   const { client } = useForge();
@@ -208,7 +230,7 @@ export interface UseWorkTaskCommentsResult {
 
 /**
  * The authenticated client's comment thread for a single task on one of their
- * projects — GET/POST /public/work/projects/:projectId/tasks/:taskId/comments.
+ * projects: GET/POST /public/work/projects/:projectId/tasks/:taskId/comments.
  * Newest first. The bearer token IS the client identity (server-enforced).
  * Posting invalidates the thread so the new comment appears. Tier-1 primitive:
  * returns clean data + a bound mutation, renders nothing.
@@ -259,7 +281,7 @@ export function useWorkTaskComments(projectId: string, taskId: string): UseWorkT
 
 /**
  * Read-only attachments the team has added to a task on one of the client's
- * projects — GET /public/work/projects/:projectId/tasks/:taskId/attachments.
+ * projects: GET /public/work/projects/:projectId/tasks/:taskId/attachments.
  * Tier-1 primitive: returns clean data, renders nothing.
  */
 export function useWorkTaskAttachments(projectId: string, taskId: string): UseQueryResult<WorkTaskAttachment[]> {
@@ -279,7 +301,7 @@ export function useWorkTaskAttachments(projectId: string, taskId: string): UseQu
 // ── Authed client's invoices for a project ───────────────────────────────────
 
 /**
- * The client's (non-draft) invoices for one of their projects —
+ * The client's (non-draft) invoices for one of their projects:
  * GET /public/work/projects/:id/invoices. Each carries a `payable` flag the
  * portal turns into a Pay button (links to /i/invoice/:id). Tier-1 primitive.
  */
@@ -295,11 +317,104 @@ export function useWorkProjectInvoices(projectId: string): UseQueryResult<WorkPr
   });
 }
 
+// ── Authed client's case-file documents ──────────────────────────────────────
+
+/**
+ * The documents on one of the client's projects that they may see: what the
+ * firm shared with them, and what they uploaded themselves:
+ * GET /public/work/projects/:id/documents. Tier-1 primitive.
+ */
+export function useWorkSharedDocuments(projectId: string): UseQueryResult<WorkSharedDocument[]> {
+  const { client, profileId } = useForge();
+  return useQuery<WorkSharedDocument[]>({
+    queryKey: keys.sharedDocuments(profileId, projectId),
+    queryFn: async () => {
+      const res = await client.get(`/public/work/projects/${projectId}/documents`, { params: { profileId } });
+      return res.data as WorkSharedDocument[];
+    },
+    enabled: !!profileId && !!client && !!projectId,
+  });
+}
+
+/**
+ * A sixty-second, single-use GET at one shared file's bytes:
+ * GET /public/work/projects/:id/documents/:documentId/content. Meant to be
+ * followed once, by the click that asked for it; never cache or render the URL.
+ */
+export function useWorkOpenSharedDocument(projectId: string) {
+  const { client, profileId } = useForge();
+  return useMutation<{ url: string }, unknown, string>({
+    mutationFn: async (documentId: string) => {
+      const res = await client.get(`/public/work/projects/${projectId}/documents/${documentId}/content`, {
+        params: { profileId },
+      });
+      return res.data as { url: string };
+    },
+  });
+}
+
+const mediaTypeFor = (file: File): "image" | "video" | "audio" | "document" | "other" => {
+  const mime = file.type || "";
+  if (mime.startsWith("image/")) return "image";
+  if (mime.startsWith("video/")) return "video";
+  if (mime.startsWith("audio/")) return "audio";
+  if (mime.startsWith("text/") || mime.includes("pdf") || mime.includes("word") || mime.includes("document")) {
+    return "document";
+  }
+  return "other";
+};
+
+/**
+ * Put a file into the client's matter, in three steps that must stay in this
+ * order:
+ *
+ *   1. sign a PUT into the firm's PRIVATE bucket
+ *      (POST /public/work/projects/:id/documents/upload-url);
+ *   2. send the bytes straight to object storage, with the Content-Type the
+ *      server SIGNED (derived from the extension allowlist, not the browser);
+ *   3. register the document (POST /public/work/projects/:id/documents), which
+ *      writes the row, shares it back to the client and queues extraction.
+ *
+ * A failure at any step is a failure of the whole upload. On success the
+ * shared-documents list is refetched so the new file appears at once.
+ */
+export function useUploadWorkDocument(projectId: string) {
+  const { client, profileId } = useForge();
+  const queryClient = useQueryClient();
+  return useMutation<WorkSharedDocument, unknown, { file: File; title?: string }>({
+    mutationFn: async ({ file, title }) => {
+      const { data: signed } = await client.post<{
+        presignedUrl: string;
+        key: string;
+        requiredHeaders?: Record<string, string>;
+      }>(`/public/work/projects/${projectId}/documents/upload-url`, { fileName: file.name }, { params: { profileId } });
+      await axios.put(signed.presignedUrl, file, {
+        headers: signed.requiredHeaders ?? { "Content-Type": file.type || "application/octet-stream" },
+      });
+      const { data } = await client.post(
+        `/public/work/projects/${projectId}/documents`,
+        {
+          storageKey: signed.key,
+          fileName: file.name,
+          fileSize: file.size,
+          mediaType: mediaTypeFor(file),
+          ...(title ? { title } : {}),
+        },
+        { params: { profileId } },
+      );
+      return data as WorkSharedDocument;
+    },
+    onSuccess: () => {
+      void queryClient.invalidateQueries({ queryKey: keys.sharedDocuments(profileId, projectId) });
+    },
+  });
+}
+
 // ── Client invite accept (public, no auth) ───────────────────────────────────
 
 /**
  * Fetch the branded context for an invite link (GET /public/work/invite).
- * Public — no bearer token needed; the link's token IS the credential.
+ * Public: no bearer token needed; the link's token IS the credential.
  * `null`/errored when the token or project is missing/invalid/expired.
  */
 export function useWorkInvite(
@@ -321,7 +436,7 @@ export function useWorkInvite(
 /**
  * Accept an invite (POST /public/work/invite/accept): set a password and
  * receive a fresh portal session token. The caller persists the token +
- * navigates. Public — no bearer token needed.
+ * navigates. Public: no bearer token needed.
  */
 export function useAcceptWorkInvite() {
   const { client } = useForge();

package/src/ui/media/_tests/CallStage.spec.tsx

@@ -73,6 +73,7 @@ const fakeTransport = (): MediaTransport => ({
       id: `p-local-${produced.length}`,
       kind: "audio",
       closed: false,
+      replaceTrack: vi.fn(async () => undefined),
       pause: vi.fn(),
       resume: vi.fn(),
       close: vi.fn(),