telegram-tools 3.0.0__py3-none-any.whl

telegram_tools/__init__.py

@@ -0,0 +1,5 @@
+"""Local Telethon CLI tools."""
+
+__all__ = ["__version__"]
+
+__version__ = "2.0.1"

telegram_tools/cli.py

@@ -0,0 +1,227 @@
+from __future__ import annotations
+
+import argparse
+import asyncio
+import json
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from telegram_tools.client import create_client
+from telegram_tools.config import ConfigError, load_config
+from telegram_tools.delete import confirm_clear_topic_messages, delete_topic_messages
+from telegram_tools.discovery import discover_chats, filter_chats, format_discovery_table
+from telegram_tools.doctor import run_doctor
+from telegram_tools.exporters import write_records
+from telegram_tools.resolver import EntityResolutionError, resolve_chat
+from telegram_tools.search import format_message_records, search_messages
+from telegram_tools.topics import get_forum_topics, get_forum_topics_by_ids
+
+
+def positive_int(value: str) -> int:
+    parsed = int(value)
+    if parsed < 1:
+        raise argparse.ArgumentTypeError("must be at least 1")
+    return parsed
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="telegram-tools")
+    subparsers = parser.add_subparsers(dest="command")
+
+    discover = subparsers.add_parser("discover", help="List dialogs and forum topics")
+    discover.add_argument("--json", dest="json_output", help="Write discovery output to this JSON file")
+    discover.add_argument("--all", dest="all_chats", action="store_true", help="Show every chat instead of admin/managed chats only")
+    discover.add_argument("--admin-only", action="store_true", help=argparse.SUPPRESS)
+
+    clear_messages = subparsers.add_parser("clear-messages", help="Clear messages from forum topic(s), preserving topics and topic IDs")
+    clear_messages.add_argument("--chat", required=True, help="Chat/channel username, link, or ID")
+    topic_group = clear_messages.add_mutually_exclusive_group(required=True)
+    topic_group.add_argument("--topic", dest="topics", action="append", type=int, help="Topic ID to clear messages from; repeatable")
+    topic_group.add_argument("--all-topics", "--all-topics-in-chat", dest="all_topics", action="store_true", help="Clear messages from every forum topic")
+    clear_messages.add_argument("--execute", action="store_true", help="Actually clear messages after typing DELETE")
+    clear_messages.add_argument("--batch-size", type=positive_int, default=100, help="Clear-message batch size")
+
+    search = subparsers.add_parser("search", help="Search and export messages")
+    search.add_argument("--chat", required=True, help="Chat/channel username, link, or ID")
+    search.add_argument("--topic", type=int, help="Limit search/export to one topic ID")
+    search.add_argument("--keyword", "--contains", dest="keyword", help="Case-insensitive text filter")
+    search.add_argument("--from-user", help="Sender username, ID, or 'me'")
+    search.add_argument("--since", help="Inclusive ISO date or datetime lower bound")
+    search.add_argument("--until", help="Inclusive ISO date or datetime upper bound")
+    search.add_argument("--limit", type=positive_int, help="Maximum exported messages")
+    search.add_argument("--format", choices=("json", "csv"), default="json", help="Export format")
+    search.add_argument("--output", help="Output path; prints a readable table when omitted")
+
+    subparsers.add_parser("doctor", help="Check local setup without printing secrets")
+
+    return parser
+
+
+async def _require_delete_permission(client, chat) -> None:
+    me = await client.get_me()
+    permissions = await client.get_permissions(chat, me)
+    if not (getattr(permissions, "is_creator", False) or getattr(permissions, "delete_messages", False)):
+        raise PermissionError("Current user lacks Telegram delete_messages permission in this chat.")
+
+
+async def _run_discover(client, args) -> int:
+    chats = filter_chats(await discover_chats(client), admin_only=not args.all_chats)
+    payload = [chat.to_dict() for chat in chats]
+    if args.json_output:
+        output = Path(args.json_output)
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_text(json.dumps(payload, indent=2, default=str) + "\n")
+    else:
+        print(format_discovery_table(chats))
+    return 0
+
+
+async def _run_clear_messages(client, args) -> int:
+    resolved = await resolve_chat(client, args.chat)
+    peer = resolved.input_entity
+    await _require_delete_permission(client, peer)
+
+    if args.all_topics:
+        topics = await get_forum_topics(client, peer)
+    else:
+        topics = await get_forum_topics_by_ids(client, peer, args.topics)
+
+    result = await delete_topic_messages(
+        client,
+        peer,
+        topics,
+        execute=args.execute,
+        batch_size=args.batch_size,
+        progress=print,
+        confirm=confirm_clear_topic_messages,
+    )
+    print(json.dumps(result.to_dict(), indent=2))
+    return 1 if result.cancelled else 0
+
+
+async def _run_search(client, args) -> int:
+    resolved = await resolve_chat(client, args.chat)
+    peer = resolved.input_entity
+    records = await search_messages(
+        client,
+        peer,
+        chat_id=resolved.id,
+        topic_id=args.topic,
+        keyword=args.keyword,
+        from_user=args.from_user,
+        since=args.since,
+        until=args.until,
+        limit=args.limit,
+    )
+
+    if args.output:
+        write_records(records, args.output, args.format)
+    elif args.format == "csv":
+        raise ValueError("--output is required for CSV export")
+    else:
+        print(format_message_records(records))
+    return 0
+
+
+def _namespace(**kwargs):
+    return argparse.Namespace(**kwargs)
+
+
+def _read_execute(read) -> bool:
+    return read("Type DELETE to pass --execute, or press Enter for dry-run: ") == "DELETE"
+
+
+async def run_interactive_menu(*, read=input, write=print) -> int:
+    write(
+        "\n".join(
+            [
+                "telegram-tools",
+                "--------------------------------------------",
+                "1. Discover chats/topics",
+                "2. Search messages",
+                "3. Export messages",
+                "4. Clear topic messages",
+                "5. Clear multiple topics",
+                "6. Clear all topic messages",
+                "0. Exit",
+            ]
+        )
+    )
+    choice = read("Choose: ").strip()
+    if choice == "0":
+        return 0
+    if choice == "1":
+        all_chats = read("Show all chats instead of admin/managed only? [y/N]: ").strip().lower() == "y"
+        return await run(_namespace(command="discover", json_output=None, all_chats=all_chats, admin_only=not all_chats))
+    if choice == "2":
+        chat = read("Chat (@username, t.me link, or numeric ID): ")
+        keyword = read("Contains text: ")
+        topic = read("Topic ID (optional): ").strip()
+        return await run(
+            _namespace(command="search", chat=chat, topic=int(topic) if topic else None, keyword=keyword, from_user=None, since=None, until=None, limit=None, format="json", output=None)
+        )
+    if choice == "3":
+        chat = read("Chat (@username, t.me link, or numeric ID): ")
+        topic = read("Topic ID (optional): ").strip()
+        output = read("Output file: ")
+        fmt = read("Format [json/csv, default json]: ").strip() or "json"
+        return await run(
+            _namespace(command="search", chat=chat, topic=int(topic) if topic else None, keyword=None, from_user=None, since=None, until=None, limit=None, format=fmt, output=output)
+        )
+    if choice == "4":
+        chat = read("Chat (@username, t.me link, or numeric ID): ")
+        topic = int(read("Topic ID: "))
+        return await run(_namespace(command="clear-messages", chat=chat, topics=[topic], all_topics=False, execute=_read_execute(read), batch_size=100))
+    if choice == "5":
+        chat = read("Chat (@username, t.me link, or numeric ID): ")
+        raw_topics = read("Topic IDs (space or comma separated): ")
+        topics = [int(value) for value in raw_topics.replace(",", " ").split()]
+        return await run(_namespace(command="clear-messages", chat=chat, topics=topics, all_topics=False, execute=_read_execute(read), batch_size=100))
+    if choice == "6":
+        chat = read("Chat (@username, t.me link, or numeric ID): ")
+        return await run(_namespace(command="clear-messages", chat=chat, topics=None, all_topics=True, execute=_read_execute(read), batch_size=100))
+
+    write("Unknown choice.")
+    return 2
+
+
+async def run(args) -> int:
+    if args.command == "doctor":
+        return run_doctor()
+
+    config = load_config()
+    client = create_client(config)
+    await client.start()
+    try:
+        if args.command == "discover":
+            return await _run_discover(client, args)
+        if args.command == "clear-messages":
+            return await _run_clear_messages(client, args)
+        if args.command == "search":
+            return await _run_search(client, args)
+        raise ValueError(f"Unknown command: {args.command}")
+    finally:
+        await client.disconnect()
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        if args.command is None:
+            return asyncio.run(run_interactive_menu())
+        return asyncio.run(run(args))
+    except ConfigError as exc:
+        parser.error(str(exc))
+    except EntityResolutionError as exc:
+        parser.error(str(exc))
+    except ValueError as exc:
+        parser.error(str(exc))
+    except PermissionError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

