capskip 1.0.0__py3-none-any.whl

capskip/__init__.py

@@ -0,0 +1,29 @@
+"""CapSkip Python SDK — local captcha solver client."""
+
+from .api import ApiClient
+from .async_api import AsyncApiClient
+from .async_solver import AsyncCapSkip
+from .exceptions import (
+    ApiException,
+    CapSkipError,
+    NetworkException,
+    SolverExceptions,
+    TimeoutException,
+    ValidationException,
+)
+from .solver import CapSkip
+
+__all__ = [
+    'CapSkip',
+    'AsyncCapSkip',
+    'ApiClient',
+    'AsyncApiClient',
+    'CapSkipError',
+    'SolverExceptions',
+    'ValidationException',
+    'NetworkException',
+    'ApiException',
+    'TimeoutException',
+]
+
+__version__ = '1.0.0'

capskip/_api_params.py

@@ -0,0 +1,118 @@
+"""CapSkip API parameter validation (https://capskip.com/api-docs/)."""
+
+from .exceptions import ValidationException
+
+NORMAL_SUBMIT = frozenset({'method', 'body', 'json', 'file'})
+
+RECAPTCHA_V2_SUBMIT = frozenset({
+    'method', 'googlekey', 'pageurl', 'enterprise', 'invisible', 'data-s', 'json',
+    'proxy', 'proxytype',
+})
+
+RECAPTCHA_V3_SUBMIT = frozenset({
+    'method', 'version', 'googlekey', 'pageurl', 'enterprise', 'action', 'min_score',
+    'json', 'proxy', 'proxytype',
+})
+
+TURNSTILE_SUBMIT = frozenset({
+    'method', 'sitekey', 'pageurl', 'action', 'data', 'pagedata', 'json',
+    'proxy', 'proxytype',
+})
+
+_PARAM_ALIASES = {
+    'url': 'pageurl',
+    'score': 'min_score',
+    'minScore': 'min_score',
+    'datas': 'data-s',
+    'data_s': 'data-s',
+}
+
+
+def apply_param_aliases(params: dict) -> dict:
+    out = dict(params)
+    for alias, api_name in _PARAM_ALIASES.items():
+        if alias in out:
+            if api_name in out and out[alias] != out[api_name]:
+                raise ValidationException(
+                    f"Conflicting parameters: {alias!r} and {api_name!r}"
+                )
+            out[api_name] = out.pop(alias)
+    return out
+
+
+def apply_proxy(params: dict) -> dict:
+    out = dict(params)
+    proxy = out.pop('proxy', None)
+    if not proxy:
+        return out
+    if isinstance(proxy, dict):
+        if 'uri' not in proxy or 'type' not in proxy:
+            raise ValidationException("proxy dict must contain 'type' and 'uri' keys")
+        out['proxy'] = proxy['uri']
+        out['proxytype'] = proxy['type']
+    else:
+        out['proxy'] = proxy
+        if 'proxytype' not in out:
+            out['proxytype'] = 'HTTP'
+    return out
+
+
+def _unknown_keys(params: dict, allowed: frozenset) -> set:
+    return set(params.keys()) - allowed - {'key', 'file', 'files'}
+
+
+def validate_normal_submit(params: dict) -> None:
+    unknown = _unknown_keys(params, NORMAL_SUBMIT)
+    if unknown:
+        raise ValidationException(
+            f"Unsupported parameters for image captcha: {sorted(unknown)}. "
+            f"CapSkip only supports: method, file/body, json."
+        )
+    if 'proxy' in params or 'proxytype' in params:
+        raise ValidationException(
+            "Proxy is not supported for image captcha. "
+            "Use proxy only with reCAPTCHA or Turnstile."
+        )
+
+
+def validate_recaptcha_submit(params: dict, version: str) -> None:
+    version = (version or 'v2').lower()
+    if version == 'v3':
+        allowed = RECAPTCHA_V3_SUBMIT
+        if params.get('invisible'):
+            raise ValidationException("invisible is only supported for reCAPTCHA v2.")
+    else:
+        allowed = RECAPTCHA_V2_SUBMIT
+        if params.get('version') == 'v3':
+            raise ValidationException("Use version='v3' for reCAPTCHA v3.")
+        for key in ('action', 'min_score'):
+            if key in params:
+                raise ValidationException(f"{key!r} is only supported for reCAPTCHA v3.")
+
+    unknown = _unknown_keys(params, allowed)
+    if unknown:
+        raise ValidationException(
+            f"Unsupported parameters for reCAPTCHA {version}: {sorted(unknown)}."
+        )
+
+
+def validate_turnstile_submit(params: dict) -> None:
+    unknown = _unknown_keys(params, TURNSTILE_SUBMIT)
+    if unknown:
+        raise ValidationException(
+            f"Unsupported parameters for Turnstile: {sorted(unknown)}."
+        )
+
+
+def prepare_submit_params(params: dict, captcha_type: str, version: str = 'v2') -> dict:
+    params = apply_param_aliases(params)
+    params = apply_proxy(params)
+
+    if captcha_type == 'normal':
+        validate_normal_submit(params)
+    elif captcha_type == 'recaptcha':
+        validate_recaptcha_submit(params, version)
+    elif captcha_type == 'turnstile':
+        validate_turnstile_submit(params)
+
+    return params

