restream-sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ravant Technologies FZCO
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,284 @@
+# restream-sdk
+
+Add **multi-platform restreaming** to your app in minutes. Your streamers connect
+their Twitch / Kick / YouTube accounts and you fan an existing live stream out to
+all of them — with **live chat and viewer counts** aggregated back into your UI.
+
+- ⚡️ **Zero backend.** Set a publishable key and go. (An optional one-route token
+  mode is available when you want hard per-user security.)
+- 🎛 **Headless.** React hooks only — you build the UI with your own design system.
+- 🔌 **You already have the stream.** This is a *control plane*: you hand it the
+  `publisherSessionId` from your existing stream and it manages the restream. It
+  does **not** capture or publish media.
+- 🔑 **No OAuth setup.** Connecting social accounts is hosted for you — your
+  streamers click "Connect Twitch", you register nothing on any platform.
+
+---
+
+## Table of contents
+- [Install](#install)
+- [Prerequisites](#prerequisites)
+- [Quickstart (zero backend)](#quickstart-zero-backend)
+- [How it fits together](#how-it-fits-together)
+- [Connecting accounts](#connecting-accounts)
+- [Going live](#going-live)
+- [Live chat & viewers](#live-chat--viewers)
+- [Banners / overlays](#banners--overlays)
+- [Hardened mode (optional backend)](#hardened-mode-optional-one-route-backend)
+- [API reference](#api-reference)
+- [Scopes](#scopes)
+- [Framework notes (Next.js / SSR)](#framework-notes)
+- [Troubleshooting](#troubleshooting)
+
+---
+
+## Install
+
+```bash
+npm install restream-sdk
+# peer dependency: react >= 17
+```
+
+It's a normal dependency — bundled into your app at build time. Your end users
+install nothing.
+
+## Prerequisites
+
+From whoever operates the Restream Service, you need:
+
+| Thing | What it is |
+|---|---|
+| **API base URL** | e.g. `https://api.restream.example` — where the service runs. |
+| **Publishable key** | `pk_live_…` created in the operator's **Admin → Clients → Keys**, scoped + locked to your app's origin(s). Safe to ship in your frontend. |
+| **A `publisherSessionId`** | Comes from **your existing stream session** (see [below](#where-does-publishersessionid-come-from)). |
+
+You do **not** register any OAuth apps or configure any platform webhooks — that's hosted.
+
+## Quickstart (zero backend)
+
+```jsx
+"use client";
+import { useRestream } from "restream-sdk";
+
+export default function Studio({ streamerId, publisherSessionId }) {
+  const {
+    connections, connect, disconnect,
+    goLive, stopLive, job,
+    viewers, comments, sendChat,
+  } = useRestream({
+    apiBase: "https://api.restream.example",
+    publishableKey: "pk_live_xxx",
+    userId: streamerId,                 // your own user id for this streamer
+  });
+
+  const connected = (p) => connections.find((c) => c.platform === p);
+
+  return (
+    <div>
+      {/* 1 — connect socials (hosted OAuth popup) */}
+      {["twitch", "kick"].map((p) =>
+        connected(p)
+          ? <button key={p} onClick={() => disconnect(p)}>Disconnect {p}</button>
+          : <button key={p} onClick={() => connect(p)}>Connect {p}</button>
+      )}
+
+      {/* 2 — start / stop restreaming your existing session */}
+      {!job
+        ? <button onClick={() => goLive({ publisherSessionId, destinations: ["twitch", "kick"] })}>
+            Go live
+          </button>
+        : <button onClick={stopLive}>Stop ({job.status})</button>}
+
+      {/* 3 — live stats + chat (both directions) */}
+      <p>Viewers: {viewers?.total ?? 0}</p>
+      <ul>{comments.map((c) => <li key={c.id}><b>{c.platform}/{c.author}:</b> {c.message}</li>)}</ul>
+      <button onClick={() => sendChat("hello everyone 👋")}>Say hi to all chats</button>
+    </div>
+  );
+}
+```
+
+## How it fits together
+
+```
+Your existing stream ──(produces a session)──► publisherSessionId
+                                                     │  you pass it to goLive()
+Your app + restream-sdk ────────────────────────►│ Restream Service API
+   (publishable key in the browser)                  ├─ hosted OAuth (you register nothing)
+                                                      ├─ start/stop restream
+                                                      ├─ viewers · comments (SSE) · send chat
+                                                      └─ fans your stream out to Twitch/Kick/…
+```
+
+The browser talks to the service directly with the **publishable key** (origin‑locked
++ scoped). OAuth secrets, platform tokens, and the service's master API key never
+touch the browser.
+
+### Where does `publisherSessionId` come from?
+
+From **your existing streaming setup** — whatever already produces your live session
+hands you that id, and you pass it straight into `goLive()`. The module is a control
+plane; it doesn't capture camera or publish media. (If you don't have a session
+pipeline yet, ask the operator for the recommended way to produce one.)
+
+## Connecting accounts
+
+```js
+await connect("twitch"); // opens a hosted OAuth popup, resolves when connected
+await disconnect("kick");
+connections; // [{ platform, platformUsername, ... }]  (tokens are never exposed)
+```
+
+`connect(platform)` opens a popup to the service's hosted OAuth (using the
+operator's shared platform apps) and resolves when the account is linked. **Allow
+popups** for your origin. Supported: `twitch`, `kick`, `youtube`, `facebook`
+(availability depends on what the operator has enabled).
+
+## Going live
+
+```js
+const job = await goLive({
+  publisherSessionId,                 // required — your existing session
+  destinations: ["twitch", "kick"],   // which connected platforms to fan out to
+  overlay: { htmlBanner: "https://cdn.you.com/banner.html", enabled: true }, // optional
+  recording: false,                   // optional
+});
+// ...
+await stopLive();
+```
+
+- **One live stream per streamer.** Calling `goLive()` again for the same `userId`
+  supersedes the previous job (the new one takes over).
+- **`arm({ destinations })`** lets you pre-select destinations so you can fire
+  `goLive` automatically the moment your session starts.
+
+## Live chat & viewers
+
+```js
+viewers;                       // { total, platforms: { twitch: n, kick: n } } (polled)
+comments;                      // merged incoming chat from all destinations (live via SSE)
+await sendChat("gg!");         // fan a message OUT to every connected chat
+await sendChat("ty", ["kick"]); // …or just some platforms
+```
+
+## Banners / overlays
+
+Pass an `overlay` to `goLive` to composite a banner onto the outgoing stream
+(rendered + burned in server-side, so it shows on every destination):
+
+```js
+goLive({
+  publisherSessionId,
+  destinations: ["twitch"],
+  overlay: { htmlBanner: "https://cdn.you.com/scoreboard.html", enabled: true },
+});
+```
+
+- `htmlBanner` — a URL to a **transparent HTML5 banner**. Your banner can run its
+  own JS/data feed (scoreboards, tickers, live stats) — the service just renders
+  and composites it.
+- `topBanner` / `bottomBanner` — image (PNG) URLs for simple top/bottom bars.
+- Update PNG bars on a live job with `updateOverlay({ topBanner, bottomBanner, hideTop, hideBottom })`.
+
+## Hardened mode (optional, one‑route backend)
+
+The publishable key is origin‑locked and scoped, which is enough for most apps. If
+you don't want to trust the browser with *which* `userId` it streams as, mint a
+short‑lived token on your server (one tiny route) and point the module at it:
+
+```js
+// your backend — call us with your SECRET api key (never sent to the browser)
+app.get("/api/restream-token", async (req, res) => {
+  const r = await fetch("https://api.restream.example/api/v1/auth/session", {
+    method: "POST",
+    headers: { "X-API-Key": process.env.RESTREAM_API_KEY, "Content-Type": "application/json" },
+    body: JSON.stringify({ userId: req.user.id }),     // bound server-side
+  });
+  res.json(await r.json()); // { token, expiresIn }
+});
+```
+
+```jsx
+useRestream({ apiBase: "https://api.restream.example", tokenEndpoint: "/api/restream-token" });
+// no userId/publishableKey in the browser — the user is bound by the token.
+```
+
+## API reference
+
+### `useRestream(options) → state + actions`
+
+**Options:** `{ apiBase, publishableKey?, tokenEndpoint?, userId?, timeoutMs? }`
+(provide either `publishableKey`+`userId`, or `tokenEndpoint`.) `job.status` is
+polled live (`queued → running → stopped`); incoming chat is de-duplicated.
+See [ROADMAP.md](./ROADMAP.md) for planned additions.
+
+**Returns:**
+
+| Field | Type | Notes |
+|---|---|---|
+| `connections` | `Connection[]` | linked accounts (tokens redacted) |
+| `job` | `Job \| null` | current restream job |
+| `viewers` | `{ total, platforms }` | polled viewer counts |
+| `comments` | `Comment[]` | live merged chat (SSE) |
+| `error` | `Error \| null` | last error |
+| `connect(platform)` | `Promise` | hosted OAuth popup |
+| `disconnect(platform)` | `Promise` | |
+| `listConnections()` | `Promise<Connection[]>` | |
+| `arm({ destinations })` | — | pre-select destinations |
+| `goLive(params)` | `Promise<Job>` | see [Going live](#going-live) |
+| `stopLive()` | `Promise` | |
+| `refreshJob()` | `Promise<Job>` | re-fetch job status |
+| `sendChat(message, platforms?)` | `Promise` | outbound chat fan-out |
+| `updateOverlay(opts)` | `Promise` | live banner update |
+| `studio` | `RestreamStudio` | the underlying controller |
+
+### Convenience hooks
+`useConnections(options)`, `useLiveChat(studio)`, `useViewers(studio)`.
+
+### Framework-agnostic core
+Don't use React? Import the controller directly:
+
+```js
+import { RestreamStudio } from "restream-sdk/core";
+const studio = new RestreamStudio({ apiBase, publishableKey, userId });
+studio.on("comments", (c) => …);
+await studio.connect("twitch");
+await studio.goLive({ publisherSessionId, destinations: ["twitch"] });
+```
+
+TypeScript types ship with the package.
+
+## Scopes
+
+A publishable key (or token) carries scopes; the operator sets these when creating it:
+
+| Scope | Allows |
+|---|---|
+| `connect` | manage social connections |
+| `restream` | start/stop a job + overlay updates |
+| `read` | job status, viewers, comments |
+| `chat:write` | send chat |
+
+A 403 with *"Missing required scope"* means your key needs that scope added.
+
+## Framework notes
+
+- **React 17+** (hooks). The package is ESM and side-effect-free (tree-shakeable).
+- **Next.js / SSR:** use the hooks in a Client Component (`"use client"`). `connect()`
+  uses popups + `window`, so it runs in the browser only.
+- The controller uses `fetch`, `EventSource`, and `window.open` — all standard browser APIs.
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+|---|---|
+| `connect()` does nothing | Popup blocked — allow popups for your origin. |
+| `Origin not allowed for this key` (403) | Your app's origin isn't on the key's allowlist — ask the operator to add it. |
+| `failed to fetch` on calls | Origin/key mismatch, or wrong `apiBase`. |
+| Job goes `running` but nothing on the platforms | The `publisherSessionId` must be a **live** session that's actively sending media when you `goLive`. |
+| Starting a 2nd stream stops the first | Expected — **one live stream per streamer**; a new `goLive` supersedes the old. |
+| `Missing required scope` (403) | Key needs that scope (`connect` / `restream` / `read` / `chat:write`). |
+
+---
+
+Questions or a key request? Contact your Restream Service operator.

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "restream-sdk",
+  "version": "0.1.0",
+  "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",
+  "module": "src/index.js",
+  "types": "types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/index.js"
+    },
+    "./core": {
+      "types": "./types/core.d.ts",
+      "import": "./src/core.js"
+    }
+  },
+  "files": ["src", "types", "README.md", "LICENSE"],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "react": ">=17"
+  },
+  "peerDependenciesMeta": {
+    "react": { "optional": true }
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ravant-Technologies/restream-fomogg.git",
+    "directory": "packages/restream-sdk"
+  },
+  "homepage": "https://fomo.gg",
+  "bugs": {
+    "url": "https://github.com/Ravant-Technologies/restream-fomogg/issues"
+  },
+  "author": "Ravant Technologies FZCO",
+  "license": "MIT",
+  "keywords": ["restream", "streaming", "twitch", "kick", "youtube", "multistream", "react", "sdk"]
+}

package/src/core.js

@@ -0,0 +1,271 @@
+// Framework-agnostic controller for the Restream "connect + control" plane.
+// The browser talks to the Restream API directly with a publishable key (or a
+// short-lived token); no client backend required. The media SESSION
+// (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"];
+
+const TERMINAL_STATUS = new Set(["stopped", "failed", "ended", "error", "completed"]);
+
+export class RestreamStudio extends EventTarget {
+  /**
+   * @param {object} opts
+   * @param {string} opts.apiBase           Base URL of the Restream API (e.g. https://api.restream.example)
+   * @param {string} [opts.publishableKey]  pk_live_... (zero-backend mode)
+   * @param {string} [opts.tokenEndpoint]   URL on the client's backend returning { token } (hardened mode)
+   * @param {string} [opts.userId]          External streamer id (required in publishableKey mode)
+   * @param {number} [opts.timeoutMs=15000] Per-request timeout
+   */
+  constructor({ apiBase, publishableKey, tokenEndpoint, userId, timeoutMs = 15000 } = {}) {
+    super();
+    if (!apiBase) throw new Error("apiBase is required");
+    if (!publishableKey && !tokenEndpoint) throw new Error("publishableKey or tokenEndpoint is required");
+    this.apiBase = apiBase.replace(/\/+$/, "");
+    this._apiOrigin = (() => { try { return new URL(this.apiBase).origin; } catch { return null; } })();
+    this.publishableKey = publishableKey || null;
+    this.tokenEndpoint = tokenEndpoint || null;
+    this.userId = userId || null;
+    this.timeoutMs = timeoutMs;
+
+    this.connections = [];
+    this.job = null;
+    this.viewers = null;
+    this.comments = [];
+
+    this._token = null;
+    this._tokenExp = 0;
+    this._es = null;
+    this._pollTimer = null;
+    this._sseReopen = null;
+    this._armed = null;
+  }
+
+  _emit(type, detail) { this.dispatchEvent(new CustomEvent(type, { detail })); }
+
+  /** Subscribe to an event ("connections" | "job" | "viewers" | "comment" | "comments" | "error"). Returns an unsubscribe fn. */
+  on(type, cb) {
+    const handler = (e) => cb(e.detail);
+    this.addEventListener(type, handler);
+    return () => this.removeEventListener(type, handler);
+  }
+
+  _timeoutSignal() {
+    try { return AbortSignal.timeout(this.timeoutMs); } catch { return undefined; } // older browsers: no timeout
+  }
+
+  // ---- auth ----
+  async _getToken() {
+    if (this.publishableKey) return null;
+    const now = Date.now() / 1000;
+    if (this._token && this._tokenExp - 30 > now) return this._token;
+    const res = await fetch(this.tokenEndpoint, { credentials: "include", signal: this._timeoutSignal() });
+    if (!res.ok) throw new Error(`token endpoint failed: ${res.status}`);
+    const data = await res.json();
+    this._token = data.token;
+    try { this._tokenExp = JSON.parse(atob(this._token.split(".")[1])).exp; } catch { this._tokenExp = now + 300; }
+    return this._token;
+  }
+
+  async _authHeaders() {
+    if (this.publishableKey) return { "X-Restream-Key": this.publishableKey };
+    return { Authorization: `Bearer ${await this._getToken()}` };
+  }
+
+  async _authQuery() {
+    if (this.publishableKey) {
+      const q = { pk: this.publishableKey };
+      if (this.userId) q.userId = this.userId;
+      return q;
+    }
+    return { token: await this._getToken() };
+  }
+
+  _userQuery() {
+    return this.publishableKey && this.userId ? `?userId=${encodeURIComponent(this.userId)}` : "";
+  }
+
+  async _req(method, path, body, _retried = false) {
+    const headers = { ...(await this._authHeaders()) };
+    if (body !== undefined) headers["Content-Type"] = "application/json";
+    let res;
+    try {
+      res = await fetch(`${this.apiBase}${path}`, {
+        method,
+        headers,
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+        signal: this._timeoutSignal(),
+      });
+    } catch (e) {
+      const err = new Error(e?.name === "TimeoutError" ? `request timed out after ${this.timeoutMs}ms` : (e?.message || "network error"));
+      err.status = 0;
+      this._emit("error", err);
+      throw err;
+    }
+    // Token expired mid-session (hardened mode): drop the cached token and retry once.
+    if (res.status === 401 && this.tokenEndpoint && !_retried) {
+      this._token = null; this._tokenExp = 0;
+      return this._req(method, path, body, true);
+    }
+    if (res.status === 204) return null;
+    const text = await res.text();
+    let data;
+    try { data = text ? JSON.parse(text) : null; } catch { data = text; }
+    if (!res.ok) {
+      const err = new Error((data && data.error) || `HTTP ${res.status}`);
+      err.status = res.status;
+      this._emit("error", err);
+      throw err;
+    }
+    return data;
+  }
+
+  // ---- social connections ----
+  async listConnections() {
+    this.connections = (await this._req("GET", `/api/v1/connect/list${this._userQuery()}`)) || [];
+    this._emit("connections", this.connections);
+    return this.connections;
+  }
+
+  /** Open the hosted OAuth popup for a platform; resolves when connected (or the popup closes). */
+  async connect(platform) {
+    const q = await this._authQuery();
+    const url = `${this.apiBase}/api/v1/connect/${platform}/start?${new URLSearchParams(q)}`;
+    const popup = window.open(url, "restream_connect", "width=560,height=760");
+    if (!popup) throw new Error("popup blocked — allow popups to connect accounts");
+    return new Promise((resolve, reject) => {
+      const cleanup = () => {
+        window.removeEventListener("message", onMsg);
+        clearInterval(timer);
+      };
+      const onMsg = (e) => {
+        // Only trust messages from our own callback origin.
+        if (this._apiOrigin && e.origin !== this._apiOrigin) return;
+        const d = e.data;
+        if (!d || typeof d !== "object" || d.platform !== platform) return;
+        if (d.type === "restream:connected") { cleanup(); this.listConnections().catch(() => {}); resolve({ platform }); }
+        else if (d.type === "restream:error") { cleanup(); reject(new Error(d.error || "connect failed")); }
+      };
+      const timer = setInterval(() => {
+        if (popup.closed) { cleanup(); this.listConnections().catch(() => {}); resolve({ platform, closed: true }); }
+      }, 800);
+      window.addEventListener("message", onMsg);
+    });
+  }
+
+  async disconnect(platform) {
+    await this._req("DELETE", `/api/v1/connect/${platform}${this._userQuery()}`);
+    return this.listConnections();
+  }
+
+  // ---- restream control ----
+  /** Pre-select default destinations used by goLive() when none are passed. */
+  arm(opts) { this._armed = opts || null; return this._armed; }
+
+  /**
+   * Start restreaming an existing stream session to social destinations.
+   * @param {object} opts
+   * @param {string} opts.publisherSessionId  The session from the client's existing stream (REQUIRED).
+   * @param {string[]} [opts.destinations]     e.g. ["twitch","kick"] (defaults to armed destinations).
+   * @param {object} [opts.overlay]            { topBanner?, bottomBanner?, htmlBanner?, enabled? }
+   * @param {boolean} [opts.recording]
+   * @param {string[]} [opts.trackNames]       tracks actually published, e.g. ["audio","video"]
+   */
+  async goLive({ publisherSessionId, destinations, overlay, recording, trackNames } = {}) {
+    if (!publisherSessionId) throw new Error("publisherSessionId is required (from your existing stream session)");
+    const body = {
+      publisherSessionId,
+      destinations: destinations || this._armed?.destinations || [],
+      overlay,
+      recording,
+    };
+    if (trackNames && trackNames.length) body.trackNames = trackNames;
+    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);
+    return job;
+  }
+
+  async stopLive() {
+    if (!this.job?.id) return null;
+    const r = await this._req("DELETE", `/api/v1/jobs/${this.job.id}`);
+    this.stopRealtime();
+    this.job = { ...this.job, status: "stopping" };
+    this._emit("job", this.job);
+    return r;
+  }
+
+  async refreshJob() {
+    if (!this.job?.id) return null;
+    this.job = await this._req("GET", `/api/v1/jobs/${this.job.id}`);
+    this._emit("job", this.job);
+    return this.job;
+  }
+
+  async sendChat(message, platforms) {
+    if (!this.job?.id) throw new Error("not live");
+    return this._req("POST", `/api/v1/jobs/${this.job.id}/comments`, { message, platforms });
+  }
+
+  async updateOverlay(opts) {
+    if (!this.job?.id) throw new Error("not live");
+    return this._req("PATCH", `/api/v1/jobs/${this.job.id}/overlay`, opts);
+  }
+
+  // ---- realtime (chat SSE + job-status/viewer polling) ----
+  async startRealtime(jobId) {
+    this.stopRealtime();
+    await this._openSse(jobId);
+
+    // Poll job status (so job.status tracks queued→running→stopped) + viewers.
+    let tick = 0;
+    const poll = async () => {
+      tick++;
+      try {
+        const j = await this._req("GET", `/api/v1/jobs/${jobId}`);
+        if (j) {
+          this.job = j;
+          this._emit("job", j);
+          if (TERMINAL_STATUS.has(j.status)) { this.stopRealtime(); return; }
+        }
+      } catch { /* transient — retry next tick */ }
+      if (tick % 2 === 1) { // viewers ~every other tick (~10s)
+        try { this.viewers = await this._req("GET", `/api/v1/jobs/${jobId}/viewers`); this._emit("viewers", this.viewers); } catch { /* non-critical */ }
+      }
+    };
+    poll();
+    this._pollTimer = setInterval(poll, 5000);
+  }
+
+  async _openSse(jobId) {
+    if (this._es) { this._es.close(); this._es = null; }
+    const q = await this._authQuery();
+    const es = new EventSource(`${this.apiBase}/api/v1/jobs/${jobId}/comments/stream?${new URLSearchParams(q)}`);
+    es.onmessage = (e) => {
+      let c;
+      try { c = JSON.parse(e.data); } catch { return; } // heartbeat / non-JSON
+      if (!c || (c.id && this.comments.some((x) => x.id === c.id))) return; // dedup (history replays on reconnect)
+      this.comments = [...this.comments, c].slice(-200);
+      this._emit("comment", c);
+      this._emit("comments", this.comments);
+    };
+    es.onerror = () => {
+      // Transient drop — non-fatal. pk mode auto-reconnects natively; token mode
+      // carries a token in the URL that can expire, so reopen with a fresh one.
+      if (this.tokenEndpoint && this._pollTimer && !this._sseReopen) {
+        this._sseReopen = setTimeout(() => { this._sseReopen = null; if (this._pollTimer) this._openSse(jobId); }, 3000);
+      }
+    };
+    this._es = es;
+  }
+
+  stopRealtime() {
+    if (this._es) { this._es.close(); this._es = null; }
+    if (this._pollTimer) { clearInterval(this._pollTimer); this._pollTimer = null; }
+    if (this._sseReopen) { clearTimeout(this._sseReopen); this._sseReopen = null; }
+  }
+
+  destroy() { this.stopRealtime(); }
+}

package/src/index.js

@@ -0,0 +1,2 @@
+export { RestreamStudio, PLATFORMS } from "./core.js";
+export { useRestream, useConnections, useLiveChat, useViewers } from "./react.js";

package/src/react.js

@@ -0,0 +1,71 @@
+import { useEffect, useRef, useState, useCallback } from "react";
+import { RestreamStudio } from "./core.js";
+
+/**
+ * Headless React binding for the Restream connect + control plane.
+ * Wire your own UI to the returned state and methods.
+ *
+ * @param {object} opts  { apiBase, publishableKey?|tokenEndpoint?, userId? }
+ */
+export function useRestream(opts) {
+  const ref = useRef(null);
+  if (!ref.current) ref.current = new RestreamStudio(opts);
+  const studio = ref.current;
+
+  const [connections, setConnections] = useState([]);
+  const [job, setJob] = useState(null);
+  const [viewers, setViewers] = useState(null);
+  const [comments, setComments] = useState([]);
+  const [error, setError] = useState(null);
+
+  useEffect(() => {
+    const offs = [
+      studio.on("connections", setConnections),
+      studio.on("job", setJob),
+      studio.on("viewers", setViewers),
+      studio.on("comments", setComments),
+      studio.on("error", setError),
+    ];
+    studio.listConnections().catch(() => {});
+    return () => { offs.forEach((off) => off()); studio.destroy(); };
+  }, [studio]);
+
+  return {
+    studio,
+    connections,
+    job,
+    viewers,
+    comments,
+    error,
+    connect: useCallback((p) => studio.connect(p), [studio]),
+    disconnect: useCallback((p) => studio.disconnect(p), [studio]),
+    listConnections: useCallback(() => studio.listConnections(), [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]),
+  };
+}
+
+/** Convenience: just the social-connection state + actions. */
+export function useConnections(opts) {
+  const { connections, connect, disconnect, listConnections } = useRestream(opts);
+  return { connections, connect, disconnect, refresh: listConnections };
+}
+
+/** Convenience: live chat (incoming comments + outbound send). Pass an existing studio. */
+export function useLiveChat(studio) {
+  const [comments, setComments] = useState(studio?.comments || []);
+  useEffect(() => (studio ? studio.on("comments", setComments) : undefined), [studio]);
+  const send = useCallback((m, p) => studio?.sendChat(m, p), [studio]);
+  return { comments, send };
+}
+
+/** Convenience: viewer counts for the active job. Pass an existing studio. */
+export function useViewers(studio) {
+  const [viewers, setViewers] = useState(studio?.viewers || null);
+  useEffect(() => (studio ? studio.on("viewers", setViewers) : undefined), [studio]);
+  return viewers;
+}

package/types/core.d.ts

@@ -0,0 +1,14 @@
+// Types for the framework-agnostic core (`restream-sdk/core`).
+export { RestreamStudio, PLATFORMS } from "./index";
+export type {
+  Platform,
+  RestreamOptions,
+  Connection,
+  Job,
+  ViewerCounts,
+  Comment,
+  Overlay,
+  GoLiveParams,
+  OverlayUpdate,
+  RestreamEvent,
+} from "./index";

package/types/index.d.ts

@@ -0,0 +1,126 @@
+export type Platform = "twitch" | "kick" | "youtube" | "facebook" | "instagram";
+export const PLATFORMS: Platform[];
+
+export interface RestreamOptions {
+  /** Base URL of the Restream API. */
+  apiBase: string;
+  /** Publishable key (pk_live_...) for zero-backend mode. */
+  publishableKey?: string;
+  /** URL on your backend returning `{ token }` (hardened mode). */
+  tokenEndpoint?: string;
+  /** External streamer id (required in publishableKey mode). */
+  userId?: string;
+  /** Per-request timeout in ms (default 15000). */
+  timeoutMs?: number;
+}
+
+export interface Connection {
+  platform: Platform;
+  platformUsername?: string;
+  platformChannelId?: string;
+  connectedAt?: string;
+  [k: string]: unknown;
+}
+
+export interface Job {
+  id: string;
+  status: string;
+  destinations?: Platform[];
+  broadcasts?: Array<{ platform: Platform; watchUrl?: string }>;
+  [k: string]: unknown;
+}
+
+export interface ViewerCounts {
+  total?: number;
+  platforms?: Partial<Record<Platform, number>>;
+  [k: string]: unknown;
+}
+
+export interface Comment {
+  id: string;
+  platform: Platform;
+  author: string;
+  message: string;
+  timestamp?: number;
+  authorAvatar?: string | null;
+}
+
+export interface Overlay {
+  topBanner?: string;
+  bottomBanner?: string;
+  htmlBanner?: string;
+  enabled?: boolean;
+}
+
+export interface GoLiveParams {
+  /** The session id from your existing stream (REQUIRED). */
+  publisherSessionId: string;
+  destinations?: Platform[];
+  overlay?: Overlay;
+  recording?: boolean;
+  /** Track names actually published (e.g. ["audio","video"] or ["video"]). */
+  trackNames?: string[];
+}
+
+export interface OverlayUpdate {
+  topBanner?: string;
+  bottomBanner?: string;
+  hideTop?: boolean;
+  hideBottom?: boolean;
+}
+
+export type RestreamEvent = "connections" | "job" | "viewers" | "comment" | "comments" | "error";
+
+export class RestreamStudio extends EventTarget {
+  constructor(opts: RestreamOptions);
+  connections: Connection[];
+  job: Job | null;
+  viewers: ViewerCounts | null;
+  comments: Comment[];
+  on(type: "connections", cb: (c: Connection[]) => void): () => void;
+  on(type: "job", cb: (j: Job) => void): () => void;
+  on(type: "viewers", cb: (v: ViewerCounts) => void): () => void;
+  on(type: "comment", cb: (c: Comment) => void): () => void;
+  on(type: "comments", cb: (c: Comment[]) => void): () => void;
+  on(type: "error", cb: (e: Error) => void): () => void;
+  listConnections(): Promise<Connection[]>;
+  connect(platform: Platform): Promise<{ platform: Platform; closed?: boolean }>;
+  disconnect(platform: Platform): Promise<Connection[]>;
+  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>;
+  startRealtime(jobId: string): Promise<void>;
+  stopRealtime(): void;
+  destroy(): void;
+}
+
+export interface UseRestream {
+  studio: RestreamStudio;
+  connections: Connection[];
+  job: Job | null;
+  viewers: ViewerCounts | null;
+  comments: Comment[];
+  error: Error | null;
+  connect(platform: Platform): Promise<{ platform: Platform; closed?: boolean }>;
+  disconnect(platform: Platform): Promise<Connection[]>;
+  listConnections(): Promise<Connection[]>;
+  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>;
+}
+
+export function useRestream(opts: RestreamOptions): UseRestream;
+export function useConnections(opts: RestreamOptions): {
+  connections: Connection[];
+  connect(platform: Platform): Promise<{ platform: Platform; closed?: boolean }>;
+  disconnect(platform: Platform): Promise<Connection[]>;
+  refresh(): Promise<Connection[]>;
+};
+export function useLiveChat(studio: RestreamStudio): { comments: Comment[]; send(message: string, platforms?: Platform[]): Promise<unknown> };
+export function useViewers(studio: RestreamStudio): ViewerCounts | null;