restream-sdk 0.3.0 → 0.4.0

package/package.json

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

@@ -44,6 +44,14 @@ export class RestreamStudio extends EventTarget {
     // connect helpers fall back to the static defaults above while it's null.
     this._routing = null;
 
+    // Real-time presence/layout state ({ screenShare, camera, collab, cameraPosition,
+    // cameraSize }) pushed to the server via setStreamState(). Coalesced (trailing debounce)
+    // so rapid toggles send once. _pendingState holds state set before goLive() (flushed once
+    // the job exists).
+    this._streamState = {};
+    this._pendingState = null;
+    this._stateTimer = null;
+
     this._token = null;
     this._tokenExp = 0;
     this._es = null;
@@ -385,7 +393,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 } = {}) {
+  async goLive({ publisherSessionId, destinations, overlay, recording, trackNames, restreamChannels, streamMeta, destinationMeta, streamingProvider, layout } = {}) {
     if (!publisherSessionId) throw new Error("publisherSessionId is required (from your existing stream session)");
     const body = {
       publisherSessionId,
@@ -418,6 +426,13 @@ export class RestreamStudio extends EventTarget {
     this.job = job;
     this._emit("job", job);
     if (job?.id) this.startRealtime(job.id);
+    // Push the initial presence/layout state (explicit `layout`, or whatever was set via
+    // setStreamState() before we had a job id). Best-effort — never block go-live on it.
+    const initialState = { ...(this._pendingState || {}), ...(layout || {}) };
+    if (job?.id && Object.keys(initialState).length) {
+      this._pendingState = null;
+      this.setStreamState(initialState).catch(() => {});
+    }
     return job;
   }
 
@@ -425,6 +440,7 @@ export class RestreamStudio extends EventTarget {
     if (!this.job?.id) return null;
     const r = await this._req("DELETE", `/api/v1/jobs/${this.job.id}`);
     this.stopRealtime();
+    if (this._stateTimer) { clearTimeout(this._stateTimer); this._stateTimer = null; } // drop any pending state POST
     this.job = { ...this.job, status: "stopping" };
     this._emit("job", this.job);
     return r;
@@ -447,6 +463,40 @@ export class RestreamStudio extends EventTarget {
     return this._req("PATCH", `/api/v1/jobs/${this.job.id}/overlay`, opts);
   }
 
+  /**
+   * Push the creator's real-time presence/layout state to the server. Call on EVERY change
+   * (screen-share toggled, camera on/off, collab on/off, camera moved/resized) so the server
+   * can swap banner templates per state and keep assets clear of the camera. Partial patches
+   * merge; the full merged state is sent (trailing-debounced ~150ms so rapid toggles send once).
+   *
+   * @param {object} patch
+   * @param {boolean} [patch.screenShare]
+   * @param {boolean} [patch.camera]
+   * @param {boolean} [patch.collab]
+   * @param {"top-left"|"top-right"|"bottom-left"|"bottom-right"|null} [patch.cameraPosition]
+   * @param {"small"|"medium"|"large"|number|null} [patch.cameraSize]  enum or % (1-100)
+   * @returns {object} the merged local state (the network send is debounced/best-effort)
+   */
+  setStreamState(patch = {}) {
+    this._streamState = { ...this._streamState, ...patch };
+    this._emit("state", this._streamState);
+    if (!this.job?.id) {
+      // Not live yet — remember it and flush when goLive() creates the job.
+      this._pendingState = { ...this._streamState };
+      return this._streamState;
+    }
+    const jobId = this.job.id;
+    if (this._stateTimer) clearTimeout(this._stateTimer);
+    this._stateTimer = setTimeout(() => {
+      this._stateTimer = null;
+      this._req("POST", `/api/v1/jobs/${jobId}/state`, this._streamState).catch((e) => this._emit("error", e));
+    }, 150);
+    return this._streamState;
+  }
+
+  /** Last presence/layout state set via setStreamState() (local view). */
+  get streamState() { return this._streamState; }
+
   // ---- realtime (chat SSE + job-status/viewer polling) ----
   async startRealtime(jobId) {
     this.stopRealtime();

package/src/react.js

@@ -57,6 +57,7 @@ export function useRestream(opts) {
     refreshJob: useCallback(() => studio.refreshJob(), [studio]),
     sendChat: useCallback((m, p) => studio.sendChat(m, p), [studio]),
     updateOverlay: useCallback((o) => studio.updateOverlay(o), [studio]),
+    setStreamState: useCallback((s) => studio.setStreamState(s), [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

@@ -102,6 +102,8 @@ export interface GoLiveParams {
    * default → the creator's pre-set global default → the platform's existing value.
    */
   destinationMeta?: DestinationMeta;
+  /** Initial presence/layout state for the stream (same shape as setStreamState). */
+  layout?: StreamState;
 }
 
 export interface StreamMeta {
@@ -113,6 +115,26 @@ export interface StreamMeta {
 /** Per-platform stream metadata overrides, keyed by platform name. */
 export type DestinationMeta = Partial<Record<Platform, StreamMeta>> & Record<string, StreamMeta>;
 
+/** Where the creator's frontend placed the camera while screen-sharing (template hint). */
+export type CameraPosition = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+/** Camera size as an enum or a percentage of the frame (1-100). */
+export type CameraSize = "small" | "medium" | "large" | number;
+
+/**
+ * Real-time presence/layout state pushed via setStreamState(). All fields optional —
+ * partial patches merge server-side. Camera position/size only matter while screen-sharing
+ * and are template metadata (they don't move media).
+ */
+export interface StreamState {
+  screenShare?: boolean;
+  camera?: boolean;
+  collab?: boolean;
+  cameraPosition?: CameraPosition | null;
+  cameraSize?: CameraSize | null;
+  /** Server-stamped on each update (read-only on the way back). */
+  updatedAt?: string;
+}
+
 export interface OverlayUpdate {
   topBanner?: string;
   bottomBanner?: string;
@@ -190,6 +212,7 @@ export class RestreamStudio extends EventTarget {
   on(type: "comment", cb: (c: Comment) => void): () => void;
   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: "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>;
@@ -225,6 +248,11 @@ export class RestreamStudio extends EventTarget {
   refreshJob(): Promise<Job | null>;
   sendChat(message: string, platforms?: Platform[]): Promise<unknown>;
   updateOverlay(opts: OverlayUpdate): Promise<unknown>;
+  /** Push real-time presence/layout state (screen-share/camera/collab + camera corner/size).
+   *  Call on every change; sends are coalesced (trailing-debounced). Returns the merged state. */
+  setStreamState(patch: StreamState): StreamState;
+  /** Last presence/layout state set locally. */
+  readonly streamState: StreamState;
   startRealtime(jobId: string): Promise<void>;
   stopRealtime(): void;
   // collaborative split-screen
@@ -273,6 +301,7 @@ export interface UseRestream {
   refreshJob(): Promise<Job | null>;
   sendChat(message: string, platforms?: Platform[]): Promise<unknown>;
   updateOverlay(opts: OverlayUpdate): Promise<unknown>;
+  setStreamState(patch: StreamState): StreamState;
   requestCollab(opts: RequestCollabParams): Promise<CollabInvite>;
   acceptCollab(inviteId: string, opts: AcceptCollabParams): Promise<{ invite: CollabInvite; job: Job }>;
   declineCollab(inviteId: string): Promise<CollabInvite>;