telegram_tools/client.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+from telethon import TelegramClient
+
+from telegram_tools.config import Config
+
+
+def create_client(config: Config) -> TelegramClient:
+    config.session_path.parent.mkdir(parents=True, exist_ok=True)
+    client = TelegramClient(str(config.session_path), config.api_id, config.api_hash)
+    client.flood_sleep_threshold = 24 * 60 * 60
+    return client

telegram_tools/config.py

@@ -0,0 +1,52 @@
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping
+
+from dotenv import load_dotenv
+
+
+class ConfigError(RuntimeError):
+    pass
+
+
+def config_dir(home: Path | None = None) -> Path:
+    return (home or Path.home()) / ".telegram-tools"
+
+
+@dataclass(frozen=True)
+class Config:
+    api_id: int
+    api_hash: str
+    session_path: Path
+
+
+def load_config(
+    env: Mapping[str, str] | None = None,
+    *,
+    cwd: Path | None = None,
+    home: Path | None = None,
+) -> Config:
+    cwd = cwd or Path.cwd()
+    if env is None:
+        load_dotenv(dotenv_path=cwd / ".env", override=False)
+        load_dotenv(dotenv_path=config_dir(home) / ".env", override=False)
+        env = os.environ
+
+    raw_api_id = env.get("TELEGRAM_API_ID")
+    if not raw_api_id:
+        raise ConfigError("TELEGRAM_API_ID is required.")
+
+    try:
+        api_id = int(raw_api_id)
+    except ValueError as exc:
+        raise ConfigError("TELEGRAM_API_ID must be an integer.") from exc
+
+    api_hash = env.get("TELEGRAM_API_HASH")
+    if not api_hash:
+        raise ConfigError("TELEGRAM_API_HASH is required.")
+
+    session_path = Path(env.get("TELEGRAM_TOOLS_SESSION", config_dir(home) / "telegram-tools"))
+    return Config(api_id=api_id, api_hash=api_hash, session_path=session_path)

