@voltkit-rtc/client 0.7.2 → 0.8.0

package/dist/esm/link.js

@@ -0,0 +1,214 @@
+/**
+ * Keeping the connection alive between drops (docs/implementation-progress/RTC_PERF_PROGRESS.md G1, G2).
+ *
+ * Two failures the socket's own close never reports:
+ *
+ * - **The media path dies while the socket lives** (Wi-Fi to mobile data, a NAT rebinding, UDP blocked mid-call).
+ *   The video freezes for good. Twilio and LiveKit restart ICE on the same transports first -- new ICE credentials
+ *   from the server, the same producers and consumers -- and rejoin only when that does not bring the path back.
+ *   {@link MediaPathWatch} does the same: a transport `disconnected` for {@link DISCONNECTED_GRACE_MS} or `failed`
+ *   restarts ICE; not `connected` within {@link RESTART_TIMEOUT_MS} of starting recovery (including the request), or a server without `restartIce`, is a
+ *   full reconnect.
+ * - **The socket dies silently**: the network went away and TCP has not noticed yet, which can take minutes. The
+ *   server pings, but a browser cannot see those. LiveKit pings from the client and reconnects when no pong comes.
+ *   {@link SocketLiveness} sends `ping` after {@link IDLE_MS} with nothing received, and calls the socket dead when
+ *   nothing at all arrives within {@link PING_TIMEOUT_MS} of it. Any frame counts, so an older server's
+ *   `unknown-method` reply proves the socket as well as a pong.
+ *
+ * Pure: timers and the clock are injectable, so the decisions are unit-tested on their own.
+ */
+/** A transport `disconnected` this long is restarted (it often recovers by itself within a second or two). */
+export const DISCONNECTED_GRACE_MS = 3000;
+/** The whole ICE recovery, including the request, has this long before the session rejoins. */
+export const RESTART_TIMEOUT_MS = 10_000;
+/** With nothing received for this long, the client pings. */
+export const IDLE_MS = 15_000;
+/** A ping with nothing at all received for this long after it: the socket is dead. */
+export const PING_TIMEOUT_MS = 8000;
+/** How often liveness is checked. Background tabs may run it less often; the decisions use the clock, not counts. */
+export const LIVENESS_TICK_MS = 5000;
+/** Watches each media transport's connection state and recovers a dead path. */
+export class MediaPathWatch {
+    host;
+    entries = new Map();
+    setTimer;
+    clearTimer;
+    constructor(host) {
+        this.host = host;
+        this.setTimer = host.setTimer ?? ((fn, ms) => setTimeout(fn, ms));
+        this.clearTimer = host.clearTimer ?? ((h) => clearTimeout(h));
+    }
+    /** A transport's connection state changed (mediasoup-client `connectionstatechange`). */
+    update(transportId, state) {
+        let entry = this.entries.get(transportId);
+        if (!entry) {
+            entry = { state, timer: null, restarting: false, lost: false, revision: 0 };
+            this.entries.set(transportId, entry);
+        }
+        entry.state = state;
+        switch (state) {
+            case 'connected':
+                entry.revision++;
+                this.cancel(entry);
+                entry.restarting = false;
+                this.setLost(transportId, entry, false);
+                return;
+            case 'closed':
+                this.forget(transportId);
+                return;
+            case 'disconnected':
+                // A restart is already waiting for `connected`; its own deadline decides.
+                if (entry.restarting || entry.timer !== null)
+                    return;
+                entry.timer = this.setTimer(() => {
+                    entry.timer = null;
+                    if (entry.state === 'disconnected' || entry.state === 'failed')
+                        void this.restart(transportId, entry);
+                }, DISCONNECTED_GRACE_MS);
+                return;
+            case 'failed':
+                if (entry.restarting)
+                    return; // duplicate notification; the deadline decides
+                this.cancel(entry);
+                void this.restart(transportId, entry);
+                return;
+            default:
+                // new / connecting: a fresh transport, or one mid-restart.
+                return;
+        }
+    }
+    /** The transport went away with its session (teardown): no more decisions for it. */
+    forget(transportId) {
+        const entry = this.entries.get(transportId);
+        if (!entry)
+            return;
+        this.cancel(entry);
+        this.entries.delete(transportId);
+        if (entry.lost)
+            this.host.onPathChange?.(transportId, false);
+    }
+    /** Every transport went away (teardown, close). */
+    reset() {
+        for (const id of [...this.entries.keys()])
+            this.forget(id);
+    }
+    /** For tests and the network-change nudge: is this transport being recovered now? */
+    restartingNow(transportId) {
+        return this.entries.get(transportId)?.restarting === true;
+    }
+    async restart(transportId, entry) {
+        if (!this.host.active() || this.entries.get(transportId) !== entry)
+            return;
+        entry.restarting = true;
+        const revision = ++entry.revision;
+        // Include both the RPC and the platform call in the deadline: neither is
+        // guaranteed to settle when a network/interface disappears.
+        this.cancel(entry);
+        entry.timer = this.setTimer(() => {
+            entry.timer = null;
+            if (!entry.restarting || this.entries.get(transportId) !== entry)
+                return;
+            entry.revision++;
+            entry.restarting = false;
+            if (this.host.active())
+                this.host.reconnect('media-timeout');
+        }, RESTART_TIMEOUT_MS);
+        this.setLost(transportId, entry, true);
+        let outcome;
+        try {
+            outcome = await this.host.restartIce(transportId);
+        }
+        catch {
+            outcome = 'unsupported';
+        }
+        if (this.entries.get(transportId) !== entry || entry.revision !== revision)
+            return;
+        if (outcome === 'skipped') {
+            this.cancel(entry);
+            entry.restarting = false;
+            return;
+        }
+        if (outcome === 'unsupported') {
+            this.cancel(entry);
+            entry.restarting = false;
+            if (this.host.active())
+                this.host.reconnect('media-failed');
+            return;
+        }
+        // `connected` clears the deadline, including when it arrives during the await.
+    }
+    setLost(transportId, entry, lost) {
+        if (entry.lost === lost)
+            return;
+        entry.lost = lost;
+        this.host.onPathChange?.(transportId, lost);
+    }
+    cancel(entry) {
+        if (entry.timer !== null)
+            this.clearTimer(entry.timer);
+        entry.timer = null;
+    }
+}
+/** Notices a socket that died without closing. */
+export class SocketLiveness {
+    host;
+    lastReceived = 0;
+    pingSentAt = null;
+    timer = null;
+    now;
+    constructor(host) {
+        this.host = host;
+        this.now = host.now ?? Date.now;
+    }
+    /** Start watching a newly opened socket. */
+    start() {
+        this.stop();
+        this.lastReceived = this.now();
+        this.pingSentAt = null;
+        const every = this.host.setInterval ?? ((fn, ms) => setInterval(fn, ms));
+        this.timer = every(() => this.check(), LIVENESS_TICK_MS);
+        // A Node/SSR process with no other work need not stay alive for a browser
+        // connection watch. Browser timers are numbers and have no unref.
+        this.timer?.unref?.();
+    }
+    stop() {
+        if (this.timer !== null)
+            (this.host.clearInterval ?? ((h) => clearInterval(h)))(this.timer);
+        this.timer = null;
+        this.pingSentAt = null;
+    }
+    get running() {
+        return this.timer !== null;
+    }
+    /** Any frame arrived on the socket. */
+    received() {
+        this.lastReceived = this.now();
+        this.pingSentAt = null;
+    }
+    /** Check now instead of at the next tick (the browser said the network changed). */
+    checkNow() {
+        if (this.timer === null || !this.host.active())
+            return;
+        if (this.pingSentAt === null) {
+            this.pingSentAt = this.now();
+            this.host.ping();
+        }
+    }
+    check() {
+        if (this.timer === null || !this.host.active())
+            return;
+        const now = this.now();
+        if (this.pingSentAt !== null) {
+            if (now - this.pingSentAt >= PING_TIMEOUT_MS) {
+                this.stop();
+                this.host.dead();
+            }
+            return;
+        }
+        if (now - this.lastReceived >= IDLE_MS) {
+            this.pingSentAt = now;
+            this.host.ping();
+        }
+    }
+}
+//# sourceMappingURL=link.js.map

