@anonotf/connect 0.1.0

package/README.md

@@ -0,0 +1,125 @@
+# @anonotf/connect
+
+Client SDK for AnonOtF — handles calls, live streaming to many viewers, live chat, and voice notes/recordings. 
+
+## Install
+
+```bash
+npm install @anonotf/connect
+```
+
+## Architecture — read this before wiring it up
+
+This SDK runs **in the browser**. Two things must never end up there:
+
+- Your AnonOtF **x-api-key** (it can create/delete apps, read all data)
+- Your **API secret**
+
+So your own backend needs two small pieces:
+
+1. An endpoint that mints a short-lived **socket token** —
+   call AnonOtF's `POST /api/apps/:appId/socket-token` with your x-api-key,
+   return the token to your frontend.
+2. A thin **REST proxy** for everything under `/api/*` (rooms, media clips,
+   streaming tokens) — your frontend calls *your* backend, your backend
+   attaches the x-api-key and forwards to AnonOtF.
+
+This SDK never sends your x-api-key from the browser. The `serverUrl` you
+pass in is only used for the Socket.IO connection (authenticated by the
+token, not the key); `apiBase` should point at your own backend's proxy.
+
+## Quick start
+
+```js
+import { AnonOtFConnect } from '@anonotf/connect';
+
+// `token` came from YOUR backend, which called AnonOtF's
+// POST /api/apps/:appId/socket-token using your x-api-key.
+const client = new AnonOtFConnect({
+  serverUrl: 'https://your-anonotf-server.com',
+  token: theTokenYourBackendGaveYou,
+  apiBase: 'https://your-backend.com/api', // your own proxy, see above
+});
+
+client.connect();
+await client.register({ name: 'Alex' });
+```
+
+## Calls (1-on-1, grows to group)
+
+Every accepted call gets a room behind the scenes — that's what lets you
+add people later without restarting the call.
+
+```js
+// Caller
+client.calls.on('callAccepted', ({ roomId }) => console.log('connected', roomId));
+client.calls.on('remoteStream', (stream) => { videoEl.srcObject = stream; });
+await client.calls.call('user_456', { callType: 'video' });
+
+// Callee
+client.calls.on('incomingCall', async ({ from, callType, roomId }) => {
+  await client.calls.accept(from, { callType, roomId });
+});
+
+// Mid-call — ring a third person into the SAME call (cap: 9 total)
+client.calls.addToCall('user_789', { callType: 'video' });
+
+client.calls.end('user_456');
+```
+
+## Live streaming (broadcast to many viewers)
+
+Whether you can publish (vs. just watch) is decided by
+the server based on your room role — broadcaster, moderator, and approved
+contributors can publish; plain viewers are subscribe-only.
+
+```js
+const { role } = await client.streaming.join(roomId, myUserId);
+
+client.streaming.on('trackSubscribed', ({ track, participant }) => {
+  const el = document.createElement(track.kind === 'video' ? 'video' : 'audio');
+  track.attach(el);
+  container.appendChild(el);
+});
+
+// ...later
+await client.streaming.leave();
+```
+
+## Live chat + raise hand
+
+Ephemeral —  Live, nothing is saved server-side.
+
+```js
+client.chat.on('message', ({ fromUserId, text }) => renderMessage(fromUserId, text));
+client.chat.send(roomId, 'hello!');
+
+client.chat.raiseHand(roomId);
+
+// Broadcaster side
+client.chat.on('handRaised', ({ userId }) => showRaisedHand(userId));
+client.chat.approveContributor(roomId, userId);
+```
+
+## Voice notes & call recordings
+
+```js
+const recorder = new MediaRecorder(stream);
+const chunks = [];
+recorder.ondataavailable = (e) => chunks.push(e.data);
+recorder.onstop = async () => {
+  const blob = new Blob(chunks, { type: 'audio/webm' });
+  await client.mediaClips.upload(blob, {
+    type: 'voice_note',
+    mediaType: 'audio',
+    fromUserId: myUserId,
+    roomId, // or toUserId for a DM
+  });
+};
+```
+
+## Cleanup
+
+```js
+client.disconnect();
+```

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@anonotf/connect",
+  "version": "0.1.0",
+  "description": "Client SDK for AnonOtF — calls, group calls, live streaming, chat, and voice notes.",
+  "main": "src/index.js",
+  "type": "module",
+  "files": ["src"],
+  "keywords": ["video-call", "voice-call", "live-streaming", "chat", "sdk"],
+  "license": "MIT",
+  "dependencies": {
+    "socket.io-client": "^4.7.0",
+    "livekit-client": "^2.0.0"
+  },
+  "peerDependencies": {},
+  "engines": {
+    "node": ">=16"
+  }
+}

