Metadata-Version: 2.4
Name: whitelisthub
Version: 1.1.0
Summary: Official Python SDK for the WhitelistHub partner API
Author-email: WhitelistHub <admin@whitelisthub.net>
License-Expression: MIT
Project-URL: Homepage, https://whitelisthub.net
Project-URL: Documentation, https://whitelisthub.net/partner/docs
Keywords: whitelisthub,vpn,api,sdk,partner
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Typing :: Typed
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=5; extra == "dev"
Requires-Dist: pytest>=7; extra == "dev"
Dynamic: license-file

# WhitelistHub

Official Python client for the [WhitelistHub](https://whitelisthub.net) partner API.

- Pure Python, no third-party dependencies
- Keys, balance, pricing, dynamic VLESS API
- HMAC verification for outbound panel webhooks

## Install

```bash
pip install whitelisthub
```

## Quickstart

```python
from whitelisthub import PanelClient

client = PanelClient("https://whitelisthub.net", api_token="YOUR_TOKEN")
# [whitelisthub] whitelisthub.net — connected (42 ms) | balance 1500.00 RUB

key = client.keys.create(
    limit_gb=50,
    months=1,
    user_id="tg:1",
    idempotency_key="order-1",
)
print(key.subscription_url)
```

Disable the startup health check:

```python
client = PanelClient(
    "https://whitelisthub.net",
    api_token="YOUR_TOKEN",
    auto_connect=False,
)
```

From environment (`WHITELISTHUB_API_TOKEN`, optional `WHITELISTHUB_URL`):

```python
client = PanelClient.from_env()
```

## Keys

```python
client.keys.info(key.key_id)
client.keys.renew(key.key_id, months=1)
client.keys.expand(key.key_id, limit_gb=100)
client.keys.reset(key.key_id)
client.keys.ban(key.key_id, message="blocked")
client.keys.unban(key.key_id)
client.keys.delete(key.key_id)
```

## Webhooks

The panel signs outbound events with `X-Signature: sha256=<hmac>` over the
**raw request body**. Verify with the raw bytes (e.g. Flask `request.get_data()`),
not a re-encoded JSON document.

```python
from flask import Flask, request
from whitelisthub import verify_partner_webhook

app = Flask(__name__)

@app.post("/hooks/panel")
def panel_hook():
    data = verify_partner_webhook(
        request.get_data(),
        signature=request.headers.get("X-Signature"),
        secret="YOUR_WEBHOOK_SECRET",
        max_age_sec=600,
    )
    return {"ok": True, "event": data["event"]}
```

## Docs

- API reference: https://whitelisthub.net/partner/docs
- Packaging: https://packaging.python.org/en/latest/
