restream-sdk 0.1.6 → 0.1.8

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "restream-sdk",
-  "version": "0.1.6",
-  "description": "Plug-and-play headless React hooks to add multi-platform restreaming (connect socials, go live, live chat + viewers) with zero client backend.",
+  "version": "0.1.8",
+  "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",
   "module": "src/index.js",

package/src/core.js

@@ -41,11 +41,13 @@ export class RestreamStudio extends EventTarget {
     this._armed = null;
     this._watchPoll = null;
     this._watchUserId = null;
+    this._collabEs = null;
+    this._collabReopen = null;
   }
 
   _emit(type, detail) { this.dispatchEvent(new CustomEvent(type, { detail })); }
 
-  /** Subscribe to an event ("connections" | "job" | "viewers" | "comment" | "comments" | "error"). Returns an unsubscribe fn. */
+  /** Subscribe to an event ("connections" | "job" | "viewers" | "comment" | "comments" | "error" | "collab" | "collab-invite" | "collab-accepted" | "collab-declined" | "collab-revoked" | "collab-ended" | "collab-expired" | "collab-composite" | "collab-snapshot"). Returns an unsubscribe fn. */
   on(type, cb) {
     const handler = (e) => cb(e.detail);
     this.addEventListener(type, handler);
@@ -297,7 +299,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 } = {}) {
+  async goLive({ publisherSessionId, destinations, overlay, recording, trackNames, restreamChannels, streamMeta, destinationMeta } = {}) {
     if (!publisherSessionId) throw new Error("publisherSessionId is required (from your existing stream session)");
     const body = {
       publisherSessionId,
@@ -313,6 +315,12 @@ export class RestreamStudio extends EventTarget {
     if (streamMeta && (streamMeta.title || streamMeta.description || (streamMeta.tags && streamMeta.tags.length))) {
       body.streamMeta = streamMeta;
     }
+    // Per-destination overrides, keyed by platform name (e.g. { youtube: {title},
+    // twitch: {title, tags} }). Each field falls back to streamMeta, then the
+    // creator's pre-set per-destination / global default on the platform.
+    if (destinationMeta && typeof destinationMeta === "object" && Object.keys(destinationMeta).length) {
+      body.destinationMeta = destinationMeta;
+    }
     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;
@@ -438,5 +446,108 @@ export class RestreamStudio extends EventTarget {
     this.job = null;
   }
 
-  destroy() { this.unwatch(); }
+  // ---- collaborative split-screen ----
+  /** Add the acting user id in publishable-key mode (token mode binds it server-side). */
+  _withUser(body = {}) {
+    if (this.publishableKey && this.userId) return { ...body, clientUserId: this.userId };
+    return body;
+  }
+
+  /**
+   * Invite another creator (same client) to a split-screen collab. The composite
+   * 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).
+   * @param {object} opts { collaboratorUserId, collaboratorRestreamOn?, publisherSessionId?, destinations?, metadata? }
+   */
+  async requestCollab({ collaboratorUserId, collaboratorRestreamOn = false, 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,
+    }));
+    this._emit("collab-invite", { type: "collab-invite", invite, mine: true });
+    return invite;
+  }
+
+  /** List your sent + received collab invites: { sent:[], received:[] }. */
+  async listCollabInvites() {
+    const qs = this.publishableKey && this.userId ? `?clientUserId=${encodeURIComponent(this.userId)}` : "";
+    return this._req("GET", `/api/v1/collab/invites${qs}`);
+  }
+
+  /**
+   * Accept an invite and JOIN the composite. Your publisherSessionId (your existing
+   * stream session) is required — it becomes the second video in the frame. On success
+   * this attaches to the composite job and starts realtime, emitting `collab-composite`.
+   */
+  async acceptCollab(inviteId, { publisherSessionId, overlay, recording, metadata } = {}) {
+    if (!inviteId) throw new Error("inviteId is required");
+    if (!publisherSessionId) throw new Error("publisherSessionId (your stream session) is required to join the composite");
+    const r = await this._req("POST", `/api/v1/collab/${inviteId}/accept`, this._withUser({ publisherSessionId, overlay, recording, metadata }));
+    if (r?.job?.id) {
+      this.job = r.job;
+      this._emit("job", r.job);
+      this._emit("collab-composite", { type: "collab-composite", invite: r.invite, job: r.job });
+      this.startRealtime(r.job.id);
+    }
+    return r;
+  }
+
+  /** Decline a pending invite addressed to you. */
+  async declineCollab(inviteId) {
+    return this._req("POST", `/api/v1/collab/${inviteId}/decline`, this._withUser({}));
+  }
+
+  /** Toggle whether YOUR audience (destinations + Growth) is included in the composite. */
+  async setCollabRestream(inviteId, on) {
+    return this._req("PATCH", `/api/v1/collab/${inviteId}/restream`, this._withUser({ on: !!on }));
+  }
+
+  /** Revoke a pending invite you sent (before it is accepted). */
+  async revokeCollab(inviteId) {
+    const qs = this.publishableKey && this.userId ? `?clientUserId=${encodeURIComponent(this.userId)}` : "";
+    return this._req("DELETE", `/api/v1/collab/${inviteId}${qs}`);
+  }
+
+  /** End a live collab (stops the composite job). Defaults to the current job. */
+  async endCollab(jobId) {
+    const id = jobId || this.job?.id;
+    if (!id) throw new Error("no active collab job");
+    const r = await this._req("POST", `/api/v1/collab/${id}/end`, this._withUser({}));
+    this.stopRealtime();
+    if (this.job?.id === id) { this.job = { ...this.job, status: "stopping" }; this._emit("job", this.job); }
+    return r;
+  }
+
+  /**
+   * Open the collab signaling stream: emits `collab-invite`, `collab-accepted`,
+   * `collab-declined`, `collab-revoked`, `collab-ended`, `collab-expired`, plus a
+   * `collab-snapshot` of current invites on connect. Also re-emits each as `collab`.
+   */
+  async startCollabRealtime() {
+    this.stopCollabRealtime();
+    const q = await this._authQuery();
+    if (this.publishableKey && this.userId) q.clientUserId = this.userId;
+    const es = new EventSource(`${this.apiBase}/api/v1/collab/invites/stream?${new URLSearchParams(q)}`);
+    es.onmessage = (e) => {
+      let evt;
+      try { evt = JSON.parse(e.data); } catch { return; } // heartbeat / non-JSON
+      if (!evt || !evt.type) return;
+      this._emit(evt.type, evt);
+      this._emit("collab", evt);
+    };
+    es.onerror = () => {
+      // Transient drop. token mode carries an expiring token in the URL → reopen fresh.
+      if (this.tokenEndpoint && this._collabEs && !this._collabReopen) {
+        this._collabReopen = setTimeout(() => { this._collabReopen = null; if (this._collabEs) this.startCollabRealtime(); }, 3000);
+      }
+    };
+    this._collabEs = es;
+  }
+
+  stopCollabRealtime() {
+    if (this._collabEs) { this._collabEs.close(); this._collabEs = null; }
+    if (this._collabReopen) { clearTimeout(this._collabReopen); this._collabReopen = null; }
+  }
+
+  destroy() { this.unwatch(); this.stopCollabRealtime(); }
 }

package/src/react.js

@@ -17,14 +17,18 @@ export function useRestream(opts) {
   const [viewers, setViewers] = useState(null);
   const [comments, setComments] = useState([]);
   const [error, setError] = useState(null);
+  const [collabInvites, setCollabInvites] = useState({ sent: [], received: [] });
 
   useEffect(() => {
+    const refreshInvites = () => studio.listCollabInvites().then(setCollabInvites).catch(() => {});
     const offs = [
       studio.on("connections", setConnections),
       studio.on("job", setJob),
       studio.on("viewers", setViewers),
       studio.on("comments", setComments),
       studio.on("error", setError),
+      // Any collab event refreshes the invite lists (snapshot arrives on connect).
+      studio.on("collab", refreshInvites),
     ];
     studio.listConnections().catch(() => {});
     return () => { offs.forEach((off) => off()); studio.destroy(); };
@@ -37,6 +41,7 @@ export function useRestream(opts) {
     viewers,
     comments,
     error,
+    collabInvites,
     connect: useCallback((p) => studio.connect(p), [studio]),
     disconnect: useCallback((p) => studio.disconnect(p), [studio]),
     listConnections: useCallback(() => studio.listConnections(), [studio]),
@@ -50,6 +55,16 @@ 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]),
+    // collaborative split-screen
+    requestCollab: useCallback((o) => studio.requestCollab(o), [studio]),
+    acceptCollab: useCallback((id, o) => studio.acceptCollab(id, o), [studio]),
+    declineCollab: useCallback((id) => studio.declineCollab(id), [studio]),
+    revokeCollab: useCallback((id) => studio.revokeCollab(id), [studio]),
+    setCollabRestream: useCallback((id, on) => studio.setCollabRestream(id, on), [studio]),
+    endCollab: useCallback((id) => studio.endCollab(id), [studio]),
+    listCollabInvites: useCallback(() => studio.listCollabInvites(), [studio]),
+    startCollabRealtime: useCallback(() => studio.startCollabRealtime(), [studio]),
+    stopCollabRealtime: useCallback(() => studio.stopCollabRealtime(), [studio]),
   };
 }
 

package/types/index.d.ts

@@ -81,6 +81,13 @@ export interface GoLiveParams {
    * this creator on the platform. Omit entirely to use the pre-set defaults.
    */
   streamMeta?: StreamMeta;
+  /**
+   * Per-destination overrides, keyed by platform name (e.g.
+   * `{ youtube: { title }, twitch: { title, tags } }`). Each field falls back, in
+   * order, to: this map → `streamMeta` → the creator's pre-set per-destination
+   * default → the creator's pre-set global default → the platform's existing value.
+   */
+  destinationMeta?: DestinationMeta;
 }
 
 export interface StreamMeta {
@@ -89,6 +96,9 @@ export interface StreamMeta {
   tags?: string[];
 }
 
+/** Per-platform stream metadata overrides, keyed by platform name. */
+export type DestinationMeta = Partial<Record<Platform, StreamMeta>> & Record<string, StreamMeta>;
+
 export interface OverlayUpdate {
   topBanner?: string;
   bottomBanner?: string;
@@ -96,7 +106,63 @@ export interface OverlayUpdate {
   hideBottom?: boolean;
 }
 
-export type RestreamEvent = "connections" | "job" | "viewers" | "comment" | "comments" | "error";
+export type RestreamEvent =
+  | "connections" | "job" | "viewers" | "comment" | "comments" | "error"
+  | "collab" | "collab-invite" | "collab-accepted" | "collab-declined"
+  | "collab-revoked" | "collab-ended" | "collab-expired" | "collab-composite" | "collab-snapshot";
+
+/** A collaborative split-screen invite (A invites B; the composite starts on accept). */
+export interface CollabInvite {
+  id: string;
+  clientId: string;
+  issuerUserId: string;
+  collaboratorUserId: string;
+  issuerExternalId: string;
+  collaboratorExternalId: string;
+  status: "pending" | "accepted" | "declined" | "revoked" | "ended" | "expired";
+  collaboratorRestreamOn: boolean;
+  streamJobId: string | null;
+  metadata?: Record<string, unknown>;
+  createdAt: string;
+  acceptedAt?: string | null;
+  endedAt?: string | null;
+  expiresAt: string;
+}
+
+export interface CollabInviteList {
+  sent: CollabInvite[];
+  received: CollabInvite[];
+}
+
+/** A real-time collab signaling event (from startCollabRealtime()). */
+export interface CollabEvent {
+  type: RestreamEvent;
+  invite?: CollabInvite;
+  job?: Job;
+  sent?: CollabInvite[];
+  received?: CollabInvite[];
+  [k: string]: unknown;
+}
+
+export interface RequestCollabParams {
+  /** The other creator's external id (same client). */
+  collaboratorUserId: string;
+  /** Include the collaborator's own audience (destinations + Growth) in the composite. */
+  collaboratorRestreamOn?: boolean;
+  /** Your publisher session (so the composite can start on accept). */
+  publisherSessionId?: string;
+  /** Your destination platforms for the composite. */
+  destinations?: Platform[];
+  metadata?: Record<string, unknown>;
+}
+
+export interface AcceptCollabParams {
+  /** Your existing stream session — becomes the second video in the frame (REQUIRED). */
+  publisherSessionId: string;
+  overlay?: Overlay;
+  recording?: boolean;
+  metadata?: Record<string, unknown>;
+}
 
 export class RestreamStudio extends EventTarget {
   constructor(opts: RestreamOptions);
@@ -110,6 +176,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: "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<{ platforms: Platform[]; frontendOrigin: string; redirectOrigin: string }>;
   listRestreamChannels(): Promise<RestreamChannel[]>;
@@ -135,6 +202,16 @@ export class RestreamStudio extends EventTarget {
   updateOverlay(opts: OverlayUpdate): Promise<unknown>;
   startRealtime(jobId: string): Promise<void>;
   stopRealtime(): void;
+  // collaborative split-screen
+  requestCollab(opts: RequestCollabParams): Promise<CollabInvite>;
+  acceptCollab(inviteId: string, opts: AcceptCollabParams): Promise<{ invite: CollabInvite; job: Job }>;
+  declineCollab(inviteId: string): Promise<CollabInvite>;
+  revokeCollab(inviteId: string): Promise<CollabInvite>;
+  setCollabRestream(inviteId: string, on: boolean): Promise<CollabInvite>;
+  endCollab(jobId?: string): Promise<unknown>;
+  listCollabInvites(): Promise<CollabInviteList>;
+  startCollabRealtime(): Promise<void>;
+  stopCollabRealtime(): void;
   /** Read-only viewer mode: stream a streamer's live social chat + viewer counts. */
   watch(userId: string, opts?: { pollMs?: number }): Promise<{ id: string } | null>;
   /** Stop watching (clears the poll + realtime streams). */
@@ -149,6 +226,7 @@ export interface UseRestream {
   viewers: ViewerCounts | null;
   comments: Comment[];
   error: Error | null;
+  collabInvites: CollabInviteList;
   connect(platform: Platform): Promise<{ platform: Platform; closed?: boolean }>;
   disconnect(platform: Platform): Promise<Connection[]>;
   listConnections(): Promise<Connection[]>;
@@ -165,6 +243,15 @@ export interface UseRestream {
   refreshJob(): Promise<Job | null>;
   sendChat(message: string, platforms?: Platform[]): Promise<unknown>;
   updateOverlay(opts: OverlayUpdate): Promise<unknown>;
+  requestCollab(opts: RequestCollabParams): Promise<CollabInvite>;
+  acceptCollab(inviteId: string, opts: AcceptCollabParams): Promise<{ invite: CollabInvite; job: Job }>;
+  declineCollab(inviteId: string): Promise<CollabInvite>;
+  revokeCollab(inviteId: string): Promise<CollabInvite>;
+  setCollabRestream(inviteId: string, on: boolean): Promise<CollabInvite>;
+  endCollab(jobId?: string): Promise<unknown>;
+  listCollabInvites(): Promise<CollabInviteList>;
+  startCollabRealtime(): Promise<void>;
+  stopCollabRealtime(): void;
 }
 
 export function useRestream(opts: RestreamOptions): UseRestream;