Metadata-Version: 2.4
Name: v2hub-admin
Version: 1.0.0
Summary: Admin extension for V2Hub VPN Subscription API client
Project-URL: Homepage, https://github.com/nestt/v2hub-admin
Project-URL: Documentation, https://github.com/nestt/v2hub-admin#readme
Project-URL: Repository, https://github.com/nestt/v2hub-admin
Project-URL: Issues, https://github.com/nestt/v2hub-admin/issues
Author-email: nestt <nestt@example.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 API extension for V2Hub with HMAC-SHA256 authentication for privileged operations.

## Features

- 🔐 **HMAC Authentication**: SHA-256 signature-based authentication
- 🎯 **Admin Operations**: Manage all subscriptions across the system
- 🔄 **Async & Sync**: Both `AsyncAdminClient` and `AdminClient`
- 📦 **Inherits V2Hub**: Built on top of the main v2hub library
- 🛡️ **Type Safe**: Full type hints and Pydantic models

## Installation

```bash
# Install v2hub-admin (will automatically install v2hub as dependency)
pip install v2hub-admin
```

## Quick Start

### Async Usage

```python
from v2hub_admin import AsyncAdminClient

async with AsyncAdminClient(
    base_url="https://api.example.com",
    api_token="your-admin-token",
    hmac_secret="your-hmac-secret"
) as admin:
    # List all subscriptions in the system
    all_subs = await admin.list_all_subscriptions()

    # Get any subscription by token
    sub = await admin.get_any_subscription("sub_token_123")

    # Delete any subscription (admin privilege)
    await admin.delete_any_subscription("sub_token_123")
```

### Sync Usage

```python
from v2hub_admin import AdminClient

with AdminClient(
    base_url="https://api.example.com",
    api_token="your-admin-token",
    hmac_secret="your-hmac-secret"
) as admin:
    # List all subscriptions
    all_subs = admin.list_all_subscriptions()

    # Get statistics
    stats = admin.get_statistics()
    print(f"Total subscriptions: {stats['total_subscriptions']}")
```

## HMAC Authentication

The admin client uses HMAC-SHA256 for request signing:

```python
import hmac
import hashlib
from datetime import datetime

# The library handles this automatically
# This is just for understanding

timestamp = datetime.utcnow().isoformat()
message = f"DELETE:/admin/subscriptions/{token}:{timestamp}"
signature = hmac.new(
    secret.encode(),
    message.encode(),
    hashlib.sha256
).hexdigest()
```

## Admin API Endpoints

### Subscriptions

- `list_all_subscriptions()` - List all subscriptions in system
- `get_any_subscription(token)` - Get any subscription (bypass ownership)
- `delete_any_subscription(token)` - Delete any subscription (admin privilege)

### Statistics (if available)

- `get_statistics()` - Get system-wide statistics
- `get_user_stats(user_id)` - Get stats for specific user

## Error Handling

Inherits all exception types from v2hub:

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

async with AsyncAdminClient(base_url, token, secret) as admin:
    try:
        await admin.delete_any_subscription("token123")
    except AuthenticationError:
        print("Invalid HMAC signature or credentials")
    except AuthorizationError:
        print("Insufficient admin privileges")
    except VPNAPIError as e:
        print(f"API error: {e}")
```

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Type checking
mypy src/
```

## Requirements

- **v2hub** >= 1.0.0 (automatically installed)
- Python >= 3.9

## CLI Integration

Works seamlessly with [v2hub-cli](https://github.com/nestthub/v2hub-cli):

```bash
# Install CLI with admin support
pip install v2hub-cli[admin]

# Use admin commands
v2hub admin list-all
v2hub admin delete-any <token>
v2hub admin stats
```

## Security Notes

⚠️ **Important**:

- Store HMAC secrets securely (environment variables, secret managers)
- Never commit secrets to version control
- Use HTTPS in production
- Rotate secrets regularly
- Admin tokens have elevated privileges - protect them carefully

## License

MIT License - see LICENSE file for details.

## Author

nestt
