protocol

@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