restream-sdk 0.1.3 → 0.1.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "restream-sdk",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Plug-and-play headless React hooks to add multi-platform restreaming (connect socials, go live, live chat + viewers) with zero client backend.",
   "type": "module",
   "main": "src/index.js",

package/src/core.js

@@ -4,7 +4,7 @@
 // (publisherSessionId) is produced by the client's existing stream and passed
 // into goLive() — this module never captures or publishes media itself.
 
-export const PLATFORMS = ["twitch", "kick", "youtube", "facebook", "instagram"];
+export const PLATFORMS = ["twitch", "kick", "youtube", "facebook", "instagram", "tiktok"];
 
 const TERMINAL_STATUS = new Set(["stopped", "failed", "ended", "error", "completed"]);
 
@@ -129,6 +129,125 @@ export class RestreamStudio extends EventTarget {
     return this.connections;
   }
 
+  /** Ask the backend which OAuth platforms are configured for this client. */
+  async listOAuthPlatforms() {
+    return this._req("GET", `/api/v1/connect/platforms${this._userQuery()}`);
+  }
+
+  /**
+   * List the channels the user connected inside their Restream account (the
+   * platforms Restream fans out to, e.g. TikTok). Requires a connected Restream
+   * account. Returns [{ id, platform, displayName, url, active }]; pass the chosen
+   * ids to goLive({ destinations: ["restream"], restreamChannels: [...] }).
+   */
+  async listRestreamChannels() {
+    const r = await this._req("GET", `/api/v1/connect/restream/channels${this._userQuery()}`);
+    return r?.channels || [];
+  }
+
+  /**
+   * URL of Restream's add-channel page. Restream's public API has NO endpoint to
+   * connect a new platform (e.g. TikTok) — that consent flow lives only on
+   * restream.io. So "Connect TikTok" deep-links the user here, then we auto-detect
+   * the new channel via the API. The `add` hint is best-effort (Restream ignores
+   * unknown params), so it safely falls back to the channel page.
+   */
+  restreamAddChannelUrl(platform) {
+    const base = "https://restream.io/channel";
+    return platform ? `${base}?add=${encodeURIComponent(platform)}` : base;
+  }
+
+  /**
+   * One-call "Connect <platform> via Restream" for FOMO-style UIs where the user
+   * only ever sees "Connect TikTok / YouTube / Facebook" (Restream stays in the
+   * background). Must be called from a click (it opens a popup).
+   *
+   * Flow: ensures our Restream API connection exists (runs Restream OAuth if not) →
+   * opens Restream's add-channel page → polls until the new channel of `platform`
+   * appears in the account.
+   *
+   * @param {string} platform  e.g. "tiktok" | "youtube" | "facebook"
+   * @param {object} [opts] { pollMs=3000, timeoutMs=180000 }
+   * @returns {Promise<RestreamChannel|null>} the new channel, or null if the user
+   *          closed the popup without adding one.
+   */
+  async connectRestreamChannel(platform, { pollMs = 3000, timeoutMs = 180_000 } = {}) {
+    // 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");
+
+    try {
+      // 1. We need our own API connection to the user's Restream account to read +
+      //    detect their channels. If it's missing, run the Restream OAuth first.
+      await this.listConnections();
+      if (!this.connections.some((c) => c.platform === "restream")) {
+        const q = await this._authQuery();
+        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.
+        if (popup.closed) popup = window.open("", "restream_add_channel", "width=760,height=900");
+      }
+
+      // 2. Snapshot existing channels of this platform so we detect the NEW one.
+      const before = new Set(
+        (await this.listRestreamChannels()).filter((c) => c.platform === platform).map((c) => c.id),
+      );
+
+      // 3. Send the user to Restream's add-channel page.
+      const url = this.restreamAddChannelUrl(platform);
+      if (popup && !popup.closed) popup.location = url;
+      else popup = window.open(url, "restream_add_channel", "width=760,height=900");
+
+      // 4. Poll until the new channel appears (or the popup closes / we time out).
+      return await this._awaitNewRestreamChannel(platform, before, popup, { pollMs, timeoutMs });
+    } catch (err) {
+      try { popup && popup.close(); } catch { /* ignore */ }
+      throw err;
+    }
+  }
+
+  // Resolve once a Restream API connection exists (postMessage from our callback,
+  // with a polling fallback). Rejects on timeout.
+  _awaitRestreamConnected(timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    return new Promise((resolve, reject) => {
+      const cleanup = () => { window.removeEventListener("message", onMsg); clearInterval(timer); };
+      const finish = () => { cleanup(); this.listConnections().catch(() => {}); resolve(); };
+      const onMsg = (e) => {
+        if (this._apiOrigin && e.origin !== this._apiOrigin) return;
+        const d = e.data;
+        if (d && typeof d === "object" && d.platform === "restream" && d.type === "restream:connected") finish();
+      };
+      const timer = setInterval(async () => {
+        try {
+          await this.listConnections();
+          if (this.connections.some((c) => c.platform === "restream")) return finish();
+        } catch { /* keep polling */ }
+        if (Date.now() > deadline) { cleanup(); reject(new Error("timed out connecting Restream account")); }
+      }, 1500);
+      window.addEventListener("message", onMsg);
+    });
+  }
+
+  // Poll listRestreamChannels() until a channel of `platform` not in `before`
+  // shows up. Resolves the channel, or null on popup-close/timeout with nothing new.
+  _awaitNewRestreamChannel(platform, before, popup, { pollMs, timeoutMs }) {
+    const deadline = Date.now() + timeoutMs;
+    const pick = (chans) => chans.find((c) => c.platform === platform && !before.has(c.id)) || null;
+    return new Promise((resolve) => {
+      const done = (v) => { clearInterval(timer); resolve(v); };
+      const tick = async () => {
+        let found = null;
+        try { found = pick(await this.listRestreamChannels()); } catch { /* transient */ }
+        if (found) return done(found);
+        if (Date.now() > deadline || (popup && popup.closed)) {
+          try { return done(pick(await this.listRestreamChannels())); } catch { return done(null); }
+        }
+      };
+      const timer = setInterval(tick, pollMs);
+    });
+  }
+
   /** Open the hosted OAuth popup for a platform; resolves when connected (or the popup closes). */
   async connect(platform) {
     // Open the popup synchronously, inside the click's user-activation window —
@@ -175,7 +294,7 @@ export class RestreamStudio extends EventTarget {
    * @param {boolean} [opts.recording]
    * @param {string[]} [opts.trackNames]       tracks actually published, e.g. ["audio","video"]
    */
-  async goLive({ publisherSessionId, destinations, overlay, recording, trackNames } = {}) {
+  async goLive({ publisherSessionId, destinations, overlay, recording, trackNames, restreamChannels } = {}) {
     if (!publisherSessionId) throw new Error("publisherSessionId is required (from your existing stream session)");
     const body = {
       publisherSessionId,
@@ -184,6 +303,8 @@ export class RestreamStudio extends EventTarget {
       recording,
     };
     if (trackNames && trackNames.length) body.trackNames = trackNames;
+    // Per-platform selection for the "restream" fan-out bridge (channel ids or platform names).
+    if (restreamChannels && restreamChannels.length) body.restreamChannels = restreamChannels;
     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;

package/src/react.js

@@ -40,6 +40,10 @@ export function useRestream(opts) {
     connect: useCallback((p) => studio.connect(p), [studio]),
     disconnect: useCallback((p) => studio.disconnect(p), [studio]),
     listConnections: useCallback(() => studio.listConnections(), [studio]),
+    listOAuthPlatforms: useCallback(() => studio.listOAuthPlatforms(), [studio]),
+    listRestreamChannels: useCallback(() => studio.listRestreamChannels(), [studio]),
+    connectRestreamChannel: useCallback((p, o) => studio.connectRestreamChannel(p, o), [studio]),
+    restreamAddChannelUrl: useCallback((p) => studio.restreamAddChannelUrl(p), [studio]),
     arm: useCallback((o) => studio.arm(o), [studio]),
     goLive: useCallback((o) => studio.goLive(o), [studio]),
     stopLive: useCallback(() => studio.stopLive(), [studio]),
@@ -51,8 +55,8 @@ export function useRestream(opts) {
 
 /** Convenience: just the social-connection state + actions. */
 export function useConnections(opts) {
-  const { connections, connect, disconnect, listConnections } = useRestream(opts);
-  return { connections, connect, disconnect, refresh: listConnections };
+  const { connections, connect, disconnect, listConnections, listOAuthPlatforms, listRestreamChannels, connectRestreamChannel, restreamAddChannelUrl } = useRestream(opts);
+  return { connections, connect, disconnect, refresh: listConnections, listOAuthPlatforms, listRestreamChannels, connectRestreamChannel, restreamAddChannelUrl };
 }
 
 /** Convenience: live chat (incoming comments + outbound send). Pass an existing studio. */

package/types/core.d.ts

@@ -2,6 +2,7 @@
 export { RestreamStudio, PLATFORMS } from "./index";
 export type {
   Platform,
+  RestreamChannel,
   RestreamOptions,
   Connection,
   Job,

package/types/index.d.ts

@@ -1,4 +1,13 @@
-export type Platform = "twitch" | "kick" | "youtube" | "facebook" | "instagram";
+export type Platform = "twitch" | "kick" | "youtube" | "facebook" | "instagram" | "tiktok" | "restream";
+
+/** A channel the user connected inside their Restream account (a fan-out target). */
+export interface RestreamChannel {
+  id: string;
+  platform: string;
+  displayName: string | null;
+  url: string | null;
+  active: boolean;
+}
 export const PLATFORMS: Platform[];
 
 export interface RestreamOptions {
@@ -60,6 +69,12 @@ export interface GoLiveParams {
   recording?: boolean;
   /** Track names actually published (e.g. ["audio","video"] or ["video"]). */
   trackNames?: string[];
+  /**
+   * For the "restream" fan-out destination: which Restream channels to relay to
+   * (channel ids from listRestreamChannels(), or platform names like "tiktok").
+   * Omit to use whichever channels are currently active in the Restream account.
+   */
+  restreamChannels?: string[];
 }
 
 export interface OverlayUpdate {
@@ -84,6 +99,20 @@ export class RestreamStudio extends EventTarget {
   on(type: "comments", cb: (c: Comment[]) => void): () => void;
   on(type: "error", cb: (e: Error) => void): () => void;
   listConnections(): Promise<Connection[]>;
+  listOAuthPlatforms(): Promise<{ platforms: Platform[]; frontendOrigin: string; redirectOrigin: string }>;
+  listRestreamChannels(): Promise<RestreamChannel[]>;
+  /** URL of Restream's add-channel page (best-effort deep-link to `platform`). */
+  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
+   * adding one. Must be called from a user gesture (opens a popup).
+   */
+  connectRestreamChannel(
+    platform: string,
+    opts?: { pollMs?: number; timeoutMs?: number }
+  ): Promise<RestreamChannel | null>;
   connect(platform: Platform): Promise<{ platform: Platform; closed?: boolean }>;
   disconnect(platform: Platform): Promise<Connection[]>;
   arm(opts: { destinations: Platform[] }): unknown;
@@ -111,6 +140,13 @@ 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 }>;
+  listRestreamChannels(): Promise<RestreamChannel[]>;
+  restreamAddChannelUrl(platform?: string): string;
+  connectRestreamChannel(
+    platform: string,
+    opts?: { pollMs?: number; timeoutMs?: number }
+  ): Promise<RestreamChannel | null>;
   arm(opts: { destinations: Platform[] }): unknown;
   goLive(opts: GoLiveParams): Promise<Job>;
   stopLive(): Promise<unknown>;
@@ -125,6 +161,13 @@ 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 }>;
+  listRestreamChannels(): Promise<RestreamChannel[]>;
+  restreamAddChannelUrl(platform?: string): string;
+  connectRestreamChannel(
+    platform: string,
+    opts?: { pollMs?: number; timeoutMs?: number }
+  ): Promise<RestreamChannel | null>;
 };
 export function useLiveChat(studio: RestreamStudio): { comments: Comment[]; send(message: string, platforms?: Platform[]): Promise<unknown> };
 export function useViewers(studio: RestreamStudio): ViewerCounts | null;