@voltkit-rtc/client 0.6.1 → 0.7.0

package/dist/esm/network.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Network quality, from the media transports' WebRTC statistics: round-trip
+ * time, packet loss in the worse direction, and the bandwidth the browser
+ * estimates it can use. A level sums them up for a UI, with documented
+ * thresholds (docs/SDK-CONTRACT.md, "Network quality").
+ *
+ * The parsers are pure, like stats.ts: they take the stats objects of a
+ * getStats() report and the previous sample's counters.
+ */
+import type { StatsEntry } from './stats.js';
+export type NetworkQualityLevel = 'excellent' | 'good' | 'poor' | 'bad';
+export interface NetworkQuality {
+    level: NetworkQualityLevel;
+    /** Round trip to the media server, in ms; null before the browser has measured one. */
+    rttMs: number | null;
+    /** Packets lost over the last interval, in percent, the worse of sending and receiving; null when nothing moved. */
+    lossPct: number | null;
+    /** The bandwidth the browser estimates it can use, in kbps: upload while publishing, else download when reported. */
+    availableKbps: number | null;
+}
+/** How often the transports are sampled while someone listens for `networkQuality`. */
+export declare const NETWORK_QUALITY_INTERVAL_MS = 3000;
+/**
+ * The thresholds: the first level whose round trip and loss are both below
+ * its limits, else `bad`. An unknown value does not lower the level.
+ */
+export declare const NETWORK_QUALITY_LEVELS: readonly {
+    level: Exclude<NetworkQualityLevel, 'bad'>;
+    rttMsBelow: number;
+    lossPctBelow: number;
+}[];
+export declare function networkLevel(rttMs: number | null, lossPct: number | null): NetworkQualityLevel;
+/** One transport's counters at one moment; the next sample's deltas are taken against it. */
+export interface TransportSample {
+    /** The selected candidate pair's current round trip, in ms. */
+    rttMs: number | null;
+    /** The round trip RTCP reports from the server, in ms (a fallback). */
+    remoteRttMs: number | null;
+    /** RTP packets sent, and how many of them the server reported lost. */
+    packetsSent: number;
+    remotePacketsLost: number;
+    /** RTP packets received, and how many were lost on the way. */
+    packetsReceived: number;
+    packetsLost: number;
+    /** Bits per second the browser estimates it can send / receive. */
+    availableOutgoing: number | null;
+    availableIncoming: number | null;
+}
+/** The counters of one transport's report. */
+export declare function readTransportStats(report: Iterable<StatsEntry>): TransportSample;
+/**
+ * The quality now, from each transport's sample and the one before it (by
+ * key; a transport that is new, or whose counters went backwards, gives no
+ * loss for this interval). `publishing` picks the upload estimate.
+ */
+export declare function networkQualityOf(current: ReadonlyMap<string, TransportSample>, previous: ReadonlyMap<string, TransportSample>, publishing: boolean): NetworkQuality;
+/**
+ * Samples the transports on a timer while wanted and reports each interval.
+ * The first report comes as soon as a round trip is known; loss needs the
+ * previous interval's counters, so it is null until the second.
+ */
+export declare class NetworkQualityWatch {
+    /** Each live transport's report, by a key that changes when the transport does. */
+    private readonly sample;
+    private readonly publishing;
+    private readonly report;
+    private readonly intervalMs;
+    private timer;
+    private previous;
+    private sampling;
+    private generation;
+    constructor(
+    /** Each live transport's report, by a key that changes when the transport does. */
+    sample: () => Promise<Map<string, Iterable<StatsEntry>>>, publishing: () => boolean, report: (quality: NetworkQuality) => void, intervalMs?: number);
+    get running(): boolean;
+    /** Start or stop sampling. Safe to call as often as anything changes. */
+    set(wanted: boolean): void;
+    private tick;
+}
+//# sourceMappingURL=network.d.ts.map

package/dist/esm/network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../src/network.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAE7C,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,MAAM,GAAG,MAAM,GAAG,KAAK,CAAC;AAExE,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,mBAAmB,CAAC;IAC3B,uFAAuF;IACvF,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,oHAAoH;IACpH,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,qHAAqH;IACrH,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,uFAAuF;AACvF,eAAO,MAAM,2BAA2B,OAAO,CAAC;AAEhD;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS;IAAE,KAAK,EAAE,OAAO,CAAC,mBAAmB,EAAE,KAAK,CAAC,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,YAAY,EAAE,MAAM,CAAA;CAAE,EAIrI,CAAC;AAEF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,mBAAmB,CAK9F;AAED,6FAA6F;AAC7F,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,uEAAuE;IACvE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;IACpB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,+DAA+D;IAC/D,eAAe,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,mEAAmE;IACnE,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAClC;AAKD,8CAA8C;AAC9C,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,eAAe,CA8ChF;AAID;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,EAC7C,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,EAC9C,UAAU,EAAE,OAAO,GAClB,cAAc,CA4BhB;AAED;;;;GAIG;AACH,qBAAa,mBAAmB;IAO5B,mFAAmF;IACnF,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAV7B,OAAO,CAAC,KAAK,CAA+C;IAC5D,OAAO,CAAC,QAAQ,CAAsC;IACtD,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,UAAU,CAAK;;IAGrB,mFAAmF;IAClE,MAAM,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,CAAC,CAAC,EACxD,UAAU,EAAE,MAAM,OAAO,EACzB,MAAM,EAAE,CAAC,OAAO,EAAE,cAAc,KAAK,IAAI,EACzC,UAAU,SAA8B;IAG3D,IAAI,OAAO,IAAI,OAAO,CAErB;IAED,yEAAyE;IACzE,GAAG,CAAC,MAAM,EAAE,OAAO,GAAG,IAAI;YAYZ,IAAI;CAsBnB"}

