tabsail 0.0.0-stage → 0.1.0

package/dist/resources.d.ts

@@ -0,0 +1,59 @@
+import { type FileDownload, type Transport } from "./transport.js";
+import type { BrowserSession, ConnectionCreateParams, ConnectionGrant, FileListParams, FileUploadParams, Handoff, HandoffCheckpoint, HandoffWaitOptions, Page, RequestOptions, SessionCreateParams, SessionFile, SessionListParams, SessionUpdateParams, WaitOptions } from "./types.js";
+export declare class Profiles {
+    private transport;
+    constructor(transport: Transport);
+    create(params: {
+        name: string;
+    }, options?: RequestOptions): Promise<import("./types.js").Profile>;
+    get(profileId: string, options?: RequestOptions): Promise<import("./types.js").Profile>;
+    list(params?: {
+        limit?: number;
+        cursor?: string;
+    }, options?: RequestOptions): Promise<Page<import("./types.js").Profile>>;
+    delete(profileId: string, options?: RequestOptions): Promise<void>;
+}
+export declare function handoffCheckpoint(session: BrowserSession): HandoffCheckpoint;
+export declare class Connections {
+    private transport;
+    constructor(transport: Transport);
+    create(sessionId: string, params: ConnectionCreateParams, options?: RequestOptions): Promise<ConnectionGrant>;
+}
+export declare class Handoffs {
+    private transport;
+    private sessions;
+    constructor(transport: Transport, sessions: Sessions);
+    create(sessionId: string, params?: {
+        reason?: string;
+    }, options?: RequestOptions): Promise<Handoff>;
+    get(sessionId: string, handoffId: string, options?: RequestOptions): Promise<Handoff>;
+    complete(sessionId: string, handoffId: string, options?: RequestOptions): Promise<Handoff>;
+    waitUntilCompleted(sessionId: string, handoffId: string, options?: WaitOptions): Promise<Handoff>;
+}
+export declare class Files {
+    private transport;
+    constructor(transport: Transport);
+    upload(sessionId: string, params: FileUploadParams, options?: RequestOptions): Promise<SessionFile>;
+    list(sessionId: string, params?: FileListParams, options?: RequestOptions): Promise<Page<SessionFile>>;
+    get(sessionId: string, fileId: string, options?: RequestOptions): Promise<SessionFile>;
+    download(sessionId: string, fileId: string, options?: RequestOptions): Promise<FileDownload>;
+    delete(sessionId: string, fileId: string, options?: RequestOptions): Promise<void>;
+}
+export declare class Sessions {
+    private transport;
+    readonly connections: Connections;
+    readonly handoffs: Handoffs;
+    readonly files: Files;
+    constructor(transport: Transport);
+    /** Latest complete state snapshots, including an initial state and reconnect resynchronization. */
+    watch(sessionId: string, options?: WaitOptions): AsyncGenerator<BrowserSession>;
+    create(params?: SessionCreateParams, options?: RequestOptions): Promise<BrowserSession>;
+    get(sessionId: string, options?: RequestOptions): Promise<BrowserSession>;
+    list(params?: SessionListParams, options?: RequestOptions): Promise<Page<BrowserSession>>;
+    update(sessionId: string, params: SessionUpdateParams, options?: RequestOptions): Promise<BrowserSession>;
+    touch(sessionId: string, options?: RequestOptions): Promise<BrowserSession>;
+    close(sessionId: string, options?: RequestOptions): Promise<BrowserSession>;
+    waitUntilReady(sessionId: string, options?: WaitOptions): Promise<BrowserSession>;
+    waitUntilReleased(sessionId: string, options?: WaitOptions): Promise<BrowserSession>;
+    waitForHandoff(sessionId: string, options: HandoffWaitOptions): Promise<BrowserSession>;
+}

package/dist/resources.js

