Metadata-Version: 2.5
Name: tdelegram
Version: 0.1.0
Summary: A full-featured Telegram client library + CLI backed by TDLib
Project-URL: Homepage, https://github.com/bulanovdm/TDelegram
Project-URL: Repository, https://github.com/bulanovdm/TDelegram
Project-URL: Issues, https://github.com/bulanovdm/TDelegram/issues
Project-URL: Changelog, https://github.com/bulanovdm/TDelegram/blob/main/CHANGELOG.md
Author: TDelegram
License: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: cli,tdlib,telegram
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: MacOS :: MacOS X
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
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
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: rich>=13
Requires-Dist: typer>=0.9
Provides-Extra: dev
Requires-Dist: mypy>=1.10; extra == 'dev'
Requires-Dist: packaging>=23; extra == 'dev'
Requires-Dist: pytest-cov>=5; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Provides-Extra: test
Requires-Dist: packaging>=23; extra == 'test'
Requires-Dist: pytest-cov>=5; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Description-Content-Type: text/markdown

# TDelegram — a full-featured Telegram client (library + CLI)

[![ci](https://github.com/bulanovdm/TDelegram/actions/workflows/ci.yml/badge.svg)](https://github.com/bulanovdm/TDelegram/actions/workflows/ci.yml)
[![python](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue)](https://github.com/bulanovdm/TDelegram/blob/main/pyproject.toml)
[![license](https://img.shields.io/badge/license-Apache--2.0-green)](https://github.com/bulanovdm/TDelegram/blob/main/LICENSE)
[![image](https://img.shields.io/badge/ghcr.io-tdelegram-blue)](https://github.com/bulanovdm/TDelegram/pkgs/container/tdelegram)

TDLib exposes **1022 functions through a single JSON interface**. TDelegram covers
all of them on day one through one generic transport, with ergonomics,
normalization, safety, errors and docs on top. No MCP layer: an importable Python
library plus a `tdelegram` CLI.

## What it is for

- **Where Telegram is blocked** — `proxy add` takes a shared `tg://proxy`,
  `t.me/proxy` or `socks5://` link and works before login, which is when it is
  needed.
- **Catching up without being seen to** — `inbox` lists unread messages across
  chats and marks nothing read; `draft set` leaves a reply for you to send.
- **Backups and research** — `chat export` is resumable and incremental, with
  media where the chat allows saving it; records carry views, forwards,
  reactions and where a forward came from.
- **Taking your words back** — `msg delete-mine` removes your own messages in a
  chat for everyone, after showing how many.
- **Alerts** — `watch` streams new messages matching words, a pattern, a chat
  or a sender.
- **Reading without seeing or hearing** — `--format text` gives screen readers
  plain sentences, and `msg transcribe` turns a voice message into text.

## Install

TDLib is a C++ dependency with no distribution package, so installing it
natively means a ~20 minute compile on Linux. Docker is the short way in — the
image has TDLib already built.

Published for `linux/amd64` and `linux/arm64`:

```bash
docker pull ghcr.io/bulanovdm/tdelegram:latest

# The session lives in /session; mount it or every run starts logged out.
docker run --rm -i -v "$HOME/.tdelegram:/session" \
  ghcr.io/bulanovdm/tdelegram auth status
```

Which tag to pull — a pinned release, the newest one, or unreleased `main` —
and when each moves is in [RELEASING.md](https://github.com/bulanovdm/TDelegram/blob/main/RELEASING.md#docker-image-tags).

Global flags such as `--yes` go before the command. One alias makes every
command in this README work verbatim:

```bash
alias tdelegram='docker run --rm -i -v "$HOME/.tdelegram:/session" \
  -v "$PWD:/work" -w /work -e TELEGRAM_API_ID -e TELEGRAM_API_HASH \
  ghcr.io/bulanovdm/tdelegram'
```

`auth login` and destructive commands are the exceptions — they prompt, and a
destructive command takes its typed confirmation only from a terminal. A second
alias gives them one:

```bash
alias tdelegram-tty='docker run --rm -it -v "$HOME/.tdelegram:/session" \
  -v "$PWD:/work" -w /work -e TELEGRAM_API_ID -e TELEGRAM_API_HASH \
  ghcr.io/bulanovdm/tdelegram'
tdelegram-tty auth login
```

Keep `-t` out of the first alias: with a terminal attached, Docker merges
stderr into stdout, which puts diagnostics in the JSON, and it refuses to start
when its input is a pipe.

### Native

Preferable on macOS, and the fallback wherever Docker is not available:

```bash
brew install tdlib   # macOS
pip install tdelegram
```

On Linux, build TDLib from source and point `TDELEGRAM_TDJSON` at the resulting
`libtdjson.so`. Full instructions, including getting an `api_id`/`api_hash` and
the first login, are in
[skills/tdelegram/references/setup.md](https://github.com/bulanovdm/TDelegram/blob/main/skills/tdelegram/references/setup.md).

## Quickstart

```bash
tdelegram auth login
tdelegram chat list
tdelegram inbox                                  # unread messages; marks nothing read
tdelegram chat history --chat @durov --limit 5
tdelegram msg send --chat me --text "hi"        # previews
tdelegram --yes msg send --chat me --text "hi"  # performs
tdelegram --yes msg send --chat me --text "*hi*" --parse-mode markdown  # MarkdownV2
tdelegram watch --for 10m                       # new messages as they arrive
tdelegram --format text inbox                   # plain lines, for a screen reader
```

Where Telegram is blocked, store a proxy before logging in — every `proxy`
command works without a session:

```bash
tdelegram --yes proxy add 'https://t.me/proxy?server=...&port=443&secret=...'
tdelegram proxy ping 1 && tdelegram auth login
```

Library:

```python
from tdelegram.client import TelegramClient
from tdelegram.transport import TdJsonTransport
from tdelegram.config import discover_library
from tdelegram.api import chats, messages

transport = TdJsonTransport(discover_library())
with TelegramClient(transport) as client:
    for chat in chats.iter_list(client, scope="main", maximum=10):
        print(chat["title"])
```

## Using it from an agent

`skills/tdelegram/` is an agent skill covering the CLI, the gate and the
discipline it implies, reading recipes, the Python API, troubleshooting and
installation from scratch. Point a coding agent at `skills/tdelegram/SKILL.md`,
or install the packaged bundle.

## Safety

Mutating calls preview and exit; `--yes` performs them. Destructive calls
(`deleteChatHistory`, `banChatMember`, `logOut`, `deleteAccount`,
`terminateAllOtherSessions`, …) need `--yes` *and* the method name typed at an
interactive terminal, so a script, a pipe or an agent's shell does not complete
one by accident. It is a safeguard, not a sandbox: a program that fakes a
terminal can type the name too. The gate lives in `TelegramClient.call()` —
including the raw `call` escape hatch. See `src/tdelegram/methods.json` for all 1022 verdicts.

`call` also checks each request against TDLib's schema before sending it,
because TDLib ignores a field it does not recognise and runs the call without
it. `tdelegram describe <method>` shows the real parameters.

## Layout

- `src/tdelegram/tdjson.py` — ctypes, modern C API only
- `transport.py` / `loop.py` / `client.py` — seam, reader thread, facade
- `auth.py` — 11-state machine with `CredentialProvider`
- `safety.py` + `methods.json` — write gate + registry
- `normalize.py` / `entities.py` / `dates.py` / `paging.py` / `files.py`
- `api/` — account chats messages media contacts users admin topics folders drafts reactions polls search updates bots stories secret proxies inbox export
- `schema.py` + `schema.json` — every TDLib request shape; what `call` and the tests check against
- `cli/` — Typer tree, JSONL on stdout, diagnostics on stderr

## Session

Own home at `~/.tdelegram/` (`--session-dir` overrides). Never commit or copy it:
it is full account access. See SECURITY.md.