package/dist/esm/network.js

@@ -0,0 +1,183 @@
+/** How often the transports are sampled while someone listens for `networkQuality`. */
+export const NETWORK_QUALITY_INTERVAL_MS = 3000;
+/**
+ * The thresholds: the first level whose round trip and loss are both below
+ * its limits, else `bad`. An unknown value does not lower the level.
+ */
+export const NETWORK_QUALITY_LEVELS = [
+    { level: 'excellent', rttMsBelow: 150, lossPctBelow: 1 },
+    { level: 'good', rttMsBelow: 300, lossPctBelow: 3 },
+    { level: 'poor', rttMsBelow: 500, lossPctBelow: 8 },
+];
+export function networkLevel(rttMs, lossPct) {
+    for (const l of NETWORK_QUALITY_LEVELS) {
+        if ((rttMs === null || rttMs < l.rttMsBelow) && (lossPct === null || lossPct < l.lossPctBelow))
+            return l.level;
+    }
+    return 'bad';
+}
+const num = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : 0);
+const optNum = (value) => (typeof value === 'number' && Number.isFinite(value) ? value : undefined);
+/** The counters of one transport's report. */
+export function readTransportStats(report) {
+    const entries = [...report].filter((e) => typeof e === 'object' && e !== null);
+    const byId = new Map();
+    for (const entry of entries)
+        if (typeof entry.id === 'string')
+            byId.set(entry.id, entry);
+    // The candidate pair in use: the transport's selected one, else a nominated
+    // succeeded pair (Firefox reports no transport entry).
+    let pair;
+    for (const transport of entries.filter((e) => e.type === 'transport')) {
+        const selected = typeof transport.selectedCandidatePairId === 'string' ? byId.get(transport.selectedCandidatePairId) : undefined;
+        if (selected) {
+            pair = selected;
+            break;
+        }
+    }
+    if (!pair) {
+        const pairs = entries.filter((e) => e.type === 'candidate-pair');
+        pair = pairs.find((p) => p.nominated === true && p.state === 'succeeded') ?? pairs.find((p) => p.selected === true);
+    }
+    const rtt = optNum(pair?.currentRoundTripTime);
+    let remoteRtt;
+    let packetsSent = 0;
+    let remotePacketsLost = 0;
+    let packetsReceived = 0;
+    let packetsLost = 0;
+    for (const e of entries) {
+        if (e.type === 'outbound-rtp')
+            packetsSent += num(e.packetsSent);
+        else if (e.type === 'remote-inbound-rtp') {
+            remotePacketsLost += Math.max(0, num(e.packetsLost));
+            const r = optNum(e.roundTripTime);
+            if (r !== undefined)
+                remoteRtt = Math.max(remoteRtt ?? 0, r);
+        }
+        else if (e.type === 'inbound-rtp') {
+            packetsReceived += num(e.packetsReceived);
+            packetsLost += Math.max(0, num(e.packetsLost));
+        }
+    }
+    const out = optNum(pair?.availableOutgoingBitrate);
+    const inc = optNum(pair?.availableIncomingBitrate);
+    return {
+        rttMs: rtt === undefined ? null : Math.round(rtt * 1000),
+        remoteRttMs: remoteRtt === undefined ? null : Math.round(remoteRtt * 1000),
+        packetsSent,
+        remotePacketsLost,
+        packetsReceived,
+        packetsLost,
+        availableOutgoing: out ?? null,
+        availableIncoming: inc ?? null,
+    };
+}
+const pct = (lost, total) => (total > 0 ? Math.round((Math.min(lost, total) / total) * 1000) / 10 : null);
+/**
+ * The quality now, from each transport's sample and the one before it (by
+ * key; a transport that is new, or whose counters went backwards, gives no
+ * loss for this interval). `publishing` picks the upload estimate.
+ */
+export function networkQualityOf(current, previous, publishing) {
+    let rttMs = null;
+    let lossPct = null;
+    let upload = null;
+    let download = null;
+    for (const [key, now] of current) {
+        const rtt = now.rttMs ?? now.remoteRttMs;
+        if (rtt !== null)
+            rttMs = Math.max(rttMs ?? 0, rtt);
+        if (now.availableOutgoing !== null)
+            upload = Math.max(upload ?? 0, now.availableOutgoing);
+        if (now.availableIncoming !== null)
+            download = Math.max(download ?? 0, now.availableIncoming);
+        const before = previous.get(key);
+        if (!before)
+            continue;
+        const sent = now.packetsSent - before.packetsSent;
+        const remoteLost = now.remotePacketsLost - before.remotePacketsLost;
+        const received = now.packetsReceived - before.packetsReceived;
+        const lost = now.packetsLost - before.packetsLost;
+        // Counters only go forward on one transport; backwards is a new one.
+        const up = sent >= 0 && remoteLost >= 0 ? pct(remoteLost, sent) : null;
+        const down = received >= 0 && lost >= 0 ? pct(lost, received + lost) : null;
+        for (const value of [up, down])
+            if (value !== null)
+                lossPct = Math.max(lossPct ?? 0, value);
+    }
+    const bandwidth = publishing ? upload ?? download : download ?? upload;
+    return {
+        level: networkLevel(rttMs, lossPct),
+        rttMs,
+        lossPct,
+        availableKbps: bandwidth === null ? null : Math.round(bandwidth / 1000),
+    };
+}
+/**
+ * Samples the transports on a timer while wanted and reports each interval.
+ * The first report comes as soon as a round trip is known; loss needs the
+ * previous interval's counters, so it is null until the second.
+ */
+export class NetworkQualityWatch {
+    sample;
+    publishing;
+    report;
+    intervalMs;
+    timer = null;
+    previous = new Map();
+    sampling = false;
+    generation = 0;
+    constructor(
+    /** Each live transport's report, by a key that changes when the transport does. */
+    sample, publishing, report, intervalMs = NETWORK_QUALITY_INTERVAL_MS) {
+        this.sample = sample;
+        this.publishing = publishing;
+        this.report = report;
+        this.intervalMs = intervalMs;
+    }
+    get running() {
+        return this.timer !== null;
+    }
+    /** Start or stop sampling. Safe to call as often as anything changes. */
+    set(wanted) {
+        if (wanted && !this.timer) {
+            this.timer = setInterval(() => void this.tick(), this.intervalMs);
+            void this.tick();
+        }
+        else if (!wanted && this.timer) {
+            clearInterval(this.timer);
+            this.timer = null;
+            this.generation += 1;
+            this.previous = new Map();
+        }
+    }
+    async tick() {
+        if (this.sampling)
+            return;
+        const generation = this.generation;
+        this.sampling = true;
+        try {
+            const reports = await this.sample();
+            if (generation !== this.generation || !this.timer)
+                return;
+            const current = new Map();
+            for (const [key, report] of reports)
+                current.set(key, readTransportStats(report));
+            const first = this.previous.size === 0;
+            const quality = networkQualityOf(current, this.previous, this.publishing());
+            this.previous = current;
+            // Nothing to report without a transport, or before a second sample
+            // when not even the round trip is known yet.
+            if (current.size === 0 || (first && quality.rttMs === null))
+                return;
+            this.report(quality);
+        }
+        catch {
+            // Statistics are best effort; the next interval tries again.
+        }
+        finally {
+            this.sampling = false;
+        }
+    }
+}
+//# sourceMappingURL=network.js.map

