Merge pull request #1 from lexfrei/refactor/code-quality-overhaul

refactor: type-safe rewrite with tests, packaging, container and CI

Author: NetBUG

.containerignore

@@ -0,0 +1,18 @@
+.git
+.github
+.venv
+__pycache__/
+*.py[cod]
+*.session
+*.session-journal
+.env
+tests/
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+README*.md
+Containerfile
+.containerignore
+.gitignore

.env.example

@@ -5,3 +5,6 @@ API_ID=12345678
 API_HASH=1a2b3c4d5e6f1239983abcdef
 MUTE_TIMEOUT=3600
 SUMMARY_PREFIX="I've put together your %d messages:\n"
+# Optional. Session name or path; Telethon stores auth at $SESSION.session.
+# Leave unset to use the default ("userbot"; the container image uses /data/userbot).
+# SESSION=userbot

.github/workflows/ci.yml

@@ -0,0 +1,35 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@08807647e7069bb48b6ef5acd8ec9567f424441b # v8.1.0
+        with:
+          enable-cache: true
+
+      - name: Install dependencies
+        run: uv sync --locked
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Format
+        run: uv run ruff format --check .
+
+      - name: Type-check
+        run: uv run mypy bot.py
+
+      - name: Test
+        run: uv run pytest

.gitignore

@@ -1,11 +1,18 @@
-# Telethon session
+# Telethon session files (contain auth secrets — never commit)
 *.session
 *.session-journal
 
-# Environment
+# Local environment
 .env
 
 # Python
 __pycache__/
-*.pyc
-*.pyo
+*.py[cod]
+.venv/
+
+# Tooling caches
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/

Containerfile

@@ -0,0 +1,44 @@
+# syntax=docker/dockerfile:1
+
+# Build stage: resolve and install dependencies into a virtual environment.
+FROM ghcr.io/astral-sh/uv:python3.13-bookworm-slim AS builder
+
+ENV UV_COMPILE_BYTECODE=1 \
+    UV_LINK_MODE=copy \
+    UV_PYTHON_DOWNLOADS=0
+
+WORKDIR /app
+
+# Install dependencies from the lockfile in a cached, reproducible layer.
+# The project itself is not a package (tool.uv.package = false), so only
+# third-party dependencies land in the virtual environment.
+RUN --mount=type=cache,target=/root/.cache/uv \
+    --mount=type=bind,source=uv.lock,target=uv.lock \
+    --mount=type=bind,source=pyproject.toml,target=pyproject.toml \
+    uv sync --locked --no-dev
+
+COPY bot.py /app/bot.py
+
+# Runtime stage: a slim image without uv. The interpreter path must match the
+# builder image, hence the same python:3.13 base.
+FROM python:3.13-slim-bookworm
+
+RUN groupadd --system --gid 999 nonroot \
+    && useradd --system --gid 999 --uid 999 --create-home nonroot
+
+COPY --from=builder --chown=nonroot:nonroot /app /app
+
+# Put the virtual environment's executables first on PATH.
+ENV PATH="/app/.venv/bin:$PATH" \
+    PYTHONUNBUFFERED=1 \
+    SESSION=/data/userbot
+
+# Telethon persists its session at $SESSION.session; mount a volume on /data to
+# keep authentication across restarts.
+RUN install --directory --owner=nonroot --group=nonroot /data
+VOLUME ["/data"]
+
+USER nonroot
+WORKDIR /app
+
+ENTRYPOINT ["python", "bot.py"]

README.md

@@ -1,55 +1,89 @@
 # Telegram Abridger Userbot
 
-[English version](README_en.md)
+**English** · [中文](README.zh-CN.md) · [Русский](README.ru.md)
 
-## Что делает бот
-
-Юзербот входит в Telegram от имени пользователя и следит за входящими сообщениями во всех чатах, которые не заглушены и не находятся в архиве (чаты с topics игнорируются).
-
-Для каждого отправителя ведётся скользящее окно `COOLDOWN_INTERVAL` секунд:
-
-- Все входящие сообщения автоматически отмечаются прочитанными и накапливаются в буфер
-- Когда окно истекает, буфер склеивается через `MESSAGE_CONCAT_STRING` и отправляется в тот же чат без уведомления (silently); если задан `SUMMARY_PREFIX`, он добавляется в начало (`%d` → число сообщений)
-- Если отправитель превышает `MESSAGE_FREQUENCY_LIMIT` сообщений за окно, он сразу заглушается на `MUTE_TIMEOUT` секунд, а накопленный буфер отправляется досрочно
-- Если за `COOLDOWN_INTERVAL` в том же чате были исходящие сообщения (т.е. пользователь сам отвечал), суммари не отправляется — это нормальный ход разговора
+A self-account (MTProto) userbot that watches incoming messages, buffers them per sender over a sliding window, and—when a sender floods the window—joins the buffered messages into one silent summary and mutes the sender's notifications. If you reply in the chat yourself, the summary is suppressed: the conversation is clearly active.
 
 ## Requirements
 
