capmonster-client 0.1.0__py3-none-any.whl

capmonster/__init__.py

@@ -0,0 +1,79 @@
+"""CapMonster Cloud recognition API client."""
+
+from .client import DEFAULT_SOFT_ID, CapMonster
+from .errors import CAPMONSTER_ERRORS, CapMonsterError
+from .tasks import (
+    alibaba,
+    altcha,
+    amazon,
+    basilisk,
+    binance,
+    castle,
+    complex_image,
+    datadome,
+    friendly_captcha,
+    funcaptcha,
+    geetest,
+    hcaptcha,
+    hunt,
+    image_to_text,
+    imperva,
+    mtcaptcha,
+    prosopo,
+    recaptcha_v2,
+    recaptcha_v2_enterprise,
+    recaptcha_v3,
+    recaptcha_v3_enterprise,
+    temu,
+    tendi,
+    tspd,
+    turnstile,
+    yidun,
+)
+from .types import (
+    TASK_CLASSES,
+    TASK_TYPES,
+    CapMonsterBalance,
+    RawApiResponse,
+    TaskResult,
+    TaskStatus,
+)
+
+__all__ = [
+    "CAPMONSTER_ERRORS",
+    "DEFAULT_SOFT_ID",
+    "TASK_CLASSES",
+    "TASK_TYPES",
+    "CapMonster",
+    "CapMonsterBalance",
+    "CapMonsterError",
+    "RawApiResponse",
+    "TaskResult",
+    "TaskStatus",
+    "alibaba",
+    "altcha",
+    "amazon",
+    "basilisk",
+    "binance",
+    "castle",
+    "complex_image",
+    "datadome",
+    "friendly_captcha",
+    "funcaptcha",
+    "geetest",
+    "hcaptcha",
+    "hunt",
+    "image_to_text",
+    "imperva",
+    "mtcaptcha",
+    "prosopo",
+    "recaptcha_v2",
+    "recaptcha_v2_enterprise",
+    "recaptcha_v3",
+    "recaptcha_v3_enterprise",
+    "temu",
+    "tendi",
+    "tspd",
+    "turnstile",
+    "yidun",
+]

capmonster/client.py