package/dist/esm/link.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"link.js","sourceRoot":"","sources":["../../src/link.ts"],"names":[],"mappings":"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"}

package/dist/esm/preflight.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Pre-call check (docs/implementation-progress/RTC_PERF_PROGRESS.md L1).
+ *
+ * - Twilio's `runPreflight` (read from its code) joins a test room, publishes synthetic audio and video and reports
+ *   timings, the connection path, round trip, jitter and loss.
+ * - LiveKit's `ConnectionCheck` runs separate checks -- WebSocket, WebRTC, TURN, publishing audio and video, UDP
+ *   against TCP -- each with messages and warnings.
+ * - Agora's `startLastmileProbeTest` measures the last mile before a call.
+ *
+ * This joins the room the token names (mint one for a test room nobody else is in: the session is real, and billed
+ * like any other for its few seconds), publishes what it is given -- or a tone and a picture it makes -- and reports
+ * what it saw. The orchestration takes a small target interface, so it is tested without a browser.
+ */
+import { type NetworkQualityLevel } from './network.js';
+import type { StatsEntry } from './stats.js';
+import type { MediaWarningCode } from './health.js';
+export interface PreflightOptions {
+    /** What to publish (cloned; your tracks are left running). Without it, a tone and a moving picture are made. */
+    media?: MediaStream;
+    /** How long media is measured once it flows. Default 5 s. */
+    durationMs?: number;
+}
+export type PreflightStepName = 'join' | 'media';
+export interface PreflightStep {
+    name: PreflightStepName;
+    ok: boolean;
+    /** How long it took, in ms. */
+    ms: number | null;
+    error?: string;
+}
+export interface PreflightReport {
+    /** Joined, and media reached the server. */
+    ok: boolean;
+    steps: PreflightStep[];
+    /** How media travelled: UDP is best; TCP or a relay means a firewall in the way (it works, with more delay). */
+    path: {
+        protocol: 'udp' | 'tcp' | null;
+        relayed: boolean;
+    } | null;
+    rttMs: number | null;
+    lossPct: number | null;
+    /** The upload the browser estimated it could use, in kbps. */
+    uploadKbps: number | null;
+    level: NetworkQualityLevel | null;
+    /** Camera and microphone problems seen during the test (see the mediaWarning event). */
+    warnings: MediaWarningCode[];
+}
+/** What a pre-call check needs from a client. */
+export interface PreflightTarget {
+    connect(): Promise<unknown>;
+    publish(stream: MediaStream): Promise<void>;
+    /** The send transport's connection state, or null before there is one. */
+    sendState(): string | null;
+    /** The send transport's statistics, or null without one. */
+    sendStats(): Promise<Iterable<StatsEntry> | null>;
+    onWarning(listener: (code: MediaWarningCode, active: boolean) => void): () => void;
+    close(): void;
+}
+export interface PreflightEnv {
+    now(): number;
+    sleep(ms: number): Promise<void>;
+}
+/** Media has this long to connect once published. */
+export declare const MEDIA_CONNECT_TIMEOUT_MS = 10000;
+/** Statistics are read this often while measuring. */
+export declare const PREFLIGHT_SAMPLE_MS = 1000;
+/** The selected candidate pair's protocol, and whether either end is a relay. */
+export declare function connectionPath(report: Iterable<StatsEntry>): PreflightReport['path'];
+/** Run the check on `target`, closing it at the end whatever happens. */
+export declare function runPreflight(target: PreflightTarget, stream: MediaStream, options?: PreflightOptions, env?: PreflightEnv): Promise<PreflightReport>;
+/**
+ * A tone and a moving picture to publish when the app gives none (Twilio's preflight makes synthetic media too).
+ * Returns the stream and a function that stops everything it made. Browser only.
+ */
+export declare function syntheticMedia(): {
+    stream: MediaStream;
+    stop: () => void;
+};
+//# sourceMappingURL=preflight.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../../src/preflight.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAwC,KAAK,mBAAmB,EAAwB,MAAM,cAAc,CAAC;AACpH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAEpD,MAAM,WAAW,gBAAgB;IAC/B,gHAAgH;IAChH,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,OAAO,CAAC;AAEjD,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,iBAAiB,CAAC;IACxB,EAAE,EAAE,OAAO,CAAC;IACZ,+BAA+B;IAC/B,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,4CAA4C;IAC5C,EAAE,EAAE,OAAO,CAAC;IACZ,KAAK,EAAE,aAAa,EAAE,CAAC;IACvB,gHAAgH;IAChH,IAAI,EAAE;QAAE,QAAQ,EAAE,KAAK,GAAG,KAAK,GAAG,IAAI,CAAC;QAAC,OAAO,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;IAClE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,8DAA8D;IAC9D,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,KAAK,EAAE,mBAAmB,GAAG,IAAI,CAAC;IAClC,wFAAwF;IACxF,QAAQ,EAAE,gBAAgB,EAAE,CAAC;CAC9B;AAED,iDAAiD;AACjD,MAAM,WAAW,eAAe;IAC9B,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5B,OAAO,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5C,0EAA0E;IAC1E,SAAS,IAAI,MAAM,GAAG,IAAI,CAAC;IAC3B,4DAA4D;IAC5D,SAAS,IAAI,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC,CAAC;IAClD,SAAS,CAAC,QAAQ,EAAE,CAAC,IAAI,EAAE,gBAAgB,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,GAAG,MAAM,IAAI,CAAC;IACnF,KAAK,IAAI,IAAI,CAAC;CACf;AAED,MAAM,WAAW,YAAY;IAC3B,GAAG,IAAI,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAClC;AAID,qDAAqD;AACrD,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAC/C,sDAAsD;AACtD,eAAO,MAAM,mBAAmB,OAAO,CAAC;AAExC,iFAAiF;AACjF,wBAAgB,cAAc,CAAC,MAAM,EAAE,QAAQ,CAAC,UAAU,CAAC,GAAG,eAAe,CAAC,MAAM,CAAC,CAgBpF;AAED,yEAAyE;AACzE,wBAAsB,YAAY,CAAC,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,GAAE,gBAAqB,EAAE,GAAG,GAAE,YAAsB,GAAG,OAAO,CAAC,eAAe,CAAC,CAsDtK;AAED;;;GAGG;AACH,wBAAgB,cAAc,IAAI;IAAE,MAAM,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,IAAI,CAAA;CAAE,CAqC1E"}

