Metadata-Version: 2.4
Name: telegram-gateway-verification
Version: 0.1.1
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.

## Возможности

- Отправка кода верификации (`sendVerificationMessage`)
- Проверка возможности отправки (`checkSendAbility`)
- Проверка статуса верификации (`checkVerificationStatus`)
- Отмена отправленного запроса (`revokeVerificationMessage`)
- Проверка подписи webhook callback (`X-Request-Timestamp`, `X-Request-Signature`)

## Установка

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

Установка для локальной разработки:

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

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

```python
import os

from telegram_gateway_verification import TelegramGatewayClient

client = TelegramGatewayClient(
    api_token=os.environ["TELEGRAM_GATEWAY_TOKEN"],  #https://gateway.telegram.org/account/api
)

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)
```

## API

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

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

```python
from telegram_gateway_verification import verify_callback_signature

ok = verify_callback_signature(
    api_token=os.environ["TELEGRAM_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
```

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

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

## Полезные ссылки

- Telegram Gateway API: https://core.telegram.org/gateway/api
- Telegram Gateway Overview: https://core.telegram.org/gateway
- Verification Tutorial: https://core.telegram.org/gateway/verification-tutorial
