Metadata-Version: 2.4
Name: navig-telegram
Version: 0.1.0
Summary: Telegram surface for navig — bot management, sessions, status and the MTProto user-account verbs, as its own plugin.
Author-email: NAVIG Development Team <opensource@navig.run>
License-Expression: Apache-2.0
Keywords: navig,telegram,bot,mtproto,messaging,plugin
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Communications :: Chat
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: navig>=3.25.0
Requires-Dist: typer>=0.14.0
Requires-Dist: rich>=13.7.0
Requires-Dist: requests>=2.28
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.6.0; extra == "dev"

# navig-telegram

<!-- navig:plugin-card:start -->
<!-- Generated by scripts/gen_plugin_catalog.py — edit the plugin's pyproject.toml, not this block. -->

> Telegram surface for navig — bot management, sessions, status and the MTProto user-account verbs, as its own plugin.

**A navig extension** — installing it pulls in navig and adds the commands below · v0.1.0 · not on PyPI yet (install from source below)

**Install**

```bash
pip install "git+https://github.com/navig-run/plugins#subdirectory=navig-telegram"
```

It is not a separate program: it needs navig, and installing it installs navig for you.

<details><summary>Commands</summary>

| Command | What it does |
|---|---|
| `navig telegram briefings` | The morning and evening briefing cards: on/off, time, days. |
| `navig telegram business alerts` | Turn deletion alerts on or off (on = digest, unless you chose instant). |
| `navig telegram business deleted` | What was deleted in your business chats — the DM alert, browsable. |
| `navig telegram business deletions flush` | Send the pending digest now, instead of waiting for the window. |
| `navig telegram business deletions mode` | How you hear about deletions. |
| `navig telegram business deletions mute` | Stop announcing deletions from ONE chat (still recorded). |
| `navig telegram business deletions quiet` | Keep timer expiries and whole-chat wipes out of the alerts (still recorded). |
| `navig telegram business deletions record` | Whether deletions are tracked at all. |
| `navig telegram business deletions status` | Show every deletion switch: record · mode · window · target · muted. |
| `navig telegram business deletions target` | Send deletion reports to a separate log chat instead of your DM. |
| `navig telegram business deletions window` | How long a digest collects before it is sent (default 900s / 15 min). |
| `navig telegram business disable` | Disable the business layer. |
| `navig telegram business emoji` | List or remap reaction emojis, e.g. `navig telegram business emoji 🎯 tiktok`. |
| `navig telegram business enable` | Enable catching your business-profile conversations (owner-gated). |
| `navig telegram business ping` | Who gets a `/ping` status reply in business chats (default owner). |
| `navig telegram business rights` | List or change per-tool rights, e.g. `navig telegram business rights translate both`. |
| `navig telegram business status` | Show the business layer state + per-tool rights. |
| `navig telegram confirm` | Step 2 - complete login with the code (+ 2FA password if asked). |
| `navig telegram contacts list` | List your saved Telegram contacts (optionally only tagged ones). |
| `navig telegram contacts missing` | Who you filed that has since left your contact list — and why. |
| `navig telegram contacts prune` | Remove contacts by last-seen bucket (dry-run by default). |
| `navig telegram contacts runs` | List past tagging runs (what undo can reverse). |
| `navig telegram contacts tag` | File a group's members into your contacts, marked (dry-run by default). |
| `navig telegram contacts tag-list` | Mark an explicit list of @handles (dry-run by default). |
| `navig telegram contacts undo` | Reverse a tagging run: created contacts deleted, renamed ones restored. |
| `navig telegram dedupe` | Find duplicate media (live scan). Lists SAFE (exact/inbox) + REVIEW groups. |
| `navig telegram delete` | Delete messages (revoke for all). Dry-run unless --confirm. |
| `navig telegram delete-chat` | Delete a whole chat/group/channel for everyone. Dry-run unless --confirm. |
| `navig telegram dialogs` | List all your chats / channels / groups. |
| `navig telegram download-media` | Download a channel's media BYTES into a ChatExport-shaped staging folder |
| `navig telegram extensions disable` | Switch a Telegram extension off. |
| `navig telegram extensions enable` | Switch a Telegram extension on. |
| `navig telegram extensions info` | Show what one extension owns and what switching it off does. |
| `navig telegram extensions list` | Show every Telegram extension and whether it is on. |
| `navig telegram folders apply` | Apply a folder layout from a plan file. Dry-run unless --confirm. |
| `navig telegram folders export` | Dump current folders to an editable plan file (ids + raw peer ids). |
| `navig telegram folders list` | List your chat folders with their members. |
| `navig telegram folders rename` | Rename folders (label only, membership untouched). Dry-run unless --confirm. |
| `navig telegram forward` | Forward (or --copy) messages to another chat/channel. |
| `navig telegram history sync` | Backfill history into the catalog so search covers everything. |
| `navig telegram links` | Extract & classify links (tiktok/youtube/url) from a chat's recent messages. |
| `navig telegram login` | Step 1 - send a login code to your Telegram app. |
| `navig telegram logout` | Forget the stored Telegram user session. |
| `navig telegram members` | List the members of a group you can see. |
| `navig telegram move` | Move messages to another chat/group (copy + delete). Dry-run unless --confirm. |
| `navig telegram rename` | Rename a chat/channel title (needs admin). Dry-run unless --confirm. |
| `navig telegram rename-bulk` | Rename many chats from a plan file, flood-safe (one session, throttled, |
| `navig telegram search` | Search all backfilled conversations + media (or --live in one chat). |
| `navig telegram send` | Send a Telegram message using the configured bot token. |
| `navig telegram sessions clear` | Clear a session's message history. |
| `navig telegram sessions delete` | Delete a session completely. |
| `navig telegram sessions list` | List all active Telegram sessions. |
| `navig telegram sessions prune` | Remove inactive sessions. |
| `navig telegram sessions show` | Show details of a specific session. |
| `navig telegram setup` | Store your Telegram api_id/api_hash (from my.telegram.org) in the vault. |
| `navig telegram status` | Show Telegram bot status. |
| `navig telegram tidy` | Clear yesterday's routine messages from the bot's chat, every night. |
| `navig telegram topics` | List forum topics in a forum supergroup (pages through all of them). |

</details>

<!-- navig:plugin-card:end -->

**The Telegram surface for navig** — bot management, sessions, status and the MTProto
user-account verbs (login, dialogs, history, search, move, forward, dedupe, rename, links),
shipped as its own plugin instead of 58 commands inside core.

```powershell
pip install -e plugins/navig-telegram --no-deps
navig telegram --help        # same verbs as before, now owned here
navig tg --help              # the hidden alias still points at the same app
```

## Why a plugin

`core/navig/commands/telegram.py` was 35 KB of CLI plus `_telegram_mtproto.py` (45 verbs). The
bot and the channel wiring are core infrastructure, but the *command surface* is a domain with
a lifecycle — installable, versionable, uninstallable.

It could only move after the transport left the command module: `checkins/engine.py`,
`commands/habit.py`, `commands/body.py`, `commands/gateway.py` and `messaging/notify_operator.py`
used to import `_api_call` / `_load_telegram_token` / `telegram_send` from
`navig.commands.telegram`. Those now live in **`navig.telegram.api`** (core), so core no longer
depends on a command module — and a plugin cannot become a core dependency.

## How it mounts

Core keeps `telegram` / `tg` in its command map pointing at
`core/navig/commands/telegram.py`, now a five-line alias to `navig_telegram.commands.telegram`
(the same shape as `navig cdp`, `navig matrix`, `navig ahk`). So:

- `navig telegram …`, `navig tg …` and the deck/OS surfaces behave exactly as before;
- with the package absent the verb still exists and says how to install it;
- `navig.commands.telegram` and `navig.commands._telegram_mtproto` stay importable, so the
  2,000+ tests that touch them did not have to move.

## What stays in core

`navig.telegram` (the bot), `navig.telegram.api` (the Bot API transport), `navig.telegram.chat_tidy`,
and the gateway's telegram channel — all of it used by core paths that must work with this
plugin uninstalled.

## Verify

```powershell
navig telegram --help                        # 19 rows, same surface
py -m pytest core/tests/telegram -q          # the command + channel suite
```
