tabsail 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,135 @@
-# Temporary Holding Version
+# TabSail TypeScript SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Hosted endpoint: `https://tabsail.com`. Set `TABSAIL_BASE_URL=https://tabsail.com` and `TABSAIL_API_KEY` to your project key. For local or separate deployments, use that instance's root URL.
+
+ESM client for Node.js 24. Package `tabsail`, version `0.1.0`, manages TabSail v1 browser resources. It has no runtime dependencies on Playwright, models, Docker, or platform internals.
+
+Fund the Tenant through the console before creating a browser. At the base rate of 100 credits/hour, each billable session rounds up to whole credits (minimum 1 credit, or one per started 36 seconds). The maximum-duration budget is also rounded up before reservation; unused credits are released and platform failures are free. Raw duration remains measured in milliseconds; $1 purchases 1,000 credits. `402 INSUFFICIENT_CREDITS` and `403 BILLING_FROZEN` are final admission refusals and never enter capacity waiting. Creating another Project or Key does not add credits or concurrency.
+
+Install from npm:
+
+```sh
+pnpm add tabsail@0.1.0
+```
+
+```ts
+import { TabSail } from "tabsail";
+import { chromium } from "playwright"; // separately installed by your application
+
+const client = new TabSail({
+  baseURL: process.env.TABSAIL_BASE_URL,
+  apiKey: process.env.TABSAIL_API_KEY,
+});
+await client.withSession({ timeoutSeconds: 900 }, async session => {
+  const grant = await client.sessions.connections.create(session.id, { type: "cdp" });
+  const browser = await chromium.connectOverCDP(grant.url);
+  try {
+    const page = browser.contexts()[0].pages()[0];
+    await page.goto("https://example.com");
+  } finally { await browser.close(); }
+});
+```
+
+`baseURL` is the instance root, such as `http://localhost:8080`; trailing slashes are normalized and `/v1` is appended. It cannot contain credentials, a path prefix, query, or fragment. Configuration defaults only to the two environment variables shown above. The SDK never searches local secret files and does not follow HTTP redirects. Keep Project Keys in your application, outside model prompts and browser pages.
+
+For Cloudflare Workers, pass `baseURL` and `apiKey` explicitly from Worker bindings. Native fetch works without a caller wrapper, including when supplied through the optional `fetch` setting. The HTTP transport has a workerd regression using compatibility date `2026-10-12` with `nodejs_compat` and `no_nodejs_global_timers`. This does not qualify an application's CDP client, embedded viewer, or Durable Object recovery. Run `pnpm --filter tabsail test` from the repository root for the Node and workerd regressions; the workerd test intercepts all outbound requests and uses no real credentials.
+
+The resource surface covers `sessions.create/get/list/close`, `sessions.connections.create`, `sessions.handoffs.create/get/complete`, and `sessions.files.upload/list/get/download/delete`. List responses expose `items` and `nextCursor`; pass the cursor explicitly for the next page. Create parameters omit server defaults unless you provide them. Close and complete send empty HTTP bodies.
+
+```ts
+import { handoffCheckpoint } from "tabsail";
+
+const stable = await client.sessions.get(sessionId); // ready + automation
+const after = handoffCheckpoint(stable);
+const resumed = await client.sessions.waitForHandoff(sessionId, { after, timeoutMs: 300_000 });
+const nextBaseline = handoffCheckpoint(resumed);
+```
+
+`waitForHandoff` returns a new stable `BrowserSession` after a later handoff has completed and the same resource snapshot shows automation control. It can observe a handoff that completed entirely between observations. It compares decimal `controlEpoch` strings as bigint and never reuses an already observed completed handoff. Each return supplies the next stable checkpoint. It observes the latest handoff and current control; it is not a subscription to every historical event. `handoffs.waitUntilCompleted(sessionId, handoffId)` waits for that exact handoff; its return does not promise no subsequent handoff started. Recheck stable automation before authorizing CDP.
+
+Readiness, release and handoff helpers use an authenticated SSE snapshot subscription after the initial GET. Each reconnect reads the latest complete state; no webpage action or callback is replayed. Against older servers without the endpoint, helpers retain polling compatibility. `pollIntervalMs` controls that fallback and reconnect backoff, rather than normal update delivery.
+
+```ts
+for await (const snapshot of client.sessions.watch(sessionId, { signal, timeoutMs: 300_000 })) {
+  console.log(snapshot.status, snapshot.controller);
+  if (snapshot.releasedAt) break;
+}
+```
+
+Breaking iteration closes the local stream. A watch does not close the remote browser. Authentication revocation, explicit cancellation and total deadlines remain enforced.
+
+After handoff or a natural connection loss, obtain a fresh grant, reconnect the same BrowserSession, retrieve its existing context/page again, and observe the current page. The SDK never replays webpage actions or the callback. Use explicit `sessions.create` if you need a browser to remain open for a human. Disconnecting a Playwright browser does not release the remote session.
+
+`withSession(options, callback)` owns only the session created by its logical request, waits for ready, gives the callback a typed session resource once, then closes and waits for `releasedAt`. Caller cancellation does not cancel cleanup. Unknown creation results use the original parameters and the same key within an independent cleanup budget to acquire one resource and immediately close it. If the first attempt never reached the server, recovery can briefly create a new resource. `CleanupError` preserves `primaryError`, `cleanupError`, `sessionId`, and a directly accessible `operationKey` for recovery; cleanup failure never substitutes a successful release claim. A failed resource remains occupied until `releasedAt` is present. The SDK uses native fetch and owns no separate connection pool; discarding the client does not close remote sessions.
+
+Time values have separate roles:
+
+| Option | Meaning | Default |
+| --- | --- | --- |
+| `timeoutSeconds` | Remote session lifespan | Server chooses |
+| `requestTimeoutMs` | One HTTP attempt, including response consumption | 15,000 |
+| Request `timeoutMs` | Entire request including retries/backoff | Attempt budget plus 30,000 |
+| `withSession` `timeoutMs` | Entire create + ready acquisition phase | Separate creation and ready budgets when omitted |
+| Wait `timeoutMs` | Entire polling helper including in-flight requests | Ready 60,000; release 30,000; handoff 300,000 |
+| `pollIntervalMs` | Polling interval | 500 |
+| `readyTimeoutMs` | Ready helper inside `withSession` | 60,000 |
+| `cleanupTimeoutMs` | Independent recovery/close/release budget | 30,000 |
+| `maxRetries` | Explicit extra safe HTTP attempts | 0 |
+
+All calls accept an `AbortSignal`. Wait helpers include request duration and backoff in their total deadline. `withSession` `timeoutMs` covers creation plus waiting for ready; its readiness wait uses the smaller of `readyTimeoutMs` and the remaining total budget. Cleanup retains its independent budget after acquisition fails. The callback's own tool deadlines and cancellation are the application's responsibility through its tools/signal; the SDK never automatically reruns it. Ordinary resource `timeoutMs` covers that logical HTTP request. SDK transport waits honor cancellation immediately.
+
+Session and handoff creation generate one fixed `Idempotency-Key` per logical call; supply `idempotencyKey` to recover across processes. Replays can return the original starting snapshot: call `get` or `waitUntilReady` to obtain current state. Explicit retries cover network failure and retryable 429/503 on reads or operations with a known idempotent contract. Exponential backoff starts with a 250 ms window, capped at 5 seconds, with a random wait between half and all of that window **added after** `Retry-After`. The server's minimum delay is never shortened; the overall deadline can end the call before another attempt. Authentication, permissions, validation, and conflicts do not retry. Connections and uploads are never automatically replayed. A lost response throws `ResultUnknownError`; 5xx mutation errors also represent an unknown result because a gateway or service can fail after acceptance. Its `originalError` preserves HTTP status and request ID. Explicit `NO_CAPACITY` and `STARTUP_BUSY` remain immediate API errors by default. Upload recovery requires inspecting the session, not sending a duplicate file.
+
+`withSession({ waitForCapacity: true }, callback)` waits for `503 NO_CAPACITY/STARTUP_BUSY` and `429 CREATE_RATE_LIMITED`, using one key and unchanged parameters. Its backoff window grows from 250 ms to 10 seconds with the same randomization after `Retry-After`. The default total create + ready budget is 300,000 ms (override `timeoutMs`); `readyTimeoutMs` still bounds startup. Cancellation interrupts waiting. Tenant concurrency limits, insufficient credits and billing freezes are not capacity waits. No queue position or eventual allocation is promised; confirmed refusals do not create cleanup work. The callback is never replayed.
+
+```ts
+const uploaded = await client.sessions.files.upload(sessionId, {
+  file: new Blob([new Uint8Array([0, 128, 255])]),
+  filename: "图表.bin",
+});
+const download = await client.sessions.files.download(sessionId, uploaded.id);
+try {
+  for await (const bytes of download) { /* write each chunk to your destination */ }
+} finally { await download.close(); }
+```
+
+Upload accepts Blob, Uint8Array, ReadableStream, or AsyncIterable of Uint8Array. Stream input supports optional exact `sizeBytes`; multipart bodies stream without buffering the entire input. Downloads expose `body`, `headers`, `status`, an async iterator, `close`, and async disposal. Consuming the entire stream or closing it releases the local response. Breaking the SDK async iterator also closes it. Binary bytes and Unicode filenames retain their content. `browserPath` belongs to the remote browser; retrieve temporary files before session closure.
+
+Errors export `ConfigurationError`, `APIError`, `NetworkError`, `RequestTimeoutError`, `WaitTimeoutError`, `CancelledError`, `ProtocolError`, `ResultUnknownError`, `SessionTerminatedError`, `HandoffCancelledError`, and `CleanupError`. Common context is `status`, `code`, `retryable`, `requestId`, `retryAfter`, `retryAfterMs`, and `sessionId` when known. Unknown API codes remain APIError; unknown states fail as ProtocolError. Empty/HTML gateway errors retain HTTP context; 204 needs no JSON. SDK exception messages and transport causes redact keys and URLs. Grant URL access is explicit; grant JSON/inspection redacts it. Application code should also redact third party browser errors and avoid logging a spread/copied grant or its explicit URL.
+
+Run `pnpm --filter tabsail check`, `test`, and `test:consumer` from the repository. The consumer check packs the SDK and installs its tarball and TypeScript in a temporary directory outside the repository, then checks ESM exports, types, and lifecycle behavior. Real PG/Steel/CDP/Live acceptance is a separate platform gate.
+
+With elastic capacity, opt into bounded acquisition with `client.withSession({ waitForCapacity: true, timeoutMs: 300000 }, callback)`. The default total acquisition budget is five minutes when enabled and includes capacity retries and readiness. It keeps one idempotency key/body; only confirmed `NO_CAPACITY` / `STARTUP_BUSY` refusals wait. Tenant quota failures return immediately. The callback and browser lifetime are separate from this acquisition deadline.
+
+## Browser region
+
+Creation defaults to `region: "auto"`, using the API caller's public egress IP. Asia and Oceania use `asia`; other or unknown locations use `west`. A backend calling on behalf of users should override the region when its own location differs.
+
+```ts
+await client.withSession({ region: "asia", waitForCapacity: true }, async session => {
+  console.log(session.region); // actual "asia" or "west"
+});
+```
+
+`sessions.create({ region: "west" })` also accepts the override. Region stays fixed for retries with the same idempotency key, connections, files and the entire session. Capacity waiting stays in that region; switching regions requires a new creation request and key. Use the returned connection URL for CDP/Live.
+
+## Browser settings, lifetime, and Profiles
+
+With an initialized client:
+
+```typescript
+const profile = await client.profiles.create({ name: "Report login" });
+await client.withSession({
+  browser: { locale: "en-US", timezone: "Asia/Tokyo", headless: true },
+  idleTimeoutSeconds: 120,
+  profile: { id: profile.id, persistOnClose: true },
+}, async session => {
+  await client.sessions.update(session.id, { timeoutSeconds: 1200 });
+  await client.sessions.touch(session.id);
+  // Connect and perform your task. The scope closes and releases the browser.
+});
+```
+
+`timeoutSeconds` in an update is the new total lifetime from `startedAt`, not extra seconds. It cannot decrease; extra budget is reserved atomically. Use `idleTimeoutSeconds: null` to disable idle expiry. GET, SSE and read-only Live do not renew idle activity.
+
+Profiles support `create`, `list`, `get`, and `delete`. One unreleased session may use a Profile. Normal close/expiry saves cookies and localStorage when `persistOnClose` is true; inspect the ended session's `profile.saveStatus`. A failed save preserves the previous version. Profiles exclude downloads, page memory, and Agent history.

