restream-sdk 0.1.9 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "restream-sdk",
-  "version": "0.1.9",
+  "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",
@@ -55,4 +55,4 @@
     "react",
     "sdk"
   ]
-}
+}

package/src/core.js

@@ -5,6 +5,12 @@
 // into goLive() — this module never captures or publishes media itself.
 
 export const PLATFORMS = ["twitch", "kick", "youtube", "facebook", "instagram", "tiktok", "restream"];
+// FALLBACK only. The real routing (oauth | restream | off) is fetched per-client from
+// GET /api/v1/connect/platforms → `routing`, so the platform team controls native↔Restream
+// entirely from the admin with no SDK/app change. These statics are used solely if that
+// fetch hasn't happened yet (e.g. a sync call before loadRouting()).
+const NATIVE_CONNECT_PLATFORMS = new Set(["youtube", "facebook"]);
+const RESTREAM_BRIDGE_PLATFORMS = new Set(["tiktok"]);
 
 const TERMINAL_STATUS = new Set(["stopped", "failed", "ended", "error", "completed"]);
 
@@ -33,6 +39,19 @@ export class RestreamStudio extends EventTarget {
     this.viewers = null;
     this.comments = [];
 
+    // Per-client routing map { <platform>: "oauth" | "restream" | "off" }, fetched from
+    // GET /connect/platforms. Null until loadRouting()/listOAuthPlatforms() runs; the
+    // 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;
@@ -131,9 +150,57 @@ export class RestreamStudio extends EventTarget {
     return this.connections;
   }
 
-  /** Ask the backend which OAuth platforms are configured for this client. */
+  /** Ask the backend which OAuth platforms are configured for this client.
+   *  Also caches the per-client `routing` map ({platform: oauth|restream|off}) that
+   *  drives connectPlatform()/restreamAddChannelUrl() — so native↔Restream is decided
+   *  by the admin, not hardcoded here. */
   async listOAuthPlatforms() {
-    return this._req("GET", `/api/v1/connect/platforms${this._userQuery()}`);
+    const r = await this._req("GET", `/api/v1/connect/platforms${this._userQuery()}`);
+    if (r && r.routing && typeof r.routing === "object") this._routing = r.routing;
+    return r;
+  }
+
+  /** Load (and cache) the per-client routing map. Call once on init so the synchronous
+   *  connect helpers route correctly. Returns { platform: "oauth"|"restream"|"off" }. */
+  async loadRouting() {
+    await this.listOAuthPlatforms();
+    return this._routing || {};
+  }
+
+  /** Effective route for a platform: "oauth" | "restream" | "off" | null (unknown). Uses
+   *  the cached admin routing if loaded; otherwise the static fallbacks. */
+  routeFor(platform) {
+    const p = String(platform || "").toLowerCase();
+    if (this._routing && this._routing[p]) return this._routing[p];
+    if (NATIVE_CONNECT_PLATFORMS.has(p)) return "oauth";
+    if (RESTREAM_BRIDGE_PLATFORMS.has(p)) return "restream";
+    return null;
+  }
+
+  _isNativeConnect(platform) {
+    return this.routeFor(platform) === "oauth";
+  }
+
+  _isBridge(platform) {
+    return this.routeFor(platform) === "restream";
+  }
+
+  /**
+   * Single dynamic connect entry point — the app calls this for ANY platform and the
+   * SDK routes it per the admin's configuration (no app change when routing flips):
+   *   "oauth"    → native OAuth popup (connect)
+   *   "restream" → Restream bridge add-channel flow (connectRestreamChannel)
+   *   "off"      → throws (platform disabled for this client)
+   * Loads routing first if it hasn't been cached yet. Must be called from a click.
+   * @param {string} platform
+   * @param {object} [opts] forwarded to connectRestreamChannel for bridge platforms
+   */
+  async connectPlatform(platform, opts = {}) {
+    if (!this._routing) { try { await this.loadRouting(); } catch { /* fall back to statics */ } }
+    const route = this.routeFor(platform);
+    if (route === "oauth") return this.connect(platform);
+    if (route === "restream") return this.connectRestreamChannel(platform, opts);
+    throw new Error(`"${platform}" is not available to connect for this client (routed "off").`);
   }
 
   /**
@@ -155,6 +222,15 @@ export class RestreamStudio extends EventTarget {
    * unknown params), so it safely falls back to the channel page.
    */
   restreamAddChannelUrl(platform) {
+    const normalized = String(platform || "").toLowerCase();
+    if (this._isNativeConnect(normalized) && this.publishableKey) {
+      const q = new URLSearchParams({ pk: this.publishableKey });
+      if (this.userId) q.set("userId", this.userId);
+      return `${this.apiBase}/api/v1/connect/${platform}/start?${q}`;
+    }
+    if (normalized && !this._isBridge(normalized)) {
+      throw new Error(`"${platform}" is not routed through the Restream bridge for this client. Use native OAuth (connect) instead.`);
+    }
     const base = "https://restream.io/channel";
     return platform ? `${base}?add=${encodeURIComponent(platform)}` : base;
   }
@@ -174,6 +250,23 @@ export class RestreamStudio extends EventTarget {
    *          closed the popup without adding one.
    */
   async connectRestreamChannel(platform, { pollMs = 3000, timeoutMs = 180_000 } = {}) {
+    const normalized = String(platform || "").toLowerCase();
+    // Load routing so native↔bridge is decided by the admin, not the statics.
+    if (!this._routing) { try { await this.loadRouting(); } catch { /* fall back to statics */ } }
+    if (this._isNativeConnect(normalized)) {
+      const result = await this.connect(platform);
+      return {
+        id: `native:${platform}`,
+        platform,
+        displayName: null,
+        url: null,
+        active: !result?.closed,
+      };
+    }
+    if (!this._isBridge(normalized)) {
+      throw new Error(`"${platform}" is not routed through the Restream bridge for this client. Use native OAuth (connect) instead.`);
+    }
+
     // Open synchronously to preserve the click's user-activation (else it's blocked).
     let popup = window.open("", "restream_add_channel", "width=760,height=900");
     if (!popup) throw new Error("popup blocked — allow popups to connect accounts");
@@ -184,6 +277,7 @@ export class RestreamStudio extends EventTarget {
       await this.listConnections();
       if (!this.connections.some((c) => c.platform === "restream")) {
         const q = await this._authQuery();
+        q.platform = normalized;
         popup.location = `${this.apiBase}/api/v1/connect/restream/start?${new URLSearchParams(q)}`;
         await this._awaitRestreamConnected(timeoutMs);
         // Our OAuth callback page auto-closes the popup; reopen for the add step.
@@ -299,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 } = {}) {
+  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,
@@ -321,11 +415,24 @@ export class RestreamStudio extends EventTarget {
     if (destinationMeta && typeof destinationMeta === "object" && Object.keys(destinationMeta).length) {
       body.destinationMeta = destinationMeta;
     }
+    // Streaming provider selection per destination.
+    // Example: { youtube: "youtube_native" } to use native YouTube instead of Restream bridge.
+    // Default is "restream" for all destinations.
+    if (streamingProvider && typeof streamingProvider === "object" && Object.keys(streamingProvider).length) {
+      body.streamingProvider = streamingProvider;
+    }
     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;
     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;
   }
 
@@ -333,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;
@@ -355,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();
@@ -457,9 +599,17 @@ export class RestreamStudio extends EventTarget {
    * 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).
+   *
+   * 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.
    * @param {object} opts { collaboratorUserId, collaboratorRestreamOn?, publisherSessionId?, destinations?, metadata? }
    */
-  async requestCollab({ collaboratorUserId, collaboratorRestreamOn = false, publisherSessionId, destinations, metadata } = {}) {
+  async requestCollab({ collaboratorUserId, collaboratorRestreamOn = true, 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,

package/src/react.js

@@ -49,12 +49,15 @@ export function useRestream(opts) {
     listRestreamChannels: useCallback(() => studio.listRestreamChannels(), [studio]),
     connectRestreamChannel: useCallback((p, o) => studio.connectRestreamChannel(p, o), [studio]),
     restreamAddChannelUrl: useCallback((p) => studio.restreamAddChannelUrl(p), [studio]),
+    connectPlatform: useCallback((p, o) => studio.connectPlatform(p, o), [studio]),
+    loadRouting: useCallback(() => studio.loadRouting(), [studio]),
     arm: useCallback((o) => studio.arm(o), [studio]),
     goLive: useCallback((o) => studio.goLive(o), [studio]),
     stopLive: useCallback(() => studio.stopLive(), [studio]),
     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]),
@@ -70,8 +73,8 @@ export function useRestream(opts) {
 
 /** Convenience: just the social-connection state + actions. */
 export function useConnections(opts) {
-  const { connections, connect, disconnect, listConnections, listOAuthPlatforms, listRestreamChannels, connectRestreamChannel, restreamAddChannelUrl } = useRestream(opts);
-  return { connections, connect, disconnect, refresh: listConnections, listOAuthPlatforms, listRestreamChannels, connectRestreamChannel, restreamAddChannelUrl };
+  const { connections, connect, disconnect, listConnections, listOAuthPlatforms, listRestreamChannels, connectRestreamChannel, restreamAddChannelUrl, connectPlatform, loadRouting } = useRestream(opts);
+  return { connections, connect, disconnect, refresh: listConnections, listOAuthPlatforms, listRestreamChannels, connectRestreamChannel, restreamAddChannelUrl, connectPlatform, loadRouting };
 }
 
 /** Convenience: live chat (incoming comments + outbound send). Pass an existing studio. */

package/types/index.d.ts

@@ -1,5 +1,19 @@
 export type Platform = "twitch" | "kick" | "youtube" | "facebook" | "instagram" | "tiktok" | "restream";
 
+/** How a platform is reached for this client (admin-controlled): native OAuth, the
+ *  Restream bridge, or disabled. */
+export type RoutingValue = "oauth" | "restream" | "off";
+/** Per-client routing map returned by GET /connect/platforms (`routing`). */
+export type Routing = Partial<Record<Platform, RoutingValue>>;
+/** Response of listOAuthPlatforms(). `routing` is the single source of truth for
+ *  native↔Restream; `platforms` is the legacy natively-connectable set. */
+export interface OAuthPlatformsResponse {
+  platforms: Platform[];
+  routing?: Routing;
+  frontendOrigin: string;
+  redirectOrigin: string;
+}
+
 /** A channel the user connected inside their Restream account (a fan-out target). */
 export interface RestreamChannel {
   id: string;
@@ -88,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 {
@@ -99,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;
@@ -176,22 +212,34 @@ 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<{ platforms: Platform[]; frontendOrigin: string; redirectOrigin: string }>;
+  listOAuthPlatforms(): Promise<OAuthPlatformsResponse>;
   listRestreamChannels(): Promise<RestreamChannel[]>;
-  /** URL of Restream's add-channel page (best-effort deep-link to `platform`). */
+  /** URL of Restream's add-channel page; YouTube/Facebook return native OAuth URLs in publishable-key mode. */
   restreamAddChannelUrl(platform?: string): string;
   /**
    * One-call "Connect <platform> via Restream" — ensures the Restream account is
    * connected, opens Restream's add-channel page, and resolves once the new channel
-   * appears. Returns the new channel, or null if the user closed the popup without
+   * appears. YouTube and Facebook are routed to native OAuth instead. Returns the
+   * new channel, a native placeholder, or null if the user closed the popup without
    * adding one. Must be called from a user gesture (opens a popup).
    */
   connectRestreamChannel(
     platform: string,
     opts?: { pollMs?: number; timeoutMs?: number }
   ): Promise<RestreamChannel | null>;
+  /** Load + cache the per-client routing map; call once on init. */
+  loadRouting(): Promise<Routing>;
+  /** Effective route for a platform (uses cached admin routing, else static fallback). */
+  routeFor(platform: string): RoutingValue | null;
+  /** Single dynamic connect entry point — routes to native OAuth or the Restream bridge
+   *  per the admin's configuration. Must be called from a user gesture. */
+  connectPlatform(
+    platform: string,
+    opts?: { pollMs?: number; timeoutMs?: number }
+  ): Promise<{ platform: Platform; closed?: boolean } | RestreamChannel | null>;
   connect(platform: Platform): Promise<{ platform: Platform; closed?: boolean }>;
   disconnect(platform: Platform): Promise<Connection[]>;
   arm(opts: { destinations: Platform[] }): unknown;
@@ -200,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
@@ -230,19 +283,25 @@ export interface UseRestream {
   connect(platform: Platform): Promise<{ platform: Platform; closed?: boolean }>;
   disconnect(platform: Platform): Promise<Connection[]>;
   listConnections(): Promise<Connection[]>;
-  listOAuthPlatforms(): Promise<{ platforms: Platform[]; frontendOrigin: string; redirectOrigin: string }>;
+  listOAuthPlatforms(): Promise<OAuthPlatformsResponse>;
   listRestreamChannels(): Promise<RestreamChannel[]>;
   restreamAddChannelUrl(platform?: string): string;
   connectRestreamChannel(
     platform: string,
     opts?: { pollMs?: number; timeoutMs?: number }
   ): Promise<RestreamChannel | null>;
+  connectPlatform(
+    platform: string,
+    opts?: { pollMs?: number; timeoutMs?: number }
+  ): Promise<{ platform: Platform; closed?: boolean } | RestreamChannel | null>;
+  loadRouting(): Promise<Routing>;
   arm(opts: { destinations: Platform[] }): unknown;
   goLive(opts: GoLiveParams): Promise<Job>;
   stopLive(): Promise<unknown>;
   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>;
@@ -260,13 +319,18 @@ export function useConnections(opts: RestreamOptions): {
   connect(platform: Platform): Promise<{ platform: Platform; closed?: boolean }>;
   disconnect(platform: Platform): Promise<Connection[]>;
   refresh(): Promise<Connection[]>;
-  listOAuthPlatforms(): Promise<{ platforms: Platform[]; frontendOrigin: string; redirectOrigin: string }>;
+  listOAuthPlatforms(): Promise<OAuthPlatformsResponse>;
   listRestreamChannels(): Promise<RestreamChannel[]>;
   restreamAddChannelUrl(platform?: string): string;
   connectRestreamChannel(
     platform: string,
     opts?: { pollMs?: number; timeoutMs?: number }
   ): Promise<RestreamChannel | null>;
+  connectPlatform(
+    platform: string,
+    opts?: { pollMs?: number; timeoutMs?: number }
+  ): Promise<{ platform: Platform; closed?: boolean } | RestreamChannel | null>;
+  loadRouting(): Promise<Routing>;
 };
 export function useLiveChat(studio: RestreamStudio): { comments: Comment[]; send(message: string, platforms?: Platform[]): Promise<unknown> };
 export function useViewers(studio: RestreamStudio): ViewerCounts | null;