Metadata-Version: 2.4
Name: ghostcaptcha-client
Version: 1.0.0
Summary: Official Python client for GhostCaptcha API — sync/async captcha solving
Home-page: https://github.com/ghostcaptchareal/ghostcaptcha-client
Author: GhostCaptcha
Author-email: support@ghostcaptcha.xyz
Project-URL: Source, https://github.com/ghostcaptchareal/ghostcaptcha-client
Project-URL: Bug Tracker, https://github.com/ghostcaptchareal/ghostcaptcha-client/issues
Project-URL: Documentation, https://ghostcaptcha.xyz/docs
Keywords: hcaptcha captcha solver api ghostcaptcha async captcha-solving
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
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 :: Internet :: WWW/HTTP
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: httpx>=0.27.0
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: project-url
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

<p align="center">
  <img src="https://ghostcaptcha.xyz/logo.png" alt="GhostCaptcha" width="120"/>
</p>

<h1 align="center">GhostCaptcha Client</h1>

<p align="center">
  <strong>Official Python client for the GhostCaptcha API</strong>
</p>

<p align="center">
  <a href="https://pypi.org/project/ghostcaptcha-client/"><img src="https://img.shields.io/pypi/v/ghostcaptcha-client?color=blue&logo=pypi&logoColor=white" alt="PyPI version"></a>
  <a href="https://pypi.org/project/ghostcaptcha-client/"><img src="https://img.shields.io/pypi/pyversions/ghostcaptcha-client?color=blue" alt="Python versions"></a>
  <a href="https://github.com/ghostcaptchareal/ghostcaptcha-client"><img src="https://img.shields.io/badge/github-ghostcaptchareal/ghostcaptcha--client-8B5CF6?logo=github" alt="GitHub"></a>
</p>

---

GhostCaptcha Client, hCaptca çözüm API'si için yazılmış, production-grade Python kütüphanesidir.
Senkron ve asenkron istemci, bağlantı havuzu, otomatik yeniden deneme,
ve kapsamlı hata yönetimi sunar.

## Features

- **Dual Client** — Sync (`GhostCaptchaClient`) + Async (`AsyncGhostCaptchaClient`)
- **Connection Pooling** — Single httpx connection pool, auto cleanup
- **Rate Limit Auto-Retry** — 429 hatasında `Retry-After` başlığını okuyup bekler
- **Proxy Support** — HTTP/HTTPS proxy, `set_proxy()` ile canlı değiştirme
- **Debug Mode** — `enable_debug()` ile detaylı request/response loglama
- **Device Registration** — HWID/MAC/CPU toplama (Windows/Linux/Mac)
- **TypedDict Responses** — IDE otocomplete ile tip güvenli yanıtlar
- **YesCaptcha Compatible** — `createTask`, `getTaskResult`, `getBalance`

## Installation

```bash
pip install ghostcaptcha-client
```

Requires Python 3.9+ and httpx.

## Quick Start

```python
from ghostcaptcha_client import GhostCaptchaClient

client = GhostCaptchaClient("hcap-xxx...")
print(client.get_balance())
client.close()
```

```python
import asyncio
from ghostcaptcha_client import AsyncGhostCaptchaClient

async def main():
    async with AsyncGhostCaptchaClient("hcap-xxx...") as client:
        print(await client.get_balance())

asyncio.run(main())
```

## API Reference

### Constructor Options

| Parameter | Default | Description |
|-----------|---------|-------------|
| `api_key` | — | Your API key (hcap-...) |
| `base_url` | production | API base URL (can also set `GHOSTCAPTCHA_API_URL` env) |
| `verify_ssl` | `True` | SSL certificate verification |
| `timeout` | `60` | Request timeout in seconds |
| `auto_register` | `False` | Auto-register device info on init |
| `proxy` | `None` | Proxy URL (e.g. `http://user:pass@host:8080`) |

### Configuration

```python
client = GhostCaptchaClient("hcap-xxx...")

client.enable_debug()             # Enable debug logging
client.set_proxy("http://proxy:8080")  # Set HTTP proxy
```

### Captcha Solving

| Method | Returns | Description |
|--------|---------|-------------|
| `solve(image_bytes)` | `dict` | Solve from raw image bytes |
| `solve_file(path)` | `dict` | Solve from image file |
| `solve_base64(b64)` | `dict` | Solve from base64-encoded image |

```python
result = client.solve_file("captcha.png")
print(result["actions"])  # [{"x": 120, "y": 340}, ...]
```

### YesCaptcha-Compatible

| Method | Returns | Description |
|--------|---------|-------------|
| `get_balance()` | `dict` | Get account balance |
| `get_soft_id()` | `str` | Get Soft ID |
| `create_task(task)` | `str` | Create solving task (returns taskId) |
| `get_task_result(task_id)` | `dict` | Poll for task result |
| `wait_for_result(task_id)` | `dict` | Poll with auto-retry until ready |

```python
task_id = client.create_task({
    "type": "HCaptchaClassification",
    "queries": ["base64_encoded_image"],
})

result = client.wait_for_result(task_id, poll_interval=0.5, timeout=120)
```

## Error Handling

```python
from ghostcaptcha_client import (
    GhostCaptchaError, AuthError, RateLimitError,
    BalanceError, NetworkError,
)

try:
    balance = client.get_balance()
except AuthError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except BalanceError:
    print("Insufficient balance")
except NetworkError:
    print("Connection error")
except GhostCaptchaError as e:
    print(f"API error [{e.code}]: {e.description}")
```

| Exception | HTTP Status | Description |
|-----------|-------------|-------------|
| `AuthError` | 401 | Invalid or missing API key |
| `RateLimitError` | 429 | Too many requests (auto-retries with `Retry-After`) |
| `BalanceError` | 401 | Insufficient credits |
| `NetworkError` | — | Connection or timeout error |
| `GhostCaptchaError` | varies | Base exception for all API errors |

## Context Managers

```python
# Sync
with GhostCaptchaClient("hcap-xxx...") as client:
    balance = client.get_balance()

# Async
async with AsyncGhostCaptchaClient("hcap-xxx...") as client:
    balance = await client.get_balance()
```

## Device Registration

Auto-collects HWID, CPU ID, MAC address, and OS info for device-bound licensing.
Works on Windows (WMI/PowerShell), Linux (sysfs/dmidecode), and macOS (system_profiler).

```python
client = GhostCaptchaClient("hcap-xxx...", auto_register=True)
print(client.device_id)  # UUID if registration succeeded
```

## Wait for Result (Polling)

Automatically polls `get_task_result` until the task completes or times out:

```python
# Sync
result = client.wait_for_result(task_id, poll_interval=0.5, timeout=120)

# Async
result = await client.wait_for_result(task_id, poll_interval=0.5, timeout=120)
```

## Connection Pooling

Both clients use a single `httpx.Client` / `httpx.AsyncClient` instance with
connection pooling. For manual resource management:

```python
client = GhostCaptchaClient("hcap-xxx...")
# ... use client ...
client.close()  # Frees the connection pool
```

## Testing

```bash
GHOSTCAPTCHA_API_URL=http://api.ghostcaptcha.xyz/v1 python -m pytest tests/ -v
```

---

<p align="center">
  Made with ❤️ by <a href="https://ghostcaptcha.xyz">GhostCaptcha</a> · <a href="https://github.com/ghostcaptchareal/ghostcaptcha-client">GitHub</a>
</p>
