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

```
amnezio/
├── src/
│   └── amnezio/
│       ├── __init__.py          # Экспорт основных классов
│       ├── client.py            # AmnezioClient - основной клиент
│       ├── users.py             # UsersAPI - работа с пользователями
│       ├── profiles.py          # ProfilesAPI - работа с профилями
│       ├── nodes.py             # NodesAPI - работа с нодами
│       ├── models.py            # Pydantic модели данных
│       ├── exceptions.py        # Исключения SDK
│       └── types.py             # Type hints
│
├── tests/
│   ├── conftest.py              # Pytest фикстуры
│   ├── test_client.py           # Тесты клиента
│   └── test_users.py            # Тесты Users API
│
├── examples/
│   ├── basic_usage.py           # Базовое использование
│   ├── telegram_bot.py          # Создание пользователя через Telegram
│   ├── subscription_management.py  # Управление подписками
│   └── telegram_bot_integration.py # Полная интеграция с Telegram ботом
│
├── pyproject.toml               # Конфигурация проекта
├── README.md                    # Основная документация
├── INSTALL.md                   # Инструкция по установке
├── CHANGELOG.md                 # История изменений
├── LICENSE                      # MIT лицензия
├── pytest.ini                   # Конфигурация pytest
├── .gitignore                   # Git ignore
└── test_sdk.py                  # CLI утилита для тестирования
```

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

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

### Для разработки
- `pytest>=8.0.0` - Тестовый фреймворк
- `pytest-asyncio>=0.23.0` - Поддержка async тестов
- `pytest-cov>=4.1.0` - Покрытие кода тестами

## Архитектура

### AmnezioClient
Основной класс для работы с API панели. Управляет аутентификацией и HTTP запросами.

**Возможности:**
- Автоматическая аутентификация при первом запросе
- Повторная аутентификация при 401
- Поддержка контекстного менеджера
- Управление HTTP клиентом

### API классы
Каждый API класс (UsersAPI, ProfilesAPI, NodesAPI) инкапсулирует работу с соответствующим эндпоинтом.

**UsersAPI** - управление пользователями VPN:
- CRUD операции
- Получение конфига и QR-кода
- Управление статусом и подпиской
- Генерация ключей

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

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

### Модели данных
Pydantic модели для валидации и сериализации:
- `User` - пользователь VPN
- `Profile` - профиль (шаблон конфига)
- `Node` - нода (сервер)
- `KeyPair` - пара ключей WireGuard
- `UserConfig` - конфиг пользователя
- `PaginatedResponse` - пагинированный ответ

### Обработка ошибок
Иерархия исключений:
- `AmnezioError` - базовое исключение
  - `AuthenticationError` - ошибка аутентификации
  - `NotFoundError` - ресурс не найден
  - `APIError` - ошибка API (содержит status_code и message)

## Использование

### Базовый пример

```python
from amnezio import AmnezioClient

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
    )
    
    # Получение конфига
    config = await client.users.get_config(user.id)
```

### Интеграция с Telegram ботом

```python
from amnezio import AmnezioClient

async def create_vpn_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
        )
        return await client.users.get_config(user.id)
```

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

### Запуск тестов
```bash
cd amnezio
pytest
```

### Покрытие кода
```bash
pytest --cov=amnezio --cov-report=html
```

### CLI утилита
```bash
./test_sdk.py --url https://panel.example.com --username admin --password secret
```

## Публикация

### Локальная установка
```bash
pip install -e .
```

### Сборка пакета
```bash
python -m build
```

### Публикация на PyPI
```bash
python -m twine upload dist/*
```

## Roadmap

### v0.2.0
- [ ] Поддержка WebSocket для real-time обновлений
- [ ] Batch операции для массового создания пользователей
- [ ] Кэширование токена аутентификации
- [ ] Retry логика для failed запросов

### v0.3.0
- [ ] CLI утилита как отдельный пакет
- [ ] Синхронная версия клиента
- [ ] Поддержка API ключей (альтернатива username/password)
- [ ] Метрики и статистика использования

### v1.0.0
- [ ] Полное покрытие тестами (>90%)
- [ ] Документация на ReadTheDocs
- [ ] Примеры интеграции с популярными фреймворками
- [ ] Stable API
