restream-sdk 0.1.0 → 0.1.1

package/README.md

@@ -1,34 +1,49 @@
 # 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.
+Add **multi-platform restreaming** to your app. Your streamers connect their
+Twitch / Kick / YouTube accounts once, and you fan an **already-live stream** out
+to all of them — with **live chat and viewer counts** aggregated back into your UI.
+
+```
+Your existing live stream  ──►  Twitch
+        (one session)      ──►  Kick      + merged chat & viewer counts back to your UI
+                           ──►  YouTube …
+```
+
+- ⚡️ **Zero backend.** Drop in a publishable key and go. (An optional one-route token mode adds hard per-user security — recommended for production.)
+- 🎛 **Headless.** React hooks only — you build the UI with your own components.
+- 🔌 **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 fully hosted — your streamers click "Connect Twitch"; you register nothing on any platform and configure no webhooks.
+
+> **Mental model.** You're already streaming a session (e.g. via Cloudflare
+> Realtime). This SDK is the thin layer that lets a streamer **link their social
+> accounts** and **mirror that session** to them, controlled entirely from your
+> frontend. The heavy lifting (OAuth, tokens, transcoding, RTMP fan-out, chat
+> collection) lives server-side.
 
 ---
 
 ## Table of contents
 - [Install](#install)
-- [Prerequisites](#prerequisites)
-- [Quickstart (zero backend)](#quickstart-zero-backend)
-- [How it fits together](#how-it-fits-together)
+- [The integration contract (read this first)](#the-integration-contract-read-this-first)
+- [What you get from your operator](#what-you-get-from-your-operator)
+- [Quickstart](#quickstart-zero-backend)
+- [The full streamer lifecycle](#the-full-streamer-lifecycle)
+- [Where `publisherSessionId` comes from](#where-publishersessionid-comes-from)
+- [The `userId` contract & persistence](#the-userid-contract--persistence)
 - [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)
+- [Auth modes: publishable key vs. token](#auth-modes-publishable-key-vs-token)
+- [Output resolution & quality](#output-resolution--quality)
 - [API reference](#api-reference)
+- [Data shapes](#data-shapes)
 - [Scopes](#scopes)
-- [Framework notes (Next.js / SSR)](#framework-notes)
+- [Next.js / SSR notes](#nextjs--ssr-notes)
+- [Error handling](#error-handling)
 - [Troubleshooting](#troubleshooting)
+- [Integration checklist](#integration-checklist)
 
 ---
 
@@ -36,23 +51,40 @@ all of them — with **live chat and viewer counts** aggregated back into your U
 
 ```bash
 npm install restream-sdk
-# peer dependency: react >= 17
+# peer dependency: react >= 17 (optional — a framework-agnostic core ships too)
 ```
 
-It's a normal dependency — bundled into your app at build time. Your end users
-install nothing.
+It's a normal build-time dependency bundled into your app. **Your end users install nothing.**
 
-## Prerequisites
+---
 
-From whoever operates the Restream Service, you need:
+## The integration contract (read this first)
 
-| 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)). |
+To go from zero to live you provide exactly **four** things. Everything else is hosted.
+
+| # | You provide | Where it comes from | Notes |
+|---|---|---|---|
+| 1 | **`apiBase`** | Your operator | e.g. `https://restream-api.fomo.gg` |
+| 2 | **A credential** | Your operator | A `publishableKey` (`pk_live_…`) for zero-backend, **or** a `tokenEndpoint` for [hardened mode](#auth-modes-publishable-key-vs-token) |
+| 3 | **A stable `userId`** | **Your** user system | The streamer's id in *your* database. Must be **stable + unique** — connections and jobs are keyed by it server-side. See [the contract](#the-userid-contract--persistence). |
+| 4 | **A `publisherSessionId`** | **Your existing stream** | The live media session you already produce, passed into `goLive()`. See [below](#where-publishersessionid-comes-from). |
+
+You do **not** register OAuth apps, host OAuth callbacks, configure platform
+webhooks, or handle any platform tokens. That's all server-side.
+
+---
+
+## What you get from your operator
+
+Ask whoever runs the Restream Service for:
 
-You do **not** register any OAuth apps or configure any platform webhooks — that's hosted.
+1. **API base URL** — e.g. `https://restream-api.fomo.gg`.
+2. **A publishable key** — `pk_live_…`, created in **Admin → Clients → Keys**, with:
+   - **Scopes:** `connect`, `restream`, `read`, `chat:write` (see [Scopes](#scopes)).
+   - **Allowed origins:** every origin your app runs on, e.g. `https://app.fomo.gg`, `http://localhost:3000`. The key is **origin-locked** — it only works from those origins, which is what makes it safe to ship in your frontend.
+3. *(Production)* The **secret API key** — server-side only, for [token mode](#auth-modes-publishable-key-vs-token). **Never** put this in the browser.
+
+---
 
 ## Quickstart (zero backend)
 
@@ -60,36 +92,36 @@ You do **not** register any OAuth apps or configure any platform webhooks — th
 "use client";
 import { useRestream } from "restream-sdk";
 
-export default function Studio({ streamerId, publisherSessionId }) {
+export default function RestreamPanel({ streamerId, publisherSessionId }) {
   const {
     connections, connect, disconnect,
     goLive, stopLive, job,
     viewers, comments, sendChat,
   } = useRestream({
-    apiBase: "https://api.restream.example",
+    apiBase: "https://restream-api.fomo.gg",
     publishableKey: "pk_live_xxx",
-    userId: streamerId,                 // your own user id for this streamer
+    userId: streamerId,            // ← your stable id for this streamer
   });
 
-  const connected = (p) => connections.find((c) => c.platform === p);
+  const isConnected = (p) => connections.some((c) => c.platform === p);
 
   return (
     <div>
-      {/* 1 — connect socials (hosted OAuth popup) */}
+      {/* 1 — link social accounts (hosted OAuth popup) */}
       {["twitch", "kick"].map((p) =>
-        connected(p)
+        isConnected(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 */}
+      {/* 2 — mirror your existing session to the connected platforms */}
       {!job
         ? <button onClick={() => goLive({ publisherSessionId, destinations: ["twitch", "kick"] })}>
             Go live
           </button>
         : <button onClick={stopLive}>Stop ({job.status})</button>}
 
-      {/* 3 — live stats + chat (both directions) */}
+      {/* 3 — merged viewers + 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>
@@ -98,73 +130,210 @@ export default function Studio({ streamerId, publisherSessionId }) {
 }
 ```
 
-## How it fits together
+---
+
+## The full streamer lifecycle
+
+A complete, production-shaped component covering the whole journey — link accounts,
+go live with your session, watch links, viewers, two-way chat, stop:
+
+```jsx
+"use client";
+import { useRestream } from "restream-sdk";
+import { useState } from "react";
+
+const PLATFORMS = ["twitch", "kick"];
+
+export default function Studio({ streamerId, getPublisherSessionId }) {
+  const r = useRestream({
+    apiBase: "https://restream-api.fomo.gg",
+    publishableKey: process.env.NEXT_PUBLIC_RESTREAM_PK,
+    userId: streamerId,                 // stable id from your user table
+  });
+  const [msg, setMsg] = useState("");
+  const isConnected = (p) => r.connections.some((c) => c.platform === p);
+  const live = r.job && !["stopped", "failed", "ended"].includes(r.job.status);
+
+  async function start() {
+    // Pull the session id from YOUR existing stream pipeline at go-live time.
+    const publisherSessionId = await getPublisherSessionId();
+    await r.goLive({ publisherSessionId, destinations: PLATFORMS.filter(isConnected) });
+  }
 
+  return (
+    <section>
+      {/* link accounts — persists across refreshes (keyed by userId) */}
+      <div>
+        {PLATFORMS.map((p) => (
+          <button key={p} onClick={() => isConnected(p) ? r.disconnect(p) : r.connect(p)}>
+            {isConnected(p) ? `✓ ${p}` : `Connect ${p}`}
+          </button>
+        ))}
+      </div>
+
+      {/* go live / stop */}
+      {!live
+        ? <button disabled={!PLATFORMS.some(isConnected)} onClick={start}>Go live</button>
+        : <button onClick={r.stopLive}>Stop stream</button>}
+      {r.job && <span> status: {r.job.status}</span>}
+
+      {/* watch links (available once broadcasts are created) */}
+      {(r.job?.broadcasts || []).map((b) => b.watchUrl &&
+        <a key={b.platform} href={b.watchUrl} target="_blank" rel="noreferrer">Watch on {b.platform} ↗</a>)}
+
+      {/* live stats + merged chat */}
+      {live && (
+        <>
+          <p>Viewers: {r.viewers?.total ?? 0}
+            {r.viewers?.platforms && Object.entries(r.viewers.platforms).map(([p, n]) => ` · ${p}: ${n}`)}</p>
+          <ul>{r.comments.map((c) => <li key={c.id}><b>{c.platform}/{c.author}:</b> {c.message}</li>)}</ul>
+          <form onSubmit={(e) => { e.preventDefault(); r.sendChat(msg); setMsg(""); }}>
+            <input value={msg} onChange={(e) => setMsg(e.target.value)} placeholder="message all chats" />
+            <button>Send</button>
+          </form>
+        </>
+      )}
+
+      {r.error && <p role="alert">{r.error.message}</p>}
+    </section>
+  );
+}
 ```
-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/…
+
+> Note `getPublisherSessionId()` — you supply the session id from **your** stream
+> at the moment you go live. The SDK never creates it.
+
+---
+
+## Where `publisherSessionId` comes from
+
+This is the one piece that ties into *your* infrastructure, so it's worth being precise.
+
+**The `publisherSessionId` is the live media session your platform already
+produces for the streamer.** If your platform publishes streamer media to
+**Cloudflare Realtime (Calls)** — the typical setup — the **session id** Cloudflare
+returns when the streamer's broadcast starts **is** the `publisherSessionId`. You
+already have it; you just pass it in:
+
+```js
+// when your streamer goes live on YOUR platform, you already create a session:
+const publisherSessionId = "<the Cloudflare Calls session id for this broadcast>";
+
+await goLive({ publisherSessionId, destinations: ["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.
+Requirements:
+- The session must be **live and actively sending media** at the moment you call `goLive()`. The worker pulls from it immediately.
+- It must carry the tracks you intend to restream (audio + video). If you publish **video only** (e.g. no mic), pass `trackNames: ["video"]` so the worker doesn't wait for an audio track that will never arrive:
+
+  ```js
+  goLive({ publisherSessionId, destinations: ["twitch"], trackNames: ["video"] });
+  ```
+
+The SDK is a control plane: it **does not** open a camera, capture a screen, or
+publish RTMP/WebRTC. Producing the session stays entirely on your side, exactly as
+it works today — the only change is that **your frontend** now makes the `goLive()`
+call (instead of nothing happening after the session starts).
+
+---
+
+## The `userId` contract & persistence
+
+`userId` is the streamer's id **in your system** (e.g. your DB primary key). It is
+the join key for everything server-side, so:
+
+- ✅ **Stable** — use the same value for a given streamer **forever**. Don't use a
+  random/session value.
+- ✅ **Unique per streamer** — one streamer = one `userId`.
+- ✅ **Opaque is fine** — `"user_8412"`, a UUID, etc. Avoid PII.
+
+**Why it matters — persistence is automatic and server-side:**
+
+- When a streamer connects Twitch/Kick, the link is stored **server-side**, keyed
+  by `(yourClient, userId, platform)`. Nothing about it lives in the browser.
+- On mount (including **after a page refresh, in a new tab, or on another device**),
+  the SDK auto-calls `listConnections()` and your `connections` state repopulates —
+  the streamer sees "✓ Twitch" again with **no re-auth**.
+- Platform tokens are **auto-refreshed** server-side, so connections stay valid
+  long-term. A streamer only needs to reconnect if they revoke access on the
+  platform itself.
 
-### Where does `publisherSessionId` come from?
+> If you pass a *different* `userId` on the next load, you'll get a different
+> (empty) connection set. A stable `userId` is the whole persistence story.
 
-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.)
+In [token mode](#auth-modes-publishable-key-vs-token) the `userId` is baked into
+the token your backend mints — so it's inherently stable per logged-in user and the
+browser can't stream as anyone else.
+
+---
 
 ## Connecting accounts
 
 ```js
-await connect("twitch"); // opens a hosted OAuth popup, resolves when connected
+await connect("twitch");   // opens a hosted OAuth popup, resolves when linked
 await disconnect("kick");
-connections; // [{ platform, platformUsername, ... }]  (tokens are never exposed)
+connections;               // [{ platform, platformUsername, ... }] — tokens 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).
+- `connect(platform)` opens a popup to the service's **hosted OAuth** (using the
+  operator's shared platform apps) and resolves on success. **Allow popups** for
+  your origin.
+- Supported: `twitch`, `kick`, `youtube`, `facebook`, `instagram` — availability
+  depends on what the operator has enabled.
+- Connections **persist** (see [above](#the-userid-contract--persistence)); you
+  don't store anything yourself.
+
+---
 
 ## Going live
 
 ```js
 const job = await goLive({
-  publisherSessionId,                 // required — your existing session
-  destinations: ["twitch", "kick"],   // which connected platforms to fan out to
+  publisherSessionId,                  // REQUIRED — your existing live 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
+  recording: false,                    // optional
+  trackNames: ["audio", "video"],      // optional — match what your session publishes
 });
-// ...
+
 await stopLive();
 ```
 
+- **One encode → many destinations.** Restreaming to 2 platforms or 5 costs the
+  same on the source; it's a single encode fanned out.
 - **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.
+  **supersedes** the previous job (the new one takes over). This prevents duplicate
+  streams if a streamer double-clicks or reloads mid-stream.
+- **Watch links.** Once broadcasts are created, `job.broadcasts` carries
+  `{ platform, watchUrl }` for each destination — handy for "Watch on Twitch ↗".
+- **`arm({ destinations })`** pre-selects destinations so you can fire `goLive`
+  (with just the `publisherSessionId`) the instant your session starts — useful for
+  auto-start when a streamer goes live on your platform.
+
+---
 
 ## 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
+viewers;                          // { total, platforms: { twitch: 12, kick: 5 } } — polled ~10s
+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 only some platforms
 ```
 
+- `comments` is the **merged inbound** feed across all destinations, delivered over
+  SSE and **de-duplicated** (history replays safely on reconnect). It's capped to
+  the most recent 200 messages.
+- Each comment: `{ id, platform, author, authorAvatar, message, timestamp }`.
+- `sendChat` is **outbound fan-out** — one message posted to every (or selected)
+  connected chat. Requires the `chat:write` scope.
+
+---
+
 ## 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):
+(rendered + burned in server-side, so it shows on **every** destination):
 
 ```js
 goLive({
@@ -174,57 +343,84 @@ goLive({
 });
 ```
 
-- `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 })`.
+- `htmlBanner` — URL to a **transparent HTML5 page**. It can run its own JS/data
+  feed (scoreboards, tickers, live stats); the service renders it headlessly and
+  composites it full-frame every tick.
+- `topBanner` / `bottomBanner` — transparent **PNG** URLs for simple top/bottom bars.
+- Update PNG bars on a live job without restarting it:
+  ```js
+  await updateOverlay({ topBanner, bottomBanner, hideTop, hideBottom });
+  ```
 
-## Hardened mode (optional, one‑route backend)
+---
+
+## Auth modes: publishable key vs. token
 
-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:
+| | **Publishable key** (`pk_live_…`) | **Token** (`tokenEndpoint`) |
+|---|---|---|
+| Client backend | **None** | One small route |
+| `userId` | Passed from the browser | **Bound server-side** in the token |
+| Security | Origin-locked + scoped (good) | Hard per-user binding (best) |
+| Best for | Quick start, demos, trusted UIs | **Production** — anywhere the browser shouldn't pick *which* user it streams as |
+
+The publishable key is origin-locked and scoped, which is enough for many apps. For
+production (and anywhere a user could tamper with a `userId`), mint a **short-lived
+token** on your server with your **secret** API key and point the SDK 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", {
+// YOUR backend — one route. The secret key never reaches the browser.
+app.get("/api/restream-token", requireAuth, async (req, res) => {
+  const r = await fetch("https://restream-api.fomo.gg/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
+    body: JSON.stringify({ userId: req.user.id }),   // ← bound to the logged-in user, server-side
   });
-  res.json(await r.json()); // { token, expiresIn }
+  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.
+// browser — no publishableKey, no userId; the token carries (and locks) the user.
+useRestream({ apiBase: "https://restream-api.fomo.gg", tokenEndpoint: "/api/restream-token" });
 ```
 
+The SDK fetches the token, attaches it to every request, and **transparently
+re-mints** it when it expires (including reopening the chat stream).
+
+---
+
+## Output resolution & quality
+
+The restream output **matches the resolution of your publisher session** (up to
+**1080p**). Bitrate, H.264 profile, and encoding are handled server-side — you don't
+configure an encoder. To deliver 1080p, publish your session at 1080p; a 720p
+session restreams at 720p. Adding more destinations does **not** reduce quality
+(single encode, fanned out).
+
+---
+
 ## 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.
+— provide either `publishableKey` (+ `userId`) **or** `tokenEndpoint`. `timeoutMs`
+defaults to `15000`. On mount it auto-loads connections; `job.status` is polled live
+(`queued → running → stopped`); incoming chat is de-duplicated.
 
 **Returns:**
 
 | Field | Type | Notes |
 |---|---|---|
-| `connections` | `Connection[]` | linked accounts (tokens redacted) |
-| `job` | `Job \| null` | current restream job |
+| `connections` | `Connection[]` | linked accounts (tokens redacted); auto-loaded on mount |
+| `job` | `Job \| null` | current restream job (status polled) |
 | `viewers` | `{ total, platforms }` | polled viewer counts |
-| `comments` | `Comment[]` | live merged chat (SSE) |
-| `error` | `Error \| null` | last error |
+| `comments` | `Comment[]` | live merged inbound chat (SSE), latest 200 |
+| `error` | `Error \| null` | last error (`err.status` carries the HTTP code) |
 | `connect(platform)` | `Promise` | hosted OAuth popup |
 | `disconnect(platform)` | `Promise` | |
-| `listConnections()` | `Promise<Connection[]>` | |
-| `arm({ destinations })` | — | pre-select destinations |
+| `listConnections()` | `Promise<Connection[]>` | manual refresh |
+| `arm({ destinations })` | — | pre-select destinations for `goLive` |
 | `goLive(params)` | `Promise<Job>` | see [Going live](#going-live) |
 | `stopLive()` | `Promise` | |
 | `refreshJob()` | `Promise<Job>` | re-fetch job status |
@@ -233,52 +429,129 @@ See [ROADMAP.md](./ROADMAP.md) for planned additions.
 | `studio` | `RestreamStudio` | the underlying controller |
 
 ### Convenience hooks
-`useConnections(options)`, `useLiveChat(studio)`, `useViewers(studio)`.
+`useConnections(options)` → `{ connections, connect, disconnect, refresh }`,
+`useLiveChat(studio)` → `{ comments, send }`,
+`useViewers(studio)` → `{ viewers }`.
 
 ### Framework-agnostic core
-Don't use React? Import the controller directly:
+Not using React? Import the controller directly:
 
 ```js
 import { RestreamStudio } from "restream-sdk/core";
+
 const studio = new RestreamStudio({ apiBase, publishableKey, userId });
-studio.on("comments", (c) => …);
+const off = studio.on("comments", (list) => render(list));   // also: connections, job, viewers, comment, error
+await studio.listConnections();
 await studio.connect("twitch");
 await studio.goLive({ publisherSessionId, destinations: ["twitch"] });
+// ... studio.destroy() to tear down timers/streams
+```
+
+TypeScript types ship with the package (`restream-sdk` and `restream-sdk/core`).
+
+---
+
+## Data shapes
+
+```ts
+type Platform = "twitch" | "kick" | "youtube" | "facebook" | "instagram";
+
+interface Connection {
+  platform: Platform;
+  platformUsername: string;     // display name on the platform
+  platformUserId?: string;
+}
+
+interface Job {
+  id: string;
+  status: "queued" | "running" | "stopping" | "stopped" | "failed" | "ended";
+  broadcasts?: { platform: Platform; watchUrl?: string; broadcastId?: string }[];
+}
+
+interface Comment {
+  id: string;
+  platform: Platform;
+  author: string;
+  authorAvatar?: string | null;
+  message: string;
+  timestamp: number;
+}
+
+interface Viewers {
+  total: number;
+  platforms: Record<Platform, number>;   // e.g. { twitch: 12, kick: 5 }
+}
 ```
 
-TypeScript types ship with the package.
+---
 
 ## Scopes
 
-A publishable key (or token) carries scopes; the operator sets these when creating it:
+A publishable key (or token) carries scopes; the operator sets them at creation:
 
 | Scope | Allows |
 |---|---|
-| `connect` | manage social connections |
+| `connect` | manage social connections (connect / list / disconnect) |
 | `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.
+A `403 "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.
+## Next.js / SSR notes
+
+- **Use the hooks in a Client Component** (`"use client"`). `connect()` uses popups
+  and `window`, so it runs in the browser only.
+- Put the publishable key in a **`NEXT_PUBLIC_`** env var (it's safe — origin-locked).
+  The **secret** API key (token mode) stays server-side only.
+- The package is **ESM** and side-effect-free (tree-shakeable). It uses `fetch`,
+  `EventSource`, and `window.open` — all standard browser APIs.
+
+---
+
+## Error handling
+
+- Every action rejects on failure; the hook also surfaces the latest error as
+  `error`. Errors carry `err.status` (the HTTP status, or `0` for network/timeout):
+
+  ```js
+  try { await goLive({ publisherSessionId, destinations }); }
+  catch (e) { if (e.status === 403) showUpgrade(); else toast(e.message); }
+  ```
+- Common statuses: `401` (bad/expired credential — token mode re-mints automatically),
+  `403` (origin not allowed, or missing scope), `409`/supersede (a newer stream took
+  over), `0` (network/timeout).
+- Realtime is resilient: transient SSE drops reconnect automatically and chat
+  history de-dupes on replay; job-status polling retries on transient failures.
+
+---
 
 ## Troubleshooting
 
 | Symptom | Cause / fix |
 |---|---|
-| `connect()` does nothing | Popup blocked — allow popups for your origin. |
+| `connect()` does nothing | Popup blocked — allow popups for your origin (call it from a click handler). |
 | `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`. |
+| `failed to fetch` / network error | Wrong `apiBase`, or the origin/key mismatch blocked CORS. |
+| Connections empty after refresh | You passed a **different `userId`** — it must be stable per streamer. |
+| Job goes `running` but nothing on the platforms | The `publisherSessionId` must be a **live** session actively sending media when you `goLive()`. |
+| Worker seems to wait / no audio | Your session has no audio track — pass `trackNames: ["video"]`. |
 | 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.
+## Integration checklist
+
+- [ ] Operator created a **publishable key** scoped `connect, restream, read, chat:write` and allowlisted your origin(s).
+- [ ] You pass a **stable, unique `userId`** per streamer.
+- [ ] You can supply a **live `publisherSessionId`** from your existing stream at go-live time (with `trackNames` if audio-less).
+- [ ] Popups are allowed for your origin (for `connect`).
+- [ ] *(Production)* You stood up the **token endpoint** and switched the SDK to `tokenEndpoint` so `userId` is server-bound.
+- [ ] You render `connections`, `job.status`, `job.broadcasts` watch links, `viewers`, and `comments`.
+
+---
+
+Questions, a key request, or an origin to allowlist? Contact your Restream Service operator.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "restream-sdk",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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",