restream-sdk 0.5.0 → 0.7.0

package/package.json

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

@@ -400,14 +400,27 @@ 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 } = {}) {
+  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)");
+    // 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
+    // cause of duplicate + stale jobs — those are LIVE changes, so use setStreamState() /
+    // startScreenShare() / acceptCollab(), NOT a new goLive. Keep ONE publisher session for the whole
+    // stream; call stopLive() first to intentionally start over. Only live states block, so after the
+    // job stops (status becomes stopping/stopped/failed/ended) a genuine restart works normally.
+    if (this.job?.id && ["queued", "starting", "connecting", "running"].includes(this.job.status)) {
+      throw new Error(`goLive blocked: a stream is already live (job ${this.job.id}, status ${this.job.status}). Use setStreamState()/startScreenShare()/acceptCollab() for live changes, and call stopLive() before starting a new stream — do not re-publish or re-goLive on reconnect/screen/collab changes.`);
+    }
     const body = {
       publisherSessionId,
       destinations: destinations || this._armed?.destinations || [],
       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;
@@ -523,10 +536,11 @@ export class RestreamStudio extends EventTarget {
 
   /**
    * Start screen sharing: capture the screen and publish it as its OWN Cloudflare Realtime
-   * session (a separate LAYER from the camera). Returns { sessionId, trackName } — pass the
-   * sessionId to goLive({ screenSessionId }) (or updateScreenLayer() while live) so the backend
-   * composites screen + camera server-side via the template. Restream-only; not shown in the
-   * client's own player. Must be called from a user gesture (getDisplayMedia requires it).
+   * 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}>}

package/types/index.d.ts

@@ -107,6 +107,12 @@ export interface GoLiveParams {
   /** 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 {