TypeScript SDK
Configure TabSail, inspect the complete method surface, and understand owned-session behavior.
Requires Node.js 24 or newer and ESM. Install from npm using SDK installation.
import { TabSail } from "tabsail";
const client = new TabSail({
baseURL: process.env.TABSAIL_BASE_URL,
apiKey: process.env.TABSAIL_API_KEY,
requestTimeoutMs: 15_000,
maxRetries: 0,
});The base URL is the instance root with no path, query, fragment, or embedded credentials. The client appends /v1. Environment variables are used when constructor values are omitted; .env files are not loaded automatically.
Cloudflare Workers transport
Pass baseURL and apiKey explicitly from your Worker bindings. The SDK invokes native fetch with the correct runtime context; no custom fetch wrapper is required.
The HTTP transport is regression-tested in workerd with compatibility date 2026-10-12 and the nodejs_compat / no_nodejs_global_timers flags. CDP client connections, embedded Live View, and Durable Object recovery still require application-specific integration validation.
Methods
| Method | Input / behavior |
|---|---|
| client.withSession(options, callback) | Create, wait ready, run callback once, close and confirm release |
| sessions.create(params?, options?) | SessionCreateParams; returns accepted resource |
| sessions.get(id, options?) | Current BrowserSession |
| sessions.list(params?, options?) | limit, status, cursor |
| sessions.close(id, options?) | Request stop |
| sessions.watch(id, options?) | Async iterator of current snapshots |
| sessions.waitUntilReady(id, options?) | Wait for readiness |
| sessions.waitUntilReleased(id, options?) | Wait for non-null releasedAt |
| sessions.waitForHandoff(id, options) | Requires an after checkpoint; waits for a later completed handoff and stable automation |
| sessions.connections.create(id, params, options?) | CDP, Live view, or handoff-bound Live control |
| sessions.handoffs.create(id, params?, options?) | Optional reason |
| sessions.handoffs.get(id, handoffId, options?) | Current handoff |
| sessions.handoffs.complete(id, handoffId, options?) | Request return to automation |
| sessions.handoffs.waitUntilCompleted(id, handoffId, options?) | Wait for that exact handoff |
| sessions.files.upload(id, params, options?) | file, filename, optional contentType and sizeBytes |
| sessions.files.list(id, params?, options?) | limit, origin, cursor |
| sessions.files.get(id, fileId, options?) | File metadata |
| sessions.files.download(id, fileId, options?) | Streamed FileDownload |
| sessions.files.delete(id, fileId, options?) | Delete a ready file |
Request and wait options
RequestOptions exposes signal, requestTimeoutMs, timeoutMs, maxRetries, and idempotencyKey. The key applies to session and handoff creation. WaitOptions adds pollIntervalMs for polling fallback and reconnect backoff.
WithSessionOptions combines creation parameters with request options, waitForCapacity, readyTimeoutMs, cleanupTimeoutMs, and pollIntervalMs. Its timeoutMs bounds acquisition, not arbitrary callback execution.
handoffCheckpoint(session) constructs a checkpoint from a stable ready/automation snapshot. waitForHandoff returns the resource you can use for the next checkpoint. See handoff guidance.
Files and errors
Uploads accept Blob, Uint8Array, ReadableStream, or AsyncIterable of Uint8Array. FileDownload exposes body, headers, status, async iteration, close, and async disposal. Fully consume or close it.
Exported errors are TabSailError, ConfigurationError, APIError, NetworkError, RequestTimeoutError, WaitTimeoutError, CancelledError, ProtocolError, SessionTerminatedError, HandoffCancelledError, ResultUnknownError, and CleanupError.
Errors expose code, status, retryable, requestId, retryAfter, retryAfterMs, and sessionId when available. CleanupError additionally preserves primaryError, cleanupError, and an operationKey for recovery. Inspecting the error intentionally omits secret recovery values; access them directly only in trusted recovery logic.
Use package-provided types for full TypeScript signatures. BrowserSession and related resource fields are documented in Resource models.