restream-sdk 0.1.9 → 0.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "restream-sdk",
-  "version": "0.1.9",
+  "version": "0.3.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,11 @@ 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;
+
     this._token = null;
     this._tokenExp = 0;
     this._es = null;
@@ -131,9 +142,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 +214,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 +242,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 +269,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 +385,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 } = {}) {
     if (!publisherSessionId) throw new Error("publisherSessionId is required (from your existing stream session)");
     const body = {
       publisherSessionId,
@@ -321,6 +407,12 @@ 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;
@@ -457,9 +549,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,6 +49,8 @@ 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]),
@@ -70,8 +72,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;
@@ -178,20 +192,31 @@ export class RestreamStudio extends EventTarget {
   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 }>;
+  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;
@@ -230,13 +255,18 @@ 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>;
@@ -260,13 +290,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;