@strevokit/meeting-sdk 0.0.0-stage → 0.8.0

package/docs/backend-api.md

@@ -0,0 +1,370 @@
+# Backend API for meeting clients
+
+Your backend prepares each meeting with the Strevokit HTTP API, then mints a short-lived **join token** for the
+browser. The meeting SDK only ever receives that token — never your API credential.
+
+Base URL in the examples: `https://api.example.com` (replace with your Strevokit API host).
+
+## Auth
+
+Every route below requires:
+
+```http
+Authorization: Bearer <STREVOKIT_API_CREDENTIAL>
+Content-Type: application/json
+```
+
+Keep `STREVOKIT_API_CREDENTIAL` on the server only. Never put it in browser code, `VITE_*` / `NEXT_PUBLIC_*`
+variables, or mobile apps.
+
+Meeting and participant identifiers in paths and JSON are opaque `public_id` values (26-character Crockford ULIDs).
+Responses never include numeric internal database ids.
+
+## Route index
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| `POST` | `/v1/embed-origins` | Allow-list a browser origin that may join |
+| `GET` | `/v1/embed-origins` | List allow-listed origins |
+| `DELETE` | `/v1/embed-origins/{public_id}` | Remove an allow-listed origin |
+| `POST` | `/v1/meetings` | Create a meeting |
+| `GET` | `/v1/meetings/{public_id}` | Fetch a meeting |
+| `POST` | `/v1/meetings/{public_id}/participants` | Authorize (register) a participant |
+| `POST` | `/v1/meetings/{public_id}/join-token` | Mint a join token for one participant |
+| `POST` | `/v1/meetings/{public_id}/end` | End the meeting for everyone |
+
+## Integration sequence
+
+1. **Allow-list your app origin** (`POST /v1/embed-origins`) once per environment (for example `https://app.example.com`).
+   Joins from other origins fail with `origin_not_allowed` at the realtime handshake.
+2. **Create a meeting** (`POST /v1/meetings`) when your product starts a session. Store `data.public_id`.
+3. **Authorize each person** (`POST /v1/meetings/{public_id}/participants`) as `host` or `participant`. Store each
+   `data.public_id` (the participant public id).
+4. **Mint a join token** (`POST /v1/meetings/{public_id}/join-token`) when that user opens the meeting page. Return
+   only `data.token` to the browser.
+5. **Join in the browser** with `createMeetingEngine({ token, realtimeUrl })` (see the [README](../README.md)).
+
+Optional later: `GET /v1/meetings/{public_id}` to read status; `POST /v1/meetings/{public_id}/end` to end from your
+backend.
+
+---
+
+## POST /v1/embed-origins
+
+Register one browser origin that may open meetings.
+
+```http
+POST /v1/embed-origins
+Authorization: Bearer <STREVOKIT_API_CREDENTIAL>
+Content-Type: application/json
+```
+
+```json
+{ "origin": "https://app.example.com" }
+```
+
+`origin` must be a full web origin (`http` or `https`, host, optional non-default port). No path, query, fragment, or
+wildcards.
+
+**Success:** `201` when newly inserted, `200` when the same origin already exists.
+
+```json
+{
+  "data": {
+    "public_id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
+    "origin": "https://app.example.com",
+    "created_at": "2026-09-24T12:00:00.000000Z"
+  }
+}
+```
+
+Also available: `GET /v1/embed-origins` (list) and `DELETE /v1/embed-origins/{public_id}` (`204` on success). An empty
+allow-list means joins fail closed until you add at least one origin.
+
+---
+
+## POST /v1/meetings
+
+Create a meeting.
+
+```http
+POST /v1/meetings
+Authorization: Bearer <STREVOKIT_API_CREDENTIAL>
+Content-Type: application/json
+Idempotency-Key: <optional opaque string>
+```
+
+```json
+{
+  "type": "one_to_one",
+  "max_participants": 2,
+  "recording_requested": false,
+  "external_reference": "session_9876",
+  "empty_timeout_seconds": 300
+}
+```
+
+| Field | Required | Notes |
+|-------|----------|--------|
+| `type` | yes | `one_to_one` or `one_to_many` |
+| `max_participants` | yes | `2` for `one_to_one`; `3`–`50` for `one_to_many` |
+| `recording_requested` | no | Default `false`. Alias `recording` is accepted |
+| `scheduled_start` | no | ISO-8601 with timezone; stored as `scheduled_at` |
+| `metadata` | no | Flat JSON object; keep it small |
+| `external_reference` | no | Your own id, 1–255 characters when present; echoed unchanged |
+| `empty_timeout_seconds` | no | `60`–`86400`; default `300`. Idle empty meetings end after this many seconds |
+
+Do not send `tenant_id`, numeric `id`, or a client-chosen media mode — the platform selects delivery.
+
+Optional `Idempotency-Key` (≤255 characters): same key + same body replays the first response; same key + different
+body returns `409` `idempotency_conflict`.
+
+**Success:** `201 Created` (idempotent replay may return the original status).
+
+```json
+{
+  "data": {
+    "public_id": "01JB2Q8ABCDEF01234567890AB",
+    "external_reference": "session_9876",
+    "type": "one_to_one",
+    "max_participants": 2,
+    "recording_requested": false,
+    "recording_allowed": false,
+    "status": "created",
+    "scheduled_at": null,
+    "started_at": null,
+    "ended_at": null,
+    "end_reason": null,
+    "empty_timeout_seconds": 300,
+    "metadata": null,
+    "created_at": "2026-09-22T12:00:00+00:00",
+    "updated_at": "2026-09-22T12:00:00+00:00"
+  }
+}
+```
+
+The response may also include platform-selected fields (for example how media is delivered). Store `public_id` for
+later calls.
+
+| Case | HTTP | `error.code` |
+|------|------|--------------|
+| Missing or invalid credential | 401 | `unauthorized` |
+| Bad or missing fields | 422 | `validation_failed` |
+| Idempotency key reused with a different body | 409 | `idempotency_conflict` |
+| Rate limited | 429 | `rate_limited` (+ `Retry-After`) |
+| Suspended tenant | 403 | `forbidden` |
+
+---
+
+## GET /v1/meetings/{public_id}
+
+Fetch the meeting resource for your tenant (same shape as create). Missing or other-tenant ids return `404`
+`meeting_not_found`.
+
+---
+
+## POST /v1/meetings/{public_id}/participants
+
+Authorize (register) a participant on a meeting. Call once per person who may join.
+
+```http
+POST /v1/meetings/{public_id}/participants
+Authorization: Bearer <STREVOKIT_API_CREDENTIAL>
+Content-Type: application/json
+Idempotency-Key: <optional opaque string>
+```
+
+```json
+{
+  "external_user_id": "user_42",
+  "display_name": "Alex",
+  "role": "host"
+}
+```
+
+| Field | Required | Notes |
+|-------|----------|--------|
+| `external_user_id` | yes | Your user id within this meeting (1–255 chars; not whitespace-only) |
+| `display_name` | yes | Shown name (1–255 chars; not whitespace-only) |
+| `role` | yes | `host` or `participant` |
+
+**Upsert:** the same `external_user_id` on the same meeting returns the same participant `public_id`, updates name and
+role, and does not consume an extra capacity slot. A **new** identity is rejected with `422`
+`participant_limit_exceeded` when the meeting already has `max_participants` distinct people.
+
+**Display names:** Pass the name users should see in the roster as `display_name` when you authorize. The join-token
+route and the browser (including this SDK) do not accept a name. If no usable name is available at join, the UI shows
+**Guest**. To rename someone, re-authorize with the same `external_user_id` and a new `display_name`, then mint a new
+join token and have them join again.
+
+Optional `Idempotency-Key` behaves like create (same key + different body → `409` `idempotency_conflict`).
+
+**Success:** `201` on first insert, `200` on upsert of an existing identity (idempotent replay returns the stored
+status and body).
+
+```json
+{
+  "data": {
+    "public_id": "01JQ4ABCDEF01234567890ABCD",
+    "external_user_id": "user_42",
+    "display_name": "Alex",
+    "role": "host",
+    "status": "invited"
+  }
+}
+```
+
+| Case | HTTP | `error.code` |
+|------|------|--------------|
+| Missing or invalid credential | 401 | `unauthorized` |
+| Bad or missing fields | 422 | `validation_failed` |
+| Meeting missing or other tenant | 404 | `meeting_not_found` |
+| Meeting already `ended` | 409 | `meeting_ended` |
+| Meeting `cancelled` / `failed` | 403 | `forbidden` |
+| New identity over capacity | 422 | `participant_limit_exceeded` |
+| Idempotency conflict | 409 | `idempotency_conflict` |
+| Rate limited | 429 | `rate_limited` (+ `Retry-After`) |
+
+---
+
+## POST /v1/meetings/{public_id}/join-token
+
+Mint a short-lived join token for one authorized participant. Mint a **new** token for every join (including rejoin
+after leave). Do **not** send `Idempotency-Key` — each successful call issues a new token.
+
+```http
+POST /v1/meetings/{public_id}/join-token
+Authorization: Bearer <STREVOKIT_API_CREDENTIAL>
+Content-Type: application/json
+```
+
+```json
+{ "participant_public_id": "01JQ4ABCDEF01234567890ABCD" }
+```
+
+| Field | Required | Notes |
+|-------|----------|--------|
+| `participant_public_id` | yes | From authorize; must belong to this meeting |
+
+Do not send `role`, `display_name`, `tenant_id`, or numeric `id`. Role and display name come from the authorized
+participant row.
+
+**Success:** `201 Created`
+
+```json
+{
+  "data": {
+    "token": "<compact JWT>",
+    "expires_at": "2026-09-24T15:05:00Z",
+    "expires_in": 300
+  }
+}
+```
+
+Default TTL is 300 seconds. Treat `token` like a secret: do not log it, put it in URLs, or cache it (`Cache-Control:
+no-store` on your app response). Return only the token string to the browser.
+
+| Case | HTTP | `error.code` |
+|------|------|--------------|
+| Missing or invalid credential | 401 | `unauthorized` |
+| Bad or missing `participant_public_id` | 422 | `validation_failed` |
+| Meeting missing or other tenant | 404 | `meeting_not_found` |
+| Participant missing or not on this meeting | 404 | `participant_not_found` |
+| Meeting already `ended` | 409 | `meeting_ended` |
+| Meeting `cancelled` / `failed` | 403 | `forbidden` |
+| Join-token rate limited | 429 | `rate_limited` (+ `Retry-After`) |
+
+Realtime handshake failures (after you hand the token to the SDK) include `invalid_join_token`, `join_token_expired`,
+and `origin_not_allowed`.
+
+---
+
+## POST /v1/meetings/{public_id}/end
+
+End the meeting for everyone from your backend. Optional `Idempotency-Key`. Success returns the updated meeting
+resource with `status` `ended` and `end_reason` `tenant_api`.
+
+---
+
+## Errors
+
+Error bodies use a stable `error.code` string (and a message). On `429`, honor `Retry-After`. Prefer mapping known
+codes in your backend rather than parsing message text.
+
+## End-to-end example (Node.js)
+
+```ts
+const STREVOKIT_API = "https://api.example.com";
+const API_CREDENTIAL = process.env.STREVOKIT_API_CREDENTIAL!;
+
+async function strevokit(path: string, init: RequestInit = {}) {
+  const response = await fetch(`${STREVOKIT_API}${path}`, {
+    ...init,
+    headers: {
+      Authorization: `Bearer ${API_CREDENTIAL}`,
+      "Content-Type": "application/json",
+      ...(init.headers ?? {}),
+    },
+  });
+  if (!response.ok) throw new Error(`Strevokit ${path} → HTTP ${response.status}`);
+  if (response.status === 204) return null;
+  return response.json();
+}
+
+// Once per environment:
+await strevokit("/v1/embed-origins", {
+  method: "POST",
+  body: JSON.stringify({ origin: "https://app.example.com" }),
+});
+
+// When your product starts a session:
+const { data: meeting } = await strevokit("/v1/meetings", {
+  method: "POST",
+  headers: { "Idempotency-Key": crypto.randomUUID() },
+  body: JSON.stringify({
+    type: "one_to_one",
+    max_participants: 2,
+    external_reference: "booking_123",
+  }),
+});
+
+const { data: host } = await strevokit(`/v1/meetings/${meeting.public_id}/participants`, {
+  method: "POST",
+  body: JSON.stringify({
+    external_user_id: "user_host",
+    display_name: "Alex",
+    role: "host",
+  }),
+});
+
+const { data: guest } = await strevokit(`/v1/meetings/${meeting.public_id}/participants`, {
+  method: "POST",
+  body: JSON.stringify({
+    external_user_id: "user_guest",
+    display_name: "Sam",
+    role: "participant",
+  }),
+});
+
+// When that signed-in user opens the meeting page:
+const { data: issued } = await strevokit(`/v1/meetings/${meeting.public_id}/join-token`, {
+  method: "POST",
+  body: JSON.stringify({ participant_public_id: host.public_id }),
+});
+// Return issued.token to the browser only.
+```
+
+## Hand the token to the SDK
+
+```ts
+import { createMeetingEngine } from "@strevokit/meeting-sdk";
+
+const engine = createMeetingEngine({
+  token, // from your backend
+  realtimeUrl: "wss://realtime.example.com",
+});
+await engine.join();
+```
+
+A longer Express-style proxy that creates, authorizes, and mints is in
+[examples/backend-integration.md](./examples/backend-integration.md).