capskip/api.py

@@ -0,0 +1,56 @@
+import requests
+
+from .exceptions import ApiException, NetworkException
+
+
+class ApiClient:
+    """Low-level HTTP client for CapSkip in.php / res.php endpoints."""
+
+    def __init__(self, host='127.0.0.1', port=8080):
+        self.host = host
+        self.port = port
+
+    @property
+    def base_url(self):
+        return f'http://{self.host}:{self.port}'
+
+    def in_(self, files=None, **kwargs):
+        files = files or {}
+        try:
+            url = f'{self.base_url}/in.php'
+            if files:
+                opened = {key: open(path, 'rb') for key, path in files.items()}
+                try:
+                    resp = requests.post(url, data=kwargs, files=opened)
+                finally:
+                    for f in opened.values():
+                        f.close()
+            elif 'file' in kwargs:
+                with open(kwargs.pop('file'), 'rb') as f:
+                    resp = requests.post(url, data=kwargs, files={'file': f})
+            else:
+                resp = requests.post(url, data=kwargs)
+        except requests.RequestException as e:
+            raise NetworkException(e) from e
+
+        if resp.status_code != 200:
+            raise NetworkException(f'bad response: {resp.status_code}')
+
+        text = resp.content.decode('utf-8')
+        if 'ERROR' in text:
+            raise ApiException(text)
+        return text
+
+    def res(self, **kwargs):
+        try:
+            resp = requests.get(f'{self.base_url}/res.php', params=kwargs)
+        except requests.RequestException as e:
+            raise NetworkException(e) from e
+
+        if resp.status_code != 200:
+            raise NetworkException(f'bad response: {resp.status_code}')
+
+        text = resp.content.decode('utf-8')
+        if 'ERROR' in text:
+            raise ApiException(text)
+        return text

capskip/async_api.py

