auto-captcha 0.1.0__tar.gz

auto_captcha-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Suhaas Chitturi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

auto_captcha-0.1.0/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: auto-captcha
+Version: 0.1.0
+Summary: Universal captcha solver for Playwright automation — hCaptcha + reCAPTCHA v2 via NopeCHA API
+Author: Suhaas Chitturi
+License: MIT
+Project-URL: Homepage, https://github.com/interfluve-wav/auto-captcha
+Project-URL: Repository, https://github.com/interfluve-wav/auto-captcha
+Project-URL: Issues, https://github.com/interfluve-wav/auto-captcha/issues
+Keywords: captcha,hcaptcha,recaptcha,playwright,automation,browser,solver
+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.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Testing
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28.0
+Provides-Extra: playwright
+Requires-Dist: playwright>=1.30.0; extra == "playwright"
+Provides-Extra: all
+Requires-Dist: playwright>=1.30.0; extra == "all"
+Dynamic: license-file
+
+# auto-captcha
+
+Universal captcha solver for Playwright browser automation. Detects hCaptcha and reCAPTCHA v2, solves them via the NopeCHA API, and injects tokens — so your scripts never get stuck.
+
+Works as a **Python library**, **CLI tool**, **MCP server**, and **Hermes skill**.
+
+## Install
+
+```bash
+pip install auto-captcha
+python -m playwright install chromium
+
+# Or from source
+git clone https://github.com/interfluve-wav/auto-captcha.git
+cd auto-captcha
+pip install -e ".[all]"
+```
+
+## Quick Start (1 line)
+
+```python
+from auto_captcha import smart_page
+
+with smart_page(api_key="your-key") as page:
+    page.goto("https://protected-site.com")
+    page.fill("#email", "user@example.com")
+    page.click("#submit")   # captcha auto-solved
+```
+
+## Three Ways to Use
+
+### 1. `smart_page()` — Context Manager (easiest)
+
+```python
+from auto_captcha import smart_page
+
+with smart_page(api_key="your-key") as page:
+    page.goto("https://example.com")
+    page.fill("#email", "user@test.com")
+    page.click("#submit")
+    print(page.captcha_log)  # [{'type': 'hcaptcha', 'status': 'solved'}]
+```
+
+### 2. `SmartPage` — Wrap Existing Browser
+
+```python
+from auto_captcha import SmartPage
+from playwright.sync_api import sync_playwright
+
+pw = sync_playwright().start()
+browser = pw.chromium.launch(headless=True)
+page = SmartPage(browser.new_page(), api_key="your-key")
+
+page.goto("https://example.com")
+page.fill("#input", "value")
+```
+
+### 3. `CaptchaSolver` — Full Control
+
+```python
+from auto_captcha import CaptchaSolver
+
+solver = CaptchaSolver(api_key="your-key")
+
+captchas = solver.detect(page)       # [{'type': 'hcaptcha', 'sitekey': '...'}]
+token = solver.solve("hcaptcha", sitekey, url)   # CaptchaResult(success=True, token='...')
+solver.inject(page, "hcaptcha", token)
+results = solver.auto_solve(page)    # detect + solve + inject
+```
+
+## CLI
+
+```bash
+# Check credits
+auto-captcha credits --key YOUR_KEY
+
+# Detect captchas
+auto-captcha detect --url https://example.com --key YOUR_KEY
+
+# Solve captchas
+auto-captcha solve --url https://example.com --key YOUR_KEY
+```
+
+## MCP Server (for AI agents)
+
+Works with Claude Code, OpenClaw, Cursor, and any MCP-compatible agent.
+
+```bash
+# Add to Claude Code
+claude mcp add auto-captcha -- python -m auto_captcha.mcp_server
+
+# Or configure in MCP config
+{
+  "mcpServers": {
+    "auto-captcha": {
+      "command": "python",
+      "args": ["-m", "auto_captcha.mcp_server"],
+      "env": {"NOPECHA_API_KEY": "your-key"}
+    }
+  }
+}
+```
+
+Provides three MCP tools:
+- `captcha_detect` — detect captchas on a URL
+- `captcha_solve` — detect and solve all captchas
+- `captcha_credits` — check NopeCHA credit balance
+
+## Hermes Skill
+
+Copy the `hermes-skill/` directory to `~/.hermes/skills/auto-captcha/` and set `NOPECHA_API_KEY` in your `.env`.
+
+## Supported Captcha Types
+
+| Type | Detection | Speed | Reliability |
+|------|-----------|-------|-------------|
+| hCaptcha (checkbox) | iframe + DOM | 10-40s | High |
+| hCaptcha (enterprise) | iframe + DOM | 10-40s | High |
+| reCAPTCHA v2 | iframe + DOM | 60-120s+ | Medium (queue) |
+
+**Not supported:** reCAPTCHA v3 (score-based, no challenge), Cloudflare Turnstile, FunCAPTCHA
+
+## Pitfalls
+
+- **reCAPTCHA queues are slow** — can take 60-120+ seconds during peak
+- **Each solve costs 1 credit** — check with `solver.get_credits()`
+- **Headless detection** — some sites block headless; use `headless=False`
+- **Lazy-loaded captchas** — add `time.sleep()` after actions that might trigger them
+
+## NopeCHA API Key
+
+Get free credits at [nopecha.com](https://nopecha.com). Set as environment variable:
+
+```bash
+export NOPECHA_API_KEY="your-key"
+```
+
+## License
+
+MIT

auto_captcha-0.1.0/README.md

@@ -0,0 +1,140 @@
+# auto-captcha
+
+Universal captcha solver for Playwright browser automation. Detects hCaptcha and reCAPTCHA v2, solves them via the NopeCHA API, and injects tokens — so your scripts never get stuck.
+
+Works as a **Python library**, **CLI tool**, **MCP server**, and **Hermes skill**.
+
+## Install
+
+```bash
+pip install auto-captcha
+python -m playwright install chromium
+
+# Or from source
+git clone https://github.com/interfluve-wav/auto-captcha.git
+cd auto-captcha
+pip install -e ".[all]"
+```
+
+## Quick Start (1 line)
+
+```python
+from auto_captcha import smart_page
+
+with smart_page(api_key="your-key") as page:
+    page.goto("https://protected-site.com")
+    page.fill("#email", "user@example.com")
+    page.click("#submit")   # captcha auto-solved
+```
+
+## Three Ways to Use
+
+### 1. `smart_page()` — Context Manager (easiest)
+
+```python
+from auto_captcha import smart_page
+
+with smart_page(api_key="your-key") as page:
+    page.goto("https://example.com")
+    page.fill("#email", "user@test.com")
+    page.click("#submit")
+    print(page.captcha_log)  # [{'type': 'hcaptcha', 'status': 'solved'}]
+```
+
+### 2. `SmartPage` — Wrap Existing Browser
+
+```python
+from auto_captcha import SmartPage
+from playwright.sync_api import sync_playwright
+
+pw = sync_playwright().start()
+browser = pw.chromium.launch(headless=True)
+page = SmartPage(browser.new_page(), api_key="your-key")
+
+page.goto("https://example.com")
+page.fill("#input", "value")
+```
+
+### 3. `CaptchaSolver` — Full Control
+
+```python
+from auto_captcha import CaptchaSolver
+
+solver = CaptchaSolver(api_key="your-key")
+
+captchas = solver.detect(page)       # [{'type': 'hcaptcha', 'sitekey': '...'}]
+token = solver.solve("hcaptcha", sitekey, url)   # CaptchaResult(success=True, token='...')
+solver.inject(page, "hcaptcha", token)
+results = solver.auto_solve(page)    # detect + solve + inject
+```
+
+## CLI
+
+```bash
+# Check credits
+auto-captcha credits --key YOUR_KEY
+
+# Detect captchas
+auto-captcha detect --url https://example.com --key YOUR_KEY
+
+# Solve captchas
+auto-captcha solve --url https://example.com --key YOUR_KEY
+```
+
+## MCP Server (for AI agents)
+
+Works with Claude Code, OpenClaw, Cursor, and any MCP-compatible agent.
+
+```bash
+# Add to Claude Code
+claude mcp add auto-captcha -- python -m auto_captcha.mcp_server
+
+# Or configure in MCP config
+{
+  "mcpServers": {
+    "auto-captcha": {
+      "command": "python",
+      "args": ["-m", "auto_captcha.mcp_server"],
+      "env": {"NOPECHA_API_KEY": "your-key"}
+    }
+  }
+}
+```
+
+Provides three MCP tools:
+- `captcha_detect` — detect captchas on a URL
+- `captcha_solve` — detect and solve all captchas
+- `captcha_credits` — check NopeCHA credit balance
+
+## Hermes Skill
+
+Copy the `hermes-skill/` directory to `~/.hermes/skills/auto-captcha/` and set `NOPECHA_API_KEY` in your `.env`.
+
+## Supported Captcha Types
+
+| Type | Detection | Speed | Reliability |
+|------|-----------|-------|-------------|
+| hCaptcha (checkbox) | iframe + DOM | 10-40s | High |
+| hCaptcha (enterprise) | iframe + DOM | 10-40s | High |
+| reCAPTCHA v2 | iframe + DOM | 60-120s+ | Medium (queue) |
+
+**Not supported:** reCAPTCHA v3 (score-based, no challenge), Cloudflare Turnstile, FunCAPTCHA
+
+## Pitfalls
+
+- **reCAPTCHA queues are slow** — can take 60-120+ seconds during peak
+- **Each solve costs 1 credit** — check with `solver.get_credits()`
+- **Headless detection** — some sites block headless; use `headless=False`
+- **Lazy-loaded captchas** — add `time.sleep()` after actions that might trigger them
+
+## NopeCHA API Key
+
+Get free credits at [nopecha.com](https://nopecha.com). Set as environment variable:
+
+```bash
+export NOPECHA_API_KEY="your-key"
+```
+
+## License
+
+MIT

auto_captcha-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "auto-captcha"
+version = "0.1.0"
+description = "Universal captcha solver for Playwright automation — hCaptcha + reCAPTCHA v2 via NopeCHA API"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.9"
+authors = [
+    {name = "Suhaas Chitturi"},
+]
+keywords = ["captcha", "hcaptcha", "recaptcha", "playwright", "automation", "browser", "solver"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Testing",
+    "Topic :: Internet :: WWW/HTTP",
+]
+dependencies = [
+    "requests>=2.28.0",
+]
+
+[project.optional-dependencies]
+playwright = ["playwright>=1.30.0"]
+all = ["playwright>=1.30.0"]
+
+[project.scripts]
+auto-captcha = "auto_captcha.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/interfluve-wav/auto-captcha"
+Repository = "https://github.com/interfluve-wav/auto-captcha"
+Issues = "https://github.com/interfluve-wav/auto-captcha/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]

auto_captcha-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

auto_captcha-0.1.0/src/auto_captcha/__init__.py

@@ -0,0 +1,7 @@
+"""auto-captcha: Universal captcha solver for Playwright automation."""
+
+from .solver import CaptchaSolver, CaptchaResult
+from .wrapper import SmartPage, smart_page
+
+__version__ = "0.1.0"
+__all__ = ["CaptchaSolver", "CaptchaResult", "SmartPage", "smart_page"]

auto_captcha-0.1.0/src/auto_captcha/cli.py

@@ -0,0 +1,96 @@
+#!/usr/bin/env python3
+"""
+auto-captcha CLI — solve captchas from the command line.
+
+Usage:
+    auto-captcha solve --url https://example.com --key YOUR_KEY
+    auto-captcha credits --key YOUR_KEY
+    auto-captcha detect --url https://example.com --key YOUR_KEY
+"""
+
+import argparse
+import json
+import os
+import sys
+import time
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="auto-captcha",
+        description="Universal captcha solver for Playwright automation",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    # -- solve --
+    solve_p = sub.add_parser("solve", help="Solve captchas on a URL")
+    solve_p.add_argument("--url", required=True, help="Page URL with captcha")
+    solve_p.add_argument("--key", default=os.environ.get("NOPECHA_API_KEY", ""), help="NopeCHA API key")
+    solve_p.add_argument("--headless", action="store_true", default=True)
+    solve_p.add_argument("--no-headless", action="store_false", dest="headless")
+    solve_p.add_argument("--timeout", type=float, default=120, help="Solve timeout in seconds")
+
+    # -- detect --
+    detect_p = sub.add_parser("detect", help="Detect captchas without solving")
+    detect_p.add_argument("--url", required=True, help="Page URL")
+    detect_p.add_argument("--key", default=os.environ.get("NOPECHA_API_KEY", ""), help="NopeCHA API key")
+    detect_p.add_argument("--headless", action="store_true", default=True)
+
+    # -- credits --
+    credits_p = sub.add_parser("credits", help="Check NopeCHA credit balance")
+    credits_p.add_argument("--key", default=os.environ.get("NOPECHA_API_KEY", ""), help="NopeCHA API key")
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    if not args.key:
+        print("Error: NopeCHA API key required. Set NOPECHA_API_KEY or use --key", file=sys.stderr)
+        sys.exit(1)
+
+    from auto_captcha import CaptchaSolver
+
+    solver = CaptchaSolver(api_key=args.key)
+
+    if args.command == "credits":
+        credits = solver.get_credits()
+        print(json.dumps({"credits": credits}))
+
+    elif args.command == "detect":
+        from playwright.sync_api import sync_playwright
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=args.headless, args=["--no-sandbox"])
+            page = browser.new_page()
+            page.goto(args.url, timeout=30000)
+            time.sleep(3)
+            captchas = solver.detect(page)
+            browser.close()
+        print(json.dumps(captchas, indent=2, default=str))
+
+    elif args.command == "solve":
+        from playwright.sync_api import sync_playwright
+        with sync_playwright() as p:
+            browser = p.chromium.launch(headless=args.headless, args=["--no-sandbox"])
+            page = browser.new_page()
+            page.goto(args.url, timeout=30000)
+            time.sleep(3)
+            results = solver.auto_solve(page)
+            browser.close()
+
+        output = []
+        for r in results:
+            output.append({
+                "type": r.captcha_type,
+                "success": r.success,
+                "token": r.token[:50] + "..." if len(r.token) > 50 else r.token,
+                "error": r.error,
+                "attempts": r.attempts,
+                "elapsed_sec": r.elapsed_sec,
+            })
+        print(json.dumps(output, indent=2))
+
+
+if __name__ == "__main__":
+    main()