capsolver-core 0.1.0__py3-none-any.whl

capsolver_core/__init__.py

@@ -0,0 +1,44 @@
+"""CapSolver SDK for Python — detect, solve and autofill captchas via the CapSolver API."""
+
+from capsolver_core.capsolver import Capsolver, create_capsolver
+from capsolver_core.core.types import CaptchaType
+from capsolver_core.core.errors import CapsolverError, CapsolverTimeoutError, NetworkError, RateLimitError
+from capsolver_core.core.client import CapsolverClient, WaitOptions
+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,
+)
+from capsolver_core.browser.driver import PageDriver
+from capsolver_core.browser.adapter import from_playwright_page, to_driver
+
+__all__ = [
+    # Main entry
+    "Capsolver",
+    "create_capsolver",
+    # Core
+    "CaptchaType",
+    "CapsolverError",
+    "CapsolverTimeoutError",
+    "NetworkError",
+    "RateLimitError",
+    "CapsolverClient",
+    "WaitOptions",
+    # Captcha
+    "CaptchaInfo",
+    "Solution",
+    "CaptchaHandler",
+    "HandlerRegistry",
+    "RecaptchaHandler",
+    "CloudflareHandler",
+    "default_handlers",
+    # Browser
+    "PageDriver",
+    "from_playwright_page",
+    "to_driver",
+]
+
+__version__ = "0.1.0"

capsolver_core/__main__.py