package/src/calls.js

@@ -0,0 +1,193 @@
+// src/calls.js
+//
+// Wraps the raw WebRTC RTCPeerConnection + the server's call-user /
+// accept-call / signal / add-to-call socket events. A developer using
+// this module never creates an RTCPeerConnection or handles an ICE
+// candidate themselves — they call .call(), .accept(), .addToCall(),
+// and listen for simple events like 'remoteStream'.
+//
+// IMPORTANT: every call (even a plain 1-on-1) gets a backing room on
+// the server the moment it's accepted — that's what makes
+// .addToCall() possible later without restarting anything. This
+// module doesn't need to know that; it just reacts to whatever
+// roomId comes back from the server.
+
+const RTC_CONFIG_DEFAULTS = {
+  iceServers: [{ urls: 'stun:stun.l.google.com:19302' }], // overridden by fetchIceServers() below when available
+};
+
+export class Calls {
+  /**
+   * @param {import('./socket.js').SocketManager} socketManager
+   * @param {object} opts
+   * @param {() => Promise<RTCConfiguration>} [opts.fetchIceServers]
+   *   Optional — call your backend's GET /api/ice and return the
+   *   result here for TURN support behind restrictive networks.
+   *   Falls back to a public STUN-only config if omitted.
+   */
+  constructor(socketManager, { fetchIceServers } = {}) {
+    this._socket = socketManager;
+    this._fetchIceServers = fetchIceServers;
+    this._listeners = new Map(); // event -> Set<handler>, for this module's own public events
+    this._pc = null;             // current RTCPeerConnection, one active call at a time
+    this._localStream = null;
+    this.roomId = null;          // set once a call is accepted — null when idle
+    this._pendingOffer = null;   // offer received before the local peer connection exists yet
+
+    this._socket.on('incoming-call', (data) => this._emit('incomingCall', data));
+    this._socket.on('call-accepted', (data) => this._onCallAccepted(data));
+    this._socket.on('call-declined', (data) => this._emit('callDeclined', data));
+    this._socket.on('call-cancelled', (data) => this._emit('callCancelled', data));
+    this._socket.on('call-ended', (data) => this._teardown('callEnded', data));
+    this._socket.on('call-error', (data) => this._emit('callError', data));
+    this._socket.on('signal', (payload) => this._onSignal(payload));
+  }
+
+  // ---- public event subscription ----
+  on(event, handler) {
+    if (!this._listeners.has(event)) this._listeners.set(event, new Set());
+    this._listeners.get(event).add(handler);
+    return () => this._listeners.get(event)?.delete(handler); // returns an unsubscribe fn
+  }
+
+  _emit(event, data) {
+    this._listeners.get(event)?.forEach((h) => h(data));
+  }
+
+  // ---- outgoing call ----
+  /**
+   * Start a call. Prompts for mic (and camera, if callType is 'video')
+   * via getUserMedia internally — the browser will show its own
+   * permission prompt.
+   */
+  async call(calleeId, { callType = 'audio', callerName } = {}) {
+    await this._ensureLocalStream(callType);
+    this._socket.emit('call-user', { calleeId, callType, callerName });
+  }
+
+  cancelCall(calleeId) {
+    this._socket.emit('call-cancelled', { calleeId });
+    this._cleanupLocal();
+  }
+
+  // ---- incoming call ----
+  async accept(callerId, { callType = 'audio', calleeName, roomId } = {}) {
+    await this._ensureLocalStream(callType);
+    this._socket.emit('accept-call', { callerId, callType, calleeName, roomId });
+  }
+
+  decline(callerId, { calleeName } = {}) {
+    this._socket.emit('decline-call', { callerId, calleeName });
+  }
+
+  // ---- mid-call ----
+  /** Ring a third (or fourth, fifth...) person into the call you're already in. */
+  addToCall(newUserId, { callType = 'audio', callerName } = {}) {
+    if (!this.roomId) throw new Error('[AnonOtFConnect] Not currently in a call');
+    this._socket.emit('add-to-call', { roomId: this.roomId, newUserId, callType, callerName });
+  }
+
+  end(otherPartyId) {
+    this._socket.emit('end-call', { otherParty: otherPartyId });
+    this._teardown('callEnded', { from: 'self' });
+  }
+
+  /** Notify everyone in the call that you've started/stopped a local recording. */
+  notifyRecordingStarted({ mediaType = 'audio', otherParty } = {}) {
+    this._socket.emit('recording-started', this.roomId ? { roomId: this.roomId, mediaType } : { otherParty, mediaType });
+  }
+  notifyRecordingStopped({ otherParty } = {}) {
+    this._socket.emit('recording-stopped', this.roomId ? { roomId: this.roomId } : { otherParty });
+  }
+
+  get localStream() {
+    return this._localStream;
+  }
+
+  // ---- internals ----
+  async _ensureLocalStream(callType) {
+    if (this._localStream) return this._localStream;
+    const constraints = callType === 'video' ? { audio: true, video: true } : { audio: true, video: false };
+    this._localStream = await navigator.mediaDevices.getUserMedia(constraints);
+    this._emit('localStream', this._localStream);
+    return this._localStream;
+  }
+
+  async _ensurePeerConnection() {
+    if (this._pc) return this._pc;
+
+    const config = this._fetchIceServers ? await this._fetchIceServers() : RTC_CONFIG_DEFAULTS;
+    this._pc = new RTCPeerConnection(config);
+
+    this._localStream?.getTracks().forEach((track) => this._pc.addTrack(track, this._localStream));
+
+    this._pc.onicecandidate = (event) => {
+      if (event.candidate) {
+        this._socket.emit('signal', {
+          type: 'ice-candidate',
+          candidate: event.candidate,
+          roomId: this.roomId,
+        });
+      }
+    };
+
+    this._pc.ontrack = (event) => {
+      this._emit('remoteStream', event.streams[0]);
+    };
+
+    this._pc.onconnectionstatechange = () => {
+      this._emit('connectionStateChange', this._pc.connectionState);
+      if (this._pc.connectionState === 'failed' || this._pc.connectionState === 'closed') {
+        this._teardown('callEnded', { reason: this._pc.connectionState });
+      }
+    };
+
+    return this._pc;
+  }
+
+  async _onCallAccepted({ from, roomId, callType }) {
+    this.roomId = roomId;
+    const pc = await this._ensurePeerConnection();
+    const offer = await pc.createOffer();
+    await pc.setLocalDescription(offer);
+    this._socket.emit('signal', { type: 'offer', sdp: offer, roomId, to: roomId ? undefined : from });
+    this._emit('callAccepted', { from, roomId, callType });
+  }
+
+  async _onSignal(payload) {
+    const { type, sdp, candidate, from, roomId } = payload;
+    if (roomId) this.roomId = roomId;
+
+    const pc = await this._ensurePeerConnection();
+
+    if (type === 'offer') {
+      await pc.setRemoteDescription(sdp);
+      const answer = await pc.createAnswer();
+      await pc.setLocalDescription(answer);
+      this._socket.emit('signal', { type: 'answer', sdp: answer, roomId, to: roomId ? undefined : from });
+    } else if (type === 'answer') {
+      await pc.setRemoteDescription(sdp);
+    } else if (type === 'ice-candidate' && candidate) {
+      try {
+        await pc.addIceCandidate(candidate);
+      } catch (err) {
+        // Benign in most cases — candidates can arrive before setRemoteDescription
+        // resolves; the browser just drops the stale ones.
+        this._emit('callError', { message: 'Failed to add ICE candidate', error: err });
+      }
+    }
+  }
+
+  _cleanupLocal() {
+    this._localStream?.getTracks().forEach((t) => t.stop());
+    this._localStream = null;
+    this._pc?.close();
+    this._pc = null;
+    this.roomId = null;
+  }
+
+  _teardown(event, data) {
+    this._cleanupLocal();
+    this._emit(event, data);
+  }
+}

