capsolver-core 0.1.0__py3-none-any.whl

capsolver_core/core/client.py

@@ -0,0 +1,163 @@
+"""CapsolverClient — the pure-Python token-solving core.
+
+Mirrors the Node SDK's core/client.ts. Responsible only for
+``/createTask``, ``/getTaskResult`` polling and ``/getBalance``.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from dataclasses import dataclass, field
+from typing import Any, Callable, NoReturn
+
+from capsolver_core.core.errors import CapsolverError, CapsolverTimeoutError, RateLimitError
+from capsolver_core.core.http import FetchHttp
+from capsolver_core.core.types import BalanceResp
+
+
+@dataclass
+class WaitOptions:
+    """Per-call overrides for polling behaviour."""
+
+    timeout: float | None = None
+    polling_interval: float | None = None
+    cancel_event: asyncio.Event | None = None
+
+
+@dataclass
+class CapsolverClientOptions:
+    api_key: str = ""
+    service: str = "https://api.capsolver.com"
+    default_timeout: float = 120.0
+    polling_interval: float = 5.0
+    request_timeout_ms: int = 30_000
+    app_id: str | None = None
+    source: str | None = None
+    version: str | None = None
+    on_error: Callable[[CapsolverError], None] | None = field(default=None, repr=False)
+
+
+class CapsolverClient:
+    """Token-solving client — create tasks, poll for results, check balance."""
+
+    def __init__(self, options: CapsolverClientOptions | None = None, **kwargs: Any) -> None:
+        opts = options or CapsolverClientOptions(**kwargs)
+        if not opts.api_key:
+            raise CapsolverError("CapsolverClient: apiKey is required")
+        self._options = opts
+        self._http = FetchHttp(opts.service)
+
+    # ── public API ────────────────────────────────────────────────
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP client and release connections."""
+        await self._http.aclose()
+
+    async def get_balance(self) -> BalanceResp:
+        res = await self._http.post(
+            "/getBalance",
+            {"clientKey": self._options.api_key},
+            timeout_ms=self._options.request_timeout_ms,
+        )
+        data = self._unwrap(res.status, res.data, "getBalance failed")
+        return BalanceResp.from_dict(data)
+
+    async def create_task(self, task: dict[str, Any], **extra: Any) -> dict[str, Any]:
+        body: dict[str, Any] = {
+            "clientKey": self._options.api_key,
+            "task": task,
+        }
+        if extra.get("app_id") or self._options.app_id:
+            body["appId"] = extra.get("app_id") or self._options.app_id
+        if extra.get("source") or self._options.source:
+            body["source"] = extra.get("source") or self._options.source
+        if extra.get("version") or self._options.version:
+            body["version"] = extra.get("version") or self._options.version
+
+        res = await self._http.post(
+            "/createTask",
+            body,
+            timeout_ms=self._options.request_timeout_ms,
+        )
+        data = self._unwrap(res.status, res.data, "createTask failed")
+        if not data.get("taskId"):
+            self._fail(CapsolverError("createTask returned an empty taskId"))
+        return data
+
+    async def get_task_solution(self, task_id: str) -> dict[str, Any]:
+        res = await self._http.post(
+            "/getTaskResult",
+            {"clientKey": self._options.api_key, "taskId": task_id},
+            timeout_ms=self._options.request_timeout_ms,
+        )
+        return self._unwrap(res.status, res.data, "getTaskResult failed")
+
+    async def create_task_result(
+        self,
+        task: dict[str, Any],
+        wait_options: WaitOptions | None = None,
+    ) -> dict[str, Any]:
+        """Create a task and poll until ``ready``, throwing on ``failed`` or timeout."""
+        timeout = (
+            wait_options.timeout if wait_options and wait_options.timeout is not None else self._options.default_timeout
+        )
+        interval = (
+            wait_options.polling_interval
+            if wait_options and wait_options.polling_interval is not None
+            else self._options.polling_interval
+        )
+        cancel = wait_options.cancel_event if wait_options else None
+
+        result = await self.create_task(task)
+        task_id = result.get("taskId", "")
+        started_at = time.monotonic()
+
+        # Poll immediately before the first sleep — the task may already be ready
+        # (e.g. simple captcha types or cached solutions).
+        while True:
+            if cancel and cancel.is_set():
+                self._fail(CapsolverError("Polling aborted", error_code="ABORTED"))
+
+            if time.monotonic() - started_at > timeout:
+                self._fail(CapsolverTimeoutError(timeout, task_id))
+
+            state = await self.get_task_solution(task_id)
+            status = state.get("status")
+
+            if status == "ready":
+                return state
+            if status == "failed":
+                self._fail(
+                    CapsolverError(
+                        state.get("errorDescription") or "Task failed",
+                        error_id=state.get("errorId"),
+                        error_code=state.get("errorCode"),
+                        error_description=state.get("errorDescription"),
+                    )
+                )
+
+            await asyncio.sleep(interval)
+
+    # ── internals ─────────────────────────────────────────────────
+
+    def _unwrap(self, http_status: int, data: dict[str, Any], fallback_message: str) -> dict[str, Any]:
+        if http_status != 200 or (data and (data.get("errorId") or data.get("errorCode"))):
+            error_msg = data.get("errorDescription") if data else fallback_message
+            message = str(error_msg or fallback_message)
+            error_kwargs: dict[str, Any] = {
+                "error_id": data.get("errorId") if data else None,
+                "error_code": data.get("errorCode") if data else None,
+                "error_description": data.get("errorDescription") if data else None,
+                "http_status": http_status,
+            }
+            if http_status == 429:
+                self._fail(RateLimitError(message or "Rate limit exceeded", **error_kwargs))
+            else:
+                self._fail(CapsolverError(message, **error_kwargs))
+        return data
+
+    def _fail(self, error: CapsolverError) -> NoReturn:
+        if self._options.on_error:
+            self._options.on_error(error)
+        raise error

