restream-sdk 0.9.0 → 0.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "restream-sdk",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Plug-and-play headless React hooks to add multi-platform restreaming (connect socials, go live, live chat + viewers, collaborative split-screen) with zero client backend.",
   "type": "module",
   "main": "src/index.js",

package/src/core.js

@@ -492,7 +492,7 @@ export class RestreamStudio extends EventTarget {
    *                                           Restream channels. Any field omitted falls back to the
    *                                           default pre-set for this creator on the platform.
    */
-  async goLive({ publisherSessionId, destinations, overlay, recording, trackNames, restreamChannels, streamMeta, destinationMeta, streamingProvider, layout, screenSessionId, participantOnly } = {}) {
+  async goLive({ publisherSessionId, destinations, overlay, recording, trackNames, restreamChannels, streamMeta, destinationMeta, streamingProvider, layout, screenSessionId, participantOnly, metadata, preComposited } = {}) {
     if (!publisherSessionId) throw new Error("publisherSessionId is required (from your existing stream session)");
     // Idempotency guard: refuse a second goLive while a job is already live. Re-publishing a fresh
     // session and calling goLive() again on reconnect / screen toggle / collaborator change is the #1
@@ -541,6 +541,13 @@ export class RestreamStudio extends EventTarget {
       body.screenSessionId = screenId;
       body.screenTrackName = this._screen?.trackName || "screen";
     }
+    // Arbitrary job metadata + the pre-composited flag. preComposited:true tells the backend this
+    // publisher session already contains the partner (client-side composite / chart-canvas), so the
+    // per-creator collab reconciler must NOT attach the partner's feed to this job (it would double-
+    // composite + flip to sidebyside). Both forms land at restream_jobs.metadata.preComposited.
+    const meta = { ...(metadata || {}) };
+    if (preComposited) meta.preComposited = true;
+    if (Object.keys(meta).length) body.metadata = meta;
     if (this.publishableKey && this.userId) body.clientUserId = this.userId; // token mode binds server-side
     const job = await this._req("POST", "/api/v1/jobs", body);
     this.job = job;
@@ -669,25 +676,44 @@ export class RestreamStudio extends EventTarget {
    * go-live if called first, or LIVE mid-stream via the layout transition. Restream-only; not shown
    * in the client's own player. Must be called from a user gesture (getDisplayMedia requires it).
    *
-   * @param {object} [opts] { trackName='screen', audio=false }
+   * A CALLER-SUPPLIED track may be passed instead of capturing the OS screen — e.g. a
+   * `canvas.captureStream()` video track that already contains a pre-composited frame (host cam +
+   * guest cam + chart). When `track` is given we skip `getDisplayMedia` entirely (no OS picker, no
+   * permission prompt) and publish that track as the layer. The CALLER owns that track's lifecycle:
+   * we never stop it (on `stopScreenShare` or teardown), so a single continuous canvas track can
+   * survive stop/restart and coin switches with no media blip.
+   *
+   * NOTE on layout: this publishes as the SCREEN layer, so the backend composites `screen_camera`
+   * (screen full-frame + camera PiP). For a PRE-COMPOSITED pass-through feed where you do NOT want a
+   * camera PiP, publish the canvas as your PRIMARY track instead (the backend renders `solo` =
+   * full-frame, no PiP, mic audio) — see the chart-canvas integration guide.
+   *
+   * @param {object} [opts] { trackName='screen', audio=false, track?: MediaStreamTrack }
    * @returns {Promise<{sessionId:string, trackName:string}>}
    */
-  async startScreenShare({ trackName = "screen", audio = false } = {}) {
-    if (typeof navigator === "undefined" || !navigator.mediaDevices?.getDisplayMedia) {
-      throw new Error("Screen sharing is not supported in this environment");
-    }
+  async startScreenShare({ trackName = "screen", audio = false, track = null } = {}) {
     if (this._screen) return { sessionId: this._screen.sessionId, trackName: this._screen.trackName };
 
-    // 1) Capture the screen.
-    const stream = await navigator.mediaDevices.getDisplayMedia({ video: true, audio });
-    const track = stream.getVideoTracks()[0];
-    if (!track) { stream.getTracks().forEach((t) => t.stop()); throw new Error("no screen video track"); }
+    // 1) Obtain the video track: caller-supplied (pre-composited, caller-owned) or captured screen.
+    let stream = null;
+    let videoTrack = track;
+    const callerOwnsTrack = !!track;
+    if (!callerOwnsTrack) {
+      if (typeof navigator === "undefined" || !navigator.mediaDevices?.getDisplayMedia) {
+        throw new Error("Screen sharing is not supported in this environment");
+      }
+      stream = await navigator.mediaDevices.getDisplayMedia({ video: true, audio });
+      videoTrack = stream.getVideoTracks()[0];
+      if (!videoTrack) { stream.getTracks().forEach((t) => t.stop()); throw new Error("no screen video track"); }
+    }
+    if (!videoTrack) throw new Error("startScreenShare: no video track (pass { track } or enable screen capture)");
+    const track_ = videoTrack;
 
     try {
       // 2) ICE servers + peer connection.
       const { iceServers } = await this._req("GET", "/api/streams/turn-credentials");
       const pc = new RTCPeerConnection({ iceServers, bundlePolicy: "max-bundle" });
-      const transceiver = pc.addTransceiver(track, { direction: "sendonly" });
+      const transceiver = pc.addTransceiver(track_, { direction: "sendonly" });
 
       // 3) New Cloudflare Realtime session (brokered by our backend — CF creds stay server-side).
       const session = await this._req("POST", "/api/streams/sessions", {});
@@ -703,17 +729,19 @@ export class RestreamStudio extends EventTarget {
       });
       if (res?.sessionDescription) await pc.setRemoteDescription(new RTCSessionDescription(res.sessionDescription));
 
-      // Stop-sharing from the browser's own UI must tear us down too.
-      track.addEventListener("ended", () => { this.stopScreenShare().catch(() => {}); });
+      // Stop-sharing from the browser's own UI must tear us down too — but ONLY for a screen we
+      // captured. A caller-supplied track's lifecycle belongs to the caller (e.g. a canvas capture
+      // that must outlive stop/restart), so we don't bind its 'ended' to our teardown.
+      if (!callerOwnsTrack) track_.addEventListener("ended", () => { this.stopScreenShare().catch(() => {}); });
 
-      this._screen = { pc, track, stream, sessionId, trackName };
+      this._screen = { pc, track: track_, stream, sessionId, trackName, callerOwnsTrack };
       // Signal the backend WHICH session/track the screen is on so it can pull it as a live layer
       // and transition the layout server-side (solo → screen_camera, collab → collab_screen).
       this.setStreamState({ screenShare: true, screenSessionId: sessionId, screenTrackName: trackName });
       this._emit("screenshare", { active: true, sessionId, trackName });
       return { sessionId, trackName };
     } catch (err) {
-      try { stream.getTracks().forEach((t) => t.stop()); } catch { /* ignore */ }
+      if (stream) { try { stream.getTracks().forEach((t) => t.stop()); } catch { /* ignore */ } }
       throw err;
     }
   }
@@ -724,8 +752,12 @@ export class RestreamStudio extends EventTarget {
     if (!s) return;
     this._screen = null;
     try { await this._req("POST", `/api/streams/sessions/${s.sessionId}/tracks/close`, { tracks: [{ mid: s.pc?.getTransceivers?.()[0]?.mid, trackName: s.trackName }], force: true }); } catch { /* best-effort */ }
-    try { s.track.stop(); } catch { /* ignore */ }
-    try { s.stream.getTracks().forEach((t) => t.stop()); } catch { /* ignore */ }
+    // Only stop tracks WE created (captured screen). A caller-supplied track (e.g. a continuous
+    // canvas capture) is owned by the caller and must keep running across stop/restart + coin switches.
+    if (!s.callerOwnsTrack) {
+      try { s.track.stop(); } catch { /* ignore */ }
+      try { s.stream?.getTracks().forEach((t) => t.stop()); } catch { /* ignore */ }
+    }
     try { s.pc.close(); } catch { /* ignore */ }
     // Clear the screen session so the backend reverts the layout (screen_camera → solo,
     // collab_screen → sidebyside).

package/types/index.d.ts

@@ -104,6 +104,15 @@ export interface GoLiveParams {
   destinationMeta?: DestinationMeta;
   /** Initial presence/layout state for the stream (same shape as setStreamState). */
   layout?: StreamState;
+  /** Arbitrary job metadata (stored on the job row, readable by the backend). */
+  metadata?: Record<string, unknown>;
+  /**
+   * Mark this publisher session as PRE-COMPOSITED: it already contains the partner (host + guest
+   * composited client-side onto one canvas). The backend renders it full-frame (solo) and the
+   * per-creator collab reconciler will NOT attach the partner's feed to this job (which would
+   * double-composite + flip to sidebyside). Folded into metadata.preComposited.
+   */
+  preComposited?: boolean;
   /** Cloudflare session of a screen-share publish (from startScreenShare) to composite as a
    *  separate layer. Defaults to the SDK's active screen share if omitted. */
   screenSessionId?: string;
@@ -273,7 +282,7 @@ export class RestreamStudio extends EventTarget {
   /** Capture the screen and publish it as its OWN Cloudflare session (a separate layer the
    *  backend composites via templates). Pass the returned sessionId to goLive({ screenSessionId }).
    *  Restream-only; must be called from a user gesture. */
-  startScreenShare(opts?: { trackName?: string; audio?: boolean }): Promise<{ sessionId: string; trackName: string }>;
+  startScreenShare(opts?: { trackName?: string; audio?: boolean; track?: MediaStreamTrack }): Promise<{ sessionId: string; trackName: string }>;
   /** Stop screen sharing (close the Cloudflare track + peer connection). */
   stopScreenShare(): Promise<void>;
   /** Cloudflare session id of the live screen-share publish, or null. */
@@ -335,7 +344,7 @@ export interface UseRestream {
   sendChat(message: string, platforms?: Platform[]): Promise<unknown>;
   updateOverlay(opts: OverlayUpdate): Promise<unknown>;
   setStreamState(patch: StreamState): StreamState;
-  startScreenShare(opts?: { trackName?: string; audio?: boolean }): Promise<{ sessionId: string; trackName: string }>;
+  startScreenShare(opts?: { trackName?: string; audio?: boolean; track?: MediaStreamTrack }): Promise<{ sessionId: string; trackName: string }>;
   stopScreenShare(): Promise<void>;
   requestCollab(opts: RequestCollabParams): Promise<CollabInvite>;
   acceptCollab(inviteId: string, opts: AcceptCollabParams): Promise<{ invite: CollabInvite; job: Job }>;