Events

Server-pushed notifications for console messages, network activity, dialogs, and page lifecycle.

BAP servers push event notifications to connected clients over the WebSocket connection. Events use JSON-RPC 2.0 notification format (no id, no response expected).

Subscribing to Events

Use events/subscribe to select which event types to receive:

{
  "jsonrpc": "2.0",
  "method": "events/subscribe",
  "params": {
    "types": ["console", "network", "page", "dialog", "download"]
  },
  "id": 1
}

Event Types

Console Events

Browser console messages (log, warn, error) forwarded to the client. Console errors are always forwarded; other levels require subscription.

{
  "jsonrpc": "2.0",
  "method": "notifications/console",
  "params": {
    "pageId": "page-1",
    "type": "error",
    "text": "Uncaught TypeError: Cannot read property 'x' of null",
    "url": "https://example.com/app.js",
    "lineNumber": 42
  }
}

Field	Type	Description
pageId	string	Page that generated the message
type	"log" | "warn" | "error" | "info" | "debug"	Console level
text	string	Message text
url	string	Source file URL
lineNumber	number	Source line number

Network Events

HTTP request and response events for 4xx/5xx responses. Sensitive headers are automatically redacted.

{
  "jsonrpc": "2.0",
  "method": "notifications/network",
  "params": {
    "pageId": "page-1",
    "type": "response",
    "url": "https://api.example.com/data",
    "status": 404,
    "method": "GET"
  }
}

Field	Type	Description
pageId	string	Page that made the request
type	"request" | "response" | "failed"	Event type
url	string	Request URL
method	string	HTTP method
status	number	HTTP status code (response events)

Headers containing credentials (authorization, cookie, set-cookie, x-api-key, proxy-authorization, x-auth-token, x-csrf-token) are stripped from network events. Request postData is always blanket-redacted.

Page Events

Page lifecycle events — navigation, load, close.

{
  "jsonrpc": "2.0",
  "method": "notifications/page",
  "params": {
    "pageId": "page-1",
    "type": "navigated",
    "url": "https://example.com/dashboard"
  }
}

Field	Type	Description
pageId	string	Affected page
type	"created" | "navigated" | "loaded" | "closed"	Lifecycle event
url	string	Current page URL

Dialog Events

Browser dialog events (alert, confirm, prompt, beforeunload).

{
  "jsonrpc": "2.0",
  "method": "notifications/dialog",
  "params": {
    "pageId": "page-1",
    "type": "alert",
    "message": "Are you sure you want to leave?"
  }
}

Handle dialogs with dialog/handle:

{
  "jsonrpc": "2.0",
  "method": "dialog/handle",
  "params": { "accept": true, "promptText": "yes" },
  "id": 5
}

Download Events

File download notifications.

{
  "jsonrpc": "2.0",
  "method": "notifications/download",
  "params": {
    "pageId": "page-1",
    "url": "https://example.com/report.pdf",
    "suggestedFilename": "report.pdf",
    "path": "/tmp/downloads/report.pdf"
  }
}

Rate Limiting

The server enforces a rate limit of 100 events per second per page to prevent event floods (e.g., a page emitting thousands of console messages). Events exceeding the limit are dropped silently.

Rate limiter state is cleaned up when a page closes.

Event Handling in SDKs

TypeScript

client.on("console", (event) => {
  if (event.type === "error") {
    console.error(`[${event.pageId}] ${event.text}`);
  }
});

client.on("network", (event) => {
  if (event.status >= 400) {
    console.warn(`${event.method} ${event.url} -> ${event.status}`);
  }
});

client.on("dialog", (event) => {
  console.log(`Dialog: ${event.type} - ${event.message}`);
});

Python

@client.on("console")
async def on_console(event):
    if event.type == "error":
        print(f"[{event.page_id}] {event.text}")

@client.on("network")
async def on_network(event):
    if event.status and event.status >= 400:
        print(f"{event.method} {event.url} -> {event.status}")

CLI Event Streaming

The BAP CLI provides bap watch for live event monitoring in the terminal:

# Watch all events
bap watch

# Filter to specific event types
bap watch --filter=console,network

# JSON output for piping
bap watch --format=json

Events are color-coded by type: page events in blue, console in yellow/red, network in green/red, dialogs in magenta.