Metadata-Version: 2.4
Name: v2hub-admin
Version: 1.0.1
Summary: Admin extension for V2Hub VPN Subscription API client
Project-URL: Homepage, https://github.com/nestthub/v2hub-admin
Project-URL: Documentation, https://github.com/nestthub/v2hub-admin#readme
Project-URL: Repository, https://github.com/nestthub/v2hub-admin
Project-URL: Issues, https://github.com/nestthub/v2hub-admin/issues
Author-email: nestt <nestt@tutamail.com>
License: MIT
License-File: LICENSE
Keywords: admin,api,client,subscription,vpn
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.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Typing :: Typed
Requires-Python: >=3.9
Requires-Dist: httpx>=0.25.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: v2hub>=1.0.0
Provides-Extra: dev
Requires-Dist: mypy>=1.5.0; extra == 'dev'
Requires-Dist: pre-commit>=3.4.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.11.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# V2Hub Admin — Admin Extension for VPN Subscription API

## Admin-расширение для V2Hub, предоставляющее привилегированные операции управления пользователями и IP через HMAC-SHA256 аутентификацию.

## Features

- 🔐 **HMAC Authentication** (SHA-256 подпись)
- 👤 **User Management API** (CRUD пользователей)
- 🚫 **IP Ban System**
- ✅ **Whitelist Management**
- 🔄 **Async & Sync клиенты**
- 📦 Основан на `v2hub`
- 🛡️ Полная типизация (type hints + Pydantic)

---

## Installation

```bash
pip install v2hub-admin
```

---

## Quick Start

## Async Usage

```python
from v2hub_admin import AsyncAdminClient

async with AsyncAdminClient(
    base_url="https://api.example.com",
    secret_key="your-hmac-secret"
) as admin:

    user = await admin.get_user(12345)
    print(user)
```

---

## Sync Usage

```python
from v2hub_admin import AdminClient

with AdminClient(
    base_url="https://api.example.com",
    secret_key="your-hmac-secret"
) as admin:

    user = admin.get_user(12345)
    print(user)
```

---

# Admin API

## 👤 User Management

```python
admin.create_user(user_id: int)
admin.get_user(user_id: int)
admin.delete_user(user_id: int)
admin.set_user_status(user_id: int, is_active: bool)
admin.refresh_token(user_id: int)
```

### Example

```python
user = admin.create_user(12345)
print(user.api_token)

user = admin.set_user_status(12345, False)
print(user.is_active)
```

---

## 🚫 IP Ban Management

```python
admin.ban_ip(ip_address: str, duration_seconds: int | None = None)
admin.unban_ip(ip_address: str)
admin.get_ban_status(ip_address: str)
admin.get_ban_list()
```

### Example

```python
ban = admin.ban_ip("192.168.1.100", duration_seconds=3600)
print(ban.banned_until)

status = admin.get_ban_status("192.168.1.100")
print(status.is_banned)
```

---

## ✅ Whitelist Management

```python
admin.add_to_whitelist(ip_address: str, description: str | None = None)
admin.remove_from_whitelist(ip_address: str)
admin.list_whitelist()
```

### Example

```python
admin.add_to_whitelist("10.0.0.0/24", description="Office network")

whitelist = admin.list_whitelist()
for entry in whitelist.entries:
    print(entry.ip_address, entry.description)
```

---

## ⚠️ Error Handling

Все ошибки наследуются из `v2hub`:

```python
from v2hub import VPNAPIError, AuthenticationError, AuthorizationError

try:
    admin.delete_user(12345)
except AuthenticationError:
    print("Invalid HMAC signature")
except AuthorizationError:
    print("No admin privileges")
except VPNAPIError as e:
    print(e)
```

---

## Development

```bash
pip install -e ".[dev]"

pytest
mypy src/
```

---

## Requirements

- Python >= 3.9
- v2hub >= 1.0.0

---

## Security Notes

⚠️ Важно:

- Не храните secret_key в коде
- Используйте env / secret managers
- Только HTTPS в production
- Регулярно ротируйте ключи
- Admin API имеет полный доступ к системе

---

## License

MIT

---

## Author

nestt