package/dist/esm/preflight.js

@@ -0,0 +1,153 @@
+/**
+ * Pre-call check (docs/implementation-progress/RTC_PERF_PROGRESS.md L1).
+ *
+ * - Twilio's `runPreflight` (read from its code) joins a test room, publishes synthetic audio and video and reports
+ *   timings, the connection path, round trip, jitter and loss.
+ * - LiveKit's `ConnectionCheck` runs separate checks -- WebSocket, WebRTC, TURN, publishing audio and video, UDP
+ *   against TCP -- each with messages and warnings.
+ * - Agora's `startLastmileProbeTest` measures the last mile before a call.
+ *
+ * This joins the room the token names (mint one for a test room nobody else is in: the session is real, and billed
+ * like any other for its few seconds), publishes what it is given -- or a tone and a picture it makes -- and reports
+ * what it saw. The orchestration takes a small target interface, so it is tested without a browser.
+ */
+import { networkQualityOf, readTransportStats } from './network.js';
+const realEnv = { now: () => Date.now(), sleep: (ms) => new Promise((r) => setTimeout(r, ms)) };
+/** Media has this long to connect once published. */
+export const MEDIA_CONNECT_TIMEOUT_MS = 10_000;
+/** Statistics are read this often while measuring. */
+export const PREFLIGHT_SAMPLE_MS = 1000;
+/** The selected candidate pair's protocol, and whether either end is a relay. */
+export function connectionPath(report) {
+    const entries = [...report];
+    const byId = new Map();
+    for (const e of entries)
+        if (typeof e.id === 'string')
+            byId.set(e.id, e);
+    let pair;
+    for (const t of entries.filter((e) => e.type === 'transport')) {
+        if (typeof t.selectedCandidatePairId === 'string')
+            pair = byId.get(t.selectedCandidatePairId);
+        if (pair)
+            break;
+    }
+    pair ??= entries.find((e) => e.type === 'candidate-pair' && e.nominated === true && e.state === 'succeeded');
+    if (!pair)
+        return null;
+    const local = typeof pair.localCandidateId === 'string' ? byId.get(pair.localCandidateId) : undefined;
+    const remote = typeof pair.remoteCandidateId === 'string' ? byId.get(pair.remoteCandidateId) : undefined;
+    const protocol = local?.protocol === 'udp' || local?.protocol === 'tcp' ? local.protocol : null;
+    const relayed = local?.candidateType === 'relay' || remote?.candidateType === 'relay';
+    return { protocol, relayed };
+}
+/** Run the check on `target`, closing it at the end whatever happens. */
+export async function runPreflight(target, stream, options = {}, env = realEnv) {
+    const report = { ok: false, steps: [], path: null, rttMs: null, lossPct: null, uploadKbps: null, level: null, warnings: [] };
+    const seen = new Set();
+    const stopWarnings = target.onWarning((code, active) => { if (active)
+        seen.add(code); });
+    try {
+        let started = env.now();
+        try {
+            await target.connect();
+            report.steps.push({ name: 'join', ok: true, ms: env.now() - started });
+        }
+        catch (err) {
+            report.steps.push({ name: 'join', ok: false, ms: null, error: String(err?.message ?? err) });
+            return report;
+        }
+        started = env.now();
+        try {
+            await target.publish(stream);
+            while (target.sendState() !== 'connected') {
+                const state = target.sendState();
+                if (state === 'failed' || state === 'closed')
+                    throw new Error(`media connection ${state}`);
+                if (env.now() - started > MEDIA_CONNECT_TIMEOUT_MS)
+                    throw new Error('media did not connect in time (a firewall blocking UDP and TCP?)');
+                await env.sleep(100);
+            }
+            report.steps.push({ name: 'media', ok: true, ms: env.now() - started });
+        }
+        catch (err) {
+            report.steps.push({ name: 'media', ok: false, ms: null, error: String(err?.message ?? err) });
+            return report;
+        }
+        // Measure: the worst round trip and loss over the run, the last upload estimate.
+        const duration = options.durationMs ?? 5000;
+        let previous = new Map();
+        const until = env.now() + duration;
+        while (env.now() < until) {
+            await env.sleep(PREFLIGHT_SAMPLE_MS);
+            const stats = await target.sendStats().catch(() => null);
+            if (!stats)
+                continue;
+            const entries = [...stats];
+            report.path = connectionPath(entries) ?? report.path;
+            const now = new Map([['send', readTransportStats(entries)]]);
+            const q = networkQualityOf(now, previous, true);
+            previous = now;
+            if (q.rttMs !== null)
+                report.rttMs = Math.max(report.rttMs ?? 0, q.rttMs);
+            if (q.lossPct !== null)
+                report.lossPct = Math.max(report.lossPct ?? 0, q.lossPct);
+            if (q.availableKbps !== null)
+                report.uploadKbps = q.availableKbps;
+            report.level = q.level;
+        }
+        report.ok = true;
+        return report;
+    }
+    finally {
+        report.warnings = [...seen];
+        stopWarnings();
+        target.close();
+    }
+}
+/**
+ * A tone and a moving picture to publish when the app gives none (Twilio's preflight makes synthetic media too).
+ * Returns the stream and a function that stops everything it made. Browser only.
+ */
+export function syntheticMedia() {
+    const tracks = [];
+    const stops = [];
+    const AudioCtx = globalThis.AudioContext;
+    if (AudioCtx) {
+        const ctx = new AudioCtx();
+        const osc = ctx.createOscillator();
+        const gain = ctx.createGain();
+        gain.gain.value = 0.05;
+        const dest = ctx.createMediaStreamDestination();
+        osc.connect(gain).connect(dest);
+        osc.start();
+        tracks.push(...dest.stream.getAudioTracks());
+        stops.push(() => { osc.stop(); void ctx.close(); });
+    }
+    if (typeof document !== 'undefined') {
+        const canvas = document.createElement('canvas');
+        canvas.width = 640;
+        canvas.height = 360;
+        const g = canvas.getContext('2d');
+        let frame = 0;
+        const draw = () => {
+            if (!g)
+                return;
+            frame += 1;
+            g.fillStyle = `hsl(${frame % 360}, 60%, 40%)`;
+            g.fillRect(0, 0, canvas.width, canvas.height);
+            g.fillStyle = '#fff';
+            g.fillRect((frame * 8) % canvas.width, 150, 60, 60);
+        };
+        draw();
+        const timer = setInterval(draw, 1000 / 30);
+        const captured = canvas.captureStream?.(30);
+        if (captured)
+            tracks.push(...captured.getVideoTracks());
+        stops.push(() => clearInterval(timer));
+    }
+    const stream = new MediaStream(tracks);
+    return { stream, stop: () => { for (const t of tracks)
+            t.stop(); for (const s of stops)
+            s(); } };
+}
+//# sourceMappingURL=preflight.js.map