telegram_tools/delete.py

@@ -0,0 +1,95 @@
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Callable, Iterable
+from typing import Any
+
+from telethon.errors import FloodWaitError
+
+from telegram_tools.models import DeleteResult, TopicInfo
+
+CLEAR_TOPIC_MESSAGES_WARNING = """\
+====================================================
+WARNING: CLEAR TOPIC MESSAGES
+
+This will permanently delete ALL MESSAGES from the selected topic(s).
+
+OK: Forum topics will NOT be deleted.
+OK: Topic IDs will NOT change.
+OK: Only messages will be removed.
+===================================================="""
+
+
+def _chunks(values: list[int], size: int) -> Iterable[list[int]]:
+    for index in range(0, len(values), size):
+        yield values[index : index + size]
+
+
+async def _delete_batch_with_flood_wait(client, chat: Any, batch: list[int], *, sleep=asyncio.sleep, progress: Callable[[str], None]) -> int:
+    while True:
+        try:
+            await client.delete_messages(chat, batch)
+            return len(batch)
+        except FloodWaitError as exc:
+            seconds = int(getattr(exc, "seconds", 0))
+            progress(f"FloodWait: sleeping {seconds}s before retrying clear-message batch")
+            await sleep(seconds)
+
+
+def confirm_clear_topic_messages(*, read=input, write=print) -> str:
+    write(CLEAR_TOPIC_MESSAGES_WARNING)
+    return read("Type DELETE to continue: ")
+
+
+async def _collect_topic_message_ids(client, chat: Any, topic: TopicInfo) -> list[int]:
+    ids: list[int] = []
+    skip_ids = {topic.id}
+    if topic.top_message is not None:
+        skip_ids.add(topic.top_message)
+
+    async for message in client.iter_messages(chat, reply_to=topic.id, wait_time=1):
+        message_id = int(getattr(message, "id"))
+        if message_id not in skip_ids:
+            ids.append(message_id)
+    return ids
+
+
+async def delete_topic_messages(
+    client,
+    chat: Any,
+    topics: list[TopicInfo],
+    *,
+    execute: bool = False,
+    confirm: Callable[[], str] = input,
+    batch_size: int = 100,
+    progress: Callable[[str], None] | None = None,
+    sleep=asyncio.sleep,
+) -> DeleteResult:
+    progress = progress or (lambda _message: None)
+    if batch_size < 1:
+        raise ValueError("batch_size must be at least 1")
+
+    ids: list[int] = []
+    seen: set[int] = set()
+    for topic in topics:
+        progress(f"Scanning topic {topic.id} ({topic.title})")
+        for message_id in await _collect_topic_message_ids(client, chat, topic):
+            if message_id not in seen:
+                seen.add(message_id)
+                ids.append(message_id)
+
+    if not execute:
+        progress(f"Dry-run: {len(ids)} topic messages would be cleared")
+        return DeleteResult(matched=len(ids), deleted=0, dry_run=True)
+
+    if confirm() != "DELETE":
+        progress("Clear topic messages cancelled")
+        return DeleteResult(matched=len(ids), deleted=0, dry_run=False, cancelled=True)
+
+    deleted = 0
+    for batch in _chunks(ids, batch_size):
+        progress(f"Clearing batch of {len(batch)} topic messages")
+        deleted += await _delete_batch_with_flood_wait(client, chat, batch, sleep=sleep, progress=progress)
+        progress(f"Cleared {deleted}/{len(ids)} topic messages")
+
+    return DeleteResult(matched=len(ids), deleted=deleted, dry_run=False)