package/src/chat.js

@@ -0,0 +1,54 @@
+// src/chat.js
+//
+// Wraps the ephemeral live-stream chat events plus the raise-hand /
+// contributor-approval flow. Nothing here is persisted server-side —
+// matches how TikTok/Instagram Live chat behaves (no scrollback for
+// someone who joins mid-stream).
+
+export class Chat {
+  constructor(socketManager) {
+    this._socket = socketManager;
+    this._listeners = new Map();
+
+    this._socket.on('stream-chat-message', (data) => this._emit('message', data));
+    this._socket.on('hand-raised', (data) => this._emit('handRaised', data));
+    this._socket.on('hand-lowered', (data) => this._emit('handLowered', data));
+    this._socket.on('contributor-approved', (data) => this._emit('contributorApproved', data));
+    this._socket.on('contributor-revoked', (data) => this._emit('contributorRevoked', data));
+    this._socket.on('you-are-now-contributor', (data) => this._emit('youAreNowContributor', data));
+    this._socket.on('you-are-no-longer-contributor', (data) => this._emit('youAreNoLongerContributor', data));
+  }
+
+  on(event, handler) {
+    if (!this._listeners.has(event)) this._listeners.set(event, new Set());
+    this._listeners.get(event).add(handler);
+    return () => this._listeners.get(event)?.delete(handler);
+  }
+
+  _emit(event, data) {
+    this._listeners.get(event)?.forEach((h) => h(data));
+  }
+
+  /** Send a chat message into a live stream's room. Max 500 chars, rate-limited server-side (5 msgs / 10s). */
+  send(roomId, text) {
+    this._socket.emit('stream-chat-message', { roomId, text });
+  }
+
+  /** Viewer signals wanting to come on-stage / get publish access. */
+  raiseHand(roomId) {
+    this._socket.emit('raise-hand', { roomId });
+  }
+
+  lowerHand(roomId) {
+    this._socket.emit('lower-hand', { roomId });
+  }
+
+  /** Broadcaster/moderator only — server rejects this otherwise. */
+  approveContributor(roomId, targetUserId) {
+    this._socket.emit('approve-contributor', { roomId, targetUserId });
+  }
+
+  revokeContributor(roomId, targetUserId) {
+    this._socket.emit('revoke-contributor', { roomId, targetUserId });
+  }
+}

