browser-debugger-cli 0.0.1-alpha.0

package/README.md

@@ -0,0 +1,85 @@
+# browser-debugger-cli
+
+CLI tool for collecting browser telemetry (DOM, network, console) via Chrome DevTools Protocol.
+
+## Installation
+
+```bash
+npm install -g browser-debugger-cli
+```
+
+## Quick Start
+
+```bash
+# Just run bdg - it will auto-launch Chrome if needed
+bdg localhost:3000
+
+# Interact with the page, then press Ctrl+C
+```
+
+JSON output with collected network requests, console logs, and DOM will be written to stdout.
+
+### How It Works
+
+`bdg` automatically launches Chrome with debugging enabled if it's not already running. You can also manually start Chrome first if you prefer:
+
+```bash
+# macOS
+/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \
+  --remote-debugging-port=9222 \
+  --user-data-dir=/tmp/chrome-bdg
+
+# Linux
+google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-bdg
+
+# Windows
+"C:\Program Files\Google\Chrome\Application\chrome.exe" ^
+  --remote-debugging-port=9222 ^
+  --user-data-dir=C:\temp\chrome-bdg
+```
+
+If Chrome is already running with debugging enabled, `bdg` will detect and use the existing instance.
+
+## Usage
+
+```bash
+# Collect all telemetry (default)
+bdg localhost:3000
+
+# Collect specific data
+bdg dom localhost:3000
+bdg network localhost:3000
+bdg console localhost:3000
+
+# Options
+bdg localhost:3000 --port 9223
+bdg localhost:3000 --timeout 30
+```
+
+## Output
+
+```json
+{
+  "success": true,
+  "duration": 45230,
+  "target": { "url": "...", "title": "..." },
+  "data": {
+    "network": [...],
+    "console": [...],
+    "dom": {...}
+  }
+}
+```
+
+## Documentation
+
+See [CHROME_SETUP.md](./CHROME_SETUP.md) for Chrome configuration details.
+
+## Requirements
+
+- Node.js >= 18.0.0
+- Chrome/Chromium with remote debugging
+
+## License
+
+MIT

package/dist/collectors/console.d.ts

@@ -0,0 +1,17 @@
+import { CDPConnection } from '../connection/cdp.js';
+import { ConsoleMessage, CleanupFunction } from '../types.js';
+/**
+ * Start collecting console messages and exceptions via CDP Runtime domain.
+ *
+ * Captures console.log, console.error, etc. and JavaScript exceptions thrown in the page.
+ *
+ * @param cdp - CDP connection instance
+ * @param messages - Array to populate with console messages
+ * @returns Cleanup function to remove event handlers
+ *
+ * @remarks
+ * - Message limit of 10,000 prevents memory issues in long-running sessions
+ * - After limit is reached, new messages are silently dropped (warning logged once)
+ */
+export declare function startConsoleCollection(cdp: CDPConnection, messages: ConsoleMessage[]): Promise<CleanupFunction>;
+//# sourceMappingURL=console.d.ts.map

package/dist/collectors/console.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../../src/collectors/console.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EACL,cAAc,EACd,eAAe,EAGhB,MAAM,aAAa,CAAC;AAIrB;;;;;;;;;;;;GAYG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,aAAa,EAClB,QAAQ,EAAE,cAAc,EAAE,GACzB,OAAO,CAAC,eAAe,CAAC,CAoD1B"}

package/dist/collectors/console.js