@@ -0,0 +1,472 @@
+import { ConfigurationError, HandoffCancelledError, RequestTimeoutError, SessionTerminatedError, WaitTimeoutError, } from "./errors.js";
+import { parseFile, parseGrant, parseHandoff, parsePage, parseProfile, parseSession, } from "./protocol.js";
+import { checkCancelled, operationKey, positive, sleep, } from "./transport.js";
+import { sessionUpdates } from "./updates.js";
+export class Profiles {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    create(params, options = {}) {
+        return this.transport.request({
+            method: "POST",
+            path: "profiles",
+            json: params,
+            key: operationKey(options.idempotencyKey),
+            replayable: true,
+            uncertain: "profile.create",
+            parse: parseProfile,
+        }, options);
+    }
+    get(profileId, options = {}) {
+        return this.transport.request({
+            method: "GET",
+            path: `profiles/${segment(profileId)}`,
+            replayable: true,
+            parse: parseProfile,
+        }, options);
+    }
+    list(params = {}, options = {}) {
+        return this.transport.request({
+            method: "GET",
+            path: `profiles${query(params)}`,
+            replayable: true,
+            parse: parsePage(parseProfile),
+        }, options);
+    }
+    delete(profileId, options = {}) {
+        return this.transport.request({
+            method: "DELETE",
+            path: `profiles/${segment(profileId)}`,
+            replayable: true,
+        }, options);
+    }
+}
+function segment(value) {
+    if (!value || value === "." || value === "..")
+        throw new ConfigurationError("Resource IDs must be nonempty path segments.", { code: "INVALID_PATH" });
+    return encodeURIComponent(value);
+}
+function path(session) {
+    return `browser-sessions/${segment(session)}`;
+}
+function query(values) {
+    const search = new URLSearchParams();
+    for (const [key, value] of Object.entries(values))
+        if (value !== undefined)
+            search.set(key, String(value));
+    return search.size ? `?${search}` : "";
+}
+function ended(session) {
+    throw new SessionTerminatedError(`BrowserSession ended in ${session.status} state.`, {
+        code: session.error?.code ?? "SESSION_ENDED",
+        sessionId: session.id,
+    });
+}
+export function handoffCheckpoint(session) {
+    if (session.status !== "ready" || session.controller !== "automation")
+        throw new ConfigurationError("A handoff checkpoint requires the same stable ready + automation snapshot.", { code: "UNSTABLE_CHECKPOINT", sessionId: session.id });
+    if (!/^(0|[1-9]\d*)$/.test(session.controlEpoch))
+        throw new ConfigurationError("controlEpoch must be a decimal bigint string.", { code: "INVALID_CHECKPOINT", sessionId: session.id });
+    return {
+        controlEpoch: session.controlEpoch,
+        latestHandoffId: session.latestHandoff?.id ?? null,
+    };
+}
+class WaitBudget {
+    options;
+    sessionId;
+    label;
+    deadline;
+    interval;
+    constructor(options, sessionId, label, fallback) {
+        this.options = options;
+        this.sessionId = sessionId;
+        this.label = label;
+        this.deadline =
+            performance.now() + positive(options.timeoutMs ?? fallback, "timeoutMs");
+        this.interval = positive(options.pollIntervalMs ?? 500, "pollIntervalMs");
+    }
+    remaining() {
+        checkCancelled(this.options.signal, this.sessionId);
+        const left = this.deadline - performance.now();
+        if (left <= 0)
+            this.expired();
+        return left;
+    }
+    expired() {
+        throw new WaitTimeoutError(`${this.label} exceeded its total deadline.`, {
+            code: "WAIT_TIMEOUT",
+            sessionId: this.sessionId,
+        });
+    }
+    async request(call) {
+        const left = this.remaining();
+        try {
+            return await call({ ...this.options, timeoutMs: left });
+        }
+        catch (error) {
+            checkCancelled(this.options.signal, this.sessionId);
+            if (performance.now() >= this.deadline ||
+                (error instanceof RequestTimeoutError &&
+                    error.code === "OPERATION_TIMEOUT"))
+                this.expired();
+            throw error;
+        }
+    }
+    async pause() {
+        await sleep(Math.min(this.interval, this.remaining()), this.options.signal, this.sessionId);
+    }
+}
+export class Connections {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    create(sessionId, params, options = {}) {
+        return this.transport.request({
+            method: "POST",
+            path: `${path(sessionId)}/connections`,
+            sessionId,
+            json: params,
+            replayable: false,
+            uncertain: "connection.create",
+            parse: parseGrant,
+        }, options);
+    }
+}
+export class Handoffs {
+    transport;
+    sessions;
+    constructor(transport, sessions) {
+        this.transport = transport;
+        this.sessions = sessions;
+    }
+    create(sessionId, params = {}, options = {}) {
+        return this.transport.request({
+            method: "POST",
+            path: `${path(sessionId)}/handoffs`,
+            sessionId,
+            json: params,
+            key: operationKey(options.idempotencyKey),
+            replayable: true,
+            uncertain: "handoff.create",
+            parse: parseHandoff,
+        }, options);
+    }
+    get(sessionId, handoffId, options = {}) {
+        return this.transport.request({
+            method: "GET",
+            path: `${path(sessionId)}/handoffs/${segment(handoffId)}`,
+            sessionId,
+            replayable: true,
+            parse: parseHandoff,
+        }, options);
+    }
+    complete(sessionId, handoffId, options = {}) {
+        return this.transport.request({
+            method: "POST",
+            path: `${path(sessionId)}/handoffs/${segment(handoffId)}/complete`,
+            sessionId,
+            replayable: true,
+            parse: parseHandoff,
+        }, options);
+    }
+    async waitUntilCompleted(sessionId, handoffId, options = {}) {
+        const budget = new WaitBudget(options, sessionId, "Waiting for handoff completion", 300_000);
+        for await (const session of this.sessions.watch(sessionId, {
+            ...options,
+            timeoutMs: budget.remaining(),
+        })) {
+            const handoff = await budget.request((opts) => this.get(sessionId, handoffId, opts));
+            if (handoff.status === "cancelled")
+                throw new HandoffCancelledError("The handoff was cancelled.", {
+                    code: "HANDOFF_CANCELLED",
+                    sessionId,
+                });
+            if (session.status !== "ready")
+                ended(session);
+            if (handoff.status === "completed")
+                return handoff;
+        }
+        return budget.expired();
+    }
+}
+function multipart(params) {
+    if (!params.filename || /[\r\n\0\\/]/.test(params.filename))
+        throw new ConfigurationError("Upload filename must be a plain filename without control characters.", { code: "INVALID_FILENAME" });
+    const type = params.contentType ??
+        ((params.file instanceof Blob && params.file.type) ||
+            "application/octet-stream");
+    if (/[\r\n\0]/.test(type))
+        throw new ConfigurationError("Upload contentType cannot contain control characters.", { code: "INVALID_UPLOAD" });
+    const boundary = `tabsail-${crypto.randomUUID()}`;
+    const encoder = new TextEncoder();
+    const prefix = encoder.encode(`--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${params.filename.replace(/"/g, "%22")}"\r\nContent-Type: ${type}\r\n\r\n`);
+    const suffix = encoder.encode(`\r\n--${boundary}--\r\n`);
+    const knownSize = params.file instanceof Blob
+        ? params.file.size
+        : params.file instanceof Uint8Array
+            ? params.file.byteLength
+            : params.sizeBytes;
+    if (params.sizeBytes !== undefined &&
+        (!Number.isSafeInteger(params.sizeBytes) ||
+            params.sizeBytes < 0 ||
+            (knownSize !== undefined && params.sizeBytes !== knownSize)))
+        throw new ConfigurationError("sizeBytes must match the upload content length.", { code: "INVALID_UPLOAD" });
+    async function* bytes() {
+        yield prefix;
+        let sent = 0;
+        const source = params.file instanceof Blob ? params.file.stream() : params.file;
+        if (source instanceof Uint8Array) {
+            sent = source.byteLength;
+            yield source;
+        }
+        else {
+            const iterator = source instanceof ReadableStream ? streamIterator(source) : source;
+            for await (const part of iterator) {
+                if (!(part instanceof Uint8Array))
+                    throw new ConfigurationError("Upload streams must yield Uint8Array chunks.", { code: "INVALID_UPLOAD" });
+                sent += part.byteLength;
+                if (knownSize !== undefined && sent > knownSize)
+                    throw new ConfigurationError("Upload exceeded its declared sizeBytes.", { code: "INVALID_UPLOAD" });
+                yield part;
+            }
+        }
+        if (knownSize !== undefined && sent !== knownSize)
+            throw new ConfigurationError("Upload length differs from sizeBytes.", {
+                code: "INVALID_UPLOAD",
+            });
+        yield suffix;
+    }
+    const iterator = bytes();
+    const body = new ReadableStream({
+        async pull(controller) {
+            try {
+                const item = await iterator.next();
+                if (item.done)
+                    controller.close();
+                else
+                    controller.enqueue(item.value);
+            }
+            catch (error) {
+                controller.error(error);
+            }
+        },
+        async cancel() {
+            await iterator.return(undefined);
+        },
+    }, { highWaterMark: 0 });
+    return {
+        body,
+        headers: {
+            "Content-Type": `multipart/form-data; boundary=${boundary}`,
+            ...(knownSize === undefined
+                ? {}
+                : {
+                    "Content-Length": String(prefix.byteLength + knownSize + suffix.byteLength),
+                }),
+        },
+    };
+}
+async function* streamIterator(stream) {
+    const reader = stream.getReader();
+    let completed = false;
+    try {
+        while (true) {
+            const item = await reader.read();
+            if (item.done) {
+                completed = true;
+                return;
+            }
+            yield item.value;
+        }
+    }
+    finally {
+        if (!completed)
+            await reader.cancel();
+        reader.releaseLock();
+    }
+}
+export class Files {
+    transport;
+    constructor(transport) {
+        this.transport = transport;
+    }
+    upload(sessionId, params, options = {}) {
+        checkCancelled(options.signal, sessionId);
+        const upload = multipart(params);
+        return this.transport.request({
+            method: "POST",
+            path: `${path(sessionId)}/files`,
+            sessionId,
+            ...upload,
+            replayable: false,
+            uncertain: "file.upload",
+            parse: parseFile,
+        }, options);
+    }
+    list(sessionId, params = {}, options = {}) {
+        return this.transport.request({
+            method: "GET",
+            path: `${path(sessionId)}/files${query(params)}`,
+            sessionId,
+            replayable: true,
+            parse: parsePage(parseFile),
+        }, options);
+    }
+    get(sessionId, fileId, options = {}) {
+        return this.transport.request({
+            method: "GET",
+            path: `${path(sessionId)}/files/${segment(fileId)}`,
+            sessionId,
+            replayable: true,
+            parse: parseFile,
+        }, options);
+    }
+    download(sessionId, fileId, options = {}) {
+        return this.transport.request({
+            method: "GET",
+            path: `${path(sessionId)}/files/${segment(fileId)}/content`,
+            sessionId,
+            replayable: true,
+            streaming: true,
+        }, options);
+    }
+    delete(sessionId, fileId, options = {}) {
+        return this.transport.request({
+            method: "DELETE",
+            path: `${path(sessionId)}/files/${segment(fileId)}`,
+            sessionId,
+            replayable: true,
+        }, options);
+    }
+}
+export class Sessions {
+    transport;
+    connections;
+    handoffs;
+    files;
+    constructor(transport) {
+        this.transport = transport;
+        this.connections = new Connections(transport);
+        this.handoffs = new Handoffs(transport, this);
+        this.files = new Files(transport);
+    }
+    /** Latest complete state snapshots, including an initial state and reconnect resynchronization. */
+    watch(sessionId, options = {}) {
+        return sessionUpdates(this.transport, path(sessionId), sessionId, options);
+    }
+    create(params = {}, options = {}) {
+        return this.transport.request({
+            method: "POST",
+            path: "browser-sessions",
+            json: params,
+            key: operationKey(options.idempotencyKey),
+            replayable: true,
+            uncertain: "session.create",
+            parse: parseSession,
+        }, options);
+    }
+    get(sessionId, options = {}) {
+        return this.transport.request({
+            method: "GET",
+            path: path(sessionId),
+            sessionId,
+            replayable: true,
+            parse: parseSession,
+        }, options);
+    }
+    list(params = {}, options = {}) {
+        return this.transport.request({
+            method: "GET",
+            path: `browser-sessions${query(params)}`,
+            replayable: true,
+            parse: parsePage(parseSession),
+        }, options);
+    }
+    update(sessionId, params, options = {}) {
+        return this.transport.request({
+            method: "PATCH",
+            path: path(sessionId),
+            sessionId,
+            json: params,
+            replayable: true,
+            parse: parseSession,
+        }, options);
+    }
+    touch(sessionId, options = {}) {
+        return this.transport.request({
+            method: "POST",
+            path: `${path(sessionId)}/touch`,
+            sessionId,
+            replayable: true,
+            parse: parseSession,
+        }, options);
+    }
+    close(sessionId, options = {}) {
+        return this.transport.request({
+            method: "POST",
+            path: `${path(sessionId)}/close`,
+            sessionId,
+            replayable: true,
+            parse: parseSession,
+        }, options);
+    }
+    async waitUntilReady(sessionId, options = {}) {
+        const budget = new WaitBudget(options, sessionId, "Waiting for session readiness", 60_000);
+        for await (const session of this.watch(sessionId, {
+            ...options,
+            timeoutMs: budget.remaining(),
+        })) {
+            if (session.status === "ready")
+                return session;
+            if (session.status !== "starting")
+                ended(session);
+        }
+        return budget.expired();
+    }
+    async waitUntilReleased(sessionId, options = {}) {
+        const budget = new WaitBudget(options, sessionId, "Waiting for session release", 30_000);
+        for await (const session of this.watch(sessionId, {
+            ...options,
+            timeoutMs: budget.remaining(),
+        })) {
+            if (session.releasedAt !== null)
+                return session;
+        }
+        return budget.expired();
+    }
+    async waitForHandoff(sessionId, options) {
+        const after = options.after;
+        if (!after ||
+            typeof after.controlEpoch !== "string" ||
+            !/^(0|[1-9]\d*)$/.test(after.controlEpoch) ||
+            !(after.latestHandoffId === null ||
+                typeof after.latestHandoffId === "string"))
+            throw new ConfigurationError("after must be a stable handoffCheckpoint.", { code: "INVALID_CHECKPOINT", sessionId });
+        const epoch = BigInt(after.controlEpoch);
+        const budget = new WaitBudget(options, sessionId, "Waiting for handoff and automation control", 300_000);
+        for await (const session of this.watch(sessionId, {
+            ...options,
+            timeoutMs: budget.remaining(),
+        })) {
+            if (session.status !== "ready")
+                ended(session);
+            const handoff = session.latestHandoff;
+            if (BigInt(session.controlEpoch) > epoch &&
+                handoff &&
+                handoff.id !== after.latestHandoffId) {
+                if (handoff.status === "cancelled")
+                    throw new HandoffCancelledError("The handoff was cancelled.", {
+                        code: "HANDOFF_CANCELLED",
+                        sessionId,
+                    });
+                if (handoff.status === "completed" &&
+                    session.controller === "automation")
+                    return session;
+            }
+        }
+        return budget.expired();
+    }
+}