package/src/index.js

@@ -0,0 +1,78 @@
+// src/index.js
+//
+// Public entry point. This is the only file a developer should ever
+// import from — everything in socket.js / calls.js / etc. is an
+// internal implementation detail they never need to touch directly.
+
+import { SocketManager } from './socket.js';
+import { Calls } from './calls.js';
+import { Rooms } from './rooms.js';
+import { Chat } from './chat.js';
+import { Streaming } from './streaming.js';
+import { MediaClips } from './mediaClips.js';
+
+export class AnonOtFConnect {
+  /**
+   * @param {object} opts
+   * @param {string} opts.serverUrl
+   *   Your AnonOtF server's base URL (e.g. "https://api.yourapp.com").
+   * @param {string} opts.token
+   *   A short-lived JWT minted by YOUR backend via
+   *   POST /api/apps/:appId/socket-token. Never embed your raw
+   *   x-api-key in client-side code — that key can create/delete
+   *   apps and read everything; the socket token is scoped to one
+   *   user and expires.
+   * @param {string} [opts.apiBase]
+   *   Base URL for a REST proxy on YOUR backend (rooms, media clips,
+   *   streaming tokens). Defaults to `${serverUrl}/api`, but most
+   *   real integrations should point this at their OWN backend,
+   *   which then forwards to AnonOtF with the x-api-key attached
+   *   server-side — see README for why.
+   * @param {() => Promise<RTCConfiguration>} [opts.fetchIceServers]
+   *   Optional — return your GET /api/ice response here for TURN
+   *   support. Falls back to public STUN only.
+   */
+  constructor({ serverUrl, token, apiBase, fetchIceServers }) {
+    const resolvedApiBase = apiBase || `${serverUrl.replace(/\/$/, '')}/api`;
+
+    this._socketManager = new SocketManager({ serverUrl, token });
+
+    this.calls = new Calls(this._socketManager, { fetchIceServers });
+    this.rooms = new Rooms(this._socketManager, { apiBase: resolvedApiBase });
+    this.chat = new Chat(this._socketManager);
+    this.streaming = new Streaming({ apiBase: resolvedApiBase });
+    this.mediaClips = new MediaClips({ apiBase: resolvedApiBase });
+  }
+
+  /** Opens the underlying Socket.IO connection. Call once, after constructing. */
+  connect() {
+    this._socketManager.connect();
+    return this;
+  }
+
+  disconnect() {
+    this._socketManager.disconnect();
+  }
+
+  get connected() {
+    return this._socketManager.connected;
+  }
+
+  /** Announce presence and receive the current online-user list back. */
+  register({ name, photo, emoji, about } = {}) {
+    return new Promise((resolve) => {
+      this._socketManager.emit('register', { name, photo, emoji, about }, (onlineUsers) => resolve(onlineUsers));
+    });
+  }
+
+  updateProfile({ name, photo, emoji, about } = {}) {
+    this._socketManager.emit('update-profile', { name, photo, emoji, about });
+  }
+
+  /** Keep presence alive — call roughly every 60-90s while connected. */
+  heartbeat() {
+    this._socketManager.emit('heartbeat');
+  }
+}
+
+export { Calls, Rooms, Chat, Streaming, MediaClips };