@@ -0,0 +1,65 @@
+const MAX_MESSAGES = 10000; // Prevent memory issues
+/**
+ * Start collecting console messages and exceptions via CDP Runtime domain.
+ *
+ * Captures console.log, console.error, etc. and JavaScript exceptions thrown in the page.
+ *
+ * @param cdp - CDP connection instance
+ * @param messages - Array to populate with console messages
+ * @returns Cleanup function to remove event handlers
+ *
+ * @remarks
+ * - Message limit of 10,000 prevents memory issues in long-running sessions
+ * - After limit is reached, new messages are silently dropped (warning logged once)
+ */
+export async function startConsoleCollection(cdp, messages) {
+    const handlers = [];
+    // Enable runtime
+    await cdp.send('Runtime.enable');
+    await cdp.send('Log.enable');
+    // Listen for console API calls
+    const consoleAPIId = cdp.on('Runtime.consoleAPICalled', (params) => {
+        const message = {
+            type: params.type,
+            text: params.args
+                .map((arg) => {
+                if (arg.value !== undefined) {
+                    return String(arg.value);
+                }
+                if (arg.description !== undefined) {
+                    return arg.description;
+                }
+                return '';
+            })
+                .join(' '),
+            timestamp: params.timestamp,
+            args: params.args
+        };
+        if (messages.length < MAX_MESSAGES) {
+            messages.push(message);
+        }
+        else if (messages.length === MAX_MESSAGES) {
+            console.error(`Warning: Console message limit reached (${MAX_MESSAGES})`);
+        }
+    });
+    handlers.push({ event: 'Runtime.consoleAPICalled', id: consoleAPIId });
+    // Listen for exceptions
+    const exceptionId = cdp.on('Runtime.exceptionThrown', (params) => {
+        const exception = params.exceptionDetails;
+        const message = {
+            type: 'error',
+            text: exception.text || exception.exception?.description || 'Unknown error',
+            timestamp: exception.timestamp || Date.now()
+        };
+        if (messages.length < MAX_MESSAGES) {
+            messages.push(message);
+        }
+    });
+    handlers.push({ event: 'Runtime.exceptionThrown', id: exceptionId });
+    // Return cleanup function
+    return () => {
+        // Remove event handlers
+        handlers.forEach(({ event, id }) => cdp.off(event, id));
+    };
+}
+//# sourceMappingURL=console.js.map

package/dist/collectors/console.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"console.js","sourceRoot":"","sources":["../../src/collectors/console.ts"],"names":[],"mappings":"AAQA,MAAM,YAAY,GAAG,KAAK,CAAC,CAAC,wBAAwB;AAEpD;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,GAAkB,EAClB,QAA0B;IAE1B,MAAM,QAAQ,GAAyC,EAAE,CAAC;IAE1D,iBAAiB;IACjB,MAAM,GAAG,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;IACjC,MAAM,GAAG,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC;IAE7B,+BAA+B;IAC/B,MAAM,YAAY,GAAG,GAAG,CAAC,EAAE,CAAC,0BAA0B,EAAE,CAAC,MAAiC,EAAE,EAAE;QAC5F,MAAM,OAAO,GAAmB;YAC9B,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,IAAI,EAAE,MAAM,CAAC,IAAI;iBACd,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;gBACX,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;oBAC5B,OAAO,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;gBAC3B,CAAC;gBACD,IAAI,GAAG,CAAC,WAAW,KAAK,SAAS,EAAE,CAAC;oBAClC,OAAO,GAAG,CAAC,WAAW,CAAC;gBACzB,CAAC;gBACD,OAAO,EAAE,CAAC;YACZ,CAAC,CAAC;iBACD,IAAI,CAAC,GAAG,CAAC;YACZ,SAAS,EAAE,MAAM,CAAC,SAAS;YAC3B,IAAI,EAAE,MAAM,CAAC,IAAI;SAClB,CAAC;QACF,IAAI,QAAQ,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC;YACnC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;aAAM,IAAI,QAAQ,CAAC,MAAM,KAAK,YAAY,EAAE,CAAC;YAC5C,OAAO,CAAC,KAAK,CAAC,2CAA2C,YAAY,GAAG,CAAC,CAAC;QAC5E,CAAC;IACH,CAAC,CAAC,CAAC;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,0BAA0B,EAAE,EAAE,EAAE,YAAY,EAAE,CAAC,CAAC;IAEvE,wBAAwB;IACxB,MAAM,WAAW,GAAG,GAAG,CAAC,EAAE,CAAC,yBAAyB,EAAE,CAAC,MAAgC,EAAE,EAAE;QACzF,MAAM,SAAS,GAAG,MAAM,CAAC,gBAAgB,CAAC;QAC1C,MAAM,OAAO,GAAmB;YAC9B,IAAI,EAAE,OAAO;YACb,IAAI,EAAE,SAAS,CAAC,IAAI,IAAI,SAAS,CAAC,SAAS,EAAE,WAAW,IAAI,eAAe;YAC3E,SAAS,EAAE,SAAS,CAAC,SAAS,IAAI,IAAI,CAAC,GAAG,EAAE;SAC7C,CAAC;QACF,IAAI,QAAQ,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC;YACnC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QACzB,CAAC;IACH,CAAC,CAAC,CAAC;IACH,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,yBAAyB,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;IAErE,0BAA0B;IAC1B,OAAO,GAAG,EAAE;QACV,wBAAwB;QACxB,QAAQ,CAAC,OAAO,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IAC1D,CAAC,CAAC;AACJ,CAAC"}