telegram_tools/discovery.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+from typing import Any
+
+from telegram_tools.models import ChatInfo, TopicInfo
+from telegram_tools.topics import get_forum_topics
+
+
+def classify_entity(entity: Any) -> str:
+    if getattr(entity, "broadcast", False):
+        return "channel"
+    if getattr(entity, "megagroup", False) and getattr(entity, "forum", False):
+        return "forum_group"
+    if getattr(entity, "megagroup", False):
+        return "supergroup"
+    if entity.__class__.__name__ == "User":
+        return "user"
+    return "group"
+
+
+def dialog_to_chat_info(
+    dialog: Any,
+    *,
+    is_admin: bool,
+    topics: list[TopicInfo] | None = None,
+) -> ChatInfo:
+    entity = dialog.entity
+    return ChatInfo(
+        id=int(dialog.id),
+        title=str(getattr(dialog, "title", None) or getattr(dialog, "name", None) or ""),
+        username=getattr(entity, "username", None),
+        type=classify_entity(entity),
+        is_admin=is_admin,
+        topics=topics or [],
+    )
+
+
+def filter_chats(chats: list[ChatInfo], *, admin_only: bool) -> list[ChatInfo]:
+    if not admin_only:
+        return chats
+    return [chat for chat in chats if chat.is_admin]
+
+
+def _display_type(chat_type: str) -> str:
+    return chat_type.replace("_", " ").title()
+
+
+def _group_discovery_chats(chats: list[ChatInfo]) -> list[tuple[str, list[ChatInfo]]]:
+    forum_groups = [chat for chat in chats if chat.type == "forum_group"]
+    channels = [chat for chat in chats if chat.type == "channel"]
+    other_admin_groups = [
+        chat
+        for chat in chats
+        if chat.type in {"group", "supergroup"} and chat.is_admin and chat not in forum_groups
+    ]
+    other_chats = [
+        chat
+        for chat in chats
+        if chat not in forum_groups and chat not in channels and chat not in other_admin_groups
+    ]
+
+    groups = [
+        ("Forum Groups", forum_groups),
+        ("Channels", channels),
+        ("Other Admin Groups", other_admin_groups),
+    ]
+    if other_chats:
+        groups.append(("Other Chats", other_chats))
+    return groups
+
+
+def _format_chat(chat: ChatInfo) -> str:
+    lines = [
+        chat.title or "(untitled)",
+        f"Chat ID: {chat.id}",
+        f"Type: {_display_type(chat.type)}",
+        f"Admin: {'yes' if chat.is_admin else 'no'}",
+    ]
+    if chat.username:
+        lines.append(f"Username: @{chat.username}")
+
+    if chat.topics:
+        width = max(len(str(topic.id)) for topic in chat.topics)
+        lines.extend(
+            [
+                "",
+                "Topics",
+                "--------------------------------------------",
+            ]
+        )
+        lines.extend(f"{topic.id:<{width}}  {topic.title}" for topic in chat.topics)
+
+    return "\n".join(lines)
+
+
+def format_discovery_table(chats: list[ChatInfo]) -> str:
+    if not chats:
+        return "No chats found."
+
+    sections: list[str] = []
+    for title, group in _group_discovery_chats(chats):
+        if not group:
+            continue
+        lines = [title, "=" * len(title)]
+        lines.extend(_format_chat(chat) for chat in group)
+        sections.append("\n\n".join(lines))
+
+    return "\n\n".join(sections)
+
+
+async def is_admin(client, entity, user) -> bool:
+    try:
+        permissions = await client.get_permissions(entity, user)
+    except Exception:
+        return False
+    return bool(getattr(permissions, "is_admin", False))
+
+
+async def discover_chats(client) -> list[ChatInfo]:
+    user = await client.get_me()
+    chats: list[ChatInfo] = []
+
+    async for dialog in client.iter_dialogs():
+        entity = dialog.entity
+        topics: list[TopicInfo] = []
+        if getattr(entity, "forum", False):
+            peer = getattr(dialog, "input_entity", entity)
+            topics = await get_forum_topics(client, peer)
+
+        chats.append(
+            dialog_to_chat_info(
+                dialog,
+                is_admin=await is_admin(client, entity, user),
+                topics=topics,
+            )
+        )
+
+    return chats

telegram_tools/doctor.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Mapping
+
+from telegram_tools.config import config_dir
+
+
+MIN_PYTHON = (3, 11)
+
+
+@dataclass(frozen=True)
+class DoctorCheck:
+    status: str
+    message: str
+
+    @property
+    def failed(self) -> bool:
+        return self.status == "FAIL"
+
+    def format(self) -> str:
+        return f"{self.status:<4} {self.message}"
+
+
+def check_python_version(version_info: tuple[int, ...] | None = None) -> DoctorCheck:
+    version_info = version_info or sys.version_info[:3]
+    if version_info >= MIN_PYTHON:
+        return DoctorCheck("OK", "Python version is supported")
+    return DoctorCheck("FAIL", "Python 3.11 or newer is required")
+
+
+def check_config_presence(root: Path, env: Mapping[str, str], home: Path | None = None) -> DoctorCheck:
+    if env.get("TELEGRAM_API_ID") and env.get("TELEGRAM_API_HASH"):
+        return DoctorCheck("OK", "Telegram config is present")
+    if (root / ".env").exists() or (config_dir(home) / ".env").exists():
+        return DoctorCheck("OK", "Telegram config is present")
+    return DoctorCheck("FAIL", "Telegram config is missing")
+
+
+def check_session_storage(env: Mapping[str, str], home: Path | None = None) -> DoctorCheck:
+    session_path = Path(env.get("TELEGRAM_TOOLS_SESSION", config_dir(home) / "telegram-tools"))
+    candidates = [session_path, Path(f"{session_path}.session")]
+    if any(path.exists() for path in candidates):
+        return DoctorCheck("OK", "Session storage exists")
+    return DoctorCheck("WARN", "Session storage was not found (created on first login)")
+
+
+def run_doctor(
+    *,
+    root: Path | str | None = None,
+    env: Mapping[str, str] | None = None,
+    version_info: tuple[int, ...] | None = None,
+    home: Path | None = None,
+) -> int:
+    root = Path(root) if root is not None else Path.cwd()
+    env = os.environ if env is None else env
+    checks = [
+        check_python_version(version_info),
+        check_config_presence(root, env, home),
+        check_session_storage(env, home),
+    ]
+
+    for check in checks:
+        print(check.format())
+
+    return 1 if any(check.failed for check in checks) else 0