package/dist/client.d.ts

@@ -0,0 +1,10 @@
+import { Profiles, Sessions } from "./resources.js";
+import type { BrowserSession, TabSailOptions, WithSessionOptions } from "./types.js";
+export declare class TabSail {
+    #private;
+    readonly sessions: Sessions;
+    readonly profiles: Profiles;
+    constructor(options?: TabSailOptions);
+    /** Creates and owns exactly one logical session; the callback runs once. */
+    withSession<T>(options: WithSessionOptions, callback: (session: BrowserSession) => T | Promise<T>): Promise<T>;
+}

package/dist/client.js

@@ -0,0 +1,157 @@
+import { APIError, CleanupError, ResultUnknownError, TabSailError, WaitTimeoutError, } from "./errors.js";
+import { Profiles, Sessions } from "./resources.js";
+import { checkCancelled, operationKey, positive, retryDelay, sleep, Transport, } from "./transport.js";
+export class TabSail {
+    sessions;
+    profiles;
+    #transport;
+    constructor(options = {}) {
+        this.#transport = new Transport(options);
+        this.sessions = new Sessions(this.#transport);
+        this.profiles = new Profiles(this.#transport);
+    }
+    /** Creates and owns exactly one logical session; the callback runs once. */
+    async withSession(options, callback) {
+        checkCancelled(options.signal);
+        const key = operationKey(options.idempotencyKey);
+        const params = {};
+        if (options.browser !== undefined)
+            params.browser = options.browser;
+        if (options.profile !== undefined)
+            params.profile = options.profile;
+        if (options.idleTimeoutSeconds !== undefined)
+            params.idleTimeoutSeconds = options.idleTimeoutSeconds;
+        if (options.region !== undefined)
+            params.region = options.region;
+        if (options.timeoutSeconds !== undefined)
+            params.timeoutSeconds = options.timeoutSeconds;
+        if (options.viewport !== undefined)
+            params.viewport = options.viewport;
+        if (options.metadata !== undefined)
+            params.metadata = options.metadata;
+        // Snapshot parameters: recovery must not observe mutations made by the callback.
+        const request = JSON.parse(JSON.stringify(params));
+        const cleanupTimeout = positive(options.cleanupTimeoutMs ?? 30_000, "cleanupTimeoutMs");
+        const readyTimeout = positive(options.readyTimeoutMs ?? 60_000, "readyTimeoutMs");
+        const acquisitionTimeout = options.timeoutMs ?? (options.waitForCapacity ? 300_000 : undefined);
+        const acquisitionDeadline = acquisitionTimeout === undefined
+            ? undefined
+            : performance.now() + positive(acquisitionTimeout, "timeoutMs");
+        const requestOptions = {
+            signal: options.signal,
+            idempotencyKey: key,
+            requestTimeoutMs: options.requestTimeoutMs,
+            timeoutMs: options.timeoutMs,
+            maxRetries: options.maxRetries,
+        };
+        let session;
+        let unknownCreate = false;
+        let primaryError;
+        let failed = false;
+        let value;
+        let capacityAttempt = 0;
+        try {
+            while (!session) {
+                checkCancelled(options.signal);
+                const remaining = acquisitionDeadline === undefined
+                    ? undefined
+                    : acquisitionDeadline - performance.now();
+                if (remaining !== undefined && remaining <= 0)
+                    throw new WaitTimeoutError("Browser capacity was not acquired within the total deadline.", { code: "CAPACITY_WAIT_TIMEOUT" });
+                try {
+                    session = await this.sessions.create(request, {
+                        ...requestOptions,
+                        timeoutMs: remaining,
+                    });
+                }
+                catch (error) {
+                    if (!options.waitForCapacity ||
+                        !(error instanceof APIError) ||
+                        !error.retryable ||
+                        !((error.status === 503 &&
+                            ["NO_CAPACITY", "STARTUP_BUSY"].includes(error.code)) ||
+                            (error.status === 429 && error.code === "CREATE_RATE_LIMITED")))
+                        throw error;
+                    const left = acquisitionDeadline - performance.now();
+                    if (left <= 0)
+                        throw new WaitTimeoutError("Browser capacity wait timed out.", {
+                            code: "CAPACITY_WAIT_TIMEOUT",
+                        });
+                    const delay = retryDelay(capacityAttempt++, error.retryAfterMs, 10_000);
+                    await sleep(Math.min(left, delay), options.signal);
+                    if (delay >= left)
+                        throw new WaitTimeoutError("Browser capacity wait timed out.", {
+                            code: "CAPACITY_WAIT_TIMEOUT",
+                        });
+                }
+            }
+            const remainingAcquisition = acquisitionDeadline === undefined
+                ? undefined
+                : acquisitionDeadline - performance.now();
+            if (remainingAcquisition !== undefined && remainingAcquisition <= 0)
+                throw new WaitTimeoutError("Owned session acquisition exceeded its total deadline.", { code: "WAIT_TIMEOUT", sessionId: session.id });
+            const ready = await this.sessions.waitUntilReady(session.id, {
+                signal: options.signal,
+                timeoutMs: remainingAcquisition === undefined
+                    ? readyTimeout
+                    : Math.min(readyTimeout, remainingAcquisition),
+                requestTimeoutMs: options.requestTimeoutMs,
+                maxRetries: options.maxRetries,
+                pollIntervalMs: options.pollIntervalMs,
+            });
+            checkCancelled(options.signal, session.id);
+            if (acquisitionDeadline !== undefined &&
+                performance.now() >= acquisitionDeadline)
+                throw new WaitTimeoutError("Owned session acquisition exceeded its total deadline.", { code: "WAIT_TIMEOUT", sessionId: session.id });
+            value = await callback(ready);
+            checkCancelled(options.signal, session.id);
+        }
+        catch (error) {
+            failed = true;
+            primaryError = error;
+            unknownCreate =
+                !session &&
+                    error instanceof ResultUnknownError &&
+                    error.operation === "session.create";
+        }
+        if (session || unknownCreate) {
+            const deadline = performance.now() + cleanupTimeout;
+            const remaining = () => {
+                const left = deadline - performance.now();
+                if (left <= 0)
+                    throw new WaitTimeoutError("Owned cleanup exceeded its independent deadline.", { code: "CLEANUP_TIMEOUT", sessionId: session?.id });
+                return left;
+            };
+            try {
+                // Recovery can briefly create a resource if the original request never arrived.
+                // The same key ensures only one logical resource, and it is immediately closed.
+                if (!session)
+                    session = await this.sessions.create(request, {
+                        idempotencyKey: key,
+                        timeoutMs: remaining(),
+                        requestTimeoutMs: options.requestTimeoutMs,
+                        maxRetries: 1,
+                    });
+                await this.sessions.close(session.id, {
+                    timeoutMs: remaining(),
+                    requestTimeoutMs: options.requestTimeoutMs,
+                    maxRetries: 1,
+                });
+                await this.sessions.waitUntilReleased(session.id, {
+                    timeoutMs: remaining(),
+                    requestTimeoutMs: options.requestTimeoutMs,
+                    maxRetries: 1,
+                    pollIntervalMs: options.pollIntervalMs,
+                });
+            }
+            catch (error) {
+                throw new CleanupError(failed ? primaryError : undefined, error instanceof TabSailError
+                    ? error
+                    : this.#transport.safe(error, session?.id), key, session?.id);
+            }
+        }
+        if (failed)
+            throw primaryError;
+        return value;
+    }
+}

package/dist/errors.d.ts

@@ -0,0 +1,77 @@
+declare const inspect: unique symbol;
+export interface ErrorContext {
+    status?: number;
+    code?: string;
+    retryable?: boolean;
+    requestId?: string;
+    retryAfter?: string;
+    retryAfterMs?: number;
+    sessionId?: string;
+}
+/** Removes grant URLs and authorization strings, even from third party causes. */
+export declare function redact(value: string, secrets?: readonly string[]): string;
+export declare class TabSailError extends Error {
+    readonly status?: number;
+    readonly code: string;
+    readonly retryable: boolean;
+    readonly requestId?: string;
+    readonly retryAfter?: string;
+    readonly retryAfterMs?: number;
+    readonly sessionId?: string;
+    constructor(message: string, context?: ErrorContext);
+    toJSON(): {
+        name: string;
+        message: string;
+        status: number | undefined;
+        code: string;
+        retryable: boolean;
+        requestId: string | undefined;
+        retryAfter: string | undefined;
+        retryAfterMs: number | undefined;
+        sessionId: string | undefined;
+    };
+    [inspect](): {
+        name: string;
+        message: string;
+        status: number | undefined;
+        code: string;
+        retryable: boolean;
+        requestId: string | undefined;
+        retryAfter: string | undefined;
+        retryAfterMs: number | undefined;
+        sessionId: string | undefined;
+    };
+}
+export declare class ConfigurationError extends TabSailError {
+}
+export declare class APIError extends TabSailError {
+}
+export declare class NetworkError extends TabSailError {
+}
+export declare class RequestTimeoutError extends TabSailError {
+}
+export declare class WaitTimeoutError extends TabSailError {
+}
+export declare class CancelledError extends TabSailError {
+}
+export declare class ProtocolError extends TabSailError {
+}
+export declare class SessionTerminatedError extends TabSailError {
+}
+export declare class HandoffCancelledError extends TabSailError {
+}
+/** Access operationKey directly to recover; inspection intentionally omits it. */
+export declare class ResultUnknownError extends TabSailError {
+    readonly operation: "session.create" | "handoff.create" | "profile.create" | "file.upload" | "connection.create";
+    readonly operationKey?: string;
+    readonly originalError: TabSailError;
+    constructor(operation: ResultUnknownError["operation"], key: string | undefined, error: TabSailError, sessionId?: string);
+}
+/** The original error is retained without inserting unsafe causes into the stack. */
+export declare class CleanupError extends TabSailError {
+    readonly primaryError: unknown;
+    readonly cleanupError: TabSailError;
+    readonly operationKey?: string;
+    constructor(primaryError: unknown, cleanupError: TabSailError, key: string, sessionId?: string);
+}
+export {};

package/dist/errors.js

@@ -0,0 +1,104 @@
+const inspect = Symbol.for("nodejs.util.inspect.custom");
+/** Removes grant URLs and authorization strings, even from third party causes. */
+export function redact(value, secrets = []) {
+    let result = value;
+    for (const secret of secrets)
+        if (secret)
+            result = result.split(secret).join("[REDACTED]");
+    return result
+        .replace(/\b(?:https?|wss?):\/\/[^\s"'<>]+/gi, "[REDACTED_URL]")
+        .replace(/\bBearer\s+[^\s"'<>]+/gi, "Bearer [REDACTED]")
+        .replace(/\b(?:bpk|bp_key)_[A-Za-z0-9_-]+/g, "[REDACTED_KEY]")
+        .replace(/\bbp_[A-Za-z0-9_-]{43}(?![A-Za-z0-9_-])/g, "[REDACTED_KEY]")
+        .slice(0, 1024);
+}
+export class TabSailError extends Error {
+    status;
+    code;
+    retryable;
+    requestId;
+    retryAfter;
+    retryAfterMs;
+    sessionId;
+    constructor(message, context = {}) {
+        super(redact(message));
+        this.name = new.target.name;
+        this.status = context.status;
+        this.code = redact(context.code ?? "SDK_ERROR");
+        this.retryable = context.retryable ?? false;
+        this.requestId = context.requestId ? redact(context.requestId) : undefined;
+        this.retryAfter = context.retryAfter
+            ? redact(context.retryAfter)
+            : undefined;
+        this.retryAfterMs = context.retryAfterMs;
+        this.sessionId = context.sessionId ? redact(context.sessionId) : undefined;
+    }
+    toJSON() {
+        return {
+            name: this.name,
+            message: this.message,
+            status: this.status,
+            code: this.code,
+            retryable: this.retryable,
+            requestId: this.requestId,
+            retryAfter: this.retryAfter,
+            retryAfterMs: this.retryAfterMs,
+            sessionId: this.sessionId,
+        };
+    }
+    [inspect]() {
+        return this.toJSON();
+    }
+}
+export class ConfigurationError extends TabSailError {
+}
+export class APIError extends TabSailError {
+}
+export class NetworkError extends TabSailError {
+}
+export class RequestTimeoutError extends TabSailError {
+}
+export class WaitTimeoutError extends TabSailError {
+}
+export class CancelledError extends TabSailError {
+}
+export class ProtocolError extends TabSailError {
+}
+export class SessionTerminatedError extends TabSailError {
+}
+export class HandoffCancelledError extends TabSailError {
+}
+/** Access operationKey directly to recover; inspection intentionally omits it. */
+export class ResultUnknownError extends TabSailError {
+    operation;
+    originalError;
+    constructor(operation, key, error, sessionId) {
+        super(`${operation} result is unknown. ${key ? "Recover with the same operationKey and original parameters; " : "Inspect the session before taking further action; "}do not blindly replay non-idempotent operations.`, {
+            ...error.toJSON(),
+            code: "RESULT_UNKNOWN",
+            sessionId: sessionId ?? error.sessionId,
+        });
+        this.operation = operation;
+        Object.defineProperty(this, "operationKey", {
+            value: key,
+            enumerable: false,
+        });
+        this.originalError = error;
+    }
+}
+/** The original error is retained without inserting unsafe causes into the stack. */
+export class CleanupError extends TabSailError {
+    cleanupError;
+    constructor(primaryError, cleanupError, key, sessionId) {
+        super("Owned session cleanup failed. Inspect sessionId or recover with operationKey and the original creation parameters, then close and wait for releasedAt.", { code: "CLEANUP_FAILED", sessionId, requestId: cleanupError.requestId });
+        Object.defineProperty(this, "primaryError", {
+            value: primaryError,
+            enumerable: false,
+        });
+        Object.defineProperty(this, "operationKey", {
+            value: key,
+            enumerable: false,
+        });
+        this.cleanupError = cleanupError;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { TabSail } from "./client.js";
+export * from "./errors.js";
+export { handoffCheckpoint } from "./resources.js";
+export { FileDownload } from "./transport.js";
+export type * from "./types.js";

package/dist/index.js

@@ -0,0 +1,4 @@
+export { TabSail } from "./client.js";
+export * from "./errors.js";
+export { handoffCheckpoint } from "./resources.js";
+export { FileDownload } from "./transport.js";

package/dist/protocol.d.ts

@@ -0,0 +1,8 @@
+import type { BrowserSession, ConnectionGrant, Handoff, HandoffSummary, Page, Profile, SessionFile } from "./types.js";
+export declare function parseHandoffSummary(value: unknown): HandoffSummary;
+export declare function parseHandoff(value: unknown): Handoff;
+export declare function parseSession(value: unknown): BrowserSession;
+export declare function parseProfile(value: unknown): Profile;
+export declare function parseGrant(value: unknown): ConnectionGrant;
+export declare function parseFile(value: unknown): SessionFile;
+export declare function parsePage<T>(parse: (value: unknown) => T): (value: unknown) => Page<T>;

package/dist/protocol.js

@@ -0,0 +1,133 @@
+import { ProtocolError } from "./errors.js";
+function invalid(label) {
+    throw new ProtocolError(`Unexpected ${label} response.`, {
+        code: "INVALID_RESPONSE",
+    });
+}
+function object(value, label) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        invalid(label);
+    return value;
+}
+function strings(row, names, label) {
+    if (names.some((name) => typeof row[name] !== "string"))
+        invalid(label);
+}
+function nullableStrings(row, names, label) {
+    if (names.some((name) => row[name] !== null && typeof row[name] !== "string"))
+        invalid(label);
+}
+function enumValue(value, choices, label) {
+    if (typeof value !== "string" || !choices.includes(value))
+        invalid(label);
+}
+export function parseHandoffSummary(value) {
+    const row = object(value, "handoff");
+    strings(row, ["id", "reason", "createdAt"], "handoff");
+    nullableStrings(row, ["completedAt"], "handoff");
+    enumValue(row.status, ["requested", "active", "returning", "completed", "cancelled"], "handoff status");
+    return row;
+}
+export function parseHandoff(value) {
+    const row = parseHandoffSummary(value);
+    strings(row, ["browserSessionId"], "handoff");
+    return row;
+}
+export function parseSession(value) {
+    const row = object(value, "session");
+    enumValue(row.region, ["west", "asia"], "session region");
+    strings(row, ["id", "projectId", "controlEpoch", "createdAt", "startupDeadlineAt"], "session");
+    if (!/^(0|[1-9]\d*)$/.test(row.controlEpoch))
+        invalid("controlEpoch");
+    enumValue(row.status, ["starting", "ready", "closing", "closed", "failed"], "session status");
+    enumValue(row.controller, ["automation", "human", "none"], "controller");
+    nullableStrings(row, [
+        "handoffId",
+        "startedAt",
+        "expiresAt",
+        "endedAt",
+        "releasedAt",
+        "closeReason",
+        "downloadDirectory",
+    ], "session");
+    if (row.latestHandoff !== null)
+        parseHandoffSummary(row.latestHandoff);
+    if (!Number.isInteger(row.timeoutSeconds) || Number(row.timeoutSeconds) < 0)
+        invalid("session timeout");
+    if (row.idleTimeoutSeconds != null &&
+        (!Number.isInteger(row.idleTimeoutSeconds) ||
+            Number(row.idleTimeoutSeconds) < 60))
+        invalid("idle timeout");
+    if (row.lastActivityAt != null && typeof row.lastActivityAt !== "string")
+        invalid("last activity");
+    if (row.profile != null) {
+        const profile = object(row.profile, "session Profile");
+        strings(profile, ["id"], "session Profile");
+        enumValue(profile.saveStatus, ["not_requested", "pending", "saved", "failed"], "Profile save status");
+        if (typeof profile.persistOnClose !== "boolean")
+            invalid("Profile persistence");
+    }
+    const metadata = object(row.metadata, "session metadata");
+    if (Object.values(metadata).some((value) => typeof value !== "string"))
+        invalid("session metadata");
+    if (row.error !== null)
+        strings(object(row.error, "session error"), ["code"], "session error");
+    return row;
+}
+export function parseProfile(value) {
+    const row = object(value, "Profile");
+    strings(row, ["id", "projectId", "name", "createdAt", "updatedAt"], "Profile");
+    if (!Number.isInteger(row.version) ||
+        Number(row.version) < 0 ||
+        typeof row.inUse !== "boolean")
+        invalid("Profile metadata");
+    return row;
+}
+export function parseGrant(value) {
+    const row = object(value, "connection grant");
+    strings(row, ["url", "expiresAt"], "connection grant");
+    enumValue(row.type, ["cdp", "live"], "connection type");
+    if (row.type === "live")
+        enumValue(row.mode, ["view", "control"], "connection mode");
+    try {
+        const url = new URL(row.url);
+        if (!(row.type === "cdp" ? ["ws:", "wss:"] : ["http:", "https:"]).includes(url.protocol))
+            invalid("connection URL");
+    }
+    catch {
+        invalid("connection URL");
+    }
+    const safe = { ...row, url: "[REDACTED]" };
+    Object.defineProperty(row, "toJSON", {
+        value: () => safe,
+        enumerable: false,
+    });
+    Object.defineProperty(row, Symbol.for("nodejs.util.inspect.custom"), {
+        value: () => safe,
+        enumerable: false,
+    });
+    return row;
+}
+export function parseFile(value) {
+    const row = object(value, "file");
+    strings(row, ["id", "filename", "contentType", "browserPath", "createdAt"], "file");
+    enumValue(row.status, ["uploading", "downloading", "ready", "failed", "deleted"], "file status");
+    enumValue(row.origin, ["upload", "download"], "file origin");
+    if (!Number.isSafeInteger(row.sizeBytes) || Number(row.sizeBytes) < 0)
+        invalid("file size");
+    if (row.error !== null)
+        strings(object(row.error, "file error"), ["code"], "file error");
+    return row;
+}
+export function parsePage(parse) {
+    return (value) => {
+        const row = object(value, "page");
+        if (!Array.isArray(row.items))
+            invalid("page items");
+        nullableStrings(row, ["nextCursor"], "page");
+        return {
+            items: row.items.map(parse),
+            nextCursor: row.nextCursor,
+        };
+    };
+}