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?"
}
}
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
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}`);
});
@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
