botasaurus-turnstile 0.1.0__tar.gz

botasaurus_turnstile-0.1.0/.gitignore

@@ -0,0 +1,5 @@
+dist/
+build/
+*.egg-info/
+__pycache__/
+*.pyc

botasaurus_turnstile-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peak
+
+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.

botasaurus_turnstile-0.1.0/PKG-INFO

@@ -0,0 +1,109 @@
+Metadata-Version: 2.5
+Name: botasaurus-turnstile
+Version: 0.1.0
+Summary: Solve Cloudflare Turnstile in Botasaurus via the Peak API — read the sitekey, get a token, inject it. For when the anti-detect driver still stalls on the widget.
+Project-URL: Homepage, https://peak.fo/?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=botasaurus-turnstile
+Project-URL: Documentation, https://peak.fo/docs/turnstile?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=botasaurus-turnstile
+Project-URL: Pricing, https://peak.fo/pricing?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=botasaurus-turnstile
+Project-URL: Source, https://github.com/CircuitSavage/botasaurus-turnstile
+Author: Peak
+License: MIT
+License-File: LICENSE
+Keywords: anti-detect,botasaurus,bypass,captcha,cf-clearance,cloudflare,scraping,solver,turnstile
+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 :: Only
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.8
+Provides-Extra: botasaurus
+Requires-Dist: botasaurus-driver>=4.0; extra == 'botasaurus'
+Description-Content-Type: text/markdown
+
+<a href="https://peak.fo/?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=botasaurus-turnstile">
+  <img src="https://raw.githubusercontent.com/CircuitSavage/botasaurus-turnstile/main/assets/peak-banner.png" alt="Peak — solve Cloudflare Turnstile & the 5s challenge in ~1s" width="100%">
+</a>
+
+# botasaurus-turnstile
+
+**botasaurus-turnstile** solves Cloudflare Turnstile on a [Botasaurus](https://github.com/omkarcloud/botasaurus) driver by injecting a Peak-solved token, so a protected form or navigation proceeds.
+
+## Why
+
+Botasaurus drives an anti-detect Chrome and ships a lot of Cloudflare handling, which is why people run it against protected sites. The interstitial often clears. The Turnstile *widget* on a datacenter IP is the part that doesn't — it renders, waits for a click or a token that never comes, and the run stalls.
+
+This reads the sitekey from the DOM, gets a token from Peak, and injects it as the `cf-turnstile-response` value plus the widget's success callback. When the driver gets you to the page but the widget won't clear, drop in a Peak API key and it goes through.
+
+## Powered by Peak
+
+This package uses [Peak](https://peak.fo/?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=botasaurus-turnstile) to solve Turnstile.
+- Solve Cloudflare Turnstile & the 5s challenge in about a second
+- $0.90 per 1,000 successful Turnstile solves, down to $0.35 at volume
+- 1,000 free solves to start, no card.
+
+→ [Get your free API key](https://peak.fo/?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=botasaurus-turnstile) · [Docs](https://peak.fo/docs/turnstile?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=botasaurus-turnstile) · [Pricing](https://peak.fo/pricing?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=botasaurus-turnstile)
+
+## Install
+
+```bash
+pip install botasaurus-turnstile botasaurus-driver
+```
+
+## Quickstart
+
+```python
+import os
+from botasaurus.browser import browser, Driver
+from botasaurus_turnstile import solve_turnstile
+
+os.environ["PEAK_API_KEY"] = "pk_your_api_key"
+
+
+@browser
+def scrape(driver: Driver, data):
+    driver.get("https://protected.example/login")
+
+    # Reads the sitekey from the page, solves via Peak, injects the token.
+    solve_turnstile(driver)
+
+    # the form / navigation can now proceed
+
+
+scrape()
+```
+
+Works the same with a standalone `botasaurus_driver.Driver()` — anything that exposes `run_js` and `current_url`.
+
+## How it works
+
+1. **Read the sitekey.** A `run_js` DOM scan finds the `data-sitekey` on the `.cf-turnstile` widget, or the sitekey set through a JS `render()` call.
+2. **Solve via Peak.** `POST https://api.peak.fo/solve` with `task_type: "turnstiletask"`, the sitekey, and the driver's current URL. Pass `proxy=` to mint the token from your browser's egress IP.
+3. **Inject the token.** `run_js` sets every `cf-turnstile-response` field, fires `input`/`change`, and calls the widget's `data-callback` so the form or navigation continues.
+
+## API
+
+```python
+solve_turnstile(
+    driver,               # a Botasaurus Driver
+    api_key=None,         # defaults to env PEAK_API_KEY
+    proxy=None,           # optional http://user:pass@ip:port, forwarded to Peak
+    sitekey=None,         # override auto-detection (e.g. widget in a frame)
+    url=None,             # defaults to driver.current_url
+    task_type="turnstiletask",
+    timeout=180.0,
+) -> str                  # the injected token
+```
+
+`read_sitekey(driver)` and `inject_token(driver, token)` are exposed for finer control. Peak also supports `task_type="cloudflare5stask"` for the 5s interstitial.
+
+The API key is read from `PEAK_API_KEY` by default; you can also pass it explicitly. Never hardcode a real key.
+
+## Legitimate use
+
+For automation, QA, and scraping public data you are allowed to access. Respect each target's Terms of Service and robots directives, and do not use this for credential-stuffing or other abuse.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

botasaurus_turnstile-0.1.0/README.md

@@ -0,0 +1,85 @@
+<a href="https://peak.fo/?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=botasaurus-turnstile">
+  <img src="https://raw.githubusercontent.com/CircuitSavage/botasaurus-turnstile/main/assets/peak-banner.png" alt="Peak — solve Cloudflare Turnstile & the 5s challenge in ~1s" width="100%">
+</a>
+
+# botasaurus-turnstile
+
+**botasaurus-turnstile** solves Cloudflare Turnstile on a [Botasaurus](https://github.com/omkarcloud/botasaurus) driver by injecting a Peak-solved token, so a protected form or navigation proceeds.
+
+## Why
+
+Botasaurus drives an anti-detect Chrome and ships a lot of Cloudflare handling, which is why people run it against protected sites. The interstitial often clears. The Turnstile *widget* on a datacenter IP is the part that doesn't — it renders, waits for a click or a token that never comes, and the run stalls.
+
+This reads the sitekey from the DOM, gets a token from Peak, and injects it as the `cf-turnstile-response` value plus the widget's success callback. When the driver gets you to the page but the widget won't clear, drop in a Peak API key and it goes through.
+
+## Powered by Peak
+
+This package uses [Peak](https://peak.fo/?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=botasaurus-turnstile) to solve Turnstile.
+- Solve Cloudflare Turnstile & the 5s challenge in about a second
+- $0.90 per 1,000 successful Turnstile solves, down to $0.35 at volume
+- 1,000 free solves to start, no card.
+
+→ [Get your free API key](https://peak.fo/?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=botasaurus-turnstile) · [Docs](https://peak.fo/docs/turnstile?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=botasaurus-turnstile) · [Pricing](https://peak.fo/pricing?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=botasaurus-turnstile)
+
+## Install
+
+```bash
+pip install botasaurus-turnstile botasaurus-driver
+```
+
+## Quickstart
+
+```python
+import os
+from botasaurus.browser import browser, Driver
+from botasaurus_turnstile import solve_turnstile
+
+os.environ["PEAK_API_KEY"] = "pk_your_api_key"
+
+
+@browser
+def scrape(driver: Driver, data):
+    driver.get("https://protected.example/login")
+
+    # Reads the sitekey from the page, solves via Peak, injects the token.
+    solve_turnstile(driver)
+
+    # the form / navigation can now proceed
+
+
+scrape()
+```
+
+Works the same with a standalone `botasaurus_driver.Driver()` — anything that exposes `run_js` and `current_url`.
+
+## How it works
+
+1. **Read the sitekey.** A `run_js` DOM scan finds the `data-sitekey` on the `.cf-turnstile` widget, or the sitekey set through a JS `render()` call.
+2. **Solve via Peak.** `POST https://api.peak.fo/solve` with `task_type: "turnstiletask"`, the sitekey, and the driver's current URL. Pass `proxy=` to mint the token from your browser's egress IP.
+3. **Inject the token.** `run_js` sets every `cf-turnstile-response` field, fires `input`/`change`, and calls the widget's `data-callback` so the form or navigation continues.
+
+## API
+
+```python
+solve_turnstile(
+    driver,               # a Botasaurus Driver
+    api_key=None,         # defaults to env PEAK_API_KEY
+    proxy=None,           # optional http://user:pass@ip:port, forwarded to Peak
+    sitekey=None,         # override auto-detection (e.g. widget in a frame)
+    url=None,             # defaults to driver.current_url
+    task_type="turnstiletask",
+    timeout=180.0,
+) -> str                  # the injected token
+```
+
+`read_sitekey(driver)` and `inject_token(driver, token)` are exposed for finer control. Peak also supports `task_type="cloudflare5stask"` for the 5s interstitial.
+
+The API key is read from `PEAK_API_KEY` by default; you can also pass it explicitly. Never hardcode a real key.
+
+## Legitimate use
+
+For automation, QA, and scraping public data you are allowed to access. Respect each target's Terms of Service and robots directives, and do not use this for credential-stuffing or other abuse.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).

botasaurus_turnstile-0.1.0/botasaurus_turnstile/__init__.py

@@ -0,0 +1,34 @@
+"""botasaurus-turnstile: solve Cloudflare Turnstile in Botasaurus via Peak.
+
+Public API::
+
+    from botasaurus_turnstile import solve_turnstile
+    token = solve_turnstile(driver, api_key="pk_...")
+"""
+
+from __future__ import annotations
+
+from .peak import (
+    DEFAULT_API_URL,
+    TASK_CLOUDFLARE_5S,
+    TASK_TURNSTILE,
+    PeakClient,
+    PeakError,
+    build_solve_payload,
+)
+from .solver import inject_token, read_sitekey, solve_turnstile
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "solve_turnstile",
+    "read_sitekey",
+    "inject_token",
+    "PeakClient",
+    "PeakError",
+    "build_solve_payload",
+    "DEFAULT_API_URL",
+    "TASK_TURNSTILE",
+    "TASK_CLOUDFLARE_5S",
+    "__version__",
+]

botasaurus_turnstile-0.1.0/botasaurus_turnstile/peak.py

@@ -0,0 +1,110 @@
+"""Peak API client for solving Cloudflare Turnstile.
+
+Kept free of any Botasaurus dependency so it can be unit tested and reused
+on its own. The HTTP call uses the standard library only.
+"""
+
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+from typing import Optional
+
+DEFAULT_API_URL = "https://api.peak.fo/solve"
+
+# task_type sent to Peak for the Turnstile widget challenge.
+TASK_TURNSTILE = "turnstiletask"
+# Peak also supports the 5s interstitial via this task_type.
+TASK_CLOUDFLARE_5S = "cloudflare5stask"
+
+
+class PeakError(RuntimeError):
+    """Raised when Peak cannot solve the challenge or the call fails."""
+
+
+def build_solve_payload(
+    sitekey: str,
+    url: str,
+    proxy: Optional[str] = None,
+    task_type: str = TASK_TURNSTILE,
+) -> dict:
+    """Build the JSON body for POST https://api.peak.fo/solve.
+
+    ``proxy`` is omitted entirely when not provided, per the Peak contract.
+    """
+    payload = {
+        "task_type": task_type,
+        "sitekey": sitekey,
+        "url": url,
+    }
+    if proxy:
+        payload["proxy"] = proxy
+    return payload
+
+
+class PeakClient:
+    """Thin client around the Peak solve endpoint."""
+
+    def __init__(
+        self,
+        api_key: str,
+        api_url: str = DEFAULT_API_URL,
+        proxy: Optional[str] = None,
+        timeout: float = 180.0,
+    ) -> None:
+        if not api_key:
+            raise PeakError(
+                "No Peak API key. Set PEAK_API_KEY (get a free key at "
+                "https://peak.fo)."
+            )
+        self.api_key = api_key
+        self.api_url = api_url
+        self.proxy = proxy
+        self.timeout = timeout
+
+    def _post(self, payload: dict) -> dict:
+        data = json.dumps(payload).encode("utf-8")
+        req = urllib.request.Request(
+            self.api_url,
+            data=data,
+            method="POST",
+            headers={
+                "Content-Type": "application/json",
+                "X-API-Key": self.api_key,
+                "User-Agent": "botasaurus-turnstile/0.1.0 (+https://github.com/CircuitSavage/botasaurus-turnstile)",
+            },
+        )
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as resp:
+                body = resp.read().decode("utf-8")
+        except urllib.error.HTTPError as exc:  # pragma: no cover - network path
+            body = exc.read().decode("utf-8", "replace")
+        except urllib.error.URLError as exc:  # pragma: no cover - network path
+            raise PeakError(f"Peak request failed: {exc}") from exc
+        try:
+            return json.loads(body)
+        except ValueError as exc:  # pragma: no cover - defensive
+            raise PeakError(f"Peak returned non-JSON response: {body!r}") from exc
+
+    def solve(
+        self,
+        sitekey: str,
+        url: str,
+        proxy: Optional[str] = None,
+        task_type: str = TASK_TURNSTILE,
+    ) -> str:
+        """Solve a Turnstile challenge and return the token string.
+
+        Raises :class:`PeakError` on failure.
+        """
+        payload = build_solve_payload(
+            sitekey, url, proxy=proxy or self.proxy, task_type=task_type
+        )
+        result = self._post(payload)
+        if not result.get("success"):
+            raise PeakError(result.get("error") or "Peak solve failed")
+        token = (result.get("data") or {}).get("token")
+        if not token:
+            raise PeakError("Peak response missing data.token")
+        return token

botasaurus_turnstile-0.1.0/botasaurus_turnstile/solver.py

@@ -0,0 +1,123 @@
+"""Solve Cloudflare Turnstile on a live Botasaurus driver via the Peak API.
+
+Botasaurus drives an anti-detect Chrome and is a common pick against
+Cloudflare. When the Turnstile widget still stalls, this reads the sitekey,
+gets a token from Peak, and injects it so the form or navigation proceeds.
+
+Works with the Botasaurus ``Driver`` (uses ``run_js`` and ``current_url``).
+Botasaurus itself is an optional import.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Optional
+
+from .peak import DEFAULT_API_URL, TASK_TURNSTILE, PeakClient, PeakError
+
+_READ_SITEKEY_JS = r"""
+var el = document.querySelector('[data-sitekey]');
+if (el) { return el.getAttribute('data-sitekey'); }
+var m = (document.documentElement.outerHTML || '').match(
+    /(?:sitekey|render)\s*[:=]\s*["']((?:0x|1x)[^"']+)["']/i);
+return m ? m[1] : null;
+"""
+
+# Injects a solved token: sets every cf-turnstile-response field, fires
+# input/change so listeners react, and calls the widget's success callback.
+# The token is embedded as a JSON literal in inject_token.
+_INJECT_TOKEN_BODY = r"""
+var fields = document.querySelectorAll(
+    'input[name="cf-turnstile-response"], textarea[name="cf-turnstile-response"], ' +
+    'input#cf-turnstile-response, [name="cf-turnstile-response"]');
+if (!fields.length) {
+    var holder = document.querySelector('.cf-turnstile') || document.body;
+    var inp = document.createElement('input');
+    inp.type = 'hidden';
+    inp.name = 'cf-turnstile-response';
+    holder.appendChild(inp);
+    fields = [inp];
+}
+fields.forEach(function (f) {
+    f.value = token;
+    f.dispatchEvent(new Event('input', { bubbles: true }));
+    f.dispatchEvent(new Event('change', { bubbles: true }));
+});
+var called = false;
+document.querySelectorAll('[data-callback]').forEach(function (w) {
+    var name = w.getAttribute('data-callback');
+    if (name && typeof window[name] === 'function') {
+        window[name](token);
+        called = true;
+    }
+});
+return called;
+"""
+
+
+def read_sitekey(driver) -> Optional[str]:
+    """Return the Turnstile sitekey on the current page, or None."""
+    sitekey = driver.run_js(_READ_SITEKEY_JS)
+    if sitekey:
+        return str(sitekey).strip()
+    return None
+
+
+def inject_token(driver, token: str) -> None:
+    """Inject a solved token into the page's Turnstile widget."""
+    driver.run_js("var token = " + json.dumps(token) + ";\n" + _INJECT_TOKEN_BODY)
+
+
+def _current_url(driver) -> Optional[str]:
+    try:
+        url = getattr(driver, "current_url", None)
+        if url:
+            return url
+    except Exception:
+        pass
+    try:
+        return driver.run_js("return window.location.href")
+    except Exception:
+        return None
+
+
+def solve_turnstile(
+    driver,
+    api_key: Optional[str] = None,
+    proxy: Optional[str] = None,
+    sitekey: Optional[str] = None,
+    url: Optional[str] = None,
+    task_type: str = TASK_TURNSTILE,
+    api_url: Optional[str] = None,
+    timeout: float = 180.0,
+) -> str:
+    """Solve the Turnstile challenge on ``driver``'s current page.
+
+    Reads the sitekey from the DOM (unless ``sitekey`` is given), asks Peak
+    for a token, injects it, and returns the token. ``api_key`` defaults to
+    the ``PEAK_API_KEY`` environment variable; ``url`` defaults to the
+    driver's current URL. Pass ``proxy`` to mint the token from the browser's
+    egress IP; omit it and Peak solves without one.
+
+    Raises :class:`~botasaurus_turnstile.peak.PeakError` on failure.
+    """
+    api_key = api_key or os.environ.get("PEAK_API_KEY")
+
+    if sitekey is None:
+        sitekey = read_sitekey(driver)
+    if not sitekey:
+        raise PeakError(
+            "No Turnstile sitekey found on the page. Pass sitekey= "
+            "explicitly if the widget renders in a frame or after load."
+        )
+
+    if url is None:
+        url = _current_url(driver)
+
+    client = PeakClient(
+        api_key, api_url=api_url or DEFAULT_API_URL, proxy=proxy, timeout=timeout
+    )
+    token = client.solve(sitekey, url, proxy=proxy, task_type=task_type)
+    inject_token(driver, token)
+    return token

botasaurus_turnstile-0.1.0/examples/solve_login.py

@@ -0,0 +1,18 @@
+import os
+
+from botasaurus.browser import browser, Driver
+from botasaurus_turnstile import solve_turnstile
+
+# Get a free key at https://peak.fo
+os.environ.setdefault("PEAK_API_KEY", "pk_your_api_key")
+
+
+@browser
+def scrape(driver: Driver, data):
+    driver.get("https://protected.example/login")
+    token = solve_turnstile(driver)
+    print("solved, token length:", len(token))
+
+
+if __name__ == "__main__":
+    scrape()

botasaurus_turnstile-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "botasaurus-turnstile"
+version = "0.1.0"
+description = "Solve Cloudflare Turnstile in Botasaurus via the Peak API — read the sitekey, get a token, inject it. For when the anti-detect driver still stalls on the widget."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+authors = [{ name = "Peak" }]
+keywords = [
+    "botasaurus",
+    "cloudflare",
+    "turnstile",
+    "captcha",
+    "solver",
+    "bypass",
+    "cf-clearance",
+    "scraping",
+    "anti-detect",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Topic :: Internet :: WWW/HTTP :: Browsers",
+    "Topic :: Software Development :: Testing",
+]
+dependencies = []
+
+[project.optional-dependencies]
+botasaurus = ["botasaurus-driver>=4.0"]
+
+[project.urls]
+Homepage = "https://peak.fo/?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=botasaurus-turnstile"
+Documentation = "https://peak.fo/docs/turnstile?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=botasaurus-turnstile"
+Pricing = "https://peak.fo/pricing?utm_source=github&utm_medium=readme&utm_campaign=packages&utm_content=botasaurus-turnstile"
+Source = "https://github.com/CircuitSavage/botasaurus-turnstile"
+
+[tool.hatch.build.targets.wheel]
+packages = ["botasaurus_turnstile"]