vibegram 1.0.0__tar.gz

vibegram-1.0.0/LICENSE

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

vibegram-1.0.0/PKG-INFO

@@ -0,0 +1,72 @@
+Metadata-Version: 2.4
+Name: vibegram
+Version: 1.0.0
+Summary: Python client library for Vibe Messenger (MTProto over WebSocket)
+Author-email: Ali VEX <lyrdaadhrpyk802@gmail.com>
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: websockets>=13.0
+Requires-Dist: pycryptodome>=3.20
+Requires-Dist: telethon>=1.36
+Requires-Dist: python-socks[asyncio]>=2.4
+Requires-Dist: rsa>=4.9
+Provides-Extra: dev
+Requires-Dist: scapy>=2.5; extra == "dev"
+Requires-Dist: pytest>=7.0; extra == "dev"
+Dynamic: license-file
+
+# pyvibe
+
+Python client library for Vibe Messenger (vibegram.chat).
+MTProto over WebSocket with Vibe's custom authentication scheme.
+
+## About the Author
+- Name: Ali VEX
+- Email: lyrdaadhrpyk802@gmail.com
+- GitHub: lyrdaadhrpyk802-ux
+- Jabber: @UserBoT
+
+(درباره سازنده: علی، توسعه‌دهنده پایتون. این پروژه در محیط Termux اندروید بدون روت توسعه یافته است.)
+
+## Project Status
+- 852 high-level methods available directly on VibeClient.
+- Full passthrough to 875 Telethon TL requests (raw API).
+- Verified end-to-end: Login, Messaging, Media, Stories, Forums, JSON Backups.
+
+(وضعیت پروژه: کتابخانه به صورت کامل روی سرور Vibe تست شده است. احراز هویت اختصاصی Vibe، ارسال و دریافت مدیا، استوری، فروم و بکاپ‌گیری کاملاً عملیاتی هستند.)
+
+## Installation
+cd pyvibe
+pip install -e .
+
+## Quick Start
+import asyncio
+from userapi import VibeClient
+
+async def main():
+    c = VibeClient()
+    await c.connect()
+    
+    if not await c.is_authorized():
+        phone = input("Phone: ")
+        await c.request_code(phone)
+        code = input("OTP: ")
+        await c.sign_in(phone, code)
+        
+    me = await c.get_me()
+    print(f"Logged in as {me.first_name}")
+    
+    await c.send_message("me", "Hello from pyvibe")
+    await c.disconnect()
+
+asyncio.run(main())
+
+## Documentation
+- ARCHITECTURE.md - Technical details of transport and auth.
+- VIBE_COMPAT.md - Feature support matrix.
+- examples/ - 11 guided examples with Persian comments.
+
+## License
+MIT License

vibegram-1.0.0/README.md

@@ -0,0 +1,53 @@
+# pyvibe
+
+Python client library for Vibe Messenger (vibegram.chat).
+MTProto over WebSocket with Vibe's custom authentication scheme.
+
+## About the Author
+- Name: Ali VEX
+- Email: lyrdaadhrpyk802@gmail.com
+- GitHub: lyrdaadhrpyk802-ux
+- Jabber: @UserBoT
+
+(درباره سازنده: علی، توسعه‌دهنده پایتون. این پروژه در محیط Termux اندروید بدون روت توسعه یافته است.)
+
+## Project Status
+- 852 high-level methods available directly on VibeClient.
+- Full passthrough to 875 Telethon TL requests (raw API).
+- Verified end-to-end: Login, Messaging, Media, Stories, Forums, JSON Backups.
+
+(وضعیت پروژه: کتابخانه به صورت کامل روی سرور Vibe تست شده است. احراز هویت اختصاصی Vibe، ارسال و دریافت مدیا، استوری، فروم و بکاپ‌گیری کاملاً عملیاتی هستند.)
+
+## Installation
+cd pyvibe
+pip install -e .
+
+## Quick Start
+import asyncio
+from userapi import VibeClient
+
+async def main():
+    c = VibeClient()
+    await c.connect()
+    
+    if not await c.is_authorized():
+        phone = input("Phone: ")
+        await c.request_code(phone)
+        code = input("OTP: ")
+        await c.sign_in(phone, code)
+        
+    me = await c.get_me()
+    print(f"Logged in as {me.first_name}")
+    
+    await c.send_message("me", "Hello from pyvibe")
+    await c.disconnect()
+
+asyncio.run(main())
+
+## Documentation
+- ARCHITECTURE.md - Technical details of transport and auth.
+- VIBE_COMPAT.md - Feature support matrix.
+- examples/ - 11 guided examples with Persian comments.
+
+## License
+MIT License

