# Amnezio Python SDK - Полный обзор

## Что это?

**Amnezio SDK** — это Python библиотека для работы с панелью управления AmneziaWG VPN. SDK предоставляет удобный интерфейс для автоматизации управления пользователями, профилями и серверами VPN.

## Основные возможности

✅ **Управление пользователями**
- Создание, чтение, обновление, удаление пользователей
- Генерация ключей WireGuard
- Получение конфигов и QR-кодов
- Управление статусом (включение/отключение)
- Продление подписок

✅ **Управление профилями**
- CRUD операции для профилей (шаблонов конфигов)
- Настройка параметров AmneziaWG обфускации

✅ **Управление нодами (серверами)**
- CRUD операции для нод
- Синхронизация с серверами
- Push конфигов
- Перезапуск AmneziaWG

✅ **Дополнительно**
- Асинхронный API на базе httpx
- Автоматическая аутентификация
- Обработка ошибок
- Type hints
- Pydantic модели

## Установка

```bash
cd amnezio
pip install -e .
```

## Быстрый пример

```python
from amnezio import AmnezioClient
from datetime import date, timedelta

async with AmnezioClient(
    base_url="https://panel.example.com",
    username="admin",
    password="secret"
) as client:
    # Создание пользователя
    keypair = await client.users.generate_keypair()
    user = await client.users.create(
        sub_id="user123",
        private_key=keypair.private_key,
        profile_id=1,
        paid_for=date.today() + timedelta(days=30)
    )
    
    # Получение конфига
    config = await client.users.get_config(user.id)
    print(config.config)
```

## Структура проекта

```
amnezio/
├── src/amnezio/          # Исходный код SDK
│   ├── client.py         # Основной клиент
│   ├── users.py          # API пользователей
│   ├── profiles.py       # API профилей
│   ├── nodes.py          # API нод
│   ├── models.py         # Модели данных
│   ├── exceptions.py     # Исключения
│   └── types.py          # Type hints
│
├── examples/             # Примеры использования
│   ├── basic_usage.py                    # Базовое использование
│   ├── telegram_bot.py                   # Создание через Telegram
│   ├── subscription_management.py        # Управление подписками
│   ├── telegram_bot_integration.py       # Полная интеграция с ботом
│   └── advanced_subscription_system.py   # Автоматизация подписок
│
├── tests/                # Тесты
└── docs/                 # Документация
```

## API методы

### Users API

```python
# Создание
user = await client.users.create(sub_id, private_key, profile_id, ...)

# Чтение
user = await client.users.get(user_id)
users = await client.users.list(page=1, per_page=50)

# Обновление
user = await client.users.update(user_id, status="active", ...)

# Удаление
await client.users.delete(user_id)

# Конфиг и QR-код
config = await client.users.get_config(user_id)
qrcode = await client.users.get_qrcode(user_id)

# Управление
user = await client.users.enable(user_id)
user = await client.users.disable(user_id)
user = await client.users.renew_subscription(user_id, paid_for)

# Утилиты
keypair = await client.users.generate_keypair()
```

### Profiles API

```python
# CRUD
profile = await client.profiles.create(name, listen_port, ...)
profile = await client.profiles.get(profile_id)
profiles = await client.profiles.list()
profile = await client.profiles.update(profile_id, ...)
await client.profiles.delete(profile_id)
```

### Nodes API

```python
# CRUD
result = await client.nodes.create(name, host, port=9999, node_type="awg")
node = await client.nodes.get(node_id)
nodes = await client.nodes.list()
node = await client.nodes.update(node_id, ...)
await client.nodes.delete(node_id)

# Управление
result = await client.nodes.push_config(node_id)
result = await client.nodes.restart(node_id)
```

## Примеры использования

### Telegram бот

```python
from amnezio import AmnezioClient

async def create_vpn_for_user(telegram_id: int):
    async with AmnezioClient(...) as client:
        keypair = await client.users.generate_keypair()
        user = await client.users.create(
            sub_id=f"tg_{telegram_id}",
            telegram_id=telegram_id,
            private_key=keypair.private_key,
            profile_id=1,
            paid_for=date.today() + timedelta(days=30)
        )
        return await client.users.get_config(user.id)
```

### Автоматизация подписок

```python
# Проверка истекающих подписок
expiring = await client.users.list()
for user in expiring.items:
    if user.paid_for and user.paid_for < date.today():
        await client.users.disable(user.id)
        # Отправить уведомление

# Продление подписки после оплаты
user = await client.users.renew_subscription(
    user_id,
    paid_for=date.today() + timedelta(days=30)
)
```

### FastAPI интеграция

```python
from fastapi import FastAPI
from amnezio import AmnezioClient

app = FastAPI()

@app.post("/vpn/create")
async def create_vpn(user_id: str):
    async with AmnezioClient(...) as client:
        keypair = await client.users.generate_keypair()
        user = await client.users.create(
            sub_id=user_id,
            private_key=keypair.private_key,
            profile_id=1
        )
        config = await client.users.get_config(user.id)
        return {"config": config.config}
```

## Документация

📚 Полная документация:
- `README.md` - Основная документация и API
- `QUICKSTART.md` - Быстрый старт за 5 минут
- `INSTALL.md` - Детальная установка и примеры
- `STRUCTURE.md` - Архитектура и устройство SDK
- `CHANGELOG.md` - История изменений
- `examples/` - Рабочие примеры кода

## Тестирование

```bash
# Установка с dev зависимостями
pip install -e ".[dev]"

# Запуск тестов
pytest

# С покрытием
pytest --cov=amnezio --cov-report=html

# CLI тестирование
./test_sdk.py --url https://panel.example.com --username admin --password secret
```

## Зависимости

**Основные:**
- `httpx>=0.27.0` - Асинхронный HTTP клиент
- `pydantic>=2.0.0` - Валидация данных

**Для разработки:**
- `pytest>=8.0.0`
- `pytest-asyncio>=0.23.0`
- `pytest-cov>=4.1.0`

## Roadmap

### v0.2.0
- WebSocket поддержка для real-time обновлений
- Batch операции
- Retry логика
- Кэширование токенов

### v0.3.0
- CLI утилита
- Синхронная версия клиента
- API ключи

### v1.0.0
- Полное покрытие тестами (>90%)
- Stable API
- Публикация на PyPI

## Примеры реальных кейсов

### 1. Telegram бот с оплатой
- Пользователь оплачивает через Telegram
- Бот создает VPN подписку через SDK
- Отправляет конфиг и QR-код
- Автоматически проверяет истечение

### 2. Web-панель для клиентов
- FastAPI backend использует SDK
- Клиенты управляют подписками через веб
- Автоматическое продление после оплаты

### 3. Автоматизация для провайдера
- Массовое создание пользователей
- Мониторинг истечений
- Автоматическое отключение
- Статистика и отчеты

### 4. Интеграция с биллингом
- Синхронизация с системой оплаты
- Автоматическое продление при оплате
- Уведомления об истечении

## Поддержка

- 📧 Email: support@example.com
- 💬 Telegram: @amnezio_support
- 🐛 Issues: https://github.com/amnezio/amnezio/issues
- 📖 Docs: https://github.com/amnezio/amnezio#readme

## Лицензия

MIT License - свободное использование в коммерческих и некоммерческих проектах.

---

**Amnezio SDK** - Простое и мощное управление AmneziaWG VPN 🚀
