Upbraded SDK

Author: dariyaanis

.github/workflows/tests.yml

@@ -0,0 +1,30 @@
+name: Tests
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with dev dependencies
+        run: python -m pip install -e ".[dev]"
+
+      - name: Run tests
+        run: python -m pytest tests/ -v
+
+      - name: Verify package builds
+        run: |
+          python -m pip install build
+          python -m build --sdist --wheel

README.md

@@ -1,23 +1,28 @@
 # Captcha Solver Python SDK
 ![python-examples-banner](assets/repo-banner-python.png)
 
-Official Python SDK for the Captcha Solver API. Solve reCAPTCHA v2, reCAPTCHA v3, Cloudflare Turnstile, GeeTest, and image captchas with a single method call.
+Official Python SDK for the Captcha Solver API. Solve reCAPTCHA v2/v3, Cloudflare Turnstile, GeeTest, Yandex SmartCaptcha, Tencent, and image/click captchas with a single method call -- sync or async.
 
 ## Table of Contents
 
 - [Installation](#installation)
+- [Configuration](#configuration)
 - [Quick Start](#quick-start)
 - [Supported CAPTCHA Types](#supported-captcha-types)
 - [Usage Examples](#usage-examples)
-  - [reCAPTCHA v2](#recaptcha-v2)
+  - [reCAPTCHA v2 with proxy](#recaptcha-v2-with-proxy)
   - [reCAPTCHA v2 Enterprise](#recaptcha-v2-enterprise)
   - [reCAPTCHA v3](#recaptcha-v3)
   - [Cloudflare Turnstile](#cloudflare-turnstile)
   - [Image to Text](#image-to-text)
   - [GeeTest v3](#geetest-v3)
   - [GeeTest v4](#geetest-v4)
+  - [Yandex SmartCaptcha](#yandex-smartcaptcha)
+  - [Coordinates (click captcha)](#coordinates-click-captcha)
+  - [Tencent](#tencent)
   - [Check Balance](#check-balance)
-  - [Custom Timeout](#custom-timeout-and-polling)
+  - [Custom Timeout and Polling](#custom-timeout-and-polling)
+  - [Async Client](#async-client)
   - [Error Handling](#error-handling)
 - [Requirements](#requirements)
 - [API Documentation](#api-documentation)
@@ -30,13 +35,18 @@ Official Python SDK for the Captcha Solver API. Solve reCAPTCHA v2, reCAPTCHA v3
 pip install git+https://github.com/captcha-solver-api/python-sdk.git
 ```
 ## Configuration
-Set your API key as an environment variable.
+The client always takes the API key as an explicit argument -- it does not read
+environment variables on its own. Read `CAPTCHA_API_KEY` yourself and pass it in:
 ```bash
 export CAPTCHA_API_KEY=your_api_key
 ```
-Or pass it directly to the client.
 ```python
+import os
 from captcha_sdk import CaptchaClient
+client = CaptchaClient(os.getenv("CAPTCHA_API_KEY"))
+```
+Or just pass the key directly, without an environment variable:
+```python
 client = CaptchaClient("your_api_key")
 ```
 ## Quick Start
@@ -62,6 +72,9 @@ print(result["gRecaptchaResponse"])
 | GeeTest v3 | ✅ | ✅ |
 | GeeTest v4 | ✅ | ✅ |
 | Image to Text | ✅ | ❌ |
+| Yandex SmartCaptcha | ✅ | ✅ |
+| Coordinates (click captcha) | ✅ | ❌ |
+| Tencent | ✅ | ✅ |
 ## Usage Examples
 ### reCAPTCHA v2 with proxy
 ```python
@@ -165,6 +178,49 @@ task = GeeTestTaskProxyless(
 result = client.solve(task)
 print(result["captcha_output"])
 ```
+### Yandex SmartCaptcha
+```python
+from captcha_sdk import CaptchaClient
+from captcha_sdk.tasks import YandexSmartCaptchaTaskProxyless
+client = CaptchaClient("your_api_key")
+task = YandexSmartCaptchaTaskProxyless(
+    websiteURL="https://example.com/login",
+    websiteKey="Y5Lh0ti..."
+)
+result = client.solve(task)
+print(result["token"])
+```
+Use `YandexSmartCaptchaTask` instead for the with-proxy variant (same extra `proxyType`/`proxyAddress`/`proxyPort`/`proxyLogin`/`proxyPassword` fields as `RecaptchaV2Task`).
+
+To solve Yandex SmartCaptcha's image challenge instead of the token challenge, use `CoordinatesTask` with `imgType="smart_captcha"` or `imgType="pazl_smart_captcha"` -- see [examples/sync/yandex_smartcaptcha_image.py](examples/sync/yandex_smartcaptcha_image.py) (or [examples/async](examples/async/yandex_smartcaptcha_image.py) for the async version).
+
+### Coordinates (click captcha)
+```python
+from captcha_sdk import CaptchaClient
+from captcha_sdk.tasks import CoordinatesTask
+import base64
+with open("captcha.png", "rb") as f:
+    image_base64 = base64.b64encode(f.read()).decode("utf-8")
+client = CaptchaClient("your_api_key")
+task = CoordinatesTask(
+    body=image_base64,
+    comment="click on the green apple"
+)
+result = client.solve(task)
+print(result["coordinates"])  # [{"x": 358, "y": 268}, ...]
+```
+### Tencent
+```python
+from captcha_sdk import CaptchaClient
+from captcha_sdk.tasks import TencentTaskProxyless
+client = CaptchaClient("your_api_key")
+task = TencentTaskProxyless(
+    websiteURL="https://example.com/login",
+    appId="190014885"
+)
+result = client.solve(task)
+print(result["ticket"])
+```
 ### Check balance
 ```python
 from captcha_sdk import CaptchaClient
@@ -180,12 +236,63 @@ client = CaptchaClient(
     polling_interval=5
 )
 ```
+A single `solve()` call can also override the client's default timeout, which is handy for
+captcha types that reliably take longer to solve (e.g. classic reCAPTCHA v2) without changing
+it for every other call:
+```python
+result = client.solve(task, timeout=300)
+```
+### Async client
+`AsyncCaptchaClient` mirrors `CaptchaClient` method-for-method (`create_task`, `get_task_result`,
+`get_balance`, `solve`, same constructor options), just `await`ed and built on `httpx` instead of
+`requests`:
+```python
+import asyncio
+from captcha_sdk import AsyncCaptchaClient
+from captcha_sdk.tasks import RecaptchaV2TaskProxyless
+
+async def main():
+    client = AsyncCaptchaClient("your_api_key")
+    task = RecaptchaV2TaskProxyless(
+        websiteURL="https://example.com/login",
+        websiteKey="6Le-xxxxxxxxx"
+    )
+    result = await client.solve(task)
+    print(result["gRecaptchaResponse"])
+
+asyncio.run(main())
+```
+See [examples/async](examples/async) for more.
+
+#### Solving multiple captchas in parallel
+This is the main reason to reach for the async client -- run several `solve()` calls
+concurrently instead of waiting for each one in turn:
+```python
+import asyncio
+from captcha_sdk import AsyncCaptchaClient
+from captcha_sdk.tasks import RecaptchaV2TaskProxyless, TurnstileTaskProxyless
+
+async def solve_multiple():
+    client = AsyncCaptchaClient("your_api_key")
+
+    task1 = client.solve(RecaptchaV2TaskProxyless(websiteURL="https://site1.com", websiteKey="key1"))
+    task2 = client.solve(TurnstileTaskProxyless(websiteURL="https://site2.com", websiteKey="key2"))
+
+    results = await asyncio.gather(task1, task2, return_exceptions=True)
+    return results
+
+results = asyncio.run(solve_multiple())
+```
+This completes in roughly the time of the slowest single captcha, not the sum of all of them.
+
 ### Error handling
 ```python
-from captcha_sdk import CaptchaClient, ApiError, TimeoutError, NetworkError
+from captcha_sdk import CaptchaClient, ApiError, TimeoutError, NetworkError, ValidationError
 client = CaptchaClient("your_api_key")
 try:
     result = client.solve(task)
+except ValidationError as e:
+    print(f"Invalid argument: {e}")
 except ApiError as e:
     print(f"API error: {e.error_code} {e.error_description}")
 except TimeoutError:

captcha_sdk/__init__.py

@@ -14,19 +14,23 @@
 """
 
 from .client import CaptchaClient
+from .async_client import AsyncCaptchaClient
 from .exceptions import (
     CaptchaError,
     ApiError,
     NetworkError,
     TimeoutError,
+    ValidationError,
 )
 
-__version__ = "1.0.0"
+__version__ = "1.1.0"
 
 __all__ = [
     "CaptchaClient",
+    "AsyncCaptchaClient",
     "CaptchaError",
     "ApiError",
     "NetworkError",
     "TimeoutError",
+    "ValidationError",
 ]

captcha_sdk/async_client.py

@@ -0,0 +1,129 @@
+"""
+Async counterpart of captcha_sdk.client.CaptchaClient -- same endpoints
+(createTask / getTaskResult / getBalance), same method names/arguments,
+`await`ed. Requires httpx.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import Any, Dict, Optional
+
+import httpx
+
+from .exceptions import (
+    ApiError,
+    NetworkError,
+    TimeoutError,
+    ValidationError,
+)
+
+
+class AsyncCaptchaClient:
+    """
+    Async client for interacting with the Captcha Solver API.
+
+    Example:
+        client = AsyncCaptchaClient("YOUR_API_KEY")
+        result = await client.solve(task)
+    """
+
+    def __init__(
+        self,
+        client_key: str,
+        base_url: str = "https://api.captcha-solver.com",
+        timeout: int = 120,
+        polling_interval: int = 3,
+    ) -> None:
+        if not client_key:
+            raise ValidationError("client_key is required")
+
+        self.client_key = client_key
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self.polling_interval = polling_interval
+
+    async def _request(
+        self,
+        endpoint: str,
+        payload: Dict[str, Any],
+    ) -> Dict[str, Any]:
+        url = f"{self.base_url}/{endpoint.lstrip('/')}"
+
+        try:
+            async with httpx.AsyncClient(follow_redirects=True) as client:
+                response = await client.post(
+                    url,
+                    json=payload,
+                    timeout=30,
+                    headers={"Content-Type": "application/json", "Accept": "application/json"},
+                )
+                response.raise_for_status()
+        except httpx.TimeoutException as exc:
+            raise TimeoutError("Request timed out.") from exc
+        except httpx.HTTPError as exc:
+            raise NetworkError(str(exc)) from exc
+
+        try:
+            data = response.json()
+        except ValueError as exc:
+            raise NetworkError(f"Non-JSON response from API: {response.text[:200]!r}") from exc
+
+        return data
+
+    def _ensure_success(self, data: Dict[str, Any]) -> None:
+        if data.get("errorId", 0) != 0:
+            raise ApiError(
+                data.get("errorCode", "UNKNOWN_ERROR"),
+                data.get("errorDescription", "Unknown API error."),
+            )
+
+    async def create_task(self, task: Any, language_pool: Optional[str] = None) -> int:
+        payload: Dict[str, Any] = {
+            "clientKey": self.client_key,
+            "task": task.to_dict(),
+        }
+        if language_pool:
+            payload["languagePool"] = language_pool
+
+        data = await self._request("createTask", payload)
+        self._ensure_success(data)
+        return data["taskId"]
+
+    async def get_task_result(self, task_id: int) -> Dict[str, Any]:
+        payload = {
+            "clientKey": self.client_key,
+            "taskId": task_id,
+        }
+        data = await self._request("getTaskResult", payload)
+        self._ensure_success(data)
+        return data
+
+    async def get_balance(self) -> float:
+        payload = {"clientKey": self.client_key}
+        data = await self._request("getBalance", payload)
+        self._ensure_success(data)
+        return data["balance"]
+
+    async def solve(
+        self,
+        task: Any,
+        language_pool: Optional[str] = None,
+        timeout: Optional[int] = None,
+    ) -> Dict[str, Any]:
+        """See captcha_sdk.client.CaptchaClient.solve -- same semantics, awaited."""
+
+        task_id = await self.create_task(task, language_pool=language_pool)
+
+        deadline = time.time() + (timeout if timeout is not None else self.timeout)
+
+        while time.time() < deadline:
+            result = await self.get_task_result(task_id)
+
+            if result.get("status") == "ready":
+                return result["solution"]
+
+            await asyncio.sleep(self.polling_interval)
+
+        raise TimeoutError("Task solving timed out.")