Metadata-Version: 2.4
Name: nakalbrowser
Version: 0.1.6
Summary: Nakal Browser — light, powerful CDP browser automation for Python
Author: NakalBrowser
License: MIT
Project-URL: Homepage, https://github.com/nakalbrowser/nakalbrowser
Project-URL: Documentation, https://github.com/nakalbrowser/nakalbrowser
Keywords: browser,automation,cdp,chrome,scraping,nakal,mcp
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
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
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: websocket-client>=1.6.0
Provides-Extra: parse
Requires-Dist: selectolax>=0.3.21; extra == "parse"
Provides-Extra: proc
Requires-Dist: psutil>=5.9.0; extra == "proc"
Provides-Extra: cloak
Requires-Dist: cloakbrowser>=0.4.0; extra == "cloak"
Provides-Extra: captcha
Provides-Extra: all
Requires-Dist: nakalbrowser[cloak,parse,proc]; extra == "all"
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23; extra == "dev"

<p align="center">
  <img src="BannerGithubBrowser.png?v=2" alt="Nakal Browser" width="100%">
</p>

<h1 align="center">Nakal Browser</h1>

<p align="center">
  <b>Lightweight browser automation for Python — fast, stealth, production-ready</b>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/python-3.10+-blue?style=flat-square&logo=python&logoColor=white" alt="Python">
  <img src="https://img.shields.io/badge/license-MIT-green?style=flat-square" alt="License">
  <img src="https://img.shields.io/badge/CDP-pure-red?style=flat-square" alt="CDP">
  <img src="https://img.shields.io/badge/version-0.1.6-orange?style=flat-square" alt="Version">
</p>

---

## Features

- **Pure CDP** — no chromedriver, no webdriver, direct Chrome DevTools Protocol
- **Rush** — HTTP requests + JavaScript rendering in one class
- **Playwright-style locators** — `bot.locator("h1").click()` with auto-wait
- **Stealth built-in** — fingerprint, humanize, proxy, multi-account
- **Any Chromium** — Chrome, Edge, CloakBrowser, or custom binary
- **Farm** — run multiple accounts in parallel
- **Network capture** — sniff requests, intercept, mock responses
- **AI Agent ready** — snapshot, extract, a11y for LLM integration

---

## Install

```bash
pip install nakalbrowser
```

```bash
python -m nakalbrowser doctor   # check environment
```

---

## Quick start

```python
from nakalbrowser import Engine

with Engine(headless=True) as bot:
    bot.open("https://example.com")
    print(bot.title)
    print(bot.find("h1").text)
    bot.find("a").click()
```

---

## Rush — HTTP + JS hybrid

```python
from nakalbrowser import Rush

# Pure HTTP (fast, no browser)
with Rush(impersonate="chrome") as r:
    resp = r.get("https://api.example.com/data")
    print(resp.json)

# Need JS? Render with browser
with Rush(headless=True) as r:
    r.render("https://spa.example.com", wait_for=".content", wait_until="networkidle")
    print(r.find("h1").text)
```

---

## Locators

```python
bot.locator("h1").click()
bot.locator("#email").fill("user@example.com")
bot.get_by_role("button", name="Submit").click()
bot.get_by_text("Welcome").expect().to_have_text("Welcome")
bot.locator("h1").expect().to_be_visible(timeout=5)
bot.locator("form").locator("input[type=text]").fill("x")
```

---

## Multi-account & Proxy

```python
from nakalbrowser import Engine, Face, Profile, Proxy

face = Face.from_seed("acc01", os="windows")
prof = Profile.create("acc01", solid=True, proxy="socks5://user:pass@host:1080")
with Engine(profile=prof, headless=True) as bot:
    bot.open("https://example.com")
```

---

## Farm — parallel execution

```python
from nakalbrowser import Farm, Profile

profiles = [Profile.create(f"acc_{i}", solid=True) for i in range(10)]
farm = Farm(profiles=profiles, concurrency=3, headless=True)
results = farm.run(lambda bot, prof: bot.open("https://target.com") or bot.title)
```

---

## Mouse & Keyboard

```python
bot.mouse.click(100, 200)
bot.mouse.drag(0, 0, 500, 500)
bot.keyboard.type("Hello World")
bot.keyboard.hotkey("Control", "a")
```

---

## Network

```python
# Capture
bot.sniff.start("**/api/**")
bot.open("https://example.com")
for c in bot.sniff.all():
    print(c.method, c.url, c.status)

# Mock
bot.intercept.fulfill("*/api/data", body='{"ok": true}', content_type="application/json")
```

---

## AI Agent

```python
with Engine(headless=True) as bot:
    bot.open("https://example.com")
    state = bot.snapshot(markdown=True)    # compact state for LLM
    data = bot.extract({"title": "h1", "links": "a@href[]"})
    bot.find("text:Learn more").click()
```

---

## API

| Class | What it does |
|---|---|
| `Engine` | Main browser controller |
| `Rush` | HTTP + JS render |
| `Face` | Fingerprint (save/load) |
| `Profile` | Multi-account bundle |
| `Proxy` | Proxy parse + auth bridge |
| `Farm` | Concurrent multi-profile |
| `Locator` | Playwright-style finder |
| `Mouse` / `Keyboard` | Precise input |
| `Page` / `Node` / `Ghost` | Tab / element / missing |
| `Pane` / `Shell` | iframe / shadow DOM |

Plus: `sniff`, `intercept`, `until`, `download`, `save_state` / `load_state`

---

## CLI

```bash
python -m nakalbrowser doctor
python -m nakalbrowser open https://example.com --headless
```

---

## Browser

```python
Engine()                       # auto-detect
Engine(browser="chrome")       # force Chrome
Engine(browser="edge")         # force Edge
Engine(browser_path="...")     # custom path
```

---

## MCP Server

One command to install MCP for Claude Code, Claude Desktop, Cursor:

```bash
nakalbrowser mcp
```

That's it. Restart your AI assistant and the tools are available.

**11 tools:** `browser_open`, `browser_click`, `browser_fill`, `browser_text`, `browser_screenshot`, `browser_extract`, `browser_js`, `http_get`, `http_post`, `scrape_links`, `browser_close`

---

## Docs

| File | Content |
|---|---|
| [docs/USAGE.md](docs/USAGE.md) | Full guide |
| [docs/AGENTS.md](docs/AGENTS.md) | Project structure for AI agents |

---

## License

MIT