package/src/mediaClips.js

@@ -0,0 +1,60 @@
+// src/mediaClips.js
+//
+// Voice notes and call recordings. Upload goes through your backend
+// proxy (apiBase) so the multipart request carries your x-api-key
+// server-side, never in the browser.
+
+export class MediaClips {
+  constructor({ apiBase }) {
+    this._apiBase = apiBase;
+  }
+
+  /**
+   * Upload a recorded clip (from MediaRecorder, for example).
+   * @param {Blob} blob
+   * @param {object} opts
+   * @param {'voice_note'|'call_recording'} opts.type
+   * @param {'audio'|'video'} opts.mediaType
+   * @param {string} opts.fromUserId
+   * @param {string} [opts.roomId]     Room-scoped — provide this OR toUserId, not both
+   * @param {string} [opts.toUserId]   DM-scoped
+   * @param {number} [opts.durationSeconds]
+   */
+  async upload(blob, { type, mediaType, fromUserId, roomId, toUserId, durationSeconds }) {
+    const form = new FormData();
+    form.append('file', blob);
+    form.append('type', type);
+    form.append('mediaType', mediaType);
+    form.append('fromUserId', fromUserId);
+    if (roomId) form.append('roomId', roomId);
+    if (toUserId) form.append('toUserId', toUserId);
+    if (durationSeconds != null) form.append('durationSeconds', String(durationSeconds));
+
+    const res = await fetch(`${this._apiBase}/media-clips`, { method: 'POST', body: form });
+    if (!res.ok) throw new Error(`[AnonOtFConnect] Upload failed: ${res.status}`);
+    return res.json();
+  }
+
+  async listForRoom(roomId, userId) {
+    const res = await fetch(`${this._apiBase}/rooms/${roomId}/media-clips?userId=${encodeURIComponent(userId)}`);
+    if (!res.ok) throw new Error(`[AnonOtFConnect] Failed to list room clips: ${res.status}`);
+    return res.json();
+  }
+
+  async listForDM(otherUserId, userId) {
+    const res = await fetch(`${this._apiBase}/media-clips/dm/${otherUserId}?userId=${encodeURIComponent(userId)}`);
+    if (!res.ok) throw new Error(`[AnonOtFConnect] Failed to list DM clips: ${res.status}`);
+    return res.json();
+  }
+
+  /** Returns a playable URL (the underlying endpoint streams the file once access is verified). */
+  getPlaybackUrl(clipId, userId) {
+    return `${this._apiBase}/media-clips/${clipId}?userId=${encodeURIComponent(userId)}`;
+  }
+
+  async delete(clipId, userId) {
+    const res = await fetch(`${this._apiBase}/media-clips/${clipId}?userId=${encodeURIComponent(userId)}`, { method: 'DELETE' });
+    if (!res.ok) throw new Error(`[AnonOtFConnect] Failed to delete clip: ${res.status}`);
+    return res.json();
+  }
+}

package/src/rooms.js

