capsolver-core 0.1.0__py3-none-any.whl

capsolver_core/capsolver.py

@@ -0,0 +1,206 @@
+"""Capsolver — the public, agent-facing entry point.
+
+Mirrors the Node SDK's capsolver.ts. Wires a ``CapsolverClient``
+(token-solving core) to a ``HandlerRegistry`` of per-captcha handlers.
+
+The API key is optional at construction so read-only calls like
+``get_supported_captchas()`` work without one; it is required (and
+validated lazily) the first time a solve is attempted.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from capsolver_core.core.client import CapsolverClient, CapsolverClientOptions, WaitOptions
+from capsolver_core.core.errors import CapsolverError
+from capsolver_core.core.types import CaptchaType, BalanceResp
+from capsolver_core.captcha.handler import CaptchaHandler
+from capsolver_core.captcha.handlers import default_handlers
+from capsolver_core.captcha.registry import HandlerRegistry
+from capsolver_core.captcha.types import CaptchaInfo, Solution
+from capsolver_core.browser.adapter import to_driver
+
+
+@dataclass
+class SolveOnPageOptions:
+    """Options for ``Capsolver.solve_on_page``."""
+
+    autofill: bool = True
+    throw_on_error: bool = False
+    timeout: float | None = None
+    polling_interval: float | None = None
+
+
+@dataclass
+class SolveOnPageResult:
+    """Per-captcha result from ``solve_on_page``."""
+
+    info: CaptchaInfo
+    solution: Solution | None = None
+    filled: bool | None = None
+    error: str | None = None
+
+
+class Capsolver:
+    """Main SDK entry point — detect, solve, and autofill captchas."""
+
+    def __init__(
+        self,
+        *,
+        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: Any = None,
+        handlers: list[CaptchaHandler] | None = None,
+    ) -> None:
+        self._client_options = CapsolverClientOptions(
+            api_key=api_key,
+            service=service,
+            default_timeout=default_timeout,
+            polling_interval=polling_interval,
+            request_timeout_ms=request_timeout_ms,
+            app_id=app_id,
+            source=source,
+            version=version,
+            on_error=on_error,
+        )
+        self._registry = HandlerRegistry()
+        self._client: CapsolverClient | None = None
+
+        for h in handlers if handlers is not None else default_handlers():
+            self._registry.register(h)
+
+    # ── resource management ───────────────────────────────────────
+
+    async def aclose(self) -> None:
+        """Close the underlying HTTP client and release connections."""
+        if self._client is not None:
+            await self._client.aclose()
+
+    async def __aenter__(self) -> Capsolver:
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+    # ── registry access ───────────────────────────────────────────
+
+    def register(self, handler: CaptchaHandler) -> Capsolver:
+        """Add or replace a captcha handler."""
+        self._registry.register(handler)
+        return self
+
+    def get_supported_captchas(self) -> list[str]:
+        """Names of every registered handler."""
+        return self._registry.list()
+
+    def get_handler(self, key: str | CaptchaType) -> CaptchaHandler | None:
+        """Resolve a handler by name or captcha type."""
+        return self._registry.resolve(key)
+
+    # ── solving ───────────────────────────────────────────────────
+
+    async def solve(self, info: CaptchaInfo, wait_options: WaitOptions | None = None) -> Solution:
+        """Solve a captcha from its normalized info (token mode)."""
+        if not info or not info.type:
+            raise CapsolverError("CaptchaInfo.type is required to pick a handler")
+
+        handler = self._registry.resolve(info.type)
+        if not handler:
+            raise CapsolverError(f"No handler registered for captcha type: {info.type}")
+
+        return await handler.solve(info, self._get_client(), wait_options)
+
+    # ── browser-aware methods ─────────────────────────────────────
+
+    async def detect(self, page: Any) -> list[CaptchaType]:
+        """Which captcha types are present on a page. Returns ``[]`` when none.
+
+        Derived from :meth:`get_captcha_info` so the reported type reflects the
+        actual widget — e.g. reCAPTCHA v3 is returned as ``RECAPTCHA_V3``, not
+        the handler's canonical ``RECAPTCHA_V2`` family. Order-preserving and
+        de-duplicated.
+        """
+        driver = to_driver(page)
+        found: list[CaptchaType] = []
+        for info in await self.get_captcha_info(driver):
+            if info.type not in found:
+                found.append(info.type)
+        return found
+
+    async def get_captcha_info(self, page: Any) -> list[CaptchaInfo]:
+        """Structured params for every captcha on the page. Returns ``[]`` when none."""
+        driver = to_driver(page)
+        infos: list[CaptchaInfo] = []
+        for handler in self._registry.handlers():
+            try:
+                result = await handler.get_captcha_info(driver)
+                infos.extend(result)
+            except Exception:
+                pass
+        return infos
+
+    async def solve_on_page(
+        self,
+        page: Any,
+        options: SolveOnPageOptions | None = None,
+    ) -> list[SolveOnPageResult]:
+        """One-shot: detect → solve → (optionally) autofill.
+
+        Per-captcha errors are collected unless ``throw_on_error`` is set.
+        """
+        opts = options or SolveOnPageOptions()
+        driver = to_driver(page)
+        infos = await self.get_captcha_info(driver)
+
+        wait_opts = WaitOptions(timeout=opts.timeout, polling_interval=opts.polling_interval)
+
+        results: list[SolveOnPageResult] = []
+        for info in infos:
+            result = SolveOnPageResult(info=info)
+            try:
+                handler = self._registry.resolve(info.type)
+                if not handler:
+                    raise CapsolverError(f"No handler registered for captcha type: {info.type}")
+
+                result.solution = await handler.solve(info, self._get_client(), wait_opts)
+
+                if opts.autofill and hasattr(handler, "fill") and handler.fill is not None:
+                    try:
+                        result.filled = await handler.fill(driver, result.solution, info)
+                    except Exception:
+                        result.filled = False
+            except Exception as e:
+                if opts.throw_on_error:
+                    raise
+                result.error = str(e)
+            results.append(result)
+        return results
+
+    # ── account ───────────────────────────────────────────────────
+
+    async def get_balance(self) -> BalanceResp:
+        """Account balance (requires an API key)."""
+        return await self._get_client().get_balance()
+
+    # ── internals ─────────────────────────────────────────────────
+
+    def _get_client(self) -> CapsolverClient:
+        """Lazily construct the client, validating the API key on first use."""
+        if self._client is None:
+            if not self._client_options.api_key:
+                raise CapsolverError("Capsolver: apiKey is required to solve. Pass it to the constructor.")
+            self._client = CapsolverClient(self._client_options)
+        return self._client
+
+
+def create_capsolver(**kwargs: Any) -> Capsolver:
+    """Convenience factory mirroring ``Capsolver(...)``."""
+    return Capsolver(**kwargs)

capsolver_core/captcha/__init__.py

@@ -0,0 +1,20 @@
+"""Captcha layer — handler protocol, registry, built-in handlers."""
+
+from capsolver_core.captcha.types import CaptchaInfo, Solution
+from capsolver_core.captcha.handler import CaptchaHandler
+from capsolver_core.captcha.registry import HandlerRegistry
+from capsolver_core.captcha.handlers import (
+    RecaptchaHandler,
+    CloudflareHandler,
+    default_handlers,
+)
+
+__all__ = [
+    "CaptchaInfo",
+    "Solution",
+    "CaptchaHandler",
+    "HandlerRegistry",
+    "RecaptchaHandler",
+    "CloudflareHandler",
+    "default_handlers",
+]

capsolver_core/captcha/handler.py

@@ -0,0 +1,55 @@
+"""CaptchaHandler — the per-captcha plugin contract.
+
+Mirrors the Node SDK's captcha/handler.ts. Uses ``Protocol`` for
+structural subtyping so third-party handlers don't need to inherit.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from capsolver_core.core.types import CaptchaType
+from capsolver_core.core.client import CapsolverClient, WaitOptions
+from capsolver_core.browser.driver import PageDriver
+from capsolver_core.captcha.types import CaptchaInfo, Solution
+
+
+@runtime_checkable
+class CaptchaHandler(Protocol):
+    """Per-captcha-family plugin interface."""
+
+    @property
+    def type(self) -> CaptchaType:
+        """Canonical captcha family this handler serves."""
+        ...
+
+    @property
+    def name(self) -> str:
+        """Short, stable name used for registration."""
+        ...
+
+    @property
+    def aliases(self) -> tuple[CaptchaType, ...]:
+        """Extra captcha types this handler also serves."""
+        ...
+
+    async def solve(
+        self,
+        info: CaptchaInfo,
+        client: CapsolverClient,
+        wait_options: WaitOptions | None = None,
+    ) -> Solution:
+        """Token-mode solve: build the task, poll, normalize the result."""
+        ...
+
+    async def detect(self, page: PageDriver) -> bool:
+        """Is this captcha present on the page?"""
+        ...
+
+    async def get_captcha_info(self, page: PageDriver) -> list[CaptchaInfo]:
+        """Extract structured info for every instance on the page."""
+        ...
+
+    async def fill(self, page: PageDriver, solution: Solution, info: CaptchaInfo) -> bool:
+        """Write a solved token back into the page (autofill)."""
+        ...