@@ -0,0 +1,299 @@
+"""Client for the CapMonster Cloud recognition API."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Mapping
+from typing import Any
+
+import httpx
+
+from .errors import CapMonsterError, describe_error
+
+_DEFAULT_BASE_URL = "https://api.capmonster.cloud"
+_DEFAULT_TIMEOUT = 30.0
+
+# Developer software id sent as `softId` on createTask.
+#
+# TODO: CapMonster Cloud's developer program is pending approval, so no
+# softId has been issued yet. Leave this empty. When a numeric id is
+# assigned, set it here. Requests omit `softId` until this constant or the
+# client `soft_id` argument is a non-empty value.
+#
+# The createTask field name is `softId` (same name as the official client).
+# https://docs.capmonster.cloud/docs/api/methods/create-task/
+DEFAULT_SOFT_ID = ""
+
+
+class CapMonster:
+    """Client for the CapMonster Cloud recognition API.
+
+    Args:
+        client_key: CapMonster Cloud client key.
+        base_url: Custom API base URL (defaults to `https://api.capmonster.cloud`).
+        timeout: Request timeout in seconds (defaults to 30.0).
+        soft_id: Developer software id. Empty until the developer program assigns one.
+
+    Examples:
+        >>> from capmonster import CapMonster
+        >>> with CapMonster("your_client_key") as client:
+        ...     balance = client.get_balance()
+    """
+
+    def __init__(
+        self,
+        client_key: str,
+        *,
+        base_url: str = _DEFAULT_BASE_URL,
+        timeout: float = _DEFAULT_TIMEOUT,
+        soft_id: str | int | None = None,
+    ) -> None:
+        if not client_key or not client_key.strip():
+            raise CapMonsterError("Client key is required", 1, "MISSING_CLIENT_KEY")
+
+        self._client_key = client_key.strip()
+        self._soft_id: str | int = DEFAULT_SOFT_ID if soft_id is None else soft_id
+        self._http = httpx.Client(
+            base_url=base_url.rstrip("/"),
+            timeout=timeout,
+            headers={
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+        )
+
+    def close(self) -> None:
+        """Close the underlying HTTP client."""
+        self._http.close()
+
+    def __enter__(self) -> CapMonster:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def get_balance(self) -> dict[str, float]:
+        """Retrieve the available account balance.
+
+        Returns:
+            Dictionary with a ``balance`` amount.
+
+        Examples:
+            >>> with CapMonster("your_key") as client:
+            ...     balance = client.get_balance()
+            ...     print(balance["balance"])
+        """
+        response = self._post("/getBalance", {"clientKey": self._client_key})
+        return {"balance": float(response.get("balance", 0.0))}
+
+    def create_task(
+        self,
+        task: Mapping[str, Any],
+        *,
+        soft_id: str | int | None = None,
+        callback_url: str | None = None,
+    ) -> int:
+        """Submit a new captcha recognition task.
+
+        ``softId`` is included only when ``DEFAULT_SOFT_ID`` or ``soft_id`` is set.
+
+        Args:
+            task: Task dictionary (must include ``type``).
+            soft_id: Override the client software id for this call.
+            callback_url: Optional URL that receives the getTaskResult payload.
+
+        Returns:
+            The submitted numeric task ID.
+
+        Examples:
+            >>> with CapMonster("your_key") as client:
+            ...     task_id = client.create_task({
+            ...         "type": "TurnstileTask",
+            ...         "websiteURL": "https://example.com",
+            ...         "websiteKey": "0x4AAAAAAA...",
+            ...     })
+        """
+        payload: dict[str, Any] = {
+            "clientKey": self._client_key,
+            "task": dict(task),
+        }
+        chosen = self._soft_id if soft_id is None else soft_id
+        if has_soft_id(chosen):
+            payload["softId"] = format_soft_id(chosen)
+        if callback_url:
+            payload["callbackUrl"] = callback_url
+
+        response = self._post("/createTask", payload)
+        task_id = normalize_task_id(response.get("taskId"))
+        if task_id is None:
+            raise CapMonsterError(
+                "Response missing taskId",
+                response.get("errorId", 0),
+                response.get("errorCode"),
+                200,
+                response,
+            )
+        return task_id
+
+    def get_task_result(self, task_id: int | str) -> dict[str, Any]:
+        """Query the status and solution of a submitted task.
+
+        ``CAPTCHA_NOT_READY`` is returned as ``{"status": "processing"}``.
+
+        Args:
+            task_id: Task identifier returned by ``create_task``.
+
+        Returns:
+            Dictionary containing ``status`` and optional ``solution``.
+        """
+        normalized = normalize_task_id(task_id)
+        if normalized is None:
+            raise CapMonsterError(f"Invalid taskId: {task_id}", 1, "WRONG_CAPTCHA_ID")
+
+        try:
+            response = self._post(
+                "/getTaskResult",
+                {"clientKey": self._client_key, "taskId": normalized},
+            )
+        except CapMonsterError as err:
+            if err.error_code == "CAPTCHA_NOT_READY":
+                return {"status": "processing", "solution": {}}
+            raise
+
+        return {
+            "status": response.get("status", "processing"),
+            "solution": response.get("solution", {}),
+        }
+
+    def wait_for_result(
+        self,
+        task_id: int | str,
+        *,
+        timeout: float = 120.0,
+        interval: float = 3.0,
+    ) -> dict[str, Any]:
+        """Poll ``get_task_result`` until the solution is ready.
+
+        Args:
+            task_id: Task identifier.
+            timeout: Maximum wait time in seconds (defaults to 120.0).
+            interval: Delay between poll attempts in seconds (defaults to 3.0).
+
+        Returns:
+            The solution dictionary.
+
+        Raises:
+            CapMonsterError: If polling times out or the task fails.
+        """
+        start_time = time.monotonic()
+
+        while True:
+            res = self.get_task_result(task_id)
+            if res.get("status") == "ready" and res.get("solution"):
+                solution = res["solution"]
+                if isinstance(solution, dict):
+                    return solution
+                return {"value": solution}
+
+            if time.monotonic() - start_time >= timeout:
+                raise CapMonsterError(
+                    "Timed out waiting for captcha solution",
+                    0,
+                    "TIMEOUT",
+                )
+
+            time.sleep(interval)
+
+    def solve(
+        self,
+        task: Mapping[str, Any],
+        *,
+        timeout: float = 120.0,
+        interval: float = 3.0,
+        soft_id: str | int | None = None,
+        callback_url: str | None = None,
+    ) -> dict[str, Any]:
+        """Submit a task and wait for its solution.
+
+        Args:
+            task: Task dictionary.
+            timeout: Maximum wait time in seconds.
+            interval: Delay between poll attempts in seconds.
+            soft_id: Override the client software id for this call.
+            callback_url: Optional result callback URL.
+
+        Returns:
+            The solution dictionary.
+        """
+        task_id = self.create_task(task, soft_id=soft_id, callback_url=callback_url)
+        return self.wait_for_result(task_id, timeout=timeout, interval=interval)
+
+    def _post(self, path: str, json_data: Any) -> dict[str, Any]:
+        try:
+            res = self._http.post(path, json=json_data)
+        except httpx.HTTPError as err:
+            raise CapMonsterError(str(err), 0) from err
+
+        try:
+            data = res.json()
+        except ValueError:
+            data = None
+
+        if res.is_error:
+            error_id = data.get("errorId", 0) if isinstance(data, dict) else 0
+            error_code = data.get("errorCode") if isinstance(data, dict) else None
+            error_description = data.get("errorDescription") if isinstance(data, dict) else None
+            if isinstance(data, dict) and (error_description or error_code or error_id):
+                error_msg = describe_error(error_code, error_description, error_id)
+            else:
+                error_msg = res.text or f"HTTP {res.status_code}"
+            raise CapMonsterError(error_msg, error_id, error_code, res.status_code, data)
+
+        if not isinstance(data, dict):
+            raise CapMonsterError(
+                "Unexpected non-JSON response from CapMonster Cloud API",
+                0,
+                None,
+                res.status_code,
+                res.text,
+            )
+
+        if data.get("errorId", 0) != 0:
+            error_id = int(data.get("errorId", 0))
+            error_code = data.get("errorCode")
+            msg = describe_error(error_code, data.get("errorDescription"), error_id)
+            raise CapMonsterError(msg, error_id, error_code, res.status_code, data)
+
+        return data
+
+
+def has_soft_id(value: str | int | None) -> bool:
+    """True when a softId should be sent. Empty string and 0 are treated as unset."""
+    if value is None:
+        return False
+    if isinstance(value, str):
+        return value.strip() != ""
+    return value != 0
+
+
+def format_soft_id(value: str | int) -> str | int:
+    """CapMonster expects a numeric softId. Numeric strings are sent as integers."""
+    if isinstance(value, int):
+        return value
+    trimmed = value.strip()
+    if trimmed.isdigit():
+        return int(trimmed)
+    return trimmed
+
+
+def normalize_task_id(task_id: Any) -> int | None:
+    """Return a positive integer task id, or None when the value cannot be used."""
+    if task_id is None or task_id == "":
+        return None
+    try:
+        value = int(task_id)
+    except (TypeError, ValueError):
+        return None
+    if value <= 0:
+        return None
+    return value

capmonster/errors.py

@@ -0,0 +1,96 @@
+"""Error types for the CapMonster Cloud API client."""
+
+from __future__ import annotations
+
+from typing import Any
+
+# Documented codes: https://docs.capmonster.cloud/docs/api/api-errors/
+CAPMONSTER_ERRORS: dict[str, str] = {
+    "ERROR_KEY_DOES_NOT_EXIST": "API key not found or provided in an incorrect format",
+    "ERROR_PROXY_CREDENTIALS_INVALID_CHARACTER": (
+        "Proxy login or password contains an invalid character"
+    ),
+    "ERROR_ZERO_BALANCE": "Insufficient funds on the account to solve captchas",
+    "ERROR_TOO_BIG_CAPTCHA_FILESIZE": (
+        "The uploaded image exceeds the maximum allowed size of 50 KB"
+    ),
+    "ERROR_ZERO_CAPTCHA_FILESIZE": "The image size is too small (less than 100 bytes)",
+    "ERROR_NO_SUCH_CAPCHA_ID": "Captcha task id was not found",
+    "WRONG_CAPTCHA_ID": "Captcha task id is missing, expired, or invalid",
+    "ERROR_CAPTCHA_UNSOLVABLE": (
+        "The captcha could not be solved. Unsolved tasks are not charged"
+    ),
+    "CAPTCHA_NOT_READY": "The task is still being solved",
+    "ERROR_IP_NOT_ALLOWED": "Requests from this IP with the current key are denied",
+    "ERROR_IP_BANNED": "The IP address has been temporarily blocked due to invalid requests",
+    "ERROR_NO_SUCH_METHOD": "An incorrect task type was specified",
+    "ERROR_TOO_MUCH_REQUESTS": "The allowed request limit has been exceeded",
+    "ERROR_DOMAIN_NOT_ALLOWED": "Solving captchas from this domain is forbidden",
+    "ERROR_TOKEN_EXPIRED": "The provided token or challenge has expired",
+    "ERROR_RECAPTCHA_INVALID_SITEKEY": "An invalid websiteKey was provided",
+    "ERROR_RECAPTCHA_INVALID_DOMAIN": (
+        "The domain does not match the sitekey, or websiteURL is not a full http(s) URL"
+    ),
+    "ERROR_RECAPTCHA_TIMEOUT": "The captcha solving time has expired",
+    "ERROR_IP_BLOCKED": "Access from this IP is blocked due to a high number of failed requests",
+    "ERROR_PROXY_CONNECT_REFUSED": "The proxy server refused the connection",
+    "ERROR_PROXY_BANNED": "The specified proxy is blocked by the target website",
+    "ERROR_PROXY_MISSING": "Proxy parameters are missing or proxyType is incorrect",
+    "ERROR_PROXY_NOT_AUTHORISED": "Proxy login or password is incorrect",
+    "ERROR_PROXY_READ_TIMEOUT": "The response timed out while using the proxy",
+    "ERROR_TASK_NOT_SUPPORTED": "The specified task type is unsupported or invalid",
+    "ERROR_TASK_ABSENT": "The task object is missing or the JSON is invalid",
+    "ERROR_WRONG_USERAGENT": "An invalid User-Agent was provided",
+    "ERROR_SERVICE_NOT_AVAILABLE": "The service is temporarily unavailable",
+    "ERROR_INVALID_TASK": "The task is syntactically valid but contains invalid data",
+    "TIMEOUT": "Polling timed out before the captcha was solved",
+    "MISSING_CLIENT_KEY": "Client key is required",
+}
+
+
+class CapMonsterError(Exception):
+    """Exception raised for API errors or failed requests.
+
+    Args:
+        message: Human-readable error description.
+        error_id: Numeric error ID returned by CapMonster Cloud (0 is success).
+        error_code: String code (e.g. `ERROR_KEY_DOES_NOT_EXIST`).
+        status_code: HTTP status code or 0 for client/transport errors.
+        response: Raw response body, if available.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        error_id: int = 0,
+        error_code: str | None = None,
+        status_code: int = 0,
+        response: Any = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.error_id = error_id
+        self.error_code = error_code
+        self.status_code = status_code
+        self.response = response
+
+    def __repr__(self) -> str:
+        return (
+            f"CapMonsterError(message={self.message!r}, "
+            f"error_id={self.error_id}, error_code={self.error_code!r})"
+        )
+
+
+def describe_error(
+    error_code: str | None,
+    error_description: str | None,
+    error_id: int,
+) -> str:
+    """Prefer the API description, then the local catalog, then the raw code."""
+    if error_description:
+        return error_description
+    if error_code and error_code in CAPMONSTER_ERRORS:
+        return CAPMONSTER_ERRORS[error_code]
+    if error_code:
+        return error_code
+    return f"API error #{error_id}"