@@ -0,0 +1,65 @@
+// src/rooms.js
+//
+// Thin wrapper over /api/rooms/* REST endpoints and the join-room /
+// leave-room socket events. REST calls here go through YOUR backend
+// (see note on `apiBase` below) rather than carrying a raw API key
+// in the browser.
+
+export class Rooms {
+  /**
+   * @param {import('./socket.js').SocketManager} socketManager
+   * @param {object} opts
+   * @param {string} opts.apiBase
+   *   Base URL for YOUR backend's proxy of the AnonOtF REST API
+   *   (e.g. "/api/anonotf"). This SDK never sends your raw x-api-key
+   *   from the browser — your backend should hold that key and proxy
+   *   these requests, attaching the key server-side.
+   */
+  constructor(socketManager, { apiBase }) {
+    this._socket = socketManager;
+    this._apiBase = apiBase;
+    this._listeners = new Map();
+
+    this._socket.on('room-joined', (data) => this._emit('joined', data));
+    this._socket.on('user-joined', (data) => this._emit('userJoined', data));
+    this._socket.on('user-left', (data) => this._emit('userLeft', data));
+    this._socket.on('error', (data) => this._emit('error', data));
+  }
+
+  on(event, handler) {
+    if (!this._listeners.has(event)) this._listeners.set(event, new Set());
+    this._listeners.get(event).add(handler);
+    return () => this._listeners.get(event)?.delete(handler);
+  }
+
+  _emit(event, data) {
+    this._listeners.get(event)?.forEach((h) => h(data));
+  }
+
+  /** Join a room over the live socket connection (fastest path, used for calls/streams). */
+  join(roomId) {
+    this._socket.emit('join-room', { roomId });
+  }
+
+  /** Leave whichever room this socket is currently in. */
+  leave() {
+    this._socket.emit('leave-room');
+  }
+
+  /** Create a new room. Goes through your backend proxy, not directly to AnonOtF, to keep the API key server-side. */
+  async create({ roomName, maxParticipants } = {}) {
+    const res = await fetch(`${this._apiBase}/rooms`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ roomName, maxParticipants }),
+    });
+    if (!res.ok) throw new Error(`[AnonOtFConnect] Failed to create room: ${res.status}`);
+    return res.json();
+  }
+
+  async listParticipants(roomId) {
+    const res = await fetch(`${this._apiBase}/rooms/${roomId}/participants`);
+    if (!res.ok) throw new Error(`[AnonOtFConnect] Failed to list participants: ${res.status}`);
+    return res.json();
+  }
+}

package/src/socket.js

@@ -0,0 +1,80 @@
+// src/socket.js
+//
+// Internal — not exported from the package. Every other module
+// (calls.js, rooms.js, chat.js) gets a reference to this and calls
+// .emit()/.on() through it, rather than touching socket.io-client
+// directly. This is the one place that knows the actual event names
+// the AnonOtF server expects, so if those ever change, only this
+// file (plus whichever module uses that specific event) needs an edit.
+
+import { io } from 'socket.io-client';
+
+export class SocketManager {
+  /**
+   * @param {object} opts
+   * @param {string} opts.serverUrl   Your AnonOtF server's base URL (e.g. https://api.yourapp.com)
+   * @param {string} opts.token       A short-lived JWT minted by YOUR backend via
+   *                                  POST /api/apps/:appId/socket-token — never
+   *                                  put your raw x-api-key in client-side code.
+   */
+  constructor({ serverUrl, token }) {
+    if (!serverUrl) throw new Error('[AnonOtFConnect] serverUrl is required');
+    if (!token) throw new Error('[AnonOtFConnect] token is required (mint one server-side via POST /api/apps/:appId/socket-token)');
+
+    this.serverUrl = serverUrl;
+    this.token = token;
+    this.socket = null;
+    this._listeners = new Map(); // event -> Set<handler>, replayed onto socket.io-client on (re)connect
+  }
+
+  connect() {
+    if (this.socket) return this.socket;
+
+    this.socket = io(this.serverUrl, {
+      auth: { token: this.token },
+      transports: ['websocket'],
+      reconnection: true,
+    });
+
+    // Re-attach any handlers that were registered before connect(),
+    // or that need to survive a reconnect (socket.io-client keeps
+    // listeners across reconnects automatically, but we replay here
+    // too so .on() calls made before connect() aren't lost).
+    for (const [event, handlers] of this._listeners) {
+      for (const handler of handlers) this.socket.on(event, handler);
+    }
+
+    return this.socket;
+  }
+
+  on(event, handler) {
+    if (!this._listeners.has(event)) this._listeners.set(event, new Set());
+    this._listeners.get(event).add(handler);
+    if (this.socket) this.socket.on(event, handler);
+  }
+
+  off(event, handler) {
+    this._listeners.get(event)?.delete(handler);
+    if (this.socket) this.socket.off(event, handler);
+  }
+
+  emit(event, payload, callback) {
+    if (!this.socket) {
+      throw new Error(`[AnonOtFConnect] Cannot emit "${event}" before connecting`);
+    }
+    if (typeof callback === 'function') {
+      this.socket.emit(event, payload, callback);
+    } else {
+      this.socket.emit(event, payload);
+    }
+  }
+
+  disconnect() {
+    this.socket?.disconnect();
+    this.socket = null;
+  }
+
+  get connected() {
+    return !!this.socket?.connected;
+  }
+}