capsolver_core/core/errors.py

@@ -0,0 +1,55 @@
+"""Error types for the CapSolver SDK.
+
+Mirrors the Node SDK's core/errors.ts.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+class CapsolverError(Exception):
+    """Raised when the CapSolver API returns an error envelope or an unexpected HTTP status."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        error_id: int | None = None,
+        error_code: str | None = None,
+        error_description: str | None = None,
+        http_status: int | None = None,
+    ) -> None:
+        super().__init__(message)
+        self.error_id = error_id
+        self.error_code = error_code
+        self.error_description = error_description
+        self.http_status = http_status
+
+
+class CapsolverTimeoutError(CapsolverError):
+    """Raised when polling exceeds the configured timeout."""
+
+    def __init__(self, timeout_seconds: float, task_id: str | None = None) -> None:
+        super().__init__(f"Timeout of {timeout_seconds}s reached while waiting for task result")
+        self.task_id = task_id
+
+
+class NetworkError(CapsolverError):
+    """Raised when the CapSolver API is unreachable after all retries.
+
+    Wraps connection-level failures (DNS, TCP, TLS, read timeout) so that
+    callers can distinguish "server said no" from "couldn't reach server".
+    """
+
+    def __init__(self, message: str, *, cause: Exception | None = None) -> None:
+        super().__init__(message)
+        self.cause = cause
+
+
+class RateLimitError(CapsolverError):
+    """Raised when the API returns HTTP 429 (Too Many Requests)."""
+
+    def __init__(self, message: str = "Rate limit exceeded", **kwargs: Any) -> None:
+        kwargs.setdefault("http_status", 429)
+        super().__init__(message, **kwargs)

capsolver_core/core/http.py