telegram_tools/exporters.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+
+import csv
+import json
+from pathlib import Path
+from typing import Any, Iterable
+
+
+def write_records(records: Iterable[dict[str, Any]], output: str | Path, fmt: str) -> None:
+    rows = list(records)
+    path = Path(output)
+    path.parent.mkdir(parents=True, exist_ok=True)
+
+    if fmt == "json":
+        path.write_text(json.dumps(rows, indent=2, default=str) + "\n")
+        return
+
+    if fmt != "csv":
+        raise ValueError(f"Unsupported export format: {fmt}")
+
+    fieldnames: list[str] = []
+    for row in rows:
+        for key in row:
+            if key not in fieldnames:
+                fieldnames.append(key)
+
+    with path.open("w", newline="") as handle:
+        writer = csv.DictWriter(handle, fieldnames=fieldnames)
+        writer.writeheader()
+        writer.writerows(rows)

telegram_tools/models.py

@@ -0,0 +1,54 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(frozen=True)
+class TopicInfo:
+    id: int
+    title: str
+    top_message: int | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "title": self.title,
+            "top_message": self.top_message,
+        }
+
+
+@dataclass(frozen=True)
+class ChatInfo:
+    id: int
+    title: str
+    username: str | None
+    type: str
+    is_admin: bool
+    topics: list[TopicInfo] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "title": self.title,
+            "username": self.username,
+            "type": self.type,
+            "is_admin": self.is_admin,
+            "topics": [topic.to_dict() for topic in self.topics],
+        }
+
+
+@dataclass(frozen=True)
+class DeleteResult:
+    matched: int
+    deleted: int
+    dry_run: bool
+    cancelled: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "matched": self.matched,
+            "cleared": self.deleted,
+            "dry_run": self.dry_run,
+            "cancelled": self.cancelled,
+        }

telegram_tools/records.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+from datetime import UTC, date, datetime, time
+from typing import Any
+
+
+def parse_date_bound(value: str | None, *, end_of_day: bool) -> datetime | None:
+    if not value:
+        return None
+
+    if "T" not in value and len(value) == 10:
+        parsed_date = date.fromisoformat(value)
+        parsed_time = time.max if end_of_day else time.min
+        return datetime.combine(parsed_date, parsed_time, tzinfo=UTC)
+
+    parsed = datetime.fromisoformat(value.replace("Z", "+00:00"))
+    if parsed.tzinfo is None:
+        return parsed.replace(tzinfo=UTC)
+    return parsed.astimezone(UTC)
+
+
+def topic_id_for_message(message: Any) -> int | None:
+    reply_to = getattr(message, "reply_to", None)
+    if not reply_to or not getattr(reply_to, "forum_topic", False):
+        return None
+    return getattr(reply_to, "reply_to_top_id", None) or getattr(reply_to, "reply_to_msg_id", None)
+
+
+def message_to_record(message: Any, *, chat_id: int | None = None, topic_id: int | None = None) -> dict[str, Any]:
+    reply_to = getattr(message, "reply_to", None)
+    sender = getattr(message, "sender", None)
+    message_date = getattr(message, "date", None)
+    if isinstance(message_date, datetime):
+        if message_date.tzinfo is None:
+            message_date = message_date.replace(tzinfo=UTC)
+        date_value = message_date.astimezone(UTC).isoformat()
+    else:
+        date_value = None
+
+    text = getattr(message, "raw_text", None)
+    if text is None:
+        text = getattr(message, "message", "") or ""
+
+    return {
+        "id": int(getattr(message, "id")),
+        "chat_id": chat_id,
+        "topic_id": topic_id if topic_id is not None else topic_id_for_message(message),
+        "date": date_value,
+        "sender_id": getattr(message, "sender_id", None),
+        "sender_username": getattr(sender, "username", None),
+        "reply_to_msg_id": getattr(reply_to, "reply_to_msg_id", None) if reply_to else None,
+        "reply_to_top_id": getattr(reply_to, "reply_to_top_id", None) if reply_to else None,
+        "has_media": bool(getattr(message, "media", None)),
+        "text": text,
+    }
+
+
+def message_matches_filters(
+    message: Any,
+    *,
+    keyword: str | None = None,
+    from_user_id: int | None = None,
+    since: datetime | None = None,
+    until: datetime | None = None,
+) -> bool:
+    message_date = getattr(message, "date", None)
+    if isinstance(message_date, datetime):
+        if message_date.tzinfo is None:
+            message_date = message_date.replace(tzinfo=UTC)
+        message_date = message_date.astimezone(UTC)
+
+    if since and isinstance(message_date, datetime) and message_date < since:
+        return False
+    if until and isinstance(message_date, datetime) and message_date > until:
+        return False
+    if from_user_id is not None and getattr(message, "sender_id", None) != from_user_id:
+        return False
+    if keyword:
+        text = (getattr(message, "raw_text", None) or getattr(message, "message", "") or "").lower()
+        if keyword.lower() not in text:
+            return False
+    return True