package/docs/examples/backend-integration.md

@@ -0,0 +1,103 @@
+# Backend integration (create, authorize, join token)
+
+The meeting SDK needs a join token for each participant. Tokens are short-lived and single-use. Only your backend can
+mint them, because minting needs your Strevokit API credential.
+
+Before minting, your backend usually **creates** the meeting and **authorizes** participants. The full HTTP reference
+(methods, paths, bodies, errors) is in [Backend API](../backend-api.md).
+
+**Keep the API credential on your server.** Never ship it in browser code, environment variables exposed to the
+browser (such as `VITE_*` or `NEXT_PUBLIC_*`), or mobile apps. The browser only ever receives the join token.
+
+## Flow
+
+1. (Once) Allow-list the origin that hosts your meeting page (`POST /v1/embed-origins`).
+2. When your product starts a session, create a meeting (`POST /v1/meetings`) and authorize each person
+   (`POST /v1/meetings/{public_id}/participants`).
+3. The signed-in user opens a meeting page in your app.
+4. The page asks your backend for a join token.
+5. Your backend checks that this user may join, then calls `POST /v1/meetings/{public_id}/join-token`.
+6. Your backend returns only the token to the page, which passes it to `createMeetingEngine({ token, realtimeUrl })`.
+
+## Example (Node.js with Express)
+
+```ts
+import express from "express";
+
+const app = express();
+app.use(express.json());
+
+const STREVOKIT_API = "https://api.example.com"; // your Strevokit API base URL
+const API_CREDENTIAL = process.env.STREVOKIT_API_CREDENTIAL; // server-side secret, never sent to browsers
+
+const strevokitHeaders = {
+  Authorization: `Bearer ${API_CREDENTIAL}`,
+  "Content-Type": "application/json",
+};
+
+// Once per environment (run from a setup script or admin path):
+// await fetch(`${STREVOKIT_API}/v1/embed-origins`, {
+//   method: "POST",
+//   headers: strevokitHeaders,
+//   body: JSON.stringify({ origin: "https://app.example.com" }),
+// });
+
+app.post("/api/meetings", requireSignedInUser, async (req, res) => {
+  const response = await fetch(`${STREVOKIT_API}/v1/meetings`, {
+    method: "POST",
+    headers: { ...strevokitHeaders, "Idempotency-Key": crypto.randomUUID() },
+    body: JSON.stringify({
+      type: "one_to_one",
+      max_participants: 2,
+      external_reference: req.body.bookingId,
+    }),
+  });
+  if (!response.ok) return res.sendStatus(502);
+  const { data: meeting } = await response.json();
+
+  const hostResponse = await fetch(`${STREVOKIT_API}/v1/meetings/${meeting.public_id}/participants`, {
+    method: "POST",
+    headers: strevokitHeaders,
+    body: JSON.stringify({
+      external_user_id: String(req.user.id),
+      display_name: req.user.displayName,
+      role: "host",
+    }),
+  });
+  if (!hostResponse.ok) return res.sendStatus(502);
+  const { data: host } = await hostResponse.json();
+
+  // Persist meeting.public_id and host.public_id in your own database, keyed by your booking / room.
+  res.status(201).json({ meetingPublicId: meeting.public_id, participantPublicId: host.public_id });
+});
+
+app.post("/api/meetings/:meetingId/join-token", requireSignedInUser, async (req, res) => {
+  // Your own authorization: may this user join this meeting, and as which Strevokit participant?
+  const participantPublicId = await participantFor(req.user, req.params.meetingId);
+  if (!participantPublicId) return res.sendStatus(403);
+
+  const response = await fetch(
+    `${STREVOKIT_API}/v1/meetings/${encodeURIComponent(req.params.meetingId)}/join-token`,
+    {
+      method: "POST",
+      headers: strevokitHeaders,
+      body: JSON.stringify({ participant_public_id: participantPublicId }),
+    },
+  );
+  if (!response.ok) return res.sendStatus(502);
+
+  const { data } = await response.json(); // { token, expires_at, expires_in }
+  res.set("Cache-Control", "no-store").json({ token: data.token });
+});
+```
+
+`requireSignedInUser` and `participantFor` stand for your own session and authorization code.
+
+## Notes
+
+- Create and authorize before the first join-token call; join-token needs an existing participant `public_id`.
+- Pass a real `display_name` on authorize; join-token cannot set or change it. If the UI shows **Guest**, authorize
+  used a missing or placeholder name, or that step was skipped.
+- Mint a new token for every join, including rejoining after `leave()` / `dispose()`.
+- Send the join-token response with `Cache-Control: no-store` so the token isn't cached.
+- Don't log the token or put it in a URL. The SDK keeps it in memory only.