package/dist/esm/preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.js","sourceRoot":"","sources":["../../src/preflight.ts"],"names":[],"mappings":"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"}

package/dist/esm/recording.d.ts

@@ -68,6 +68,20 @@ export declare class RecordingUploader {
     private upload;
     waitForCapacity(): Promise<void>;
     seal(): Promise<void>;
+    /**
+     * How long complete() waits before asking `/complete` again when the
+     * answer was lost or unclear: one wait per extra attempt. Exposed for tests.
+     * @internal
+     */
+    static completeRetryDelaysMs: number[];
+    /**
+     * Finalise. An accepted `/complete` whose reply cannot be read rejects
+     * saying the recording completed. A lost or unclear answer (no reply, an
+     * unreadable one, a 5xx, 408/409/425/429) is asked again -- the service's
+     * completion is idempotent -- and if it is still unclear, rejects saying the
+     * recording may already be saved. Neither is aborted; only a readable
+     * refusal is final (V072-04).
+     */
     complete(): Promise<RecordingFile>;
     abort(): Promise<void>;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"recording.d.ts","sourceRoot":"","sources":["../../src/recording.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"recording.d.ts","sourceRoot":"","sources":["../../src/recording.ts"],"names":[],"mappings":"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"}

package/dist/esm/recording.js

@@ -7,8 +7,9 @@ export class RecordingError extends Error {
     }
 }
 const delay = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
-export async function recordingRequest(base, path, body, token) {
-    const response = await fetch(`${base.replace(/\/$/, "")}/recording/upload${path}`, {
+/** One POST to the recording API. */
+function recordingFetch(base, path, body, token) {
+    return fetch(`${base.replace(/\/$/, "")}/recording/upload${path}`, {
         method: "POST",
         credentials: "omit",
         headers: {
@@ -18,6 +19,9 @@ export async function recordingRequest(base, path, body, token) {
         body: JSON.stringify(body),
         signal: AbortSignal.timeout(path.endsWith("/complete") ? 180000 : 15000),
     });
+}
+export async function recordingRequest(base, path, body, token) {
+    const response = await recordingFetch(base, path, body, token);
     const result = (await response.json());
     if (!response.ok || !result.success || !result.data)
         throw new RecordingError(result.error?.message ?? "Recording request failed", response.status);
@@ -222,11 +226,53 @@ export class RecordingUploader {
         }
         this.sealed = true;
     }
+    /**
+     * How long complete() waits before asking `/complete` again when the
+     * answer was lost or unclear: one wait per extra attempt. Exposed for tests.
+     * @internal
+     */
+    static completeRetryDelaysMs = [1000, 3000];
+    /**
+     * Finalise. An accepted `/complete` whose reply cannot be read rejects
+     * saying the recording completed. A lost or unclear answer (no reply, an
+     * unreadable one, a 5xx, 408/409/425/429) is asked again -- the service's
+     * completion is idempotent -- and if it is still unclear, rejects saying the
+     * recording may already be saved. Neither is aborted; only a readable
+     * refusal is final (V072-04).
+     */
     async complete() {
         await this.seal();
-        const file = await recordingRequest(this.options.apiUrl, `/sessions/${this.session.recording.id}/complete`, {}, this.session.token);
-        this.emit("ready");
-        return file;
+        const path = `/sessions/${this.session.recording.id}/complete`;
+        for (let attempt = 0;; attempt++) {
+            let status = 0;
+            let body = null;
+            try {
+                const response = await recordingFetch(this.options.apiUrl, path, {}, this.session.token);
+                status = response.status;
+                const parsed = await response.json();
+                if (parsed && typeof parsed === "object")
+                    body = parsed;
+            }
+            catch {
+                // Lost, cut short or unreadable: the service may have saved it.
+            }
+            if (body && status > 0 && status < 400 && body.success === true) {
+                const file = body.data;
+                if (!file || typeof file !== "object" || typeof file.id !== "string") {
+                    throw new RecordingError("The recording was completed but its reply could not be read", status);
+                }
+                this.emit("ready");
+                return file;
+            }
+            if (body && status > 0 && status < 500 && ![408, 409, 425, 429].includes(status)) {
+                throw new RecordingError(body.error?.message ?? "Recording request failed", status);
+            }
+            const delays = RecordingUploader.completeRetryDelaysMs;
+            if (attempt >= delays.length) {
+                throw new RecordingError("The service did not confirm the recording, which may already be saved; it was not aborted", status);
+            }
+            await delay(delays[attempt]);
+        }
     }
     async abort() {
         this.canceled = true;