flarebreak 0.1.0__tar.gz

flarebreak-0.1.0/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: flarebreak
+Version: 0.1.0
+Summary: Python wrapper for cloudflare-solver — bypass Turnstile & IUAM with ease
+License: MIT
+Project-URL: Homepage, https://github.com/B00H0O/cloudflare-solver
+Keywords: cloudflare,turnstile,captcha,iuam,cf-clearance,scraping,bypass
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Provides-Extra: async
+Requires-Dist: aiohttp>=3.9; extra == "async"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: aiohttp>=3.9; extra == "dev"
+Requires-Dist: responses; extra == "dev"
+Dynamic: requires-python
+
+# flarebreak
+
+Python wrapper for the [cloudflare-solver](https://github.com/B00H0O/cloudflare-solver) Rust service.  
+Supports **sync** (`requests`) and **async** (`aiohttp`) usage out of the box.
+
+---
+
+## Requirements
+
+The Rust service must be running before you use this library:
+
+```bash
+docker build -t turnstile-solver .
+docker run -d -p 407:407 turnstile-solver
+```
+
+---
+
+## Installation
+
+```bash
+# Sync only
+pip install flarebreak
+
+# Sync + Async
+pip install "flarebreak[async]"
+
+# From source
+pip install -e ".[async]"
+```
+
+---
+
+## Quick Start
+
+### Turnstile (sync)
+
+```python
+from flarebreak import CloudflareSolver
+
+with CloudflareSolver() as solver:
+    result = solver.turnstile(
+        url="https://bypass.city",
+        sitekey="0x4AAAAAAAGzw6rXeQWJ_y2P",
+    )
+    print(result.token)    # 1.kMLfH4VM8kCMPXvMy-QcrmU…
+    print(result.elapsed)  # 2.94s
+```
+
+### IUAM / cf_clearance (sync)
+
+```python
+import requests
+from flarebreak import CloudflareSolver
+
+with CloudflareSolver() as solver:
+    result = solver.iuam(url="https://nowsecure.nl")
+
+print(result.cf_clearance)  # 155jEz2BCC8oFRCOu0x8…
+print(result.user_agent)
+print(result.ip)            # egress IP used during solve
+
+# Replay the session — same IP + UA is mandatory
+session = requests.Session()
+session.headers.update(result.headers)   # sets Cookie + User-Agent
+resp = session.get("https://nowsecure.nl")
+```
+
+### Async / parallel
+
+```python
+import asyncio
+from flarebreak import AsyncCloudflareSolver
+
+async def main():
+    async with AsyncCloudflareSolver() as solver:
+        results = await asyncio.gather(
+            solver.turnstile(url="https://a.com", sitekey="0x..."),
+            solver.turnstile(url="https://b.com", sitekey="0x..."),
+            solver.iuam(url="https://c.com"),
+        )
+    for r in results:
+        print(r)
+
+asyncio.run(main())
+```
+
+---
+
+## API Reference
+
+### `CloudflareSolver(host, port, timeout, session)`
+
+| Param | Default | Description |
+|-------|---------|-------------|
+| `host` | `"localhost"` | Solver service host |
+| `port` | `407` | Solver service port |
+| `timeout` | `60` | Seconds before giving up |
+| `session` | `None` | Custom `requests.Session` |
+
+#### `.health() → HealthResult`
+
+```python
+h = solver.health()
+print(h.available, h.capacity)  # 18 / 20
+print(h.healthy)                # True
+```
+
+#### `.turnstile(url, sitekey, *, cdata, action, proxy) → TurnstileResult`
+
+| Param | Required | Description |
+|-------|----------|-------------|
+| `url` | ✅ | Page hosting the widget |
+| `sitekey` | ✅ | `"0x4AAA…"` or `["0x…", "0x…"]` for multiple widgets |
+| `cdata` | ❌ | Turnstile cData field |
+| `action` | ❌ | Turnstile action field |
+| `proxy` | ❌ | `"http://user:pass@host:port"` / `"socks5://…"` |
+
+```python
+result.token    # str or list[str]
+result.elapsed  # "2.94s"
+result.success  # True / False
+```
+
+#### `.iuam(url, *, proxy) → IUAMResult`
+
+```python
+result.cf_clearance  # extracted cookie value
+result.user_agent    # must be replayed verbatim
+result.ip            # egress IP (important for proxy users)
+result.headers       # {"Cookie": "…", "User-Agent": "…"}
+result.elapsed       # "2.87s"
+result.success       # True / False
+```
+
+### `AsyncCloudflareSolver`
+
+Same API as `CloudflareSolver`, but every method is `async`. Use as an async context manager.
+
+---
+
+## Exceptions
+
+| Exception | When |
+|-----------|------|
+| `SolverError` | Base class for all errors |
+| `TimeoutError` | Solver gave up on the challenge |
+| `SolverUnavailableError` | Service is unreachable |
+
+```python
+from flarebreak import SolverError, TimeoutError, SolverUnavailableError
+
+try:
+    result = solver.turnstile(url=..., sitekey=...)
+except TimeoutError:
+    # retry or scale up
+    pass
+except SolverUnavailableError:
+    # docker container not running
+    pass
+except SolverError as e:
+    print(e)
+```
+
+---
+
+## Custom host / scaling
+
+```python
+# Point to a different host or port
+solver = CloudflareSolver(host="192.168.1.10", port=408)
+
+# Or load-balance across scaled containers manually
+import itertools
+ports = itertools.cycle([407, 408, 409, 410])
+solver = CloudflareSolver(port=next(ports))
+```
+
+---
+
+## Running tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/
+```
+
+---
+
+## License
+
+MIT

flarebreak-0.1.0/README.md

@@ -0,0 +1,192 @@
+# flarebreak
+
+Python wrapper for the [cloudflare-solver](https://github.com/B00H0O/cloudflare-solver) Rust service.  
+Supports **sync** (`requests`) and **async** (`aiohttp`) usage out of the box.
+
+---
+
+## Requirements
+
+The Rust service must be running before you use this library:
+
+```bash
+docker build -t turnstile-solver .
+docker run -d -p 407:407 turnstile-solver
+```
+
+---
+
+## Installation
+
+```bash
+# Sync only
+pip install flarebreak
+
+# Sync + Async
+pip install "flarebreak[async]"
+
+# From source
+pip install -e ".[async]"
+```
+
+---
+
+## Quick Start
+
+### Turnstile (sync)
+
+```python
+from flarebreak import CloudflareSolver
+
+with CloudflareSolver() as solver:
+    result = solver.turnstile(
+        url="https://bypass.city",
+        sitekey="0x4AAAAAAAGzw6rXeQWJ_y2P",
+    )
+    print(result.token)    # 1.kMLfH4VM8kCMPXvMy-QcrmU…
+    print(result.elapsed)  # 2.94s
+```
+
+### IUAM / cf_clearance (sync)
+
+```python
+import requests
+from flarebreak import CloudflareSolver
+
+with CloudflareSolver() as solver:
+    result = solver.iuam(url="https://nowsecure.nl")
+
+print(result.cf_clearance)  # 155jEz2BCC8oFRCOu0x8…
+print(result.user_agent)
+print(result.ip)            # egress IP used during solve
+
+# Replay the session — same IP + UA is mandatory
+session = requests.Session()
+session.headers.update(result.headers)   # sets Cookie + User-Agent
+resp = session.get("https://nowsecure.nl")
+```
+
+### Async / parallel
+
+```python
+import asyncio
+from flarebreak import AsyncCloudflareSolver
+
+async def main():
+    async with AsyncCloudflareSolver() as solver:
+        results = await asyncio.gather(
+            solver.turnstile(url="https://a.com", sitekey="0x..."),
+            solver.turnstile(url="https://b.com", sitekey="0x..."),
+            solver.iuam(url="https://c.com"),
+        )
+    for r in results:
+        print(r)
+
+asyncio.run(main())
+```
+
+---
+
+## API Reference
+
+### `CloudflareSolver(host, port, timeout, session)`
+
+| Param | Default | Description |
+|-------|---------|-------------|
+| `host` | `"localhost"` | Solver service host |
+| `port` | `407` | Solver service port |
+| `timeout` | `60` | Seconds before giving up |
+| `session` | `None` | Custom `requests.Session` |
+
+#### `.health() → HealthResult`
+
+```python
+h = solver.health()
+print(h.available, h.capacity)  # 18 / 20
+print(h.healthy)                # True
+```
+
+#### `.turnstile(url, sitekey, *, cdata, action, proxy) → TurnstileResult`
+
+| Param | Required | Description |
+|-------|----------|-------------|
+| `url` | ✅ | Page hosting the widget |
+| `sitekey` | ✅ | `"0x4AAA…"` or `["0x…", "0x…"]` for multiple widgets |
+| `cdata` | ❌ | Turnstile cData field |
+| `action` | ❌ | Turnstile action field |
+| `proxy` | ❌ | `"http://user:pass@host:port"` / `"socks5://…"` |
+
+```python
+result.token    # str or list[str]
+result.elapsed  # "2.94s"
+result.success  # True / False
+```
+
+#### `.iuam(url, *, proxy) → IUAMResult`
+
+```python
+result.cf_clearance  # extracted cookie value
+result.user_agent    # must be replayed verbatim
+result.ip            # egress IP (important for proxy users)
+result.headers       # {"Cookie": "…", "User-Agent": "…"}
+result.elapsed       # "2.87s"
+result.success       # True / False
+```
+
+### `AsyncCloudflareSolver`
+
+Same API as `CloudflareSolver`, but every method is `async`. Use as an async context manager.
+
+---
+
+## Exceptions
+
+| Exception | When |
+|-----------|------|
+| `SolverError` | Base class for all errors |
+| `TimeoutError` | Solver gave up on the challenge |
+| `SolverUnavailableError` | Service is unreachable |
+
+```python
+from flarebreak import SolverError, TimeoutError, SolverUnavailableError
+
+try:
+    result = solver.turnstile(url=..., sitekey=...)
+except TimeoutError:
+    # retry or scale up
+    pass
+except SolverUnavailableError:
+    # docker container not running
+    pass
+except SolverError as e:
+    print(e)
+```
+
+---
+
+## Custom host / scaling
+
+```python
+# Point to a different host or port
+solver = CloudflareSolver(host="192.168.1.10", port=408)
+
+# Or load-balance across scaled containers manually
+import itertools
+ports = itertools.cycle([407, 408, 409, 410])
+solver = CloudflareSolver(port=next(ports))
+```
+
+---
+
+## Running tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/
+```
+
+---
+
+## License
+
+MIT

flarebreak-0.1.0/flarebreak/__init__.py

@@ -0,0 +1,35 @@
+"""
+flarebreak-py
+~~~~~~~~~~~~~~~~~~~~
+Python wrapper for the flarebreak Rust service.
+Supports both sync (requests) and async (aiohttp) usage.
+"""
+
+from .client import CloudflareSolver
+from .models import (
+    TurnstileResult,
+    IUAMResult,
+    HealthResult,
+    SolverError,
+    TimeoutError,
+    SolverUnavailableError,
+)
+
+def __getattr__(name):
+    if name == "AsyncCloudflareSolver":
+        from .async_client import AsyncCloudflareSolver  # noqa: PLC0415
+        return AsyncCloudflareSolver
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__version__ = "0.1.0"
+__all__ = [
+    "CloudflareSolver",
+    "AsyncCloudflareSolver",
+    "TurnstileResult",
+    "IUAMResult",
+    "HealthResult",
+    "SolverError",
+    "TimeoutError",
+    "SolverUnavailableError",
+]

flarebreak-0.1.0/flarebreak/async_client.py

@@ -0,0 +1,225 @@
+"""
+Asynchronous client for the flarebreak service.
+Requires: aiohttp
+"""
+from __future__ import annotations
+
+from typing import Optional, Union, List
+
+try:
+    import aiohttp
+except ImportError as exc:  # pragma: no cover
+    raise ImportError(
+        "aiohttp is required for AsyncCloudflareSolver. "
+        "Install it with: pip install flarebreak-py[async]"
+    ) from exc
+
+from .models import (
+    TurnstileResult,
+    IUAMResult,
+    HealthResult,
+    SolverError,
+    TimeoutError,
+    SolverUnavailableError,
+)
+
+
+class AsyncCloudflareSolver:
+    """
+    Async wrapper around the flarebreak HTTP service (uses aiohttp).
+
+    Parameters
+    ----------
+    host:
+        Hostname / IP of the running solver container. Default ``"localhost"``.
+    port:
+        Port the solver listens on. Default ``407``.
+    timeout:
+        Seconds to wait for a solve to complete. Default ``60``.
+    session:
+        Optional pre-configured ``aiohttp.ClientSession`` to reuse.
+
+    Examples
+    --------
+    ::
+
+        import asyncio
+        from flarebreak import AsyncCloudflareSolver
+
+        async def main():
+            async with AsyncCloudflareSolver() as solver:
+                result = await solver.turnstile(
+                    url="https://example.com",
+                    sitekey="0x4AAAAAAAGzw6rXeQWJ_y2P",
+                )
+                print(result.token)
+
+        asyncio.run(main())
+
+    Parallel solves::
+
+        async def main():
+            async with AsyncCloudflareSolver() as solver:
+                results = await asyncio.gather(
+                    solver.turnstile(url="https://a.com", sitekey="0x..."),
+                    solver.turnstile(url="https://b.com", sitekey="0x..."),
+                )
+    """
+
+    def __init__(
+        self,
+        host: str = "localhost",
+        port: int = 407,
+        timeout: float = 60,
+        session: Optional[aiohttp.ClientSession] = None,
+    ) -> None:
+        self._base = f"http://{host}:{port}"
+        self._timeout = aiohttp.ClientTimeout(total=timeout)
+        self._session = session
+        self._owns_session = session is None
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    async def health(self) -> HealthResult:
+        """Check solver service health and available capacity."""
+        data = await self._get("/health")
+        return HealthResult(
+            status=data.get("status", "unknown"),
+            dyno=data.get("dyno", ""),
+            capacity=data.get("capacity", 0),
+            available=data.get("available", 0),
+            active=data.get("active", 0),
+        )
+
+    async def turnstile(
+        self,
+        url: str,
+        sitekey: Union[str, List[str]],
+        *,
+        cdata: Optional[str] = None,
+        action: Optional[str] = None,
+        proxy: Optional[str] = None,
+    ) -> TurnstileResult:
+        """
+        Solve a Cloudflare Turnstile challenge (async).
+
+        Parameters mirror :meth:`CloudflareSolver.turnstile`.
+        """
+        payload: dict = {"url": url, "sitekey": sitekey}
+        if cdata is not None:
+            payload["cdata"] = cdata
+        if action is not None:
+            payload["action"] = action
+        if proxy is not None:
+            payload["proxy"] = proxy
+
+        data = await self._post("/turnstile", payload)
+        return TurnstileResult(
+            token=data["token"],
+            elapsed=data.get("elapsed", ""),
+            status=data.get("status", ""),
+        )
+
+    async def iuam(
+        self,
+        url: str,
+        *,
+        proxy: Optional[str] = None,
+    ) -> IUAMResult:
+        """
+        Pass a Cloudflare IUAM challenge (async).
+
+        Parameters mirror :meth:`CloudflareSolver.iuam`.
+        """
+        payload: dict = {"url": url}
+        if proxy is not None:
+            payload["proxy"] = proxy
+
+        data = await self._post("/iuam", payload)
+        return IUAMResult(
+            headers=data.get("headers", {}),
+            ip=data.get("ip", ""),
+            elapsed=data.get("elapsed", ""),
+            status=data.get("status", ""),
+        )
+
+    # ------------------------------------------------------------------
+    # Context manager support
+    # ------------------------------------------------------------------
+
+    async def __aenter__(self) -> "AsyncCloudflareSolver":
+        if self._owns_session:
+            self._session = aiohttp.ClientSession(
+                headers={"Content-Type": "application/json"},
+                timeout=self._timeout,
+            )
+        return self
+
+    async def __aexit__(self, *_) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Close the underlying aiohttp session (if owned by this client)."""
+        if self._owns_session and self._session and not self._session.closed:
+            await self._session.close()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _ensure_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession(
+                headers={"Content-Type": "application/json"},
+                timeout=self._timeout,
+            )
+            self._owns_session = True
+        return self._session
+
+    async def _get(self, path: str) -> dict:
+        session = self._ensure_session()
+        try:
+            async with session.get(f"{self._base}{path}") as resp:
+                resp.raise_for_status()
+                return await resp.json()
+        except aiohttp.ClientConnectorError as exc:
+            raise SolverUnavailableError(
+                f"Cannot connect to solver at {self._base}. "
+                "Is the Docker container running?"
+            ) from exc
+        except aiohttp.ServerTimeoutError as exc:
+            raise TimeoutError("Health check timed out.") from exc
+
+    async def _post(self, path: str, payload: dict) -> dict:
+        session = self._ensure_session()
+        try:
+            async with session.post(f"{self._base}{path}", json=payload) as resp:
+                try:
+                    data = await resp.json(content_type=None)
+                except Exception:
+                    text = await resp.text()
+                    raise SolverError(f"Non-JSON response (HTTP {resp.status}): {text[:200]}")
+
+                status = data.get("status", "")
+                if status == "timeout" or resp.status == 408:
+                    raise TimeoutError(
+                        f"Solver timed out on challenge. elapsed={data.get('elapsed')}"
+                    )
+                if resp.status >= 400 or status == "error":
+                    raise SolverError(
+                        f"Solver returned error (HTTP {resp.status}): "
+                        f"{data.get('error') or data}"
+                    )
+                return data
+
+        except aiohttp.ClientConnectorError as exc:
+            raise SolverUnavailableError(
+                f"Cannot connect to solver at {self._base}. "
+                "Is the Docker container running?"
+            ) from exc
+        except aiohttp.ServerTimeoutError as exc:
+            raise TimeoutError(
+                f"No response from solver within the configured timeout."
+            ) from exc

flarebreak-0.1.0/flarebreak/client.py

@@ -0,0 +1,249 @@
+"""
+Synchronous client for the flarebreak service.
+Requires: requests
+"""
+from __future__ import annotations
+
+from typing import Optional, Union, List
+import requests
+
+from .models import (
+    TurnstileResult,
+    IUAMResult,
+    HealthResult,
+    SolverError,
+    TimeoutError,
+    SolverUnavailableError,
+)
+
+
+class CloudflareSolver:
+    """
+    Synchronous wrapper around the flarebreak HTTP service.
+
+    Parameters
+    ----------
+    host:
+        Hostname / IP of the running solver container. Default ``"localhost"``.
+    port:
+        Port the solver listens on. Default ``407``.
+    timeout:
+        Seconds to wait for a solve to complete. Default ``60``.
+        Set higher if you see timeouts under heavy load.
+    session:
+        Optional pre-configured ``requests.Session`` to reuse (useful for
+        proxies, custom TLS, retries, etc.).
+
+    Examples
+    --------
+    Basic Turnstile solve::
+
+        from flarebreak import CloudflareSolver
+
+        solver = CloudflareSolver()
+        result = solver.turnstile(
+            url="https://example.com",
+            sitekey="0x4AAAAAAAGzw6rXeQWJ_y2P",
+        )
+        print(result.token)
+
+    IUAM (cf_clearance) solve::
+
+        result = solver.iuam(url="https://nowsecure.nl")
+        print(result.cf_clearance)
+        print(result.user_agent)
+    """
+
+    def __init__(
+        self,
+        host: str = "localhost",
+        port: int = 407,
+        timeout: float = 60,
+        session: Optional[requests.Session] = None,
+    ) -> None:
+        self._base = f"http://{host}:{port}"
+        self._timeout = timeout
+        self._session = session or requests.Session()
+        self._session.headers.update({"Content-Type": "application/json"})
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def health(self) -> HealthResult:
+        """
+        Check solver service health and available capacity.
+
+        Returns
+        -------
+        HealthResult
+        """
+        data = self._get("/health")
+        return HealthResult(
+            status=data.get("status", "unknown"),
+            dyno=data.get("dyno", ""),
+            capacity=data.get("capacity", 0),
+            available=data.get("available", 0),
+            active=data.get("active", 0),
+        )
+
+    def turnstile(
+        self,
+        url: str,
+        sitekey: Union[str, List[str]],
+        *,
+        cdata: Optional[str] = None,
+        action: Optional[str] = None,
+        proxy: Optional[str] = None,
+    ) -> TurnstileResult:
+        """
+        Solve a Cloudflare Turnstile challenge.
+
+        Parameters
+        ----------
+        url:
+            The page URL that hosts the Turnstile widget.
+        sitekey:
+            Turnstile sitekey (``0x4AAA…``). Pass a list to solve
+            multiple widgets in one request.
+        cdata:
+            Optional Turnstile ``cData`` field.
+        action:
+            Optional Turnstile ``action`` field.
+        proxy:
+            Optional proxy, e.g. ``"http://user:pass@host:port"`` or
+            ``"socks5://host:port"``.
+
+        Returns
+        -------
+        TurnstileResult
+
+        Raises
+        ------
+        TimeoutError
+            If the solver service gives up on the challenge.
+        SolverError
+            For any other solver-side error.
+        SolverUnavailableError
+            If the service cannot be reached.
+        """
+        payload: dict = {"url": url, "sitekey": sitekey}
+        if cdata is not None:
+            payload["cdata"] = cdata
+        if action is not None:
+            payload["action"] = action
+        if proxy is not None:
+            payload["proxy"] = proxy
+
+        data = self._post("/turnstile", payload)
+        return TurnstileResult(
+            token=data["token"],
+            elapsed=data.get("elapsed", ""),
+            status=data.get("status", ""),
+        )
+
+    def iuam(
+        self,
+        url: str,
+        *,
+        proxy: Optional[str] = None,
+    ) -> IUAMResult:
+        """
+        Pass a Cloudflare IUAM ("I'm Under Attack Mode") challenge and
+        return a ready-to-use ``cf_clearance`` cookie + User-Agent pair.
+
+        Parameters
+        ----------
+        url:
+            The protected URL.
+        proxy:
+            Optional proxy (same format as :meth:`turnstile`).
+
+        Returns
+        -------
+        IUAMResult
+
+        Raises
+        ------
+        TimeoutError
+        SolverError
+        SolverUnavailableError
+        """
+        payload: dict = {"url": url}
+        if proxy is not None:
+            payload["proxy"] = proxy
+
+        data = self._post("/iuam", payload)
+        return IUAMResult(
+            headers=data.get("headers", {}),
+            ip=data.get("ip", ""),
+            elapsed=data.get("elapsed", ""),
+            status=data.get("status", ""),
+        )
+
+    # ------------------------------------------------------------------
+    # Context manager support
+    # ------------------------------------------------------------------
+
+    def __enter__(self) -> "CloudflareSolver":
+        return self
+
+    def __exit__(self, *_) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the underlying requests session."""
+        self._session.close()
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _get(self, path: str) -> dict:
+        try:
+            resp = self._session.get(f"{self._base}{path}", timeout=self._timeout)
+            resp.raise_for_status()
+            return resp.json()
+        except requests.exceptions.ConnectionError as exc:
+            raise SolverUnavailableError(
+                f"Cannot connect to solver at {self._base}. "
+                "Is the Docker container running?"
+            ) from exc
+        except requests.exceptions.Timeout as exc:
+            raise TimeoutError("Health check timed out.") from exc
+
+    def _post(self, path: str, payload: dict) -> dict:
+        try:
+            resp = self._session.post(
+                f"{self._base}{path}",
+                json=payload,
+                timeout=self._timeout,
+            )
+        except requests.exceptions.ConnectionError as exc:
+            raise SolverUnavailableError(
+                f"Cannot connect to solver at {self._base}. "
+                "Is the Docker container running?"
+            ) from exc
+        except requests.exceptions.Timeout as exc:
+            raise TimeoutError(
+                f"No response from solver within {self._timeout}s."
+            ) from exc
+
+        # Parse body regardless of status code (solver sends errors as JSON too)
+        try:
+            data = resp.json()
+        except Exception:
+            resp.raise_for_status()
+            raise SolverError(f"Unexpected non-JSON response: {resp.text[:200]}")
+
+        status = data.get("status", "")
+        if status == "timeout" or resp.status_code == 408:
+            raise TimeoutError(
+                f"Solver timed out on challenge. elapsed={data.get('elapsed')}"
+            )
+        if resp.status_code >= 400 or status == "error":
+            raise SolverError(
+                f"Solver returned error (HTTP {resp.status_code}): "
+                f"{data.get('error') or data}"
+            )
+        return data

flarebreak-0.1.0/flarebreak/models.py

@@ -0,0 +1,116 @@
+"""
+Models and exceptions for flarebreak-py.
+"""
+from dataclasses import dataclass, field
+from typing import Optional, Dict, List, Union
+
+
+# ---------------------------------------------------------------------------
+# Exceptions
+# ---------------------------------------------------------------------------
+
+class SolverError(Exception):
+    """Base exception for all solver errors."""
+
+
+class TimeoutError(SolverError):
+    """Raised when the solver service times out on a challenge."""
+
+
+class SolverUnavailableError(SolverError):
+    """Raised when the solver service is unreachable or has no capacity."""
+
+
+# ---------------------------------------------------------------------------
+# Result dataclasses
+# ---------------------------------------------------------------------------
+
+@dataclass
+class TurnstileResult:
+    """Result of a Turnstile solve."""
+
+    token: Union[str, List[str]]
+    """
+    The cf-turnstile-response token(s).
+    A list when multiple sitekeys were submitted.
+    """
+
+    elapsed: str
+    """Human-readable elapsed time, e.g. '2.94s'."""
+
+    status: str
+    """'completed' on success."""
+
+    @property
+    def success(self) -> bool:
+        return self.status == "completed"
+
+    def __repr__(self) -> str:  # noqa: D105
+        tok = self.token if isinstance(self.token, str) else f"[{len(self.token)} tokens]"
+        return f"<TurnstileResult status={self.status!r} elapsed={self.elapsed!r} token={tok[:30]!r}…>"
+
+
+@dataclass
+class IUAMResult:
+    """Result of an IUAM (cf_clearance) solve."""
+
+    headers: Dict[str, str]
+    """
+    Ready-to-use headers dict containing at minimum:
+      - ``Cookie`` – includes ``cf_clearance=…``
+      - ``User-Agent`` – must be replayed verbatim
+    """
+
+    ip: str
+    """The egress IP the solve was performed from (important for proxy users)."""
+
+    elapsed: str
+    """Human-readable elapsed time, e.g. '2.87s'."""
+
+    status: str
+    """'completed' on success."""
+
+    @property
+    def success(self) -> bool:
+        return self.status == "completed"
+
+    @property
+    def cf_clearance(self) -> Optional[str]:
+        """Extract just the cf_clearance value from the Cookie header."""
+        cookie = self.headers.get("Cookie", "")
+        for part in cookie.split(";"):
+            part = part.strip()
+            if part.startswith("cf_clearance="):
+                return part[len("cf_clearance="):]
+        return None
+
+    @property
+    def user_agent(self) -> Optional[str]:
+        return self.headers.get("User-Agent")
+
+    def __repr__(self) -> str:  # noqa: D105
+        return (
+            f"<IUAMResult status={self.status!r} elapsed={self.elapsed!r} "
+            f"ip={self.ip!r} cf_clearance={'…' if self.cf_clearance else None}>"
+        )
+
+
+@dataclass
+class HealthResult:
+    """Result of GET /health."""
+
+    status: str
+    dyno: str
+    capacity: int
+    available: int
+    active: int
+
+    @property
+    def healthy(self) -> bool:
+        return self.status == "ok" and self.available > 0
+
+    def __repr__(self) -> str:  # noqa: D105
+        return (
+            f"<HealthResult status={self.status!r} "
+            f"available={self.available}/{self.capacity}>"
+        )

flarebreak-0.1.0/flarebreak.egg-info/PKG-INFO

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: flarebreak
+Version: 0.1.0
+Summary: Python wrapper for cloudflare-solver — bypass Turnstile & IUAM with ease
+License: MIT
+Project-URL: Homepage, https://github.com/B00H0O/cloudflare-solver
+Keywords: cloudflare,turnstile,captcha,iuam,cf-clearance,scraping,bypass
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.28
+Provides-Extra: async
+Requires-Dist: aiohttp>=3.9; extra == "async"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: aiohttp>=3.9; extra == "dev"
+Requires-Dist: responses; extra == "dev"
+Dynamic: requires-python
+
+# flarebreak
+
+Python wrapper for the [cloudflare-solver](https://github.com/B00H0O/cloudflare-solver) Rust service.  
+Supports **sync** (`requests`) and **async** (`aiohttp`) usage out of the box.
+
+---
+
+## Requirements
+
+The Rust service must be running before you use this library:
+
+```bash
+docker build -t turnstile-solver .
+docker run -d -p 407:407 turnstile-solver
+```
+
+---
+
+## Installation
+
+```bash
+# Sync only
+pip install flarebreak
+
+# Sync + Async
+pip install "flarebreak[async]"
+
+# From source
+pip install -e ".[async]"
+```
+
+---
+
+## Quick Start
+
+### Turnstile (sync)
+
+```python
+from flarebreak import CloudflareSolver
+
+with CloudflareSolver() as solver:
+    result = solver.turnstile(
+        url="https://bypass.city",
+        sitekey="0x4AAAAAAAGzw6rXeQWJ_y2P",
+    )
+    print(result.token)    # 1.kMLfH4VM8kCMPXvMy-QcrmU…
+    print(result.elapsed)  # 2.94s
+```
+
+### IUAM / cf_clearance (sync)
+
+```python
+import requests
+from flarebreak import CloudflareSolver
+
+with CloudflareSolver() as solver:
+    result = solver.iuam(url="https://nowsecure.nl")
+
+print(result.cf_clearance)  # 155jEz2BCC8oFRCOu0x8…
+print(result.user_agent)
+print(result.ip)            # egress IP used during solve
+
+# Replay the session — same IP + UA is mandatory
+session = requests.Session()
+session.headers.update(result.headers)   # sets Cookie + User-Agent
+resp = session.get("https://nowsecure.nl")
+```
+
+### Async / parallel
+
+```python
+import asyncio
+from flarebreak import AsyncCloudflareSolver
+
+async def main():
+    async with AsyncCloudflareSolver() as solver:
+        results = await asyncio.gather(
+            solver.turnstile(url="https://a.com", sitekey="0x..."),
+            solver.turnstile(url="https://b.com", sitekey="0x..."),
+            solver.iuam(url="https://c.com"),
+        )
+    for r in results:
+        print(r)
+
+asyncio.run(main())
+```
+
+---
+
+## API Reference
+
+### `CloudflareSolver(host, port, timeout, session)`
+
+| Param | Default | Description |
+|-------|---------|-------------|
+| `host` | `"localhost"` | Solver service host |
+| `port` | `407` | Solver service port |
+| `timeout` | `60` | Seconds before giving up |
+| `session` | `None` | Custom `requests.Session` |
+
+#### `.health() → HealthResult`
+
+```python
+h = solver.health()
+print(h.available, h.capacity)  # 18 / 20
+print(h.healthy)                # True
+```
+
+#### `.turnstile(url, sitekey, *, cdata, action, proxy) → TurnstileResult`
+
+| Param | Required | Description |
+|-------|----------|-------------|
+| `url` | ✅ | Page hosting the widget |
+| `sitekey` | ✅ | `"0x4AAA…"` or `["0x…", "0x…"]` for multiple widgets |
+| `cdata` | ❌ | Turnstile cData field |
+| `action` | ❌ | Turnstile action field |
+| `proxy` | ❌ | `"http://user:pass@host:port"` / `"socks5://…"` |
+
+```python
+result.token    # str or list[str]
+result.elapsed  # "2.94s"
+result.success  # True / False
+```
+
+#### `.iuam(url, *, proxy) → IUAMResult`
+
+```python
+result.cf_clearance  # extracted cookie value
+result.user_agent    # must be replayed verbatim
+result.ip            # egress IP (important for proxy users)
+result.headers       # {"Cookie": "…", "User-Agent": "…"}
+result.elapsed       # "2.87s"
+result.success       # True / False
+```
+
+### `AsyncCloudflareSolver`
+
+Same API as `CloudflareSolver`, but every method is `async`. Use as an async context manager.
+
+---
+
+## Exceptions
+
+| Exception | When |
+|-----------|------|
+| `SolverError` | Base class for all errors |
+| `TimeoutError` | Solver gave up on the challenge |
+| `SolverUnavailableError` | Service is unreachable |
+
+```python
+from flarebreak import SolverError, TimeoutError, SolverUnavailableError
+
+try:
+    result = solver.turnstile(url=..., sitekey=...)
+except TimeoutError:
+    # retry or scale up
+    pass
+except SolverUnavailableError:
+    # docker container not running
+    pass
+except SolverError as e:
+    print(e)
+```
+
+---
+
+## Custom host / scaling
+
+```python
+# Point to a different host or port
+solver = CloudflareSolver(host="192.168.1.10", port=408)
+
+# Or load-balance across scaled containers manually
+import itertools
+ports = itertools.cycle([407, 408, 409, 410])
+solver = CloudflareSolver(port=next(ports))
+```
+
+---
+
+## Running tests
+
+```bash
+pip install -e ".[dev]"
+pytest tests/
+```
+
+---
+
+## License
+
+MIT

flarebreak-0.1.0/flarebreak.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+setup.py
+flarebreak/__init__.py
+flarebreak/async_client.py
+flarebreak/client.py
+flarebreak/models.py
+flarebreak.egg-info/PKG-INFO
+flarebreak.egg-info/SOURCES.txt
+flarebreak.egg-info/dependency_links.txt
+flarebreak.egg-info/requires.txt
+flarebreak.egg-info/top_level.txt

flarebreak-0.1.0/flarebreak.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

flarebreak-0.1.0/flarebreak.egg-info/requires.txt

@@ -0,0 +1,10 @@
+requests>=2.28
+
+[async]
+aiohttp>=3.9
+
+[dev]
+pytest>=7
+pytest-asyncio
+aiohttp>=3.9
+responses

flarebreak-0.1.0/flarebreak.egg-info/top_level.txt

@@ -0,0 +1 @@
+flarebreak

flarebreak-0.1.0/pyproject.toml

@@ -0,0 +1,33 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.backends.legacy:build"
+
+[project]
+name = "flarebreak"
+version = "0.1.0"
+description = "Python wrapper for cloudflare-solver — bypass Turnstile & IUAM with ease"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+keywords = ["cloudflare", "turnstile", "captcha", "iuam", "cf-clearance", "scraping", "bypass"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Topic :: Internet :: WWW/HTTP",
+]
+
+dependencies = [
+    "requests>=2.28",
+]
+
+[project.optional-dependencies]
+async = ["aiohttp>=3.9"]
+dev = ["pytest>=7", "pytest-asyncio", "aiohttp>=3.9", "responses"]
+
+[project.urls]
+"Homepage" = "https://github.com/B00H0O/cloudflare-solver"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["flarebreak*"]

flarebreak-0.1.0/setup.cfg

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

flarebreak-0.1.0/setup.py

@@ -0,0 +1,26 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="flarebreak",
+    version="0.1.0",
+    description="Python wrapper for cloudflare-solver — bypass Turnstile & IUAM with ease",
+    long_description=open("README.md", encoding="utf-8").read(),
+    long_description_content_type="text/markdown",
+    license="MIT",
+    python_requires=">=3.8",
+    packages=find_packages(include=["flarebreak*"]),
+    install_requires=["requests>=2.28"],
+    extras_require={
+        "async": ["aiohttp>=3.9"],
+    },
+    keywords=["cloudflare", "turnstile", "captcha", "iuam", "cf-clearance", "scraping", "bypass"],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: MIT License",
+        "Operating System :: OS Independent",
+        "Topic :: Internet :: WWW/HTTP",
+    ],
+    project_urls={
+        "Homepage": "https://github.com/B00H0O/cloudflare-solver",
+    },
+)