@@ -0,0 +1,137 @@
+"""Thin ``httpx`` wrapper around the CapSolver JSON API.
+
+Mirrors the Node SDK's core/http.ts. Uses ``httpx`` so both sync and
+async callers are supported without pulling in extra dependencies.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass, field
+from typing import Any
+
+import httpx
+
+from capsolver_core.core.errors import NetworkError
+
+logger = logging.getLogger("capsolver_core")
+
+
+@dataclass
+class HttpResp:
+    """Normalized HTTP response."""
+
+    status: int
+    status_text: str
+    data: Any
+    headers: httpx.Headers = field(repr=False)
+
+
+# Transient status codes that should trigger an automatic retry.
+_RETRY_STATUSES = frozenset({429, 500, 502, 503, 504})
+
+
+class FetchHttp:
+    """Minimal async HTTP client for the CapSolver JSON API.
+
+    Features:
+    - Reuses a single ``httpx.AsyncClient`` for connection pooling.
+    - Retries on transient HTTP errors (429, 5xx) with exponential backoff.
+    - Gracefully handles non-JSON responses instead of crashing.
+    """
+
+    def __init__(
+        self,
+        base_url: str = "https://api.capsolver.com",
+        *,
+        max_retries: int = 3,
+        retry_backoff: float = 1.0,
+    ) -> None:
+        self.base_url = base_url.rstrip("/")
+        self._max_retries = max_retries
+        self._retry_backoff = retry_backoff
+        self._client: httpx.AsyncClient | None = None
+
+    def get_url(self, path: str) -> str:
+        if not path.startswith("/"):
+            path = "/" + path
+        return self.base_url + path
+
+    async def _get_client(self, timeout_s: float) -> httpx.AsyncClient:
+        """Return the shared client, (re)creating it if the timeout changed."""
+        if self._client is None or self._client.is_closed:
+            self._client = httpx.AsyncClient(timeout=timeout_s)
+        return self._client
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP client. Safe to call multiple times."""
+        if self._client is not None and not self._client.is_closed:
+            await self._client.aclose()
+            self._client = None
+
+    async def post(
+        self,
+        path: str,
+        body: Any,
+        *,
+        timeout_ms: int = 30_000,
+        headers: dict[str, str] | None = None,
+    ) -> HttpResp:
+        merged_headers = {"Content-Type": "application/json"}
+        if headers:
+            merged_headers.update(headers)
+
+        url = self.get_url(path)
+        timeout_s = timeout_ms / 1000.0
+        last_exc: Exception | None = None
+
+        for attempt in range(1, self._max_retries + 1):
+            try:
+                client = await self._get_client(timeout_s)
+                resp = await client.post(url, json=body, headers=merged_headers)
+
+                # Retry on transient server errors
+                if resp.status_code in _RETRY_STATUSES and attempt < self._max_retries:
+                    delay = self._retry_backoff * (2 ** (attempt - 1))
+                    logger.warning(
+                        "Transient HTTP %d on %s (attempt %d/%d), retrying in %.1fs",
+                        resp.status_code, path, attempt, self._max_retries, delay,
+                    )
+                    await asyncio.sleep(delay)
+                    continue
+
+                # Parse JSON safely — non-JSON bodies (e.g. HTML 502 page)
+                # should produce an empty dict, not crash.
+                try:
+                    data = resp.json()
+                except (ValueError, TypeError):
+                    logger.warning(
+                        "Non-JSON response (HTTP %d) from %s, treating as empty",
+                        resp.status_code, path,
+                    )
+                    data = {}
+
+                return HttpResp(
+                    status=resp.status_code,
+                    status_text=resp.reason_phrase or "",
+                    data=data,
+                    headers=resp.headers,
+                )
+
+            except (httpx.ConnectError, httpx.ReadError, httpx.TimeoutException) as exc:
+                last_exc = exc
+                if attempt < self._max_retries:
+                    delay = self._retry_backoff * (2 ** (attempt - 1))
+                    logger.warning(
+                        "Network error on %s: %s (attempt %d/%d), retrying in %.1fs",
+                        path, exc, attempt, self._max_retries, delay,
+                    )
+                    await asyncio.sleep(delay)
+                    continue
+
+        # All retries exhausted on network errors
+        raise NetworkError(
+            f"Failed to reach CapSolver API after {self._max_retries} attempts: {last_exc}",
+            cause=last_exc,
+        )

capsolver_core/core/tasks.py

