capsolver-core 0.1.0__tar.gz

capsolver_core-0.1.0/.gitignore

@@ -0,0 +1,44 @@
+# Byte-compiled / optimized
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Distribution
+dist/
+build/
+*.egg-info/
+*.egg
+*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+.cursor/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+.dmypy.json
+
+# Environment
+.env
+.env.local
+.python-version
+
+# Logs
+*.log
+
+# OS
+.DS_Store
+Thumbs.db

capsolver_core-0.1.0/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project follows semantic versioning where practical. Public releases are
+tagged in Git as `vX.Y.Z` and published to PyPI with the same version.
+
+## [0.1.0] - 2026-09-01
+
+### Added
+
+- Initial public release of `capsolver-core`.
+- Async CapSolver client for creating tasks, polling results, and checking
+  account balance.
+- Captcha detection and token autofill helpers for Playwright pages.
+- Built-in support for reCAPTCHA v2, reCAPTCHA v3, and Cloudflare Turnstile.
+- `capsolver` CLI for local diagnostics.
+

capsolver_core-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,39 @@
+# Contributing
+
+Thank you for your interest in `capsolver-core`.
+
+This repository is maintained by the CapSolver team. Issues and pull requests
+are welcome when they are focused on bugs, documentation, compatibility, or
+small improvements to the public SDK surface.
+
+## Before You Start
+
+- Search existing issues before opening a new one.
+- Open an issue before starting a large change.
+- Do not include real API keys, cookies, private URLs, or customer data in
+  issues, tests, examples, or screenshots.
+- Keep examples token-mode focused and use placeholder credentials.
+
+## Development
+
+```bash
+uv sync --all-extras
+uv run pytest
+uv run ruff check src tests
+uv run mypy src
+```
+
+If you do not use `uv`, install the development dependencies from
+`requirements-dev.txt` and run the equivalent commands with Python.
+
+## Pull Requests
+
+Pull requests should include:
+
+- A clear description of the change.
+- Tests or a short explanation of why tests are not needed.
+- Documentation updates for user-facing behavior.
+
+Maintainers may close changes that are outside the public SDK scope or require
+private service-side details.
+

capsolver_core-0.1.0/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2025-2026 capsolver-ai
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY
+AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM
+LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR
+OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR
+PERFORMANCE OF THIS SOFTWARE.

capsolver_core-0.1.0/PKG-INFO

