> ## Documentation Index
> Fetch the complete documentation index at: https://piyushvyas.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```bash theme={null}
npm install @browseragentprotocol/client
```

## Quick Start

```typescript theme={null}
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"), "user@example.com");

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

await client.close();
```

<Tip>
  Use `createClient()` as a shorthand that creates and connects in one call:

  ```typescript theme={null}
  import { createClient } from "@browseragentprotocol/client";
  const client = await createClient("ws://localhost:9222");
  ```
</Tip>

## Semantic Selector Helpers

The SDK exports factory functions for all selector types:

```typescript theme={null}
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"), "user@example.com");

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

## API Reference

### Connection

```typescript theme={null}
const client = new BAPClient(url, options?);
await client.connect();
await client.close();
```

### Browser Lifecycle

```typescript theme={null}
await client.launch({ browser: "chromium", headless: true });
await client.closeBrowser();
```

### Page Management

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
// 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

```typescript theme={null}
// 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: "user@example.com",
  }),
  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

```typescript theme={null}
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

```typescript theme={null}
// Discover tools exposed by the current page
const tools = await client.discoverTools();
```

## Connection Options

The `BAPClient` constructor accepts an options object:

```typescript theme={null}
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:

<CodeGroup>
  ```bash CLI daemon theme={null}
  npm i -g @browseragentprotocol/cli
  bap open
  # Server starts automatically on port 9222
  ```

  ```bash Direct server theme={null}
  npx @browseragentprotocol/server-playwright --port 9222
  ```
</CodeGroup>

## Requirements

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