TypeScript SDK

Installation #

Install the package from npm.

npm install @browserbeam/sdk

yarn add browserbeam

Quick Start #

Create a session, interact with a page, extract data, and close.

import Browserbeam from "@browserbeam/sdk";

const client = new Browserbeam({ apiKey: "bb_live_..." });

const session = await client.sessions.create({
  url: "https://example.com",
});

// Click a link
await session.click({ text: "More information" });

// Extract structured data
const result = await session.extract({
  title: "string",
  description: "string",
});
console.log(result.extraction);

// Close the session
await session.close();

Configuration #

Pass options when creating the client.

import Browserbeam from "@browserbeam/sdk";

const client = new Browserbeam({
  apiKey: "bb_live_...",
  baseUrl: "https://api.browserbeam.com",
  timeout: 120_000,
});

Creating Sessions #

Call client.sessions.create() to launch a browser and navigate to a URL.

const session = await client.sessions.create({
  url: "https://example.com",
  viewport: { width: 1280, height: 720 },
  locale: "en-US",
  timezone: "America/New_York",
  proxy: { kind: "residential", country: "us" },
  block_resources: ["image", "font"],
  auto_dismiss_blockers: true,
  cookies: [
    { name: "session", value: "abc123", domain: ".example.com" }
  ],
  timeout: 30000,
  idempotency_key: "unique-request-id",
});

Parameters

Session Methods #

Every method returns a Promise<SessionEnvelope> with the updated page state, media, extraction data, and any errors.

// Simple
await session.goto("https://example.com/page");

// With wait condition
await session.goto({
  url: "https://example.com/page",
  wait_for: "networkidle",
  wait_timeout: 10000,
});

const result = await session.observe({
  scope: "main",
  format: "markdown",
  include_links: true,
  max_text_length: 5000,
});

console.log(result.page?.markdown?.content);
console.log(result.page?.interactive_elements);

// Page map is auto-included on first observe
result.page?.map?.forEach((entry) => {
  console.log(`${entry.section}: ${entry.hint}`);
});

// Re-request the map on subsequent calls
await session.observe({ include_page_map: true });

// Get content from all page sections
const full = await session.observe({ mode: "full", max_text_length: 20_000 });
// full.page?.markdown?.content contains:
// ## [nav]
// Home · Docs · Pricing
// ## [main]
// ...article content...
// ## [aside]
// Related posts · ...

// By element ref (from observe)
await session.click({ ref: "a7" });

// By visible text
await session.click({ text: "Sign In" });

// By accessible label
await session.click({ label: "Submit form" });

await session.fill({ value: "user@example.com", ref: "input3" });

await session.fill({ value: "search query", label: "Search" });

await session.fillForm({
  fields: {
    "Email": "user@example.com",
    "Password": "s3cret",
  },
  submit: true,
});

// Mix CSS, JS, and AI selectors in a single extraction
const result = await session.extract({
  products: [{
    _parent: ".product-card",
    _limit: 3,
    name: "h2 >> text",                          // CSS selector
    price: ".price >> text",                     // CSS selector
    url: "a >> href",                            // CSS attribute
    rating: "ai >> the star rating out of 5",    // AI selector
    in_stock: "js >> el.querySelector('.stock')?.textContent.includes('In stock')",  // JS selector
  }],
});

console.log(result.extraction);
// { products: [{ name: "Widget Pro", price: "$29.99", url: "...", rating: "4.5", in_stock: true }] }

const result = await session.screenshot({ full_page: true });

const image = result.media[0];
console.log(image.type);   // "screenshot"
console.log(image.format); // "png"

// Save to file
import { writeFileSync } from "fs";
writeFileSync("page.png", Buffer.from(image.data, "base64"));

const result = await session.scrollCollect({
  max_scrolls: 10,
  wait_ms: 1000,
  timeout_ms: 30000,
  max_text_length: 50000,
});

await session.close();

await session.type({ value: "search query", ref: "e5", delay: 50 });
await session.type({ value: "hello", label: "Search" });

await session.select({ value: "us", label: "Country" });

await session.check({ label: "I agree to the terms" });
await session.check({ ref: "cb3", checked: false });

await session.scroll({ to: "bottom" });
await session.scroll({ direction: "down", amount: 500 });
await session.scroll({ text: "Footer section" });

await session.wait({ ms: 2000 });
await session.wait({ selector: ".loaded", timeout: 10000 });
await session.wait({ until: "document.querySelectorAll('.item').length > 5" });

await session.upload({ files: ["https://example.com/file.pdf"], ref: "file1" });
await session.upload({ files: ["https://example.com/photo.jpg"], label: "Upload photo" });

import { writeFileSync } from "fs";

const result = await session.pdf({
  format: "A4",
  landscape: true,
  scale: 0.8,
  margin: { top: "1cm", bottom: "1cm" },
});
writeFileSync("page.pdf", Buffer.from(result.media[0].data, "base64"));

const result = await session.executeJs("return document.title");
console.log(result.extraction?.js_result);