package/dist/collectors/dom.d.ts

@@ -0,0 +1,21 @@
+import { CDPConnection } from '../connection/cdp.js';
+import { DOMData, CleanupFunction } from '../types.js';
+/**
+ * Prepare CDP domains for DOM collection.
+ *
+ * Enables Page, DOM, and Runtime domains required for capturing DOM snapshots.
+ *
+ * @param cdp - CDP connection instance
+ * @returns Cleanup function that disables Runtime domain
+ */
+export declare function prepareDOMCollection(cdp: CDPConnection): Promise<CleanupFunction>;
+/**
+ * Capture a complete DOM snapshot of the current page.
+ *
+ * Called during session shutdown to get the final state of the page.
+ *
+ * @param cdp - CDP connection instance
+ * @returns DOM data including URL, title, and full HTML
+ */
+export declare function collectDOM(cdp: CDPConnection): Promise<DOMData>;
+//# sourceMappingURL=dom.d.ts.map

package/dist/collectors/dom.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.d.ts","sourceRoot":"","sources":["../../src/collectors/dom.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEvD;;;;;;;GAOG;AACH,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,eAAe,CAAC,CAsBvF;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAAC,GAAG,EAAE,aAAa,GAAG,OAAO,CAAC,OAAO,CAAC,CAoErE"}

package/dist/collectors/dom.js

@@ -0,0 +1,88 @@
+/**
+ * Prepare CDP domains for DOM collection.
+ *
+ * Enables Page, DOM, and Runtime domains required for capturing DOM snapshots.
+ *
+ * @param cdp - CDP connection instance
+ * @returns Cleanup function that disables Runtime domain
+ */
+export async function prepareDOMCollection(cdp) {
+    // Enable Page domain for frame tree
+    await cdp.send('Page.enable');
+    // Enable DOM domain for document access
+    await cdp.send('DOM.enable');
+    // Enable Runtime domain for document.title evaluation
+    await cdp.send('Runtime.enable');
+    // Return cleanup function that disables Runtime domain
+    return () => {
+        // Disable Runtime domain to clean up resources
+        // Note: This is best-effort during shutdown; errors are ignored
+        try {
+            cdp.send('Runtime.disable').catch(() => {
+                // Ignore errors during cleanup (Chrome may be closing)
+            });
+        }
+        catch {
+            // Ignore synchronous errors
+        }
+    };
+}
+/**
+ * Capture a complete DOM snapshot of the current page.
+ *
+ * Called during session shutdown to get the final state of the page.
+ *
+ * @param cdp - CDP connection instance
+ * @returns DOM data including URL, title, and full HTML
+ */
+export async function collectDOM(cdp) {
+    try {
+        // Add a timeout wrapper to prevent hanging
+        const timeout = 5000; // 5 seconds should be plenty for DOM capture
+        const captureWithTimeout = async (promise, label) => {
+            return Promise.race([
+                promise,
+                new Promise((_, reject) => setTimeout(() => reject(new Error(`${label} timed out after ${timeout}ms`)), timeout))
+            ]);
+        };
+        // Get document
+        console.error('Getting document...');
+        const { root } = await captureWithTimeout(cdp.send('DOM.getDocument', { depth: -1 }), 'DOM.getDocument');
+        console.error(`Got document root (nodeId: ${root.nodeId})`);
+        // Get outer HTML
+        console.error('Getting outer HTML...');
+        const { outerHTML } = await captureWithTimeout(cdp.send('DOM.getOuterHTML', { nodeId: root.nodeId }), 'DOM.getOuterHTML');
+        console.error(`Got outer HTML (${outerHTML.length} chars)`);
+        // Get page info
+        console.error('Getting page info...');
+        const frameTree = await captureWithTimeout(cdp.send('Page.getFrameTree'), 'Page.getFrameTree');
+        const frame = frameTree.frameTree.frame;
+        console.error(`Got page info (url: ${frame.url})`);
+        // Get real document title using Runtime.evaluate
+        console.error('Getting document title...');
+        let title = 'Untitled';
+        try {
+            const titleResult = await captureWithTimeout(cdp.send('Runtime.evaluate', {
+                expression: 'document.title',
+                returnByValue: true
+            }), 'Runtime.evaluate (document.title)');
+            if (titleResult.result && titleResult.result.value) {
+                title = titleResult.result.value;
+            }
+        }
+        catch (titleError) {
+            console.error('Failed to get document title, using fallback:', titleError);
+        }
+        console.error(`Got document title: ${title}`);
+        return {
+            url: frame.url,
+            title,
+            outerHTML
+        };
+    }
+    catch (error) {
+        console.error('Error in collectDOM:', error);
+        throw error;
+    }
+}
+//# sourceMappingURL=dom.js.map

