Metadata-Version: 2.4
Name: captcha-router
Version: 0.1.3
Summary: Reusable captcha router with pluggable solver providers.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: aiohttp>=3.9
Provides-Extra: mcp
Requires-Dist: mcp>=1.0; extra == "mcp"
Requires-Dist: pydantic>=2.0; extra == "mcp"

# captcha-router

Reusable captcha router with pluggable providers.

## Install

```bash
pip install captcha-router
```

```bash
uv add captcha-router
```

## Supported providers

- `anticaptcha` (alias: `anti-captcha`)
- `2captcha` (alias: `twocaptcha`)

## Router methods

- `CaptchaRouter.list_providers()`: returns all registered provider names and aliases.
- `CaptchaRouter.list_provider_capabilities(include_aliases=False)`: returns provider -> supported captcha kinds.
- `CaptchaRouter.get_supported_task_kinds(provider_name)`: returns supported captcha kinds for one provider.
- `CaptchaRouter.list_supported_task_kinds()`: returns union of captcha kinds across providers.
- `CaptchaRouter.get_solver(provider_name=None, api_key=None, **kwargs)`: creates a solver instance and uses env fallbacks when `api_key` is omitted.

## Usage

### 1) Create a solver
```python
from captcha_router import CaptchaRouter

solver = CaptchaRouter.get_solver(provider_name="anticaptcha", api_key="YOUR_KEY")
```

### 2) Solve a task
```python
import asyncio
from captcha_router import CaptchaRouter, CaptchaTaskSpec


async def main():
    solver = CaptchaRouter.get_solver(provider_name="anticaptcha", api_key="YOUR_KEY")
    try:
        result = await solver.solve_task(
            CaptchaTaskSpec(
                kind="recaptcha_v2",
                params={
                    "website_url": "https://example.com",
                    "site_key": "SITE_KEY_HERE",
                },
            )
        )
        print(result.status, result.token, result.error)
    finally:
        await solver.close()


asyncio.run(main())
```

### 3) Inspect capabilities
```python
from captcha_router import CaptchaRouter

print(CaptchaRouter.list_providers())
print(CaptchaRouter.list_provider_capabilities())
```