telegram_tools/resolver.py

@@ -0,0 +1,59 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+
+class EntityResolutionError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class ResolvedChat:
+    id: int
+    entity: Any
+    input_entity: Any
+
+
+def _parse_numeric_reference(reference: Any) -> int | None:
+    if isinstance(reference, int):
+        return reference
+    if isinstance(reference, str):
+        value = reference.strip()
+        if value and value.lstrip("+-").isdigit():
+            return int(value)
+    return None
+
+
+async def _resolve_from_dialogs(client, chat_id: int) -> ResolvedChat | None:
+    async for dialog in client.iter_dialogs():
+        if int(getattr(dialog, "id")) != chat_id:
+            continue
+
+        entity = dialog.entity
+        input_entity = getattr(dialog, "input_entity", None)
+        if input_entity is None:
+            input_entity = await client.get_input_entity(entity)
+        return ResolvedChat(id=chat_id, entity=entity, input_entity=input_entity)
+
+    return None
+
+
+async def resolve_chat(client, reference: str | int) -> ResolvedChat:
+    numeric_reference = _parse_numeric_reference(reference)
+    if numeric_reference is not None:
+        resolved = await _resolve_from_dialogs(client, numeric_reference)
+        if resolved is not None:
+            return resolved
+        lookup_reference: str | int = numeric_reference
+    else:
+        lookup_reference = reference
+
+    try:
+        entity = await client.get_entity(lookup_reference)
+        input_entity = await client.get_input_entity(entity)
+        peer_id = int(await client.get_peer_id(entity))
+    except Exception as exc:
+        raise EntityResolutionError(f"Cannot resolve chat {reference!r}.") from exc
+
+    return ResolvedChat(id=peer_id, entity=entity, input_entity=input_entity)

telegram_tools/search.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from typing import Any
+
+from telegram_tools.records import message_matches_filters, message_to_record, parse_date_bound
+
+
+def _truncate(value: str, max_length: int = 80) -> str:
+    value = " ".join(value.split())
+    if len(value) <= max_length:
+        return value
+    return value[: max_length - 1] + "..."
+
+
+def format_message_records(records: list[dict[str, Any]]) -> str:
+    if not records:
+        return "No messages found."
+
+    lines = ["Messages", "--------------------------------------------"]
+    for record in records:
+        sender = record.get("sender_username") or record.get("sender_id") or ""
+        topic = record.get("topic_id") or ""
+        date = record.get("date") or ""
+        text = _truncate(str(record.get("text") or ""))
+        lines.append(
+            f"{record.get('id')}\t{date}\ttopic={topic}\tsender={sender}\t{text}"
+        )
+    return "\n".join(lines)
+
+
+async def _resolve_from_user_id(client, from_user: str | int | None) -> int | None:
+    if from_user is None:
+        return None
+    return int(await client.get_peer_id(from_user))
+
+
+async def search_messages(
+    client,
+    chat: Any,
+    *,
+    chat_id: int | None = None,
+    topic_id: int | None = None,
+    keyword: str | None = None,
+    from_user: str | int | None = None,
+    since: str | None = None,
+    until: str | None = None,
+    limit: int | None = None,
+) -> list[dict[str, Any]]:
+    since_dt = parse_date_bound(since, end_of_day=False)
+    until_dt = parse_date_bound(until, end_of_day=True)
+    records: list[dict[str, Any]] = []
+
+    if topic_id is not None:
+        from_user_id = await _resolve_from_user_id(client, from_user)
+        iterator = client.iter_messages(chat, reply_to=topic_id, wait_time=1)
+        async for message in iterator:
+            if message_matches_filters(
+                message,
+                keyword=keyword,
+                from_user_id=from_user_id,
+                since=since_dt,
+                until=until_dt,
+            ):
+                records.append(message_to_record(message, chat_id=chat_id, topic_id=topic_id))
+                if limit is not None and len(records) >= limit:
+                    break
+        return records
+
+    kwargs: dict[str, Any] = {"limit": limit, "wait_time": 1}
+    if keyword:
+        kwargs["search"] = keyword
+    if from_user:
+        kwargs["from_user"] = from_user
+    if until_dt:
+        kwargs["offset_date"] = until_dt
+
+    async for message in client.iter_messages(chat, **kwargs):
+        if message_matches_filters(message, keyword=keyword, since=since_dt, until=until_dt):
+            records.append(message_to_record(message, chat_id=chat_id))
+
+    return records

telegram_tools/topics.py