package/dist/collectors/dom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dom.js","sourceRoot":"","sources":["../../src/collectors/dom.ts"],"names":[],"mappings":"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"}

package/dist/collectors/network.d.ts

@@ -0,0 +1,19 @@
+import { CDPConnection } from '../connection/cdp.js';
+import { NetworkRequest, CleanupFunction } from '../types.js';
+/**
+ * Start collecting network requests via CDP Network domain.
+ *
+ * Tracks all HTTP requests and responses, including headers and bodies (for JSON/text responses).
+ * Implements automatic cleanup of stale requests to prevent memory leaks during long sessions.
+ *
+ * @param cdp - CDP connection instance
+ * @param requests - Array to populate with completed network requests
+ * @returns Cleanup function to remove event handlers and clear state
+ *
+ * @remarks
+ * - Stale requests (incomplete after 60s) are removed from tracking but NOT added to output
+ * - Request limit of 10,000 prevents memory issues in long-running sessions
+ * - Response bodies are only fetched for JSON/JavaScript/text MIME types
+ */
+export declare function startNetworkCollection(cdp: CDPConnection, requests: NetworkRequest[]): Promise<CleanupFunction>;
+//# sourceMappingURL=network.d.ts.map

package/dist/collectors/network.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.d.ts","sourceRoot":"","sources":["../../src/collectors/network.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EACL,cAAc,EACd,eAAe,EAKhB,MAAM,aAAa,CAAC;AAKrB;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,sBAAsB,CAC1C,GAAG,EAAE,aAAa,EAClB,QAAQ,EAAE,cAAc,EAAE,GACzB,OAAO,CAAC,eAAe,CAAC,CAwG1B"}

package/dist/collectors/network.js

