Metadata-Version: 2.4
Name: telegram-gateway-verification
Version: 0.1.0
Summary: Python client for Telegram Gateway verification API
Author: Demkin Denis
License-Expression: MIT
Keywords: telegram,otp,verification,gateway
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.31.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Dynamic: license-file

# telegram-gateway-verification

Python-библиотека для отправки кодов верификации через [Telegram Gateway API](https://core.telegram.org/gateway/api).

## Установка

```bash
pip install telegram-gateway-verification
```

Для разработки локально:

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

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

```python
from telegram_gateway_verification import TelegramGatewayClient

client = TelegramGatewayClient(api_token="YOUR_GATEWAY_TOKEN")

status = client.send_verification_message(
    phone_number="+15551234567",
    code_length=6,
    ttl=60,
    callback_url="https://example.com/webhooks/telegram-gateway",
)

print(status.request_id)
```

## Основные методы

- `send_verification_message(...)` -> `RequestStatus`
- `check_send_ability(phone_number=...)` -> `RequestStatus`
- `check_verification_status(request_id=..., code=...)` -> `RequestStatus`
- `revoke_verification_message(request_id=...)` -> `bool`

## Проверка подписи callback

Telegram отправляет заголовки `X-Request-Timestamp` и `X-Request-Signature`.

```python
from telegram_gateway_verification import verify_callback_signature

ok = verify_callback_signature(
    api_token="YOUR_GATEWAY_TOKEN",
    timestamp_header=request.headers["X-Request-Timestamp"],
    signature_header=request.headers["X-Request-Signature"],
    raw_body=request.get_data(),  # raw bytes тела запроса
)

if not ok:
    return "invalid signature", 403
```

## Важные детали из API

- `phone_number` должен быть в формате E.164 (`+15551234567`).
- `ttl` для `sendVerificationMessage`: от **30** до **3600** секунд.
- Если API отвечает `{"ok": false, ...}`, библиотека бросает `TelegramGatewayAPIError`.

## Ссылки

- API reference: https://core.telegram.org/gateway/api
- Overview: https://core.telegram.org/gateway
- Verification tutorial: https://core.telegram.org/gateway/verification-tutorial