package/dist/esm/network.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.js","sourceRoot":"","sources":["../../src/network.ts"],"names":[],"mappings":"AAuBA,uFAAuF;AACvF,MAAM,CAAC,MAAM,2BAA2B,GAAG,IAAI,CAAC;AAEhD;;;GAGG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAwG;IACzI,EAAE,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,GAAG,EAAE,YAAY,EAAE,CAAC,EAAE;IACxD,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,YAAY,EAAE,CAAC,EAAE;IACnD,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,YAAY,EAAE,CAAC,EAAE;CACpD,CAAC;AAEF,MAAM,UAAU,YAAY,CAAC,KAAoB,EAAE,OAAsB;IACvE,KAAK,MAAM,CAAC,IAAI,sBAAsB,EAAE,CAAC;QACvC,IAAI,CAAC,KAAK,KAAK,IAAI,IAAI,KAAK,GAAG,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,OAAO,KAAK,IAAI,IAAI,OAAO,GAAG,CAAC,CAAC,YAAY,CAAC;YAAE,OAAO,CAAC,CAAC,KAAK,CAAC;IACjH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAmBD,MAAM,GAAG,GAAG,CAAC,KAAc,EAAU,EAAE,CAAC,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC1G,MAAM,MAAM,GAAG,CAAC,KAAc,EAAsB,EAAE,CAAC,CAAC,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC;AAEjI,8CAA8C;AAC9C,MAAM,UAAU,kBAAkB,CAAC,MAA4B;IAC7D,MAAM,OAAO,GAAG,CAAC,GAAG,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAmB,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC;IAChG,MAAM,IAAI,GAAG,IAAI,GAAG,EAAsB,CAAC;IAC3C,KAAK,MAAM,KAAK,IAAI,OAAO;QAAE,IAAI,OAAO,KAAK,CAAC,EAAE,KAAK,QAAQ;YAAE,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,CAAC,CAAC;IAEzF,4EAA4E;IAC5E,uDAAuD;IACvD,IAAI,IAA4B,CAAC;IACjC,KAAK,MAAM,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,WAAW,CAAC,EAAE,CAAC;QACtE,MAAM,QAAQ,GAAG,OAAO,SAAS,CAAC,uBAAuB,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,SAAS,CAAC,uBAAuB,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QACjI,IAAI,QAAQ,EAAE,CAAC;YAAC,IAAI,GAAG,QAAQ,CAAC;YAAC,MAAM;QAAC,CAAC;IAC3C,CAAC;IACD,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,gBAAgB,CAAC,CAAC;QACjE,IAAI,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,KAAK,IAAI,IAAI,CAAC,CAAC,KAAK,KAAK,WAAW,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,IAAI,CAAC,CAAC;IACtH,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,EAAE,oBAAoB,CAAC,CAAC;IAE/C,IAAI,SAA6B,CAAC;IAClC,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,iBAAiB,GAAG,CAAC,CAAC;IAC1B,IAAI,eAAe,GAAG,CAAC,CAAC;IACxB,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;QACxB,IAAI,CAAC,CAAC,IAAI,KAAK,cAAc;YAAE,WAAW,IAAI,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;aAC5D,IAAI,CAAC,CAAC,IAAI,KAAK,oBAAoB,EAAE,CAAC;YACzC,iBAAiB,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;YACrD,MAAM,CAAC,GAAG,MAAM,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC;YAClC,IAAI,CAAC,KAAK,SAAS;gBAAE,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,SAAS,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;QAC/D,CAAC;aAAM,IAAI,CAAC,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;YACpC,eAAe,IAAI,GAAG,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;YAC1C,WAAW,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC;QACjD,CAAC;IACH,CAAC;IACD,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,EAAE,wBAAwB,CAAC,CAAC;IACnD,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,EAAE,wBAAwB,CAAC,CAAC;IACnD,OAAO;QACL,KAAK,EAAE,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,GAAG,IAAI,CAAC;QACxD,WAAW,EAAE,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC;QAC1E,WAAW;QACX,iBAAiB;QACjB,eAAe;QACf,WAAW;QACX,iBAAiB,EAAE,GAAG,IAAI,IAAI;QAC9B,iBAAiB,EAAE,GAAG,IAAI,IAAI;KAC/B,CAAC;AACJ,CAAC;AAED,MAAM,GAAG,GAAG,CAAC,IAAY,EAAE,KAAa,EAAiB,EAAE,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,KAAK,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;AAEzI;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAC9B,OAA6C,EAC7C,QAA8C,EAC9C,UAAmB;IAEnB,IAAI,KAAK,GAAkB,IAAI,CAAC;IAChC,IAAI,OAAO,GAAkB,IAAI,CAAC;IAClC,IAAI,MAAM,GAAkB,IAAI,CAAC;IACjC,IAAI,QAAQ,GAAkB,IAAI,CAAC;IACnC,KAAK,MAAM,CAAC,GAAG,EAAE,GAAG,CAAC,IAAI,OAAO,EAAE,CAAC;QACjC,MAAM,GAAG,GAAG,GAAG,CAAC,KAAK,IAAI,GAAG,CAAC,WAAW,CAAC;QACzC,IAAI,GAAG,KAAK,IAAI;YAAE,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,CAAC,EAAE,GAAG,CAAC,CAAC;QACpD,IAAI,GAAG,CAAC,iBAAiB,KAAK,IAAI;YAAE,MAAM,GAAG,IAAI,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,EAAE,GAAG,CAAC,iBAAiB,CAAC,CAAC;QAC1F,IAAI,GAAG,CAAC,iBAAiB,KAAK,IAAI;YAAE,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,IAAI,CAAC,EAAE,GAAG,CAAC,iBAAiB,CAAC,CAAC;QAC9F,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QACjC,IAAI,CAAC,MAAM;YAAE,SAAS;QACtB,MAAM,IAAI,GAAG,GAAG,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;QAClD,MAAM,UAAU,GAAG,GAAG,CAAC,iBAAiB,GAAG,MAAM,CAAC,iBAAiB,CAAC;QACpE,MAAM,QAAQ,GAAG,GAAG,CAAC,eAAe,GAAG,MAAM,CAAC,eAAe,CAAC;QAC9D,MAAM,IAAI,GAAG,GAAG,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAC;QAClD,qEAAqE;QACrE,MAAM,EAAE,GAAG,IAAI,IAAI,CAAC,IAAI,UAAU,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QACvE,MAAM,IAAI,GAAG,QAAQ,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;QAC5E,KAAK,MAAM,KAAK,IAAI,CAAC,EAAE,EAAE,IAAI,CAAC;YAAE,IAAI,KAAK,KAAK,IAAI;gBAAE,OAAO,GAAG,IAAI,CAAC,GAAG,CAAC,OAAO,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;IAC9F,CAAC;IACD,MAAM,SAAS,GAAG,UAAU,CAAC,CAAC,CAAC,MAAM,IAAI,QAAQ,CAAC,CAAC,CAAC,QAAQ,IAAI,MAAM,CAAC;IACvE,OAAO;QACL,KAAK,EAAE,YAAY,CAAC,KAAK,EAAE,OAAO,CAAC;QACnC,KAAK;QACL,OAAO;QACP,aAAa,EAAE,SAAS,KAAK,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,SAAS,GAAG,IAAI,CAAC;KACxE,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,mBAAmB;IAQX;IACA;IACA;IACA;IAVX,KAAK,GAA0C,IAAI,CAAC;IACpD,QAAQ,GAAG,IAAI,GAAG,EAA2B,CAAC;IAC9C,QAAQ,GAAG,KAAK,CAAC;IACjB,UAAU,GAAG,CAAC,CAAC;IAEvB;IACE,mFAAmF;IAClE,MAAwD,EACxD,UAAyB,EACzB,MAAyC,EACzC,aAAa,2BAA2B;QAHxC,WAAM,GAAN,MAAM,CAAkD;QACxD,eAAU,GAAV,UAAU,CAAe;QACzB,WAAM,GAAN,MAAM,CAAmC;QACzC,eAAU,GAAV,UAAU,CAA8B;IACxD,CAAC;IAEJ,IAAI,OAAO;QACT,OAAO,IAAI,CAAC,KAAK,KAAK,IAAI,CAAC;IAC7B,CAAC;IAED,yEAAyE;IACzE,GAAG,CAAC,MAAe;QACjB,IAAI,MAAM,IAAI,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC;YAC1B,IAAI,CAAC,KAAK,GAAG,WAAW,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC;YAClE,KAAK,IAAI,CAAC,IAAI,EAAE,CAAC;QACnB,CAAC;aAAM,IAAI,CAAC,MAAM,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACjC,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAC1B,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;YAClB,IAAI,CAAC,UAAU,IAAI,CAAC,CAAC;YACrB,IAAI,CAAC,QAAQ,GAAG,IAAI,GAAG,EAAE,CAAC;QAC5B,CAAC;IACH,CAAC;IAEO,KAAK,CAAC,IAAI;QAChB,IAAI,IAAI,CAAC,QAAQ;YAAE,OAAO;QAC1B,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,CAAC;QACnC,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAC;QACrB,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,CAAC;YACpC,IAAI,UAAU,KAAK,IAAI,CAAC,UAAU,IAAI,CAAC,IAAI,CAAC,KAAK;gBAAE,OAAO;YAC1D,MAAM,OAAO,GAAG,IAAI,GAAG,EAA2B,CAAC;YACnD,KAAK,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,OAAO;gBAAE,OAAO,CAAC,GAAG,CAAC,GAAG,EAAE,kBAAkB,CAAC,MAAM,CAAC,CAAC,CAAC;YAClF,MAAM,KAAK,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,KAAK,CAAC,CAAC;YACvC,MAAM,OAAO,GAAG,gBAAgB,CAAC,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC;YAC5E,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC;YACxB,mEAAmE;YACnE,6CAA6C;YAC7C,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,OAAO,CAAC,KAAK,KAAK,IAAI,CAAC;gBAAE,OAAO;YACpE,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QACvB,CAAC;QAAC,MAAM,CAAC;YACP,6DAA6D;QAC/D,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,QAAQ,GAAG,KAAK,CAAC;QACxB,CAAC;IACH,CAAC;CACF"}