capmonster/tasks.py

@@ -0,0 +1,230 @@
+"""Task builders for documented CapMonster Cloud captcha types.
+
+Each helper sets `type` (and `class`, when the docs require `CustomTask`)
+and forwards the remaining API fields unchanged. Field names match the JSON
+documented at https://docs.capmonster.cloud/docs/captchas/.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def _task(task_type: str, fields: dict[str, Any], task_class: str | None = None) -> dict[str, Any]:
+    task: dict[str, Any] = {"type": task_type}
+    if task_class is not None:
+        task["class"] = task_class
+    task.update(fields)
+    return task
+
+
+def recaptcha_v2(website_url: str, website_key: str, **extra: Any) -> dict[str, Any]:
+    """reCAPTCHA v2 (`RecaptchaV2Task`)."""
+    return _task(
+        "RecaptchaV2Task",
+        {"websiteURL": website_url, "websiteKey": website_key, **extra},
+    )
+
+
+def recaptcha_v2_enterprise(website_url: str, website_key: str, **extra: Any) -> dict[str, Any]:
+    """reCAPTCHA v2 Enterprise (`RecaptchaV2EnterpriseTask`)."""
+    return _task(
+        "RecaptchaV2EnterpriseTask",
+        {"websiteURL": website_url, "websiteKey": website_key, **extra},
+    )
+
+
+def recaptcha_v3(website_url: str, website_key: str, **extra: Any) -> dict[str, Any]:
+    """reCAPTCHA v3 (`RecaptchaV3TaskProxyless`). Pass isEnterprise=True for v3 Enterprise."""
+    return _task(
+        "RecaptchaV3TaskProxyless",
+        {"websiteURL": website_url, "websiteKey": website_key, **extra},
+    )
+
+
+def recaptcha_v3_enterprise(website_url: str, website_key: str, **extra: Any) -> dict[str, Any]:
+    """reCAPTCHA v3 Enterprise (`RecaptchaV3EnterpriseTask`)."""
+    return _task(
+        "RecaptchaV3EnterpriseTask",
+        {"websiteURL": website_url, "websiteKey": website_key, **extra},
+    )
+
+
+def turnstile(website_url: str, website_key: str, **extra: Any) -> dict[str, Any]:
+    """Cloudflare Turnstile, Challenge, and Waiting Room (`TurnstileTask`)."""
+    return _task("TurnstileTask", {"websiteURL": website_url, "websiteKey": website_key, **extra})
+
+
+def geetest(website_url: str, gt: str, **extra: Any) -> dict[str, Any]:
+    """GeeTest v3 or v4 (`GeeTestTask`). Pass version and challenge via extra."""
+    return _task("GeeTestTask", {"websiteURL": website_url, "gt": gt, **extra})
+
+
+def image_to_text(body: str, **extra: Any) -> dict[str, Any]:
+    """ImageToTextTask. `body` is a single-line Base64 image."""
+    return _task("ImageToTextTask", {"body": body, **extra})
+
+
+def complex_image(class_name: str, **extra: Any) -> dict[str, Any]:
+    """ComplexImageTask. `class_name` is recaptcha, hcaptcha, funcaptcha, or recognition."""
+    return _task("ComplexImageTask", extra, class_name)
+
+
+def datadome(website_url: str, metadata: dict[str, Any], **extra: Any) -> dict[str, Any]:
+    """DataDome (`CustomTask` / `DataDome`). Requires your own proxy in extra."""
+    return _task(
+        "CustomTask",
+        {"websiteURL": website_url, "metadata": metadata, **extra},
+        "DataDome",
+    )
+
+
+def tendi(website_url: str, website_key: str, **extra: Any) -> dict[str, Any]:
+    """TenDI / Tencent captcha (`CustomTask` / `TenDI`).
+
+    CapMonster documents this captcha as TenDI, not Tenable.
+    """
+    return _task(
+        "CustomTask",
+        {"websiteURL": website_url, "websiteKey": website_key, **extra},
+        "TenDI",
+    )
+
+
+def amazon(website_url: str, website_key: str, **extra: Any) -> dict[str, Any]:
+    """Amazon / AWS WAF (`AmazonTask`)."""
+    return _task("AmazonTask", {"websiteURL": website_url, "websiteKey": website_key, **extra})
+
+
+def binance(website_url: str, website_key: str, validate_id: str, **extra: Any) -> dict[str, Any]:
+    """Binance captcha (`BinanceTask`)."""
+    return _task(
+        "BinanceTask",
+        {
+            "websiteURL": website_url,
+            "websiteKey": website_key,
+            "validateId": validate_id,
+            **extra,
+        },
+    )
+
+
+def funcaptcha(website_url: str, website_public_key: str, **extra: Any) -> dict[str, Any]:
+    """Arkose Labs FunCaptcha (`FunCaptchaTask`)."""
+    return _task(
+        "FunCaptchaTask",
+        {"websiteURL": website_url, "websitePublicKey": website_public_key, **extra},
+    )
+
+
+def hcaptcha(website_url: str, website_key: str, **extra: Any) -> dict[str, Any]:
+    """hCaptcha (`HCaptchaTask`)."""
+    return _task("HCaptchaTask", {"websiteURL": website_url, "websiteKey": website_key, **extra})
+
+
+def basilisk(website_url: str, website_key: str, **extra: Any) -> dict[str, Any]:
+    """Basilisk (`CustomTask` / `Basilisk`)."""
+    return _task(
+        "CustomTask",
+        {"websiteURL": website_url, "websiteKey": website_key, **extra},
+        "Basilisk",
+    )
+
+
+def imperva(website_url: str, metadata: dict[str, Any], **extra: Any) -> dict[str, Any]:
+    """Imperva / Incapsula (`CustomTask` / `Imperva`)."""
+    return _task(
+        "CustomTask",
+        {"websiteURL": website_url, "metadata": metadata, **extra},
+        "Imperva",
+    )
+
+
+def prosopo(website_url: str, website_key: str, **extra: Any) -> dict[str, Any]:
+    """Prosopo (`ProsopoTask`)."""
+    return _task("ProsopoTask", {"websiteURL": website_url, "websiteKey": website_key, **extra})
+
+
+def yidun(website_url: str, website_key: str, **extra: Any) -> dict[str, Any]:
+    """Yidun (`YidunTask`)."""
+    return _task("YidunTask", {"websiteURL": website_url, "websiteKey": website_key, **extra})
+
+
+def mtcaptcha(website_url: str, website_key: str, **extra: Any) -> dict[str, Any]:
+    """MTCaptcha (`MTCaptchaTask`)."""
+    return _task("MTCaptchaTask", {"websiteURL": website_url, "websiteKey": website_key, **extra})
+
+
+def altcha(
+    website_url: str,
+    website_key: str,
+    metadata: dict[str, Any],
+    **extra: Any,
+) -> dict[str, Any]:
+    """Altcha (`CustomTask` / `altcha`)."""
+    return _task(
+        "CustomTask",
+        {"websiteURL": website_url, "websiteKey": website_key, "metadata": metadata, **extra},
+        "altcha",
+    )
+
+
+def friendly_captcha(
+    website_url: str,
+    website_key: str,
+    metadata: dict[str, Any],
+    **extra: Any,
+) -> dict[str, Any]:
+    """Friendly Captcha (`CustomTask` / `friendly`)."""
+    return _task(
+        "CustomTask",
+        {"websiteURL": website_url, "websiteKey": website_key, "metadata": metadata, **extra},
+        "friendly",
+    )
+
+
+def temu(website_url: str, metadata: dict[str, Any], **extra: Any) -> dict[str, Any]:
+    """Temu (`CustomTask` / `Temu`)."""
+    return _task("CustomTask", {"websiteURL": website_url, "metadata": metadata, **extra}, "Temu")
+
+
+def castle(
+    website_url: str,
+    website_key: str,
+    metadata: dict[str, Any],
+    **extra: Any,
+) -> dict[str, Any]:
+    """Castle (`CustomTask` / `Castle`)."""
+    return _task(
+        "CustomTask",
+        {"websiteURL": website_url, "websiteKey": website_key, "metadata": metadata, **extra},
+        "Castle",
+    )
+
+
+def tspd(
+    website_url: str,
+    user_agent: str,
+    metadata: dict[str, Any],
+    **extra: Any,
+) -> dict[str, Any]:
+    """TSPD (`CustomTask` / `tspd`)."""
+    return _task(
+        "CustomTask",
+        {"websiteURL": website_url, "userAgent": user_agent, "metadata": metadata, **extra},
+        "tspd",
+    )
+
+
+def hunt(website_url: str, metadata: dict[str, Any], **extra: Any) -> dict[str, Any]:
+    """Hunt CAPTCHA (`CustomTask` / `HUNT`)."""
+    return _task("CustomTask", {"websiteURL": website_url, "metadata": metadata, **extra}, "HUNT")
+
+
+def alibaba(website_url: str, metadata: dict[str, Any], **extra: Any) -> dict[str, Any]:
+    """Alibaba captcha (`CustomTask` / `alibaba`)."""
+    return _task(
+        "CustomTask",
+        {"websiteURL": website_url, "metadata": metadata, **extra},
+        "alibaba",
+    )

capmonster/types.py

@@ -0,0 +1,76 @@
+"""Type definitions for the CapMonster Cloud API client."""
+
+from __future__ import annotations
+
+from typing import Any, Literal, TypedDict
+
+ProxyType = Literal["http", "https", "socks4", "socks5"]
+TaskStatus = Literal["processing", "ready"]
+
+# Documented `type` values. Custom captchas also set `class` (see TASK_CLASSES).
+TASK_TYPES: dict[str, str] = {
+    "recaptcha_v2": "RecaptchaV2Task",
+    "recaptcha_v2_proxyless": "RecaptchaV2TaskProxyless",
+    "no_captcha": "NoCaptchaTask",
+    "no_captcha_proxyless": "NoCaptchaTaskProxyless",
+    "recaptcha_v2_enterprise": "RecaptchaV2EnterpriseTask",
+    "recaptcha_v3": "RecaptchaV3TaskProxyless",
+    "recaptcha_v3_enterprise": "RecaptchaV3EnterpriseTask",
+    "turnstile": "TurnstileTask",
+    "geetest": "GeeTestTask",
+    "image_to_text": "ImageToTextTask",
+    "complex_image": "ComplexImageTask",
+    "custom": "CustomTask",
+    "funcaptcha": "FunCaptchaTask",
+    "hcaptcha": "HCaptchaTask",
+    "hcaptcha_proxyless": "HCaptchaTaskProxyless",
+    "amazon": "AmazonTask",
+    "binance": "BinanceTask",
+    "prosopo": "ProsopoTask",
+    "yidun": "YidunTask",
+    "mtcaptcha": "MTCaptchaTask",
+}
+
+# `class` values for CustomTask and ComplexImageTask.
+TASK_CLASSES: dict[str, str] = {
+    "datadome": "DataDome",
+    "tendi": "TenDI",
+    "basilisk": "Basilisk",
+    "imperva": "Imperva",
+    "altcha": "altcha",
+    "friendly": "friendly",
+    "temu": "Temu",
+    "castle": "Castle",
+    "tspd": "tspd",
+    "hunt": "HUNT",
+    "alibaba": "alibaba",
+    "complex_recaptcha": "recaptcha",
+    "complex_hcaptcha": "hcaptcha",
+    "complex_funcaptcha": "funcaptcha",
+    "complex_recognition": "recognition",
+}
+
+
+class CapMonsterBalance(TypedDict):
+    """Account balance details."""
+
+    balance: float
+
+
+class TaskResult(TypedDict, total=False):
+    """Result returned by getTaskResult."""
+
+    status: TaskStatus
+    solution: dict[str, Any]
+
+
+class RawApiResponse(TypedDict, total=False):
+    """Envelope returned by CapMonster Cloud endpoints."""
+
+    errorId: int
+    errorCode: str | None
+    errorDescription: str | None
+    taskId: int | str
+    status: TaskStatus
+    solution: Any
+    balance: float

capmonster_client-0.1.0.dist-info/METADATA

@@ -0,0 +1,211 @@
+Metadata-Version: 2.5
+Name: capmonster-client
+Version: 0.1.0
+Summary: Python client for the CapMonster Cloud captcha recognition API
+Project-URL: Repository, https://github.com/TysikGG/api-kit
+Project-URL: Documentation, https://docs.capmonster.cloud
+License-Expression: ISC
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Description-Content-Type: text/markdown
+
+# capmonster-client
+
+[![PyPI version](https://img.shields.io/pypi/v/capmonster-client.svg)](https://pypi.org/project/capmonster-client/)
+[![Python versions](https://img.shields.io/pypi/pyversions/capmonster-client.svg)](https://pypi.org/project/capmonster-client/)
+[![License: ISC](https://img.shields.io/badge/License-ISC-blue.svg)](https://opensource.org/licenses/ISC)
+
+Typed Python client for the [CapMonster Cloud API](https://docs.capmonster.cloud). Supports reCAPTCHA v2/v3/Enterprise, Cloudflare Turnstile (including Challenge and Waiting Room), GeeTest, ImageToText, ComplexImage, DataDome, Amazon AWS WAF, TenDI (Tencent), Binance, and the other task types documented by CapMonster Cloud. Built on [HTTPX](https://www.python-httpx.org).
+
+Official API documentation: <https://docs.capmonster.cloud>
+
+The import package is `capmonster`. The distribution name is `capmonster-client` so it does not collide with other projects on PyPI.
+
+---
+
+## Features
+
+- 🧩 **Documented task types** — Helpers for reCAPTCHA v2/v3/Enterprise, Turnstile, GeeTest, ImageToText, ComplexImage, DataDome, Amazon WAF, TenDI, Binance, FunCaptcha, hCaptcha, Basilisk, Imperva, Prosopo, Yidun, MTCaptcha, Altcha, Friendly Captcha, Temu, Castle, TSPD, Hunt, and Alibaba.
+- ⏳ **Automated polling** — `wait_for_result()` and `solve()` poll until the solution is ready. `CAPTCHA_NOT_READY` stays in the processing state.
+- 💰 **Balance tracking** — `get_balance()` reads the account balance and does not spend credit.
+- 🏷️ **Developer id** — `softId` is omitted until you set it. CapMonster's developer program is still pending, so `DEFAULT_SOFT_ID` is empty.
+- 🐍 **Modern Python** — Type annotations, context manager support (`with CapMonster(...) as client:`).
+- 🚨 **Structured errors** — `CapMonsterError` carries `error_id` and `error_code` for every documented API error.
+
+---
+
+## Installation
+
+```bash
+pip install capmonster-client
+```
+
+Requires Python 3.10 or higher.
+
+---
+
+## Quick Start (Safe Check)
+
+The quick check only inspects your account balance. It does not submit tasks or spend credits.
+
+```python
+import os
+from capmonster import CapMonster
+
+with CapMonster(os.environ["CAPMONSTER_API_KEY"]) as client:
+    balance = client.get_balance()
+    print(f"Balance: {balance['balance']}")
+```
+
+---
+
+## Usage Guide
+
+### 1. High-Level Solve (Recommended)
+
+`client.solve()` submits the task and waits until the solution is ready:
+
+```python
+import os
+from capmonster import CapMonster, turnstile
+
+with CapMonster(os.environ["CAPMONSTER_API_KEY"]) as client:
+    solution = client.solve(turnstile("https://example.com/", "0x4AAAAAAA..."))
+    print("Turnstile token:", solution["token"])
+```
+
+### 2. Solving reCAPTCHA v2
+
+```python
+from capmonster import CapMonster, recaptcha_v2
+
+with CapMonster(os.environ["CAPMONSTER_API_KEY"]) as client:
+    solution = client.solve(recaptcha_v2(
+        "https://lessons.zennolab.com/captchas/recaptcha/v2_simple.php?level=high",
+        "6Lcg7CMUAAAAANphynKgn9YAgA4tQ2KI_iqRyTwd",
+    ))
+    print(solution["gRecaptchaResponse"])
+```
+
+### 3. Manual Task Lifecycle
+
+```python
+from capmonster import CapMonster, turnstile
+
+with CapMonster(os.environ["CAPMONSTER_API_KEY"]) as client:
+    task_id = client.create_task(turnstile("https://example.com/", "0x4AAAAAAA..."))
+    result = client.get_task_result(task_id)
+    if result["status"] == "ready":
+        print("Solution:", result["solution"])
+    else:
+        print("Task is still processing...")
+```
+
+You can also pass a raw `dict`. `type` is required. Custom captchas (DataDome, TenDI, and the others listed below) also require `class`.
+
+### 4. Developer software id
+
+`create_task` sends `softId` only when it is set:
+
+```python
+from capmonster import DEFAULT_SOFT_ID, CapMonster
+
+print(DEFAULT_SOFT_ID)  # ""
+
+with CapMonster(os.environ["CAPMONSTER_API_KEY"], soft_id=12345) as client:
+    ...
+```
+
+TODO: replace `DEFAULT_SOFT_ID` in `src/capmonster/client.py` once CapMonster assigns a numeric id.
+
+---
+
+## Task Types
+
+| Captcha | `type` | `class` | Helper |
+| :--- | :--- | :--- | :--- |
+| reCAPTCHA v2 | `RecaptchaV2Task` | | `recaptcha_v2` |
+| reCAPTCHA v2 Enterprise | `RecaptchaV2EnterpriseTask` | | `recaptcha_v2_enterprise` |
+| reCAPTCHA v3 | `RecaptchaV3TaskProxyless` | | `recaptcha_v3` |
+| reCAPTCHA v3 Enterprise | `RecaptchaV3EnterpriseTask` | | `recaptcha_v3_enterprise` |
+| Cloudflare Turnstile / Challenge / Waiting Room | `TurnstileTask` | | `turnstile` |
+| GeeTest v3 / v4 | `GeeTestTask` | | `geetest` |
+| ImageToText | `ImageToTextTask` | | `image_to_text` |
+| ComplexImage (click, grid, recognition) | `ComplexImageTask` | `recaptcha`, `hcaptcha`, `funcaptcha`, `recognition` | `complex_image` |
+| DataDome | `CustomTask` | `DataDome` | `datadome` |
+| TenDI (Tencent) | `CustomTask` | `TenDI` | `tendi` |
+| Amazon AWS WAF | `AmazonTask` | | `amazon` |
+| Binance | `BinanceTask` | | `binance` |
+| FunCaptcha | `FunCaptchaTask` | | `funcaptcha` |
+| hCaptcha | `HCaptchaTask` | | `hcaptcha` |
+| Basilisk | `CustomTask` | `Basilisk` | `basilisk` |
+| Imperva (Incapsula) | `CustomTask` | `Imperva` | `imperva` |
+| Prosopo | `ProsopoTask` | | `prosopo` |
+| Yidun | `YidunTask` | | `yidun` |
+| MTCaptcha | `MTCaptchaTask` | | `mtcaptcha` |
+| Altcha | `CustomTask` | `altcha` | `altcha` |
+| Friendly Captcha | `CustomTask` | `friendly` | `friendly_captcha` |
+| Temu | `CustomTask` | `Temu` | `temu` |
+| Castle | `CustomTask` | `Castle` | `castle` |
+| TSPD | `CustomTask` | `tspd` | `tspd` |
+| Hunt | `CustomTask` | `HUNT` | `hunt` |
+| Alibaba | `CustomTask` | `alibaba` | `alibaba` |
+
+Legacy aliases `NoCaptchaTask`, `NoCaptchaTaskProxyless`, `RecaptchaV2TaskProxyless`, and `HCaptchaTaskProxyless` are accepted on the `type` field. Current docs use `RecaptchaV2Task` with proxy fields omitted when CapMonster's own proxies are enough.
+
+TenDI is the Tencent captcha documented by CapMonster. It is not a Tenable product.
+
+Parameter reference: <https://docs.capmonster.cloud/docs/captchas/>
+
+---
+
+## Error Handling
+
+When the API returns an error, the client raises `CapMonsterError`:
+
+```python
+from capmonster import CapMonster, CapMonsterError
+
+try:
+    with CapMonster("invalid_key") as client:
+        client.get_balance()
+except CapMonsterError as err:
+    print(f"CapMonster error #{err.error_id} [{err.error_code}]: {err.message}")
+```
+
+Common error codes (full list: <https://docs.capmonster.cloud/docs/api/api-errors/>):
+
+- `ERROR_KEY_DOES_NOT_EXIST` — Account key does not exist or is malformed.
+- `ERROR_ZERO_BALANCE` — Account has no funds. Returned by `create_task`, not by `get_balance`.
+- `ERROR_CAPTCHA_UNSOLVABLE` — The captcha could not be solved. Unsolved tasks are not charged.
+- `CAPTCHA_NOT_READY` — Still solving. `get_task_result` maps this to `status: "processing"`.
+- `ERROR_TASK_NOT_SUPPORTED` / `ERROR_NO_SUCH_METHOD` — Unknown `type`.
+- `ERROR_INVALID_TASK` / `ERROR_TASK_ABSENT` — Task payload is missing or invalid.
+- `ERROR_TOO_MUCH_REQUESTS` — Poll `get_task_result` no more than once every 2 seconds. The default interval is 3 seconds.
+- `TIMEOUT` — `wait_for_result()` exceeded the configured timeout.
+
+`CAPMONSTER_ERRORS` maps every documented code to a short description. The API `errorDescription` is used when CapMonster sends one.
+
+---
+
+## Live Tests
+
+Unit tests mock HTTP and always run. The live suite calls the real API and runs only when `CAPMONSTER_API_KEY` is set. It checks balance, an invalid key, and `ERROR_ZERO_BALANCE` on `create_task`.
+
+`create_task` is sent only when the account balance is exactly `0`. A funded key skips that assertion so the suite does not spend credit.
+
+```bash
+cd capmonster/python
+uv sync
+uv run pytest -m "not live"
+CAPMONSTER_API_KEY=your_key uv run pytest -m live
+```
+
+Do not commit API keys.
+
+---
+
+## License
+
+[ISC](LICENSE) © api-kit contributors

capmonster_client-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+capmonster/__init__.py,sha256=srbljr3wN9rR6cTQzvH6uGbuOj6GntzMiHVdtgmxyZI,1373
+capmonster/client.py,sha256=2Jnynz_BaANaHPZSPN8MzzJ0WWR4D1EptgsYfPcvAoY,9968
+capmonster/errors.py,sha256=1I7sycm5oDCjKl8DJDe49A-ITEEj_tJBlNdYufl3vRk,4274
+capmonster/tasks.py,sha256=uM_b241tD1xEoZ8j_futb_bERhmjnLIryYedrSNGvg0,7665
+capmonster/types.py,sha256=2SipfWVTmUfwdfO8oksEoyDR9qL0lov2gihEmviFc1Y,2163
+capmonster_client-0.1.0.dist-info/METADATA,sha256=uypg5KE1UyAgiBZLnZQIGO_jjwY2Ahof0P6fWbVfPlc,8256
+capmonster_client-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+capmonster_client-0.1.0.dist-info/licenses/LICENSE,sha256=8S0uYmn_aeljwFudfBoV91HcIo79yab9s0yhMVsOHJ0,751
+capmonster_client-0.1.0.dist-info/RECORD,,

capmonster_client-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any

capmonster_client-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 api-kit contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.