@@ -0,0 +1,206 @@
+Metadata-Version: 2.5
+Name: capsolver-core
+Version: 0.1.0
+Summary: CapSolver core library — detect captchas, solve via API, and autofill tokens. Powers capsolver-agent and capsolver-mcp.
+Project-URL: Homepage, https://capsolver.com
+Project-URL: Repository, https://github.com/capsolver-ai/capsolver-core
+Project-URL: Issues, https://github.com/capsolver-ai/capsolver-core/issues
+Project-URL: Changelog, https://github.com/capsolver-ai/capsolver-core/blob/main/CHANGELOG.md
+Project-URL: Security, https://github.com/capsolver-ai/capsolver-core/blob/main/SECURITY.md
+Author-email: capsolver-ai <dev@capsolver.ai>
+License-Expression: ISC
+License-File: LICENSE
+Keywords: capsolver,captcha,recaptcha,turnstile
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest-asyncio>=1.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: playwright
+Requires-Dist: playwright>=1.40; extra == 'playwright'
+Description-Content-Type: text/markdown
+
+# capsolver-core
+
+A Python SDK for [CapSolver](https://capsolver.com) — detect captchas on a page, read their parameters, solve them via the CapSolver API, and write the token back.
+
+> **Token mode only.** This SDK solves captchas by requesting a token from the
+> CapSolver API (reCAPTCHA v2/v3, Cloudflare Turnstile).
+
+## Install
+
+```bash
+pip install capsolver-core
+```
+
+With Playwright support:
+
+```bash
+pip install capsolver-core[playwright]
+```
+
+Set your API key (or pass `api_key=` directly to `create_capsolver()`):
+
+```bash
+# bash / zsh
+export CAPSOLVER_API_KEY="your-capsolver-api-key"
+
+# PowerShell
+$env:CAPSOLVER_API_KEY = "your-capsolver-api-key"
+
+# cmd
+set CAPSOLVER_API_KEY=your-capsolver-api-key
+```
+
+## Two ways to use it
+
+### 1. Pure API (you already have the sitekey)
+
+No browser needed — give it the captcha parameters, get a token back.
+
+```python
+import asyncio
+from capsolver_core import create_capsolver, CaptchaType, CaptchaInfo
+
+async def main():
+    cap = create_capsolver(api_key="YOUR_API_KEY")
+
+    info = CaptchaInfo(
+        type=CaptchaType.RECAPTCHA_V2,
+        website_url="https://example.com",
+        website_key="6Lc...",
+    )
+    solution = await cap.solve(info)
+    print(solution.token)  # submit this as g-recaptcha-response
+
+asyncio.run(main())
+```
+
+### 2. Driving a real browser (Playwright)
+
+Detect, read params, solve, and autofill — all from a live page.
+
+```python
+import asyncio
+from capsolver_core import create_capsolver
+from playwright.async_api import async_playwright
+
+async def main():
+    cap = create_capsolver(api_key="YOUR_API_KEY")
+
+    async with async_playwright() as p:
+        browser = await p.chromium.launch()
+        page = await browser.new_page()
+        await page.goto("https://example.com/login")
+
+        # One-shot: detect every captcha, solve each, write tokens back.
+        results = await cap.solve_on_page(page)
+        for r in results:
+            print(r.info.type, r.solution.token if r.solution else None, r.filled, r.error)
+
+        # …or step by step:
+        types = await cap.detect(page)
+        infos = await cap.get_captcha_info(page)
+        solution = await cap.solve(infos[0])
+
+asyncio.run(main())
+```
+
+## CLI
+
+The `capsolver` command provides quick diagnostics without writing code.
+
+```bash
+# Show SDK version, Python version, and optional dependency status
+capsolver info
+
+# List all supported captcha types and registered handlers
+capsolver list-types
+
+# Check account balance (requires CAPSOLVER_API_KEY)
+capsolver balance
+capsolver balance --api-key YOUR_KEY
+```
+
+Also works via `python -m capsolver_core info`.
+
+## API
+
+### `create_capsolver(**options)` / `Capsolver(**options)`
+
+| Option              | Default                     | Description                            |
+|---------------------|-----------------------------|----------------------------------------|
+| `api_key`           | —                           | CapSolver client key (required to solve)|
+| `service`           | `https://api.capsolver.com` | API base URL                           |
+| `default_timeout`   | `120`                       | Polling budget, seconds                |
+| `polling_interval`  | `5`                         | Delay between result polls, seconds    |
+| `request_timeout_ms`| `30000`                     | Per-HTTP-request timeout               |
+| `app_id`            | —                           | Developer/affiliate id                 |
+| `handlers`          | all built-ins               | Override the registered captcha handlers|
+| `source`            | —                           | Traffic source identifier              |
+| `version`           | —                           | Client version tag                     |
+| `on_error`          | —                           | Callback for non-fatal errors          |
+
+### Resource cleanup
+
+`Capsolver` holds an internal HTTP connection pool. Use it as an async context
+manager to ensure connections are released:
+
+```python
+async with create_capsolver(api_key="YOUR_API_KEY") as cap:
+    solution = await cap.solve(info)
+```
+
+Or call `await cap.aclose()` explicitly when done.
+
+### Methods
+
+- `solve(info, wait_options?)` → `Solution` — solve from a `CaptchaInfo`.
+- `detect(page)` → `list[CaptchaType]` — which captchas are present.
+- `get_captcha_info(page)` → `list[CaptchaInfo]` — structured params per widget.
+- `solve_on_page(page, options?)` → `list[SolveOnPageResult]` — detect → solve → autofill.
+- `get_balance()` → `BalanceResp` — account balance.
+- `register(handler)` / `get_supported_captchas()` / `get_handler(key)` — registry access.
+
+### Supported captchas
+
+`reCaptchaV2`, `reCaptchaV3` (incl. enterprise), `cloudflare` (Turnstile).
+
+## Architecture
+
+```
+src/capsolver_core/
+  __init__.py   public API surface (all exports)
+  __main__.py   CLI entry point (capsolver command)
+  core/         pure-Python token solving (http, client, task builders, types)
+  captcha/      handler registry + per-captcha handlers (the plugin layer)
+  browser/      PageDriver adapter + self-contained in-page inject scripts
+  capsolver.py  public Capsolver class
+```
+
+## Development
+
+```bash
+git clone https://github.com/capsolver-ai/capsolver-core.git
+cd capsolver-core
+uv sync --all-extras          # or: pip install -r requirements-dev.txt
+uv run pytest                 # run tests
+uv run ruff check src tests   # lint
+```
+
+## License
+
+ISC

capsolver_core-0.1.0/PUBLISHING.md

@@ -0,0 +1,108 @@
+# Publishing
+
+Release target: `capsolver-core` version `0.1.0`, prepared for public release on
+2026-09-01.
+
+This checklist is for maintainers syncing the prepared public files to the
+official open-source repository, testing the package on TestPyPI, and then
+publishing the final package to PyPI.
+
+## Preconditions
+
+- The source is the prepared public copy, not a private development checkout.
+- `pyproject.toml` has `version = "0.1.0"`.
+- `CHANGELOG.md` has `## [0.1.0] - 2026-09-01`.
+- `README.md`, `LICENSE`, `SECURITY.md`, `CONTRIBUTING.md`, and `SUPPORT.md`
+  are present.
+- Documentation examples use placeholder credentials only.
+- The tree does not contain `.git`, `.venv`, `uv.lock`, caches, local path
+  overrides, real API keys, browser profiles, or private service data.
+
+## Sync to the Official Open-Source Repository
+
+Copy this directory into the official `capsolver-core` public repository working
+tree, then review the diff before committing.
+
+```bash
+git status
+git diff
+git add .
+git commit -m "Release v0.1.0"
+git status
+```
+
+Do not tag until the build, TestPyPI upload, and install test have passed.
+
+## Verify Locally
+
+```bash
+uv sync --all-extras
+uv run pytest
+uv run ruff check src tests
+uv run mypy src
+```
+
+## Build and Check
+
+```bash
+python -m pip install --upgrade build twine
+python -m build
+python -m twine check dist/*
+```
+
+Inspect the source distribution and wheel before upload. Confirm that no
+private files, local paths, secrets, browser profiles, caches, or test output
+are included.
+
+## TestPyPI Test Release
+
+Upload the exact distribution files to TestPyPI first.
+
+```bash
+python -m twine upload --repository testpypi dist/*
+```
+
+Install from TestPyPI in a clean environment and smoke-test the CLI import path.
+
+```bash
+python -m pip install --index-url https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ capsolver-core==0.1.0
+python -c "import capsolver_core; print(capsolver_core.__version__)"
+capsolver --help
+```
+
+PyPI and TestPyPI distributions cannot be overwritten. If the test upload is
+wrong, fix the issue and publish a new version.
+
+## Formal PyPI Release
+
+After TestPyPI passes, upload the same checked distribution files to PyPI.
+
+```bash
+python -m twine upload dist/*
+```
+
+Then verify installation from PyPI.
+
+```bash
+python -m pip install capsolver-core==0.1.0
+python -c "import capsolver_core; print(capsolver_core.__version__)"
+capsolver --help
+```
+
+## Tag and GitHub Release
+
+When the PyPI release is verified, create the release tag and push it from the
+official public repository.
+
+```bash
+git tag v0.1.0
+git push origin main
+git push origin v0.1.0
+```
+
+Create a GitHub Release for `v0.1.0` using the `CHANGELOG.md` entry.
+
+Prefer PyPI Trusted Publishing from the official public GitHub repository for
+future releases. If manual upload is used, use a project-scoped PyPI API token
+instead of an account password.
+

capsolver_core-0.1.0/README.md

@@ -0,0 +1,171 @@
+# capsolver-core
+
+A Python SDK for [CapSolver](https://capsolver.com) — detect captchas on a page, read their parameters, solve them via the CapSolver API, and write the token back.
+
+> **Token mode only.** This SDK solves captchas by requesting a token from the
+> CapSolver API (reCAPTCHA v2/v3, Cloudflare Turnstile).
+
+## Install
+
+```bash
+pip install capsolver-core
+```
+
+With Playwright support:
+
+```bash
+pip install capsolver-core[playwright]
+```
+
+Set your API key (or pass `api_key=` directly to `create_capsolver()`):
+
+```bash
+# bash / zsh
+export CAPSOLVER_API_KEY="your-capsolver-api-key"
+
+# PowerShell
+$env:CAPSOLVER_API_KEY = "your-capsolver-api-key"
+
+# cmd
+set CAPSOLVER_API_KEY=your-capsolver-api-key
+```
+
+## Two ways to use it
+
+### 1. Pure API (you already have the sitekey)
+
+No browser needed — give it the captcha parameters, get a token back.
+
+```python
+import asyncio
+from capsolver_core import create_capsolver, CaptchaType, CaptchaInfo
+
+async def main():
+    cap = create_capsolver(api_key="YOUR_API_KEY")
+
+    info = CaptchaInfo(
+        type=CaptchaType.RECAPTCHA_V2,
+        website_url="https://example.com",
+        website_key="6Lc...",
+    )
+    solution = await cap.solve(info)
+    print(solution.token)  # submit this as g-recaptcha-response
+
+asyncio.run(main())
+```
+
+### 2. Driving a real browser (Playwright)
+
+Detect, read params, solve, and autofill — all from a live page.
+
+```python
+import asyncio
+from capsolver_core import create_capsolver
+from playwright.async_api import async_playwright
+
+async def main():
+    cap = create_capsolver(api_key="YOUR_API_KEY")
+
+    async with async_playwright() as p:
+        browser = await p.chromium.launch()
+        page = await browser.new_page()
+        await page.goto("https://example.com/login")
+
+        # One-shot: detect every captcha, solve each, write tokens back.
+        results = await cap.solve_on_page(page)
+        for r in results:
+            print(r.info.type, r.solution.token if r.solution else None, r.filled, r.error)
+
+        # …or step by step:
+        types = await cap.detect(page)
+        infos = await cap.get_captcha_info(page)
+        solution = await cap.solve(infos[0])
+
+asyncio.run(main())
+```
+
+## CLI
+
+The `capsolver` command provides quick diagnostics without writing code.
+
+```bash
+# Show SDK version, Python version, and optional dependency status
+capsolver info
+
+# List all supported captcha types and registered handlers
+capsolver list-types
+
+# Check account balance (requires CAPSOLVER_API_KEY)
+capsolver balance
+capsolver balance --api-key YOUR_KEY
+```
+
+Also works via `python -m capsolver_core info`.
+
+## API
+
+### `create_capsolver(**options)` / `Capsolver(**options)`
+
+| Option              | Default                     | Description                            |
+|---------------------|-----------------------------|----------------------------------------|
+| `api_key`           | —                           | CapSolver client key (required to solve)|
+| `service`           | `https://api.capsolver.com` | API base URL                           |
+| `default_timeout`   | `120`                       | Polling budget, seconds                |
+| `polling_interval`  | `5`                         | Delay between result polls, seconds    |
+| `request_timeout_ms`| `30000`                     | Per-HTTP-request timeout               |
+| `app_id`            | —                           | Developer/affiliate id                 |
+| `handlers`          | all built-ins               | Override the registered captcha handlers|
+| `source`            | —                           | Traffic source identifier              |
+| `version`           | —                           | Client version tag                     |
+| `on_error`          | —                           | Callback for non-fatal errors          |
+
+### Resource cleanup
+
+`Capsolver` holds an internal HTTP connection pool. Use it as an async context
+manager to ensure connections are released:
+
+```python
+async with create_capsolver(api_key="YOUR_API_KEY") as cap:
+    solution = await cap.solve(info)
+```
+
+Or call `await cap.aclose()` explicitly when done.
+
+### Methods
+
+- `solve(info, wait_options?)` → `Solution` — solve from a `CaptchaInfo`.
+- `detect(page)` → `list[CaptchaType]` — which captchas are present.
+- `get_captcha_info(page)` → `list[CaptchaInfo]` — structured params per widget.
+- `solve_on_page(page, options?)` → `list[SolveOnPageResult]` — detect → solve → autofill.
+- `get_balance()` → `BalanceResp` — account balance.
+- `register(handler)` / `get_supported_captchas()` / `get_handler(key)` — registry access.
+
+### Supported captchas
+
+`reCaptchaV2`, `reCaptchaV3` (incl. enterprise), `cloudflare` (Turnstile).
+
+## Architecture
+
+```
+src/capsolver_core/
+  __init__.py   public API surface (all exports)
+  __main__.py   CLI entry point (capsolver command)
+  core/         pure-Python token solving (http, client, task builders, types)
+  captcha/      handler registry + per-captcha handlers (the plugin layer)
+  browser/      PageDriver adapter + self-contained in-page inject scripts
+  capsolver.py  public Capsolver class
+```
+
+## Development
+
+```bash
+git clone https://github.com/capsolver-ai/capsolver-core.git
+cd capsolver-core
+uv sync --all-extras          # or: pip install -r requirements-dev.txt
+uv run pytest                 # run tests
+uv run ruff check src tests   # lint
+```
+
+## License
+
+ISC

capsolver_core-0.1.0/SECURITY.md

@@ -0,0 +1,30 @@
+# Security Policy
+
+## Supported Versions
+
+Security fixes are provided for the latest public release line.
+
+| Version | Supported |
+| ------- | --------- |
+| 0.1.x   | Yes       |
+
+## Reporting a Vulnerability
+
+Please do not open public issues for vulnerabilities, leaked credentials, or
+reports that include private target URLs, API keys, or customer data.
+
+Report security issues by emailing `dev@capsolver.ai` with:
+
+- The affected package and version.
+- A concise description of the issue.
+- Reproduction steps or a minimal proof of concept.
+- The impact you believe the issue has.
+
+We will acknowledge valid reports as soon as possible and coordinate a fix or
+mitigation before public disclosure.
+
+## Handling API Keys
+
+Never commit real `CAPSOLVER_API_KEY` values, browser profiles, cookies, or
+captured tokens. Documentation examples must use placeholder values only.
+

capsolver_core-0.1.0/SUPPORT.md

@@ -0,0 +1,24 @@
+# Support
+
+Use the right channel for the type of help you need.
+
+## Package Bugs and Documentation
+
+Open a GitHub issue for:
+
+- Installation problems.
+- Runtime errors in this package.
+- Documentation mistakes.
+- Compatibility issues with supported Python versions or Playwright.
+
+Include the package version, Python version, operating system, and a minimal
+reproduction when possible.
+
+## CapSolver Account or API Service Issues
+
+For account access, billing, API key, balance, or service availability issues,
+use the support options available from `https://capsolver.com`.
+
+Do not post API keys, account identifiers, cookies, browser profiles, or target
+site credentials in public issues.
+