# Бот на Python

Бот раз в 5 секунд проверяет новые донаты и выводит в терминал те, что можно показать на стриме. Один файл, без дополнительных библиотек.

## Что нужно

- Python 3.9 или новее.
- Секретный ключ с правом `donations:read` в переменной `DONATTY_TOKEN`: [как сохранить](https://developers.donatty.com/quickstart/bot.md#2-сохраните-ключ-в-переменной).

## 1. Сохраните код

Скопируйте код в файл `bot.py`.

> **Имя и текст — чужой ввод.**
> Текст и имя донатера — чужой ввод: очищайте перед выводом в чат, оверлей или HTML. Пример заменяет управляющие символы пробелом, чтобы донатер не управлял вашим терминалом.

```python title="bot.py"
import json, os, re, sys, time, urllib.error, urllib.parse, urllib.request
from datetime import datetime, timedelta, timezone

API = "https://api.donatty.com"
TOKEN = os.environ.get("DONATTY_TOKEN") or sys.exit(
    "Задайте DONATTY_TOKEN: секретный ключ с правом donations:read")

SHOW = {"NONE", "PASSED"}
CONTROL = re.compile(r"[\x00-\x1f\x7f-\x9f\u2028\u2029\u202a-\u202e\u2066-\u2069]")  # чужой ввод: управляющие символы → пробел
shown = set()                        # id уже показанных донатов
waiting = {}                         # id → createdAt донатов, по которым модерация ещё не решила
boundary = datetime.now(timezone.utc)  # читаем донаты, созданные с момента запуска
failures = 0


class Retry(Exception):
    def __init__(self, message, after=None):
        super().__init__(message)
        self.after = after


def clean(text):
    return CONTROL.sub(" ", str(text))


def parse(ts):
    return datetime.fromisoformat(re.sub(r"(\.\d{6})\d+", r"\1", ts).replace("Z", "+00:00"))


def get(url):
    req = urllib.request.Request(url, headers={"Authorization": f"Bearer {TOKEN}"})
    try:
        with urllib.request.urlopen(req, timeout=10) as res:
            return json.load(res)
    except urllib.error.HTTPError as err:
        try:
            problem = json.load(err)
        except ValueError:
            problem = {}
        if err.code in (401, 403):
            sys.exit(f"{err.code} {problem.get('code')} {problem.get('type')}")
        after = int(err.headers.get("Retry-After", 5)) if err.code == 429 else None
        raise Retry(f"{err.code} {problem.get('code', '')}".strip(), after)
    except (urllib.error.URLError, OSError, ValueError) as err:
        raise Retry(str(err))


# Один проход: все страницы окна с одними и теми же параметрами.
def read_window():
    items, cursor = [], None
    while True:
        url = f"{API}/v1/donations?limit=100&since={boundary.isoformat().replace('+00:00', 'Z')}"
        if cursor:
            url += "&cursor=" + urllib.parse.quote(cursor, safe="")
        page = get(url)
        items += page["items"]
        cursor = page["nextCursor"]
        if not cursor:
            return items


def handle(items):
    global boundary
    seen = set()
    for d in reversed(items):  # от старых к новым
        seen.add(d["id"])
        status = d["moderation"]["status"]
        if status == "PENDING":
            waiting[d["id"]] = d["createdAt"]
            continue
        waiting.pop(d["id"], None)
        if status in SHOW and d["id"] not in shown:
            shown.add(d["id"])
            amount = d["amount"]
            fee = d.get("feeCompensation")
            extra = f' (+{fee["value"]} {fee["currency"]} за комиссию)' if fee else ""
            print(f'{clean(d["donorName"])} — {amount["value"]} {amount["currency"]}{extra}: {clean(d["message"])}', flush=True)
    for stale in [key for key in waiting if key not in seen]:
        del waiting[stale]
    if items:
        newest = max(parse(d["createdAt"]) for d in items) - timedelta(minutes=1)
        boundary = max(boundary, min([newest, *map(parse, waiting.values())]))


while True:
    pause = 5
    try:
        handle(read_window())
        failures = 0
    except Retry as error:
        failures += 1
        pause = error.after if error.after is not None else min(2 ** failures, 60)
        print(error, file=sys.stderr, flush=True)
    time.sleep(pause)
```

## 2. Запустите

В том же окне терминала, где вы сохранили ключ, перейдите в папку с файлом и выполните:


**macOS и Linux:**

```sh
python3 bot.py
```
**Windows (PowerShell):**

```powershell
py bot.py
```


## Что вы увидите

Бот показывает донаты, которые пришли после запуска, поэтому сначала в терминале пусто. Каждый новый донат, который можно показать на стриме, появится строкой:

```text
Alex — 500.00 RUB (+27.00 RUB за комиссию): Thanks for the stream!
```

Если донатер доплатил за комиссию, доплата показана в скобках; без доплаты скобок нет.

Проверить бота можно только настоящим донатом: «Тест на стриме» в кабинете показывает оповещение, но доната не создаёт, и в API его нет.

## Как это работает

- Бот читает донаты без фильтра модерации: так не теряется донат, который сначала ждал решения, а потом прошёл. Ожидающие `PENDING` он запоминает и перечитывает, пока модерация не решит.
- Выводятся только `NONE` и `PASSED`. `BLOCKED` и неизвестный статус бот не показывает.
- Бот читает все страницы, пока `nextCursor` не станет `null`. Следующий проход он начинает с более раннего из двух моментов: создание самого старого доната со статусом `PENDING` или создание самого нового доната минус минута. Уже показанные донаты пропускает по `id`.
- После `429` бот ждёт `Retry-After`. На `401` и `403` бот останавливается и печатает код ошибки со ссылкой на её страницу. Там сказано, что сделать с ключом. На 5xx и сетевых ошибках повторяет с паузой 2, 4, 8… секунд, не дольше минуты.
- Сумма — строка `value` и код валюты. Не переводите её в число с плавающей точкой.
- `feeCompensation` — доплата за комиссию в той же форме и валюте, или `null`; `amount` остаётся основной суммой.

## Ограничения примера

- После перезапуска бот начинает с текущего момента: что показано раньше, он не помнит.
- Донат, который появился в списке больше чем через минуту после своего создания, бот не увидит. Так бывает с донатами Donation Alerts после обрыва связи.
- Давно отклонённый донат, который вы вернули кнопкой «Повторить на стриме», бот тоже не увидит.

## Что поменять

- Замените `print` на отправку в чат или в оверлей. Имя и текст перед этим очистите.
- Пока новых донатов меньше 100, один проход — один запрос. Каждая следующая страница — ещё один запрос в счёт [лимита](https://developers.donatty.com/rate-limits.md).
