restream-sdk 0.8.0 → 0.9.0

package/README.md

@@ -33,6 +33,8 @@ Your existing live stream  ──►  Twitch
 - [The `userId` contract & persistence](#the-userid-contract--persistence)
 - [Connecting accounts](#connecting-accounts)
 - [Going live](#going-live)
+- [Screen share & live layout](#screen-share--live-layout)
+- [Collaboration (split-screen)](#collaboration-split-screen)
 - [Live chat & viewers](#live-chat--viewers)
 - [Banners / overlays](#banners--overlays)
 - [Auth modes: publishable key vs. token](#auth-modes-publishable-key-vs-token)
@@ -72,6 +74,13 @@ To go from zero to live you provide exactly **four** things. Everything else is
 You do **not** register OAuth apps, host OAuth callbacks, configure platform
 webhooks, or handle any platform tokens. That's all server-side.
 
+> **The golden rule: keep ONE publisher session for the whole stream.** Publish the
+> camera once and reuse that `publisherSessionId`. **Never re-publish (a new session)
+> or call `goLive()` again** on reconnect, screen toggle, or collaborator change — those
+> are *live* changes: use `setStreamState()`, `startScreenShare()`, and `acceptCollab()`.
+> `goLive()` **throws if a stream is already live**; call `stopLive()` to cleanly end one
+> before starting another.
+
 ---
 
 ## What you get from your operator
@@ -301,9 +310,14 @@ await stopLive();
 
 - **One encode → many destinations.** Restreaming to 2 platforms or 5 costs the
   same on the source; it's a single encode fanned out.
-- **One live stream per streamer.** Calling `goLive()` again for the same `userId`
-  **supersedes** the previous job (the new one takes over). This prevents duplicate
-  streams if a streamer double-clicks or reloads mid-stream.
+- **One live stream per streamer.** `goLive()` **throws** if a job is already live for
+  this streamer — guarding against accidental double-clicks / re-go-lives (the #1 cause
+  of duplicate + stale jobs). Call `stopLive()` first to intentionally restart. Screen /
+  collab / layout are *live* changes — use `setStreamState()`, `startScreenShare()`,
+  `acceptCollab()`, never a second `goLive()`.
+- **`participantOnly: true`** goes live as a compositing-only participant — a collab
+  guest with **no** socials: the job runs (pullable into a host's composite) but fans
+  out nowhere. Pass no `destinations`.
 - **Watch links.** Once broadcasts are created, `job.broadcasts` carries
   `{ platform, watchUrl }` for each destination — handy for "Watch on Twitch ↗".
 - **`arm({ destinations })`** pre-selects destinations so you can fire `goLive`
@@ -312,6 +326,62 @@ await stopLive();
 
 ---
 
+## Screen share & live layout
+
+Screen share is a **separate layer** on your existing stream — never a re-publish or a new `goLive`:
+
+```js
+await startScreenShare();   // publishes the screen session + composites it (solo → screen_camera, collab → collab_screen)
+await stopScreenShare();    // reverts the layout
+```
+
+Push presence/layout live (debounced, best-effort) with `setStreamState`:
+
+```js
+setStreamState({ screenShare: true, camera: true, collab: false,
+                 cameraPosition: "bottom-right", cameraSize: "small" });
+```
+
+---
+
+## Collaboration (split-screen)
+
+Two creators appear side-by-side. Your operator picks the model per client:
+
+**Per-creator (default)** — each creator keeps their **own** live stream; the composite is fanned to **both** creators' own socials:
+
+```js
+// A (host, already live) invites B
+await requestCollab({ collaboratorUserId, publisherSessionId, destinations: ["twitch", "kick"] });
+// B (already live) accepts with their live session
+await acceptCollab(inviteId, { publisherSessionId });
+```
+
+When a collaborator leaves or drops, each still-live creator **automatically reverts to solo** — no stream stops. Send `setStreamState({ collab: false })` for an immediate clean transition.
+
+**Merged (host + challenger)** — only the **host** creates the stream; the challenger joins as a **feed**, with **no job of their own**:
+
+```js
+// Challenger: publish a camera, then join — NO goLive:
+await acceptCollab(inviteId, { publisherSessionId });   // participantOnly guest
+```
+
+- A **new** challenger calling `acceptCollab` while the host is live **swaps** the current one out — **live**, on the host's same session (the host never re-publishes).
+- Live swap is **feed-only**: a swapped-in challenger must have no own socials. An audience-carrying swap is refused — end the collab and start fresh.
+
+**Realtime** — open the collab stream to react to invites/starts/ends live:
+
+```js
+studio.on("collab-composite",  (e) => enterCollabUI(e.job));  // you're in the composite
+studio.on("collab-reassigned", (e) => followJob(e.job));      // your job changed (reverted to solo / swapped out)
+studio.on("collab-ended",      ()  => exitCollabUI());
+await startCollabRealtime();
+```
+
+The SDK **auto-adopts** the new `job.id` on `collab-composite` / `collab-reassigned`, so your `job` state follows the right stream automatically.
+
+---
+
 ## Live chat & viewers
 
 ```js
@@ -426,6 +496,13 @@ defaults to `15000`. On mount it auto-loads connections; `job.status` is polled
 | `refreshJob()` | `Promise<Job>` | re-fetch job status |
 | `sendChat(message, platforms?)` | `Promise` | outbound chat fan-out |
 | `updateOverlay(opts)` | `Promise` | live banner update |
+| `setStreamState(patch)` | — | push live presence/layout (screen/camera/collab, position/size) |
+| `startScreenShare()` / `stopScreenShare()` | `Promise` | screen as a live layer (no re-publish) |
+| `requestCollab(opts)` / `acceptCollab(id, opts)` | `Promise` | invite / join a collab — see [Collaboration](#collaboration-split-screen) |
+| `declineCollab(id)` / `revokeCollab(id)` / `endCollab(id?)` | `Promise` | decline / cancel / end a collab |
+| `setCollabRestream(id, on)` | `Promise` | toggle a guest's own-socials fan-out |
+| `listCollabInvites()` · `collabInvites` | `Promise` · state | sent + received invites |
+| `startCollabRealtime()` / `stopCollabRealtime()` | `Promise` | collab event stream (SSE) |
 | `studio` | `RestreamStudio` | the underlying controller |
 
 ### Convenience hooks
@@ -483,6 +560,12 @@ interface Viewers {
 }
 ```
 
+**Events** — subscribe with `studio.on(type, cb)` (the hook subscribes for you):
+`connections` · `job` · `viewers` · `comment` · `comments` · `error` · `state` ·
+`screenshare` · and collab: `collab-invite` · `collab-accepted` · `collab-declined` ·
+`collab-revoked` · `collab-ended` · `collab-expired` · `collab-composite` ·
+**`collab-reassigned`** (your job id changed — the SDK adopts it) · `collab-snapshot`.
+
 ---
 
 ## Scopes
@@ -521,8 +604,9 @@ A `403 "Missing required scope"` means your key needs that scope added.
   catch (e) { if (e.status === 403) showUpgrade(); else toast(e.message); }
   ```
 - Common statuses: `401` (bad/expired credential — token mode re-mints automatically),
-  `403` (origin not allowed, or missing scope), `409`/supersede (a newer stream took
-  over), `0` (network/timeout).
+  `403` (origin not allowed, or missing scope), `409` (a stream is already live for this
+  streamer, or a duplicate collab), `0` (network/timeout). Note: `goLive()` also **throws
+  client-side** if a job is already live — call `stopLive()` first.
 - Realtime is resilient: transient SSE drops reconnect automatically and chat
   history de-dupes on replay; job-status polling retries on transient failures.
 
@@ -538,7 +622,7 @@ A `403 "Missing required scope"` means your key needs that scope added.
 | Connections empty after refresh | You passed a **different `userId`** — it must be stable per streamer. |
 | Job goes `running` but nothing on the platforms | The `publisherSessionId` must be a **live** session actively sending media when you `goLive()`. |
 | Worker seems to wait / no audio | Your session has no audio track — pass `trackNames: ["video"]`. |
-| Starting a 2nd stream stops the first | Expected — **one live stream per streamer**; a new `goLive` supersedes the old. |
+| `goLive()` throws "a stream is already live" | Expected (0.7.0+) — **one live stream per streamer**. Call `stopLive()` first; use `setStreamState()` / `startScreenShare()` / `acceptCollab()` for live changes (don't re-`goLive`). |
 | `Missing required scope` (403) | Key needs that scope (`connect` / `restream` / `read` / `chat:write`). |
 
 ---

package/package.json

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

@@ -102,6 +102,98 @@ export class RestreamStudio extends EventTarget {
     return { Authorization: `Bearer ${await this._getToken()}` };
   }
 
+  /**
+   * Wait until a published Cloudflare Realtime session is GENUINELY transmitting media — not merely
+   * ICE/SDP-connected. This closes the "the worker pulled before the publisher was actually sending"
+   * race: a CF `tracks/new` success returns the moment the SDP answer is accepted, but Cloudflare
+   * only registers a "live" remote peer once the publisher's RTCPeerConnection hits connectionState
+   * 'connected' AND every active sender starts emitting RTP packets (outbound-rtp.packetsSent > 0).
+   *
+   * Call this RIGHT AFTER your tracks/new / publish helper resolves and BEFORE you fan-out (goLive,
+   * requestCollab, acceptCollab, setMode). The restream worker pulls immediately at that point; if
+   * you signal before media is flowing, the pull fails transitently ("Track not found on remote
+   * peer") and the composite can drop.
+   *
+   * Resolves when BOTH are true (or rejects on timeout). Pure local getStats polling — no server
+   * round-trip. Picks senders dynamically so a replaceTrack mid-wait is tolerated.
+   *
+   * @param {RTCPeerConnection} pc    the publisher PeerConnection (from your publish helper)
+   * @param {object} [opts]
+   * @param {number} [opts.timeoutMs=8000]   hard cap; rejects with a clear error if media never flows
+   * @param {number} [opts.minPackets=1]     per-sender packet count considered "transmitting"
+   * @param {number} [opts.pollMs=250]       getStats interval
+   * @returns {Promise<{ok:true, senders:number}>}
+   * @throws {Error} on timeout or if the connection dies during the wait
+   */
+  async waitUntilPublishing(pc, { timeoutMs = 8000, minPackets = 1, pollMs = 250 } = {}) {
+    if (!pc || typeof pc.getStats !== "function") {
+      throw new Error("waitUntilPublishing: an RTCPeerConnection is required");
+    }
+    const deadline = Date.now() + Math.max(500, timeoutMs);
+    const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+    // A dead/failing connection is a terminal failure — surface it instead of waiting out the timer.
+    let dead = false;
+    const onFail = () => { dead = true; };
+    const wrap = () => {
+      try { pc.addEventListener("connectionstatechange", onFail); } catch {}
+    };
+    const unwrap = () => {
+      try { pc.removeEventListener("connectionstatechange", onFail); } catch {}
+    };
+    wrap();
+
+    try {
+      while (Date.now() < deadline) {
+        if (dead || pc.connectionState === "failed" || pc.connectionState === "closed") {
+          throw new Error(`waitUntilPublishing: connection ${pc.connectionState} before media flowed`);
+        }
+        const connected = pc.connectionState === "connected" || pc.iceConnectionState === "connected";
+        let transmitting = connected;
+        let senderCount = 0;
+        if (connected) {
+          try {
+            const stats = await pc.getStats();
+            // Map each sender to whether its outbound-rtp shows real packets. Every sender must pass,
+            // so a single stalled track holds the resolve (that's the whole point — the worker pulls
+            // every track and any one missing makes CF reject the pull).
+            const senders = pc.getSenders ? pc.getSenders() : [];
+            for (const s of senders) {
+              if (!s.track) continue; // a sender without a live track (e.g. stopped) doesn't count
+              senderCount++;
+              let trackReport = null;
+              stats.forEach((report) => {
+                if (report.type === "outbound-rtp" && report.track === s.track.id && !report.isReceiving) {
+                  trackReport = report;
+                }
+              });
+              // Some UA variants expose the sender via report trackIdentifier / mediaSource — cover both.
+              if (!trackReport) {
+                stats.forEach((report) => {
+                  if (report.type === "outbound-rtp" && (report.trackIdentifier === s.track.id || (report.id && s.track.id && report.track === s.track.id))) {
+                    trackReport = report;
+                  }
+                });
+              }
+              if (!trackReport || !Number.isFinite(trackReport.packetsSent) || trackReport.packetsSent < minPackets) {
+                transmitting = false;
+                break;
+              }
+            }
+            if (senderCount === 0) transmitting = false; // nothing to transmit yet
+          } catch {
+            transmitting = false; // transient getStats failure — keep polling
+          }
+        }
+        if (transmitting && senderCount > 0) return { ok: true, senders: senderCount };
+        await sleep(pollMs);
+      }
+      throw new Error(`waitUntilPublishing: timed out after ${timeoutMs}ms (connectionState=${pc.connectionState}) — media never flowed`);
+    } finally {
+      unwrap();
+    }
+  }
+
   async _authQuery() {
     if (this.publishableKey) {
       const q = { pk: this.publishableKey };
@@ -527,6 +619,41 @@ export class RestreamStudio extends EventTarget {
     return this._streamState;
   }
 
+  /**
+   * Switch a LIVE job's MODE (the new single-job model: one job holds the host's stream; modes
+   * change which feeds are composited + their positions — solo / host_screen / 1v1 / 1v1_screen / …).
+   * The ingest + RTMP fan-out NEVER restart on a mode change (immutable-job invariant); only the
+   * compositor layers/positions change. A guest may arrive later or a different guest swap in
+   * without a new job — the compositor is "always ready".
+   *
+   * On scene_engine='legacy' (default) this drives a brief restartWithFeeds internally; on
+   * 'live_v2' it is a true zero-restart sink mutation. The SDK call is identical either way —
+   * Stage 2 swaps the engine under you with no client change.
+   *
+   * @param {string} mode  a preset key (solo / host_screen / 1v1 / 1v1_screen / solo_fullscreen_cam)
+   *                       or a per-creator override key configured in the admin
+   * @returns {Promise<{ok:boolean, mode:string, applied:boolean, engine:string}>}
+   */
+  async setMode(mode) {
+    if (!mode) throw new Error("mode is required (e.g. 'solo', '1v1', '1v1_screen')");
+    const jobId = this.job?.id;
+    if (!jobId) throw new Error("Not live — go live before switching modes");
+    const r = await this._req("POST", `/api/v1/jobs/${jobId}/mode`, this._withUser({ mode }));
+    if (r?.ok) this._emit("mode", { mode, engine: r.engine });
+    return r;
+  }
+
+  /**
+   * The job's CURRENTLY-active mode (resolved from its live state against the client's presets +
+   * per-creator overrides). Returns { mode, template, layoutState }. Read-only.
+   */
+  async getMode() {
+    const jobId = this.job?.id;
+    if (!jobId) throw new Error("Not live");
+    const r = await this._req("GET", `/api/v1/jobs/${jobId}/mode`, this._withUser({}));
+    return r;
+  }
+
   /** Last presence/layout state set via setStreamState() (local view). */
   get streamState() { return this._streamState; }
 
@@ -720,20 +847,27 @@ export class RestreamStudio extends EventTarget {
    * starts only when they accept. Pass your own publisherSessionId + destinations so
    * the server can begin the merged broadcast on accept (or rely on your active job).
    *
-   * collaboratorRestreamOn defaults to TRUE: the invited creator's connected social
-   * accounts MUST receive the side-by-side composite unless they explicitly opt out
-   * (pass `collaboratorRestreamOn: false`). This matches the server product intent in
-   * routes/collab.js and CollabService.createInvite. The bug: defaulting the SDK to
-   * `false` here sent `false` in the request body, which the server honored, so the
-   * collaborator's broadcasts/fan-out were silently skipped and the collab frame never
-   * appeared on the collaborator's own social accounts.
+   * collaboratorRestreamOn controls whether the invited creator gets THEIR OWN job +
+   * fan-out (their own socials broadcast the composite), and is RESOLVED SERVER-SIDE
+   * by default so a single SDK works for both product models:
+   *   - host/challenger products (Aurealone): only the HOST restreams. The guest is a
+   *     feed-only participant inside the host's composite and creates NO job. The
+   *     client's per-server default (collab_guest_restream=false) applies.
+   *   - symmetric products (fomo.gg): both creators restream their own composite.
+   *     The client's per-server default is true.
+   * Pass `collaboratorRestreamOn: true|false` ONLY to override the per-client default
+   * for this specific invite (rare). Omit it (do NOT default it client-side) so the
+   * server's per-client rule is the single source of truth.
    * @param {object} opts { collaboratorUserId, collaboratorRestreamOn?, publisherSessionId?, destinations?, metadata? }
    */
-  async requestCollab({ collaboratorUserId, collaboratorRestreamOn = true, publisherSessionId, destinations, metadata } = {}) {
+  async requestCollab({ collaboratorUserId, collaboratorRestreamOn, publisherSessionId, destinations, metadata } = {}) {
     if (!collaboratorUserId) throw new Error("collaboratorUserId is required");
-    const invite = await this._req("POST", "/api/v1/collab/request", this._withUser({
-      collaboratorUserId, collaboratorRestreamOn, publisherSessionId, destinations, metadata,
-    }));
+    const body = this._withUser({ collaboratorUserId, publisherSessionId, destinations, metadata });
+    // Only send the flag if the caller EXPLICITLY set it — otherwise omit so the server resolves
+    // the per-client default (host-only vs symmetric). Previously this defaulted to TRUE client-side
+    // and was sent on every call, forcing a guest fan-out for host-only products → duplicate jobs.
+    if (collaboratorRestreamOn === true || collaboratorRestreamOn === false) body.collaboratorRestreamOn = collaboratorRestreamOn;
+    const invite = await this._req("POST", "/api/v1/collab/request", body);
     this._emit("collab-invite", { type: "collab-invite", invite, mine: true });
     return invite;
   }

package/types/index.d.ts

@@ -278,6 +278,14 @@ export class RestreamStudio extends EventTarget {
   stopScreenShare(): Promise<void>;
   /** Cloudflare session id of the live screen-share publish, or null. */
   readonly screenSessionId: string | null;
+  /** Wait until a published Cloudflare Realtime session is genuinely transmitting media
+   *  (connectionState 'connected' AND every active sender's outbound-rtp.packetsSent > minPackets),
+   *  not merely ICE/SDP-connected. Call this RIGHT AFTER your tracks/new/publish helper resolves
+   *  and BEFORE you signal fan-out (goLive / requestCollab / acceptCollab / setMode) so the
+   *  restream-side pull never races the publisher's first RTP packets ('Track not found on
+   *  remote peer'). Pure local getStats polling; no server round-trip. Rejects on timeout /
+   *  connection failure. New in 0.9.0. */
+  waitUntilPublishing(pc: RTCPeerConnection, opts?: { timeoutMs?: number; minPackets?: number; pollMs?: number }): Promise<{ ok: true; senders: number }>;
   startRealtime(jobId: string): Promise<void>;
   stopRealtime(): void;
   // collaborative split-screen