@@ -0,0 +1,63 @@
+from contextlib import AsyncExitStack
+
+import aiofiles
+import httpx
+
+from .exceptions import ApiException, NetworkException
+
+
+class AsyncApiClient:
+    """Async HTTP client for CapSkip in.php / res.php endpoints."""
+
+    def __init__(self, host='127.0.0.1', port=8080):
+        self.host = host
+        self.port = port
+
+    @property
+    def base_url(self):
+        return f'http://{self.host}:{self.port}'
+
+    async def in_(self, files=None, **kwargs):
+        files = files or {}
+        url = f'{self.base_url}/in.php'
+        try:
+            async with httpx.AsyncClient(follow_redirects=True) as client:
+                if files:
+                    async with AsyncExitStack() as stack:
+                        file_objects = {}
+                        for key, path in files.items():
+                            handle = await stack.enter_async_context(aiofiles.open(path, 'rb'))
+                            file_objects[key] = await handle.read()
+                        resp = await client.post(url, data=kwargs, files=file_objects)
+                elif 'file' in kwargs:
+                    path = kwargs.pop('file')
+                    async with aiofiles.open(path, 'rb') as handle:
+                        content = await handle.read()
+                    resp = await client.post(url, data=kwargs, files={'file': content})
+                else:
+                    resp = await client.post(url, data=kwargs)
+        except httpx.RequestError as e:
+            raise NetworkException(e) from e
+
+        if resp.status_code != 200:
+            raise NetworkException(f'bad response: {resp.status_code}')
+
+        text = resp.content.decode('utf-8')
+        if 'ERROR' in text:
+            raise ApiException(text)
+        return text
+
+    async def res(self, **kwargs):
+        try:
+            async with httpx.AsyncClient(follow_redirects=True) as client:
+                resp = await client.get(f'{self.base_url}/res.php', params=kwargs)
+        except httpx.RequestError as e:
+            raise NetworkException(e) from e
+
+        if resp.status_code != 200:
+            raise NetworkException(f'bad response: {resp.status_code}')
+
+        text = resp.content.decode('utf-8')
+        if 'ERROR' in text:
+            raise ApiException(text)
+        return text

capskip/async_solver.py

@@ -0,0 +1,123 @@
+import asyncio
+import os
+import time
+from base64 import b64encode
+
+import httpx
+
+from .async_api import AsyncApiClient
+from ._api_params import apply_param_aliases, apply_proxy, prepare_submit_params
+from .exceptions import ApiException, NetworkException, TimeoutException, ValidationException, SolverExceptions
+from .solver import INITIAL_POLLING_INTERVAL, _apply_poll_result, _next_poll_interval, _parse_poll_response
+
+
+class AsyncCapSkip:
+    """Async client for the CapSkip local captcha solver."""
+
+    def __init__(self,
+                 apiKey='capskip',
+                 host='127.0.0.1',
+                 port=8080,
+                 defaultTimeout=120,
+                 recaptchaTimeout=300,
+                 pollingInterval=5):
+
+        self.API_KEY = apiKey
+        self.default_timeout = defaultTimeout
+        self.recaptcha_timeout = recaptchaTimeout
+        self.polling_interval = pollingInterval
+        self.api_client = AsyncApiClient(host=host, port=port)
+        self.exceptions = SolverExceptions
+
+    async def normal(self, file, **kwargs):
+        unsupported = set(kwargs) - {'json'}
+        if unsupported:
+            raise ValidationException(
+                f"Unsupported parameters for image captcha: {sorted(unsupported)}. "
+                f"Only json is supported besides the image input."
+            )
+        method = await self.get_method(file)
+        return await self.solve(**method, **kwargs)
+
+    async def recaptcha(self, sitekey, url, version='v2', enterprise=0, **kwargs):
+        params = {
+            'googlekey': sitekey,
+            'url': url,
+            'method': 'userrecaptcha',
+            'enterprise': enterprise,
+            **kwargs,
+        }
+        if str(version).lower() == 'v3':
+            params['version'] = 'v3'
+        return await self.solve(timeout=self.recaptcha_timeout, **params)
+
+    async def turnstile(self, sitekey, url, **kwargs):
+        return await self.solve(
+            sitekey=sitekey,
+            url=url,
+            method='turnstile',
+            poll_json=1,
+            **kwargs,
+        )
+
+    async def solve(self, timeout=0, polling_interval=0, poll_json=0, **kwargs):
+        poll_json = int(kwargs.pop('poll_json', poll_json) or 0)
+        captcha_id = await self.send(**kwargs)
+        result = {'captchaId': captcha_id}
+        timeout = float(timeout or self.default_timeout)
+        sleep = float(polling_interval or self.polling_interval)
+        polled = await self.wait_result(captcha_id, timeout, sleep, json=poll_json)
+        return _apply_poll_result(result, polled)
+
+    async def wait_result(self, id_, timeout, polling_interval, json=0):
+        deadline = time.time() + timeout
+        interval = min(INITIAL_POLLING_INTERVAL, polling_interval)
+        while time.time() < deadline:
+            try:
+                return await self.get_result(id_, json=json)
+            except NetworkException:
+                await asyncio.sleep(interval)
+                interval = _next_poll_interval(interval, polling_interval)
+        raise TimeoutException(f'timeout {timeout} exceeded')
+
+    async def get_method(self, file):
+        if not file:
+            raise ValidationException('File required')
+        if file.startswith('data:'):
+            return {'method': 'base64', 'body': file.split(',', 1)[1]}
+        if '.' not in file and len(file) > 50:
+            return {'method': 'base64', 'body': file}
+        if file.startswith('http'):
+            async with httpx.AsyncClient(follow_redirects=True) as client:
+                resp = await client.get(file)
+                if resp.status_code != 200:
+                    raise ValidationException(f'File could not be downloaded from url: {file}')
+                return {'method': 'base64', 'body': b64encode(resp.content).decode('utf-8')}
+        if not os.path.exists(file):
+            raise ValidationException(f'File not found: {file}')
+        return {'method': 'post', 'file': file}
+
+    async def send(self, **kwargs):
+        params = self._prepare_send_params({**kwargs, 'key': self.API_KEY})
+        files = params.pop('files', {})
+        response = await self.api_client.in_(files=files, **params)
+        if not response.startswith('OK|'):
+            raise ApiException(f'cannot recognize response {response}')
+        return response[3:]
+
+    async def get_result(self, id_, json=0):
+        query = {'key': self.API_KEY, 'action': 'get', 'id': id_}
+        if json:
+            query['json'] = 1
+        response = await self.api_client.res(**query)
+        return _parse_poll_response(response, json_mode=int(json or 0))
+
+    def _prepare_send_params(self, params: dict) -> dict:
+        method = params.get('method')
+        if method in ('post', 'base64'):
+            return prepare_submit_params(params, 'normal')
+        if method == 'userrecaptcha':
+            return prepare_submit_params(params, 'recaptcha', params.get('version', 'v2'))
+        if method == 'turnstile':
+            return prepare_submit_params(params, 'turnstile')
+        return apply_proxy(apply_param_aliases(params))