@@ -0,0 +1,99 @@
+"""CLI entry point for ``python -m capsolver_core`` and the ``capsolver`` console script.
+
+Usage:
+    capsolver info                 # show version, Python, optional deps
+    capsolver balance              # check API balance (needs CAPSOLVER_API_KEY)
+    capsolver list-types           # list supported captcha types
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from importlib.metadata import version as pkg_version
+
+
+def _cmd_info(_args: argparse.Namespace) -> None:
+    """Print SDK version, Python version, and optional-dependency availability."""
+    print(f"capsolver-core  {pkg_version('capsolver-core')}")
+    print(f"python         {sys.version.split()[0]}")
+
+    optionals = {"playwright": "playwright"}
+    for label, module in optionals.items():
+        try:
+            mod_ver = pkg_version(module)
+            print(f"{label:<14} {mod_ver}")
+        except Exception:
+            print(f"{label:<14} not installed")
+
+
+def _cmd_balance(args: argparse.Namespace) -> None:
+    """Check API balance — requires CAPSOLVER_API_KEY."""
+    import asyncio
+    import os
+
+    key = args.api_key or os.environ.get("CAPSOLVER_API_KEY", "")
+    if not key:
+        print("Error: CAPSOLVER_API_KEY is not set.", file=sys.stderr)
+        sys.exit(1)
+
+    from capsolver_core import Capsolver
+
+    async def _run() -> None:
+        cs = Capsolver(api_key=key)
+        balance = await cs.get_balance()
+        data = {"balance": balance.balance, "packages": balance.packages}
+        print(json.dumps(data, indent=2, ensure_ascii=False))
+
+    asyncio.run(_run())
+
+
+def _cmd_list_types(_args: argparse.Namespace) -> None:
+    """List all supported captcha types."""
+    from capsolver_core import Capsolver, CaptchaType
+
+    cs = Capsolver()
+    handlers = cs.get_supported_captchas()
+    all_types = [t.value for t in CaptchaType]
+
+    print("All captcha types:")
+    for t in all_types:
+        marker = " *" if t in handlers else ""
+        print(f"  {t}{marker}")
+
+    if handlers:
+        print(f"\nRegistered handlers ({len(handlers)}): {', '.join(handlers)}")
+    print("\n(* = handler registered)")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="capsolver",
+        description="CapSolver SDK — diagnostics and info CLI.",
+    )
+    sub = parser.add_subparsers(dest="command")
+
+    sub.add_parser("info", help="Show version and environment info.")
+
+    bal = sub.add_parser("balance", help="Check CapSolver account balance.")
+    bal.add_argument("--api-key", default=None, help="API key (default: CAPSOLVER_API_KEY env).")
+
+    sub.add_parser("list-types", help="List supported captcha types.")
+
+    args = parser.parse_args()
+
+    if args.command is None:
+        parser.print_help()
+        sys.exit(0)
+
+    dispatch = {
+        "info": _cmd_info,
+        "balance": _cmd_balance,
+        "list-types": _cmd_list_types,
+    }
+    dispatch[args.command](args)
+
+
+if __name__ == "__main__":
+    main()

capsolver_core/browser/__init__.py

@@ -0,0 +1,6 @@
+"""Browser layer — page driver, adapters, and inject scripts."""
+
+from capsolver_core.browser.driver import PageDriver
+from capsolver_core.browser.adapter import from_playwright_page, to_driver
+
+__all__ = ["PageDriver", "from_playwright_page", "to_driver"]

capsolver_core/browser/adapter.py

@@ -0,0 +1,116 @@
+"""Page adapters.
+
+Mirrors the Node SDK's browser/adapter.ts. Wraps a Playwright ``Page``
+(or any structurally-compatible object) as a ``PageDriver``.
+
+The SDK deliberately does **not** import Playwright at module level so
+it stays dependency-free at import time — callers pass their own page.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, cast, runtime_checkable
+
+from capsolver_core.browser.driver import PageDriver
+
+
+@runtime_checkable
+class EvaluatablePage(Protocol):
+    """The minimal surface the SDK needs from a Playwright/Selenium page."""
+
+    async def evaluate(self, expression: str, arg: Any = None) -> Any: ...
+    def url(self) -> str: ...
+
+
+class _PlaywrightDriver:
+    """Wraps a Playwright ``Page`` as a ``PageDriver``."""
+
+    def __init__(self, page: Any) -> None:
+        self._page = page
+
+    async def evaluate(self, script: str, arg: Any = None) -> Any:
+        if arg is not None:
+            return await self._page.evaluate(script, arg)
+        return await self._page.evaluate(script)
+
+    async def url(self) -> str:
+        return cast(str, self._page.url)
+
+    async def wait_for_selector(self, selector: str, *, timeout: float | None = None) -> None:
+        opts: dict[str, Any] = {}
+        if timeout is not None:
+            opts["timeout"] = timeout
+        await self._page.wait_for_selector(selector, **opts)
+
+
+class _GenericDriver:
+    """Wraps any object that exposes ``evaluate`` and ``url`` (async or sync)."""
+
+    def __init__(self, page: Any) -> None:
+        self._page = page
+
+    async def evaluate(self, script: str, arg: Any = None) -> Any:
+        fn = self._page.evaluate
+        import asyncio
+
+        if arg is not None:
+            result = fn(script, arg)
+        else:
+            result = fn(script)
+        if asyncio.iscoroutine(result):
+            return await result
+        return result
+
+    async def url(self) -> str:
+        result = self._page.url
+        import asyncio
+
+        if asyncio.iscoroutine(result):
+            return cast(str, await result)
+        if callable(result):
+            r = result()
+            if asyncio.iscoroutine(r):
+                return cast(str, await r)
+            return cast(str, r)
+        return cast(str, result)
+
+    async def wait_for_selector(self, selector: str, *, timeout: float | None = None) -> None:
+        fn = getattr(self._page, "wait_for_selector", None)
+        if fn is None:
+            return
+        import asyncio
+
+        opts: dict[str, Any] = {}
+        if timeout is not None:
+            opts["timeout"] = timeout
+        result = fn(selector, **opts)
+        if asyncio.iscoroutine(result):
+            await result
+
+
+def from_playwright_page(page: Any) -> PageDriver:
+    """Wrap a Playwright ``Page`` as a ``PageDriver``."""
+    return _PlaywrightDriver(page)
+
+
+def from_generic_page(page: Any) -> PageDriver:
+    """Wrap any evaluate/url-compatible object as a ``PageDriver``."""
+    return _GenericDriver(page)
+
+
+def to_driver(page: Any) -> PageDriver:
+    """Normalize a page-like object into a ``PageDriver``.
+
+    If it already satisfies ``PageDriver`` it is returned as-is;
+    otherwise it is wrapped with the generic adapter.
+    """
+    # A raw Playwright ``Page`` exposes ``url`` as a string property, whereas a
+    # ``PageDriver`` exposes it as an async method. Detect the Playwright page
+    # FIRST: a raw page also structurally satisfies the runtime-checkable
+    # PageDriver protocol, so the isinstance check below would otherwise return
+    # it unwrapped — and ``await page.url()`` would then fail on the string.
+    if hasattr(page, "url") and not callable(getattr(page, "url", None)):
+        return _PlaywrightDriver(page)
+    if isinstance(page, PageDriver):
+        return page
+    return _GenericDriver(page)

capsolver_core/browser/driver.py