@@ -0,0 +1,114 @@
+const MAX_REQUESTS = 10000; // Prevent memory issues
+const STALE_REQUEST_TIMEOUT = 60000; // 60 seconds
+/**
+ * Start collecting network requests via CDP Network domain.
+ *
+ * Tracks all HTTP requests and responses, including headers and bodies (for JSON/text responses).
+ * Implements automatic cleanup of stale requests to prevent memory leaks during long sessions.
+ *
+ * @param cdp - CDP connection instance
+ * @param requests - Array to populate with completed network requests
+ * @returns Cleanup function to remove event handlers and clear state
+ *
+ * @remarks
+ * - Stale requests (incomplete after 60s) are removed from tracking but NOT added to output
+ * - Request limit of 10,000 prevents memory issues in long-running sessions
+ * - Response bodies are only fetched for JSON/JavaScript/text MIME types
+ */
+export async function startNetworkCollection(cdp, requests) {
+    const requestMap = new Map();
+    const handlers = [];
+    // Enable network tracking
+    await cdp.send('Network.enable');
+    // Periodic cleanup of stale requests (see JSDoc @remarks for behavior)
+    const cleanupInterval = setInterval(() => {
+        const now = Date.now();
+        const staleRequests = [];
+        requestMap.forEach((value, requestId) => {
+            if (now - value.timestamp > STALE_REQUEST_TIMEOUT) {
+                staleRequests.push(requestId);
+            }
+        });
+        if (staleRequests.length > 0) {
+            console.error(`Cleaning up ${staleRequests.length} stale network requests`);
+            staleRequests.forEach(requestId => requestMap.delete(requestId));
+        }
+    }, 30000); // Check every 30 seconds
+    // Listen for requests
+    const requestWillBeSentId = cdp.on('Network.requestWillBeSent', (params) => {
+        if (requestMap.size >= MAX_REQUESTS) {
+            console.error(`Warning: Network request limit reached (${MAX_REQUESTS}), dropping new requests`);
+            return;
+        }
+        const request = {
+            requestId: params.requestId,
+            url: params.request.url,
+            method: params.request.method,
+            timestamp: params.timestamp,
+            requestHeaders: params.request.headers,
+            requestBody: params.request.postData
+        };
+        requestMap.set(params.requestId, {
+            request,
+            timestamp: Date.now()
+        });
+    });
+    handlers.push({ event: 'Network.requestWillBeSent', id: requestWillBeSentId });
+    // Listen for responses
+    const responseReceivedId = cdp.on('Network.responseReceived', (params) => {
+        const entry = requestMap.get(params.requestId);
+        if (entry) {
+            entry.request.status = params.response.status;
+            entry.request.mimeType = params.response.mimeType;
+            entry.request.responseHeaders = params.response.headers;
+        }
+    });
+    handlers.push({ event: 'Network.responseReceived', id: responseReceivedId });
+    // Listen for finished requests
+    const loadingFinishedId = cdp.on('Network.loadingFinished', async (params) => {
+        const entry = requestMap.get(params.requestId);
+        if (entry && requests.length < MAX_REQUESTS) {
+            const request = entry.request;
+            // Try to get response body for API calls
+            if (request.mimeType?.includes('json') || request.mimeType?.includes('javascript') || request.mimeType?.includes('text')) {
+                try {
+                    const { body } = await cdp.send('Network.getResponseBody', { requestId: params.requestId });
+                    request.responseBody = body;
+                }
+                catch (error) {
+                    // Response body not available (e.g., 204 No Content, redirects, etc.)
+                }
+            }
+            requests.push(request);
+            requestMap.delete(params.requestId);
+        }
+        else if (requests.length >= MAX_REQUESTS) {
+            console.error(`Warning: Network request limit reached (${MAX_REQUESTS})`);
+            requestMap.delete(params.requestId);
+        }
+    });
+    handlers.push({ event: 'Network.loadingFinished', id: loadingFinishedId });
+    // Listen for failed requests
+    const loadingFailedId = cdp.on('Network.loadingFailed', (params) => {
+        const entry = requestMap.get(params.requestId);
+        if (entry && requests.length < MAX_REQUESTS) {
+            entry.request.status = 0; // Indicate failure
+            requests.push(entry.request);
+            requestMap.delete(params.requestId);
+        }
+        else if (requests.length >= MAX_REQUESTS) {
+            requestMap.delete(params.requestId);
+        }
+    });
+    handlers.push({ event: 'Network.loadingFailed', id: loadingFailedId });
+    // Return cleanup function
+    return () => {
+        // Clear interval
+        clearInterval(cleanupInterval);
+        // Remove event handlers
+        handlers.forEach(({ event, id }) => cdp.off(event, id));
+        // Clear request map
+        requestMap.clear();
+    };
+}
+//# sourceMappingURL=network.js.map

package/dist/collectors/network.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"network.js","sourceRoot":"","sources":["../../src/collectors/network.ts"],"names":[],"mappings":"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"}

package/dist/connection/cdp.d.ts