vibegram-1.0.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "vibegram"
+version = "1.0.0"
+description = "Python client library for Vibe Messenger (MTProto over WebSocket)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Ali VEX", email = "lyrdaadhrpyk802@gmail.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "websockets>=13.0",
+    "pycryptodome>=3.20",
+    "telethon>=1.36",
+    "python-socks[asyncio]>=2.4",
+    "rsa>=4.9",
+]
+
+[project.scripts]
+vibe = "scripts.vibe:main"
+
+[project.optional-dependencies]
+dev = [
+    "scapy>=2.5",
+    "pytest>=7.0",
+]
+
+[tool.setuptools.packages.find]
+include = ["userapi*", "botapi*", "scripts*"]
+
+[tool.pytest.ini_options]
+testpaths = ["userapi/tests"]

vibegram-1.0.0/scripts/backup_chat.py

@@ -0,0 +1,75 @@
+# ============================================
+#  scripts/backup_chat.py - CLI to backup a chat to JSON
+#  Usage:
+#    python -B scripts/backup_chat.py <peer>
+#    python -B scripts/backup_chat.py <peer> --limit 1000
+#    python -B scripts/backup_chat.py <peer> --no-media
+#    python -B scripts/backup_chat.py <peer> --fresh
+#    python -B scripts/backup_chat.py <peer> --output ~/my_backups
+#  All code and comments are English. No emojis.
+# ============================================
+import argparse
+import asyncio
+import os
+import sys
+
+from userapi import VibeClient
+from userapi.backup import backup_chat
+
+
+async def main():
+    ap = argparse.ArgumentParser(prog="backup_chat")
+    ap.add_argument("peer", help="username (@x), id, phone, or title")
+    ap.add_argument("--limit", type=int, default=None,
+                    help="max messages per run (default: all)")
+    ap.add_argument("--no-media", action="store_true",
+                    help="skip downloading media files")
+    ap.add_argument("--output", default=None,
+                    help="output root directory (default: ~/pyvibe/backups)")
+    ap.add_argument("--fresh", action="store_true",
+                    help="ignore existing backup and start over")
+    ap.add_argument("--quiet", action="store_true",
+                    help="do not print per-message progress")
+    args = ap.parse_args()
+
+    if os.getenv("VIBE_DEBUG") != "1":
+        import logging
+        logging.getLogger("telethon.network.mtprotosender").setLevel(logging.CRITICAL)
+        logging.getLogger("telethon.network.connection.connection").setLevel(logging.CRITICAL)
+        logging.getLogger("websockets").setLevel(logging.CRITICAL)
+
+    c = VibeClient()
+    try:
+        await c.connect()
+
+        def progress(step, total, msg):
+            if args.quiet:
+                return
+            mt = msg.get("media_type") or "-"
+            txt = (msg.get("text") or "")[:40].replace("\n", " ")
+            print(f"  [{step}{('/' + str(total)) if total else ''}] "
+                  f"id={msg.get('id')} {mt:8s} {txt!r}")
+
+        path, doc = await backup_chat(
+            c, args.peer,
+            output_root=args.output,
+            limit=args.limit,
+            download_media=not args.no_media,
+            progress=progress,
+            fresh=args.fresh,
+        )
+        print(f"\n[+] saved {doc['message_count']} message(s), "
+              f"{doc['media_count']} media file(s)")
+        print(f"[+] json: {path}")
+        print(f"[+] dir:  {path.parent}")
+    except Exception as e:
+        print(f"[backup_chat] error: {type(e).__name__}: {e}")
+    finally:
+        await c.disconnect()
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        sys.exit(0)

