telegram-assistant 0.2.1__tar.gz

telegram_assistant-0.2.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stanislav Popov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

telegram_assistant-0.2.1/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: telegram-assistant
+Version: 0.2.1
+Summary: Telegram automation service (MTProto/Telethon) with an optional Planfix integration plugin.
+Author-email: Stanislav Popov <popstas@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/popstas/telegram-assistant
+Project-URL: Repository, https://github.com/popstas/telegram-assistant
+Project-URL: Bug Tracker, https://github.com/popstas/telegram-assistant/issues
+Keywords: telegram,telethon,automation,mtproto,planfix
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Framework :: FastAPI
+Classifier: Topic :: Communications :: Chat
+Classifier: Operating System :: OS Independent
+Classifier: License :: OSI Approved :: MIT License
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: telethon<2.0,>=1.36
+Requires-Dist: fastapi<1.0,>=0.115
+Requires-Dist: uvicorn[standard]<1.0,>=0.30
+Requires-Dist: pydantic<3.0,>=2.7
+Requires-Dist: pyyaml<7.0,>=6.0
+Requires-Dist: typer<1.0,>=0.12
+Requires-Dist: structlog<25.0,>=24.1
+Requires-Dist: SQLAlchemy<3.0,>=2.0
+Requires-Dist: httpx<1.0,>=0.27
+Requires-Dist: python-socks[asyncio]<3.0,>=2.4
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio<1.0,>=0.23; extra == "dev"
+Requires-Dist: ruff<1.0,>=0.5; extra == "dev"
+Requires-Dist: git-cliff>=2.0.0; extra == "dev"
+Requires-Dist: pre-commit<5.0,>=3.7; extra == "dev"
+Requires-Dist: build<2.0,>=1.2; extra == "dev"
+Requires-Dist: twine<7.0,>=5.0; extra == "dev"
+Requires-Dist: bump-my-version<1.0,>=0.28; extra == "dev"
+Dynamic: license-file
+
+# telegram-assistant
+
+Telegram automation service for the Planfix ↔ Telegram integration.
+
+Three interfaces share one domain layer:
+
+- HTTP API (FastAPI) on port `8085` with bearer-token auth — primary entry point for Planfix and automations.
+- CLI (`telegram-assistant`) — mirrors every HTTP endpoint plus admin commands (`auth`, `operations status`, `operations retry`).
+- Worker/queue — performs Telegram operations with throttling and `FLOOD_WAIT` handling.
+
+Runs on MTProto via Telethon under a technical Telegram user account.
+
+## Quick start
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Place a config file at data/config.yml (see Configuration below)
+telegram-assistant auth      # interactive Telethon login
+telegram-assistant health    # show current health
+uvicorn telegram_assistant.http_api.app:create_app --factory --port 8085
+```
+
+## Commands
+
+Every CLI subcommand maps 1:1 to an HTTP endpoint (except the admin-only commands `auth`, `operations status`, and `operations retry`). Run any command with `--help` for full flag documentation.
+
+Top-level:
+
+- `auth` — interactive Telethon login for the technical account.
+- `health` — report service health (Telegram session, database, default folder).
+- `version` — print the installed version.
+
+`groups` — manage Telegram supergroups:
+
+- `groups create` — create a Telegram supergroup for a Planfix client. Accepts `--topics-layout list|tabs` to pick the forum layout for this group (defaults to `telegram.defaults.topics_layout`).
+- `groups set-layout` — set the topics layout (`list` vs `tabs`) for an existing forum chat.
+- `groups get-layout` — read the current topics layout (`list` or `tabs`) for a forum chat.
+
+`topics` — manage forum topics:
+
+- `topics create` — create a single forum topic in an existing supergroup.
+- `topics bulk-create` — bulk-create topics from a CSV or JSON file.
+- `topics close` — close an existing forum topic (the topic and its history are kept).
+
+`members` — manage group membership:
+
+- `members bulk-add` — bulk-add members to an existing supergroup, optionally promoting to admin.
+- `members bulk-remove` — bulk-remove members from a supergroup (kick or permanently ban).
+
+`messages` — send messages and service commands:
+
+- `messages send` — send a message or service command (targeted or folder-wide mass mode).
+
+`folders` — inspect and manage chat folders:
+
+- `folders inspect` — inspect a chat folder and list its chats.
+- `folders add-chat` — move an existing chat into a folder.
+
+`operations` — inspect and retry queued operations:
+
+- `operations status` — show the status of an operation, including per-item summary.
+- `operations retry` — reset a failed/`needs_review` operation (and its items) back to pending.
+
+Updating this list: descriptions are sourced from each Typer command's docstring in `src/telegram_assistant/cli/main.py`. When you add or rename a command, update this section, `skills/telegram-assistant/SKILL.md`, and re-run `pytest tests/test_skill_inventory.py` — the inventory guard fails if the README/skill catalog drifts from the CLI.
+
+## Configuration
+
+Config is read from `data/config.yml` by default. The `data/` directory is excluded from version control and holds the Telethon session, SQLite database, and secrets.
+
+If `./data/config.yml` is absent, the loader falls back to `~/.config/telegram-assistant/config.yml`. On a clean machine, running any CLI command without `--config` will create a template at that path with `REPLACE_ME` placeholders for `api_id`, `api_hash`, and `bearer_token` — fill them in and re-run.
+
+To reach Telegram through a proxy, set `telegram.proxy_url` to a single URL — supported schemes are `socks5`, `socks4`, `http`, and `https`. Credentials and explicit ports are optional:
+
+```yaml
+telegram:
+  proxy_url: "socks5://user:pass@host:1080"   # or http://host:8080, socks4://host, ...
+```
+
+Leave it unset (or remove the line) to connect directly.
+
+Defaults applied to new supergroups live under `telegram.defaults`:
+
+```yaml
+telegram:
+  defaults:
+    enable_topics: true
+    create_invite_link: true
+    topics_layout: "list"        # "list" | "tabs" — applied after groups create
+    default_member_permissions:
+      create_topics: true        # let ordinary members create forum topics
+      pin_messages: true         # let ordinary members pin messages
+```
+
+`topics_layout` controls how the forum opens after `groups create`: `"list"` shows topics as a vertical list (Telegram's default), `"tabs"` shows them as horizontal tabs. The CLI `groups create --topics-layout` and `groups set-layout --layout` flags, and the `POST /telegram/groups` / `POST /telegram/groups/layout` bodies (`topics_layout`), override the default per call.
+
+`default_member_permissions` sets the new group's default banned rights so ordinary members can `create_topics` and `pin_messages`. Other default rights are left untouched.
+
+### Idempotency anchor
+
+Group/topic creation is idempotent on a generic `external_ref` (CLI `--external-ref`, HTTP `external_ref`). For backward compatibility the CLI `--planfix-task-id` flag and the HTTP `planfix_task_id` field are accepted as aliases that map onto `external_ref`. With no `external_ref`, groups key on the exact title and topics key on `chat_id + topic_name`.
+
+### Planfix plugin (optional, off by default)
+
+Planfix-specific behavior lives behind an opt-in plugin. With it disabled the core has **zero Planfix knowledge** — `external_ref` still anchors idempotency, but there is no `/task <id>` service message, no `@planfix_bot` welcome cleanup, and `@planfix_bot` is not treated as a protected account. Enable it under `plugins`:
+
+```yaml
+plugins:
+  planfix:
+    enabled: true                 # turn on Planfix-specific behavior
+    bot_username: "@planfix_bot"  # group member that receives the /task command
+    group_title_postfix: ""       # appended to the Telegram chat title at creation
+    cleanup_messages: false       # delete welcome / /task / bot-reply after creation (opt-in)
+    task_reply_wait_seconds: 5    # how long to poll for the bot's /task reply
+```
+
+When enabled and `external_ref` is set on a group whose members include `bot_username`, the plugin sends `/task <external_ref>` after creation. `group_title_postfix` is appended to the Telegram chat title at creation time but deliberately kept out of the idempotency key, so a replay of the same `external_ref` still matches on the raw title. `cleanup_messages` (default `false`) deletes the bot's welcome message, the `/task <id>` command, and the bot's reply to it; `task_reply_wait_seconds` is how long to poll for that reply before deleting only the welcome + command. All cleanup is best-effort: failures are recorded in the operation's `skipped` list and never fail the create.
+
+See `docs/plans/20260518-telegram-assistant-mvp.md` for the full configuration schema and feature scope.
+
+## Docker
+
+The service ships as a slim Python 3.12 image. Runtime state (Telethon session, SQLite database, `data/config.yml`, bearer token) lives in `/data`, which must be mounted as a volume — nothing sensitive is baked into the image.
+
+Build and run with `docker compose`:
+
+```bash
+mkdir -p data
+cp path/to/your/config.yml data/config.yml   # fill in api_id, api_hash, bearer_token, etc.
+docker compose up -d
+curl http://127.0.0.1:8085/health
+```
+
+Run a one-shot CLI invocation against the same volume:
+
+```bash
+docker compose run --rm telegram-assistant \
+    telegram-assistant health
+```
+
+The `auth` CLI is interactive (it prompts for phone, code, and optional 2FA password), so run it with a TTY attached:
+
+```bash
+docker compose run --rm -it telegram-assistant \
+    telegram-assistant auth
+```
+
+The Telethon session is written to `/data` and persists across container restarts.
+
+A self-contained smoke script lives at `scripts/docker-smoke.sh`. It builds the image, starts a throwaway container with a temporary `data/config.yml`, polls `GET /health` until it returns `200`, and tears everything down.
+
+```bash
+bash scripts/docker-smoke.sh
+```
+
+## Tests
+
+```bash
+pytest
+```

telegram_assistant-0.2.1/README.md

@@ -0,0 +1,162 @@
+# telegram-assistant
+
+Telegram automation service for the Planfix ↔ Telegram integration.
+
+Three interfaces share one domain layer:
+
+- HTTP API (FastAPI) on port `8085` with bearer-token auth — primary entry point for Planfix and automations.
+- CLI (`telegram-assistant`) — mirrors every HTTP endpoint plus admin commands (`auth`, `operations status`, `operations retry`).
+- Worker/queue — performs Telegram operations with throttling and `FLOOD_WAIT` handling.
+
+Runs on MTProto via Telethon under a technical Telegram user account.
+
+## Quick start
+
+```bash
+python3.12 -m venv .venv
+source .venv/bin/activate
+pip install -e ".[dev]"
+
+# Place a config file at data/config.yml (see Configuration below)
+telegram-assistant auth      # interactive Telethon login
+telegram-assistant health    # show current health
+uvicorn telegram_assistant.http_api.app:create_app --factory --port 8085
+```
+
+## Commands
+
+Every CLI subcommand maps 1:1 to an HTTP endpoint (except the admin-only commands `auth`, `operations status`, and `operations retry`). Run any command with `--help` for full flag documentation.
+
+Top-level:
+
+- `auth` — interactive Telethon login for the technical account.
+- `health` — report service health (Telegram session, database, default folder).
+- `version` — print the installed version.
+
+`groups` — manage Telegram supergroups:
+
+- `groups create` — create a Telegram supergroup for a Planfix client. Accepts `--topics-layout list|tabs` to pick the forum layout for this group (defaults to `telegram.defaults.topics_layout`).
+- `groups set-layout` — set the topics layout (`list` vs `tabs`) for an existing forum chat.
+- `groups get-layout` — read the current topics layout (`list` or `tabs`) for a forum chat.
+
+`topics` — manage forum topics:
+
+- `topics create` — create a single forum topic in an existing supergroup.
+- `topics bulk-create` — bulk-create topics from a CSV or JSON file.
+- `topics close` — close an existing forum topic (the topic and its history are kept).
+
+`members` — manage group membership:
+
+- `members bulk-add` — bulk-add members to an existing supergroup, optionally promoting to admin.
+- `members bulk-remove` — bulk-remove members from a supergroup (kick or permanently ban).
+
+`messages` — send messages and service commands:
+
+- `messages send` — send a message or service command (targeted or folder-wide mass mode).
+
+`folders` — inspect and manage chat folders:
+
+- `folders inspect` — inspect a chat folder and list its chats.
+- `folders add-chat` — move an existing chat into a folder.
+
+`operations` — inspect and retry queued operations:
+
+- `operations status` — show the status of an operation, including per-item summary.
+- `operations retry` — reset a failed/`needs_review` operation (and its items) back to pending.
+
+Updating this list: descriptions are sourced from each Typer command's docstring in `src/telegram_assistant/cli/main.py`. When you add or rename a command, update this section, `skills/telegram-assistant/SKILL.md`, and re-run `pytest tests/test_skill_inventory.py` — the inventory guard fails if the README/skill catalog drifts from the CLI.
+
+## Configuration
+
+Config is read from `data/config.yml` by default. The `data/` directory is excluded from version control and holds the Telethon session, SQLite database, and secrets.
+
+If `./data/config.yml` is absent, the loader falls back to `~/.config/telegram-assistant/config.yml`. On a clean machine, running any CLI command without `--config` will create a template at that path with `REPLACE_ME` placeholders for `api_id`, `api_hash`, and `bearer_token` — fill them in and re-run.
+
+To reach Telegram through a proxy, set `telegram.proxy_url` to a single URL — supported schemes are `socks5`, `socks4`, `http`, and `https`. Credentials and explicit ports are optional:
+
+```yaml
+telegram:
+  proxy_url: "socks5://user:pass@host:1080"   # or http://host:8080, socks4://host, ...
+```
+
+Leave it unset (or remove the line) to connect directly.
+
+Defaults applied to new supergroups live under `telegram.defaults`:
+
+```yaml
+telegram:
+  defaults:
+    enable_topics: true
+    create_invite_link: true
+    topics_layout: "list"        # "list" | "tabs" — applied after groups create
+    default_member_permissions:
+      create_topics: true        # let ordinary members create forum topics
+      pin_messages: true         # let ordinary members pin messages
+```
+
+`topics_layout` controls how the forum opens after `groups create`: `"list"` shows topics as a vertical list (Telegram's default), `"tabs"` shows them as horizontal tabs. The CLI `groups create --topics-layout` and `groups set-layout --layout` flags, and the `POST /telegram/groups` / `POST /telegram/groups/layout` bodies (`topics_layout`), override the default per call.
+
+`default_member_permissions` sets the new group's default banned rights so ordinary members can `create_topics` and `pin_messages`. Other default rights are left untouched.
+
+### Idempotency anchor
+
+Group/topic creation is idempotent on a generic `external_ref` (CLI `--external-ref`, HTTP `external_ref`). For backward compatibility the CLI `--planfix-task-id` flag and the HTTP `planfix_task_id` field are accepted as aliases that map onto `external_ref`. With no `external_ref`, groups key on the exact title and topics key on `chat_id + topic_name`.
+
+### Planfix plugin (optional, off by default)
+
+Planfix-specific behavior lives behind an opt-in plugin. With it disabled the core has **zero Planfix knowledge** — `external_ref` still anchors idempotency, but there is no `/task <id>` service message, no `@planfix_bot` welcome cleanup, and `@planfix_bot` is not treated as a protected account. Enable it under `plugins`:
+
+```yaml
+plugins:
+  planfix:
+    enabled: true                 # turn on Planfix-specific behavior
+    bot_username: "@planfix_bot"  # group member that receives the /task command
+    group_title_postfix: ""       # appended to the Telegram chat title at creation
+    cleanup_messages: false       # delete welcome / /task / bot-reply after creation (opt-in)
+    task_reply_wait_seconds: 5    # how long to poll for the bot's /task reply
+```
+
+When enabled and `external_ref` is set on a group whose members include `bot_username`, the plugin sends `/task <external_ref>` after creation. `group_title_postfix` is appended to the Telegram chat title at creation time but deliberately kept out of the idempotency key, so a replay of the same `external_ref` still matches on the raw title. `cleanup_messages` (default `false`) deletes the bot's welcome message, the `/task <id>` command, and the bot's reply to it; `task_reply_wait_seconds` is how long to poll for that reply before deleting only the welcome + command. All cleanup is best-effort: failures are recorded in the operation's `skipped` list and never fail the create.
+
+See `docs/plans/20260518-telegram-assistant-mvp.md` for the full configuration schema and feature scope.
+
+## Docker
+
+The service ships as a slim Python 3.12 image. Runtime state (Telethon session, SQLite database, `data/config.yml`, bearer token) lives in `/data`, which must be mounted as a volume — nothing sensitive is baked into the image.
+
+Build and run with `docker compose`:
+
+```bash
+mkdir -p data
+cp path/to/your/config.yml data/config.yml   # fill in api_id, api_hash, bearer_token, etc.
+docker compose up -d
+curl http://127.0.0.1:8085/health
+```
+
+Run a one-shot CLI invocation against the same volume:
+
+```bash
+docker compose run --rm telegram-assistant \
+    telegram-assistant health
+```
+
+The `auth` CLI is interactive (it prompts for phone, code, and optional 2FA password), so run it with a TTY attached:
+
+```bash
+docker compose run --rm -it telegram-assistant \
+    telegram-assistant auth
+```
+
+The Telethon session is written to `/data` and persists across container restarts.
+
+A self-contained smoke script lives at `scripts/docker-smoke.sh`. It builds the image, starts a throwaway container with a temporary `data/config.yml`, polls `GET /health` until it returns `200`, and tears everything down.
+
+```bash
+bash scripts/docker-smoke.sh
+```
+
+## Tests
+
+```bash
+pytest
+```

telegram_assistant-0.2.1/pyproject.toml

@@ -0,0 +1,92 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "telegram-assistant"
+version = "0.2.1"
+description = "Telegram automation service (MTProto/Telethon) with an optional Planfix integration plugin."
+readme = "README.md"
+requires-python = ">=3.12"
+license = { text = "MIT" }
+authors = [{ name = "Stanislav Popov", email = "popstas@gmail.com" }]
+keywords = ["telegram", "telethon", "automation", "mtproto", "planfix"]
+classifiers = [
+    "Programming Language :: Python :: 3.12",
+    "Framework :: FastAPI",
+    "Topic :: Communications :: Chat",
+    "Operating System :: OS Independent",
+    "License :: OSI Approved :: MIT License",
+]
+dependencies = [
+    "telethon>=1.36,<2.0",
+    "fastapi>=0.115,<1.0",
+    "uvicorn[standard]>=0.30,<1.0",
+    "pydantic>=2.7,<3.0",
+    "pyyaml>=6.0,<7.0",
+    "typer>=0.12,<1.0",
+    "structlog>=24.1,<25.0",
+    "SQLAlchemy>=2.0,<3.0",
+    "httpx>=0.27,<1.0",
+    "python-socks[asyncio]>=2.4,<3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0,<9.0",
+    "pytest-asyncio>=0.23,<1.0",
+    "ruff>=0.5,<1.0",
+    "git-cliff>=2.0.0",
+    "pre-commit>=3.7,<5.0",
+    "build>=1.2,<2.0",
+    "twine>=5.0,<7.0",
+    "bump-my-version>=0.28,<1.0",
+]
+
+[project.scripts]
+telegram-assistant = "telegram_assistant.cli.main:app"
+
+[project.urls]
+Homepage = "https://github.com/popstas/telegram-assistant"
+Repository = "https://github.com/popstas/telegram-assistant"
+"Bug Tracker" = "https://github.com/popstas/telegram-assistant/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+addopts = "-ra"
+
+[tool.ruff]
+line-length = 100
+target-version = "py312"
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "B", "UP"]
+ignore = ["E501"]
+
+# Version bumping: `bump-my-version bump patch|minor|major` updates both files,
+# commits as `chore(release): vX.Y.Z`, and creates the `vX.Y.Z` tag. Pushing the
+# tag triggers .github/workflows/release.yml (GitHub release + PyPI publish).
+[tool.bumpversion]
+current_version = "0.2.1"
+allow_dirty = false
+commit = true
+message = "chore(release): v{new_version}"
+tag = true
+tag_name = "v{new_version}"
+tag_message = "v{new_version}"
+
+[[tool.bumpversion.files]]
+filename = "pyproject.toml"
+search = '''name = "telegram-assistant"
+version = "{current_version}"'''
+replace = '''name = "telegram-assistant"
+version = "{new_version}"'''
+
+[[tool.bumpversion.files]]
+filename = "src/telegram_assistant/__init__.py"
+search = '__version__ = "{current_version}"'
+replace = '__version__ = "{new_version}"'

telegram_assistant-0.2.1/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

telegram_assistant-0.2.1/src/telegram_assistant/__init__.py

@@ -0,0 +1,3 @@
+"""telegram-assistant — Telegram automation service (MTProto/Telethon)."""
+
+__version__ = "0.2.1"

telegram_assistant-0.2.1/src/telegram_assistant/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI surface (Typer)."""
+
+from telegram_assistant.cli.main import app
+
+__all__ = ["app"]