capsolver_core/captcha/handlers/__init__.py

@@ -0,0 +1,20 @@
+"""Built-in captcha handlers."""
+
+from capsolver_core.captcha.handlers.recaptcha import RecaptchaHandler
+from capsolver_core.captcha.handlers.cloudflare import CloudflareHandler
+from capsolver_core.captcha.handler import CaptchaHandler
+
+
+def default_handlers() -> list[CaptchaHandler]:
+    """Fresh instances of every built-in token-mode handler."""
+    return [
+        RecaptchaHandler(),
+        CloudflareHandler(),
+    ]
+
+
+__all__ = [
+    "RecaptchaHandler",
+    "CloudflareHandler",
+    "default_handlers",
+]

capsolver_core/captcha/handlers/cloudflare.py

@@ -0,0 +1,83 @@
+"""Cloudflare Turnstile handler (token mode).
+
+Mirrors the Node SDK's captcha/handlers/cloudflare.ts.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from capsolver_core.core.types import CaptchaType, TokenSolution
+from capsolver_core.core.client import CapsolverClient, WaitOptions
+from capsolver_core.core.tasks import build_cloudflare_task
+from capsolver_core.browser.driver import PageDriver
+from capsolver_core.browser.inject.cloudflare import (
+    DETECT_CLOUDFLARE_JS,
+    GET_CLOUDFLARE_INFOS_JS,
+    FILL_CLOUDFLARE_JS,
+)
+from capsolver_core.captcha.types import CaptchaInfo, Solution
+from capsolver_core.captcha.handlers.support import require_url_and_key, to_solution
+
+
+class CloudflareHandler:
+    """Cloudflare Turnstile token-mode handler."""
+
+    @property
+    def type(self) -> CaptchaType:
+        return CaptchaType.CLOUDFLARE
+
+    @property
+    def name(self) -> str:
+        return "cloudflare"
+
+    @property
+    def aliases(self) -> tuple[CaptchaType, ...]:
+        return ()
+
+    async def solve(
+        self,
+        info: CaptchaInfo,
+        client: CapsolverClient,
+        wait_options: WaitOptions | None = None,
+    ) -> Solution:
+        website_url, website_key = require_url_and_key(info)
+        task = build_cloudflare_task(
+            website_url=website_url,
+            website_key=website_key,
+            action=info.page_action,
+            cdata=info.cdata,
+            proxy=info.proxy,
+        )
+        res = await client.create_task_result(task, wait_options)
+        return to_solution(CaptchaType.CLOUDFLARE, TokenSolution.from_dict(res.get("solution")))
+
+    async def detect(self, page: PageDriver) -> bool:
+        return bool(await page.evaluate(DETECT_CLOUDFLARE_JS))
+
+    async def get_captcha_info(self, page: PageDriver) -> list[CaptchaInfo]:
+        url = await page.url()
+        raws: list[dict[str, Any]] = await page.evaluate(GET_CLOUDFLARE_INFOS_JS)
+        infos: list[CaptchaInfo] = []
+        for r in raws:
+            if not r.get("websiteKey"):
+                continue
+            infos.append(
+                CaptchaInfo(
+                    type=CaptchaType.CLOUDFLARE,
+                    website_url=url,
+                    website_key=r["websiteKey"],
+                    page_action=r.get("action") or None,
+                    cdata=r.get("cdata") or None,
+                    container_id=r.get("containerId"),
+                )
+            )
+        return infos
+
+    async def fill(self, page: PageDriver, solution: Solution, info: CaptchaInfo) -> bool:
+        return bool(
+            await page.evaluate(
+                FILL_CLOUDFLARE_JS,
+                {"token": solution.token, "containerId": info.container_id},
+            )
+        )

capsolver_core/captcha/handlers/recaptcha.py

@@ -0,0 +1,106 @@
+"""reCAPTCHA handler — covers v2 and v3 (incl. enterprise) in token mode.
+
+Mirrors the Node SDK's captcha/handlers/recaptcha.ts.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from capsolver_core.core.types import CaptchaType, TokenSolution
+from capsolver_core.core.client import CapsolverClient, WaitOptions
+from capsolver_core.core.tasks import build_recaptcha_v2_task, build_recaptcha_v3_task
+from capsolver_core.browser.driver import PageDriver
+from capsolver_core.browser.inject.recaptcha import (
+    DETECT_RECAPTCHA_JS,
+    GET_RECAPTCHA_INFOS_JS,
+    FILL_RECAPTCHA_JS,
+)
+from capsolver_core.captcha.types import CaptchaInfo, Solution
+from capsolver_core.captcha.handlers.support import require_url_and_key, to_solution
+
+
+class RecaptchaHandler:
+    """reCAPTCHA v2 + v3 (incl. enterprise) token-mode handler."""
+
+    @property
+    def type(self) -> CaptchaType:
+        return CaptchaType.RECAPTCHA_V2
+
+    @property
+    def name(self) -> str:
+        return "recaptcha"
+
+    @property
+    def aliases(self) -> tuple[CaptchaType, ...]:
+        return (CaptchaType.RECAPTCHA_V3,)
+
+    async def solve(
+        self,
+        info: CaptchaInfo,
+        client: CapsolverClient,
+        wait_options: WaitOptions | None = None,
+    ) -> Solution:
+        website_url, website_key = require_url_and_key(info)
+        enterprise_payload = {"s": info.s} if info.s else None
+        is_v3 = info.version == "v3" or info.type == CaptchaType.RECAPTCHA_V3
+
+        if is_v3:
+            task = build_recaptcha_v3_task(
+                website_url=website_url,
+                website_key=website_key,
+                page_action=info.page_action,
+                min_score=info.min_score,
+                enterprise=info.enterprise,
+                enterprise_payload=enterprise_payload,
+                proxy=info.proxy,
+            )
+        else:
+            task = build_recaptcha_v2_task(
+                website_url=website_url,
+                website_key=website_key,
+                invisible=info.invisible,
+                page_action=info.page_action,
+                enterprise=info.enterprise,
+                enterprise_payload=enterprise_payload,
+                proxy=info.proxy,
+                user_agent=info.user_agent,
+            )
+
+        res = await client.create_task_result(task, wait_options)
+        return to_solution(info.type, TokenSolution.from_dict(res.get("solution")))
+
+    async def detect(self, page: PageDriver) -> bool:
+        return bool(await page.evaluate(DETECT_RECAPTCHA_JS))
+
+    async def get_captcha_info(self, page: PageDriver) -> list[CaptchaInfo]:
+        url = await page.url()
+        raws: list[dict[str, Any]] = await page.evaluate(GET_RECAPTCHA_INFOS_JS)
+        infos: list[CaptchaInfo] = []
+        for r in raws:
+            if not r.get("sitekey"):
+                continue
+            infos.append(
+                CaptchaInfo(
+                    type=CaptchaType.RECAPTCHA_V3 if r.get("version") == "v3" else CaptchaType.RECAPTCHA_V2,
+                    version=r.get("version"),
+                    website_url=url,
+                    website_key=r["sitekey"],
+                    page_action=r.get("action") or None,
+                    invisible=r.get("invisible"),
+                    enterprise=r.get("enterprise"),
+                    s=r.get("s") or None,
+                    container_id=r.get("containerId"),
+                    callback=r.get("callback"),
+                    binded_button_id=r.get("bindedButtonId"),
+                )
+            )
+        return infos
+
+    async def fill(self, page: PageDriver, solution: Solution, info: CaptchaInfo) -> bool:
+        return bool(
+            await page.evaluate(
+                FILL_RECAPTCHA_JS,
+                {"token": solution.token, "containerId": info.container_id, "callback": info.callback},
+            )
+        )

