restream-sdk 0.1.4 → 0.1.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "restream-sdk",
-  "version": "0.1.4",
+  "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.",
   "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", "tiktok"];
+export const PLATFORMS = ["twitch", "kick", "youtube", "facebook", "instagram", "tiktok", "restream"];
 
 const TERMINAL_STATUS = new Set(["stopped", "failed", "ended", "error", "completed"]);
 
@@ -145,6 +145,109 @@ export class RestreamStudio extends EventTarget {
     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 —
@@ -190,8 +293,11 @@ export class RestreamStudio extends EventTarget {
    * @param {object} [opts.overlay]            { topBanner?, bottomBanner?, htmlBanner?, enabled? }
    * @param {boolean} [opts.recording]
    * @param {string[]} [opts.trackNames]       tracks actually published, e.g. ["audio","video"]
+   * @param {object} [opts.streamMeta]         { title?, description?, tags?:string[] } applied to
+   *                                           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 } = {}) {
+  async goLive({ publisherSessionId, destinations, overlay, recording, trackNames, restreamChannels, streamMeta } = {}) {
     if (!publisherSessionId) throw new Error("publisherSessionId is required (from your existing stream session)");
     const body = {
       publisherSessionId,
@@ -202,6 +308,11 @@ export class RestreamStudio extends EventTarget {
     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;
+    // Stream title/description/tags. Send only what you have — omitted fields fall
+    // back to the creator's pre-set default on the platform.
+    if (streamMeta && (streamMeta.title || streamMeta.description || (streamMeta.tags && streamMeta.tags.length))) {
+      body.streamMeta = streamMeta;
+    }
     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

@@ -42,6 +42,8 @@ export function useRestream(opts) {
     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]),
@@ -53,8 +55,8 @@ export function useRestream(opts) {
 
 /** Convenience: just the social-connection state + actions. */
 export function useConnections(opts) {
-  const { connections, connect, disconnect, listConnections, listOAuthPlatforms, listRestreamChannels } = useRestream(opts);
-  return { connections, connect, disconnect, refresh: listConnections, listOAuthPlatforms, listRestreamChannels };
+  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/index.d.ts

@@ -75,6 +75,18 @@ export interface GoLiveParams {
    * Omit to use whichever channels are currently active in the Restream account.
    */
   restreamChannels?: string[];
+  /**
+   * Stream title / description / tags applied to the Restream channels. Send only
+   * the fields you have — any field you omit falls back to the default pre-set for
+   * this creator on the platform. Omit entirely to use the pre-set defaults.
+   */
+  streamMeta?: StreamMeta;
+}
+
+export interface StreamMeta {
+  title?: string;
+  description?: string;
+  tags?: string[];
 }
 
 export interface OverlayUpdate {
@@ -101,6 +113,18 @@ export class RestreamStudio extends EventTarget {
   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;
@@ -130,6 +154,11 @@ export interface UseRestream {
   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>;
@@ -146,6 +175,11 @@ export function useConnections(opts: RestreamOptions): {
   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;