@@ -0,0 +1,26 @@
+"""PageDriver — the browser abstraction handlers use to read the DOM.
+
+Mirrors the Node SDK's browser/driver.ts. Uses ``Protocol`` so any
+object with the right shape works without inheritance.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class PageDriver(Protocol):
+    """Minimal browser page interface."""
+
+    async def evaluate(self, script: str, arg: Any = None) -> Any:
+        """Run a JavaScript snippet in the page context and return its result."""
+        ...
+
+    async def url(self) -> str:
+        """The page's current URL."""
+        ...
+
+    async def wait_for_selector(self, selector: str, *, timeout: float | None = None) -> None:
+        """Optionally wait for a selector to appear."""
+        ...

capsolver_core/browser/inject/__init__.py

@@ -0,0 +1 @@
+"""Inject script package — JS snippets for in-page captcha detection/fill."""

capsolver_core/browser/inject/cloudflare.py

@@ -0,0 +1,67 @@
+"""In-page Cloudflare Turnstile scripts (ported from the Node SDK's cloudflare.inject.ts).
+
+Self-contained JS snippets — see recaptcha.py for the pattern.
+"""
+
+# ── Cheap presence check ──────────────────────────────────────────
+
+DETECT_CLOUDFLARE_JS = """
+() => {
+    // Match Cloudflare-specific markers only. A bare [data-sitekey] is NOT
+    // Cloudflare-exclusive (reCAPTCHA/hCaptcha use it too) and would cause a
+    // reCAPTCHA page to be mis-detected as Cloudflare.
+    return !!document.querySelector(
+        'input[name="cf-turnstile-response"], .cf-turnstile, iframe[src*="challenges.cloudflare.com"]'
+    );
+}
+"""
+
+# ── Extract info for Cloudflare Turnstile widgets on the page ─────
+
+GET_CLOUDFLARE_INFOS_JS = """
+() => {
+    // Only consider Cloudflare-specific containers — never a bare
+    // [data-sitekey], which would grab a reCAPTCHA/hCaptcha sitekey and
+    // build an invalid Turnstile task.
+    const widget =
+        document.querySelector('.cf-turnstile[data-sitekey]') ||
+        document.querySelector('.cf-turnstile');
+
+    let websiteKey = widget ? widget.getAttribute('data-sitekey') : null;
+    let action = widget ? widget.getAttribute('data-action') : null;
+    let cdata = widget ? widget.getAttribute('data-cdata') : null;
+
+    // Fall back to the widget iframe's query string.
+    if (!websiteKey) {
+        const iframe = document.querySelector('iframe[src*="challenges.cloudflare.com"]');
+        if (iframe && iframe.src) {
+            const params = new URL(iframe.src.replace('#', '?')).searchParams;
+            websiteKey = params.get('sitekey');
+            action = action || params.get('action');
+            cdata = cdata || params.get('cData');
+        }
+    }
+
+    // Identify a container for fill / autofill.
+    const input = document.querySelector('input[name="cf-turnstile-response"]');
+    const container = (input ? input.parentElement : widget) || null;
+    if (container && !container.id) container.id = 'cloudflare-container-' + Date.now();
+
+    if (!websiteKey) return [];
+    return [{ websiteKey, action, cdata, containerId: container ? container.id : null }];
+}
+"""
+
+# ── Write the token back into the hidden input ────────────────────
+
+FILL_CLOUDFLARE_JS = """
+(args) => {
+    const scope = args.containerId ? document.getElementById(args.containerId) : document;
+    const input =
+        (scope ? scope.querySelector('input[name="cf-turnstile-response"]') : null) ||
+        document.querySelector('input[name="cf-turnstile-response"]');
+    if (!input) return false;
+    input.value = args.token;
+    return true;
+}
+"""

capsolver_core/browser/inject/recaptcha.py

