TypeScript SDK

Programmatic browser control with the BAP TypeScript client

The TypeScript SDK gives you full programmatic control over BAP servers. Use it to build agent backends, custom automation tools, or integrate browser control into your application.

Installation

npm install @browseragentprotocol/client

Quick Start

import { BAPClient, role, label, text } from "@browseragentprotocol/client";

const client = new BAPClient("ws://localhost:9222");
await client.connect();

// Launch browser and navigate
await client.launch({ browser: "chromium", headless: false });
await client.createPage({ url: "https://example.com" });

// Interact with semantic selectors
await client.click(role("button", "Submit"));
await client.fill(label("Email"), "[e-mail]");

// Get page state for AI reasoning
const { tree } = await client.accessibility();

await client.close();

Use createClient() as a shorthand that creates and connects in one call:

import { createClient } from "@browseragentprotocol/client";
const client = await createClient("ws://localhost:9222");

Semantic Selector Helpers

The SDK exports factory functions for all selector types:

import { role, text, label, testId } from "@browseragentprotocol/client";

// By ARIA role and accessible name
await client.click(role("button", "Submit"));
await client.fill(role("textbox", "Search"), "query");

// By visible text
await client.click(text("Sign in"));

// By form label
await client.fill(label("Email address"), "[e-mail]");

// By data-testid
await client.click(testId("submit-button"));

API Reference

Connection

const client = new BAPClient(url, options?);
await client.connect();
await client.close();

Browser Lifecycle

await client.launch({ browser: "chromium", headless: true });
await client.closeBrowser();

Page Management

const page = await client.createPage({ url: "https://example.com" });
await client.navigate("https://another.com");
await client.reload();
await client.goBack();
await client.goForward();
await client.closePage();

// Multi-tab
const pages = await client.listPages();
await client.activatePage(pages[1].id);

Actions

await client.click(selector);
await client.dblclick(selector);
await client.fill(selector, "text");
await client.type(selector, "text");
await client.clear(selector);
await client.press("Enter");
await client.hover(selector);
await client.scroll({ direction: "down", amount: 500 });
await client.select(selector, "option-value");
await client.check(selector);
await client.uncheck(selector);

Observations

// Screenshot (returns base64 data)
const { data } = await client.screenshot();

// Full accessibility tree
const { tree } = await client.accessibility();

// Token-efficient YAML snapshot
const { snapshot } = await client.ariaSnapshot();

// Page content as text or markdown
const { content } = await client.content("text");

AI Agent Methods

// Observe: AI-optimized page snapshot
const observation = await client.observe();

// Act: execute multiple steps atomically
const result = await client.act([
  BAPClient.step("action/fill", {
    selector: label("Email"),
    value: "[e-mail]",
  }),
  BAPClient.step("action/click", {
    selector: role("button", "Submit"),
  }),
]);

// Extract: structured data extraction
const data = await client.extract({
  instruction: "Extract product names and prices",
  schema: {
    type: "array",
    items: {
      type: "object",
      properties: {
        name: { type: "string" },
        price: { type: "number" },
      },
    },
  },
});

Events

client.on("page", (event) => console.log("Page:", event));
client.on("console", (event) => console.log("Console:", event));
client.on("network", (event) => console.log("Network:", event));
client.on("dialog", (event) => console.log("Dialog:", event));
client.on("download", (event) => console.log("Download:", event));

WebMCP Discovery

// Discover tools exposed by the current page
const tools = await client.discoverTools();

Connection Options

The BAPClient constructor accepts an options object:

const client = new BAPClient("ws://localhost:9222", {
  timeout: 30000, // Request timeout (ms)
  token: "my-auth-token", // Authentication token
  maxReconnectAttempts: 5, // Auto-reconnect attempts
  reconnectDelay: 1000, // Base delay between reconnects (ms)
});

The transport uses exponential backoff for reconnection: delay * 2^attempt.

Starting the Server

The TypeScript SDK requires a running BAP server. Start one with:

CLI daemon

npm i -g @browseragentprotocol/cli
bap open
# Server starts automatically on port 9222

Requirements

• Node.js >= 20.0.0
• A running BAP Playwright server