@bug0/sdk

Official TypeScript SDK for Bug0 Cloud Browsers. Spin up chromium browsers in the cloud and control them via CDP.

Install

npm install @bug0/sdk

Quick start

import { Bug0 } from "@bug0/sdk";
import { chromium } from "playwright";

const bug0 = new Bug0({ apiKey: "bug0_sk_..." });

// Create a cloud browser
const session = await bug0.createBrowser();

// Connect with Playwright
const browser = await chromium.connectOverCDP(session.cdpUrl);
const page = browser.contexts()[0].pages()[0];
await page.goto("https://example.com");
console.log(await page.title());
await browser.close();

// Stop the session when done
await bug0.stopBrowser(session.sessionId);

API

new Bug0(config)

| Option | Type | Default | Description | |--------|------|---------|-------------| | apiKey | string | required | Your Bug0 API key | | baseUrl | string | https://browsers.bug0.com | API base URL | | maxRetries | number | 3 | Max retry attempts for transient errors | | retryDelayMs | number | 1000 | Base delay between retries (exponential backoff) |

bug0.createBrowser(options?)

Creates a new cloud browser session.

| Option | Type | Default | Description | |--------|------|---------|-------------| | timeoutMs | number | 900000 | Session duration (60,000–2,700,000 ms) | | livePreview | boolean | true | Set false for headless-only (faster startup) |

Returns:

{
  sessionId: string;
  cdpUrl: string;         // Pass to chromium.connectOverCDP()
  livePreviewUrl: string | null;
  expiresAt: string;
  startupMs: number;
}

bug0.stopBrowser(sessionId)

Stops a running session. Frees resources and stops billing immediately.

await bug0.stopBrowser(session.sessionId);
// { sessionId: "...", status: "stopped" }

Error handling

import { Bug0, Bug0APIError, Bug0QuotaError } from "@bug0/sdk";

try {
  const session = await bug0.createBrowser();
} catch (err) {
  if (err instanceof Bug0QuotaError) {
    // Free minutes exhausted or concurrency limit
  } else if (err instanceof Bug0APIError) {
    console.error(err.status, err.code, err.message);
  }
}

| Error class | Status | When | |-------------|--------|------| | Bug0AuthError | 401 | Invalid or missing API key | | Bug0ValidationError | 400 | Invalid parameters | | Bug0QuotaError | 402 | Free quota exceeded or concurrency limit | | Bug0RateLimitError | 429 | Too many requests | | Bug0APIError | * | Base class for all API errors |

Retries

Transient errors (408, 429, 502, 503, 504) and network failures are retried automatically with exponential backoff and jitter. Client errors (400, 401, 402) are not retried.