# WebRobo API

Browser automation API with built-in anti-bot stealth. Send a URL and a sequence of declarative actions — fill a field,
click, wait for an element — and get back the rendered page, including sites behind Cloudflare-style JS challenges.

## Status

Early MVP (v0), under active development. Single browser engine, no queue, no billing yet — see [Roadmap](#roadmap).

## Architecture

```
Client → Caddy (TLS) → FastAPI → API-key auth → semaphore acquire
                                                       │
                                                       ▼
                                          Camoufox browser context
                                          (run actions, collect result)
                                                       │
                                                       ▼
                                          release semaphore → response
```

- **Engine**: [Camoufox](https://camoufox.com/) (stealth Firefox, driven via Playwright). Chosen for v1 because
  Firefox-based fingerprinting is less commoditized against anti-bot vendors than patched Chromium.
- **API**: FastAPI, single versioned endpoint (`POST /v1/solve`).
- **Concurrency**: bounded by an `asyncio.Semaphore` over browser contexts — no external job queue in v1. Simpler to
  run, hard ceiling on throughput per instance (see Roadmap for scaling out).
- **Auth**: per-client API key (`X-API-Key` header), checked against a SQLite table. (SQLAlchemy ORM)
- **Logging**: every request's outcome (success/failure/duration) is persisted — this becomes the success-rate data used
  to evaluate the service and talk to clients about reliability.
- **Proxies**: not managed by the service in v1 — the client supplies their own proxy per request if they need one.
- **Deployment**: single Docker container behind a Caddy reverse proxy.

### Planned project layout

```
src/
  main.py            # FastAPI app + router wiring
  config.py          # settings (env vars)
  api/
    solve.py         # POST /v1/solve
    deps.py          # API-key auth dependency
  engine/
    browser.py       # Camoufox context pool + semaphore
    actions.py       # fill / click / wait_for execution
    schemas.py       # SolveRequest / SolveResponse / Action models
  db/
    models.py        # api_keys, request_logs
    session.py
tests/
wheels/              # whl библиотеки для оффлайн установки под Ubuntu Noble
Dockerfile
requirements.txt
env.example
```

## API (draft)

```
POST /v1/solve
X-API-Key: <key>

{
	"captcha": "token",
	"url": "https://example.com/login",
	"actions": [
		{"type": "fill", "selector": "#email",  "value": "user@example.com"},
		{"type": "fill", "selector": "#password", "value": "..."},
		{"type": "mouse_move", "selector": "#submit"},
		{"type": "click", "selector": "#submit"},
		{"type": "wait_for", "selector": ".dashboard", "timeout": 30}
	],
	"proxy": "socks5://user:pass@host:port",
	"screen": "1280x920",
	"user_agent": "Firefox",
	"timeout": 120
}
```

Response:

```json
{
	"status": "ok",
	"html": "<html>...</html>",
	"cookies": [
		{
			"name": "session",
			"value": "..."
		}
	],
	"actions_result": [
		{
			"type": "fill",
			"ok": true
		},
		{
			"type": "fill",
			"ok": true
		},
		{
			"type": "click",
			"ok": true
		},
		{
			"type": "wait_for",
			"ok": true
		}
	],
	"error": null
}
```

On failure, `status` is `"error"` and `error` carries a machine-readable reason (`selector_not_found`, `timeout`,
`navigation_failed`, ...).

Fill команда включает 3 действия

1. `{"type": "mouse_move", "selector": "#email"},` - навести мышку на элемент
2. `{"type": "click"},` - клик в текущие координаты
3. `{"type": "typing", "value": "user@example.com"},` - набор текста

## Roadmap

Deliberately out of scope for v1:

- Second engine (Patchright/Chromium) for targets where the Firefox fingerprint doesn't fit
- Job queue (Redis/RabbitMQ) + multiple worker VPS for horizontal scaling
- Real billing/usage plans beyond a flat API-key check
- Broader action vocabulary beyond fill/click/wait_for

## Local development

```bash
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
uvicorn app.main:app --reload
```