@@ -0,0 +1,72 @@
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from telethon.tl.functions.messages import GetForumTopicsByIDRequest, GetForumTopicsRequest
+
+from telegram_tools.models import TopicInfo
+
+
+def topic_from_telethon(raw_topic) -> TopicInfo:
+    topic_id = int(getattr(raw_topic, "id"))
+    return TopicInfo(
+        id=topic_id,
+        title=str(getattr(raw_topic, "title", topic_id)),
+        top_message=getattr(raw_topic, "top_message", topic_id),
+    )
+
+
+async def get_forum_topics(client, peer, *, page_size: int = 100) -> list[TopicInfo]:
+    topics: list[TopicInfo] = []
+    seen: set[int] = set()
+    offset_date = None
+    offset_id = 0
+    offset_topic = 0
+
+    while True:
+        result = await client(
+            GetForumTopicsRequest(
+                peer=peer,
+                offset_date=offset_date,
+                offset_id=offset_id,
+                offset_topic=offset_topic,
+                limit=page_size,
+            )
+        )
+        raw_topics = list(getattr(result, "topics", []) or [])
+        if not raw_topics:
+            break
+
+        added = 0
+        for raw_topic in raw_topics:
+            topic_id = getattr(raw_topic, "id", None)
+            if topic_id is None or topic_id in seen:
+                continue
+            seen.add(topic_id)
+            topics.append(topic_from_telethon(raw_topic))
+            added += 1
+
+        total_count = getattr(result, "count", None)
+        if total_count is not None and len(topics) >= total_count:
+            break
+        if added == 0 or len(raw_topics) < page_size:
+            break
+
+        last = raw_topics[-1]
+        offset_date = getattr(last, "date", None)
+        offset_id = int(getattr(last, "top_message", 0) or 0)
+        offset_topic = int(getattr(last, "id", 0) or 0)
+
+    return topics
+
+
+async def get_forum_topics_by_ids(client, peer, topic_ids: Iterable[int]) -> list[TopicInfo]:
+    ids = [int(topic_id) for topic_id in topic_ids]
+    if not ids:
+        return []
+
+    result = await client(GetForumTopicsByIDRequest(peer=peer, topics=ids))
+    topics = [topic_from_telethon(topic) for topic in getattr(result, "topics", []) or []]
+    found = {topic.id for topic in topics}
+    topics.extend(TopicInfo(id=topic_id, title=str(topic_id), top_message=topic_id) for topic_id in ids if topic_id not in found)
+    return topics

telegram_tools-3.0.0.dist-info/METADATA