capskip/exceptions.py

@@ -0,0 +1,21 @@
+class CapSkipError(Exception):
+    """Base exception for all CapSkip SDK errors."""
+
+
+SolverExceptions = CapSkipError
+
+
+class ValidationException(CapSkipError):
+    """Invalid or unsupported parameters."""
+
+
+class NetworkException(CapSkipError):
+    """Connection failure or captcha not ready."""
+
+
+class ApiException(CapSkipError):
+    """CapSkip API returned an error."""
+
+
+class TimeoutException(CapSkipError):
+    """Polling exceeded the configured timeout."""

capskip/solver.py

@@ -0,0 +1,163 @@
+import json
+import os
+import time
+from base64 import b64encode
+
+import requests
+
+from .api import ApiClient
+from ._api_params import apply_param_aliases, apply_proxy, prepare_submit_params
+from .exceptions import ApiException, NetworkException, TimeoutException, ValidationException, SolverExceptions
+
+# First poll fires this soon after submitting, then the interval backs off
+# (doubling) up to the configured pollingInterval ceiling. Keeps latency low for
+# fast local solves (e.g. image captchas) without hammering on slow ones.
+INITIAL_POLLING_INTERVAL = 0.25
+
+
+def _next_poll_interval(interval: float, ceiling: float) -> float:
+    return min(interval * 2, ceiling)
+
+
+def _parse_poll_response(response: str, json_mode: int = 0):
+    if json_mode:
+        try:
+            data = json.loads(response)
+        except json.JSONDecodeError as exc:
+            raise ApiException(f'invalid JSON response: {response}') from exc
+
+        if data.get('status') == 0 and data.get('request') == 'CAPCHA_NOT_READY':
+            raise NetworkException
+
+        if data.get('status') != 1:
+            raise ApiException(f'cannot recognize response {data}')
+
+        return data
+
+    if response == 'CAPCHA_NOT_READY':
+        raise NetworkException
+
+    if not response.startswith('OK|'):
+        raise ApiException(f'cannot recognize response {response}')
+
+    return response[3:]
+
+
+def _apply_poll_result(result: dict, polled) -> dict:
+    if isinstance(polled, dict):
+        result['code'] = polled.get('request', '')
+        user_agent = polled.get('useragent') or polled.get('userAgent')
+        if user_agent:
+            result['userAgent'] = user_agent
+    else:
+        result['code'] = polled
+    return result
+
+
+class CapSkip:
+    """Client for the CapSkip local captcha solver (image, reCAPTCHA, Turnstile)."""
+
+    def __init__(self,
+                 apiKey='capskip',
+                 host='127.0.0.1',
+                 port=8080,
+                 defaultTimeout=120,
+                 recaptchaTimeout=300,
+                 pollingInterval=5):
+
+        self.API_KEY = apiKey
+        self.default_timeout = defaultTimeout
+        self.recaptcha_timeout = recaptchaTimeout
+        self.polling_interval = pollingInterval
+        self.api_client = ApiClient(host=host, port=port)
+        self.exceptions = SolverExceptions
+
+    def normal(self, file, **kwargs):
+        unsupported = set(kwargs) - {'json'}
+        if unsupported:
+            raise ValidationException(
+                f"Unsupported parameters for image captcha: {sorted(unsupported)}. "
+                f"Only json is supported besides the image input."
+            )
+        return self.solve(**self.get_method(file), **kwargs)
+
+    def recaptcha(self, sitekey, url, version='v2', enterprise=0, **kwargs):
+        params = {
+            'googlekey': sitekey,
+            'url': url,
+            'method': 'userrecaptcha',
+            'enterprise': enterprise,
+            **kwargs,
+        }
+        if str(version).lower() == 'v3':
+            params['version'] = 'v3'
+        return self.solve(timeout=self.recaptcha_timeout, **params)
+
+    def turnstile(self, sitekey, url, **kwargs):
+        return self.solve(
+            sitekey=sitekey,
+            url=url,
+            method='turnstile',
+            poll_json=1,
+            **kwargs,
+        )
+
+    def solve(self, timeout=0, polling_interval=0, poll_json=0, **kwargs):
+        poll_json = int(kwargs.pop('poll_json', poll_json) or 0)
+        captcha_id = self.send(**kwargs)
+        result = {'captchaId': captcha_id}
+        timeout = float(timeout or self.default_timeout)
+        sleep = float(polling_interval or self.polling_interval)
+        polled = self.wait_result(captcha_id, timeout, sleep, json=poll_json)
+        return _apply_poll_result(result, polled)
+
+    def wait_result(self, id_, timeout, polling_interval, json=0):
+        deadline = time.time() + timeout
+        interval = min(INITIAL_POLLING_INTERVAL, polling_interval)
+        while time.time() < deadline:
+            try:
+                return self.get_result(id_, json=json)
+            except NetworkException:
+                time.sleep(interval)
+                interval = _next_poll_interval(interval, polling_interval)
+        raise TimeoutException(f'timeout {timeout} exceeded')
+
+    def get_method(self, file):
+        if not file:
+            raise ValidationException('File required')
+        if file.startswith('data:'):
+            return {'method': 'base64', 'body': file.split(',', 1)[1]}
+        if '.' not in file and len(file) > 50:
+            return {'method': 'base64', 'body': file}
+        if file.startswith('http'):
+            resp = requests.get(file)
+            if resp.status_code != 200:
+                raise ValidationException(f'File could not be downloaded from url: {file}')
+            return {'method': 'base64', 'body': b64encode(resp.content).decode('utf-8')}
+        if not os.path.exists(file):
+            raise ValidationException(f'File not found: {file}')
+        return {'method': 'post', 'file': file}
+
+    def send(self, **kwargs):
+        params = self._prepare_send_params({**kwargs, 'key': self.API_KEY})
+        files = params.pop('files', {})
+        response = self.api_client.in_(files=files, **params)
+        if not response.startswith('OK|'):
+            raise ApiException(f'cannot recognize response {response}')
+        return response[3:]
+
+    def get_result(self, id_, json=0):
+        query = {'key': self.API_KEY, 'action': 'get', 'id': id_}
+        if json:
+            query['json'] = 1
+        return _parse_poll_response(self.api_client.res(**query), json_mode=int(json or 0))
+
+    def _prepare_send_params(self, params: dict) -> dict:
+        method = params.get('method')
+        if method in ('post', 'base64'):
+            return prepare_submit_params(params, 'normal')
+        if method == 'userrecaptcha':
+            return prepare_submit_params(params, 'recaptcha', params.get('version', 'v2'))
+        if method == 'turnstile':
+            return prepare_submit_params(params, 'turnstile')
+        return apply_proxy(apply_param_aliases(params))