-- Python 3.10+
-- `telethon`
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/)
 - Telegram API credentials (`API_ID`, `API_HASH`)
 
-### Получение API_ID и API_HASH
+### Getting API_ID and API_HASH
 
-1. Открыть https://my.telegram.org и войти по номеру телефона
-2. Перейти в **API development tools**
-3. Создать приложение (название и платформа — любые)
-4. Скопировать `App api_id` → `API_ID` и `App api_hash` → `API_HASH`
+1. Go to https://my.telegram.org and sign in with your phone number
+2. Navigate to **API development tools**
+3. Create an application (name and platform can be anything)
+4. Copy `App api_id` → `API_ID` and `App api_hash` → `API_HASH`
 
-### Config (env vars or `.env`)
+### Configuration (environment variables or `.env`)
 
 | Variable | Default | Description |
-|---|---|---|
-| `API_ID` | — | Telegram API ID |
-| `API_HASH` | — | Telegram API Hash |
-| `COOLDOWN_INTERVAL` | `300` | Окно наблюдения в секундах |
-| `MESSAGE_FREQUENCY_LIMIT` | `5` | Макс. сообщений за окно до mute |
-| `MESSAGE_CONCAT_STRING` | `, ` | Разделитель при склейке сообщений |
-| `MUTE_TIMEOUT` | `3600` | Длительность mute в секундах |
-| `SUMMARY_PREFIX` | _(нет)_ | Префикс перед склеенным сообщением; `%d` заменяется числом сообщений (например, `"Собрано %d сообщений:\n"`) |
+| --- | --- | --- |
+| `API_ID` | — | Telegram API ID (required) |
+| `API_HASH` | — | Telegram API hash (required) |
+| `COOLDOWN_INTERVAL` | `300` | Observation window in seconds |
+| `MESSAGE_FREQUENCY_LIMIT` | `5` | Max messages per window before muting |
+| `MESSAGE_CONCAT_STRING` | `, ` | Delimiter used to join buffered messages |
+| `MUTE_TIMEOUT` | `3600` | Mute duration in seconds |
+| `SUMMARY_PREFIX` | _(none)_ | Optional prefix prepended to the summary; `%d` is replaced with the message count (e.g. `"I've put together your %d messages:\n"`) |
+| `SESSION` | `userbot` | Telethon session name or path; auth is stored at `$SESSION.session` |
 
 ## Usage
 
 ```bash
-cp .env.example .env  # заполни API_ID и API_HASH
+cp .env.example .env  # fill in API_ID and API_HASH
 uv run bot.py
 ```
 
-`uv` сам установит зависимости из inline-метаданных скрипта (PEP 723) в изолированное окружение.
+`uv run` resolves and installs the dependencies from `pyproject.toml`/`uv.lock` into an isolated environment automatically — no manual setup is needed.
+
+On first run, Telethon will prompt for your phone number and a confirmation code, then write a `*.session` file. That file holds your authentication secret — keep it private and never commit it.
+
+## Running in a container
+
+The image builds dependencies in a `uv` stage and ships a slim, non-root runtime. The session is persisted on the `/data` volume so authentication survives restarts.
+
+```bash
+# Build
+docker build --tag telegram-abridger --file Containerfile .
+
+# First run: authenticate interactively, persisting the session to a named volume
+docker run --interactive --tty \
+  --env-file .env \
+  --volume abridger-session:/data \
+  telegram-abridger
+
+# Subsequent runs (already authenticated)
+docker run --detach --restart unless-stopped \
+  --env-file .env \
+  --volume abridger-session:/data \
+  telegram-abridger
+```
+
+The image sets `SESSION=/data/userbot`; leave `SESSION` unset in your `.env` so the session lands on the volume.
+
+## How it works
+
+The userbot monitors incoming messages from non-muted, non-archived chats (forum/topics chats are excluded). For each sender it maintains a sliding window of `COOLDOWN_INTERVAL` seconds:
 
-При первом запуске Telethon запросит номер телефона и код подтверждения.
+- Incoming messages are marked as read and added to a per-sender buffer
+- If a sender exceeds `MESSAGE_FREQUENCY_LIMIT` messages within the window, they are muted for `MUTE_TIMEOUT` seconds via Telegram's notification settings and their buffer is flushed immediately
+- Buffered messages are concatenated with `MESSAGE_CONCAT_STRING` and sent silently in the same chat; if `SUMMARY_PREFIX` is set, it is prepended to the summary (`%d` → message count)
+- Buffers are also flushed periodically once a sender's window goes quiet
+- If you sent any message in the same chat within `COOLDOWN_INTERVAL`, the summary is suppressed — the conversation is already active
+
+## Development
+
+```bash
+uv sync          # install runtime + dev dependencies
+uv run pytest    # run the test suite
+uv run ruff check . && uv run ruff format --check .
+uv run mypy bot.py
+```
 
-## Output / Result Files
+## Output / result files
 
