Tabfleet TypeScript SDK

Install the official package#

Install @tabfleet/sdk from npm. The source is maintained in tabfleet/sdk-typescript under the MIT license. The SDK supports all 12 REST API operations, includes TypeScript declarations, and has no runtime dependencies.

Use Node.js 22 or later with ES modules. Create a workspace API key in the dashboard and save it in your server environment as TABFLEET_API_KEY. Keep workspace keys out of frontend code. REST uses workspace API keys rather than MCP OAuth tokens.

npm install @tabfleet/sdk

Read usage and session history#

iterateSessions follows cursor pagination across retained history. The page size ranges from 1 to 100 and defaults to 100. Use listSessions with limit and cursor when you want to manage pages yourself.

The API retains up to 100 completed sessions plus active sessions. New sessions do not enter an in-progress traversal; older history may expire.

import Tabfleet from '@tabfleet/sdk';

const tabfleet = new Tabfleet({
  apiKey: process.env.TABFLEET_API_KEY!,
});
const usage = await tabfleet.getUsage();
console.log(usage.budget.availableSeconds);

for await (const session of tabfleet.iterateSessions({ limit: 25 })) {
  console.log(session.id, session.status);
}

Create a browser with a stable idempotency key#

Save an idempotency key with your job before launching. Reuse that key and identical options if you must retry the same creation after an uncertain network result. The SDK does not automatically retry requests.

Creating a browser reserves allowance. Use a control-capable key. Signed CDP and viewer URLs are temporary credentials: pass them to your browser client without logging them. Close the session when the job finishes. A closing state means cleanup is still pending.

import { randomUUID } from 'node:crypto';

const idempotencyKey = randomUUID(); // Persist with your job before creation.
const session = await tabfleet.createSession(
  { durationSeconds: 300, idleTimeoutSeconds: 60 },
  { idempotencyKey },
);
try {
  if (!session.cdpUrl) throw new Error('Session is not active');
  // Pass session.cdpUrl to your CDP-compatible browser client.
} finally {
  await tabfleet.closeSession(session.id);
}

Handle errors and cancellation#

TabfleetError exposes status, code, message, headers, and retryAfter (seconds or null). Respect Retry-After on throttled responses and inspect the error code before retrying. Network errors have status 0 and code network_error. No operation is automatically retried.

Every method accepts an options object with an AbortSignal. The default per-request timeout is 30 seconds; set timeoutMs in the client constructor to change it. Caller cancellation and timeout reasons are propagated. Successful calls return typed JSON, including a closing session for HTTP 202 responses.

See the SDK README for every method, the API reference for request constraints, and rate limits for quota reporting.