package/src/streaming.js

@@ -0,0 +1,90 @@
+// src/streaming.js
+//
+// One-to-many broadcast (live streaming), backed by LiveKit. This is
+// the only module that talks to a server OTHER than your AnonOtF
+// server — once it has a token, the actual audio/video flows browser
+// <-> LiveKit directly, never through your Node server.
+//
+// Token flow: this module calls YOUR backend (apiBase), which in turn
+// calls AnonOtF's POST /api/streams/:roomId/token using your x-api-key
+// server-side. The browser never sees your x-api-key or your LiveKit
+// API secret — only the short-lived per-user token that comes back.
+
+import { Room, RoomEvent, createLocalTracks } from 'livekit-client';
+
+export class Streaming {
+  /**
+   * @param {object} opts
+   * @param {string} opts.apiBase  Base URL for your backend's proxy (see rooms.js for the same pattern)
+   */
+  constructor({ apiBase }) {
+    this._apiBase = apiBase;
+    this._room = null;
+    this._listeners = new Map();
+  }
+
+  on(event, handler) {
+    if (!this._listeners.has(event)) this._listeners.set(event, new Set());
+    this._listeners.get(event).add(handler);
+    return () => this._listeners.get(event)?.delete(handler);
+  }
+
+  _emit(event, data) {
+    this._listeners.get(event)?.forEach((h) => h(data));
+  }
+
+  /**
+   * Join a live stream as a viewer, the broadcaster, or an approved
+   * contributor — the server decides which based on your room role,
+   * you don't pass that in here.
+   */
+  async join(roomId, userId) {
+    const res = await fetch(`${this._apiBase}/streams/${roomId}/token`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ userId }),
+    });
+    if (!res.ok) throw new Error(`[AnonOtFConnect] Failed to get streaming token: ${res.status}`);
+    const { token, url, role } = await res.json();
+
+    this._room = new Room();
+
+    this._room
+      .on(RoomEvent.TrackSubscribed, (track, publication, participant) => {
+        this._emit('trackSubscribed', { track, participant: participant.identity });
+      })
+      .on(RoomEvent.TrackUnsubscribed, (track, publication, participant) => {
+        this._emit('trackUnsubscribed', { track, participant: participant.identity });
+      })
+      .on(RoomEvent.ParticipantConnected, (participant) => {
+        this._emit('viewerJoined', { userId: participant.identity });
+      })
+      .on(RoomEvent.ParticipantDisconnected, (participant) => {
+        this._emit('viewerLeft', { userId: participant.identity });
+      })
+      .on(RoomEvent.Disconnected, () => this._emit('disconnected'));
+
+    await this._room.connect(url, token);
+    this._emit('joined', { roomId, role });
+
+    // Broadcaster/contributor: publish camera+mic immediately. Plain
+    // viewers get canPublish: false server-side, so this is skipped
+    // for them automatically — calling publishTracks would just fail.
+    if (role === 'broadcaster' || role === 'contributor') {
+      const tracks = await createLocalTracks({ audio: true, video: true });
+      await Promise.all(tracks.map((t) => this._room.localParticipant.publishTrack(t)));
+      this._emit('publishing', { roomId });
+    }
+
+    return { role };
+  }
+
+  async leave() {
+    await this._room?.disconnect();
+    this._room = null;
+  }
+
+  get room() {
+    return this._room;
+  }
+}