package/dist/transport.d.ts

@@ -0,0 +1,44 @@
+import { ResultUnknownError, TabSailError } from "./errors.js";
+import type { RequestOptions, TabSailOptions } from "./types.js";
+export declare function positive(value: number, name: string): number;
+export declare function retries(value: number): number;
+export declare function operationKey(value?: string): string;
+export declare function checkCancelled(signal?: AbortSignal, sessionId?: string): void;
+/** Retry-After is a floor; jitter must still spread callers when it is present. */
+export declare function retryDelay(attempt: number, retryAfterMs?: number, maximumBackoffMs?: number, random?: number): number;
+export declare function sleep(milliseconds: number, signal?: AbortSignal, sessionId?: string): Promise<void>;
+type RequestSpec<T> = {
+    method: "GET" | "POST" | "PATCH" | "DELETE";
+    path: string;
+    sessionId?: string;
+    json?: unknown;
+    body?: BodyInit;
+    headers?: Record<string, string>;
+    key?: string;
+    replayable: boolean;
+    uncertain?: ResultUnknownError["operation"];
+    parse?: (value: unknown) => T;
+    streaming?: boolean;
+};
+/** A streaming download. Consume its body or explicitly close it. */
+export declare class FileDownload implements AsyncIterable<Uint8Array>, AsyncDisposable {
+    #private;
+    readonly body: ReadableStream<Uint8Array>;
+    readonly headers: Headers;
+    readonly status: number;
+    constructor(response: Response, finish: () => void, abort: () => void, failure: (error: unknown) => TabSailError);
+    close(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    [Symbol.asyncIterator](): AsyncGenerator<Uint8Array<ArrayBufferLike>, void, unknown>;
+}
+export declare class Transport {
+    #private;
+    readonly requestTimeoutMs: number;
+    readonly maxRetries: number;
+    constructor(options: TabSailOptions);
+    safe(error: unknown, sessionId?: string): TabSailError;
+    request<T>(spec: RequestSpec<T>, options?: RequestOptions): Promise<T>;
+    private sanitize;
+    private httpError;
+}
+export {};