package/dist/esm/token.d.ts

@@ -0,0 +1,17 @@
+/**
+ * When a room token expires, read from the token itself. Not verified -- the
+ * server does that -- and only used to warn before the token the SDK would
+ * reconnect with lapses (`tokenExpiring`).
+ */
+/** How long before the token's expiry `tokenExpiring` fires. */
+export declare const TOKEN_EXPIRING_LEAD_MS = 60000;
+/**
+ * The socket URL with the token as its `token` query parameter. Joined by
+ * hand rather than with `URL.searchParams`: React Native's `URL` is a partial
+ * polyfill (older releases had no `searchParams.set`), and a WebSocket URL has
+ * no fragment, so the string form is the same as the URL object's.
+ */
+export declare function socketUrl(wsUrl: string, token: string): string;
+/** The `exp` claim of a JWT, in unix milliseconds; null for a token that is not a readable JWT. */
+export declare function tokenExpiresAt(token: string): number | null;
+//# sourceMappingURL=token.d.ts.map

package/dist/esm/token.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.d.ts","sourceRoot":"","sources":["../../src/token.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,gEAAgE;AAChE,eAAO,MAAM,sBAAsB,QAAS,CAAC;AAE7C;;;;;GAKG;AACH,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAE9D;AAED,mGAAmG;AACnG,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAU3D"}