package/docs/examples/react.tsx

@@ -0,0 +1,144 @@
+// A minimal React integration: one hook that owns the engine, plus a few buttons. Not a UI kit.
+import { useEffect, useReducer, useRef, useState } from "react";
+import {
+  createMeetingEngine,
+  MeetingError,
+  type ConnectionState,
+  type MeetingEngine,
+} from "@strevokit/meeting-sdk";
+
+export function useMeetingEngine(token: string, realtimeUrl: string) {
+  const [engine, setEngine] = useState<MeetingEngine | null>(null);
+  const [state, setState] = useState<ConnectionState>("idle");
+  const [error, setError] = useState<MeetingError | null>(null);
+  const [, refresh] = useReducer((n: number) => n + 1, 0);
+
+  useEffect(() => {
+    setError(null);
+    setState("idle");
+    let next: MeetingEngine;
+    try {
+      next = createMeetingEngine({ token, realtimeUrl });
+    } catch (reason) {
+      if (!(reason instanceof MeetingError)) throw reason;
+      setError(reason);
+      setEngine(null);
+      return;
+    }
+    const unsubscribe = [
+      next.on("state_changed", (event) => setState(event.state)),
+      next.on("joined", refresh),
+      next.on("participant_joined", refresh),
+      next.on("participant_left", refresh),
+      next.on("participant_media_changed", refresh),
+      next.on("local_media_changed", refresh),
+      next.on("error", (event) => setError(event.error)),
+      next.on("closed", (event) => setError(event.error ?? null)),
+    ];
+    setEngine(next);
+    next.join().catch((reason: unknown) => {
+      if (reason instanceof MeetingError && reason.code !== "join_cancelled") setError(reason);
+    });
+    return () => {
+      for (const off of unsubscribe) off();
+      next.dispose();
+    };
+  }, [token, realtimeUrl]);
+
+  return { engine, state, error };
+}
+
+function SelfPreview({ stream }: { stream: MediaStream | null }) {
+  const ref = useRef<HTMLVideoElement>(null);
+  useEffect(() => {
+    if (ref.current) ref.current.srcObject = stream;
+  }, [stream]);
+  return <video ref={ref} autoPlay muted playsInline width={320} />;
+}
+
+function RemoteParticipant({ engine, participantId }: { engine: MeetingEngine; participantId: string }) {
+  const video = useRef<HTMLVideoElement>(null);
+  const audio = useRef<HTMLAudioElement>(null);
+  const [status, setStatus] = useState(() => engine.mediaConnectionStatus(participantId));
+
+  useEffect(() => {
+    const attach = () => {
+      const media = engine.remoteMedia(participantId);
+      if (video.current) video.current.srcObject = media.camera;
+      if (audio.current) audio.current.srcObject = media.microphone;
+    };
+    attach();
+    const unsubscribe = [
+      engine.on("remote_media_changed", (event) => {
+        if (event.participantId === participantId) attach();
+      }),
+      engine.on("media_connection_changed", (event) => {
+        if (event.participantId === participantId) setStatus(event.status);
+      }),
+    ];
+    return () => {
+      for (const off of unsubscribe) off();
+    };
+  }, [engine, participantId]);
+
+  return (
+    <figure>
+      <video ref={video} autoPlay muted playsInline width={320} />
+      <audio ref={audio} autoPlay />
+      <figcaption>{status === "interrupted" ? "Connection lost — reconnecting…" : status}</figcaption>
+    </figure>
+  );
+}
+
+export function Meeting({ token, realtimeUrl }: { token: string; realtimeUrl: string }) {
+  const { engine, state, error } = useMeetingEngine(token, realtimeUrl);
+  if (!engine) return error ? <p role="alert">{error.message}</p> : null;
+
+  const media = engine.localMediaState;
+  const run = (action: () => Promise<void>) => {
+    action().catch((reason: unknown) => {
+      if (reason instanceof MeetingError) alert(reason.message);
+    });
+  };
+
+  return (
+    <section>
+      <p>{error ? error.message : state}</p>
+      <SelfPreview stream={engine.localMedia.camera} />
+      <div role="group" aria-label="Media controls">
+        <button
+          aria-pressed={media.camera}
+          disabled={state !== "joined"}
+          onClick={() => run(() => (media.camera ? engine.disableCamera() : engine.enableCamera()))}
+        >
+          Camera
+        </button>
+        <button
+          aria-pressed={media.microphone}
+          disabled={state !== "joined"}
+          onClick={() => run(() => (media.microphone ? engine.mute() : engine.unmute()))}
+        >
+          Microphone
+        </button>
+        <button
+          aria-pressed={media.screen}
+          disabled={state !== "joined"}
+          onClick={() => run(() => (media.screen ? engine.stopScreenShare() : engine.startScreenShare()))}
+        >
+          Share screen
+        </button>
+        <button disabled={state !== "joined"} onClick={() => void engine.leave()}>
+          Leave
+        </button>
+      </div>
+      <ul>
+        {engine.participants.map((participant) => (
+          <li key={participant.id}>
+            {participant.displayName ?? participant.id} ({participant.role})
+            <RemoteParticipant engine={engine} participantId={participant.id} />
+          </li>
+        ))}
+      </ul>
+    </section>
+  );
+}