restream-sdk 0.4.2 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "restream-sdk",
-  "version": "0.4.2",
+  "version": "0.6.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

@@ -52,6 +52,13 @@ export class RestreamStudio extends EventTarget {
     this._pendingState = null;
     this._stateTimer = null;
 
+    // Screen-share: the SDK captures the screen (getDisplayMedia) and publishes it as its OWN
+    // Cloudflare Realtime session (separate from the camera), so our backend composites it as a
+    // distinct LAYER (screen + camera PiP) server-side via the template system. Restream-only —
+    // fomo.gg's own player never renders it. Null until startScreenShare(); holds { pc, sessionId,
+    // trackName, track, stream } while active.
+    this._screen = null;
+
     this._token = null;
     this._tokenExp = 0;
     this._es = null;
@@ -393,7 +400,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 } = {}) {
+  async goLive({ publisherSessionId, destinations, overlay, recording, trackNames, restreamChannels, streamMeta, destinationMeta, streamingProvider, layout, screenSessionId, participantOnly } = {}) {
     if (!publisherSessionId) throw new Error("publisherSessionId is required (from your existing stream session)");
     const body = {
       publisherSessionId,
@@ -401,6 +408,10 @@ export class RestreamStudio extends EventTarget {
       overlay,
       recording,
     };
+    // Compositing-only participant (e.g. a collab challenger with no socials): go live with NO
+    // destinations. The job reaches 'running' — discoverable as an activeSoloJob so a per-creator
+    // collab can composite its camera — but fans out nowhere. Only forwarded when true.
+    if (participantOnly) body.participantOnly = true;
     if (trackNames && trackNames.length) body.trackNames = trackNames;
     // Per-platform selection for the "restream" fan-out bridge (channel ids or platform names).
     if (restreamChannels && restreamChannels.length) body.restreamChannels = restreamChannels;
@@ -421,6 +432,14 @@ export class RestreamStudio extends EventTarget {
     if (streamingProvider && typeof streamingProvider === "object" && Object.keys(streamingProvider).length) {
       body.streamingProvider = streamingProvider;
     }
+    // Screen-share as a separate LAYER: pass the screen-publish session + its track name so the
+    // backend pulls the RIGHT track (the SDK publishes it as "screen", not "video") and composites
+    // screen + camera per the template. Defaults to the SDK's active screen share.
+    const screenId = screenSessionId || this.screenSessionId;
+    if (screenId) {
+      body.screenSessionId = screenId;
+      body.screenTrackName = this._screen?.trackName || "screen";
+    }
     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;
@@ -502,6 +521,93 @@ export class RestreamStudio extends EventTarget {
   /** Last presence/layout state set via setStreamState() (local view). */
   get streamState() { return this._streamState; }
 
+  /** The Cloudflare session id of the live screen-share publish (or null). Pass this to
+   *  goLive({ screenSessionId }) so the backend pulls the screen as a separate layer. */
+  get screenSessionId() { return this._screen?.sessionId || null; }
+
+  /**
+   * Start screen sharing: capture the screen and publish it as its OWN Cloudflare Realtime
+   * session (a separate LAYER from the camera). Returns { sessionId, trackName }. Also calls
+   * setStreamState({ screenShare: true, screenSessionId, screenTrackName }) for you, so the backend
+   * composites screen + camera server-side (solo → screen_camera, collab → collab_screen) — at
+   * 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 }
+   * @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");
+    }
+    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"); }
+
+    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" });
+
+      // 3) New Cloudflare Realtime session (brokered by our backend — CF creds stay server-side).
+      const session = await this._req("POST", "/api/streams/sessions", {});
+      const sessionId = session.sessionId;
+      if (!sessionId) throw new Error("no sessionId from /streams/sessions");
+
+      // 4) Offer, wait for ICE gathering (CF wants the full offer), then push the LOCAL track.
+      await pc.setLocalDescription(await pc.createOffer());
+      await this._waitIceComplete(pc);
+      const res = await this._req("POST", `/api/streams/sessions/${sessionId}/tracks/new`, {
+        sessionDescription: { type: "offer", sdp: pc.localDescription.sdp },
+        tracks: [{ location: "local", mid: transceiver.mid, trackName }],
+      });
+      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(() => {}); });
+
+      this._screen = { pc, track, stream, sessionId, trackName };
+      // 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 */ }
+      throw err;
+    }
+  }
+
+  /** Stop screen sharing: close the Cloudflare track + tear down the peer connection. */
+  async stopScreenShare() {
+    const s = this._screen;
+    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 */ }
+    try { s.pc.close(); } catch { /* ignore */ }
+    // Clear the screen session so the backend reverts the layout (screen_camera → solo,
+    // collab_screen → sidebyside).
+    this.setStreamState({ screenShare: false, screenSessionId: null, screenTrackName: null });
+    this._emit("screenshare", { active: false });
+  }
+
+  // Resolve once ICE gathering completes (or after a short timeout) so the offer carries candidates.
+  _waitIceComplete(pc, timeoutMs = 3000) {
+    if (pc.iceGatheringState === "complete") return Promise.resolve();
+    return new Promise((resolve) => {
+      const done = () => { pc.removeEventListener("icegatheringstatechange", check); clearTimeout(t); resolve(); };
+      const check = () => { if (pc.iceGatheringState === "complete") done(); };
+      const t = setTimeout(done, timeoutMs);
+      pc.addEventListener("icegatheringstatechange", check);
+    });
+  }
+
   // ---- realtime (chat SSE + job-status/viewer polling) ----
   async startRealtime(jobId) {
     this.stopRealtime();

package/src/react.js

@@ -58,6 +58,8 @@ export function useRestream(opts) {
     sendChat: useCallback((m, p) => studio.sendChat(m, p), [studio]),
     updateOverlay: useCallback((o) => studio.updateOverlay(o), [studio]),
     setStreamState: useCallback((s) => studio.setStreamState(s), [studio]),
+    startScreenShare: useCallback((o) => studio.startScreenShare(o), [studio]),
+    stopScreenShare: useCallback(() => studio.stopScreenShare(), [studio]),
     // collaborative split-screen
     requestCollab: useCallback((o) => studio.requestCollab(o), [studio]),
     acceptCollab: useCallback((id, o) => studio.acceptCollab(id, o), [studio]),

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;
+  /** 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;
+  /**
+   * Compositing-only participant: go live with NO destinations. The job reaches `running` (so it's
+   * discoverable as an active solo job for a per-creator collab to composite its camera) but fans
+   * out nowhere. For a collab participant with no socials of their own (e.g. a challenger).
+   */
+  participantOnly?: boolean;
 }
 
 export interface StreamMeta {
@@ -131,6 +140,13 @@ export interface StreamState {
   collab?: boolean;
   cameraPosition?: CameraPosition | null;
   cameraSize?: CameraSize | null;
+  /**
+   * Cloudflare session/track the screen is published on. Set automatically by startScreenShare()
+   * so the backend can pull the screen as a live layer and transition the layout server-side
+   * (solo → screen_camera, collab → collab_screen). Cleared by stopScreenShare().
+   */
+  screenSessionId?: string | null;
+  screenTrackName?: string | null;
   /** Server-stamped on each update (read-only on the way back). */
   updatedAt?: string;
 }
@@ -213,6 +229,7 @@ export class RestreamStudio extends EventTarget {
   on(type: "comments", cb: (c: Comment[]) => void): () => void;
   on(type: "error", cb: (e: Error) => void): () => void;
   on(type: "state", cb: (s: StreamState) => void): () => void;
+  on(type: "screenshare", cb: (e: { active: boolean; sessionId?: string; trackName?: string }) => void): () => void;
   on(type: "collab" | "collab-invite" | "collab-accepted" | "collab-declined" | "collab-revoked" | "collab-ended" | "collab-expired" | "collab-composite" | "collab-snapshot", cb: (e: CollabEvent) => void): () => void;
   listConnections(): Promise<Connection[]>;
   listOAuthPlatforms(): Promise<OAuthPlatformsResponse>;
@@ -253,6 +270,14 @@ export class RestreamStudio extends EventTarget {
   setStreamState(patch: StreamState): StreamState;
   /** Last presence/layout state set locally. */
   readonly streamState: StreamState;
+  /** 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 }>;
+  /** Stop screen sharing (close the Cloudflare track + peer connection). */
+  stopScreenShare(): Promise<void>;
+  /** Cloudflare session id of the live screen-share publish, or null. */
+  readonly screenSessionId: string | null;
   startRealtime(jobId: string): Promise<void>;
   stopRealtime(): void;
   // collaborative split-screen
@@ -302,6 +327,8 @@ 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 }>;
+  stopScreenShare(): Promise<void>;
   requestCollab(opts: RequestCollabParams): Promise<CollabInvite>;
   acceptCollab(inviteId: string, opts: AcceptCollabParams): Promise<{ invite: CollabInvite; job: Job }>;
   declineCollab(inviteId: string): Promise<CollabInvite>;