Metadata-Version: 2.4
Name: cdp-toolkit
Version: 1.3.0
Summary: Chrome DevTools Protocol automation toolkit — WebSocket CDP client, screenshots, DOM, network interception
Author: AMEOBIUS
License: MIT
Project-URL: Homepage, https://github.com/aaameobius-crypto/cdp-toolkit
Keywords: cdp,chrome,automation,browser,websocket,devtools,screenshot,scraping
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# CDP Toolkit

> Chrome DevTools Protocol automation — WebSocket client, screenshots, DOM, network. Zero dependencies.

[![Python](https://img.shields.io/badge/python-3.8%2B-blue)](https://python.org)
[![Dependencies](https://img.shields.io/badge/dependencies-zero-success)](#)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)

## What's New in 1.3.0

- **CDPWebSocket** — full RFC 6455 WebSocket client for CDP communication
- **CDPClient.send_command()** — send any CDP method over WebSocket
- **Screenshots** — `screenshot()` and `save_screenshot()` with full-page capture
- **DOM methods** — `query_selector()`, `get_dom_tree()`, `set_input_value()`, `click_element()`
- **Navigation** — `navigate()`, `evaluate()`, `wait_for_element()`, `scroll_to()`
- **CDPNetwork** — cookie management, user agent override, extra headers, request inspection
- **CDPNavigation** — print-to-PDF parameters, enhanced evaluate with awaitPromise
- **CDPInput** — `type_text_js()` for realistic character-by-character typing
- **CDPMouseEvents** — `drag_params()` for drag-and-drop sequences

## Features

- **CDPWebSocket** — RFC 6455 WebSocket client using only stdlib (socket, struct, base64, hashlib)
- **CDPClient** — HTTP tab management + WebSocket CDP session in one client
- **CDPMouseEvents** — mouse click, release, move, drag parameters for Input.dispatchMouseEvent
- **CDPInput** — text injection, key events, React/Vue native setter JS, realistic typing simulation
- **CDPNavigation** — navigate, evaluate JS, screenshot, print-to-PDF parameters
- **CDPNetwork** — cookie management, user agent spoofing, custom headers, request inspection
- **Pure Python stdlib** — no playwright, no selenium, no puppeteer, no websockets, no requests

## Quick Start

```bash
pip install cdp-toolkit
```

Launch Chrome with remote debugging:

```bash
google-chrome --remote-debugging-port=9222
# or headless:
google-chrome --headless --remote-debugging-port=9222 --no-sandbox
```

### Tab Management (HTTP)

```python
from cdp_client import CDPClient

client = CDPClient("127.0.0.1", 9222)

# List all open tabs
tabs = client.list_targets()

# Open a new tab
tab = client.create_target("https://example.com")

# Activate and close
client.activate_target(tab["targetId"])
client.close_target(tab["targetId"])

# Browser version info
print(client.get_version())
```

### Full CDP Session (WebSocket)

```python
from cdp_client import CDPClient

client = CDPClient("127.0.0.1", 9222)
client.connect_ws()  # Connect to first page tab

# Navigate and wait for load
client.navigate("https://example.com")

# Evaluate JavaScript
title = client.evaluate("document.title")
print(f"Page title: {title}")

# Take screenshot
client.save_screenshot("page.png")

# Full-page screenshot as JPEG
img_bytes = client.screenshot(format="jpeg", quality=90, full_page=True)

# DOM interaction
client.set_input_value("#search", "hello world")
client.click_element("#submit-btn")

# Wait for dynamic content
if client.wait_for_element(".results", timeout=10):
    text = client.get_text(".results")

# Raw CDP command
resp = client.send_command("Network.enable")
resp = client.send_command("Runtime.evaluate", {
    "expression": "1 + 1",
    "returnByValue": True,
})

client.disconnect_ws()
```

### Network Interception

```python
from cdp_client import CDPClient, CDPNetwork

client = CDPClient("127.0.0.1", 9222)
client.connect_ws()

# Set custom user agent
client.send_command("Network.enable")
client.send_command("Network.setUserAgentOverride",
    CDPNetwork.set_user_agent_params(
        "Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)",
        accept_language="en-US",
        platform="iPhone",
    ))

# Set cookies
client.send_command("Network.setCookie",
    CDPNetwork.set_cookie_params(
        name="session",
        value="abc123",
        domain=".example.com",
        http_only=True,
        secure=True,
        same_site="Lax",
    ))

# Get all cookies
cookies = client.send_command("Network.getCookies")
print(cookies["result"]["cookies"])
```

### Print to PDF

```python
from cdp_client import CDPClient, CDPNavigation

client = CDPClient("127.0.0.1", 9222)
client.connect_ws()
client.navigate("https://example.com")

import base64
resp = client.send_command("Page.printToPDF",
    CDPNavigation.print_to_pdf_params(
        print_background=True,
        paper_width=8.27,  # A4
        paper_height=11.69,
    ))
pdf_bytes = base64.b64decode(resp["result"]["data"])
with open("page.pdf", "wb") as f:
    f.write(pdf_bytes)
```

### React/Vue Form Fill

```python
from cdp_client import CDPInput

# Native setter bypasses React's synthetic event system
js = CDPInput.native_setter_js("#email", "user@example.com")
# Send via CDP Runtime.evaluate

# Or use the high-level method:
client.set_input_value("#email", "user@example.com")
```

## Testing

```bash
python -m pytest tests/ -v
```

## Use Cases

- **Browser automation** without Playwright/Selenium dependencies
- **Screenshot capture** for monitoring and CI
- **Web scraping** with JavaScript rendering
- **Form automation** on React/Vue/Angular sites
- **PDF generation** from web pages
- **Cookie/session management** for authenticated scraping
- **Docker-friendly** — ~50MB image vs 250MB+ with Playwright

## API Reference

### CDPClient(host, port)

| Method | Description |
|--------|-------------|
| `list_targets()` | List all browser tabs (HTTP) |
| `create_target(url)` | Open new tab (HTTP) |
| `close_target(id)` | Close tab (HTTP) |
| `activate_target(id)` | Focus tab (HTTP) |
| `get_version()` | Browser version info (HTTP) |
| `find_target(url_contains)` | Find tab by URL substring |
| `connect_ws(url_contains)` | Connect WebSocket to tab |
| `send_command(method, params)` | Raw CDP command over WebSocket |
| `navigate(url, wait)` | Navigate and optionally wait for load |
| `evaluate(js)` | Execute JavaScript, return result |
| `screenshot(fmt, quality, full_page)` | Capture screenshot as bytes |
| `save_screenshot(path, ...)` | Save screenshot to file |
| `query_selector(sel)` | Find element, return nodeId |
| `set_input_value(sel, val)` | Set input value (React-safe) |
| `click_element(sel)` | Click element by selector |
| `get_text(sel)` | Get text content of element |
| `scroll_to(x, y)` | Scroll to coordinates |
| `wait_for_element(sel, timeout)` | Poll for element |
| `disconnect_ws()` | Close WebSocket |

## License

MIT