capsolver_core/captcha/handlers/support.py

@@ -0,0 +1,30 @@
+"""Shared helpers for token-mode handlers."""
+
+from __future__ import annotations
+
+from capsolver_core.core.errors import CapsolverError
+from capsolver_core.core.types import CaptchaType, TokenSolution
+from capsolver_core.captcha.types import CaptchaInfo, Solution
+
+
+def require_url_and_key(info: CaptchaInfo) -> tuple[str, str]:
+    """Ensure the fields every token task needs are present."""
+    if not info.website_url:
+        raise CapsolverError("CaptchaInfo.website_url is required to solve")
+    if not info.website_key:
+        raise CapsolverError("CaptchaInfo.website_key is required to solve")
+    return info.website_url, info.website_key
+
+
+def to_solution(captcha_type: CaptchaType, raw: TokenSolution | None) -> Solution:
+    """Normalize an API solution payload into the SDK ``Solution`` shape."""
+    token = (raw.g_recaptcha_response if raw else None) or (raw.token if raw else None)
+    if not token:
+        raise CapsolverError("Solver returned an empty token", error_code="EMPTY_TOKEN")
+    return Solution(
+        captcha_type=captcha_type,
+        token=token,
+        raw=raw,
+        expire_time=raw.expire_time if raw else None,
+        user_agent=raw.user_agent if raw else None,
+    )

