telegram-userbot-cli 0.3.0__tar.gz → 0.4.0__tar.gz

{telegram_userbot_cli-0.3.0 → telegram_userbot_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: telegram-userbot-cli
-Version: 0.3.0
+Version: 0.4.0
 Summary: Full-featured Telegram command-line client powered by a Telethon userbot (your own account, not a bot token)
 License-Expression: Apache-2.0
 License-File: LICENSE
@@ -31,6 +31,8 @@ no daemon, no external service**. Everything the CLI does lives in the CLI.
   admin promotion with granular rights, slow mode, forum topics, admin log
 - Chat management: archive, mute, edit title / description / photo,
   invite links, clear history
+- Contacts, privacy settings, blocking, dialog folders, multi-account,
+  voice transcription
 - Media: download, send files / albums / voice notes / stickers / GIFs,
   contact cards
 - Chats: list dialogs, history, pinned messages, in-chat & global search,
@@ -158,6 +160,27 @@ tg logout          # remove the session
 | `tg topic-create <chat> <title> [text]` | Create a forum topic, optionally with a first message |
 | `tg admin-log <chat> [-n]` | Recent admin actions |
 
+### Contacts, privacy & misc (v4)
+
+| Command | Description |
+|---|---|
+| `tg contact add <user> [name] [--phone]` | Add/update a contact |
+| `tg contact del <user...>` | Delete contacts (by name/id or `+phone`) |
+| `tg contact import <file>` | Bulk import from `.json` / `.csv` (`phone,first_name,last_name`) |
+| `tg contact export [file]` | Export contacts as re-importable JSON (default stdout) |
+| `tg photo-del [--all]` | Delete your most recent profile photo (or all) |
+| `tg privacy get [key...]` | Show privacy settings (default: all) |
+| `tg privacy set <key> all\|contacts\|nobody` | Change a privacy setting; `--allow USER` / `--deny USER` refine it |
+| `tg block <user>` / `tg unblock <user>` / `tg blocked` | Block management |
+| `tg folders` | List dialog folders |
+| `tg folder-create <name> --chat <c>...` | Create a folder with chats |
+| `tg folder-assign <folder> <chat...>` | Add chats to a folder |
+| `tg folder-del <folder>` | Delete a folder |
+| `tg folder-order <folder...>` | Reorder folders (pass all in the wanted order) |
+| `tg accounts` | List configured accounts |
+| `tg login --account <label>` | Log in an additional account |
+| `tg vtr <chat> <msg_id>` | Transcribe a voice note (Telegram Premium required) |
+
 Global flags: `--account` (v1: default only), `--json` (raw JSON output).
 Exit codes: `0` ok, `1` command error, `2` config/connection/session error,
 `130` interrupted.

{telegram_userbot_cli-0.3.0 → telegram_userbot_cli-0.4.0}/README-zh.md

@@ -15,6 +15,7 @@
 - 消息：发送 / 引用回复 / 编辑 / 删除 / 转发 / 投票 / 定时 / 草稿 / 表情回应 / 置顶
 - 群组管理：建群 / 建频道、邀请 / 踢人 / 封禁、管理员升降级（细粒度权限）、慢速模式、论坛话题、管理日志
 - 聊天管理：归档、免打扰、修改群名 / 简介 / 群头像、邀请链接、清空历史
+- 联系人、隐私设置、封锁管理、会话文件夹、多账号、语音转写
 - 媒体：下载、发文件 / 相册 / 语音条 / 贴纸 / GIF、发送名片
 - 聊天：会话列表、历史记录、置顶消息、会话内与全局搜索、在线状态、共同群组
 - 联系人与个人资料管理
@@ -136,6 +137,27 @@ tg logout          # 退出登录并删除会话
 | `tg topic-create <会话> <标题> [首条消息]` | 创建论坛话题 |
 | `tg admin-log <会话> [-n]` | 近期管理操作日志 |
 
+### 联系人、隐私与其他（v4）
+
+| 命令 | 说明 |
+|---|---|
+| `tg contact add <用户> [姓名] [--phone]` | 新增/更新联系人 |
+| `tg contact del <用户...>` | 删除联系人（按名称/id 或 `+手机号`） |
+| `tg contact import <文件>` | 从 `.json` / `.csv` 批量导入（`phone,first_name,last_name`） |
+| `tg contact export [文件]` | 导出为可再导入的 JSON（默认输出到终端） |
+| `tg photo-del [--all]` | 删除最近一张头像（`--all` 删除全部） |
+| `tg privacy get [键...]` | 查看隐私设置（默认全部） |
+| `tg privacy set <键> all\|contacts\|nobody` | 修改隐私设置；`--allow 用户` / `--deny 用户` 精细化 |
+| `tg block <用户>` / `tg unblock <用户>` / `tg blocked` | 封锁管理 |
+| `tg folders` | 列出会话文件夹 |
+| `tg folder-create <名称> --chat <会话>...` | 创建文件夹并加入会话 |
+| `tg folder-assign <文件夹> <会话...>` | 向文件夹追加会话 |
+| `tg folder-del <文件夹>` | 删除文件夹 |
+| `tg folder-order <文件夹...>` | 重排文件夹（按想要的顺序全部列出） |
+| `tg accounts` | 列出已配置的账号 |
+| `tg login --account <标签>` | 登录额外账号 |
+| `tg vtr <会话> <消息id>` | 语音转文字（需要 Telegram Premium） |
+
 全局选项：`--account`（v1 仅 default）、`--json`（原始 JSON 输出）。
 退出码：`0` 成功、`1` 命令错误、`2` 配置/连接/会话错误、`130` 中断。
 

{telegram_userbot_cli-0.3.0 → telegram_userbot_cli-0.4.0}/README.md

@@ -18,6 +18,8 @@ no daemon, no external service**. Everything the CLI does lives in the CLI.
   admin promotion with granular rights, slow mode, forum topics, admin log
 - Chat management: archive, mute, edit title / description / photo,
   invite links, clear history
+- Contacts, privacy settings, blocking, dialog folders, multi-account,
+  voice transcription
 - Media: download, send files / albums / voice notes / stickers / GIFs,
   contact cards
 - Chats: list dialogs, history, pinned messages, in-chat & global search,
@@ -145,6 +147,27 @@ tg logout          # remove the session
 | `tg topic-create <chat> <title> [text]` | Create a forum topic, optionally with a first message |
 | `tg admin-log <chat> [-n]` | Recent admin actions |
 
+### Contacts, privacy & misc (v4)
+
+| Command | Description |
+|---|---|
+| `tg contact add <user> [name] [--phone]` | Add/update a contact |
+| `tg contact del <user...>` | Delete contacts (by name/id or `+phone`) |
+| `tg contact import <file>` | Bulk import from `.json` / `.csv` (`phone,first_name,last_name`) |
+| `tg contact export [file]` | Export contacts as re-importable JSON (default stdout) |
+| `tg photo-del [--all]` | Delete your most recent profile photo (or all) |
+| `tg privacy get [key...]` | Show privacy settings (default: all) |
+| `tg privacy set <key> all\|contacts\|nobody` | Change a privacy setting; `--allow USER` / `--deny USER` refine it |
+| `tg block <user>` / `tg unblock <user>` / `tg blocked` | Block management |
+| `tg folders` | List dialog folders |
+| `tg folder-create <name> --chat <c>...` | Create a folder with chats |
+| `tg folder-assign <folder> <chat...>` | Add chats to a folder |
+| `tg folder-del <folder>` | Delete a folder |
+| `tg folder-order <folder...>` | Reorder folders (pass all in the wanted order) |
+| `tg accounts` | List configured accounts |
+| `tg login --account <label>` | Log in an additional account |
+| `tg vtr <chat> <msg_id>` | Transcribe a voice note (Telegram Premium required) |
+
 Global flags: `--account` (v1: default only), `--json` (raw JSON output).
 Exit codes: `0` ok, `1` command error, `2` config/connection/session error,
 `130` interrupted.

{telegram_userbot_cli-0.3.0 → telegram_userbot_cli-0.4.0}/ROADMAP.md

@@ -55,19 +55,26 @@ Chat management:
   (list/create)
 - ✅ `admin-log <chat>` — recent admin actions
 
-### v4 — Contacts, profile & misc
+### v4 — Contacts, profile & misc (shipped)
 
-- 🚧 `contact add/del` — add/delete contacts
-- 🚧 `contact import <file>` / `contact export` — bulk import/export
-- 🚧 `photo-del` — delete profile photo
-- 🚧 `privacy get/set` — privacy settings (last seen, phone, …)
-- 🚧 `block <user>` / `unblock <user>` / `blocked` — block management
-- 🚧 `folder ...` — dialog folders (create/assign/reorder)
-- 🚧 `accounts` — multi-account support (the `--account` hook already exists;
-  v1 resolves the default account only)
-- 🚧 `vtr <chat> <msg_id>` — voice transcription. telethon 1.44 has no
-  transcribe support; options: Groq HTTP API, or raw
-  `messages.transcribeAudio` TL (Telegram Premium)
+- ✅ `contact add/del` — add/delete contacts (`contact del` also matches `+phone`)
+- ✅ `contact import <file>` / `contact export` — bulk JSON/CSV import,
+  re-importable JSON export (note: Telegram no longer creates contacts for
+  unregistered numbers — unmatched imports return 0)
+- ✅ `photo-del` — delete the most recent profile photo (`--all` for all)
+- ✅ `privacy get/set` — 11 keys (lastseen, phone, calls, p2p, groups, photo,
+  forwards, voicemail, about, birthday, addedby); set rules must use the
+  `InputPrivacyValue*` classes — the output `PrivacyValue*` classes are
+  silently ignored by the server
+- ✅ `block <user>` / `unblock <user>` / `blocked` — block management
+- ✅ `folders` / `folder-create` / `folder-assign` / `folder-del` /
+  `folder-order` — dialog folders (list/create/assign/reorder)
+- ✅ `accounts` — multi-account support (`accounts` lists every
+  `TELEGRAM_SESSION_STRING*`; `login --account LABEL` and
+  `<command> --account LABEL` both work)
+- ✅ `vtr <chat> <msg_id>` — voice transcription via raw
+  `messages.TranscribeAudioRequest` (telethon has no wrapper). Telegram
+  Premium is required server-side; free accounts get a clean error
 
 ### Out of scope
 

{telegram_userbot_cli-0.3.0 → telegram_userbot_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "telegram-userbot-cli"
-version = "0.3.0"
+version = "0.4.0"
 description = "Full-featured Telegram command-line client powered by a Telethon userbot (your own account, not a bot token)"
 readme = "README.md"
 license = "Apache-2.0"

{telegram_userbot_cli-0.3.0 → telegram_userbot_cli-0.4.0}/src/tgcli/__init__.py

@@ -1,3 +1,3 @@
 """tgcli — standalone Telegram command-line client."""
 
-__version__ = "0.3.0"
+__version__ = "0.4.0"

{telegram_userbot_cli-0.3.0 → telegram_userbot_cli-0.4.0}/src/tgcli/auth.py

@@ -1,8 +1,10 @@
-"""Login / logout flows."""
+"""Login / logout / multi-account flows."""
 
 import asyncio
 import getpass
 import io
+import os
+import re
 import sys
 from datetime import date, datetime, timezone
 
@@ -14,6 +16,7 @@ from .client import build_client
 from .output import TgError
 
 _MAX_QR_REFRESHES = 5
+_SESSION_ENV_RE = re.compile(r"TELEGRAM_SESSION_STRING(?:_([A-Z0-9_]+))?$")
 
 
 def render_qr(url: str) -> None:
@@ -38,6 +41,19 @@ def _seconds_until(qr) -> float:
         return 120.0
 
 
+def _save_session(args, session_str: str) -> None:
+    account = getattr(args, "account", None)
+    key = config.session_env_var(account)
+    config.write_env(
+        key,
+        session_str,
+        comment=f"generated by tg login on {date.today()}; keep secret, "
+        "do NOT share with the MCP daemon session",
+    )
+    where = f" for account '{account}'" if account else ""
+    print(f"Login successful{where}. Session written to .env — verify with: tg me")
+
+
 async def _qr_login(args) -> None:
     api_id, api_hash = config.require_credentials()
     client = build_client(StringSession(), api_id, api_hash)
@@ -65,13 +81,7 @@ async def _qr_login(args) -> None:
         session_str = StringSession.save(client.session)
     finally:
         await client.disconnect()
-    config.write_env(
-        "TELEGRAM_SESSION_STRING",
-        session_str,
-        comment=f"generated by tg login on {date.today()}; keep secret, "
-        "do NOT share with the MCP daemon session",
-    )
-    print("Login successful. Session written to .env — verify with: tg me")
+    _save_session(args, session_str)
 
 
 async def _phone_login(args) -> None:
@@ -90,13 +100,7 @@ async def _phone_login(args) -> None:
         session_str = StringSession.save(client.session)
     finally:
         await client.disconnect()
-    config.write_env(
-        "TELEGRAM_SESSION_STRING",
-        session_str,
-        comment=f"generated by tg login on {date.today()}; keep secret, "
-        "do NOT share with the MCP daemon session",
-    )
-    print("Login successful. Session written to .env — verify with: tg me")
+    _save_session(args, session_str)
 
 
 async def cmd_login(args) -> None:
@@ -117,3 +121,22 @@ async def cmd_logout(args) -> None:
         await client.disconnect()
     config.clear_env(config.session_env_var(getattr(args, "account", None)))
     print("Logged out; session removed from .env. The MCP daemon's session is untouched.")
+
+
+async def cmd_accounts(args) -> None:
+    """List every configured account (TELEGRAM_SESSION_STRING* entries)."""
+    rows = []
+    for key in os.environ:
+        m = _SESSION_ENV_RE.fullmatch(key)
+        if m and os.environ[key].strip():
+            label = m.group(1).lower() if m.group(1) else "default"
+            rows.append((label, key))
+    rows.sort(key=lambda r: (r[0] != "default", r[0]))
+    if not rows:
+        print("(no accounts configured — run: tg login)")
+        return
+    print(f"{'account':<16} env variable")
+    for label, key in rows:
+        note = "   (default)" if label == "default" else ""
+        print(f"{label:<16} {key}{note}")
+    print("\nuse with: tg <command> --account <label>   |   add one: tg login --account <label>")

{telegram_userbot_cli-0.3.0 → telegram_userbot_cli-0.4.0}/src/tgcli/chats.py

@@ -1,4 +1,4 @@
-"""Chat / search / contacts / profile commands."""
+"""Chat / search / contacts / profile / privacy / block commands."""
 
 from datetime import datetime
 
@@ -8,6 +8,21 @@ from .client import run_with_client
 from .output import TgError, fmt_message_row, json_pp
 from .resolve import resolve_chat
 
+# friendly names for the privacy keys (value -> InputPrivacyKey class name)
+_PRIVACY_KEYS = {
+    "lastseen": "InputPrivacyKeyStatusTimestamp",
+    "phone": "InputPrivacyKeyPhoneNumber",
+    "calls": "InputPrivacyKeyPhoneCall",
+    "p2p": "InputPrivacyKeyPhoneP2P",
+    "groups": "InputPrivacyKeyChatInvite",
+    "photo": "InputPrivacyKeyProfilePhoto",
+    "forwards": "InputPrivacyKeyForwards",
+    "voicemail": "InputPrivacyKeyVoiceMessages",
+    "about": "InputPrivacyKeyAbout",
+    "birthday": "InputPrivacyKeyBirthday",
+    "addedby": "InputPrivacyKeyAddedByPhone",
+}
+
 
 async def cmd_me(args) -> None:
     async with run_with_client(args) as client:
@@ -186,6 +201,171 @@ async def cmd_profile(args) -> None:
         print(json_pp(me.to_dict() if me else {}))
 
 
+async def cmd_photo_del(args) -> None:
+    async with run_with_client(args) as client:
+        photos = await client.get_profile_photos("me")
+        if not photos:
+            print("(no profile photos)")
+            return
+        if not args.all:
+            photos = photos[:1]  # just the most recent one
+        await client(
+            functions.photos.DeletePhotosRequest(
+                id=[
+                    types.InputPhoto(
+                        id=p.id, access_hash=p.access_hash, file_reference=p.file_reference
+                    )
+                    for p in photos
+                ]
+            )
+        )
+        print(f"Deleted {len(photos)} profile photo(s)")
+
+
+def _privacy_key(name: str) -> types.TypeInputPrivacyKey:
+    cls_name = _PRIVACY_KEYS.get(name.lower())
+    if not cls_name:
+        raise TgError(
+            f"unknown privacy key: {name!r}",
+            f"choose from: {', '.join(sorted(_PRIVACY_KEYS))}",
+        )
+    return getattr(types, cls_name)()
+
+
+def _privacy_rule_text(rule, users: dict) -> str:
+    kind = type(rule).__name__.removeprefix("PrivacyValue")
+    if kind == "AllowAll":
+        return "everyone"
+    if kind == "AllowContacts":
+        return "contacts"
+    if kind == "AllowCloseFriends":
+        return "close friends"
+    if kind == "AllowBots":
+        return "bots"
+    if kind == "AllowPremium":
+        return "premium"
+    if kind == "AllowChatParticipants":
+        return "members of " + ", ".join(_display_chat(c, users) for c in rule.chats)
+    if kind == "AllowUsers":
+        return "+" + ", ".join(_display_chat(users.get(u), users) or str(u) for u in rule.users)
+    if kind == "DisallowAll":
+        return "nobody"
+    if kind == "DisallowContacts":
+        return "no contacts"
+    if kind == "DisallowUsers":
+        return "-" + ", ".join(_display_chat(users.get(u), users) or str(u) for u in rule.users)
+    return kind
+
+
+def _display_chat(chat, users: dict) -> str:
+    if chat is None:
+        return "?"
+    title = getattr(chat, "title", None)
+    if title:
+        return title
+    name = " ".join(
+        x for x in (getattr(chat, "first_name", None), getattr(chat, "last_name", None)) if x
+    )
+    return name or "?"
+
+
+async def cmd_privacy_get(args) -> None:
+    keys = args.key or sorted(_PRIVACY_KEYS)
+    async with run_with_client(args) as client:
+        rows = []
+        for name in keys:
+            res = await client(functions.account.GetPrivacyRequest(key=_privacy_key(name)))
+            users = {u.id: u for u in getattr(res, "users", []) or []}
+            rules = " + ".join(_privacy_rule_text(r, users) for r in res.rules) or "(unset)"
+            rows.append((name, rules))
+        if args.json:
+            print(json_pp([{"key": k, "rules": v} for k, v in rows]))
+            return
+        for name, rules in rows:
+            print(f"{name:<10} {rules}")
+
+
+def _input_user(client, peer) -> types.TypeInputUser:
+    if isinstance(peer, types.InputPeerUser):
+        return types.InputUser(user_id=peer.user_id, access_hash=peer.access_hash)
+    if isinstance(peer, types.InputPeerSelf):
+        return types.InputUserSelf()
+    raise TgError("only users can appear in privacy rules")
+
+
+async def cmd_privacy_set(args) -> None:
+    base = args.value.lower()
+    base_map = {"all": "everyone", "contacts": "contacts", "nobody": "nobody"}
+    if base not in base_map:
+        raise TgError(
+            f"unknown privacy value: {args.value!r}",
+            "use all / contacts / nobody, with optional --allow USER / --deny USER",
+        )
+    async with run_with_client(args) as client:
+        # rules need Input* rule classes and InputUser entries
+        resolved_allow = [
+            _input_user(client, await client.get_input_entity(await resolve_chat(client, u)))
+            for u in args.allow
+        ]
+        resolved_deny = [
+            _input_user(client, await client.get_input_entity(await resolve_chat(client, u)))
+            for u in args.deny
+        ]
+        rules: list = []
+        if base == "all":
+            rules.append(types.InputPrivacyValueAllowAll())
+        elif base == "contacts":
+            rules.append(types.InputPrivacyValueAllowContacts())
+        else:
+            rules.append(types.InputPrivacyValueDisallowAll())
+        if resolved_allow:
+            rules.append(types.InputPrivacyValueAllowUsers(users=resolved_allow))
+        if resolved_deny:
+            rules.append(types.InputPrivacyValueDisallowUsers(users=resolved_deny))
+        await client(functions.account.SetPrivacyRequest(key=_privacy_key(args.key), rules=rules))
+        desc = base_map[base]
+        if resolved_allow:
+            desc += ", allow " + ", ".join(args.allow)
+        if resolved_deny:
+            desc += ", deny " + ", ".join(args.deny)
+        print(f"{args.key} set to {desc}")
+
+
+async def cmd_block(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.user)
+        await client(functions.contacts.BlockRequest(id=entity))
+        print(f"Blocked {args.user}")
+
+
+async def cmd_unblock(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.user)
+        await client(functions.contacts.UnblockRequest(id=entity))
+        print(f"Unblocked {args.user}")
+
+
+async def cmd_blocked(args) -> None:
+    async with run_with_client(args) as client:
+        res = await client(functions.contacts.GetBlockedRequest(offset=0, limit=100))
+        users = {u.id: u for u in getattr(res, "users", []) or []}
+        rows = []
+        for pb in getattr(res, "blocked", []) or []:
+            pid = pb.peer_id.user_id if isinstance(pb.peer_id, types.PeerUser) else pb.peer_id
+            rows.append((pid, getattr(pb, "date", None)))
+        if args.json:
+            print(json_pp([p.to_dict() for p in getattr(res, "blocked", []) or []]))
+            return
+        if not rows:
+            print("(nobody is blocked)")
+            return
+        for pid, date in rows:
+            u = users.get(pid)
+            name = _display_chat(u, users) if u else str(pid)
+            when = date.astimezone().strftime("%Y-%m-%d") if date else ""
+            print(f"{pid:>14}  {name}  {when}")
+
+
 def setup(subparsers, common=None) -> None:
     parents = [common] if common else []
     sp = subparsers.add_parser("me", parents=parents, help="Show your account info")
@@ -233,3 +413,34 @@ def setup(subparsers, common=None) -> None:
     sp.add_argument("--bio", default=None)
     sp.add_argument("--photo", default=None, help="path to an image")
     sp.set_defaults(func=cmd_profile)
+
+    sp = subparsers.add_parser(
+        "photo-del", parents=parents, help="Delete your most recent profile photo (--all for all)"
+    )
+    sp.add_argument("--all", action="store_true", help="delete every profile photo")
+    sp.set_defaults(func=cmd_photo_del)
+
+    sp = subparsers.add_parser("privacy", parents=parents, help="Show privacy settings")
+    sub = sp.add_subparsers(dest="privacy_cmd", required=True)
+    g = sub.add_parser("get", help="privacy get [key...] (default: all)")
+    g.add_argument("key", nargs="*", default=[])
+    g.set_defaults(func=cmd_privacy_get)
+    s = sub.add_parser(
+        "set", help="privacy set KEY all|contacts|nobody [--allow USER] [--deny USER]"
+    )
+    s.add_argument("key", help=f"one of: {', '.join(sorted(_PRIVACY_KEYS))}")
+    s.add_argument("value")
+    s.add_argument("-a", "--allow", action="append", default=[], metavar="USER")
+    s.add_argument("-d", "--deny", action="append", default=[], metavar="USER")
+    s.set_defaults(func=cmd_privacy_set)
+
+    sp = subparsers.add_parser("block", parents=parents, help="Block a user")
+    sp.add_argument("user")
+    sp.set_defaults(func=cmd_block)
+
+    sp = subparsers.add_parser("unblock", parents=parents, help="Unblock a user")
+    sp.add_argument("user")
+    sp.set_defaults(func=cmd_unblock)
+
+    sp = subparsers.add_parser("blocked", parents=parents, help="List blocked users")
+    sp.set_defaults(func=cmd_blocked)

{telegram_userbot_cli-0.3.0 → telegram_userbot_cli-0.4.0}/src/tgcli/cli.py

@@ -6,7 +6,7 @@ import sys
 
 from telethon import errors
 
-from . import __version__, auth, chats, dialogs, groups, media, messages, resolve
+from . import __version__, auth, chats, contacts, dialogs, groups, media, messages, resolve
 from .output import TgError
 
 
@@ -41,7 +41,10 @@ def build_parser() -> argparse.ArgumentParser:
     sp2 = sub.add_parser("logout", parents=[common], help="Log out and remove the session")
     sp2.set_defaults(func=auth.cmd_logout)
 
-    for mod in (messages, chats, media, dialogs, groups):
+    sp3 = sub.add_parser("accounts", parents=[common], help="List configured accounts")
+    sp3.set_defaults(func=auth.cmd_accounts)
+
+    for mod in (messages, chats, media, dialogs, groups, contacts):
         mod.setup(sub, common)
 
     resolve.setup_alias(sub, common)

telegram_userbot_cli-0.4.0/src/tgcli/contacts.py

@@ -0,0 +1,173 @@
+"""Contact management: add, delete, bulk import/export."""
+
+import csv
+import json
+from pathlib import Path
+
+from telethon import functions, types
+
+from .client import run_with_client
+from .output import TgError, json_pp
+from .resolve import resolve_chat
+
+_FIELDS = ("phone", "first_name", "last_name")
+
+
+def _row_from(entry: dict) -> dict:
+    row = {}
+    for key in _FIELDS:
+        for alias in (key, key.replace("_", ""), {"phone": "tel"}.get(key, key)):
+            if alias in entry and str(entry[alias]).strip():
+                row[key] = str(entry[alias]).strip()
+                break
+        else:
+            row[key] = ""
+    if not row["first_name"]:
+        raise TgError(f"contact entry needs at least a first_name: {entry}")
+    return row
+
+
+def _load_contacts_file(path: str) -> list[dict]:
+    p = Path(path).expanduser()
+    if not p.exists():
+        raise TgError(f"file not found: {p}")
+    rows: list[dict] = []
+    if p.suffix.lower() == ".csv":
+        with p.open(newline="", encoding="utf-8-sig") as fh:
+            for i, raw in enumerate(csv.DictReader(fh), start=2):
+                entry = {k.strip().lower(): v for k, v in raw.items() if k}
+                try:
+                    rows.append(_row_from(entry))
+                except TgError as e:
+                    raise TgError(f"{p.name} line {i}: {e}") from None
+    else:
+        try:
+            data = json.loads(p.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as e:
+            raise TgError(
+                f"{p} is not valid JSON: {e}", "expected a list of contact objects"
+            ) from None
+        if not isinstance(data, list):
+            raise TgError(f"{p} must contain a JSON list of contact objects")
+        for i, entry in enumerate(data, start=1):
+            if not isinstance(entry, dict):
+                raise TgError(f"{p} entry {i} is not an object")
+            rows.append(_row_from(entry))
+    if not rows:
+        raise TgError(f"no contacts found in {p}")
+    return rows
+
+
+async def cmd_contact_add(args) -> None:
+    first, _, last = args.name.partition(" ")
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.user)
+        res = await client(
+            functions.contacts.AddContactRequest(
+                id=entity,
+                first_name=first,
+                last_name=last,
+                phone=args.phone or "",
+            )
+        )
+        status = getattr(res, "status", None)
+        print(f"Contact added: {args.name!r} ({args.user})" + (f" [{status}]" if status else ""))
+
+
+async def _resolve_contact_refs(client, users: list[str]) -> list:
+    """Resolve users by name/@username/id, or by phone when prefixed with +."""
+    res = await client(functions.contacts.GetContactsRequest(hash=0))
+    by_phone = {}
+    for u in getattr(res, "users", []) or []:
+        phone = getattr(u, "phone", None)
+        if phone:
+            by_phone["+" + phone.lstrip("+")] = u
+    refs = []
+    for spec in users:
+        if spec.startswith("+"):
+            u = by_phone.get(spec)
+            if u is None:
+                raise TgError(f"no contact with phone {spec}")
+            refs.append(u)
+        else:
+            refs.append(await resolve_chat(client, spec))
+    return refs
+
+
+async def cmd_contact_del(args) -> None:
+    async with run_with_client(args) as client:
+        refs = await _resolve_contact_refs(client, args.users)
+        await client(functions.contacts.DeleteContactsRequest(id=refs))
+        print(f"Deleted {len(refs)} contact(s)")
+
+
+async def cmd_contact_import(args) -> None:
+    rows = _load_contacts_file(args.file)
+    contacts = [
+        types.InputPhoneContact(
+            client_id=i,
+            phone=r["phone"] or "+10000000000",
+            first_name=r["first_name"],
+            last_name=r["last_name"],
+        )
+        for i, r in enumerate(rows)
+    ]
+    async with run_with_client(args) as client:
+        res = await client(functions.contacts.ImportContactsRequest(contacts=contacts))
+        imported = len(getattr(res, "imported", []) or [])
+        retry = len(getattr(res, "retry_contacts", []) or [])
+        print(
+            f"Imported {imported} new contact(s) from {args.file}"
+            + (f"; {retry} could not be matched" if retry else "")
+        )
+        if args.json:
+            print(json_pp([u.to_dict() for u in getattr(res, "users", []) or []]))
+
+
+async def cmd_contact_export(args) -> None:
+    async with run_with_client(args) as client:
+        res = await client(functions.contacts.GetContactsRequest(hash=0))
+        out = []
+        for u in getattr(res, "users", []) or []:
+            if not getattr(u, "contact", False):
+                continue  # GetContacts may return non-contact users; keep true contacts
+            out.append(
+                {
+                    "id": u.id,
+                    "phone": f"+{u.phone}" if getattr(u, "phone", None) else "",
+                    "first_name": u.first_name or "",
+                    "last_name": u.last_name or "",
+                    "username": getattr(u, "username", None) or "",
+                }
+            )
+        payload = json.dumps(out, ensure_ascii=False, indent=2) + "\n"
+        if args.file:
+            path = Path(args.file).expanduser()
+            path.write_text(payload, encoding="utf-8")
+            print(f"Exported {len(out)} contact(s) to {path}")
+        else:
+            print(payload, end="")
+
+
+def setup(subparsers, common=None) -> None:
+    parents = [common] if common else []
+    sp = subparsers.add_parser("contact", parents=parents, help="Manage contacts")
+    sub = sp.add_subparsers(dest="contact_cmd", required=True)
+
+    s1 = sub.add_parser("add", help="contact add USER [NAME] [--phone +86...]")
+    s1.add_argument("user")
+    s1.add_argument("name", nargs="?", default=None, help='display name, e.g. "John Doe"')
+    s1.add_argument("--phone", default="")
+    s1.set_defaults(func=cmd_contact_add)
+
+    s2 = sub.add_parser("del", help="contact del USER...")
+    s2.add_argument("users", nargs="+")
+    s2.set_defaults(func=cmd_contact_del)
+
+    s3 = sub.add_parser("import", help="contact import FILE (.json or .csv)")
+    s3.add_argument("file")
+    s3.set_defaults(func=cmd_contact_import)
+
+    s4 = sub.add_parser("export", help="contact export [FILE] (JSON, re-importable)")
+    s4.add_argument("file", nargs="?", default=None)
+    s4.set_defaults(func=cmd_contact_export)

{telegram_userbot_cli-0.3.0 → telegram_userbot_cli-0.4.0}/src/tgcli/dialogs.py

@@ -5,7 +5,7 @@ import re
 import time
 from datetime import datetime
 
-from telethon import functions, types
+from telethon import functions, types, utils
 
 from .client import run_with_client
 from .output import TgError, fmt_date, json_pp
@@ -201,6 +201,93 @@ async def cmd_common_chats(args) -> None:
             print(f"{c.id:>14}  {title}  {'@' + uname if uname else ''}")
 
 
+# ---- dialog folders ----
+
+
+def _filter_title(f) -> str:
+    t = getattr(f, "title", None)
+    return getattr(t, "text", None) or str(t or "?")
+
+
+async def _get_filters(client) -> list:
+    res = await client(functions.messages.GetDialogFiltersRequest())
+    return [f for f in (getattr(res, "filters", None) or []) if isinstance(f, types.DialogFilter)]
+
+
+async def _find_filter(client, spec: str):
+    for f in await _get_filters(client):
+        if str(f.id) == spec or _filter_title(f).lower() == spec.lower():
+            return f
+    raise TgError(f"folder not found: {spec!r}", "list folders with: tg folders")
+
+
+async def cmd_folders(args) -> None:
+    async with run_with_client(args) as client:
+        filters = await _get_filters(client)
+        if args.json:
+            print(json_pp([f.to_dict() for f in filters]))
+            return
+        if not filters:
+            print("(no folders — create one with: tg folder-create <name> --chat <chat>)")
+            return
+        for f in filters:
+            print(f"[{f.id:>2}] {_filter_title(f)}  ({len(f.include_peers)} chats)")
+
+
+async def cmd_folder_create(args) -> None:
+    if not args.chat:
+        raise TgError("pass at least one chat: --chat <chat>")
+    async with run_with_client(args) as client:
+        existing = await _get_filters(client)
+        new_id = max((f.id for f in existing), default=1) + 1
+        peers = [await _input_peer(client, c) for c in args.chat]
+        filt = types.DialogFilter(
+            id=new_id,
+            title=types.TextWithEntities(text=args.name, entities=[]),
+            pinned_peers=[],
+            include_peers=peers,
+            exclude_peers=[],
+        )
+        await client(functions.messages.UpdateDialogFilterRequest(id=new_id, filter=filt))
+        print(f"Folder created: [{new_id}] {args.name} ({len(peers)} chats)")
+
+
+async def cmd_folder_assign(args) -> None:
+    async with run_with_client(args) as client:
+        filt = await _find_filter(client, args.folder)
+        known = {utils.get_peer_id(p) for p in filt.include_peers}
+        added = 0
+        for c in args.chat:
+            peer = await _input_peer(client, c)
+            if utils.get_peer_id(peer) not in known:
+                filt.include_peers.append(peer)
+                added += 1
+        await client(functions.messages.UpdateDialogFilterRequest(id=filt.id, filter=filt))
+        print(f"Added {added} chat(s) to folder [{filt.id}] {_filter_title(filt)}")
+
+
+async def cmd_folder_del(args) -> None:
+    async with run_with_client(args) as client:
+        filt = await _find_filter(client, args.folder)
+        # no filter object with the id = delete the folder
+        await client(functions.messages.UpdateDialogFilterRequest(id=filt.id))
+        print(f"Folder deleted: [{filt.id}] {_filter_title(filt)}")
+
+
+async def cmd_folder_order(args) -> None:
+    async with run_with_client(args) as client:
+        ids = []
+        for spec in args.folder:
+            filt = await _find_filter(client, spec)
+            if filt.id in ids:
+                raise TgError(f"folder {spec!r} listed twice")
+            ids.append(filt.id)
+        all_ids = [f.id for f in await _get_filters(client)]
+        missing = [i for i in all_ids if i not in ids]
+        await client(functions.messages.UpdateDialogFiltersOrderRequest(order=ids + missing))
+        print("Folder order updated: " + " → ".join(str(i) for i in ids))
+
+
 def setup(subparsers, common=None) -> None:
     parents = [common] if common else []
     sp = subparsers.add_parser("archive", parents=parents, help="Archive a chat")
@@ -267,3 +354,32 @@ def setup(subparsers, common=None) -> None:
     )
     sp.add_argument("user")
     sp.set_defaults(func=cmd_common_chats)
+
+    sp = subparsers.add_parser("folders", parents=parents, help="List dialog folders")
+    sp.set_defaults(func=cmd_folders)
+
+    sp = subparsers.add_parser(
+        "folder-create",
+        parents=parents,
+        help='Create a folder, e.g. tg folder-create Work --chat "@boss"',
+    )
+    sp.add_argument("name")
+    sp.add_argument("--chat", action="append", default=[], help="chat to include (repeatable)")
+    sp.set_defaults(func=cmd_folder_create)
+
+    sp = subparsers.add_parser(
+        "folder-assign", parents=parents, help="Add chats to an existing folder"
+    )
+    sp.add_argument("folder", help="folder name or id")
+    sp.add_argument("chat", nargs="+")
+    sp.set_defaults(func=cmd_folder_assign)
+
+    sp = subparsers.add_parser("folder-del", parents=parents, help="Delete a folder")
+    sp.add_argument("folder", help="folder name or id")
+    sp.set_defaults(func=cmd_folder_del)
+
+    sp = subparsers.add_parser(
+        "folder-order", parents=parents, help="Reorder folders (pass all of them in order)"
+    )
+    sp.add_argument("folder", nargs="+", help="folder names/ids in the wanted order")
+    sp.set_defaults(func=cmd_folder_order)

{telegram_userbot_cli-0.3.0 → telegram_userbot_cli-0.4.0}/src/tgcli/media.py

@@ -1,9 +1,10 @@
-"""Media commands: dl (download), sf (send file/album), voice, sticker, gif."""
+"""Media commands: dl (download), sf (send file/album), voice, sticker, gif, vtr."""
 
+import asyncio
 import os
 import re
 
-from telethon import functions
+from telethon import functions, types
 
 from .client import run_with_client
 from .output import TgError
@@ -92,6 +93,36 @@ async def cmd_gif(args) -> None:
         print(f"GIF sent (match {idx + 1} of {len(docs)} for {args.query!r})")
 
 
+async def cmd_vtr(args) -> None:
+    async with run_with_client(args) as client:
+        entity = await resolve_chat(client, args.chat)
+        msg = await client.get_messages(entity, ids=args.msg_id)
+        doc = getattr(getattr(msg, "media", None), "document", None)
+        is_voice = any(
+            isinstance(a, types.DocumentAttributeAudio) and a.voice
+            for a in getattr(doc, "attributes", [])
+        )
+        if not is_voice:
+            raise TgError(
+                f"message {args.msg_id} has no voice note",
+                hint=f"check with: tg hist {args.chat} 5",
+            )
+        text, pending = "", True
+        for _ in range(10):
+            res = await client(
+                functions.messages.TranscribeAudioRequest(peer=entity, msg_id=args.msg_id)
+            )
+            text, pending = res.text or "", bool(res.pending)
+            if not pending:
+                break
+            await asyncio.sleep(1.5)
+        if pending:
+            raise TgError("transcription is still processing; try again in a moment")
+        if not text:
+            raise TgError("no transcription returned (Telegram Premium required for this feature)")
+        print(text)
+
+
 def setup(subparsers, common=None) -> None:
     parents = [common] if common else []
     sp = subparsers.add_parser(
@@ -132,3 +163,10 @@ def setup(subparsers, common=None) -> None:
     sp.add_argument("query")
     sp.add_argument("-n", "--index", type=int, default=1, help="send the Nth match (default 1)")
     sp.set_defaults(func=cmd_gif)
+
+    sp = subparsers.add_parser(
+        "vtr", parents=parents, help="Transcribe a voice note (Telegram Premium)"
+    )
+    sp.add_argument("chat")
+    sp.add_argument("msg_id", type=int)
+    sp.set_defaults(func=cmd_vtr)