vibegram-1.0.0/scripts/chat_info.py

@@ -0,0 +1,272 @@
+# ============================================
+#  scripts/chat_info.py - "info" helper
+#  Listens for "info" messages you send in any chat and replies with a
+#  full dump: users / groups / channels / supergroups.
+#  All code and comments are English. No emojis.
+# ============================================
+import asyncio
+import os
+import sys
+from datetime import datetime, timezone
+
+from telethon import events
+from telethon.tl.functions.messages import GetFullChatRequest
+from telethon.tl.types import (
+    User, UserEmpty, Channel, ChannelForbidden,
+    Chat, ChatForbidden,
+)
+
+from userapi import VibeClient
+
+# Silence benign Telethon shutdown noise (WebSocket ConnectionClosedOK) unless
+# explicitly debugging. This is not part of INFO_DEBUG; keep the terminal clean.
+if os.getenv("VIBE_DEBUG") != "1":
+    import logging
+    logging.getLogger("telethon.network.mtprotosender").setLevel(logging.CRITICAL)
+    logging.getLogger("telethon.network.connection.connection").setLevel(logging.CRITICAL)
+    logging.getLogger("websockets").setLevel(logging.CRITICAL)
+
+
+def _fmt_date(dt):
+    if dt is None:
+        return "?"
+    if isinstance(dt, datetime):
+        return dt.astimezone(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+    return str(dt)
+
+
+def _status_str(user):
+    s = getattr(user, "status", None)
+    if s is None:
+        return "?"
+    name = type(s).__name__
+    if name == "UserStatusOnline":
+        return f"online until {_fmt_date(getattr(s, 'expires', None))}"
+    if name == "UserStatusOffline":
+        return f"offline (last seen {_fmt_date(getattr(s, 'was_online', None))})"
+    if name == "UserStatusRecently":
+        return "recently"
+    if name == "UserStatusLastWeek":
+        return "last week"
+    if name == "UserStatusLastMonth":
+        return "last month"
+    return name
+
+
+async def info_user(client, user):
+    lines = ["=== USER INFO ===", f"id: {user.id}"]
+    lines.append(f"username: @{user.username}" if getattr(user, "username", None) else "username: -")
+    lines.append(f"first_name: {getattr(user, 'first_name', None) or '-'}")
+    lines.append(f"last_name: {getattr(user, 'last_name', None) or '-'}")
+    lines.append(f"phone: {getattr(user, 'phone', None) or '-'}")
+    lines.append(f"bot: {bool(getattr(user, 'bot', False))}")
+    lines.append(f"verified: {bool(getattr(user, 'verified', False))}")
+    lines.append(f"premium: {bool(getattr(user, 'premium', False))}")
+    lines.append(f"deleted: {bool(getattr(user, 'deleted', False))}")
+    lines.append(f"status: {_status_str(user)}")
+
+    if not isinstance(user, UserEmpty):
+        try:
+            full = await client.get_full_user(user)
+            fu = getattr(full, "full_user", None)
+            if fu is not None:
+                lines.append(f"about: {getattr(fu, 'about', None) or '-'}")
+                lines.append(f"common_chats: {getattr(fu, 'common_chats_count', 0)}")
+                lines.append(f"blocked: {bool(getattr(fu, 'blocked', False))}")
+                lines.append(f"phone_calls_available: {getattr(fu, 'phone_calls_available', '?')}")
+                lines.append(f"voice_messages_forbidden: {bool(getattr(fu, 'voice_messages_forbidden', False))}")
+        except Exception as e:
+            lines.append(f"(full_user fetch failed: {type(e).__name__}: {e})")
+    return "\n".join(lines)
+
+
+async def info_group(client, chat):
+    lines = ["=== GROUP INFO ===", f"id: {chat.id}"]
+    lines.append(f"title: {getattr(chat, 'title', '-')}")
+    lines.append(f"participants_count: {getattr(chat, 'participants_count', '?')}")
+    lines.append(f"date: {_fmt_date(getattr(chat, 'date', None))}")
+    lines.append(f"creator: {bool(getattr(chat, 'creator', False))}")
+    lines.append(f"kicked: {bool(getattr(chat, 'kicked', False))}")
+    lines.append(f"deactivated: {bool(getattr(chat, 'deactivated', False))}")
+    lines.append(f"version: {getattr(chat, 'version', '?')}")
+
+    try:
+        r = await client.raw(GetFullChatRequest(chat_id=chat.id))
+        fc = getattr(r, "full_chat", None)
+        if fc is not None:
+            lines.append(f"about: {getattr(fc, 'about', None) or '-'}")
+            parts = getattr(fc, "participants", None)
+            if parts is not None:
+                lines.append(f"participants_loaded: {len(getattr(parts, 'participants', []) or [])}")
+            lines.append(f"can_set_username: {bool(getattr(fc, 'can_set_username', False))}")
+            lines.append(f"can_set_stickers: {bool(getattr(fc, 'can_set_stickers', False))}")
+            lines.append(f"can_set_location: {bool(getattr(fc, 'can_set_location', False))}")
+            lines.append(f"hidden_prehistory: {bool(getattr(fc, 'hidden_prehistory', False))}")
+    except Exception as e:
+        lines.append(f"(full_chat fetch failed: {type(e).__name__}: {e})")
+    return "\n".join(lines)
+
+
+async def info_channel(client, channel):
+    is_megagroup = bool(getattr(channel, "megagroup", False))
+    is_broadcast = bool(getattr(channel, "broadcast", False))
+    if is_megagroup:
+        kind = "SUPERGROUP"
+    elif is_broadcast:
+        kind = "CHANNEL"
+    else:
+        kind = "CHANNEL/GROUP"
+
+    lines = [f"=== {kind} INFO ===", f"id: {channel.id}"]
+    lines.append(f"title: {getattr(channel, 'title', '-')}")
+    if getattr(channel, "username", None):
+        lines.append(f"username: @{channel.username}")
+    else:
+        lines.append("username: -")
+    lines.append(f"broadcast: {is_broadcast}")
+    lines.append(f"megagroup: {is_megagroup}")
+    lines.append(f"verified: {bool(getattr(channel, 'verified', False))}")
+    lines.append(f"scam: {bool(getattr(channel, 'scam', False))}")
+    lines.append(f"fake: {bool(getattr(channel, 'fake', False))}")
+    lines.append(f"restricted: {bool(getattr(channel, 'restricted', False))}")
+    lines.append(f"signatures: {bool(getattr(channel, 'signatures', False))}")
+    lines.append(f"date: {_fmt_date(getattr(channel, 'date', None))}")
+    lines.append(f"creator: {bool(getattr(channel, 'creator', False))}")
+    lines.append(f"left: {bool(getattr(channel, 'left', False))}")
+    lines.append(f"kicked: {bool(getattr(channel, 'kicked', False))}")
+    if getattr(channel, "linked_chat_id", None):
+        lines.append(f"linked_chat_id: {channel.linked_chat_id}")
+    if getattr(channel, "slowmode_seconds", None):
+        lines.append(f"slowmode_seconds: {channel.slowmode_seconds}")
+
+    if isinstance(channel, ChannelForbidden):
+        lines.append("(ChannelForbidden: no full info available)")
+        return "\n".join(lines)
+
+    # creator/admin flag check
+    try:
+        admin_rights = getattr(channel, "admin_rights", None)
+        if admin_rights is not None:
+            lines.append(f"admin_rights: {admin_rights}")
+    except Exception:
+        pass
+
+    try:
+        full = await client.get_full_channel(channel)
+        fc = getattr(full, "full_chat", None)
+        if fc is not None:
+            for key in [
+                "about", "participants_count", "online_count",
+                "admins_count", "kicked_count", "banned_count",
+                "can_view_participants", "can_set_username",
+                "can_set_stickers", "hidden_prehistory",
+                "can_set_location", "has_scheduled",
+            ]:
+                v = getattr(fc, key, None)
+                if isinstance(v, bool):
+                    lines.append(f"{key}: {v}")
+                elif v not in (None, ""):
+                    lines.append(f"{key}: {v}")
+    except Exception as e:
+        lines.append(f"(full_channel fetch failed: {type(e).__name__}: {e})")
+    return "\n".join(lines)
+
+
+async def collect_info(client, entity):
+    if isinstance(entity, (User, UserEmpty)):
+        return await info_user(client, entity)
+    if isinstance(entity, (Channel, ChannelForbidden)):
+        return await info_channel(client, entity)
+    if isinstance(entity, (Chat, ChatForbidden)):
+        return await info_group(client, entity)
+    return f"=== UNKNOWN entity: {type(entity).__name__} ==="
+
+
+async def main():
+    c = VibeClient()
+    try:
+        await c.connect()
+        me = await c.get_me()
+        print(f"[+] connected as id={me.id} @{me.username}")
+        print("[+] listening for 'info' / '/info' messages (yours only)")
+        print("    Ctrl+C to stop\n")
+
+        debug = os.getenv("INFO_DEBUG") == "1"
+
+        @c.raw.on(events.NewMessage())
+        async def handler(event):
+            text = (event.raw_text or "").strip().lower()
+            if text not in ("info", "/info", ".info"):
+                return
+
+            # Robust chat resolution (channels sometimes need fallback)
+            chat = await event.get_chat()
+            if chat is None and getattr(event, "chat_id", None) is not None:
+                try:
+                    chat = await c.get_entity(event.chat_id)
+                except Exception:
+                    chat = None
+            if chat is None:
+                if debug:
+                    print(f"[debug] 'info' msg with no chat: chat_id={getattr(event, 'chat_id', None)}")
+                return
+
+            # Robust sender detection: works for users, groups, supergroups,
+            # and channels (both as-user and anonymous-as-channel posts).
+            sender = None
+            try:
+                sender = await event.get_sender()
+            except Exception:
+                sender = None
+
+            out = getattr(event, "out", None)
+            sender_id = getattr(sender, "id", None) if sender is not None else None
+            chat_id = getattr(chat, "id", None)
+
+            is_mine = (
+                out is True
+                or sender_id == me.id
+                or (chat_id is not None and sender_id == chat_id)
+            )
+
+            if debug:
+                print(f"[debug] 'info' in chat_id={chat_id} "
+                      f"sender_id={sender_id} out={out} is_mine={is_mine}")
+
+            if not is_mine:
+                return
+
+            try:
+                info = await collect_info(c, chat)
+            except Exception as e:
+                info = f"[chat_info] error: {type(e).__name__}: {e}"
+
+            title = getattr(chat, "title", None) or getattr(chat, "username", None) or getattr(chat, "id", "?")
+            if debug:
+                print("\n" + info + "\n")
+
+            try:
+                await event.reply(info)
+                print(f"[+] info sent -> {title}")
+            except Exception as e:
+                print(f"[chat_info] reply failed: {type(e).__name__}: {e}")
+                try:
+                    await c.send_message(chat, info)
+                    print(f"[+] info sent (fallback) -> {title}")
+                except Exception as e2:
+                    print(f"[chat_info] send_message also failed: {type(e2).__name__}: {e2}")
+
+        await c.raw.run_until_disconnected()
+    except KeyboardInterrupt:
+        pass
+    except Exception as e:
+        print(f"[chat_info] fatal: {type(e).__name__}: {e}")
+    finally:
+        await c.disconnect()
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        sys.exit(0)

vibegram-1.0.0/scripts/name_clock.py

@@ -0,0 +1,135 @@
+# ============================================
+#  scripts/name_clock.py - live clock in first_name
+#  Updates first_name to "<original>•HH:MM" (Tehran time) every 70s.
+#  Restores original name on Ctrl+C or SIGTERM.
+#  All code and comments are English. No emojis.
+# ============================================
+import asyncio
+import os
+import signal
+import sys
+from datetime import datetime, timedelta, timezone
+
+from telethon.errors import FloodWaitError
+
+from userapi import VibeClient
+
+
+# Iran: fixed offset UTC+3:30 (no DST since 2022). Using a fixed offset
+# avoids relying on the tzdata package being installed on Termux.
+TEHRAN = timezone(timedelta(hours=3, minutes=30))
+
+UPDATE_INTERVAL = 70.0          # seconds between updates
+SEPARATOR = "\u2022"            # bullet
+FIRST_NAME_MAX = 64             # Telegram limit (bytes for safety we use chars)
+
+
+def _tehran_hhmm():
+    return datetime.now(TEHRAN).strftime("%H:%M")
+
+
+def _build_first_name(base, hhmm):
+    """Compose base + separator + HH:MM, truncating base if needed."""
+    suffix = f"{SEPARATOR}{hhmm}"
+    room = FIRST_NAME_MAX - len(suffix)
+    if room < 1:
+        return suffix[-FIRST_NAME_MAX:]
+    return base[:room] + suffix
+
+
+async def main():
+    if os.getenv("VIBE_DEBUG") != "1":
+        import logging
+        logging.getLogger("telethon.network.mtprotosender").setLevel(logging.CRITICAL)
+        logging.getLogger("telethon.network.connection.connection").setLevel(logging.CRITICAL)
+        logging.getLogger("websockets").setLevel(logging.CRITICAL)
+
+    c = VibeClient()
+    stop_event = asyncio.Event()
+
+    def _stop(*_):
+        stop_event.set()
+
+    try:
+        loop = asyncio.get_running_loop()
+        for sig in (signal.SIGINT, signal.SIGTERM):
+            try:
+                loop.add_signal_handler(sig, _stop)
+            except NotImplementedError:
+                # Termux/android fallback
+                signal.signal(sig, lambda *_: stop_event.set())
+
+        await c.connect()
+
+        me = await c.get_me()
+        original_first = getattr(me, "first_name", "") or ""
+        original_last = getattr(me, "last_name", "") or ""
+        base = original_first.strip()
+
+        print(f"[+] connected as id={me.id} @{getattr(me, 'username', '-')}")
+        print(f"[+] original first_name = {original_first!r}")
+        print(f"[+] original last_name  = {original_last!r}")
+        print(f"[+] base = {base!r}")
+        print(f"[+] updating every {int(UPDATE_INTERVAL)}s to '{base}{SEPARATOR}HH:MM' (Tehran)")
+        print("[+] Ctrl+C to stop and restore\n")
+
+        last_sent = None
+
+        while not stop_event.is_set():
+            hhmm = _tehran_hhmm()
+            new_first = _build_first_name(base, hhmm)
+
+            if new_first == last_sent:
+                # Avoid redundant update_profile calls when minute didn't
+                # change (can happen due to 70s interval).
+                if os.getenv("NAME_DEBUG") == "1":
+                    print(f"[debug] skipping unchanged name {new_first!r}")
+            else:
+                try:
+                    await c.update_profile(
+                        first_name=new_first,
+                        last_name=original_last or None,
+                    )
+                    last_sent = new_first
+                    print(f"[+] name -> {new_first!r}")
+                except FloodWaitError as e:
+                    wait_s = getattr(e, "seconds", 60) + 5
+                    print(f"[!] FLOOD_WAIT {wait_s}s, backing off")
+                    try:
+                        await asyncio.wait_for(stop_event.wait(), timeout=wait_s)
+                    except asyncio.TimeoutError:
+                        pass
+                    continue
+                except Exception as e:
+                    print(f"[!] update_profile failed: {type(e).__name__}: {e}")
+
+            # Wait the remaining interval, but wake up early on Ctrl+C
+            try:
+                await asyncio.wait_for(stop_event.wait(), timeout=UPDATE_INTERVAL)
+            except asyncio.TimeoutError:
+                pass
+
+        print("\n[i] stopping, restoring original name...")
+        try:
+            await c.update_profile(
+                first_name=original_first or None,
+                last_name=original_last or None,
+            )
+            print(f"[+] restored first_name={original_first!r} last_name={original_last!r}")
+        except Exception as e:
+            print(f"[!] restore failed: {type(e).__name__}: {e}")
+            print(f"    run: python -B scripts/restore_name.py")
+    except Exception as e:
+        print(f"[name_clock] fatal: {type(e).__name__}: {e}")
+    finally:
+        try:
+            await c.disconnect()
+        except Exception:
+            pass
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        pass