-- `userbot.session` — файл сессии Telethon (не коммитить)
-- Логи выводятся в stdout
+- `$SESSION.session` (default `userbot.session`) — Telethon session file (do not commit)
+- Logs go to stdout

README.ru.md

@@ -0,0 +1,89 @@
+# Telegram Abridger Userbot
+
+[English](README.md) · [中文](README.zh-CN.md) · **Русский**
+
+Юзербот (MTProto, от имени аккаунта), который следит за входящими сообщениями, копит их по отправителю в скользящем окне и — когда отправитель заваливает окно — склеивает накопленные сообщения в одно беззвучное саммари и заглушает уведомления от него. Если ты сам ответил в этом чате, саммари не отправляется: разговор очевидно идёт.
+
+## Требования
+
+- Python 3.11+
+- [uv](https://docs.astral.sh/uv/)
+- Учётные данные Telegram API (`API_ID`, `API_HASH`)
+
+### Получение API_ID и API_HASH
+
+1. Открыть https://my.telegram.org и войти по номеру телефона
+2. Перейти в **API development tools**
+3. Создать приложение (название и платформа — любые)
+4. Скопировать `App api_id` → `API_ID` и `App api_hash` → `API_HASH`
+
+### Конфигурация (переменные окружения или `.env`)
+
+| Переменная | По умолчанию | Описание |
+| --- | --- | --- |
+| `API_ID` | — | Telegram API ID (обязательно) |
+| `API_HASH` | — | Telegram API hash (обязательно) |
+| `COOLDOWN_INTERVAL` | `300` | Окно наблюдения в секундах |
+| `MESSAGE_FREQUENCY_LIMIT` | `5` | Максимум сообщений за окно до mute |
+| `MESSAGE_CONCAT_STRING` | `, ` | Разделитель при склейке сообщений |
+| `MUTE_TIMEOUT` | `3600` | Длительность mute в секундах |
+| `SUMMARY_PREFIX` | _(нет)_ | Необязательный префикс перед саммари; `%d` заменяется числом сообщений (например, `"Собрано %d сообщений:\n"`) |
+| `SESSION` | `userbot` | Имя или путь сессии Telethon; авторизация хранится в `$SESSION.session` |
+
+## Запуск
+
+```bash
+cp .env.example .env  # заполни API_ID и API_HASH
+uv run bot.py
+```
+
+`uv run` сам разрешает и устанавливает зависимости из `pyproject.toml`/`uv.lock` в изолированное окружение — ручная настройка не нужна.
+
+При первом запуске Telethon запросит номер телефона и код подтверждения, затем создаст файл `*.session`. Этот файл содержит секрет авторизации — храни его в тайне и никогда не коммить.
+
+## Запуск в контейнере
+
+Образ собирает зависимости в стадии `uv` и поставляется как тонкий non-root рантайм. Сессия хранится на томе `/data`, поэтому авторизация переживает перезапуски.
+
+```bash
+# Сборка
+docker build --tag telegram-abridger --file Containerfile .
+
+# Первый запуск: интерактивная авторизация с сохранением сессии в именованный том
+docker run --interactive --tty \
+  --env-file .env \
+  --volume abridger-session:/data \
+  telegram-abridger
+
+# Последующие запуски (авторизация уже выполнена)
+docker run --detach --restart unless-stopped \
+  --env-file .env \
+  --volume abridger-session:/data \
+  telegram-abridger
+```
+
+Образ задаёт `SESSION=/data/userbot`; не задавай `SESSION` в своём `.env`, чтобы сессия попадала на том.
+
+## Как это работает
+
+Юзербот отслеживает входящие сообщения из не заглушённых и не архивных чатов (чаты с форумами/топиками исключаются). Для каждого отправителя ведётся скользящее окно `COOLDOWN_INTERVAL` секунд:
+
+- Входящие сообщения отмечаются прочитанными и добавляются в буфер по отправителю
+- Если отправитель превышает `MESSAGE_FREQUENCY_LIMIT` сообщений за окно, он заглушается на `MUTE_TIMEOUT` секунд через настройки уведомлений Telegram, а его буфер отправляется досрочно
+- Сообщения буфера склеиваются через `MESSAGE_CONCAT_STRING` и беззвучно отправляются в тот же чат; если задан `SUMMARY_PREFIX`, он добавляется в начало саммари (`%d` → число сообщений)
+- Буферы также периодически сбрасываются, когда окно отправителя затихает
+- Если ты отправил любое сообщение в этом же чате за `COOLDOWN_INTERVAL`, саммари подавляется — разговор уже активен
+
+## Разработка
+
+```bash
+uv sync          # установка runtime- и dev-зависимостей
+uv run pytest    # запуск тестов
+uv run ruff check . && uv run ruff format --check .
+uv run mypy bot.py
+```
+
+## Выходные файлы
+
+- `$SESSION.session` (по умолчанию `userbot.session`) — файл сессии Telethon (не коммитить)
+- Логи выводятся в stdout