# Cosmo VPN Panel — Python SDK

Python-клиент для [Seller API](https://github.com/cosmo-vpn/cosmo-panel) панели Cosmo VPN.

## Установка

### Через pip

```bash
pip install cosmo-panel
```

### Из исходников

```bash
git clone https://github.com/cosmo-vpn/cosmo-panel-sdk.git
cd sdk/python
pip install -e .
```

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

Только `urllib3` (без внешних зависимостей).

## Быстрый старт

```python
from cosmo_panel import CosmoClient, CosmoError, CosmoRequestError

# Создаём клиент
client = CosmoClient(
    api_key="wgp_your_api_key_here",
    base_url="http://163.5.153.53:8000",
)

# Создаём новый VPN-ключ
key = client.create_key(
    name="Иван Петров",
    days=30,
    traffic_gb=50,
    email="ivan@example.com",
)
print(f"Создан ключ: {key['id']}")

# Получаем список всех ключей
keys = client.list_keys()
for k in keys.get("items", []):
    print(f"  {k['id']}: {k['name']}")

# Детали конкретного ключа
info = client.get_key(key["id"])
print(f"Статус: {info['status']}")

# Продлеваем на 30 дней
client.extend_key(key["id"], days=30)

# Добавляем 10 ГБ трафика
client.add_traffic(key["id"], gb=10)

# Приостанавливаем ключ
client.suspend_key(key["id"])

# Активируем обратно
client.activate_key(key["id"])

# Изменяем параметры
client.update_key(key["id"], name="Пётр Иванов", max_devices=3)

# Включаем обфускацию и блокировку рекламы
client.update_key_features(key["id"], obfuscation=True, adblock=True)

# Скачиваем конфиг
config = client.get_key_config(key["id"])
with open("vpn.conf", "wb") as f:
    f.write(config)

# Удаляем ключ
client.delete_key(key["id"])
```

## Обработка ошибок

```python
from cosmo_panel import CosmoClient, CosmoError, CosmoRequestError

client = CosmoClient(api_key="wgp_...", base_url="http://163.5.153.53:8000")

try:
    key = client.create_key(name="Тест", days=30, traffic_gb=10)
except CosmoRequestError as e:
    print(f"Ошибка сети: {e}")
except CosmoError as e:
    print(f"Ошибка API ({e.status_code}): {e}")
```

## Настройка

```python
client = CosmoClient(
    api_key="wgp_...",
    base_url="http://163.5.153.53:8000",
    timeout=60.0,      # Таймаут запроса (сек)
    max_retries=5,     # Максимум повторных попыток
)
```

### Поведение при ошибках

- **Таймауты / ошибки соединения**: автоматический повтор до `max_retries` раз с экспоненциальной задержкой.
- **Rate-limit (429)**: автоматическое ожидание согласно заголовку `Retry-After` или экспоненциальный backoff.
- **Ошибки сервера (5xx)**: автоматический повтор.
- **Ошибки клиента (4xx)**: исключение `CosmoError` без повтора.

## Все методы

| Метод | HTTP | Эндпоинт | Описание |
|-------|------|----------|----------|
| `create_key(...)` | POST | `/api/v1/keys` | Создать ключ |
| `list_keys(...)` | GET | `/api/v1/keys` | Список ключей |
| `get_key(id)` | GET | `/api/v1/keys/{id}` | Детали ключа |
| `get_key_config(id)` | GET | `/api/v1/keys/{id}/config` | Скачать конфиг |
| `extend_key(id, days)` | POST | `/api/v1/keys/{id}/extend` | Продлить ключ |
| `add_traffic(id, gb)` | POST | `/api/v1/keys/{id}/traffic` | Добавить трафик |
| `suspend_key(id)` | POST | `/api/v1/keys/{id}/suspend` | Приостановить |
| `activate_key(id)` | POST | `/api/v1/keys/{id}/activate` | Активировать |
| `update_key(id, ...)` | PATCH | `/api/v1/keys/{id}` | Изменить параметры |
| `update_key_features(id, ...)` | PATCH | `/api/v1/keys/{id}/features` | Изменить функции |
| `delete_key(id)` | DELETE | `/api/v1/keys/{id}` | Удалить ключ |

## Лицензия

MIT