Zurf TypeScript SDK

Zurf (formerly BrowserAPI) provides managed browser infrastructure (Lightpanda & Browserless) with intelligent routing and per-request billing.

Features

• Typed & Safe: Built with TypeScript and Zod for runtime validation.
• Enterprise Grade: Automatic retries, exponential backoff, and detailed error reporting.
• Universal: Works in Node.js (and Edge runtimes compatible with fetch).
• Playwright Native: Seamless integration with Playwright.

Installation

npm install zurf-typescript-sdk playwright-core puppeteer-core
# or
pnpm add zurf-typescript-sdk playwright-core puppeteer-core

Quick Start

1. Initialize Client

import { Zurf } from 'zurf-typescript-sdk';

const zurf = new Zurf({
  apiKey: process.env.ZURF_API_KEY, // or 'bk_...'
});

2. Connect to Browser (Playwright)

Automatically routes to the best browser provider (Lightpanda for speed/cost, Browserless for features).

import { Zurf } from 'zurf-typescript-sdk';

const zurf = new Zurf();

async function scrape() {
  // Returns a connected Playwright Browser instance
  const browser = await zurf.puppeteer.browser({ region: 'lightpanda' });
  const page = await browser.newPage();
  
  await page.goto('https://example.com');
  console.log(await page.title());
  
  await browser.close();
}
scrape();

3. Check Usage & Billing

const usage = await zurf.getUsage();

console.log(`Used: ${usage.total_tasks} tasks`);
console.log(`Cost: $${usage.total_cost_cents / 100}`);
console.log(`Quota Remaining: ${usage.remaining}`);

Advanced Usage

Custom Connection

If you prefer to manage the Playwright connection yourself:

import { chromium } from 'playwright-core';

const { wsEndpoint } = zurf.getConnectionDetails({ region: 'browserless' });

const browser = await chromium.connect(wsEndpoint);

Error Handling

The SDK throws typed errors for better handling:

import { AuthenticationError, RateLimitError, APIError } from 'zurf';

try {
  await zurf.getUsage();
} catch (err) {
  if (err instanceof AuthenticationError) {
    console.error('Check your API Key!');
  } else if (err instanceof RateLimitError) {
    console.error('Slow down!');
  } else {
    console.error('Unknown error:', err);
  }
}

License

MIT