@@ -0,0 +1,156 @@
+Metadata-Version: 2.5
+Name: telegram-tools
+Version: 3.0.0
+Summary: Local Telethon CLI for Telegram chat/topic ID discovery, message search/export, and topic message clearing.
+Project-URL: Homepage, https://github.com/banozz0/telegram-tools
+Project-URL: Repository, https://github.com/banozz0/telegram-tools
+Project-URL: Issues, https://github.com/banozz0/telegram-tools/issues
+Project-URL: Changelog, https://github.com/banozz0/telegram-tools/blob/main/CHANGELOG.md
+License: MIT License
+        
+        Copyright (c) 2026 telegram-tools contributors
+        
+        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.
+License-File: LICENSE
+Keywords: cli,export,forum-topics,telegram,telethon
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Utilities
+Requires-Python: >=3.11
+Requires-Dist: python-dotenv<2,>=1.0
+Requires-Dist: telethon<2,>=1.44
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# telegram-tools
+
+A local CLI for operating your own Telegram chats: find the real IDs of your groups, channels, and forum topics, search and export messages, and clear all messages out of forum topics without destroying the topics themselves.
+
+Built on [Telethon](https://github.com/LonamiWebs/Telethon). Everything runs on your machine with your own Telegram API credentials — no server, no third party, nothing leaves your computer except the Telegram API calls you asked for.
+
+## What it does
+
+- **`discover`** — lists your chats, channels, and forum groups with their exact numeric IDs and every forum topic ID. The fastest way to answer "what is this chat's `-100…` ID and what are its topic IDs?"
+- **`search`** — searches messages by text, sender, date range, or topic, and prints a table or exports JSON/CSV.
+- **`clear-messages`** — deletes all messages inside selected forum topic(s) while preserving the topics and their IDs. Dry-run by default; deleting requires both `--execute` *and* typing `DELETE` at a prompt.
+- **`doctor`** — checks your local setup without printing any secrets.
+
+## What it doesn't do (on purpose)
+
+- No deleting or creating forum topics — topic IDs never change.
+- No media downloads.
+- No sending messages, no bots, no automation loops.
+- No cloud anything — credentials and session files stay in `~/.telegram-tools/`.
+
+## Install
+
+```bash
+pipx install telegram-tools
+# or
+uv tool install telegram-tools
+```
+
+Or from source: `pipx install git+https://github.com/banozz0/telegram-tools.git`
+
+Requires Python 3.11+.
+
+## Setup: your Telegram API credentials
+
+The tool logs in as *you* (a user account, not a bot), so it needs a Telegram API key. One-time, about two minutes:
+
+1. Open <https://my.telegram.org/apps> and log in with your Telegram phone number.
+2. Fill in the short "Create new application" form (any name/short name works; platform "Desktop").
+3. Copy the **App api_id** (a number) and **App api_hash** (a hex string).
+4. Store them where the tool can find them:
+
+```bash
+mkdir -p ~/.telegram-tools
+cat > ~/.telegram-tools/.env <<'EOF'
+TELEGRAM_API_ID=123456
+TELEGRAM_API_HASH=your-api-hash-here
+EOF
+```
+
+Shell environment variables and a `.env` in the current directory also work, and win over `~/.telegram-tools/.env`.
+
+Treat the api_hash like a password. The first command you run starts Telethon's interactive login (phone number + code from Telegram); the resulting session file is stored in `~/.telegram-tools/` and reused afterwards. Log out anytime by deleting the session file in that directory (your `.env` can stay) — the session also shows under Telegram's *Settings → Devices*.
+
+## 30 seconds of usage
+
+```bash
+# What are my chats and their IDs?
+telegram-tools discover            # admin/managed chats only
+telegram-tools discover --all      # everything
+
+# Search a group
+telegram-tools search --chat @mygroup --contains deploy
+
+# Export a topic to JSON
+telegram-tools search --chat @mygroup --topic 141 --output topic-141.json
+
+# Clear a topic (dry-run first — this is the default)
+telegram-tools clear-messages --chat @mygroup --topic 141
+# Actually delete: needs --execute AND typing DELETE at the prompt
+telegram-tools clear-messages --chat @mygroup --topic 141 --execute
+```
+
+Running `telegram-tools` with no arguments opens an interactive menu with the same operations.
+
+`discover` output looks like:
+
+```text
+Forum Groups
+============
+Example Forum
+Chat ID: -1001234567890
+Type: Forum Group
+Admin: yes
+
+Topics
+--------------------------------------------
+141   Deploys
+217   Support
+16    General
+```
+
+## Safety model
+
+| Command | Destructive? |
+| --- | --- |
+| `discover`, `search`, `doctor` | No — read-only |
+| `clear-messages` | Yes — but only with `--execute` **and** a typed `DELETE`, only messages, never topics |
+
+`clear-messages` also verifies you actually hold the delete-messages permission in the chat before doing anything, skips topic starter messages, and handles Telegram flood-wait limits automatically.
+
+## Status
+
+Stable for its three jobs; used regularly by its author. This is a solo project whose code was written by AI agents under review — issues are welcome, fixes are best-effort, and there is no support promise.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

telegram_tools-3.0.0.dist-info/RECORD

@@ -0,0 +1,18 @@
+telegram_tools/__init__.py,sha256=6OV0lQW5QffLv_UhmFj1MiK18NusHs7bvrU7nTGJjBo,82
+telegram_tools/cli.py,sha256=BmathBTQqjQ_NS_oOeDPkDpZheaQ9iiBtp8B_R1X1p8,9519
+telegram_tools/client.py,sha256=YzzrIXsHgcXw7-rLWlClVH8VcyCYpAEo74O4iwWJm40,387
+telegram_tools/config.py,sha256=lOneibo5LM5FJCKvUIVYTdAW5zuSFYsUj3DF8soV-mk,1335
+telegram_tools/delete.py,sha256=g0B2j6odhM6BDlnM47Efs7tY9-ECTmFTphYObyxmMIA,3270
+telegram_tools/discovery.py,sha256=vXrgyjMPT9aEmPOtFyaN7oZlZe0t9upc21aC4s4iEaY,3980
+telegram_tools/doctor.py,sha256=PvpjR0vuPtuE5HcTx8Va0855-VaQkschIO5qKbH6UuA,2217
+telegram_tools/exporters.py,sha256=HpEmUs8vgWGy-IK2P4Q8rEUUjU9ozaj7Oe3LbV1318E,830
+telegram_tools/models.py,sha256=yKBQ-fR7FK6Fi7H6_kai172SRhnur1aPBPGv6X3pQkA,1215
+telegram_tools/records.py,sha256=IxEmywAoJq917KXoimGHKgRim1u8UXlPdf0-UgUmGnQ,3097
+telegram_tools/resolver.py,sha256=WpcUZkqVImeUZo9wCfINmNU3yyJUvAR_9wWFxetEt6k,1803
+telegram_tools/search.py,sha256=rVdQOH-IsU3Z1Kp7tmhUiCGGYqKe3KDQxuEGKvq2PvU,2713
+telegram_tools/topics.py,sha256=5RTB6gtf6pCQ1FDv47VtIC6dw0tfmkIvZRZqw5vq-wc,2355
+telegram_tools-3.0.0.dist-info/METADATA,sha256=a8gwMblQY88AFbCC9UJrFI-tFdc-vwZTMfkmq_kJmKA,6781
+telegram_tools-3.0.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+telegram_tools-3.0.0.dist-info/entry_points.txt,sha256=hgizMaSMu4c4lHgjZEqdnB4_2ZEZqYZ0S8KeyWemhQ0,59
+telegram_tools-3.0.0.dist-info/licenses/LICENSE,sha256=JCGfvNwIwXv0kA46GVRJYepcwlt4QM-qcrie9lZB03I,1084
+telegram_tools-3.0.0.dist-info/RECORD,,

telegram_tools-3.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

telegram_tools-3.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+telegram-tools = telegram_tools.cli:main

telegram_tools-3.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 telegram-tools contributors
+
+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.