@@ -0,0 +1,134 @@
+"""Pure task-payload builders.
+
+Mirrors the Node SDK's core/tasks.ts. Each builder is a pure function
+that takes keyword arguments and returns a plain ``dict`` ready for
+JSON serialization.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from capsolver_core.core.types import (
+    ReCaptchaV2Task,
+    ReCaptchaV3Task,
+    CloudflareTask,
+)
+
+
+# ── reCAPTCHA v2 ──────────────────────────────────────────────────
+
+
+def build_recaptcha_v2_task(
+    *,
+    website_url: str,
+    website_key: str,
+    page_action: str | None = None,
+    invisible: bool | None = None,
+    enterprise: bool | None = None,
+    enterprise_payload: dict[str, Any] | None = None,
+    api_domain: str | None = None,
+    proxy: str | None = None,
+    user_agent: str | None = None,
+) -> ReCaptchaV2Task:
+    proxyless = not proxy
+    is_enterprise = enterprise
+
+    if is_enterprise:
+        task_type = "ReCaptchaV2EnterpriseTaskProxyLess" if proxyless else "ReCaptchaV2EnterpriseTask"
+    else:
+        task_type = "ReCaptchaV2TaskProxyLess" if proxyless else "ReCaptchaV2Task"
+
+    task: ReCaptchaV2Task = {
+        "type": task_type,
+        "websiteURL": website_url,
+        "websiteKey": website_key,
+    }
+
+    if invisible is not None:
+        task["invisible"] = invisible
+    if page_action:
+        task["pageAction"] = page_action
+    if api_domain:
+        task["apiDomain"] = api_domain
+    if enterprise_payload:
+        task["enterprisePayload"] = enterprise_payload
+    if proxy:
+        task["proxy"] = proxy
+    if user_agent:
+        task["userAgent"] = user_agent
+
+    return task
+
+
+# ── reCAPTCHA v3 ──────────────────────────────────────────────────
+
+
+def build_recaptcha_v3_task(
+    *,
+    website_url: str,
+    website_key: str,
+    page_action: str | None = None,
+    min_score: float | None = None,
+    enterprise: bool | None = None,
+    enterprise_payload: dict[str, Any] | None = None,
+    api_domain: str | None = None,
+    proxy: str | None = None,
+) -> ReCaptchaV3Task:
+    proxyless = not proxy
+    is_enterprise = enterprise
+
+    if is_enterprise:
+        task_type = "ReCaptchaV3EnterpriseTaskProxyLess" if proxyless else "ReCaptchaV3EnterpriseTask"
+    else:
+        task_type = "ReCaptchaV3TaskProxyLess" if proxyless else "ReCaptchaV3Task"
+
+    task: ReCaptchaV3Task = {
+        "type": task_type,
+        "websiteURL": website_url,
+        "websiteKey": website_key,
+    }
+
+    if page_action:
+        task["pageAction"] = page_action
+    if min_score is not None:
+        task["minScore"] = min_score
+    if api_domain:
+        task["apiDomain"] = api_domain
+    if enterprise_payload:
+        task["enterprisePayload"] = enterprise_payload
+    if proxy:
+        task["proxy"] = proxy
+
+    return task
+
+
+# ── Cloudflare Turnstile ──────────────────────────────────────────
+
+
+def build_cloudflare_task(
+    *,
+    website_url: str,
+    website_key: str,
+    action: str | None = None,
+    cdata: str | None = None,
+    proxy: str | None = None,
+) -> CloudflareTask:
+    task: CloudflareTask = {
+        "type": "AntiTurnstileTaskProxyLess" if not proxy else "AntiTurnstileTask",
+        "websiteURL": website_url,
+        "websiteKey": website_key,
+    }
+
+    if action or cdata:
+        metadata: dict[str, str] = {"type": "turnstile"}
+        if action:
+            metadata["action"] = action
+        if cdata:
+            metadata["cdata"] = cdata
+        task["metadata"] = metadata
+
+    if proxy:
+        task["proxy"] = proxy
+
+    return task

capsolver_core/core/types.py

@@ -0,0 +1,157 @@
+"""CapSolver API types — token-mode only.
+
+Mirrors the Node SDK's core/types.ts. Uses ``str, Enum`` so values can
+be compared directly against raw strings from the API.
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+
+class CaptchaType(str, Enum):
+    """Captcha families the SDK can reason about."""
+
+    RECAPTCHA_V2 = "reCaptchaV2"
+    RECAPTCHA_V3 = "reCaptchaV3"
+    CLOUDFLARE = "cloudflare"
+
+
+# ── Task lifecycle ────────────────────────────────────────────────
+
+
+class TaskStatus(str, Enum):
+    IDLE = "idle"
+    READY = "ready"
+    PROCESSING = "processing"
+    FAILED = "failed"
+
+
+# ── Cookie ────────────────────────────────────────────────────────
+
+
+class Cookie:
+    __slots__ = ("name", "value")
+
+    def __init__(self, name: str, value: str) -> None:
+        self.name = name
+        self.value = value
+
+    def to_dict(self) -> dict[str, str]:
+        return {"name": self.name, "value": self.value}
+
+
+# ── API envelope types ────────────────────────────────────────────
+
+
+class BaseResp:
+    """Base shape for every CapSolver API response."""
+
+    __slots__ = ("error_id", "error_code", "error_description", "status", "solution")
+
+    def __init__(
+        self,
+        error_id: int = 0,
+        error_code: str = "",
+        error_description: str = "",
+        status: str | None = None,
+        solution: Any = None,
+    ) -> None:
+        self.error_id = error_id
+        self.error_code = error_code
+        self.error_description = error_description
+        self.status = status
+        self.solution = solution
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> BaseResp:
+        return cls(
+            error_id=data.get("errorId", 0),
+            error_code=data.get("errorCode", ""),
+            error_description=data.get("errorDescription", ""),
+            status=data.get("status"),
+            solution=data.get("solution"),
+        )
+
+
+class CreateTaskResp(BaseResp):
+    __slots__ = ("task_id",)
+
+    def __init__(self, task_id: str, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.task_id = task_id
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> CreateTaskResp:
+        return cls(
+            task_id=data.get("taskId", ""),
+            error_id=data.get("errorId", 0),
+            error_code=data.get("errorCode", ""),
+            error_description=data.get("errorDescription", ""),
+            status=data.get("status"),
+            solution=data.get("solution"),
+        )
+
+
+class BalanceResp(BaseResp):
+    __slots__ = ("balance", "packages")
+
+    def __init__(self, balance: float = 0.0, packages: list[Any] | None = None, **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.balance = balance
+        self.packages = packages or []
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> BalanceResp:
+        return cls(
+            balance=data.get("balance", 0.0),
+            packages=data.get("packages", []),
+            error_id=data.get("errorId", 0),
+            error_code=data.get("errorCode", ""),
+            error_description=data.get("errorDescription", ""),
+            status=data.get("status"),
+            solution=data.get("solution"),
+        )
+
+
+# ── Token-mode task payload types ─────────────────────────────────
+# These are typed dicts so task builders can return plain dicts that
+# serialize directly to JSON without extra conversion.
+
+ReCaptchaV2Task = dict[str, Any]
+ReCaptchaV3Task = dict[str, Any]
+CloudflareTask = dict[str, Any]
+AnyTask = dict[str, Any]
+
+
+# ── Solution payloads ─────────────────────────────────────────────
+
+
+class TokenSolution:
+    """Shared shape for reCAPTCHA / Cloudflare solutions."""
+
+    __slots__ = ("g_recaptcha_response", "token", "user_agent", "expire_time")
+
+    def __init__(
+        self,
+        g_recaptcha_response: str | None = None,
+        token: str | None = None,
+        user_agent: str | None = None,
+        expire_time: int | None = None,
+    ) -> None:
+        self.g_recaptcha_response = g_recaptcha_response
+        self.token = token
+        self.user_agent = user_agent
+        self.expire_time = expire_time
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any] | None) -> TokenSolution | None:
+        if data is None:
+            return None
+        return cls(
+            g_recaptcha_response=data.get("gRecaptchaResponse"),
+            token=data.get("token"),
+            user_agent=data.get("userAgent"),
+            expire_time=data.get("expireTime"),
+        )