> ## 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.

# 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:

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "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) |

<Warning>
  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.
</Warning>

### Page Events

Page lifecycle events -- navigation, load, close.

```json theme={null}
{
  "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).

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

```json theme={null}
{
  "jsonrpc": "2.0",
  "method": "dialog/handle",
  "params": { "accept": true, "promptText": "yes" },
  "id": 5
}
```

### Download Events

File download notifications.

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

<Tabs>
  <Tab title="TypeScript">
    ```typescript theme={null}
    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}`);
    });
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    @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}")
    ```
  </Tab>
</Tabs>

## CLI Event Streaming

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

```bash theme={null}
# 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.