@@ -0,0 +1,162 @@
+"""In-page reCAPTCHA scripts (ported from the Node SDK's recaptcha.inject.ts).
+
+Each constant is a self-contained JavaScript snippet that runs inside the
+page via ``page.evaluate``. No imports, no module-scope references — only
+the page's ``window``/``document`` and their own arguments.
+"""
+
+# ── Cheap presence check ──────────────────────────────────────────
+
+DETECT_RECAPTCHA_JS = """
+() => {
+    const cfg = window.___grecaptcha_cfg;
+    return !!(cfg && cfg.clients && Object.keys(cfg.clients).length > 0);
+}
+"""
+
+# ── Extract a descriptor for every reCAPTCHA widget on the page ───
+
+GET_RECAPTCHA_INFOS_JS = """
+() => {
+    function getSaParam() {
+        const reCap = document.querySelector('iframe[title="reCAPTCHA"]');
+        const src = reCap ? reCap.getAttribute('src') : null;
+        if (!src) return null;
+        return new URL(src).searchParams.get('sa');
+    }
+
+    function getWidgetInfo(widget) {
+        const info = {
+            captchaType: 'reCaptcha',
+            version: 'v2',
+            sitekey: null,
+            action: null,
+            s: null,
+            callback: null,
+            enterprise: !!(window.grecaptcha && window.grecaptcha.enterprise),
+            containerId: null,
+            bindedButtonId: null,
+            invisible: false,
+        };
+
+        // Detect the v3 badge.
+        let isBadge = false;
+        badge: for (const f in widget) {
+            if (typeof widget[f] !== 'object') continue;
+            for (const g in widget[f]) {
+                if (widget[f][g] && widget[f][g].classList && widget[f][g].classList.contains('grecaptcha-badge')) {
+                    isBadge = true;
+                    break badge;
+                }
+            }
+        }
+        if (isBadge) {
+            info.version = 'v3';
+            info.captchaType = 'reCaptcha3';
+            for (const h in widget) {
+                const i = widget[h];
+                if (typeof i !== 'object') continue;
+                for (const j in i) {
+                    if (typeof i[j] !== 'string') continue;
+                    if (i[j] === 'fullscreen') {
+                        info.version = 'v2';
+                        info.captchaType = 'reCaptcha';
+                    }
+                }
+            }
+        }
+
+        // Find the container element id.
+        let candidate = null;
+        for (const k in widget) {
+            if (widget[k] && widget[k].nodeType) {
+                if (widget[k].id) {
+                    info.containerId = widget[k].id;
+                } else if (widget[k].dataset && widget[k].dataset.sitekey) {
+                    widget[k].id = 'recaptcha-container-' + Date.now();
+                    info.containerId = widget[k].id;
+                } else if (!candidate) {
+                    candidate = widget[k];
+                } else if (widget[k].isSameNode(candidate)) {
+                    widget[k].id = 'recaptcha-container-' + Date.now();
+                    info.containerId = widget[k].id;
+                    break;
+                }
+            }
+        }
+
+        // Find sitekey / action / s / callback / bind / size.
+        for (const k1 in widget) {
+            const obj = widget[k1];
+            if (typeof obj !== 'object') continue;
+            for (const k2 in obj) {
+                if (obj[k2] === null || typeof obj[k2] !== 'object') continue;
+                if (obj[k2].sitekey === undefined || obj[k2].action === undefined) continue;
+                for (const k3 in obj[k2]) {
+                    if (k3 === 'sitekey') info.sitekey = obj[k2][k3];
+                    if (k3 === 'action') info.action = obj[k2][k3];
+                    if (k3 === 's') info.s = obj[k2][k3];
+                    if (k3 === 'callback' || k3 === 'promise-callback') info.callback = obj[k2][k3];
+                    if (k3 === 'bind' && obj[k2][k3]) {
+                        const bind = obj[k2][k3];
+                        if (typeof bind === 'string') {
+                            info.bindedButtonId = bind;
+                        } else {
+                            if (bind.id === undefined) bind.id = 'recaptchaBindedElement' + widget.id;
+                            info.bindedButtonId = bind.id;
+                        }
+                    }
+                    if (k3 === 'size' && obj[k2][k3] === 'invisible') info.invisible = true;
+                }
+            }
+        }
+
+        // Stash a function callback under a global key so fill can invoke it.
+        if (typeof info.callback === 'function') {
+            const callbackKey = 'reCaptchaWidgetCallback' + widget.id;
+            window[callbackKey] = info.callback;
+            info.callback = callbackKey;
+        }
+
+        if (info.captchaType === 'reCaptcha') info.action = getSaParam();
+
+        return info;
+    }
+
+    const cfg = window.___grecaptcha_cfg;
+    if (!cfg || !cfg.clients) return [];
+
+    const infos = [];
+    for (const widgetId in cfg.clients) {
+        infos.push(getWidgetInfo(cfg.clients[widgetId]));
+    }
+    return infos;
+}
+"""
+
+# ── Write the token back into the response textarea and fire the callback ─
+
+FILL_RECAPTCHA_JS = """
+(args) => {
+    let textarea = null;
+    if (args.containerId) {
+        textarea = document.querySelector('#' + args.containerId + ' textarea[name=g-recaptcha-response]');
+    }
+    if (!textarea) {
+        textarea = document.querySelector('textarea[name=g-recaptcha-response]');
+    }
+    if (textarea) {
+        textarea.innerHTML = args.token;
+        textarea.value = args.token;
+    }
+
+    if (args.callback && typeof window[args.callback] === 'function') {
+        try {
+            window[args.callback](args.token);
+        } catch (e) {
+            /* callback threw — token is still set in the textarea */
+        }
+    }
+    return !!textarea;
+}
+"""