capsolver_core/captcha/registry.py

@@ -0,0 +1,56 @@
+"""HandlerRegistry — register/lookup captcha handlers.
+
+Mirrors the Node SDK's captcha/registry.ts.
+"""
+
+from __future__ import annotations
+
+import builtins
+
+from capsolver_core.core.types import CaptchaType
+from capsolver_core.captcha.handler import CaptchaHandler
+
+
+class HandlerRegistry:
+    """Index handlers by short name and by every ``CaptchaType`` they serve."""
+
+    def __init__(self) -> None:
+        self._by_name: dict[str, CaptchaHandler] = {}
+        self._by_type: dict[CaptchaType, CaptchaHandler] = {}
+
+    def register(self, handler: CaptchaHandler) -> HandlerRegistry:
+        self._by_name[handler.name] = handler
+        self._by_type[handler.type] = handler
+        for alias in handler.aliases:
+            self._by_type[alias] = handler
+        return self
+
+    def get(self, name: str) -> CaptchaHandler | None:
+        return self._by_name.get(name)
+
+    def get_by_type(self, captcha_type: CaptchaType) -> CaptchaHandler | None:
+        return self._by_type.get(captcha_type)
+
+    def resolve(self, key: str | CaptchaType) -> CaptchaHandler | None:
+        """Look up by name string or ``CaptchaType``."""
+        if isinstance(key, CaptchaType):
+            return self._by_type.get(key)
+        # Try by name first
+        handler = self._by_name.get(key)
+        if handler:
+            return handler
+        # Try converting string to CaptchaType (e.g. "reCaptchaV2")
+        try:
+            return self._by_type.get(CaptchaType(key))
+        except (ValueError, KeyError):
+            return None
+
+    def list(self) -> builtins.list[str]:
+        """Registered handler names, in insertion order."""
+        return builtins.list(self._by_name.keys())
+
+    def handlers(self) -> builtins.list[CaptchaHandler]:
+        return builtins.list(self._by_name.values())
+
+    def has(self, name: str) -> bool:
+        return name in self._by_name