// With options
const r = await session.executeJs({
  code: "return document.querySelectorAll('a').length",
  result_key: "link_count",
  timeout: 5000,
});

TypeScript Types #

All types are exported from the package. Import them directly for full type safety.

import type {
  SessionEnvelope,
  PageState,
  MapEntry,
  InteractiveElement,
  MediaItem,
  StepError,
} from "@browserbeam/sdk";

SessionEnvelope

Returned by every session method. Contains the full state after each action.

interface SessionEnvelope {
  session_id: string;
  expires_at: string;
  request_id: string;
  completed: number;
  page: PageState | null;
  media: MediaItem[];
  extraction: Record<string, unknown> | null;
  blockers_dismissed: string[];
  error: StepError | null;
}

PageState

interface PageState {
  url: string;
  title: string;
  stable: boolean;
  markdown?: MarkdownContent | null;
  map?: MapEntry[];
  interactive_elements: InteractiveElement[];
  forms: Form[];
  changes?: Changes | null;
  scroll?: ScrollState | null;
}

MapEntry

Structural outline of a page landmark region. Auto-included on first observe, or when include_page_map: true.

interface MapEntry {
  section: string;  // e.g. "nav", "main", "aside", "footer"
  selector: string; // CSS selector for the region
  hint: string;     // First visible text, truncated
}

InteractiveElement

interface InteractiveElement {
  ref: string;
  tag: string;
  role?: string;
  label: string;
  value?: string;
  in?: string;
  near?: string;
  form?: string;
}

Form

interface Form {
  ref: string;
  id: string | null;
  action: string;
  method: string;
  fields: string[];
}

MediaItem

interface MediaItem {
  type: "screenshot" | "pdf";
  format: string;
  data: string; // base64-encoded
}

StepError

interface StepError {
  step: number;
  action: string;
  code:
    | "element_not_found"
    | "navigation_failed"
    | "captcha_detected"
    | "captcha_unsolvable"
    | "access_denied"
    | "action_failed"
    | "extract_failed"
    | "invalid_request";
  message: string;
  context?: Record<string, unknown>;
}

Session Management #

List, inspect, and destroy sessions through the client.

List sessions

const { sessions, has_more, next_cursor } = await client.sessions.list({
  status: "active",
  limit: 10,
});

// Paginate
if (has_more) {
  const next = await client.sessions.list({ after: next_cursor ?? undefined });
}

Get session info

const info = await client.sessions.get("ses_abc123");

console.log(info.status);           // "active" | "closed" | "failed"
console.log(info.started_at);       // ISO 8601 timestamp
console.log(info.duration_seconds); // e.g. 42
if (info.status === "failed") {
  console.log(info.error_code, info.error_message);
}

Destroy session

await client.sessions.destroy("ses_abc123");

Error Handling #

The SDK throws typed errors for different failure scenarios. All errors extend BrowserbeamError.

import Browserbeam, {
  BrowserbeamError,
  RateLimitError,
  AuthenticationError,
  QuotaExceededError,
} from "@browserbeam/sdk";

const client = new Browserbeam();

try {
  const session = await client.sessions.create({ url: "https://example.com" });
  const result = await session.extract({ title: "string" });
  console.log(result.extraction);
  await session.close();
} catch (error) {
  if (error instanceof RateLimitError) {
    console.log(`Rate limited. Retry after ${error.retryAfter}s`);
  } else if (error instanceof AuthenticationError) {
    console.log("Check your API key");
  } else if (error instanceof QuotaExceededError) {
    console.log("Quota exhausted — upgrade your plan");
  } else if (error instanceof BrowserbeamError) {
    console.log(`API error: ${error.message} (${error.code})`);
  } else {
    throw error;
  }
}

Full Example #

Extract the top stories from Hacker News, search for a topic, and save a screenshot.

import Browserbeam from "@browserbeam/sdk";
import { writeFileSync } from "fs";

async function main() {
  const client = new Browserbeam();

  // Navigate to Hacker News
  const session = await client.sessions.create({
    url: "https://news.ycombinator.com/",
    auto_dismiss_blockers: true,
  });

  // Extract top stories from the front page
  const result = await session.extract({
    stories: [
      {
        _parent: ".titleline",
        title: "a >> text",
        url: "a >> href",
      },
    ],
  });
  console.log(result.extraction);

  // Fill the search form and submit
  await session.fillForm({
    fields: { q: "browser automation" },
    submit: true,
  });

  // Take a screenshot of search results
  const screenshot = await session.screenshot({ full_page: true });
  if (screenshot.media.length > 0) {
    const img = screenshot.media[0];
    writeFileSync("hn-search.png", Buffer.from(img.data, "base64"));
  }

  // Clean up
  await session.close();
}

main().catch(console.error);

Resources #

• GitHub Repository — Source code, issues, and contributions.
• npm Package — Install and version history.
• API Reference — Full REST API documentation.
• All Integrations — Python, Ruby, and MCP server guides.