Metadata-Version: 2.4
Name: cdp-toolkit
Version: 1.2.1
Summary: Chrome DevTools Protocol automation toolkit
Author: aaameobius-crypto
License: MIT
Project-URL: Homepage, https://github.com/aaameobius-crypto/cdp-toolkit
Keywords: cdp,chrome,automation,browser
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# CDP Toolkit

[![PyPI](https://img.shields.io/pypi/v/cdp-toolkit)](https://pypi.org/project/cdp-toolkit/)
[![Tests](https://img.shields.io/badge/tests-38%20passing-brightgreen)](tests/)
[![Dependencies](https://img.shields.io/badge/dependencies-zero-success)](https://pypi.org/project/cdp-toolkit/)
[![License](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
[![Python](https://img.shields.io/badge/python-3.10%2B-blue)](https://python.org)

> Chrome DevTools Protocol automation without external dependencies. No Playwright, no Selenium, no Puppeteer. Pure Python stdlib.

## Install

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

## Why CDP Toolkit?

| Feature | Playwright | Selenium | **cdp-toolkit** |
|---------|-----------|----------|-----------------|
| Dependencies | 50+ packages | 20+ packages | **0** |
| Install size | ~300MB | ~150MB | **~15KB** |
| Browser download | Yes (~200MB) | Yes (~100MB) | **No** |
| Learning curve | Medium | High | **Low** |
| Speed | Fast | Slow | **Fastest** |
| Cloud-native | Yes | Partial | **Yes** |

CDP Toolkit talks directly to Chrome's DevTools Protocol via HTTP and WebSocket. You bring your own Chrome instance (local, Docker, or cloud), and CDP Toolkit handles the rest.

## Quick Start

```python
from cdp_toolkit import CDPClient

# Connect to a Chrome instance with --remote-debugging-port=9222
client = CDPClient("127.0.0.1", 9222)

# List open tabs
tabs = client.list_targets()
for tab in tabs:
    print(f"{tab['id'][:8]} | {tab['url'][:60]}")

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

# Navigate
client.navigate(new_tab['id'], "https://httpbin.org/forms/post")

# Execute JavaScript
title = client.evaluate(new_tab['id'], "document.title")
print(f"Page title: {title}")
```

## React/Vue Form Filling

The most common CDP use case: filling forms on React/Vue/Angular sites where standard `input.value = "x"` does not trigger reactivity.

```python
from cdp_toolkit import CDPInput

# Generate native setter JavaScript for React
js_code = CDPInput.native_setter_js(
    selector="#email",
    value="user@example.com"
)
# Execute via CDP — triggers React's onChange handler

# For Vue.js
js_code = CDPInput.vue_setter_js(
    selector="input[name='phone']",
    value="+1234567890"
)

# Key-by-key typing simulation
js_code = CDPInput.simulate_typing(
    selector="#search",
    text="hello world",
    delay_ms=50
)
```

## Mouse Events

```python
from cdp_toolkit import CDPMouseEvents

# Click at coordinates
params = CDPMouseEvents.click(x=200, y=300)

# Right-click
params = CDPMouseEvents.click(x=200, y=300, button="right")

# Double-click
params = CDPMouseEvents.double_click(x=200, y=300)

# Drag and drop
params = CDPMouseEvents.drag(
    start_x=100, start_y=200,
    end_x=400, end_y=300
)
```

## Navigation and Screenshots

```python
from cdp_toolkit import CDPNavigation

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

# Take screenshot
screenshot_b64 = client.screenshot(tab_id)

# Scroll to element
js = CDPNavigation.scroll_to_element("#footer")
client.evaluate(tab_id, js)

# Wait for selector
js = CDPNavigation.wait_for_selector(".result-card", timeout_ms=5000)
```

## Anti-Detection

CDP Toolkit includes JavaScript snippets to make automation less detectable:

```python
from cdp_toolkit import stealth

# Remove webdriver flag
client.evaluate(tab_id, stealth.remove_webdriver_flag())

# Override navigator properties
client.evaluate(tab_id, stealth.override_navigator())

# Add realistic timing jitter
CDPInput.set_typing_delay(min_ms=30, max_ms=120)
```

## Docker Integration

Run Chrome in Docker and control it with CDP Toolkit:

```dockerfile
# Dockerfile
FROM chrome/headless
EXPOSE 9222
CMD ["chrome", "--remote-debugging-port=9222", "--no-sandbox"]
```

```python
# Connect to Docker Chrome
client = CDPClient("chrome-container", 9222)
```

## Testing

```bash
python -m pytest tests/ -v --tb=short
```

38 tests covering all modules. Zero external dependencies in tests.

## API Reference

### CDPClient

| Method | Description |
|--------|-------------|
| `list_targets()` | List all open tabs/pages |
| `create_target(url)` | Open a new tab |
| `close_target(id)` | Close a tab |
| `activate_target(id)` | Focus a tab |
| `navigate(id, url)` | Navigate to URL |
| `evaluate(id, js)` | Execute JavaScript |
| `screenshot(id)` | Capture page screenshot |

### CDPInput

| Method | Description |
|--------|-------------|
| `native_setter_js(sel, val)` | React-compatible value setter |
| `vue_setter_js(sel, val)` | Vue.js-compatible value setter |
| `simulate_typing(sel, text, delay)` | Human-like typing simulation |
| `key_event(key)` | Send keyboard event |

### CDPMouseEvents

| Method | Description |
|--------|-------------|
| `click(x, y, button)` | Mouse click |
| `double_click(x, y)` | Double click |
| `drag(sx, sy, ex, ey)` | Drag and drop |
| `hover(x, y)` | Mouse hover |

## License

MIT — see [LICENSE](LICENSE)

## Links

- [GitHub](https://github.com/aaameobius-crypto/cdp-toolkit)
- [PyPI](https://pypi.org/project/cdp-toolkit/)
- [Full templates collection](https://github.com/aaameobius-crypto/darkbot-ai-templates)