package/dist/esm/token.js

@@ -0,0 +1,31 @@
+/**
+ * When a room token expires, read from the token itself. Not verified -- the
+ * server does that -- and only used to warn before the token the SDK would
+ * reconnect with lapses (`tokenExpiring`).
+ */
+/** How long before the token's expiry `tokenExpiring` fires. */
+export const TOKEN_EXPIRING_LEAD_MS = 60_000;
+/**
+ * The socket URL with the token as its `token` query parameter. Joined by
+ * hand rather than with `URL.searchParams`: React Native's `URL` is a partial
+ * polyfill (older releases had no `searchParams.set`), and a WebSocket URL has
+ * no fragment, so the string form is the same as the URL object's.
+ */
+export function socketUrl(wsUrl, token) {
+    return `${wsUrl}${wsUrl.includes('?') ? '&' : '?'}token=${encodeURIComponent(token)}`;
+}
+/** The `exp` claim of a JWT, in unix milliseconds; null for a token that is not a readable JWT. */
+export function tokenExpiresAt(token) {
+    const payload = typeof token === 'string' ? token.split('.')[1] : undefined;
+    if (!payload || typeof globalThis.atob !== 'function')
+        return null;
+    try {
+        const base64 = payload.replace(/-/g, '+').replace(/_/g, '/');
+        const json = JSON.parse(globalThis.atob(base64 + '='.repeat((4 - (base64.length % 4)) % 4)));
+        return typeof json.exp === 'number' && Number.isFinite(json.exp) && json.exp > 0 ? json.exp * 1000 : null;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=token.js.map

package/dist/esm/token.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token.js","sourceRoot":"","sources":["../../src/token.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,gEAAgE;AAChE,MAAM,CAAC,MAAM,sBAAsB,GAAG,MAAM,CAAC;AAE7C;;;;;GAKG;AACH,MAAM,UAAU,SAAS,CAAC,KAAa,EAAE,KAAa;IACpD,OAAO,GAAG,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,SAAS,kBAAkB,CAAC,KAAK,CAAC,EAAE,CAAC;AACxF,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,MAAM,OAAO,GAAG,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC5E,IAAI,CAAC,OAAO,IAAI,OAAO,UAAU,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC;IACnE,IAAI,CAAC;QACH,MAAM,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC7D,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAsB,CAAC;QAClH,OAAO,OAAO,IAAI,CAAC,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5G,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltkit-rtc/client",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Browser SDK for VoltKit RTC: realtime audio/video rooms, chat and live broadcast publishing.",
   "keywords": [
     "voltkit",

package/src/chat.ts

@@ -7,7 +7,9 @@
  * nothing else -- for an audience that is watching a broadcast over a CDN and
  * has no reason to be on an SFU.
  */
+import { isTerminalError } from './errors.js';
 import type { Role } from './index.js';
+import { socketUrl } from './token.js';
 
 export interface ChatMessage {
   /** Monotonic within a channel, so the oldest id held is a paging cursor. */
@@ -95,16 +97,6 @@ interface Pending {
 
 const RPC_TIMEOUT_MS = 15_000;
 const MAX_RECONNECT_ATTEMPTS = 8;
-/** A token that is wrong will be wrong next time too; retrying only adds noise. */
-const TERMINAL_JOIN_ERRORS = new Set([
-  'bad-token',
-  'no-token',
-  // The account cannot use the service until it is topped up or restored.
-  'quota-exhausted',
-  'daily-limit-reached',
-  'monthly-limit-reached',
-  'tenant-suspended',
-]);
 
 const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
 
@@ -179,9 +171,7 @@ export class ChatClient {
   private openSocket(): Promise<void> {
     this.detachSocket();
     return new Promise((resolve, reject) => {
-      const url = new URL(this.wsUrl);
-      url.searchParams.set('token', this.token);
-      const ws = new WebSocket(url.toString());
+      const ws = new WebSocket(socketUrl(this.wsUrl, this.token));
       this.ws = ws;
 
       const onError = () => reject(new Error('websocket failed to open'));
@@ -246,7 +236,10 @@ export class ChatClient {
           return;
         } catch (err) {
           this.emit('error', err as Error);
-          if (err instanceof ChatRpcError && TERMINAL_JOIN_ERRORS.has(err.code)) {
+          // A token that is wrong will be wrong next time too, and an account
+          // that ran out stays out until topped up: the registry's terminal
+          // codes, shared with StreamClient. Retrying only adds noise.
+          if (err instanceof ChatRpcError && isTerminalError(err.code)) {
             this.closedByUs = true;
             this.emit('closed', 'gave-up');
             return;

package/src/errors.ts

@@ -0,0 +1,162 @@
+/**
+ * One error registry for every VoltKit SDK (docs/sdk-contract.json): the codes
+ * the controller and the media nodes answer with, passed through unchanged, and
+ * the ones the SDKs raise themselves. Switch on `error.code`, never on the
+ * message.
+ *
+ * Kept as a literal here, since the package cannot read the repository's docs
+ * at runtime, and checked against the contract by
+ * scripts/test/sdk-contract-browser.sh and test/contract.test.mjs. One code per
+ * line, so that check can read it.
+ */
+
+/** Who raises a code: the server (controller or media node) or the SDK itself. */
+export type ErrorOrigin = 'server' | 'sdk';
+
+export interface ErrorInfo {
+  origin: ErrorOrigin;
+  /** A join (or reconnect) refused with it must not be retried with the same token. */
+  terminal: boolean;
+  /** Trying the same call again later can succeed. */
+  retryable: boolean;
+}
+
+export const ERROR_CODES = {
+  'bad-json': { origin: 'server', terminal: false, retryable: false },
+  'bad-params': { origin: 'server', terminal: false, retryable: false },
+  'unknown-method': { origin: 'server', terminal: false, retryable: false },
+  'too-many-requests': { origin: 'server', terminal: false, retryable: true },
+  'not-joined': { origin: 'server', terminal: false, retryable: false },
+  'already-joined': { origin: 'server', terminal: false, retryable: false },
+  'internal': { origin: 'server', terminal: false, retryable: true },
+  'node-error': { origin: 'server', terminal: false, retryable: true },
+  'no-token': { origin: 'server', terminal: true, retryable: false },
+  'bad-token': { origin: 'server', terminal: true, retryable: false },
+  'wrong-tenant': { origin: 'server', terminal: true, retryable: false },
+  'token-mismatch': { origin: 'server', terminal: false, retryable: false },
+  'no-room': { origin: 'server', terminal: true, retryable: false },
+  'room-ended': { origin: 'server', terminal: true, retryable: false },
+  'kicked': { origin: 'server', terminal: true, retryable: false },
+  'no-node': { origin: 'server', terminal: false, retryable: true },
+  'no-capacity': { origin: 'server', terminal: false, retryable: true },
+  'stage-full': { origin: 'server', terminal: false, retryable: true },
+  'participant-quota': { origin: 'server', terminal: false, retryable: true },
+  'viewer-quota': { origin: 'server', terminal: false, retryable: true },
+  'quota-exhausted': { origin: 'server', terminal: true, retryable: false },
+  'daily-limit-reached': { origin: 'server', terminal: true, retryable: false },
+  'monthly-limit-reached': { origin: 'server', terminal: true, retryable: false },
+  'tenant-suspended': { origin: 'server', terminal: true, retryable: false },
+  'billing-unavailable': { origin: 'server', terminal: true, retryable: false },
+  'forbidden': { origin: 'server', terminal: true, retryable: false },
+  'not-in-room': { origin: 'server', terminal: false, retryable: false },
+  'no-participant': { origin: 'server', terminal: false, retryable: false },
+  'bad-transport': { origin: 'server', terminal: false, retryable: false },
+  'no-transport': { origin: 'server', terminal: false, retryable: false },
+  'no-producer': { origin: 'server', terminal: false, retryable: false },
+  'no-consumer': { origin: 'server', terminal: false, retryable: false },
+  'cannot-consume': { origin: 'server', terminal: false, retryable: false },
+  'consumer-cap': { origin: 'server', terminal: false, retryable: true },
+  'producer-cap': { origin: 'server', terminal: false, retryable: true },
+  'room-cap': { origin: 'server', terminal: false, retryable: true },
+  'draining': { origin: 'server', terminal: false, retryable: true },
+  'bad-request': { origin: 'server', terminal: false, retryable: false },
+  'source-already-published': { origin: 'server', terminal: false, retryable: false },
+  'force-muted': { origin: 'server', terminal: false, retryable: false },
+  'media-disabled': { origin: 'server', terminal: false, retryable: false },
+  'frame-rate-not-allowed': { origin: 'server', terminal: false, retryable: false },
+  'video-quality-not-allowed': { origin: 'server', terminal: false, retryable: false },
+  'audio-quality-not-allowed': { origin: 'server', terminal: false, retryable: false },
+  'video-not-allowed': { origin: 'server', terminal: false, retryable: false },
+  'audio-not-allowed': { origin: 'server', terminal: false, retryable: false },
+  'video-subscription-limit': { origin: 'server', terminal: false, retryable: false },
+  'slot-taken': { origin: 'server', terminal: false, retryable: false },
+  'slot-blocked': { origin: 'server', terminal: false, retryable: false },
+  'slot-occupied': { origin: 'server', terminal: false, retryable: false },
+  'chat-muted': { origin: 'server', terminal: false, retryable: false },
+  'rate-limited': { origin: 'server', terminal: false, retryable: true },
+  'no-message': { origin: 'server', terminal: false, retryable: false },
+  'chat-unavailable': { origin: 'server', terminal: false, retryable: false },
+  'closed': { origin: 'server', terminal: false, retryable: true },
+  'unauthorized': { origin: 'server', terminal: false, retryable: false },
+  'bad-signature': { origin: 'server', terminal: false, retryable: false },
+  'operator-only': { origin: 'server', terminal: false, retryable: false },
+  'bad-role': { origin: 'server', terminal: false, retryable: false },
+  'room-exists': { origin: 'server', terminal: false, retryable: false },
+  'room-quota': { origin: 'server', terminal: false, retryable: true },
+  'no-nodes': { origin: 'server', terminal: false, retryable: true },
+  'capacity-exhausted': { origin: 'server', terminal: false, retryable: true },
+  'unavailable': { origin: 'server', terminal: false, retryable: true },
+  'not-found': { origin: 'server', terminal: false, retryable: false },
+  'broadcast-disabled': { origin: 'server', terminal: false, retryable: false },
+  'chat-disabled': { origin: 'server', terminal: false, retryable: false },
+  'no-stream': { origin: 'server', terminal: false, retryable: false },
+  'stream-exists': { origin: 'server', terminal: false, retryable: false },
+  'stream-quota': { origin: 'server', terminal: false, retryable: true },
+  'network': { origin: 'sdk', terminal: false, retryable: true },
+  'rates-unconfigured': { origin: 'sdk', terminal: false, retryable: false },
+  'redirected': { origin: 'sdk', terminal: false, retryable: false },
+  'not-connected': { origin: 'sdk', terminal: false, retryable: true },
+  'timeout': { origin: 'sdk', terminal: false, retryable: true },
+  'connect-failed': { origin: 'sdk', terminal: false, retryable: true },
+  'replaced': { origin: 'sdk', terminal: true, retryable: false },
+  'reconnect-gave-up': { origin: 'sdk', terminal: true, retryable: false },
+  'devices-gone': { origin: 'sdk', terminal: false, retryable: false },
+  'unpublished': { origin: 'sdk', terminal: false, retryable: false },
+  'frame-rate-fallback': { origin: 'sdk', terminal: false, retryable: false },
+  'codec-fallback': { origin: 'sdk', terminal: false, retryable: false },
+  'quality-unavailable': { origin: 'sdk', terminal: false, retryable: false },
+  'screen-share-active': { origin: 'sdk', terminal: false, retryable: false },
+  'screen-share-unsupported': { origin: 'sdk', terminal: false, retryable: false },
+  'screen-share-no-video': { origin: 'sdk', terminal: false, retryable: false },
+  'disconnected': { origin: 'sdk', terminal: false, retryable: true },
+  'produce-failed': { origin: 'sdk', terminal: false, retryable: true },
+  'consume-failed': { origin: 'sdk', terminal: false, retryable: true },
+  'media-unavailable': { origin: 'sdk', terminal: false, retryable: false },
+  'music-unavailable': { origin: 'sdk', terminal: false, retryable: false },
+  'no-camera': { origin: 'sdk', terminal: false, retryable: false },
+  'camera-failed': { origin: 'sdk', terminal: false, retryable: true },
+  'unknown-producer': { origin: 'sdk', terminal: false, retryable: false },
+  'screen-share-denied': { origin: 'sdk', terminal: false, retryable: true },
+  'screen-share-service-required': { origin: 'sdk', terminal: false, retryable: false },
+  'screen-share-source-required': { origin: 'sdk', terminal: false, retryable: false },
+  'screen-share-setup-required': { origin: 'sdk', terminal: false, retryable: false },
+  'screen-share-start-timeout': { origin: 'sdk', terminal: false, retryable: true },
+  'screen-share-ended': { origin: 'sdk', terminal: false, retryable: true },
+  'screen-share-failed': { origin: 'sdk', terminal: false, retryable: true },
+  'screen-share-size-unavailable': { origin: 'sdk', terminal: false, retryable: true },
+  'screen-audio-unavailable': { origin: 'sdk', terminal: false, retryable: false },
+  'screen-stop-failed': { origin: 'sdk', terminal: false, retryable: false },
+  'degradation-preference-failed': { origin: 'sdk', terminal: false, retryable: false },
+} as const satisfies Record<string, ErrorInfo>;
+
+/** Every code in the registry. A newer server may still send one this SDK predates. */
+export type ErrorCode = keyof typeof ERROR_CODES;
+
+/** The registry entry for a code, or undefined for one this SDK does not know. */
+export function errorInfo(code: string): ErrorInfo | undefined {
+  return Object.prototype.hasOwnProperty.call(ERROR_CODES, code) ? ERROR_CODES[code as ErrorCode] : undefined;
+}
+
+/**
+ * Whether reconnecting cannot fix a join refused with this code: a room that
+ * has ended is not coming back, and a token that is wrong will be wrong next
+ * time too. Unknown codes are not terminal, so a newer server's code never
+ * stops a reconnect that could succeed.
+ */
+export function isTerminalError(code: string): boolean {
+  return errorInfo(code)?.terminal === true;
+}
+
+/**
+ * An error with a machine-readable code: returned by the server (its code
+ * passed through unchanged, known to this SDK or not) or raised by the SDK
+ * itself with a registry code. `data` is what the server attached so the app
+ * can act on a refusal rather than merely report it: `{ slots }` for
+ * `slot-occupied`, for instance.
+ */
+export class RpcError extends Error {
+  constructor(readonly code: ErrorCode | (string & {}), message: string, readonly data?: unknown) {
+    super(`${code}: ${message}`);
+    this.name = 'RpcError';
+  }
+}