capskip-1.0.0.dist-info/METADATA

@@ -0,0 +1,301 @@
+Metadata-Version: 2.4
+Name: capskip
+Version: 1.0.0
+Summary: Python SDK for the CapSkip local captcha solver
+Author-email: CapSkip <support@capskip.com>
+License: MIT
+Project-URL: Homepage, https://capskip.com
+Project-URL: Documentation, https://github.com/capskip/capskip-python/blob/main/docs/GETTING_STARTED.md
+Project-URL: Repository, https://github.com/capskip/capskip-python
+Project-URL: Bug Tracker, https://github.com/capskip/capskip-python/issues
+Project-URL: Changelog, https://github.com/capskip/capskip-python/blob/main/CHANGELOG.md
+Keywords: captcha,captcha-solver,recaptcha,cloudflare,turnstile,capskip,automation
+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.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.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: requests>=2.28
+Requires-Dist: httpx>=0.24
+Requires-Dist: aiofiles>=23.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Dynamic: license-file
+
+# CapSkip Python SDK
+
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+[![Tests](https://github.com/capskip/capskip-python/actions/workflows/ci.yml/badge.svg)](https://github.com/capskip/capskip-python/actions/workflows/ci.yml)
+
+Official Python client for the [CapSkip](https://capskip.com) **local** captcha solver.
+
+CapSkip runs on your machine and exposes a standard captcha-solver HTTP API (the familiar `in.php` / `res.php` endpoints). This SDK wraps that API with clean, familiar method names, so you can solve captchas locally — no cloud service and no per-solve API fees beyond your CapSkip license.
+
+---
+
+## Quick start (5 minutes)
+
+### 1. Install CapSkip
+
+Download and run the CapSkip desktop app from [capskip.com](https://capskip.com). Leave it running in the background.
+
+In CapSkip settings, note:
+
+- **API port** (default: `8080`)
+- **API key** (optional — if validation is disabled, any string works)
+
+### 2. Install the SDK
+
+```bash
+pip install capskip
+```
+
+Or from source:
+
+```bash
+git clone https://github.com/capskip/capskip-python.git
+cd capskip-python
+pip install -e .
+```
+
+### 3. Solve your first captcha
+
+```python
+from capskip import CapSkip
+
+solver = CapSkip(host="127.0.0.1", port=8080)
+
+result = solver.recaptcha(
+    sitekey="YOUR_SITEKEY",
+    url="https://example.com/page-with-recaptcha",
+)
+
+print(result["code"])  # g-recaptcha-response token
+```
+
+> **Prerequisite:** CapSkip must be running before you call the SDK. If you see a connection error, see [Troubleshooting](docs/TROUBLESHOOTING.md).
+
+---
+
+## Supported captcha types
+
+| Type | SDK method |
+|---|---|
+| Image CAPTCHA (distorted text) | `solver.normal(file)` |
+| reCAPTCHA v2 (checkbox) | `solver.recaptcha(sitekey, url)` |
+| reCAPTCHA v2 Invisible | `solver.recaptcha(..., invisible=1)` |
+| reCAPTCHA v2 Enterprise | `solver.recaptcha(..., enterprise=1)` |
+| reCAPTCHA v3 | `solver.recaptcha(..., version="v3")` |
+| reCAPTCHA v3 Enterprise | `solver.recaptcha(..., version="v3", enterprise=1)` |
+| Cloudflare Turnstile (widget) | `solver.turnstile(sitekey, url)` |
+| Cloudflare Turnstile (challenge page) | `solver.turnstile(..., data=..., pagedata=...)` |
+
+---
+
+## Documentation
+
+| Guide | Description |
+|---|---|
+| [Tutorial](docs/TUTORIAL.md) | Complete walkthrough of every captcha type, sync and async |
+| [Getting Started](docs/GETTING_STARTED.md) | Full setup: CapSkip app, SDK install, first script |
+| [API Reference](docs/API_REFERENCE.md) | All classes, methods, parameters, and return values |
+| [Examples](examples/) | Ready-to-run scripts for every captcha type |
+| [Troubleshooting](docs/TROUBLESHOOTING.md) | Connection errors, timeouts, proxy issues |
+| [Contributing](CONTRIBUTING.md) | Development setup, tests, pull requests |
+| [Changelog](CHANGELOG.md) | Release history |
+
+---
+
+## Configuration
+
+```python
+from capskip import CapSkip
+
+solver = CapSkip(
+    apiKey="capskip",        # your CapSkip API key (or any string if validation is off)
+    host="127.0.0.1",        # CapSkip host
+    port=8080,               # CapSkip port from app settings
+    defaultTimeout=120,      # seconds — image captcha polling timeout
+    recaptchaTimeout=300,    # seconds — reCAPTCHA / Turnstile polling timeout
+    pollingInterval=5,       # max seconds between res.php polls (starts at 0.25s, backs off to this)
+)
+```
+
+Use environment variables in production:
+
+```bash
+# Linux / macOS
+export CAPSKIP_API_KEY="your-key"
+export CAPSKIP_HOST="127.0.0.1"
+export CAPSKIP_PORT="8080"
+```
+
+```powershell
+# Windows PowerShell
+$env:CAPSKIP_API_KEY = "your-key"
+$env:CAPSKIP_HOST = "127.0.0.1"
+$env:CAPSKIP_PORT = "8080"
+```
+
+```python
+import os
+from capskip import CapSkip
+
+solver = CapSkip(
+    apiKey=os.getenv("CAPSKIP_API_KEY", "capskip"),
+    host=os.getenv("CAPSKIP_HOST", "127.0.0.1"),
+    port=int(os.getenv("CAPSKIP_PORT", "8080")),
+)
+```
+
+---
+
+## Usage examples
+
+### Image captcha
+
+```python
+result = solver.normal("captcha.png")
+result = solver.normal("https://example.com/captcha.jpg")
+result = solver.normal("data:image/png;base64,iVBORw0KGgo...")
+print(result["code"])
+```
+
+### reCAPTCHA v2 / v3
+
+```python
+# reCAPTCHA v2
+result = solver.recaptcha(sitekey="...", url="https://example.com")
+
+# reCAPTCHA v3
+result = solver.recaptcha(
+    sitekey="...",
+    url="https://example.com",
+    version="v3",
+    action="submit",
+    score=0.7,
+)
+```
+
+### Cloudflare Turnstile
+
+```python
+result = solver.turnstile(
+    sitekey="0x4AAAAAAA...",
+    url="https://example.com",
+)
+```
+
+### With a proxy (reCAPTCHA & Turnstile only)
+
+```python
+# Proxy is not supported for image captcha
+result = solver.recaptcha(
+    sitekey="...",
+    url="https://example.com",
+    proxy={"type": "HTTPS", "uri": "user:pass@1.2.3.4:3128"},
+)
+result = solver.turnstile(
+    sitekey="...",
+    url="https://example.com",
+    proxy={"type": "HTTP", "uri": "1.2.3.4:3128"},
+)
+```
+
+### Async (parallel solving)
+
+```python
+import asyncio
+from capskip import AsyncCapSkip
+
+async def main():
+    solver = AsyncCapSkip()
+    r1, r2 = await asyncio.gather(
+        solver.recaptcha(sitekey="...", url="https://a.com"),
+        solver.turnstile(sitekey="...", url="https://b.com"),
+    )
+    print(r1["code"], r2["code"])
+
+asyncio.run(main())
+```
+
+More examples: [`examples/`](examples/)
+
+---
+
+## Return value
+
+Every solve method returns:
+
+```python
+{
+    "captchaId": "12345",   # internal ID from CapSkip
+    "code": "TOKEN_OR_TEXT" # solution — text for image, token for reCAPTCHA/Turnstile
+    "userAgent": "..."      # Turnstile only — use when submitting challenge-page tokens
+}
+```
+
+---
+
+## Error handling
+
+```python
+from capskip import CapSkip, ValidationException, NetworkException, ApiException, TimeoutException
+
+try:
+    result = solver.recaptcha(sitekey="...", url="...")
+except ValidationException:
+    pass  # invalid parameters
+except NetworkException:
+    pass  # CapSkip not running, or captcha not ready (manual polling)
+except ApiException:
+    pass  # API returned an error code
+except TimeoutException:
+    pass  # polling timeout exceeded
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/capskip/capskip-python.git
+cd capskip-python
+python -m venv .venv
+
+# Windows
+.venv\Scripts\activate
+
+# Linux / macOS
+source .venv/bin/activate
+
+pip install -e ".[dev]"
+pytest
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development workflow.
+
+---
+
+## Links
+
+- [CapSkip website](https://capskip.com)
+- [CapSkip API docs](https://capskip.com/api-docs/)
+- [Report an issue](https://github.com/capskip/capskip-python/issues)
+- [PyPI package](https://pypi.org/project/capskip/) *(when published)*
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

capskip-1.0.0.dist-info/RECORD

@@ -0,0 +1,12 @@
+capskip/__init__.py,sha256=oOVghk5aU1WoSbXXEyk7GiETRYsO3Y26inPec5BG-Ac,597
+capskip/_api_params.py,sha256=zO3q-EEDxSPAYiKB0JkJSXRY1P2RRTdUYEYTSvmpvBA,3809
+capskip/api.py,sha256=tvCvTmFyz8U0PayJ1Et_Z_cI0JqKb1PiswZZyptFATc,1807
+capskip/async_api.py,sha256=7LgxNXPXlx0UdZ811KSNeC0Ua1qa7fiKYi_qyoX5DF0,2280
+capskip/async_solver.py,sha256=bbAeO7aw67CVI3BTs7f46ip-rcSe1Adakiw-NfbjBR8,5087
+capskip/exceptions.py,sha256=_dFHGjm_wc3DW1mpMtvuMiwDhpZyCL-U3gxRQDsE9d8,465
+capskip/solver.py,sha256=WGeQ8pU3SxLfXhYfOP8hbIJLpfd2caE3GZmtcwGeMTY,6138
+capskip-1.0.0.dist-info/licenses/LICENSE,sha256=hFVVci2vCCXeeP1G15tVusVHw_j2jiHM3WS9zEKjR1k,1064
+capskip-1.0.0.dist-info/METADATA,sha256=dB-zDZXQhkYCNYMbRO6fFnAr730LcbD_xgivnOqxyMc,8251
+capskip-1.0.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+capskip-1.0.0.dist-info/top_level.txt,sha256=_AHMAJcrez4g0s5jG_EON5kMwn9urg3mW-RgZxSvbas,8
+capskip-1.0.0.dist-info/RECORD,,

capskip-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

capskip-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CapSkip
+
+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.

capskip-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+capskip