@strevokit/meeting-sdk 0.6.0 → 0.8.0

package/docs/api-reference.md

@@ -30,6 +30,8 @@ Throws synchronously:
 | `realtimeUrl` | `string` | yes | Realtime endpoint base URL, `wss://host[:port]`. `ws://` is accepted only for `localhost` and `127.0.0.1`. No path, query, fragment, or credentials. |
 | `joinTimeoutMs` | `number` | no | How long `join()` waits for admission before rejecting with `join_timeout`. Integer, 1000–60000. Default 15000. |
 | `logger` | `MeetingLogger` | no | Diagnostics sink. Receives short messages and allow-listed fields only. |
+| `getJoinToken` | `() => Promise<string>` | no | Called when automatic recovery needs a fresh join token and the in-memory token cannot be used. Resolve with a token your backend issued for the same participant; reject to end recovery. Kept in memory only and never logged. |
+| `reconnectWindowMs` | `number` | no | Continuous unsuccessful recovery budget in milliseconds. Default `120000`; values outside `1000`–`600000` are clamped. |
 
 ### `MeetingLogger`
 
@@ -129,6 +131,12 @@ microphone) to `enableCamera()` or `unmute()`. Without one, the browser's defaul
 | Muted, with another device kept open | `unmute({ deviceId })` | The chosen microphone is captured and announced; the previous one is released. |
 | Unmuted with another device | `unmute({ deviceId })` | Switches in place, as for the camera. |
 
+If the camera or an unmuted microphone ends on its own, and another device of that kind is listed, capture continues
+on that device. `local_media_changed` fires with the kind still on and the new stream. The change is not announced as
+stopped or started. When no other device can be opened, the kind turns off and is announced. A muted microphone that
+ends is not replaced and is not unmuted. Calls made while the engine is `reconnecting` reject with `not_joined` and
+do not capture.
+
 If the chosen device is missing, the call rejects with `device_not_found`; if another app is using it, with
 `device_unavailable`. Either way, the device already in use keeps running. A pending call is shared only by calls for
 the same state **and** the same device. Device IDs are never logged. Read the device in use from the track:
@@ -137,7 +145,14 @@ the same state **and** the same device. Device IDs are never logged. Read the de
 ## States: `ConnectionState`
 
 ```ts
-type ConnectionState = "idle" | "connecting" | "joining" | "joined" | "leaving" | "closed";
+type ConnectionState =
+  | "idle"
+  | "connecting"
+  | "joining"
+  | "joined"
+  | "reconnecting"
+  | "leaving"
+  | "closed";
 ```
 
 | State | Meaning |
@@ -146,6 +161,7 @@ type ConnectionState = "idle" | "connecting" | "joining" | "joined" | "leaving"
 | `connecting` | Connecting and presenting the join token. |
 | `joining` | The token was accepted; waiting for the participant list. |
 | `joined` | In the meeting. Media methods are available. |
+| `reconnecting` | Previously joined; automatic recovery of the meeting-service connection is in progress. Success returns to `joined` (same self identity; `joined` is not re-emitted). |
 | `leaving` | `leave()` was called; waiting for the platform to confirm. |
 | `closed` | Finished. The engine cannot be reused; create a new one with a new token. |
 
@@ -272,6 +288,8 @@ it; otherwise `null`.
 | `interrupted` | The connection dropped after working; it may recover on its own. |
 | `failed` | The connection could not be set up or did not recover. An `error` event with `media_connection_failed` accompanies it. Rejoining starts a new attempt. |
 
+While a peer link is alive, the SDK may periodically report aggregated media-health samples (RTT, jitter, loss, bitrates, and path/connectivity indicators) to the realtime service for operator diagnostics. Sampling failures never tear down media.
+
 ### `ParticipantLeftReason`
 
 | Reason | Meaning |

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/vanilla.html

@@ -20,7 +20,7 @@
       // With a bundler, import from "@strevokit/meeting-sdk" instead.
       import { createMeetingEngine, MeetingError } from "./node_modules/@strevokit/meeting-sdk/dist/index.js";
 
-      // Ask your backend for a join token; it calls the Strevokit API with its credential.
+      // Ask your backend for a join token (see backend-integration.md and ../backend-api.md).
       const { token } = await fetch("/my-backend/join-token", { method: "POST" }).then((r) => r.json());
 
       const engine = createMeetingEngine({ token, realtimeUrl: "wss://realtime.example.com" });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@strevokit/meeting-sdk",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Embed Strevokit meetings in your web product.",
   "license": "Apache-2.0",
   "repository": {