@browseragentprotocol/protocol

Core types, schemas, and utilities for the Browser Agent Protocol (BAP).

Installation

npm install @browseragentprotocol/protocol

Note: Most users should install @browseragentprotocol/client instead, which re-exports everything from this package.

Usage

import {
  // Selector helpers
  role, text, css, xpath, label, testId,

  // Types
  type BAPSelector,
  type Page,
  type AccessibilityNode,

  // Errors
  BAPError,
  BAPTimeoutError,

  // Protocol constants
  BAP_VERSION,
  ErrorCodes,
} from "@browseragentprotocol/protocol";

// Create semantic selectors
const submitButton = role("button", "Submit");
const emailInput = label("Email address");
const searchBox = text("Search...");

Semantic Selectors

BAP uses semantic selectors that are more stable and AI-friendly than CSS selectors:

| Function | Description | Example | |----------|-------------|---------| | role(role, name?) | ARIA role and accessible name | role("button", "Submit") | | text(content) | Visible text content | text("Sign in") | | label(text) | Associated label text | label("Email") | | placeholder(text) | Placeholder attribute | placeholder("Search...") | | testId(id) | Test ID attribute | testId("submit-btn") | | css(selector) | CSS selector (fallback) | css(".btn-primary") | | xpath(expression) | XPath expression | xpath("//button[@type='submit']") |

Zod Schemas

All types have corresponding Zod schemas for runtime validation:

import { BAPSelectorSchema } from "@browseragentprotocol/protocol";

const selector = { type: "role", role: "button", name: "Submit" };
const validated = BAPSelectorSchema.parse(selector);

Error Classes

import {
  BAPError,           // Base error class
  BAPTimeoutError,    // Operation timed out
  BAPConnectionError, // Connection failed
  BAPElementNotFoundError, // Element not found
  BAPNavigationError, // Navigation failed
} from "@browseragentprotocol/protocol";

try {
  await client.click(role("button", "Missing"));
} catch (error) {
  if (error instanceof BAPElementNotFoundError) {
    console.log("Element not found:", error.message);
  }
}

License

Apache-2.0