capbypass-sdk 1.0.0__tar.gz

capbypass_sdk-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CapBypass Development
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

capbypass_sdk-1.0.0/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: capbypass-sdk
+Version: 1.0.0
+Summary: Official Python SDK for CapBypass CAPTCHA solving API
+Author-email: CapBypass Development <dev@capbypass.dev>
+License: MIT
+Project-URL: Homepage, https://capbypass.dev
+Project-URL: Documentation, https://capbypass.dev/docs/sdks/python
+Project-URL: Repository, https://github.com/CapBypass-Development/capbypass-sdk-python
+Project-URL: Bug Tracker, https://github.com/CapBypass-Development/capbypass-sdk-python/issues
+Keywords: captcha,recaptcha,aws-waf,automation,solver
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.11.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: types-requests>=2.31.0; extra == "dev"
+Dynamic: license-file
+
+# CapBypass Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/capbypass-sdk.svg)](https://pypi.org/project/capbypass-sdk/)
+[![Python versions](https://img.shields.io/pypi/pyversions/capbypass-sdk.svg)](https://pypi.org/project/capbypass-sdk/)
+[![Downloads](https://pepy.tech/badge/capbypass-sdk)](https://pepy.tech/project/capbypass-sdk)
+[![GitHub stars](https://img.shields.io/github/stars/CapBypass-Development/capbypass-sdk-python.svg)](https://github.com/CapBypass-Development/capbypass-sdk-python)
+
+Official Python SDK for CapBypass CAPTCHA solving API.
+
+## Features
+
+- ✨ Simple `solve()` method with auto-polling
+- 🎯 Advanced `createTask()` + `getTaskResult()` for granular control
+- 💰 `getBalance()` to check account balance
+- 🔄 Automatic retry logic for network failures
+- 🛡️ Comprehensive error handling
+- 📝 Type hints for better IDE support
+- 🧪 100% test coverage
+
+## Supported CAPTCHA Types
+
+- reCAPTCHA v2 (normal & invisible)
+- reCAPTCHA v3
+- reCAPTCHA v3 Enterprise
+- AWS WAF CAPTCHA
+
+## Installation
+
+```bash
+pip install capbypass-sdk
+```
+
+## Quick Start
+
+```python
+from capbypass import CapBypass
+
+# Initialize client
+client = CapBypass(api_key="your-api-key")
+# Or use environment variable: export CAPBYPASS_API_KEY="your-key"
+
+# Solve CAPTCHA (auto-polling)
+solution = client.solve({
+    "type": "ReCaptchaV2TaskProxyLess",
+    "websiteURL": "https://example.com",
+    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
+})
+
+print(solution["gRecaptchaResponse"])
+```
+
+## Advanced Usage
+
+### Granular Control
+
+```python
+# Create task
+task_id = client.createTask({
+    "type": "ReCaptchaV2TaskProxyLess",
+    "websiteURL": "https://example.com",
+    "websiteKey": "site-key"
+})
+
+# Poll for result
+import time
+while True:
+    result = client.getTaskResult(task_id)
+    if result["status"] == "ready":
+        print(result["solution"])
+        break
+    time.sleep(5)
+```
+
+### Check Balance
+
+```python
+balance = client.getBalance()
+print(f"Balance: ${balance:.4f}")
+```
+
+### Error Handling
+
+```python
+from capbypass import CapBypass
+from capbypass.errors import (
+    AuthenticationError,
+    InsufficientBalanceError,
+    TimeoutError,
+)
+
+try:
+    solution = client.solve(task)
+except AuthenticationError:
+    print("Invalid API key")
+except InsufficientBalanceError:
+    print("Insufficient balance")
+except TimeoutError:
+    print("Task timed out")
+```
+
+## Documentation
+
+Full documentation: https://capbypass.dev/docs/sdks/python
+
+## Examples
+
+See [examples/](examples/) directory for complete examples:
+
+- [recaptcha_v2.py](examples/recaptcha_v2.py) - reCAPTCHA v2 solving
+- [recaptcha_v3.py](examples/recaptcha_v3.py) - reCAPTCHA v3 solving
+- [aws_waf.py](examples/aws_waf.py) - AWS WAF CAPTCHA solving
+
+## Development
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run linter
+ruff check .
+
+# Run type checker
+mypy src/
+```
+
+## License
+
+MIT
+
+## Support
+
+- Documentation: https://capbypass.dev/docs
+- Issues: https://github.com/CapBypass-Development/capbypass-sdk-python/issues
+- Email: support@capbypass.dev

capbypass_sdk-1.0.0/README.md

@@ -0,0 +1,137 @@
+# CapBypass Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/capbypass-sdk.svg)](https://pypi.org/project/capbypass-sdk/)
+[![Python versions](https://img.shields.io/pypi/pyversions/capbypass-sdk.svg)](https://pypi.org/project/capbypass-sdk/)
+[![Downloads](https://pepy.tech/badge/capbypass-sdk)](https://pepy.tech/project/capbypass-sdk)
+[![GitHub stars](https://img.shields.io/github/stars/CapBypass-Development/capbypass-sdk-python.svg)](https://github.com/CapBypass-Development/capbypass-sdk-python)
+
+Official Python SDK for CapBypass CAPTCHA solving API.
+
+## Features
+
+- ✨ Simple `solve()` method with auto-polling
+- 🎯 Advanced `createTask()` + `getTaskResult()` for granular control
+- 💰 `getBalance()` to check account balance
+- 🔄 Automatic retry logic for network failures
+- 🛡️ Comprehensive error handling
+- 📝 Type hints for better IDE support
+- 🧪 100% test coverage
+
+## Supported CAPTCHA Types
+
+- reCAPTCHA v2 (normal & invisible)
+- reCAPTCHA v3
+- reCAPTCHA v3 Enterprise
+- AWS WAF CAPTCHA
+
+## Installation
+
+```bash
+pip install capbypass-sdk
+```
+
+## Quick Start
+
+```python
+from capbypass import CapBypass
+
+# Initialize client
+client = CapBypass(api_key="your-api-key")
+# Or use environment variable: export CAPBYPASS_API_KEY="your-key"
+
+# Solve CAPTCHA (auto-polling)
+solution = client.solve({
+    "type": "ReCaptchaV2TaskProxyLess",
+    "websiteURL": "https://example.com",
+    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
+})
+
+print(solution["gRecaptchaResponse"])
+```
+
+## Advanced Usage
+
+### Granular Control
+
+```python
+# Create task
+task_id = client.createTask({
+    "type": "ReCaptchaV2TaskProxyLess",
+    "websiteURL": "https://example.com",
+    "websiteKey": "site-key"
+})
+
+# Poll for result
+import time
+while True:
+    result = client.getTaskResult(task_id)
+    if result["status"] == "ready":
+        print(result["solution"])
+        break
+    time.sleep(5)
+```
+
+### Check Balance
+
+```python
+balance = client.getBalance()
+print(f"Balance: ${balance:.4f}")
+```
+
+### Error Handling
+
+```python
+from capbypass import CapBypass
+from capbypass.errors import (
+    AuthenticationError,
+    InsufficientBalanceError,
+    TimeoutError,
+)
+
+try:
+    solution = client.solve(task)
+except AuthenticationError:
+    print("Invalid API key")
+except InsufficientBalanceError:
+    print("Insufficient balance")
+except TimeoutError:
+    print("Task timed out")
+```
+
+## Documentation
+
+Full documentation: https://capbypass.dev/docs/sdks/python
+
+## Examples
+
+See [examples/](examples/) directory for complete examples:
+
+- [recaptcha_v2.py](examples/recaptcha_v2.py) - reCAPTCHA v2 solving
+- [recaptcha_v3.py](examples/recaptcha_v3.py) - reCAPTCHA v3 solving
+- [aws_waf.py](examples/aws_waf.py) - AWS WAF CAPTCHA solving
+
+## Development
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run linter
+ruff check .
+
+# Run type checker
+mypy src/
+```
+
+## License
+
+MIT
+
+## Support
+
+- Documentation: https://capbypass.dev/docs
+- Issues: https://github.com/CapBypass-Development/capbypass-sdk-python/issues
+- Email: support@capbypass.dev

capbypass_sdk-1.0.0/pyproject.toml

@@ -0,0 +1,78 @@
+[build-system]
+requires = ["setuptools>=61.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "capbypass-sdk"
+version = "1.0.0"
+description = "Official Python SDK for CapBypass CAPTCHA solving API"
+readme = "README.md"
+authors = [
+    {name = "CapBypass Development", email = "dev@capbypass.dev"}
+]
+license = {text = "MIT"}
+classifiers = [
+    "Development Status :: 5 - Production/Stable",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Internet :: WWW/HTTP",
+]
+keywords = ["captcha", "recaptcha", "aws-waf", "automation", "solver"]
+requires-python = ">=3.8"
+dependencies = [
+    "requests>=2.31.0",
+]
+
+[project.urls]
+Homepage = "https://capbypass.dev"
+Documentation = "https://capbypass.dev/docs/sdks/python"
+Repository = "https://github.com/CapBypass-Development/capbypass-sdk-python"
+"Bug Tracker" = "https://github.com/CapBypass-Development/capbypass-sdk-python/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=7.4.0",
+    "pytest-mock>=3.11.0",
+    "responses>=0.23.0",
+    "ruff>=0.1.0",
+    "mypy>=1.5.0",
+    "types-requests>=2.31.0",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+capbypass = ["py.typed"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py38"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "W", "UP"]
+ignore = ["E501"]  # Line too long (handled by formatter)
+
+[tool.mypy]
+python_version = "3.8"
+warn_return_any = true
+warn_unused_configs = true
+disallow_untyped_defs = false
+ignore_missing_imports = true
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+python_classes = ["Test*"]
+python_functions = ["test_*"]
+addopts = "-v --strict-markers"
+markers = [
+    "slow: marks tests as slow (deselect with '-m \"not slow\"')",
+]

capbypass_sdk-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

capbypass_sdk-1.0.0/src/capbypass/__init__.py

@@ -0,0 +1,41 @@
+"""CapBypass Python SDK
+
+Official Python SDK for CapBypass CAPTCHA solving API.
+"""
+
+from .client import CapBypass
+from .errors import (
+    CapBypassError,
+    AuthenticationError,
+    InsufficientBalanceError,
+    ValidationError,
+    TaskNotFoundError,
+    SolverError,
+    TimeoutError,
+    InternalError,
+    NetworkError,
+    GatewayError,
+    ServerError,
+    RateLimitError,
+    ParseError,
+)
+from .types import TaskType
+
+__version__ = "1.0.0"
+__all__ = [
+    "CapBypass",
+    "CapBypassError",
+    "AuthenticationError",
+    "InsufficientBalanceError",
+    "ValidationError",
+    "TaskNotFoundError",
+    "SolverError",
+    "TimeoutError",
+    "InternalError",
+    "NetworkError",
+    "GatewayError",
+    "ServerError",
+    "RateLimitError",
+    "ParseError",
+    "TaskType",
+]

capbypass_sdk-1.0.0/src/capbypass/client.py

@@ -0,0 +1,347 @@
+"""CapBypass API client."""
+
+import os
+import time
+import random
+from typing import Dict, Any, Optional
+
+import requests
+
+from .errors import (
+    AuthenticationError,
+    InsufficientBalanceError,
+    ValidationError,
+    TaskNotFoundError,
+    SolverError,
+    TimeoutError as CapBypassTimeoutError,
+    InternalError,
+    NetworkError,
+    GatewayError,
+    ServerError,
+    RateLimitError,
+    ParseError,
+)
+
+
+class CapBypass:
+    """CapBypass API client for CAPTCHA solving.
+
+    Args:
+        api_key: CapBypass API key. If not provided, reads from CAPBYPASS_API_KEY env var.
+        base_url: API gateway URL. Defaults to production gateway.
+
+    Raises:
+        ValueError: If api_key is not provided and CAPBYPASS_API_KEY env var is not set.
+
+    Example:
+        >>> from capbypass import CapBypass
+        >>> client = CapBypass(api_key="your-api-key")
+        >>> result = client.solve({
+        ...     "type": "ReCaptchaV2TaskProxyLess",
+        ...     "websiteURL": "https://example.com",
+        ...     "websiteKey": "site-key"
+        ... })
+        >>> print(result["gRecaptchaResponse"])
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        base_url: str = "https://gateway.strayder.io",
+    ):
+        self.api_key = api_key or os.getenv("CAPBYPASS_API_KEY")
+        if not self.api_key:
+            raise ValueError(
+                "API key is required. Provide via constructor or CAPBYPASS_API_KEY env var."
+            )
+
+        self.base_url = base_url.rstrip("/")
+        self.session = requests.Session()
+        self.session.headers.update({
+            "Content-Type": "application/json",
+            "User-Agent": "capbypass-sdk-python/1.0.0",
+        })
+
+    def _make_request(
+        self,
+        endpoint: str,
+        payload: Dict[str, Any],
+        max_retries: int = 3,
+    ) -> Dict[str, Any]:
+        """Make HTTP request with retry logic.
+
+        Args:
+            endpoint: API endpoint path (e.g., "/createTask")
+            payload: Request JSON payload
+            max_retries: Maximum number of retry attempts for network failures
+
+        Returns:
+            Parsed JSON response
+
+        Raises:
+            NetworkError: On connection failures
+            GatewayError: On 502/503/504 responses
+            ServerError: On 500 responses
+            RateLimitError: On 429 responses
+            ParseError: On malformed JSON responses
+        """
+        url = f"{self.base_url}{endpoint}"
+        attempt = 0
+
+        while attempt <= max_retries:
+            try:
+                response = self.session.post(url, json=payload, timeout=30)
+
+                # Handle HTTP-layer errors
+                if response.status_code in (502, 503, 504):
+                    if attempt < max_retries:
+                        # Exponential backoff with jitter for gateway errors
+                        backoff = min(10, 2 ** attempt) + random.uniform(0, 1)
+                        time.sleep(backoff)
+                        attempt += 1
+                        continue
+                    raise GatewayError(
+                        error_code="GATEWAY_ERROR",
+                        error_description=f"Gateway error: HTTP {response.status_code}",
+                    )
+
+                if response.status_code == 500:
+                    raise ServerError(
+                        error_code="SERVER_ERROR",
+                        error_description="Internal server error",
+                    )
+
+                if response.status_code == 429:
+                    raise RateLimitError(
+                        error_code="RATE_LIMIT",
+                        error_description="Rate limit exceeded",
+                    )
+
+                # Parse JSON response
+                try:
+                    return response.json()
+                except ValueError as e:
+                    raise ParseError(
+                        error_code="PARSE_ERROR",
+                        error_description=f"Malformed JSON response: {e}",
+                    )
+
+            except requests.exceptions.ConnectionError as e:
+                if attempt < max_retries:
+                    backoff = min(10, 2 ** attempt) + random.uniform(0, 1)
+                    time.sleep(backoff)
+                    attempt += 1
+                    continue
+                raise NetworkError(
+                    error_code="NETWORK_ERROR",
+                    error_description=f"Connection failed: {e}",
+                )
+
+            except requests.exceptions.Timeout as e:
+                if attempt < max_retries:
+                    backoff = min(10, 2 ** attempt) + random.uniform(0, 1)
+                    time.sleep(backoff)
+                    attempt += 1
+                    continue
+                raise NetworkError(
+                    error_code="NETWORK_ERROR",
+                    error_description=f"Request timeout: {e}",
+                )
+
+            except requests.exceptions.RequestException as e:
+                raise NetworkError(
+                    error_code="NETWORK_ERROR",
+                    error_description=f"Request failed: {e}",
+                )
+
+        # Should never reach here, but just in case
+        raise NetworkError(
+            error_code="NETWORK_ERROR",
+            error_description="Max retries exceeded",
+        )
+
+    def _handle_error_response(self, response: Dict[str, Any]) -> None:
+        """Handle error responses from API.
+
+        Args:
+            response: API response dict
+
+        Raises:
+            AuthenticationError: On ERROR_KEY_DOES_NOT_EXIST
+            InsufficientBalanceError: On ERROR_ZERO_BALANCE
+            ValidationError: On ERROR_INVALID_TASK_DATA
+            TaskNotFoundError: On ERROR_TASK_NOT_FOUND
+            SolverError: On ERROR_CAPTCHA_UNSOLVABLE
+            CapBypassTimeoutError: On ERROR_TIMEOUT
+            InternalError: On ERROR_INTERNAL or other errors
+        """
+        error_id = response.get("errorId", 0)
+        if error_id == 0:
+            return  # Success
+
+        error_code = response.get("errorCode", "UNKNOWN_ERROR")
+        error_description = response.get("errorDescription", "Unknown error")
+
+        # Map error codes to exception classes
+        error_map = {
+            "ERROR_KEY_DOES_NOT_EXIST": AuthenticationError,
+            "ERROR_ZERO_BALANCE": InsufficientBalanceError,
+            "ERROR_INVALID_TASK_DATA": ValidationError,
+            "ERROR_TASK_NOT_FOUND": TaskNotFoundError,
+            "ERROR_CAPTCHA_UNSOLVABLE": SolverError,
+            "ERROR_TIMEOUT": CapBypassTimeoutError,
+            "ERROR_INTERNAL": InternalError,
+        }
+
+        exception_class = error_map.get(error_code, InternalError)
+        raise exception_class(
+            error_code=error_code,
+            error_description=error_description,
+            error_id=error_id,
+        )
+
+    def createTask(self, task: Dict[str, Any]) -> str:
+        """Create a CAPTCHA solving task.
+
+        Args:
+            task: Task configuration dict with "type" and task-specific parameters
+
+        Returns:
+            Task ID (UUID string)
+
+        Raises:
+            AuthenticationError: Invalid API key
+            InsufficientBalanceError: Account balance is zero
+            ValidationError: Invalid task data
+
+        Example:
+            >>> task_id = client.createTask({
+            ...     "type": "ReCaptchaV2TaskProxyLess",
+            ...     "websiteURL": "https://example.com",
+            ...     "websiteKey": "site-key"
+            ... })
+        """
+        payload = {
+            "clientKey": self.api_key,
+            "task": task,
+        }
+
+        response = self._make_request("/createTask", payload)
+        self._handle_error_response(response)
+
+        return response["taskId"]
+
+    def getTaskResult(self, task_id: str) -> Dict[str, Any]:
+        """Get result of a CAPTCHA solving task.
+
+        Args:
+            task_id: Task ID returned from createTask()
+
+        Returns:
+            Dict with "status" (processing/ready/failed), "solution" (if ready), error details (if failed)
+
+        Raises:
+            TaskNotFoundError: Task ID does not exist
+            AuthenticationError: Invalid API key
+
+        Example:
+            >>> result = client.getTaskResult(task_id)
+            >>> if result["status"] == "ready":
+            ...     print(result["solution"])
+        """
+        payload = {
+            "clientKey": self.api_key,
+            "taskId": task_id,
+        }
+
+        response = self._make_request("/getTaskResult", payload)
+        self._handle_error_response(response)
+
+        return response
+
+    def solve(
+        self,
+        task: Dict[str, Any],
+        timeout: int = 120,
+    ) -> Dict[str, Any]:
+        """Create task and poll until solved (auto-polling).
+
+        Args:
+            task: Task configuration dict
+            timeout: Maximum time to wait in seconds (default: 120)
+
+        Returns:
+            Solution dict (varies by task type)
+
+        Raises:
+            CapBypassTimeoutError: Task exceeded timeout
+            SolverError: Task failed to solve
+            AuthenticationError: Invalid API key
+            InsufficientBalanceError: Account balance is zero
+            ValidationError: Invalid task data
+
+        Example:
+            >>> solution = client.solve({
+            ...     "type": "ReCaptchaV2TaskProxyLess",
+            ...     "websiteURL": "https://example.com",
+            ...     "websiteKey": "site-key"
+            ... })
+            >>> print(solution["gRecaptchaResponse"])
+        """
+        # Create task
+        task_id = self.createTask(task)
+
+        # Poll with adaptive intervals
+        start_time = time.time()
+        attempt = 0
+
+        while True:
+            # Check timeout (wall-clock time)
+            elapsed = time.time() - start_time
+            if elapsed > timeout:
+                raise CapBypassTimeoutError(
+                    error_code="TIMEOUT",
+                    error_description=f"Task exceeded timeout of {timeout}s",
+                )
+
+            # Get task result
+            result = self.getTaskResult(task_id)
+            status = result.get("status")
+
+            if status == "ready":
+                return result.get("solution", {})
+
+            if status == "failed":
+                error_description = result.get("errorDescription", "Task failed")
+                raise SolverError(
+                    error_code="SOLVER_ERROR",
+                    error_description=error_description,
+                )
+
+            # Adaptive polling: min(5, ceil(attempt / 2)) seconds
+            # Attempts 1-2 → 1s, 3-4 → 2s, 5-6 → 3s, 7+ → 5s
+            attempt += 1
+            poll_interval = min(5, (attempt + 1) // 2)
+            time.sleep(poll_interval)
+
+    def getBalance(self) -> float:
+        """Get account balance.
+
+        Returns:
+            Account balance as float
+
+        Raises:
+            AuthenticationError: Invalid API key
+
+        Example:
+            >>> balance = client.getBalance()
+            >>> print(f"Balance: ${balance:.4f}")
+        """
+        payload = {
+            "clientKey": self.api_key,
+        }
+
+        response = self._make_request("/getBalance", payload)
+        self._handle_error_response(response)
+
+        return float(response["balance"])

capbypass_sdk-1.0.0/src/capbypass/errors.py

@@ -0,0 +1,80 @@
+"""Exception classes for CapBypass SDK."""
+
+
+class CapBypassError(Exception):
+    """Base exception for all CapBypass errors.
+
+    Attributes:
+        error_code: Capsolver-compatible error code (e.g., "ERROR_KEY_DOES_NOT_EXIST")
+        error_description: Human-readable error message
+        error_id: Numeric error ID from API response
+    """
+
+    def __init__(self, error_code: str = None, error_description: str = None, error_id: int = None):
+        self.error_code = error_code
+        self.error_description = error_description or str(error_code)
+        self.error_id = error_id
+        super().__init__(self.error_description)
+
+
+class AuthenticationError(CapBypassError):
+    """Raised when API key is invalid or missing."""
+    pass
+
+
+class InsufficientBalanceError(CapBypassError):
+    """Raised when account balance is zero or insufficient."""
+    pass
+
+
+class ValidationError(CapBypassError):
+    """Raised when task data is invalid."""
+    pass
+
+
+class TaskNotFoundError(CapBypassError):
+    """Raised when task ID does not exist."""
+    pass
+
+
+class SolverError(CapBypassError):
+    """Raised when CAPTCHA cannot be solved."""
+    pass
+
+
+class TimeoutError(CapBypassError):
+    """Raised when solve() exceeds timeout."""
+    pass
+
+
+class InternalError(CapBypassError):
+    """Raised when server encounters an internal error."""
+    pass
+
+
+# HTTP-layer errors
+
+
+class NetworkError(CapBypassError):
+    """Raised when network connection fails (DNS, refused, timeout)."""
+    pass
+
+
+class GatewayError(CapBypassError):
+    """Raised when gateway returns 502/503/504 (retryable)."""
+    pass
+
+
+class ServerError(CapBypassError):
+    """Raised when server returns 500 error."""
+    pass
+
+
+class RateLimitError(CapBypassError):
+    """Raised when request is rate-limited (429)."""
+    pass
+
+
+class ParseError(CapBypassError):
+    """Raised when response JSON is malformed."""
+    pass

capbypass_sdk-1.0.0/src/capbypass/types.py

@@ -0,0 +1,24 @@
+"""Task type definitions for CapBypass API."""
+
+
+class TaskType:
+    """Supported CAPTCHA task types.
+
+    Use these constants when creating tasks to ensure correct type strings.
+    """
+
+    # AWS WAF tasks
+    ANTI_AWS_WAF_TASK = "AntiAwsWafTask"
+    ANTI_AWS_WAF_TASK_PROXYLESS = "AntiAwsWafTaskProxyLess"
+
+    # reCAPTCHA v2 tasks
+    RECAPTCHA_V2_TASK = "ReCaptchaV2Task"
+    RECAPTCHA_V2_TASK_PROXYLESS = "ReCaptchaV2TaskProxyLess"
+
+    # reCAPTCHA v3 tasks
+    RECAPTCHA_V3_TASK = "ReCaptchaV3Task"
+    RECAPTCHA_V3_TASK_PROXYLESS = "ReCaptchaV3TaskProxyLess"
+
+    # reCAPTCHA v3 Enterprise tasks
+    RECAPTCHA_V3_ENTERPRISE_TASK = "ReCaptchaV3EnterpriseTask"
+    RECAPTCHA_V3_ENTERPRISE_TASK_PROXYLESS = "ReCaptchaV3EnterpriseTaskProxyLess"

capbypass_sdk-1.0.0/src/capbypass_sdk.egg-info/PKG-INFO

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: capbypass-sdk
+Version: 1.0.0
+Summary: Official Python SDK for CapBypass CAPTCHA solving API
+Author-email: CapBypass Development <dev@capbypass.dev>
+License: MIT
+Project-URL: Homepage, https://capbypass.dev
+Project-URL: Documentation, https://capbypass.dev/docs/sdks/python
+Project-URL: Repository, https://github.com/CapBypass-Development/capbypass-sdk-python
+Project-URL: Bug Tracker, https://github.com/CapBypass-Development/capbypass-sdk-python/issues
+Keywords: captcha,recaptcha,aws-waf,automation,solver
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Internet :: WWW/HTTP
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.31.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.4.0; extra == "dev"
+Requires-Dist: pytest-mock>=3.11.0; extra == "dev"
+Requires-Dist: responses>=0.23.0; extra == "dev"
+Requires-Dist: ruff>=0.1.0; extra == "dev"
+Requires-Dist: mypy>=1.5.0; extra == "dev"
+Requires-Dist: types-requests>=2.31.0; extra == "dev"
+Dynamic: license-file
+
+# CapBypass Python SDK
+
+[![PyPI version](https://img.shields.io/pypi/v/capbypass-sdk.svg)](https://pypi.org/project/capbypass-sdk/)
+[![Python versions](https://img.shields.io/pypi/pyversions/capbypass-sdk.svg)](https://pypi.org/project/capbypass-sdk/)
+[![Downloads](https://pepy.tech/badge/capbypass-sdk)](https://pepy.tech/project/capbypass-sdk)
+[![GitHub stars](https://img.shields.io/github/stars/CapBypass-Development/capbypass-sdk-python.svg)](https://github.com/CapBypass-Development/capbypass-sdk-python)
+
+Official Python SDK for CapBypass CAPTCHA solving API.
+
+## Features
+
+- ✨ Simple `solve()` method with auto-polling
+- 🎯 Advanced `createTask()` + `getTaskResult()` for granular control
+- 💰 `getBalance()` to check account balance
+- 🔄 Automatic retry logic for network failures
+- 🛡️ Comprehensive error handling
+- 📝 Type hints for better IDE support
+- 🧪 100% test coverage
+
+## Supported CAPTCHA Types
+
+- reCAPTCHA v2 (normal & invisible)
+- reCAPTCHA v3
+- reCAPTCHA v3 Enterprise
+- AWS WAF CAPTCHA
+
+## Installation
+
+```bash
+pip install capbypass-sdk
+```
+
+## Quick Start
+
+```python
+from capbypass import CapBypass
+
+# Initialize client
+client = CapBypass(api_key="your-api-key")
+# Or use environment variable: export CAPBYPASS_API_KEY="your-key"
+
+# Solve CAPTCHA (auto-polling)
+solution = client.solve({
+    "type": "ReCaptchaV2TaskProxyLess",
+    "websiteURL": "https://example.com",
+    "websiteKey": "6Le-wvkSAAAAAPBMRTvw0Q4Muexq9bi0DJwx_mJ-"
+})
+
+print(solution["gRecaptchaResponse"])
+```
+
+## Advanced Usage
+
+### Granular Control
+
+```python
+# Create task
+task_id = client.createTask({
+    "type": "ReCaptchaV2TaskProxyLess",
+    "websiteURL": "https://example.com",
+    "websiteKey": "site-key"
+})
+
+# Poll for result
+import time
+while True:
+    result = client.getTaskResult(task_id)
+    if result["status"] == "ready":
+        print(result["solution"])
+        break
+    time.sleep(5)
+```
+
+### Check Balance
+
+```python
+balance = client.getBalance()
+print(f"Balance: ${balance:.4f}")
+```
+
+### Error Handling
+
+```python
+from capbypass import CapBypass
+from capbypass.errors import (
+    AuthenticationError,
+    InsufficientBalanceError,
+    TimeoutError,
+)
+
+try:
+    solution = client.solve(task)
+except AuthenticationError:
+    print("Invalid API key")
+except InsufficientBalanceError:
+    print("Insufficient balance")
+except TimeoutError:
+    print("Task timed out")
+```
+
+## Documentation
+
+Full documentation: https://capbypass.dev/docs/sdks/python
+
+## Examples
+
+See [examples/](examples/) directory for complete examples:
+
+- [recaptcha_v2.py](examples/recaptcha_v2.py) - reCAPTCHA v2 solving
+- [recaptcha_v3.py](examples/recaptcha_v3.py) - reCAPTCHA v3 solving
+- [aws_waf.py](examples/aws_waf.py) - AWS WAF CAPTCHA solving
+
+## Development
+
+```bash
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run linter
+ruff check .
+
+# Run type checker
+mypy src/
+```
+
+## License
+
+MIT
+
+## Support
+
+- Documentation: https://capbypass.dev/docs
+- Issues: https://github.com/CapBypass-Development/capbypass-sdk-python/issues
+- Email: support@capbypass.dev

capbypass_sdk-1.0.0/src/capbypass_sdk.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+LICENSE
+README.md
+pyproject.toml
+src/capbypass/__init__.py
+src/capbypass/client.py
+src/capbypass/errors.py
+src/capbypass/types.py
+src/capbypass_sdk.egg-info/PKG-INFO
+src/capbypass_sdk.egg-info/SOURCES.txt
+src/capbypass_sdk.egg-info/dependency_links.txt
+src/capbypass_sdk.egg-info/requires.txt
+src/capbypass_sdk.egg-info/top_level.txt

capbypass_sdk-1.0.0/src/capbypass_sdk.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

capbypass_sdk-1.0.0/src/capbypass_sdk.egg-info/requires.txt

@@ -0,0 +1,9 @@
+requests>=2.31.0
+
+[dev]
+pytest>=7.4.0
+pytest-mock>=3.11.0
+responses>=0.23.0
+ruff>=0.1.0
+mypy>=1.5.0
+types-requests>=2.31.0

capbypass_sdk-1.0.0/src/capbypass_sdk.egg-info/top_level.txt

@@ -0,0 +1 @@
+capbypass