tabsail 0.0.0-stage → 0.1.0

package/dist/transport.js

@@ -0,0 +1,384 @@
+import { APIError, CancelledError, ConfigurationError, NetworkError, ProtocolError, RequestTimeoutError, ResultUnknownError, redact, TabSailError, } from "./errors.js";
+export function positive(value, name) {
+    if (!Number.isFinite(value) || value <= 0 || value > 2_147_483_647)
+        throw new ConfigurationError(`${name} must be a positive number of milliseconds.`, { code: "INVALID_CONFIGURATION" });
+    return value;
+}
+export function retries(value) {
+    if (!Number.isInteger(value) || value < 0 || value > 10)
+        throw new ConfigurationError("maxRetries must be an integer between 0 and 10.", { code: "INVALID_CONFIGURATION" });
+    return value;
+}
+export function operationKey(value) {
+    const key = value ?? crypto.randomUUID();
+    if (!key || key.length > 128 || /[^\x20-\x7e]/.test(key))
+        throw new ConfigurationError("idempotencyKey must contain 1–128 printable ASCII characters.", { code: "INVALID_IDEMPOTENCY_KEY" });
+    return key;
+}
+export function checkCancelled(signal, sessionId) {
+    if (signal?.aborted)
+        throw new CancelledError("The caller cancelled the operation.", {
+            code: "CANCELLED",
+            sessionId,
+        });
+}
+/** Retry-After is a floor; jitter must still spread callers when it is present. */
+export function retryDelay(attempt, retryAfterMs = 0, maximumBackoffMs = 5_000, random = Math.random()) {
+    const window = Math.min(maximumBackoffMs, 250 * 2 ** Math.min(attempt, 30));
+    return Math.max(0, retryAfterMs) + window * (0.5 + random * 0.5);
+}
+export async function sleep(milliseconds, signal, sessionId) {
+    checkCancelled(signal, sessionId);
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(done, milliseconds);
+        function done() {
+            signal?.removeEventListener("abort", abort);
+            resolve();
+        }
+        function abort() {
+            clearTimeout(timer);
+            signal?.removeEventListener("abort", abort);
+            reject(new CancelledError("The caller cancelled the operation.", {
+                code: "CANCELLED",
+                sessionId,
+            }));
+        }
+        signal?.addEventListener("abort", abort, { once: true });
+        if (signal?.aborted)
+            abort();
+    });
+}
+/** A streaming download. Consume its body or explicitly close it. */
+export class FileDownload {
+    body;
+    headers;
+    status;
+    #reader;
+    #finish;
+    #abort;
+    #closed = false;
+    constructor(response, finish, abort, failure) {
+        if (!response.body)
+            throw new ProtocolError("Download response has no body.", {
+                code: "INVALID_RESPONSE",
+            });
+        this.headers = response.headers;
+        this.status = response.status;
+        this.#reader = response.body.getReader();
+        this.#finish = finish;
+        this.#abort = abort;
+        this.body = new ReadableStream({
+            pull: async (controller) => {
+                try {
+                    const result = await this.#reader.read();
+                    if (result.done) {
+                        this.#closed = true;
+                        this.#finish();
+                        controller.close();
+                    }
+                    else
+                        controller.enqueue(result.value);
+                }
+                catch (error) {
+                    this.#closed = true;
+                    this.#finish();
+                    controller.error(failure(error));
+                }
+            },
+            cancel: () => this.close(),
+        }, { highWaterMark: 0 });
+    }
+    async close() {
+        if (this.#closed)
+            return;
+        this.#closed = true;
+        this.#abort();
+        try {
+            await this.#reader.cancel();
+        }
+        catch {
+            /* Aborting closes the network stream as well. */
+        }
+        finally {
+            this.#finish();
+        }
+    }
+    async [Symbol.asyncDispose]() {
+        await this.close();
+    }
+    async *[Symbol.asyncIterator]() {
+        const reader = this.body.getReader();
+        try {
+            while (true) {
+                const item = await reader.read();
+                if (item.done)
+                    return;
+                yield item.value;
+            }
+        }
+        finally {
+            reader.releaseLock();
+            await this.close();
+        }
+    }
+}
+export class Transport {
+    #apiKey;
+    #base;
+    #fetch;
+    requestTimeoutMs;
+    maxRetries;
+    constructor(options) {
+        const apiKey = options.apiKey ?? process.env.TABSAIL_API_KEY;
+        const baseURL = options.baseURL ?? process.env.TABSAIL_BASE_URL;
+        if (!apiKey?.trim() || !baseURL?.trim())
+            throw new ConfigurationError("Set baseURL and apiKey, or TABSAIL_BASE_URL and TABSAIL_API_KEY.", { code: "MISSING_CONFIGURATION" });
+        if (/[^\x20-\x7e]/.test(apiKey))
+            throw new ConfigurationError("apiKey must contain printable ASCII characters.", { code: "INVALID_CONFIGURATION" });
+        try {
+            this.#base = new URL(baseURL);
+            if (!["http:", "https:"].includes(this.#base.protocol) ||
+                this.#base.username ||
+                this.#base.password ||
+                this.#base.search ||
+                this.#base.hash ||
+                !/^\/*$/.test(this.#base.pathname))
+                throw Error();
+            this.#base.pathname = "/v1/";
+        }
+        catch {
+            throw new ConfigurationError("baseURL must be an HTTP(S) instance root URL without credentials, query, or fragment.", { code: "INVALID_CONFIGURATION" });
+        }
+        this.#apiKey = apiKey;
+        // Native fetch in workerd requires the runtime's global receiver.
+        this.#fetch = (options.fetch ?? globalThis.fetch).bind(globalThis);
+        this.requestTimeoutMs = positive(options.requestTimeoutMs ?? 15_000, "requestTimeoutMs");
+        this.maxRetries = retries(options.maxRetries ?? 0);
+    }
+    safe(error, sessionId) {
+        if (error instanceof TabSailError)
+            return error;
+        const message = error instanceof Error
+            ? `${error.name}: ${error.message}`
+            : "Unknown transport failure";
+        return new NetworkError(redact(message, [this.#apiKey]), {
+            code: "NETWORK_ERROR",
+            retryable: true,
+            sessionId,
+        });
+    }
+    async request(spec, options = {}) {
+        checkCancelled(options.signal, spec.sessionId);
+        const requestTimeout = positive(options.requestTimeoutMs ?? this.requestTimeoutMs, "requestTimeoutMs");
+        const maxRetries = retries(options.maxRetries ?? this.maxRetries);
+        const totalTimeout = positive(options.timeoutMs ?? requestTimeout * (maxRetries + 1) + 30_000, "timeoutMs");
+        const deadline = performance.now() + totalTimeout;
+        const jsonBody = spec.json === undefined ? undefined : JSON.stringify(spec.json);
+        let dispatched = false;
+        let lastFailure;
+        try {
+            for (let attempt = 0; attempt <= maxRetries; attempt++) {
+                checkCancelled(options.signal, spec.sessionId);
+                const remaining = deadline - performance.now();
+                if (remaining <= 0)
+                    throw new RequestTimeoutError("The logical request deadline elapsed.", { code: "OPERATION_TIMEOUT", sessionId: spec.sessionId });
+                const controller = new AbortController();
+                let timedOut = false;
+                const timer = setTimeout(() => {
+                    timedOut = true;
+                    controller.abort();
+                }, Math.min(requestTimeout, remaining));
+                const abort = () => controller.abort();
+                options.signal?.addEventListener("abort", abort, { once: true });
+                const finish = () => {
+                    clearTimeout(timer);
+                    options.signal?.removeEventListener("abort", abort);
+                };
+                const failure = (error) => options.signal?.aborted
+                    ? new CancelledError("The caller cancelled the operation.", {
+                        code: "CANCELLED",
+                        sessionId: spec.sessionId,
+                    })
+                    : timedOut
+                        ? new RequestTimeoutError("HTTP request timed out.", {
+                            code: remaining <= requestTimeout
+                                ? "OPERATION_TIMEOUT"
+                                : "REQUEST_TIMEOUT",
+                            retryable: true,
+                            sessionId: spec.sessionId,
+                        })
+                        : this.safe(error, spec.sessionId);
+                let streamOwned = false;
+                try {
+                    checkCancelled(options.signal, spec.sessionId);
+                    const url = new URL(spec.path, this.#base);
+                    if (url.origin !== this.#base.origin ||
+                        !url.pathname.startsWith("/v1/"))
+                        throw new ConfigurationError("Request path must stay inside the configured API origin.", { code: "INVALID_PATH" });
+                    const headers = {
+                        Authorization: `Bearer ${this.#apiKey}`,
+                        ...(spec.json === undefined
+                            ? {}
+                            : { "Content-Type": "application/json" }),
+                        ...(spec.key === undefined ? {} : { "Idempotency-Key": spec.key }),
+                        ...spec.headers,
+                    };
+                    dispatched = true;
+                    const response = await this.#fetch(url, {
+                        method: spec.method,
+                        headers,
+                        redirect: "manual",
+                        signal: controller.signal,
+                        body: spec.json === undefined ? spec.body : jsonBody,
+                        ...(spec.body instanceof ReadableStream ? { duplex: "half" } : {}),
+                    });
+                    if (!response.ok)
+                        throw await this.httpError(response, spec.sessionId);
+                    if (spec.streaming) {
+                        const download = new FileDownload(response, finish, () => controller.abort(), failure);
+                        streamOwned = true;
+                        return download;
+                    }
+                    if (response.status === 204) {
+                        await response.body?.cancel();
+                        return undefined;
+                    }
+                    let value;
+                    try {
+                        value = await response.json();
+                    }
+                    catch (error) {
+                        if (controller.signal.aborted)
+                            throw failure(error);
+                        throw new ProtocolError("Successful HTTP response is not valid JSON.", {
+                            code: "INVALID_RESPONSE",
+                            status: response.status,
+                            requestId: this.sanitize(response.headers.get("x-request-id")),
+                            sessionId: spec.sessionId,
+                        });
+                    }
+                    checkCancelled(options.signal, spec.sessionId);
+                    try {
+                        return spec.parse ? spec.parse(value) : value;
+                    }
+                    catch (error) {
+                        if (error instanceof ProtocolError)
+                            throw new ProtocolError(error.message, {
+                                ...error.toJSON(),
+                                status: response.status,
+                                requestId: this.sanitize(response.headers.get("x-request-id")),
+                                sessionId: spec.sessionId,
+                            });
+                        throw error;
+                    }
+                }
+                catch (error) {
+                    lastFailure = error instanceof TabSailError ? error : failure(error);
+                    if (lastFailure instanceof APIError &&
+                        ((lastFailure.status ?? 0) < 500 ||
+                            ["NO_CAPACITY", "STARTUP_BUSY"].includes(lastFailure.code)))
+                        dispatched = false;
+                    const retryable = spec.replayable &&
+                        attempt < maxRetries &&
+                        (lastFailure instanceof NetworkError ||
+                            lastFailure instanceof RequestTimeoutError ||
+                            (lastFailure instanceof APIError &&
+                                [429, 503].includes(lastFailure.status ?? 0) &&
+                                lastFailure.retryable));
+                    if (!retryable || options.signal?.aborted)
+                        throw lastFailure;
+                }
+                finally {
+                    if (!streamOwned)
+                        finish();
+                }
+                const backoff = retryDelay(attempt, lastFailure?.retryAfterMs);
+                if (deadline - performance.now() <= backoff)
+                    throw new RequestTimeoutError("The logical request deadline elapsed before another retry.", { code: "OPERATION_TIMEOUT", sessionId: spec.sessionId });
+                await sleep(backoff, options.signal, spec.sessionId);
+            }
+            throw (lastFailure ??
+                new ProtocolError("Request did not produce a result.", {
+                    code: "INVALID_RESPONSE",
+                }));
+        }
+        catch (error) {
+            const safe = this.safe(error, spec.sessionId);
+            const uncertainHTTP = safe instanceof APIError &&
+                (safe.status ?? 0) >= 500 &&
+                !["NO_CAPACITY", "STARTUP_BUSY"].includes(safe.code);
+            if (spec.uncertain &&
+                dispatched &&
+                (!(safe instanceof APIError) || uncertainHTTP))
+                throw new ResultUnknownError(spec.uncertain, spec.key, safe, spec.sessionId);
+            throw safe;
+        }
+    }
+    sanitize(value) {
+        return value ? redact(value, [this.#apiKey]) : undefined;
+    }
+    async httpError(response, sessionId) {
+        // Bound error body consumption. A gateway can return arbitrary HTML or an endless body.
+        const reader = response.body?.getReader();
+        const parts = [];
+        let bytes = 0;
+        if (reader) {
+            try {
+                while (bytes < 8192) {
+                    const item = await reader.read();
+                    if (item.done)
+                        break;
+                    const part = item.value.slice(0, 8192 - bytes);
+                    parts.push(part);
+                    bytes += part.length;
+                }
+            }
+            catch {
+                /* Preserve known HTTP status and headers when the error body is interrupted. */
+            }
+            finally {
+                try {
+                    await reader.cancel();
+                }
+                catch {
+                    /* Keep HTTP evidence. */
+                }
+            }
+        }
+        const joined = new Uint8Array(bytes);
+        let offset = 0;
+        for (const part of parts) {
+            joined.set(part, offset);
+            offset += part.length;
+        }
+        let envelope = {};
+        try {
+            const value = JSON.parse(new TextDecoder().decode(joined));
+            if (value && typeof value === "object")
+                envelope =
+                    value.error && typeof value.error === "object" ? value.error : value;
+        }
+        catch {
+            /* HTML, empty, and malformed JSON retain status and headers. */
+        }
+        const retryAfter = this.sanitize(response.headers.get("retry-after"));
+        const seconds = retryAfter ? Number(retryAfter) : NaN;
+        const date = retryAfter ? Date.parse(retryAfter) : NaN;
+        const retryAfterMs = Number.isFinite(seconds) && seconds >= 0
+            ? seconds * 1000
+            : Number.isFinite(date)
+                ? Math.max(0, date - Date.now())
+                : undefined;
+        return new APIError(this.sanitize(typeof envelope.message === "string" ? envelope.message : undefined) ?? `HTTP ${response.status} returned an unsuccessful response.`, {
+            status: response.status,
+            code: this.sanitize(typeof envelope.code === "string" ? envelope.code : undefined) ?? `HTTP_${response.status}`,
+            retryable: envelope.retryable === true,
+            requestId: this.sanitize(typeof envelope.requestId === "string"
+                ? envelope.requestId
+                : response.headers.get("x-request-id")),
+            retryAfter,
+            retryAfterMs,
+            sessionId,
+        });
+    }
+}

package/dist/types.d.ts

@@ -0,0 +1,186 @@
+export type Region = "west" | "asia";
+export type SessionStatus = "starting" | "ready" | "closing" | "closed" | "failed";
+export type Controller = "automation" | "human" | "none";
+export type HandoffStatus = "requested" | "active" | "returning" | "completed" | "cancelled";
+export type FileStatus = "uploading" | "downloading" | "ready" | "failed" | "deleted";
+export interface ResourceError {
+    code: string;
+    message?: string;
+}
+export interface HandoffSummary {
+    id: string;
+    status: HandoffStatus;
+    reason: string;
+    createdAt: string;
+    completedAt: string | null;
+}
+export interface Handoff extends HandoffSummary {
+    browserSessionId: string;
+}
+export interface BrowserSession {
+    id: string;
+    projectId: string;
+    region: Region;
+    status: SessionStatus;
+    controller: Controller;
+    /** Decimal bigint string. Never convert this value to a JS Number. */
+    controlEpoch: string;
+    /** The active handoff only; completed handoffs remain in latestHandoff. */
+    handoffId: string | null;
+    latestHandoff: HandoffSummary | null;
+    timeoutSeconds: number;
+    idleTimeoutSeconds?: number | null;
+    lastActivityAt?: string | null;
+    createdAt: string;
+    startupDeadlineAt: string;
+    startedAt: string | null;
+    expiresAt: string | null;
+    endedAt: string | null;
+    releasedAt: string | null;
+    closeReason: string | null;
+    downloadDirectory: string | null;
+    error: ResourceError | null;
+    metadata: Record<string, string>;
+    browser?: BrowserOptions;
+    profile?: {
+        id: string;
+        persistOnClose: boolean;
+        saveStatus: "not_requested" | "pending" | "saved" | "failed";
+        saveError: ResourceError | null;
+    } | null;
+}
+export interface BrowserOptions {
+    locale?: string;
+    timezone?: string;
+    userAgent?: string;
+    headless?: boolean;
+    geolocation?: {
+        latitude: number;
+        longitude: number;
+        accuracy?: number;
+    };
+    permissions?: {
+        origin: string;
+        permissions: ("geolocation" | "notifications" | "clipboard-read" | "clipboard-write")[];
+    }[];
+    extensions?: "block-images"[];
+}
+export interface Profile {
+    id: string;
+    projectId: string;
+    name: string;
+    createdAt: string;
+    updatedAt: string;
+    version: number;
+    inUse: boolean;
+}
+export interface SessionCreateParams {
+    browser?: BrowserOptions;
+    profile?: {
+        id: string;
+        persistOnClose?: boolean;
+    };
+    region?: "auto" | Region;
+    timeoutSeconds?: number;
+    idleTimeoutSeconds?: number | null;
+    viewport?: {
+        width: number;
+        height: number;
+    };
+    metadata?: Record<string, string>;
+}
+export interface SessionUpdateParams {
+    /** New total running lifetime from startedAt, 60–3600 seconds; cannot decrease. */
+    timeoutSeconds?: number;
+    /** null disables idle expiry. Reading state or viewing Live does not renew it. */
+    idleTimeoutSeconds?: number | null;
+}
+export type ConnectionCreateParams = {
+    type: "cdp";
+} | {
+    type: "live";
+    mode: "view";
+} | {
+    type: "live";
+    mode: "control";
+    handoffId: string;
+};
+export interface ConnectionGrant {
+    type: "cdp" | "live";
+    mode?: "view" | "control";
+    /** Secret grant URL. SDK inspection/JSON serialization redacts this field. */
+    url: string;
+    expiresAt: string;
+}
+export interface SessionFile {
+    id: string;
+    origin: "upload" | "download";
+    status: FileStatus;
+    filename: string;
+    contentType: string;
+    sizeBytes: number;
+    /** A path inside the remote browser, not a local filename. */
+    browserPath: string;
+    error: ResourceError | null;
+    createdAt: string;
+}
+export interface Page<T> {
+    items: T[];
+    nextCursor: string | null;
+}
+export interface SessionListParams {
+    limit?: number;
+    status?: SessionStatus;
+    cursor?: string;
+}
+export interface FileListParams {
+    limit?: number;
+    origin?: "upload" | "download";
+    cursor?: string;
+}
+export interface RequestOptions {
+    signal?: AbortSignal;
+    /** Per HTTP attempt, including JSON response consumption. */
+    requestTimeoutMs?: number;
+    /** Entire logical request, including retries and backoff. */
+    timeoutMs?: number;
+    maxRetries?: number;
+    /** Used only by session/handoff creation. */
+    idempotencyKey?: string;
+}
+export interface WaitOptions extends Omit<RequestOptions, "idempotencyKey"> {
+    pollIntervalMs?: number;
+}
+export interface HandoffCheckpoint {
+    controlEpoch: string;
+    latestHandoffId: string | null;
+}
+export interface HandoffWaitOptions extends WaitOptions {
+    after: HandoffCheckpoint;
+}
+export interface WithSessionOptions extends SessionCreateParams, RequestOptions {
+    /** Opt in to retrying confirmed capacity rejection within one acquisition deadline. */
+    waitForCapacity?: boolean;
+    /** Entire acquisition phase, including capacity waiting and ready. Defaults to 5 minutes when waitForCapacity is enabled. */
+    timeoutMs?: number;
+    readyTimeoutMs?: number;
+    /** Independent cleanup budget; caller cancellation does not cancel cleanup. */
+    cleanupTimeoutMs?: number;
+    pollIntervalMs?: number;
+}
+export interface FileUploadParams {
+    file: Blob | Uint8Array | ReadableStream<Uint8Array> | AsyncIterable<Uint8Array>;
+    filename: string;
+    contentType?: string;
+    /** Supply the exact content size when known for a stream. */
+    sizeBytes?: number;
+}
+export interface TabSailOptions {
+    /** Instance root URL; the SDK appends /v1. Defaults to TABSAIL_BASE_URL. */
+    baseURL?: string;
+    /** Defaults to TABSAIL_API_KEY. */
+    apiKey?: string;
+    requestTimeoutMs?: number;
+    maxRetries?: number;
+    fetch?: typeof globalThis.fetch;
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/updates.d.ts

@@ -0,0 +1,4 @@
+import { type Transport } from "./transport.js";
+import type { BrowserSession, WaitOptions } from "./types.js";
+/** Snapshot subscription. Reconnects resume from current state, never replaying browser actions. */
+export declare function sessionUpdates(transport: Transport, path: string, sessionId: string, options?: WaitOptions): AsyncGenerator<BrowserSession>;

package/dist/updates.js

@@ -0,0 +1,111 @@
+import { APIError, NetworkError, ProtocolError, RequestTimeoutError, WaitTimeoutError, } from "./errors.js";
+import { parseSession } from "./protocol.js";
+import { positive, sleep, } from "./transport.js";
+/** Snapshot subscription. Reconnects resume from current state, never replaying browser actions. */
+export async function* sessionUpdates(transport, path, sessionId, options = {}) {
+    const deadline = performance.now() + positive(options.timeoutMs ?? 300_000, "timeoutMs");
+    const interval = positive(options.pollIntervalMs ?? 500, "pollIntervalMs");
+    let fallback = false;
+    const bounded = () => {
+        const left = deadline - performance.now();
+        if (left <= 0)
+            throw new WaitTimeoutError("The snapshot subscription deadline elapsed.", { code: "WAIT_TIMEOUT", sessionId });
+        return { ...options, timeoutMs: left };
+    };
+    // Preserve immediate terminal-state detection, including against older servers.
+    try {
+        yield await transport.request({ method: "GET", path, sessionId, replayable: true, parse: parseSession }, bounded());
+    }
+    catch (error) {
+        if (error instanceof RequestTimeoutError &&
+            (error.code === "OPERATION_TIMEOUT" || performance.now() >= deadline))
+            throw new WaitTimeoutError("The snapshot subscription deadline elapsed.", { code: "WAIT_TIMEOUT", sessionId });
+        throw error;
+    }
+    while (true) {
+        let stream;
+        try {
+            if (fallback) {
+                await sleep(Math.min(interval, bounded().timeoutMs), options.signal, sessionId);
+                yield await transport.request({
+                    method: "GET",
+                    path,
+                    sessionId,
+                    replayable: true,
+                    parse: parseSession,
+                }, bounded());
+                continue;
+            }
+            stream = await transport.request({
+                method: "GET",
+                path: `${path}/events`,
+                sessionId,
+                replayable: true,
+                streaming: true,
+                headers: { Accept: "text/event-stream" },
+            }, bounded());
+            if (!stream.headers.get("content-type")?.includes("text/event-stream")) {
+                fallback = true;
+                if (stream.headers.get("content-type")?.includes("application/json")) {
+                    let text = "";
+                    const decoder = new TextDecoder();
+                    for await (const chunk of stream) {
+                        text += decoder.decode(chunk, { stream: true });
+                        if (text.length > 1024 * 1024)
+                            throw new ProtocolError("Snapshot exceeds limit.", { sessionId });
+                    }
+                    let snapshot;
+                    try {
+                        snapshot = JSON.parse(text);
+                    }
+                    catch {
+                        throw new ProtocolError("Invalid snapshot JSON.", { sessionId });
+                    }
+                    yield parseSession(snapshot);
+                }
+                continue;
+            }
+            const decoder = new TextDecoder();
+            let buffer = "";
+            for await (const chunk of stream) {
+                buffer = (buffer + decoder.decode(chunk, { stream: true })).replace(/\r\n/g, "\n");
+                if (buffer.length > 1024 * 1024)
+                    throw new ProtocolError("Snapshot frame exceeds limit.", {
+                        sessionId,
+                    });
+                while (buffer.includes("\n\n")) {
+                    const end = buffer.indexOf("\n\n");
+                    const event = buffer.slice(0, end);
+                    buffer = buffer.slice(end + 2);
+                    if (!event.split("\n").includes("event: snapshot"))
+                        continue;
+                    const data = event
+                        .split("\n")
+                        .filter((line) => line.startsWith("data:"))
+                        .map((line) => line.slice(5).trimStart())
+                        .join("\n");
+                    let value;
+                    try {
+                        value = JSON.parse(data);
+                    }
+                    catch {
+                        throw new ProtocolError("Invalid snapshot JSON.", { sessionId });
+                    }
+                    yield parseSession(value);
+                }
+            }
+        }
+        catch (error) {
+            if (error instanceof APIError &&
+                [404, 405, 406].includes(error.status ?? 0))
+                fallback = true;
+            else if (!(error instanceof NetworkError || error instanceof RequestTimeoutError))
+                throw error;
+            bounded();
+        }
+        finally {
+            await stream?.close();
+        }
+        await sleep(Math.min(interval, bounded().timeoutMs), options.signal, sessionId);
+    }
+}