capsolver_core/captcha/types.py

@@ -0,0 +1,60 @@
+"""Contract types shared between detection and solving.
+
+Mirrors the Node SDK's captcha/types.ts.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from capsolver_core.core.types import CaptchaType, TokenSolution
+
+
+@dataclass
+class CaptchaInfo:
+    """Normalized, browser-agnostic description of a captcha on a page."""
+
+    type: CaptchaType
+    website_url: str = ""
+    website_key: str = ""
+
+    # reCAPTCHA-specific
+    version: str | None = None  # "v2" | "v3"
+    page_action: str | None = None
+    invisible: bool | None = None
+    enterprise: bool | None = None
+    s: str | None = None  # Enterprise ``s`` token
+    min_score: float | None = None  # reCAPTCHA v3
+
+    # Cloudflare Turnstile
+    cdata: str | None = None
+
+    # Generic
+    proxy: str | None = None
+    user_agent: str | None = None
+
+    # DOM hooks (Phase 3 autofill)
+    container_id: str | None = None
+    callback: str | None = None
+    binded_button_id: str | None = None
+
+    # Carry-through for fields not yet modelled
+    extra: dict[str, Any] = field(default_factory=dict)
+
+    def __post_init__(self) -> None:
+        if not self.website_url:
+            raise ValueError("CaptchaInfo.website_url is required")
+        if not self.website_key:
+            raise ValueError("CaptchaInfo.website_key is required")
+
+
+@dataclass
+class Solution:
+    """Normalized solve result."""
+
+    captcha_type: CaptchaType
+    token: str
+    raw: TokenSolution | None = None
+    expire_time: int | None = None
+    user_agent: str | None = None

capsolver_core/core/__init__.py

@@ -0,0 +1,7 @@
+"""Core layer — HTTP, errors, task builders, client, types."""
+
+from capsolver_core.core.types import *  # noqa: F401,F403
+from capsolver_core.core.errors import *  # noqa: F401,F403
+from capsolver_core.core.http import *  # noqa: F401,F403
+from capsolver_core.core.tasks import *  # noqa: F401,F403
+from capsolver_core.core.client import *  # noqa: F401,F403