nslsolver 1.0.0__tar.gz

nslsolver-1.0.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: nslsolver
+Version: 1.0.0
+Summary: Official Python SDK for the NSLSolver captcha solving API
+Author-email: NSLSolver <support@nslsolver.com>
+License: MIT
+Project-URL: Homepage, https://nslsolver.com
+Project-URL: Documentation, https://docs.nslsolver.com
+Project-URL: Repository, https://github.com/NSLSolver/NSLSolver-SDK-Python
+Project-URL: Issues, https://github.com/NSLSolver/NSLSolver-SDK-Python/issues
+Keywords: captcha,turnstile,cloudflare,solver,nslsolver
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Provides-Extra: async
+Requires-Dist: aiohttp>=3.8.0; extra == "async"
+Provides-Extra: dev
+Requires-Dist: aiohttp>=3.8.0; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+# NSLSolver Python SDK
+
+Python SDK for the [NSLSolver](https://nslsolver.com) captcha solving API.
+
+## Installation
+
+```bash
+pip install nslsolver
+
+# async support
+pip install nslsolver[async]
+```
+
+## Quick Start
+
+```python
+from nslsolver import NSLSolver
+
+solver = NSLSolver("your-api-key")
+
+# Turnstile
+result = solver.solve_turnstile(
+    site_key="0x4AAAAAAAB...",
+    url="https://example.com",
+)
+print(result.token)
+
+# Cloudflare challenge (proxy required)
+result = solver.solve_challenge(
+    url="https://example.com/protected",
+    proxy="http://user:pass@host:port",
+)
+print(result.cookies, result.user_agent)
+
+# Balance
+balance = solver.get_balance()
+print(balance.balance, balance.max_threads, balance.allowed_types)
+```
+
+## Async
+
+```python
+import asyncio
+from nslsolver import AsyncNSLSolver
+
+async def main():
+    async with AsyncNSLSolver("your-api-key") as solver:
+        result = await solver.solve_turnstile(
+            site_key="0x4AAAAAAAB...",
+            url="https://example.com",
+        )
+        print(result.token)
+
+asyncio.run(main())
+```
+
+## Error Handling
+
+```python
+from nslsolver import (
+    NSLSolver,
+    AuthenticationError,
+    InsufficientBalanceError,
+    RateLimitError,
+    SolveError,
+    NSLSolverError,
+)
+
+solver = NSLSolver("your-api-key")
+
+try:
+    result = solver.solve_turnstile(
+        site_key="0x4AAAAAAAB...",
+        url="https://example.com",
+    )
+except AuthenticationError:
+    print("Bad API key.")
+except InsufficientBalanceError:
+    print("Top up your balance.")
+except RateLimitError:
+    print("Rate limited after all retries.")
+except SolveError as e:
+    print(f"Solve failed: {e.message}")
+except NSLSolverError as e:
+    print(f"API error (HTTP {e.status_code}): {e.message}")
+```
+
+Rate-limit (429) and backend (503) errors are retried automatically with exponential backoff before raising.
+
+## Configuration
+
+```python
+solver = NSLSolver(
+    api_key="your-api-key",
+    base_url="https://api.nslsolver.com",  # default
+    timeout=120,       # seconds (default: 120)
+    max_retries=3,     # retries for 429/503 (default: 3)
+)
+```
+
+Both clients support context managers (`with` / `async with`) for session cleanup.
+
+## Requirements
+
+- Python 3.8+
+- `requests` (sync client)
+- `aiohttp` (async client, optional)
+
+## License
+
+MIT

nslsolver-1.0.0/README.md

@@ -0,0 +1,111 @@
+# NSLSolver Python SDK
+
+Python SDK for the [NSLSolver](https://nslsolver.com) captcha solving API.
+
+## Installation
+
+```bash
+pip install nslsolver
+
+# async support
+pip install nslsolver[async]
+```
+
+## Quick Start
+
+```python
+from nslsolver import NSLSolver
+
+solver = NSLSolver("your-api-key")
+
+# Turnstile
+result = solver.solve_turnstile(
+    site_key="0x4AAAAAAAB...",
+    url="https://example.com",
+)
+print(result.token)
+
+# Cloudflare challenge (proxy required)
+result = solver.solve_challenge(
+    url="https://example.com/protected",
+    proxy="http://user:pass@host:port",
+)
+print(result.cookies, result.user_agent)
+
+# Balance
+balance = solver.get_balance()
+print(balance.balance, balance.max_threads, balance.allowed_types)
+```
+
+## Async
+
+```python
+import asyncio
+from nslsolver import AsyncNSLSolver
+
+async def main():
+    async with AsyncNSLSolver("your-api-key") as solver:
+        result = await solver.solve_turnstile(
+            site_key="0x4AAAAAAAB...",
+            url="https://example.com",
+        )
+        print(result.token)
+
+asyncio.run(main())
+```
+
+## Error Handling
+
+```python
+from nslsolver import (
+    NSLSolver,
+    AuthenticationError,
+    InsufficientBalanceError,
+    RateLimitError,
+    SolveError,
+    NSLSolverError,
+)
+
+solver = NSLSolver("your-api-key")
+
+try:
+    result = solver.solve_turnstile(
+        site_key="0x4AAAAAAAB...",
+        url="https://example.com",
+    )
+except AuthenticationError:
+    print("Bad API key.")
+except InsufficientBalanceError:
+    print("Top up your balance.")
+except RateLimitError:
+    print("Rate limited after all retries.")
+except SolveError as e:
+    print(f"Solve failed: {e.message}")
+except NSLSolverError as e:
+    print(f"API error (HTTP {e.status_code}): {e.message}")
+```
+
+Rate-limit (429) and backend (503) errors are retried automatically with exponential backoff before raising.
+
+## Configuration
+
+```python
+solver = NSLSolver(
+    api_key="your-api-key",
+    base_url="https://api.nslsolver.com",  # default
+    timeout=120,       # seconds (default: 120)
+    max_retries=3,     # retries for 429/503 (default: 3)
+)
+```
+
+Both clients support context managers (`with` / `async with`) for session cleanup.
+
+## Requirements
+
+- Python 3.8+
+- `requests` (sync client)
+- `aiohttp` (async client, optional)
+
+## License
+
+MIT

nslsolver-1.0.0/nslsolver/__init__.py

@@ -0,0 +1,40 @@
+"""NSLSolver Python SDK."""
+
+__version__ = "1.0.0"
+
+from .client import NSLSolver
+from .exceptions import (
+    AuthenticationError,
+    BackendError,
+    InsufficientBalanceError,
+    NSLSolverError,
+    RateLimitError,
+    SolveError,
+    TypeNotAllowedError,
+)
+from .types import BalanceResult, ChallengeResult, TurnstileResult
+
+
+def __getattr__(name: str) -> object:
+    if name == "AsyncNSLSolver":
+        from .async_client import AsyncNSLSolver
+
+        return AsyncNSLSolver
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+__all__ = [
+    "__version__",
+    "NSLSolver",
+    "AsyncNSLSolver",
+    "TurnstileResult",
+    "ChallengeResult",
+    "BalanceResult",
+    "NSLSolverError",
+    "AuthenticationError",
+    "InsufficientBalanceError",
+    "TypeNotAllowedError",
+    "RateLimitError",
+    "BackendError",
+    "SolveError",
+]

nslsolver-1.0.0/nslsolver/async_client.py

@@ -0,0 +1,235 @@
+"""Async NSLSolver client (requires aiohttp)."""
+
+import asyncio
+import logging
+from typing import Any, Dict, Optional
+
+try:
+    import aiohttp
+except ImportError:
+    raise ImportError(
+        "The 'aiohttp' package is required for the async client. "
+        "Install it with: pip install nslsolver[async]"
+    )
+
+from .exceptions import (
+    AuthenticationError,
+    BackendError,
+    InsufficientBalanceError,
+    NSLSolverError,
+    RateLimitError,
+    SolveError,
+    TypeNotAllowedError,
+)
+from .types import BalanceResult, ChallengeResult, TurnstileResult
+
+logger = logging.getLogger("nslsolver")
+
+_DEFAULT_BASE_URL = "https://api.nslsolver.com"
+_DEFAULT_TIMEOUT = 120
+_DEFAULT_MAX_RETRIES = 3
+_INITIAL_BACKOFF = 1.0
+_BACKOFF_MULTIPLIER = 2.0
+_MAX_BACKOFF = 30.0
+
+_RETRYABLE_EXCEPTIONS = (RateLimitError, BackendError)
+
+
+class AsyncNSLSolver:
+    """Async client for the NSLSolver API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: int = _DEFAULT_TIMEOUT,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key must be a non-empty string.")
+
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = aiohttp.ClientTimeout(total=timeout)
+        self._max_retries = max_retries
+        self._session: Optional[aiohttp.ClientSession] = None
+        self._headers = {
+            "X-API-Key": self._api_key,
+            "Content-Type": "application/json",
+            "User-Agent": "nslsolver-python/1.0.0 (async)",
+        }
+
+    async def _get_session(self) -> aiohttp.ClientSession:
+        if self._session is None or self._session.closed:
+            self._session = aiohttp.ClientSession(
+                headers=self._headers,
+                timeout=self._timeout,
+            )
+        return self._session
+
+    # -- Public API ----------------------------------------------------------
+
+    async def solve_turnstile(
+        self,
+        site_key: str,
+        url: str,
+        action: Optional[str] = None,
+        cdata: Optional[str] = None,
+        proxy: Optional[str] = None,
+        user_agent: Optional[str] = None,
+    ) -> TurnstileResult:
+        """Solve a Cloudflare Turnstile captcha."""
+        payload: Dict[str, Any] = {
+            "type": "turnstile",
+            "site_key": site_key,
+            "url": url,
+        }
+        if action is not None:
+            payload["action"] = action
+        if cdata is not None:
+            payload["cdata"] = cdata
+        if proxy is not None:
+            payload["proxy"] = proxy
+        if user_agent is not None:
+            payload["user_agent"] = user_agent
+
+        data = await self._request("POST", "/solve", json_body=payload)
+
+        return TurnstileResult(
+            token=data["token"],
+            type=data.get("type", "turnstile"),
+        )
+
+    async def solve_challenge(
+        self,
+        url: str,
+        proxy: str,
+        user_agent: Optional[str] = None,
+    ) -> ChallengeResult:
+        """Solve a Cloudflare challenge page."""
+        payload: Dict[str, Any] = {
+            "type": "challenge",
+            "url": url,
+            "proxy": proxy,
+        }
+        if user_agent is not None:
+            payload["user_agent"] = user_agent
+
+        data = await self._request("POST", "/solve", json_body=payload)
+
+        return ChallengeResult(
+            cookies=data.get("cookies", {}),
+            user_agent=data.get("user_agent", ""),
+            type=data.get("type", "challenge"),
+        )
+
+    async def get_balance(self) -> BalanceResult:
+        """Retrieve current account balance."""
+        data = await self._request("GET", "/balance")
+
+        known_keys = {"balance", "max_threads", "allowed_types"}
+        extra = {k: v for k, v in data.items() if k not in known_keys}
+
+        return BalanceResult(
+            balance=float(data["balance"]),
+            max_threads=int(data["max_threads"]),
+            allowed_types=list(data.get("allowed_types", [])),
+            extra=extra,
+        )
+
+    # -- Internal ------------------------------------------------------------
+
+    async def _request(
+        self,
+        method: str,
+        path: str,
+        json_body: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Execute an HTTP request with retries on transient errors."""
+        url = f"{self._base_url}{path}"
+        last_exc: Optional[Exception] = None
+        backoff = _INITIAL_BACKOFF
+        session = await self._get_session()
+
+        for attempt in range(self._max_retries + 1):
+            try:
+                async with session.request(
+                    method=method,
+                    url=url,
+                    json=json_body,
+                ) as response:
+                    if response.status == 200:
+                        return await response.json()  # type: ignore[no-any-return]
+
+                    response_text = await response.text()
+                    self._handle_error_response(response.status, response_text)
+
+            except _RETRYABLE_EXCEPTIONS as exc:
+                last_exc = exc
+            except asyncio.TimeoutError:
+                last_exc = NSLSolverError("Request timed out.")
+            except aiohttp.ClientConnectionError:
+                last_exc = NSLSolverError("Connection error.")
+            else:
+                break  # pragma: no cover
+
+            if attempt < self._max_retries:
+                sleep_time = min(backoff, _MAX_BACKOFF)
+                logger.warning(
+                    "%s on attempt %d/%d, retrying in %.1fs",
+                    last_exc,
+                    attempt + 1,
+                    self._max_retries + 1,
+                    sleep_time,
+                )
+                await asyncio.sleep(sleep_time)
+                backoff *= _BACKOFF_MULTIPLIER
+            else:
+                raise last_exc  # type: ignore[misc]
+
+        if last_exc is not None:
+            raise last_exc
+        raise NSLSolverError("Unexpected error: no response received.")
+
+    @staticmethod
+    def _handle_error_response(status: int, response_text: str) -> None:
+        """Map an HTTP error response to the appropriate exception."""
+        import json
+
+        try:
+            body = json.loads(response_text)
+        except (ValueError, KeyError):
+            body = {}
+
+        message = body.get("error", body.get("message", response_text))
+
+        exc_map = {
+            400: SolveError,
+            401: AuthenticationError,
+            402: InsufficientBalanceError,
+            403: TypeNotAllowedError,
+            429: RateLimitError,
+            503: BackendError,
+        }
+        cls = exc_map.get(status)
+        if cls:
+            raise cls(message=str(message), status_code=status, response_body=body)
+        raise NSLSolverError(
+            message=f"Unexpected API error (HTTP {status}): {message}",
+            status_code=status,
+            response_body=body,
+        )
+
+    async def close(self) -> None:
+        """Close the underlying aiohttp session."""
+        if self._session and not self._session.closed:
+            await self._session.close()
+
+    async def __aenter__(self) -> "AsyncNSLSolver":
+        return self
+
+    async def __aexit__(self, *args: Any) -> None:
+        await self.close()
+
+    def __repr__(self) -> str:
+        return f"AsyncNSLSolver(base_url={self._base_url!r})"

nslsolver-1.0.0/nslsolver/client.py

@@ -0,0 +1,227 @@
+"""Synchronous NSLSolver client."""
+
+import time
+import logging
+from typing import Any, Dict, Optional
+
+import requests
+
+from .exceptions import (
+    AuthenticationError,
+    BackendError,
+    InsufficientBalanceError,
+    NSLSolverError,
+    RateLimitError,
+    SolveError,
+    TypeNotAllowedError,
+)
+from .types import BalanceResult, ChallengeResult, TurnstileResult
+
+logger = logging.getLogger("nslsolver")
+
+_DEFAULT_BASE_URL = "https://api.nslsolver.com"
+_DEFAULT_TIMEOUT = 120
+_DEFAULT_MAX_RETRIES = 3
+_INITIAL_BACKOFF = 1.0
+_BACKOFF_MULTIPLIER = 2.0
+_MAX_BACKOFF = 30.0
+
+# Errors worth retrying
+_RETRYABLE_EXCEPTIONS = (RateLimitError, BackendError)
+
+
+class NSLSolver:
+    """Synchronous client for the NSLSolver API."""
+
+    def __init__(
+        self,
+        api_key: str,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: int = _DEFAULT_TIMEOUT,
+        max_retries: int = _DEFAULT_MAX_RETRIES,
+    ) -> None:
+        if not api_key:
+            raise ValueError("api_key must be a non-empty string.")
+
+        self._api_key = api_key
+        self._base_url = base_url.rstrip("/")
+        self._timeout = timeout
+        self._max_retries = max_retries
+        self._session = requests.Session()
+        self._session.headers.update(
+            {
+                "X-API-Key": self._api_key,
+                "Content-Type": "application/json",
+                "User-Agent": "nslsolver-python/1.0.0",
+            }
+        )
+
+    # -- Public API ----------------------------------------------------------
+
+    def solve_turnstile(
+        self,
+        site_key: str,
+        url: str,
+        action: Optional[str] = None,
+        cdata: Optional[str] = None,
+        proxy: Optional[str] = None,
+        user_agent: Optional[str] = None,
+    ) -> TurnstileResult:
+        """Solve a Cloudflare Turnstile captcha."""
+        payload: Dict[str, Any] = {
+            "type": "turnstile",
+            "site_key": site_key,
+            "url": url,
+        }
+        if action is not None:
+            payload["action"] = action
+        if cdata is not None:
+            payload["cdata"] = cdata
+        if proxy is not None:
+            payload["proxy"] = proxy
+        if user_agent is not None:
+            payload["user_agent"] = user_agent
+
+        data = self._request("POST", "/solve", json_body=payload)
+
+        return TurnstileResult(
+            token=data["token"],
+            type=data.get("type", "turnstile"),
+        )
+
+    def solve_challenge(
+        self,
+        url: str,
+        proxy: str,
+        user_agent: Optional[str] = None,
+    ) -> ChallengeResult:
+        """Solve a Cloudflare challenge page."""
+        payload: Dict[str, Any] = {
+            "type": "challenge",
+            "url": url,
+            "proxy": proxy,
+        }
+        if user_agent is not None:
+            payload["user_agent"] = user_agent
+
+        data = self._request("POST", "/solve", json_body=payload)
+
+        return ChallengeResult(
+            cookies=data.get("cookies", {}),
+            user_agent=data.get("user_agent", ""),
+            type=data.get("type", "challenge"),
+        )
+
+    def get_balance(self) -> BalanceResult:
+        """Retrieve current account balance."""
+        data = self._request("GET", "/balance")
+
+        known_keys = {"balance", "max_threads", "allowed_types"}
+        extra = {k: v for k, v in data.items() if k not in known_keys}
+
+        return BalanceResult(
+            balance=float(data["balance"]),
+            max_threads=int(data["max_threads"]),
+            allowed_types=list(data.get("allowed_types", [])),
+            extra=extra,
+        )
+
+    # -- Internal ------------------------------------------------------------
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        json_body: Optional[Dict[str, Any]] = None,
+    ) -> Dict[str, Any]:
+        """Execute an HTTP request with retries on transient errors."""
+        url = f"{self._base_url}{path}"
+        last_exc: Optional[Exception] = None
+        backoff = _INITIAL_BACKOFF
+
+        for attempt in range(self._max_retries + 1):
+            try:
+                response = self._session.request(
+                    method=method,
+                    url=url,
+                    json=json_body,
+                    timeout=self._timeout,
+                )
+
+                if response.status_code == 200:
+                    return response.json()  # type: ignore[no-any-return]
+
+                self._handle_error_response(response)
+
+            except _RETRYABLE_EXCEPTIONS as exc:
+                last_exc = exc
+            except requests.exceptions.Timeout:
+                last_exc = NSLSolverError(f"Request timed out after {self._timeout}s.")
+            except requests.exceptions.ConnectionError:
+                last_exc = NSLSolverError("Connection error.")
+            else:
+                # _handle_error_response always raises, so we only land here
+                # on a 200, which already returned above.
+                break  # pragma: no cover
+
+            # Retry or give up
+            if attempt < self._max_retries:
+                sleep_time = min(backoff, _MAX_BACKOFF)
+                logger.warning(
+                    "%s on attempt %d/%d, retrying in %.1fs",
+                    last_exc,
+                    attempt + 1,
+                    self._max_retries + 1,
+                    sleep_time,
+                )
+                time.sleep(sleep_time)
+                backoff *= _BACKOFF_MULTIPLIER
+            else:
+                raise last_exc  # type: ignore[misc]
+
+        # Should not be reached, but keeps the type checker happy.
+        if last_exc is not None:
+            raise last_exc
+        raise NSLSolverError("Unexpected error: no response received.")
+
+    @staticmethod
+    def _handle_error_response(response: requests.Response) -> None:
+        """Map an HTTP error response to the appropriate exception."""
+        status = response.status_code
+
+        try:
+            body = response.json()
+        except (ValueError, KeyError):
+            body = {}
+
+        message = body.get("error", body.get("message", response.text))
+
+        exc_map = {
+            400: SolveError,
+            401: AuthenticationError,
+            402: InsufficientBalanceError,
+            403: TypeNotAllowedError,
+            429: RateLimitError,
+            503: BackendError,
+        }
+        cls = exc_map.get(status)
+        if cls:
+            raise cls(message=str(message), status_code=status, response_body=body)
+        raise NSLSolverError(
+            message=f"Unexpected API error (HTTP {status}): {message}",
+            status_code=status,
+            response_body=body,
+        )
+
+    def close(self) -> None:
+        """Close the underlying HTTP session."""
+        self._session.close()
+
+    def __enter__(self) -> "NSLSolver":
+        return self
+
+    def __exit__(self, *args: Any) -> None:
+        self.close()
+
+    def __repr__(self) -> str:
+        return f"NSLSolver(base_url={self._base_url!r})"

nslsolver-1.0.0/nslsolver/exceptions.py

@@ -0,0 +1,49 @@
+"""NSLSolver SDK exceptions."""
+
+from typing import Optional
+
+
+class NSLSolverError(Exception):
+    """Base exception for all NSLSolver API errors."""
+
+    def __init__(
+        self,
+        message: str,
+        status_code: Optional[int] = None,
+        response_body: Optional[dict] = None,
+    ) -> None:
+        self.message = message
+        self.status_code = status_code
+        self.response_body = response_body
+        super().__init__(message)
+
+    def __repr__(self) -> str:
+        return (
+            f"{self.__class__.__name__}("
+            f"message={self.message!r}, "
+            f"status_code={self.status_code!r})"
+        )
+
+
+class AuthenticationError(NSLSolverError):
+    """Invalid or missing API key (401)."""
+
+
+class InsufficientBalanceError(NSLSolverError):
+    """Account balance too low (402)."""
+
+
+class TypeNotAllowedError(NSLSolverError):
+    """Solve type not allowed for this key (403)."""
+
+
+class RateLimitError(NSLSolverError):
+    """Rate limit exceeded (429). Retried automatically."""
+
+
+class BackendError(NSLSolverError):
+    """Backend unavailable (503). Retried automatically."""
+
+
+class SolveError(NSLSolverError):
+    """Solve request failed (400)."""

nslsolver-1.0.0/nslsolver/types.py

@@ -0,0 +1,45 @@
+"""Response types for the NSLSolver API."""
+
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+
+@dataclass(frozen=True)
+class TurnstileResult:
+    """Result of a Turnstile captcha solve."""
+
+    token: str
+    type: str = "turnstile"
+
+    def __str__(self) -> str:
+        return self.token
+
+
+@dataclass(frozen=True)
+class ChallengeResult:
+    """Result of a Cloudflare challenge solve."""
+
+    cookies: Dict[str, str]
+    user_agent: str
+    type: str = "challenge"
+
+    @property
+    def cf_clearance(self) -> Optional[str]:
+        return self.cookies.get("cf_clearance")
+
+
+@dataclass(frozen=True)
+class BalanceResult:
+    """Account balance and capability info."""
+
+    balance: float
+    max_threads: int
+    allowed_types: List[str]
+    extra: Dict[str, object] = field(default_factory=dict)
+
+    def __str__(self) -> str:
+        return (
+            f"Balance: {self.balance}, "
+            f"Max Threads: {self.max_threads}, "
+            f"Allowed Types: {self.allowed_types}"
+        )

nslsolver-1.0.0/nslsolver.egg-info/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: nslsolver
+Version: 1.0.0
+Summary: Official Python SDK for the NSLSolver captcha solving API
+Author-email: NSLSolver <support@nslsolver.com>
+License: MIT
+Project-URL: Homepage, https://nslsolver.com
+Project-URL: Documentation, https://docs.nslsolver.com
+Project-URL: Repository, https://github.com/NSLSolver/NSLSolver-SDK-Python
+Project-URL: Issues, https://github.com/NSLSolver/NSLSolver-SDK-Python/issues
+Keywords: captcha,turnstile,cloudflare,solver,nslsolver
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+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: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: requests>=2.25.0
+Provides-Extra: async
+Requires-Dist: aiohttp>=3.8.0; extra == "async"
+Provides-Extra: dev
+Requires-Dist: aiohttp>=3.8.0; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
+Requires-Dist: mypy>=1.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+
+# NSLSolver Python SDK
+
+Python SDK for the [NSLSolver](https://nslsolver.com) captcha solving API.
+
+## Installation
+
+```bash
+pip install nslsolver
+
+# async support
+pip install nslsolver[async]
+```
+
+## Quick Start
+
+```python
+from nslsolver import NSLSolver
+
+solver = NSLSolver("your-api-key")
+
+# Turnstile
+result = solver.solve_turnstile(
+    site_key="0x4AAAAAAAB...",
+    url="https://example.com",
+)
+print(result.token)
+
+# Cloudflare challenge (proxy required)
+result = solver.solve_challenge(
+    url="https://example.com/protected",
+    proxy="http://user:pass@host:port",
+)
+print(result.cookies, result.user_agent)
+
+# Balance
+balance = solver.get_balance()
+print(balance.balance, balance.max_threads, balance.allowed_types)
+```
+
+## Async
+
+```python
+import asyncio
+from nslsolver import AsyncNSLSolver
+
+async def main():
+    async with AsyncNSLSolver("your-api-key") as solver:
+        result = await solver.solve_turnstile(
+            site_key="0x4AAAAAAAB...",
+            url="https://example.com",
+        )
+        print(result.token)
+
+asyncio.run(main())
+```
+
+## Error Handling
+
+```python
+from nslsolver import (
+    NSLSolver,
+    AuthenticationError,
+    InsufficientBalanceError,
+    RateLimitError,
+    SolveError,
+    NSLSolverError,
+)
+
+solver = NSLSolver("your-api-key")
+
+try:
+    result = solver.solve_turnstile(
+        site_key="0x4AAAAAAAB...",
+        url="https://example.com",
+    )
+except AuthenticationError:
+    print("Bad API key.")
+except InsufficientBalanceError:
+    print("Top up your balance.")
+except RateLimitError:
+    print("Rate limited after all retries.")
+except SolveError as e:
+    print(f"Solve failed: {e.message}")
+except NSLSolverError as e:
+    print(f"API error (HTTP {e.status_code}): {e.message}")
+```
+
+Rate-limit (429) and backend (503) errors are retried automatically with exponential backoff before raising.
+
+## Configuration
+
+```python
+solver = NSLSolver(
+    api_key="your-api-key",
+    base_url="https://api.nslsolver.com",  # default
+    timeout=120,       # seconds (default: 120)
+    max_retries=3,     # retries for 429/503 (default: 3)
+)
+```
+
+Both clients support context managers (`with` / `async with`) for session cleanup.
+
+## Requirements
+
+- Python 3.8+
+- `requests` (sync client)
+- `aiohttp` (async client, optional)
+
+## License
+
+MIT

nslsolver-1.0.0/nslsolver.egg-info/SOURCES.txt

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

nslsolver-1.0.0/nslsolver.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

nslsolver-1.0.0/nslsolver.egg-info/requires.txt

@@ -0,0 +1,11 @@
+requests>=2.25.0
+
+[async]
+aiohttp>=3.8.0
+
+[dev]
+aiohttp>=3.8.0
+pytest>=7.0
+pytest-asyncio>=0.21
+mypy>=1.0
+ruff>=0.1.0

nslsolver-1.0.0/nslsolver.egg-info/top_level.txt

@@ -0,0 +1 @@
+nslsolver

nslsolver-1.0.0/pyproject.toml

@@ -0,0 +1,64 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "nslsolver"
+version = "1.0.0"
+description = "Official Python SDK for the NSLSolver captcha solving API"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.8"
+authors = [
+    {name = "NSLSolver", email = "support@nslsolver.com"},
+]
+keywords = ["captcha", "turnstile", "cloudflare", "solver", "nslsolver"]
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Internet :: WWW/HTTP",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = [
+    "requests>=2.25.0",
+]
+
+[project.optional-dependencies]
+async = ["aiohttp>=3.8.0"]
+dev = [
+    "aiohttp>=3.8.0",
+    "pytest>=7.0",
+    "pytest-asyncio>=0.21",
+    "mypy>=1.0",
+    "ruff>=0.1.0",
+]
+
+[project.urls]
+Homepage = "https://nslsolver.com"
+Documentation = "https://docs.nslsolver.com"
+Repository = "https://github.com/NSLSolver/NSLSolver-SDK-Python"
+Issues = "https://github.com/NSLSolver/NSLSolver-SDK-Python/issues"
+
+[tool.setuptools.packages.find]
+include = ["nslsolver*"]
+
+[tool.mypy]
+strict = true
+python_version = "3.8"
+
+[tool.ruff]
+target-version = "py38"
+line-length = 100
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]

nslsolver-1.0.0/setup.cfg

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