@@ -0,0 +1,99 @@
+import { ConnectionOptions } from '../types.js';
+/**
+ * Chrome DevTools Protocol WebSocket connection manager.
+ *
+ * Handles bidirectional communication with Chrome via CDP:
+ * - Request/response correlation with message IDs
+ * - Event subscription and handling
+ * - Connection lifecycle (connect, reconnect, keepalive)
+ * - Graceful error handling and cleanup
+ */
+export declare class CDPConnection {
+    private ws;
+    private messageId;
+    private pendingMessages;
+    private nextHandlerId;
+    private eventHandlers;
+    private pingInterval;
+    private pongTimeout;
+    private missedPongs;
+    private readonly MAX_MISSED_PONGS;
+    private wsUrl;
+    private autoReconnect;
+    private reconnectAttempts;
+    private readonly MAX_RECONNECT_ATTEMPTS;
+    private isIntentionallyClosed;
+    private onReconnect?;
+    /**
+     * Connect to Chrome via WebSocket.
+     *
+     * @param wsUrl - WebSocket debugger URL from CDP target
+     * @param options - Connection configuration options
+     * @throws Error if connection fails after all retries
+     */
+    connect(wsUrl: string, options?: ConnectionOptions): Promise<void>;
+    private attemptConnection;
+    private attemptReconnection;
+    private startKeepalive;
+    private stopKeepalive;
+    /**
+     * Get the CDP port from the WebSocket URL.
+     *
+     * @returns CDP port number
+     * @throws Error if not connected or URL is invalid
+     */
+    getPort(): number;
+    /**
+     * Send a CDP command and wait for the response.
+     *
+     * @param method - CDP method name (e.g., 'Page.navigate', 'DOM.getDocument')
+     * @param params - Method parameters
+     * @param sessionId - Optional session ID for commands sent to specific targets
+     * @returns Promise resolving to the command result
+     * @throws Error if not connected or command times out (30s)
+     *
+     * @remarks
+     * Return type is `any` because CDP response structures vary by method.
+     * Callers should type-assert the result based on the specific method called.
+     */
+    send(method: string, params?: Record<string, any>, sessionId?: string): Promise<any>;
+    /**
+     * Register an event handler for CDP events.
+     *
+     * @param event - CDP event name (e.g., 'Network.requestWillBeSent')
+     * @param handler - Callback function to handle the event
+     * @returns Handler ID for later removal with off()
+     *
+     * @remarks
+     * Handler parameter type is `any` for flexibility. Callers should use typed
+     * event parameter interfaces (e.g., `CDPNetworkRequestParams`) at call site.
+     */
+    on(event: string, handler: (params: any) => void): number;
+    /**
+     * Remove a specific event handler.
+     *
+     * @param event - CDP event name
+     * @param handlerId - Handler ID returned from on()
+     */
+    off(event: string, handlerId: number): void;
+    /**
+     * Remove all event handlers for a specific event or all events.
+     *
+     * @param event - Optional event name. If omitted, removes all handlers for all events.
+     */
+    removeAllListeners(event?: string): void;
+    /**
+     * Close the WebSocket connection and clean up resources.
+     *
+     * @param code - WebSocket close code (default: 1000 for normal closure)
+     * @param reason - Human-readable close reason
+     */
+    close(code?: number, reason?: string): void;
+    /**
+     * Check if the WebSocket connection is open and ready.
+     *
+     * @returns True if connected and ready to send/receive
+     */
+    isConnected(): boolean;
+}
+//# sourceMappingURL=cdp.d.ts.map

package/dist/connection/cdp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cdp.d.ts","sourceRoot":"","sources":["../../src/connection/cdp.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAE5D;;;;;;;;GAQG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,eAAe,CAIlB;IACL,OAAO,CAAC,aAAa,CAAK;IAC1B,OAAO,CAAC,aAAa,CAAyD;IAG9E,OAAO,CAAC,YAAY,CAA+B;IACnD,OAAO,CAAC,WAAW,CAA+B;IAClD,OAAO,CAAC,WAAW,CAAK;IACxB,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAK;IAGtC,OAAO,CAAC,KAAK,CAAM;IACnB,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAK;IAC5C,OAAO,CAAC,qBAAqB,CAAS;IACtC,OAAO,CAAC,WAAW,CAAC,CAAsB;IAE1C;;;;;;OAMG;IACG,OAAO,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,iBAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IA+B5E,OAAO,CAAC,iBAAiB;YAoFX,mBAAmB;IAqBjC,OAAO,CAAC,cAAc;IAoBtB,OAAO,CAAC,aAAa;IAWrB;;;;;OAKG;IACH,OAAO,IAAI,MAAM;IAajB;;;;;;;;;;;;OAYG;IACG,IAAI,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC;IAsC9F;;;;;;;;;;OAUG;IACH,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,IAAI,GAAG,MAAM;IASzD;;;;;OAKG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,IAAI;IAU3C;;;;OAIG;IACH,kBAAkB,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI;IAQxC;;;;;OAKG;IACH,KAAK,CAAC,IAAI,SAAO,EAAE,MAAM,SAAmB,GAAG,IAAI;IAoBnD;;;;OAIG;IACH,WAAW,IAAI,OAAO;CAGvB"}