Automated sync from GitHub

.env.example

@@ -0,0 +1,26 @@
+# --- Telegram -------------------------------------------------------------
+API_ID=
+API_HASH=
+BOT_TOKEN=
+# Numeric Telegram ids (ask @userinfobot). Owners can do everything, admins can only create/edit posts.
+OWNER_IDS=
+ADMIN_IDS=
+
+# --- Database -------------------------------------------------------------
+# PostgreSQL, e.g. a free Neon database. Leave empty to use a local SQLite file (data/bot.db).
+DATABASE_URL=postgresql://user:password@host/dbname?sslmode=require
+# "null" = short-lived connections (lets serverless Postgres sleep); "queue" = normal pool for an always-on DB
+DB_POOL=null
+
+# --- Optional -------------------------------------------------------------
+# Where the login session is kept. On hosts that wipe files on restart, run `python make_session.py`
+# once and put the printed text in SESSION_STRING instead.
+SESSION_PATH=data/bot
+SESSION_STRING=
+# Seconds between edits during /replace (Telegram rate limits: don't go much lower)
+EDIT_DELAY=1.2
+# Also swap links that are typed as plain text in a post (not only hyperlinks and buttons)
+REPLACE_TYPED_LINKS=true
+# Some free hosts need an open port: set it and the bot answers "ok" on /
+PORT=
+LOG_LEVEL=INFO

.gitattributes

@@ -1,36 +1,8 @@
-*.7z filter=lfs diff=lfs merge=lfs -text
-*.arrow filter=lfs diff=lfs merge=lfs -text
-*.bin filter=lfs diff=lfs merge=lfs -text
-*.bz2 filter=lfs diff=lfs merge=lfs -text
-*.ckpt filter=lfs diff=lfs merge=lfs -text
-*.ftz filter=lfs diff=lfs merge=lfs -text
-*.gz filter=lfs diff=lfs merge=lfs -text
-*.h5 filter=lfs diff=lfs merge=lfs -text
-*.joblib filter=lfs diff=lfs merge=lfs -text
-*.lfs.* filter=lfs diff=lfs merge=lfs -text
-*.mlmodel filter=lfs diff=lfs merge=lfs -text
-*.model filter=lfs diff=lfs merge=lfs -text
-*.msgpack filter=lfs diff=lfs merge=lfs -text
-*.npy filter=lfs diff=lfs merge=lfs -text
-*.npz filter=lfs diff=lfs merge=lfs -text
-*.onnx filter=lfs diff=lfs merge=lfs -text
-*.ot filter=lfs diff=lfs merge=lfs -text
-*.parquet filter=lfs diff=lfs merge=lfs -text
-*.pb filter=lfs diff=lfs merge=lfs -text
-*.pickle filter=lfs diff=lfs merge=lfs -text
-*.pkl filter=lfs diff=lfs merge=lfs -text
-*.pt filter=lfs diff=lfs merge=lfs -text
-*.pth filter=lfs diff=lfs merge=lfs -text
-*.rar filter=lfs diff=lfs merge=lfs -text
-*.safetensors filter=lfs diff=lfs merge=lfs -text
-saved_model/**/* filter=lfs diff=lfs merge=lfs -text
-*.tar.* filter=lfs diff=lfs merge=lfs -text
-*.tar filter=lfs diff=lfs merge=lfs -text
-*.tflite filter=lfs diff=lfs merge=lfs -text
-*.tgz filter=lfs diff=lfs merge=lfs -text
-*.wasm filter=lfs diff=lfs merge=lfs -text
-*.xz filter=lfs diff=lfs merge=lfs -text
-*.zip filter=lfs diff=lfs merge=lfs -text
-*.zst filter=lfs diff=lfs merge=lfs -text
-*tfevents* filter=lfs diff=lfs merge=lfs -text
-rasengan.mp4 filter=lfs diff=lfs merge=lfs -text
+*.otf filter=lfs diff=lfs merge=lfs -text
+*.webp filter=lfs diff=lfs merge=lfs -text
+*.mp4 filter=lfs diff=lfs merge=lfs -text
+*.mp3 filter=lfs diff=lfs merge=lfs -text
+*.jpg filter=lfs diff=lfs merge=lfs -text
+*.jpeg filter=lfs diff=lfs merge=lfs -text
+*.png filter=lfs diff=lfs merge=lfs -text
+*.ttf filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -1,2 +1,7 @@
-.DS_Store
-**/.DS_Store
+.env
+data/*
+!data/.gitkeep
+*.session
+*.session-journal
+__pycache__/
+.pytest_cache/

Dockerfile

@@ -0,0 +1,7 @@
+FROM python:3.12-slim
+WORKDIR /app
+ENV PYTHONUNBUFFERED=1
+COPY requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY . .
+CMD ["python", "bot.py"]

app/buttons.py

@@ -0,0 +1,144 @@
+"""Button model: rows of {'t': text, 'u': url} (URL buttons) or {'t', 'raw'} (other bots' buttons, kept as-is)."""
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+MAX_ROW = 8
+MAX_TOTAL = 100
+_URL_RX = re.compile(r"(?:https?://|tg://|t\.me/|telegram\.me/)\S+", re.I)
+
+
+def norm_url(u: str) -> Optional[str]:
+    u = (u or "").strip()
+    if re.match(r"(?i)^(t\.me|telegram\.me)/", u):
+        u = "https://" + u
+    if not re.match(r"(?i)^(https?://|tg://)\S+$", u) or len(u) > 2000:
+        return None
+    return u
+
+
+def parse_buttons_text(text: str) -> list:
+    """One row per line, 'Text - link'. Several buttons in a row: separate them with ' | '."""
+    rows: list = []
+    total = 0
+    for line in (text or "").strip().splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        row = []
+        for part in re.split(r"\s+\|\s+|\s*&&\s*", line):
+            part = part.strip()
+            if not part:
+                continue
+            found = list(_URL_RX.finditer(part))
+            if not found:
+                raise ValueError(f"No link found in: {part}")
+            m = found[-1]
+            label = part[: m.start()].strip().rstrip("-–—:|=").strip()
+            if not label:
+                raise ValueError(f"No button text before the link in: {part}")
+            url = norm_url(m.group(0))
+            if not url:
+                raise ValueError(f"That link doesn't look valid: {m.group(0)}")
+            row.append({"t": label, "u": url})
+        if len(row) > MAX_ROW:
+            raise ValueError(f"At most {MAX_ROW} buttons fit in one row.")
+        if row:
+            rows.append(row)
+            total += len(row)
+    if total > MAX_TOTAL:
+        raise ValueError(f"At most {MAX_TOTAL} buttons per post.")
+    return rows
+
+
+def copy_rows(rows: list) -> list:
+    return [[dict(b) for b in row] for row in (rows or [])]
+
+
+def count(rows: list) -> int:
+    return sum(len(r) for r in rows or [])
+
+
+def missing_links(rows: list) -> int:
+    return sum(1 for r in rows or [] for b in r if not b.get("u") and not b.get("raw"))
+
+
+def valid(rows: list, r: int, c: int) -> bool:
+    return 0 <= r < len(rows) and 0 <= c < len(rows[r])
+
+
+def add_button(rows: list, btn: dict, new_row: bool = True) -> list:
+    rows = copy_rows(rows)
+    if new_row or not rows or len(rows[-1]) >= MAX_ROW:
+        rows.append([btn])
+    else:
+        rows[-1].append(btn)
+    return rows
+
+
+def set_field(rows: list, r: int, c: int, **fields) -> list:
+    rows = copy_rows(rows)
+    if valid(rows, r, c):
+        rows[r][c].update(fields)
+    return rows
+
+
+def delete_button(rows: list, r: int, c: int) -> list:
+    rows = copy_rows(rows)
+    if valid(rows, r, c):
+        rows[r].pop(c)
+        rows = [row for row in rows if row]
+    return rows
+
+
+def move_button(rows: list, r: int, c: int, direction: str) -> tuple:
+    """direction: l | r | u | d. Returns (rows, new_r, new_c)."""
+    rows = copy_rows(rows)
+    if not valid(rows, r, c):
+        return rows, r, c
+    b = rows[r][c]
+    if direction == "l":
+        if c > 0:
+            rows[r][c - 1], rows[r][c] = rows[r][c], rows[r][c - 1]
+            c -= 1
+    elif direction == "r":
+        if c < len(rows[r]) - 1:
+            rows[r][c + 1], rows[r][c] = rows[r][c], rows[r][c + 1]
+            c += 1
+    elif direction == "u":
+        if r > 0 and len(rows[r - 1]) < MAX_ROW:
+            rows[r].pop(c)
+            pos = min(c, len(rows[r - 1]))
+            rows[r - 1].insert(pos, b)
+            nr, nc = r - 1, pos
+            if not rows[r]:
+                rows.pop(r)
+            r, c = nr, nc
+    elif direction == "d":
+        if r < len(rows) - 1:
+            if len(rows[r + 1]) < MAX_ROW:
+                rows[r].pop(c)
+                pos = min(c, len(rows[r + 1]))
+                rows[r + 1].insert(pos, b)
+                nr, nc = r + 1, pos
+                if not rows[r]:
+                    rows.pop(r)
+                    nr -= 1
+                r, c = nr, nc
+        elif len(rows[r]) > 1:  # last row with company: split off into a new row below
+            rows[r].pop(c)
+            rows.append([b])
+            r, c = len(rows) - 1, 0
+    return rows, r, c
+
+
+def grid_label(b: dict) -> str:
+    t = (b.get("t") or "").strip() or "…"
+    if len(t) > 26:
+        t = t[:25] + "…"
+    if b.get("raw"):
+        return "🔒 " + t
+    if not b.get("u"):
+        return "⚠️ " + t
+    return t

app/common.py

@@ -0,0 +1,214 @@
+"""Shared context, permission guard, message helpers and post send/edit operations."""
+from __future__ import annotations
+
+import functools
+import logging
+from dataclasses import dataclass, field
+from types import SimpleNamespace
+from typing import Any, Callable, Optional
+
+from telethon import TelegramClient, errors, events
+
+from .config import Config
+from .db import Database
+from .tgutil import build_markup, de_entities, edit_raw, esc, explain_rpc, peer_of, with_media
+
+log = logging.getLogger(__name__)
+
+
+class UserError(Exception):
+    """An error whose message is safe and useful to show to the user."""
+
+
+@dataclass
+class Ctx:
+    cfg: Config
+    db: Database
+    client: TelegramClient
+    state: dict = field(default_factory=dict)  # user id -> {"mode": ..., ...}
+    pending: dict = field(default_factory=dict)  # tokens for confirm dialogs (replace, test edit)
+    seen_channels: dict = field(default_factory=dict)  # channel id -> Channel entity seen in updates
+    text_handlers: dict = field(default_factory=dict)  # mode -> async fn(event, state)
+    callbacks: dict = field(default_factory=dict)  # prefix -> async fn(event, parts)
+
+
+def is_cb(event) -> bool:
+    return isinstance(event, events.CallbackQuery.Event) or getattr(event, "_is_callback", False)
+
+
+def guard(ctx: Ctx, owner: bool = False) -> Callable:
+    """Only allowed users may use a handler; errors are turned into friendly messages."""
+
+    def deco(fn):
+        @functools.wraps(fn)
+        async def wrapper(event):
+            uid = event.sender_id
+            ok = ctx.cfg.is_owner(uid) if owner else ctx.cfg.is_allowed(uid)
+            if not ok:
+                try:
+                    if is_cb(event):
+                        await event.answer("Not allowed.", alert=True)
+                    elif getattr(event, "is_private", False):
+                        await event.respond("⛔ This bot is private.")
+                except Exception:
+                    pass
+                return
+            try:
+                await fn(event)
+            except events.StopPropagation:
+                raise
+            except errors.MessageNotModifiedError:
+                if is_cb(event):
+                    try:
+                        await event.answer()
+                    except Exception:
+                        pass
+            except UserError as e:
+                await notify_error(event, str(e))
+            except errors.RPCError as e:
+                await notify_error(event, "❌ " + explain_rpc(e))
+            except Exception as e:
+                log.exception("handler %s failed", fn.__name__)
+                await notify_error(event, f"⚠️ Something went wrong: {type(e).__name__}: {str(e)[:200]}")
+
+        return wrapper
+
+    return deco
+
+
+async def notify_error(event, text: str) -> None:
+    try:
+        if is_cb(event):
+            try:
+                await event.answer("That didn't work - see the message below.", alert=False)
+            except Exception:
+                pass
+        await event.respond(esc(text), link_preview=False)
+    except Exception:  # pragma: no cover
+        log.exception("could not report an error")
+
+
+async def say(event, text: str, buttons=None):
+    return await event.respond(text, buttons=buttons, link_preview=False)
+
+
+async def edit_callback_message(event, text: str, buttons=None):
+    """Edit the message a button was pressed on.
+
+    Telethon's CallbackQuery.edit() quietly starts a second `answer` task; the dispatcher has already
+    answered the query, so we call edit_message directly instead.
+    """
+    query = getattr(event, "query", None)
+    if query is not None and hasattr(event, "client"):
+        return await event.client.edit_message(
+            await event.get_input_chat(), query.msg_id, text, buttons=buttons, link_preview=False
+        )
+    return await event.edit(text, buttons=buttons, link_preview=False)  # test doubles
+
+
+async def show(event, text: str, buttons=None):
+    """Edit the message a button was pressed on; for normal messages send a new one."""
+    if is_cb(event):
+        try:
+            return await edit_callback_message(event, text, buttons)
+        except errors.MessageNotModifiedError:
+            return None
+    return await say(event, text, buttons)
+
+
+def require_owner(ctx: Ctx, event) -> None:
+    if not ctx.cfg.is_owner(event.sender_id):
+        raise UserError("⛔ Only the bot owner can do that.")
+
+
+# ------------------------------------------------------------------ sending and editing
+async def send_post(client, peer, post):
+    ents = de_entities(post.entities)
+    markup = build_markup(post.buttons)
+    if post.media_file_id:
+        return await with_media(
+            post.media_file_id,
+            lambda media: client.send_file(
+                peer, media, caption=post.text or "", formatting_entities=ents, buttons=markup
+            ),
+        )
+    return await client.send_message(
+        peer, post.text, formatting_entities=ents, buttons=markup, link_preview=bool(post.link_preview)
+    )
+
+
+async def push_edit(client, ch, p, *, replace_media: bool = False) -> None:
+    """Make the live channel message look like `p` (any object with the Post fields)."""
+    peer = peer_of(ch)
+    ents = de_entities(p.entities)
+    markup = build_markup(p.buttons)
+    if replace_media and p.media_file_id:
+        await with_media(
+            p.media_file_id,
+            lambda media: client.edit_message(
+                peer, p.message_id, text=p.text or "", formatting_entities=ents, buttons=markup, file=media
+            ),
+        )
+    else:
+        await edit_raw(
+            client,
+            peer,
+            p.message_id,
+            text=p.text or "",
+            entities=ents,
+            markup=markup,
+            preview=None if p.media_kind else bool(p.link_preview),
+        )
+
+
+async def apply_edit(ctx: Ctx, post, ch, *, replace_media: bool = False, **changes):
+    """Edit the channel message first (if the post is published), and only then save the change."""
+    if post.status == "sent" and post.message_id:
+        new = SimpleNamespace(**{**post.as_dict(), **changes})
+        try:
+            await push_edit(ctx.client, ch, new, replace_media=replace_media)
+        except errors.MessageNotModifiedError:
+            pass
+        except errors.RPCError as e:
+            raise UserError("❌ " + explain_rpc(e) + "\nNothing was changed.")
+    return await ctx.db.update_post(post.id, **changes)
+
+
+def on_cb(ctx: Ctx, prefix: str):
+    def deco(fn):
+        ctx.callbacks[prefix] = fn
+        return fn
+
+    return deco
+
+
+def on_text(ctx: Ctx, mode: str):
+    def deco(fn):
+        ctx.text_handlers[mode] = fn
+        return fn
+
+    return deco
+
+
+def set_state(ctx: Ctx, uid: int, mode: str, **data: Any) -> dict:
+    ctx.state[uid] = {"mode": mode, **data}
+    return ctx.state[uid]
+
+
+def clear_state(ctx: Ctx, uid: int) -> Optional[dict]:
+    return ctx.state.pop(uid, None)
+
+
+def cmd(name: str, args: bool = False):
+    """Event builder for a private-chat command such as /new or /replace <args>."""
+    pat = rf"(?is)^/{name}(?:@\w+)?" + (r"(?:\s+(.*))?$" if args else r"\s*$")
+    return events.NewMessage(incoming=True, pattern=pat, func=lambda e: e.is_private)
+
+
+async def discard_temp(ctx: Ctx, uid: int) -> None:
+    """Drop a half-made draft when the user abandons the flow that was creating it."""
+    st = ctx.state.get(uid)
+    if st and st.get("temp") and st.get("pid"):
+        p = await ctx.db.get_post(st["pid"])
+        if p is not None and p.status == "draft":
+            await ctx.db.delete_post(p.id)

app/config.py

@@ -0,0 +1,87 @@
+"""Settings, read from environment variables (or a .env file)."""
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+try:  # python-dotenv is optional; real env vars always win
+    from dotenv import load_dotenv
+
+    load_dotenv()
+except Exception:  # pragma: no cover
+    pass
+
+
+def _ints(name: str) -> frozenset:
+    raw = os.getenv(name, "") or ""
+    out = set()
+    for part in raw.replace(";", ",").replace(" ", ",").split(","):
+        part = part.strip()
+        if part.lstrip("-").isdigit():
+            out.add(int(part))
+    return frozenset(out)
+
+
+def _bool(name: str, default: bool) -> bool:
+    raw = os.getenv(name)
+    if raw is None or raw.strip() == "":
+        return default
+    return raw.strip().lower() in {"1", "true", "yes", "on"}
+
+
+def _float(name: str, default: float) -> float:
+    try:
+        return float(os.getenv(name, "") or default)
+    except ValueError:
+        return default
+
+
+@dataclass(frozen=True)
+class Config:
+    api_id: int
+    api_hash: str
+    bot_token: str
+    owners: frozenset
+    admins: frozenset
+    database_url: str
+    db_pool: str
+    session_path: str
+    session_string: str
+    edit_delay: float
+    replace_typed_links: bool
+    port: int
+    log_level: str
+
+    def is_owner(self, uid) -> bool:
+        return uid in self.owners
+
+    def is_allowed(self, uid) -> bool:
+        return uid in self.owners or uid in self.admins
+
+
+def load_config() -> Config:
+    missing = [k for k in ("API_ID", "API_HASH", "BOT_TOKEN") if not os.getenv(k)]
+    owners = _ints("OWNER_IDS")
+    if not owners:
+        missing.append("OWNER_IDS")
+    if missing:
+        raise SystemExit("Missing required settings: " + ", ".join(missing) + " (see .env.example)")
+    try:
+        api_id = int(os.environ["API_ID"])
+    except ValueError:
+        raise SystemExit("API_ID must be a number")
+    return Config(
+        api_id=api_id,
+        api_hash=os.environ["API_HASH"].strip(),
+        bot_token=os.environ["BOT_TOKEN"].strip(),
+        owners=owners,
+        admins=_ints("ADMIN_IDS"),
+        database_url=(os.getenv("DATABASE_URL") or "sqlite+aiosqlite:///data/bot.db").strip(),
+        db_pool=(os.getenv("DB_POOL") or "null").strip().lower(),
+        session_path=(os.getenv("SESSION_PATH") or "data/bot").strip(),
+        session_string=(os.getenv("SESSION_STRING") or "").strip(),
+        edit_delay=max(0.3, _float("EDIT_DELAY", 1.2)),
+        replace_typed_links=_bool("REPLACE_TYPED_LINKS", True),
+        port=int(os.getenv("PORT") or 0),
+        log_level=(os.getenv("LOG_LEVEL") or "INFO").upper(),
+    )

app/db.py

@@ -0,0 +1,375 @@
+"""Database layer (SQLAlchemy 2.0 async). PostgreSQL in production, SQLite for local tests."""
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+from datetime import datetime, timezone
+from typing import Any, Optional
+from urllib.parse import parse_qsl, urlencode, urlsplit, urlunsplit
+
+from sqlalchemy import (
+    JSON,
+    BigInteger,
+    Boolean,
+    DateTime,
+    ForeignKey,
+    Integer,
+    String,
+    Text,
+    UniqueConstraint,
+    desc,
+    func,
+    select,
+)
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.ext.asyncio import async_sessionmaker, create_async_engine
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from sqlalchemy.pool import NullPool
+
+log = logging.getLogger(__name__)
+
+JSONType = JSON().with_variant(JSONB(), "postgresql")
+
+
+def utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+class Channel(Base):
+    __tablename__ = "channels"
+
+    id: Mapped[int] = mapped_column(BigInteger, primary_key=True, autoincrement=False)
+    access_hash: Mapped[int] = mapped_column(BigInteger, default=0)
+    title: Mapped[str] = mapped_column(String(256), default="")
+    username: Mapped[Optional[str]] = mapped_column(String(64), nullable=True)
+    active: Mapped[bool] = mapped_column(Boolean, default=True)
+    added_by: Mapped[int] = mapped_column(BigInteger, default=0)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utcnow)
+
+
+class Post(Base):
+    __tablename__ = "posts"
+    __table_args__ = (UniqueConstraint("channel_id", "message_id", name="uq_post_channel_msg"),)
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    channel_id: Mapped[int] = mapped_column(BigInteger, ForeignKey("channels.id"), index=True)
+    message_id: Mapped[Optional[int]] = mapped_column(BigInteger, nullable=True)
+    status: Mapped[str] = mapped_column(String(16), default="draft", index=True)  # draft | sent
+    source: Mapped[str] = mapped_column(String(16), default="bot")  # bot | adopted
+    text: Mapped[str] = mapped_column(Text, default="")
+    entities: Mapped[list] = mapped_column(JSONType, default=list)
+    media_kind: Mapped[Optional[str]] = mapped_column(String(16), nullable=True)
+    media_file_id: Mapped[Optional[str]] = mapped_column(Text, nullable=True)
+    buttons: Mapped[list] = mapped_column(JSONType, default=list)
+    link_preview: Mapped[bool] = mapped_column(Boolean, default=False)
+    created_by: Mapped[int] = mapped_column(BigInteger, default=0)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utcnow)
+    updated_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utcnow)
+    sent_at: Mapped[Optional[datetime]] = mapped_column(DateTime(timezone=True), nullable=True)
+
+    def as_dict(self) -> dict:
+        return {c.name: getattr(self, c.name) for c in self.__table__.columns}
+
+
+class Batch(Base):
+    """One /replace run (so it can be undone)."""
+
+    __tablename__ = "batches"
+
+    id: Mapped[str] = mapped_column(String(32), primary_key=True)
+    old_username: Mapped[str] = mapped_column(String(64))
+    new_username: Mapped[str] = mapped_column(String(64))
+    created_by: Mapped[int] = mapped_column(BigInteger, default=0)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utcnow)
+    undone: Mapped[bool] = mapped_column(Boolean, default=False)
+
+
+class Change(Base):
+    __tablename__ = "changes"
+
+    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
+    batch_id: Mapped[str] = mapped_column(String(32), ForeignKey("batches.id"), index=True)
+    channel_id: Mapped[int] = mapped_column(BigInteger)
+    message_id: Mapped[int] = mapped_column(BigInteger)
+    old_state: Mapped[dict] = mapped_column(JSONType, default=dict)
+    new_state: Mapped[dict] = mapped_column(JSONType, default=dict)
+    reverted: Mapped[bool] = mapped_column(Boolean, default=False)
+    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), default=utcnow)
+
+
+def normalize_db_url(url: str) -> tuple:
+    """Turn a plain DATABASE_URL into a SQLAlchemy async URL + connect args."""
+    connect_args: dict = {}
+    if url.startswith("postgres://"):
+        url = "postgresql://" + url[len("postgres://"):]
+    if url.startswith("postgresql://"):
+        url = "postgresql+asyncpg://" + url[len("postgresql://"):]
+    if url.startswith("postgresql+asyncpg://"):
+        parts = urlsplit(url)
+        keep = []
+        for k, v in parse_qsl(parts.query, keep_blank_values=True):
+            if k == "sslmode":
+                if v in ("require", "verify-ca", "verify-full"):
+                    connect_args["ssl"] = True
+            elif k in ("channel_binding", "options"):
+                continue
+            else:
+                keep.append((k, v))
+        host = parts.hostname or ""
+        if "-pooler" in host or "pgbouncer" in host:
+            # PgBouncer in transaction mode does not support prepared statements
+            connect_args["statement_cache_size"] = 0
+            keep.append(("prepared_statement_cache_size", "0"))
+        url = urlunsplit(parts._replace(query=urlencode(keep)))
+    elif url.startswith("sqlite:///"):
+        url = "sqlite+aiosqlite:///" + url[len("sqlite:///"):]
+    return url, connect_args
+
+
+class Database:
+    def __init__(self, url: str, pool: str = "null"):
+        self.url, connect_args = normalize_db_url(url)
+        kwargs: dict = {"connect_args": connect_args}
+        if self.url.startswith("sqlite"):
+            path = self.url.split(":///", 1)[-1]
+            if path and path != ":memory:":
+                os.makedirs(os.path.dirname(path) or ".", exist_ok=True)
+        elif pool == "queue":
+            kwargs.update(pool_size=5, max_overflow=5, pool_pre_ping=True, pool_recycle=1800)
+        else:
+            # short-lived connections: lets serverless Postgres (e.g. Neon) go to sleep when idle
+            kwargs["poolclass"] = NullPool
+        self.engine = create_async_engine(self.url, **kwargs)
+        self.Session = async_sessionmaker(self.engine, expire_on_commit=False)
+
+    async def init(self, retries: int = 6) -> None:
+        last: Optional[BaseException] = None
+        for i in range(retries):
+            try:
+                async with self.engine.begin() as conn:
+                    await conn.run_sync(Base.metadata.create_all)
+                return
+            except Exception as e:  # cold start of serverless DBs can fail once
+                last = e
+                log.warning("database not ready (%s) - retry %s/%s", e, i + 1, retries)
+                await asyncio.sleep(min(2 ** i, 15))
+        assert last is not None
+        raise last
+
+    async def close(self) -> None:
+        await self.engine.dispose()
+
+    # ------------------------------------------------------------------ channels
+    async def list_channels(self, active_only: bool = True) -> list:
+        async with self.Session() as s:
+            q = select(Channel).order_by(Channel.title)
+            if active_only:
+                q = q.where(Channel.active.is_(True))
+            return list((await s.execute(q)).scalars())
+
+    async def get_channel(self, cid: int) -> Optional[Channel]:
+        async with self.Session() as s:
+            return await s.get(Channel, cid)
+
+    async def save_channel(self, cid: int, access_hash: int, title: str, username: Optional[str], added_by: int) -> Channel:
+        async with self.Session() as s:
+            ch = await s.get(Channel, cid)
+            if ch is None:
+                ch = Channel(id=cid, access_hash=access_hash, title=title, username=username, added_by=added_by, active=True)
+                s.add(ch)
+            else:
+                ch.access_hash = access_hash or ch.access_hash
+                ch.title = title or ch.title
+                ch.username = username
+                ch.active = True
+            await s.commit()
+            return ch
+
+    async def touch_channel_hash(self, cid: int, access_hash: int) -> None:
+        async with self.Session() as s:
+            ch = await s.get(Channel, cid)
+            if ch is not None and access_hash and ch.access_hash != access_hash:
+                ch.access_hash = access_hash
+                await s.commit()
+
+    async def set_channel_active(self, cid: int, active: bool) -> None:
+        async with self.Session() as s:
+            ch = await s.get(Channel, cid)
+            if ch is not None:
+                ch.active = active
+                await s.commit()
+
+    # --------------------------------------------------------------------- posts
+    async def create_post(self, **fields: Any) -> Post:
+        async with self.Session() as s:
+            p = Post(**fields)
+            s.add(p)
+            await s.commit()
+            return p
+
+    async def get_post(self, pid: int) -> Optional[Post]:
+        async with self.Session() as s:
+            return await s.get(Post, pid)
+
+    async def update_post(self, pid: int, **fields: Any) -> Optional[Post]:
+        async with self.Session() as s:
+            p = await s.get(Post, pid)
+            if p is None:
+                return None
+            for k, v in fields.items():
+                setattr(p, k, v)
+            p.updated_at = utcnow()
+            await s.commit()
+            return p
+
+    async def delete_post(self, pid: int) -> None:
+        async with self.Session() as s:
+            p = await s.get(Post, pid)
+            if p is not None:
+                await s.delete(p)
+                await s.commit()
+
+    async def list_posts(self, channel_id: Optional[int], status: Optional[str], offset: int, limit: int) -> tuple:
+        cond = []
+        if channel_id is not None:
+            cond.append(Post.channel_id == channel_id)
+        if status:
+            cond.append(Post.status == status)
+        async with self.Session() as s:
+            total = (await s.execute(select(func.count()).select_from(Post).where(*cond))).scalar_one()
+            q = (
+                select(Post)
+                .where(*cond)
+                .order_by(Post.status.asc(), desc(Post.message_id), desc(Post.id))
+                .offset(offset)
+                .limit(limit)
+            )
+            rows = list((await s.execute(q)).scalars())
+            return rows, total
+
+    async def latest_sent(self, channel_id: int, limit: int = 30) -> list:
+        async with self.Session() as s:
+            q = (
+                select(Post)
+                .where(Post.channel_id == channel_id, Post.status == "sent", Post.message_id.is_not(None))
+                .order_by(desc(Post.message_id))
+                .limit(limit)
+            )
+            return list((await s.execute(q)).scalars())
+
+    async def mine_message_ids(self, channel_id: int) -> set:
+        async with self.Session() as s:
+            q = select(Post.message_id).where(
+                Post.channel_id == channel_id, Post.source == "bot", Post.message_id.is_not(None)
+            )
+            return {r for r in (await s.execute(q)).scalars()}
+
+    async def find_by_message(self, channel_id: int, message_id: int) -> Optional[Post]:
+        async with self.Session() as s:
+            q = select(Post).where(Post.channel_id == channel_id, Post.message_id == message_id)
+            return (await s.execute(q)).scalar_one_or_none()
+
+    # ------------------------------------------------------------- replace history
+    async def create_batch(self, batch_id: str, old: str, new: str, user_id: int) -> None:
+        async with self.Session() as s:
+            s.add(Batch(id=batch_id, old_username=old, new_username=new, created_by=user_id))
+            await s.commit()
+
+    async def _adopt(self, s, channel_id: int, message_id: int, fields: dict, user_id: int) -> None:
+        q = select(Post).where(Post.channel_id == channel_id, Post.message_id == message_id)
+        p = (await s.execute(q)).scalar_one_or_none()
+        if p is not None:
+            for k, v in fields.items():
+                setattr(p, k, v)
+            p.updated_at = utcnow()
+        else:
+            s.add(
+                Post(
+                    channel_id=channel_id,
+                    message_id=message_id,
+                    status="sent",
+                    source="adopted",
+                    created_by=user_id,
+                    sent_at=utcnow(),
+                    **fields,
+                )
+            )
+
+    async def record_changes(self, batch_id: str, channel_id: int, records: list, user_id: int) -> None:
+        """records: [{message_id, old_state, new_state, adopt: {post fields}}]"""
+        if not records:
+            return
+        async with self.Session() as s:
+            for r in records:
+                s.add(
+                    Change(
+                        batch_id=batch_id,
+                        channel_id=channel_id,
+                        message_id=r["message_id"],
+                        old_state=r["old_state"],
+                        new_state=r["new_state"],
+                    )
+                )
+                await self._adopt(s, channel_id, r["message_id"], r["adopt"], user_id)
+            await s.commit()
+
+    async def last_batch(self) -> Optional[Batch]:
+        async with self.Session() as s:
+            q = select(Batch).where(Batch.undone.is_(False)).order_by(desc(Batch.created_at)).limit(1)
+            return (await s.execute(q)).scalar_one_or_none()
+
+    async def get_batch(self, batch_id: str) -> Optional[Batch]:
+        async with self.Session() as s:
+            return await s.get(Batch, batch_id)
+
+    async def batch_changes(self, batch_id: str) -> list:
+        async with self.Session() as s:
+            q = select(Change).where(Change.batch_id == batch_id, Change.reverted.is_(False)).order_by(Change.id)
+            return list((await s.execute(q)).scalars())
+
+    async def count_batch_changes(self, batch_id: str) -> int:
+        async with self.Session() as s:
+            q = select(func.count()).select_from(Change).where(Change.batch_id == batch_id, Change.reverted.is_(False))
+            return (await s.execute(q)).scalar_one()
+
+    async def finish_undo(self, batch_id: str, change_ids: list, restored: list, all_done: bool) -> None:
+        """restored: [(channel_id, message_id, state)] -> refresh the saved post copies."""
+        async with self.Session() as s:
+            for cid in change_ids:
+                c = await s.get(Change, cid)
+                if c is not None:
+                    c.reverted = True
+            for channel_id, message_id, state in restored:
+                q = select(Post).where(Post.channel_id == channel_id, Post.message_id == message_id)
+                p = (await s.execute(q)).scalar_one_or_none()
+                if p is not None:
+                    p.text = state.get("text", "")
+                    p.entities = state.get("entities", [])
+                    p.buttons = state.get("buttons", [])
+                    p.updated_at = utcnow()
+            if all_done:
+                b = await s.get(Batch, batch_id)
+                if b is not None:
+                    b.undone = True
+            await s.commit()
+
+    # -------------------------------------------------------------------- export
+    async def export_all(self) -> dict:
+        def clean(d: dict) -> dict:
+            return {k: (v.isoformat() if isinstance(v, datetime) else v) for k, v in d.items()}
+
+        async with self.Session() as s:
+            chans = list((await s.execute(select(Channel))).scalars())
+            posts = list((await s.execute(select(Post).order_by(Post.id))).scalars())
+            return {
+                "exported_at": utcnow().isoformat(),
+                "channels": [
+                    clean({c.name: getattr(ch, c.name) for c in ch.__table__.columns}) for ch in chans
+                ],
+                "posts": [clean(p.as_dict()) for p in posts],
+            }

app/handlers/basic.py

@@ -0,0 +1,96 @@
+"""/start /help /cancel /export, plus the routers for free text and inline-button presses."""
+from __future__ import annotations
+
+import io
+import json
+import logging
+
+from telethon import events
+
+from ..common import Ctx, cmd, clear_state, discard_temp, guard, say, show
+
+log = logging.getLogger(__name__)
+
+HELP = (
+    "<b>Channel Post Bot</b>\n\n"
+    "<b>Posts</b>\n"
+    "/new - create a post (text or media, with buttons)\n"
+    "/posts - your posts and drafts: edit text, caption, media and buttons, or delete them\n"
+    "/cancel - stop what you're doing\n\n"
+    "<b>Channels</b>\n"
+    "/addchannel - register a channel (the bot must be an admin there)\n"
+    "/channels - list or remove channels\n\n"
+    "<b>Owner tools</b>\n"
+    "/replace @old @new - swap the username inside t.me links (button links and hyperlinks) in all channels\n"
+    "/undo - undo the last /replace\n"
+    "/testedit &lt;post link&gt; - check that the bot can edit the buttons of one specific post\n"
+    "/export - download a JSON backup of your posts"
+)
+
+
+def register(ctx: Ctx) -> None:
+    client, db = ctx.client, ctx.db
+
+    @client.on(cmd("start"))
+    @client.on(cmd("help"))
+    @guard(ctx)
+    async def h_help(event):
+        await say(event, HELP)
+
+    @client.on(cmd("cancel"))
+    @guard(ctx)
+    async def h_cancel(event):
+        await discard_temp(ctx, event.sender_id)
+        clear_state(ctx, event.sender_id)
+        await say(event, "Cancelled.")
+
+    @client.on(cmd("export"))
+    @guard(ctx, owner=True)
+    async def h_export(event):
+        data = await db.export_all()
+        buf = io.BytesIO(json.dumps(data, ensure_ascii=False, indent=1).encode("utf-8"))
+        buf.name = "channel-posts-export.json"
+        await event.respond(f"📦 Backup: {len(data['channels'])} channel(s), {len(data['posts'])} post(s).", file=buf)
+
+    @client.on(
+        events.NewMessage(incoming=True, func=lambda e: e.is_private and not (e.raw_text or "").startswith("/"))
+    )
+    @guard(ctx)
+    async def h_free_text(event):
+        st = ctx.state.get(event.sender_id)
+        if not st:
+            await say(event, "Use /new to create a post or /posts to manage your posts. /help lists everything.")
+            return
+        fn = ctx.text_handlers.get(st["mode"])
+        if fn is None:
+            clear_state(ctx, event.sender_id)
+            await say(event, "That step is no longer active. Start again with /new.")
+            return
+        await fn(event, st)
+
+    @client.on(events.CallbackQuery())
+    @guard(ctx)
+    async def h_callback(event):
+        try:
+            await event.answer()  # stop the loading spinner right away
+        except Exception:
+            pass
+        data = event.data.decode("utf-8", "replace")
+        prefix, *parts = data.split(":")
+        fn = ctx.callbacks.get(prefix)
+        if fn is None:
+            await event.respond("This button is no longer active. Use /new or /posts.")
+            return
+        await fn(event, parts)
+
+    async def cb_noop(event, parts):
+        await event.answer()
+
+    async def cb_cancel(event, parts):
+        uid = event.sender_id
+        await discard_temp(ctx, uid)
+        clear_state(ctx, uid)
+        await show(event, "Cancelled.")
+
+    ctx.callbacks["noop"] = cb_noop
+    ctx.callbacks["cx"] = cb_cancel

app/handlers/channels.py

@@ -0,0 +1,135 @@
+"""Channel registration: /addchannel, /channels."""
+from __future__ import annotations
+
+import logging
+import re
+
+from telethon import Button, events, types
+
+from ..common import Ctx, UserError, clear_state, cmd, guard, on_cb, on_text, require_owner, say, set_state, show
+from ..tgutil import esc, get_rights, short
+from ..ui import CANCEL
+
+log = logging.getLogger(__name__)
+
+ADD_HELP = (
+    "📢 <b>Add a channel</b>\n"
+    "1. Make the bot an admin of the channel with the rights <i>Post messages</i>, <i>Edit messages of others</i> "
+    "and <i>Delete messages</i>.\n"
+    "2. Then <b>forward any post from that channel to me</b>, or send its @username (public channels).\n\n"
+    "Tip for private channels: if forwarding doesn't work, post something in the channel while the bot is "
+    "running, then forward that post."
+)
+NEEDS_ACCESS = (
+    "I can see the channel, but Telegram hasn't given me its access details yet. Post something in the "
+    "channel while the bot is running (or send the @username if it's public), then forward a post again."
+)
+
+_REF_RX = re.compile(r"(?i)^(?:https?://)?(?:t\.me|telegram\.me)/(?:c/(\d+)|([A-Za-z0-9_]{3,32}))(?:/\d+)?/?$")
+
+
+def parse_channel_ref(text: str):
+    """@name / t.me link / numeric id -> username (str) or channel id (int); None if unrecognised."""
+    t = (text or "").strip()
+    m = _REF_RX.match(t)
+    if m:
+        return int(m.group(1)) if m.group(1) else m.group(2)
+    t = t.lstrip("@")
+    if re.fullmatch(r"-?\d+", t):
+        s = str(abs(int(t)))
+        return int(s[3:]) if s.startswith("100") and len(s) > 10 else int(s)
+    if re.fullmatch(r"[A-Za-z0-9_]{3,32}", t):
+        return t
+    return None
+
+
+def rights_line(r) -> str:
+    if r is None:
+        return "rights unknown"
+    if not r.admin:
+        return "⚠️ not an admin there"
+    ok = lambda v: "✅" if v else "❌"  # noqa: E731
+    return f"post {ok(r.post)} · edit others' posts {ok(r.edit)} · delete {ok(r.delete)}"
+
+
+def register(ctx: Ctx) -> None:
+    client, db = ctx.client, ctx.db
+
+    # remember channels whose full details (access hash) we have seen in updates
+    @client.on(events.NewMessage(func=lambda e: bool(e.is_channel) and not e.is_group))
+    async def watch_channels(event):
+        try:
+            chat = await event.get_chat()
+            if isinstance(chat, types.Channel) and chat.access_hash and not getattr(chat, "min", False):
+                prev = ctx.seen_channels.get(chat.id)
+                ctx.seen_channels[chat.id] = chat
+                if prev is None or prev.access_hash != chat.access_hash:
+                    await db.touch_channel_hash(chat.id, chat.access_hash)
+        except Exception:  # pragma: no cover
+            log.debug("channel watcher failed", exc_info=True)
+
+    @client.on(cmd("addchannel"))
+    @guard(ctx, owner=True)
+    async def h_addchannel(event):
+        set_state(ctx, event.sender_id, "add_channel")
+        await say(event, ADD_HELP, CANCEL)
+
+    @on_text(ctx, "add_channel")
+    async def h_add_channel(event, st):
+        m = event.message
+        ent = None
+        fwd = m.forward
+        if fwd is not None and isinstance(getattr(fwd, "chat", None), types.Channel):
+            ent = fwd.chat
+            if getattr(ent, "min", False) or not getattr(ent, "access_hash", None):
+                ent = ctx.seen_channels.get(ent.id, ent)
+        else:
+            ref = parse_channel_ref(m.raw_text or "")
+            if ref is None:
+                raise UserError("Forward a post from the channel to me, or send its @username.")
+            if isinstance(ref, int):
+                ent = ctx.seen_channels.get(ref)
+            if ent is None:
+                try:
+                    ent = await client.get_entity(ref if isinstance(ref, str) else types.PeerChannel(ref))
+                except Exception:
+                    ent = None
+        if not isinstance(ent, types.Channel):
+            raise UserError("I couldn't find that channel.\n\n" + re.sub(r"<[^>]+>", "", ADD_HELP))
+        if not ent.broadcast:
+            raise UserError("That is a group, not a channel. Only channels are supported.")
+        if not ent.access_hash or getattr(ent, "min", False):
+            raise UserError(NEEDS_ACCESS)
+        rights = await get_rights(client, ent)
+        if rights is not None and not rights.admin:
+            raise UserError("The bot is not an admin of that channel yet. Add it as an admin, then try again.")
+        await db.save_channel(ent.id, ent.access_hash, ent.title or "", ent.username, event.sender_id)
+        clear_state(ctx, event.sender_id)
+        warn = ""
+        if rights is not None and not (rights.post and rights.edit and rights.delete):
+            warn = "\n\n⚠️ Missing rights: give the bot <i>Post</i>, <i>Edit messages of others</i> and <i>Delete</i> so everything works."
+        await say(
+            event,
+            f"✅ Added <b>{esc(ent.title or '')}</b>\n{rights_line(rights)}{warn}\n\nCreate a post with /new.",
+        )
+
+    @client.on(cmd("channels"))
+    @guard(ctx)
+    async def h_channels(event):
+        chans = await db.list_channels()
+        if not chans:
+            raise UserError("No channels yet. Use /addchannel.")
+        lines, kb = [], []
+        for ch in chans:
+            r = await get_rights(client, ch)
+            name = esc(ch.title) + (f" (@{esc(ch.username)})" if ch.username else "")
+            lines.append(f"• <b>{name}</b>\n   {rights_line(r)}")
+            if ctx.cfg.is_owner(event.sender_id):
+                kb.append([Button.inline(f"➖ Remove {short(ch.title, 22)}", f"chd:{ch.id}")])
+        await say(event, "📢 <b>Your channels</b>\n\n" + "\n".join(lines), kb or None)
+
+    @on_cb(ctx, "chd")
+    async def cb_remove_channel(event, parts):
+        require_owner(ctx, event)
+        await db.set_channel_active(int(parts[0]), False)
+        await show(event, "Channel removed from the bot. Its saved posts are kept; add it again with /addchannel.")

app/handlers/create.py

@@ -0,0 +1,179 @@
+"""/new: create a post, with the episode-range auto-suggestion."""
+from __future__ import annotations
+
+import logging
+
+from telethon import Button
+
+from ..buttons import norm_url, parse_buttons_text, set_field
+from ..common import Ctx, UserError, clear_state, cmd, discard_temp, guard, on_cb, on_text, say, set_state, show
+from ..suggest import make_suggestion
+from ..tgutil import esc, short
+from ..ui import CANCEL, KIND_NAME
+from .panel import extract_content, show_panel
+
+log = logging.getLogger(__name__)
+
+BUTTON_HELP = (
+    "➕ <b>Now the buttons</b>\n"
+    "Send one row per line as <code>Button text - link</code>.\n"
+    "Several buttons in one row: separate them with <code> | </code>.\n\n"
+    "Example:\n<code>Download Episodes 01 to 20 - https://t.me/yourbot?start=abc</code>\n\n"
+    "Or send /skip to post without buttons."
+)
+
+
+def register(ctx: Ctx) -> None:
+    client, db = ctx.client, ctx.db
+
+    async def ask_content(event, cid: int) -> None:
+        set_state(ctx, event.sender_id, "new_content", cid=cid)
+        await show(
+            event,
+            "✍️ <b>Send the post now.</b>\nText, or a photo / video / GIF / file with a caption. "
+            "Formatting (bold, links, spoilers...) is kept.",
+            CANCEL,
+        )
+
+    async def start_for_channel(event, cid: int) -> None:
+        ch = await db.get_channel(cid)
+        if ch is None:
+            raise UserError("That channel is not registered. Use /addchannel.")
+        sug = await make_suggestion(db, cid)
+        if sug is None:
+            await ask_content(event, cid)
+            return
+        lines = [
+            f"💡 <b>Suggestion for {esc(ch.title)}</b>",
+            f"Your last button post: <code>{esc(sug.prev_label)}</code>",
+            "The next one would be:",
+        ]
+        if (sug.text or "").strip():
+            lines.append(f"• Message: <i>{esc(short(sug.text, 120))}</i>")
+        lines.append(f"• Button: <code>{esc(sug.new_label)}</code>")
+        if sug.media_kind:
+            lines.append(f"• Media: same {KIND_NAME.get(sug.media_kind, 'file')} as that post (you can change it before publishing)")
+        lines.append("\nUse it and I'll only ask for the button link.")
+        kb = [
+            [Button.inline("✅ Use suggestion", f"ns:{cid}"), Button.inline("✏️ Customize", f"nn:{cid}")],
+            CANCEL[0],
+        ]
+        await show(event, "\n".join(lines), kb)
+
+    async def ask_link(event, post, pos) -> None:
+        r, c = pos
+        label = post.buttons[r][c]["t"]
+        await say(
+            event,
+            f"🔗 Send the link for the button <code>{esc(label)}</code>\n"
+            "(for example <code>https://t.me/yourbot?start=abc</code>)",
+            CANCEL,
+        )
+
+    @client.on(cmd("new"))
+    @guard(ctx)
+    async def h_new(event):
+        uid = event.sender_id
+        await discard_temp(ctx, uid)
+        clear_state(ctx, uid)
+        chans = await db.list_channels()
+        if not chans:
+            raise UserError("No channels yet. Register one with /addchannel first.")
+        if len(chans) == 1:
+            await start_for_channel(event, chans[0].id)
+            return
+        kb = [[Button.inline(f"📢 {short(c.title, 40)}", f"nc:{c.id}")] for c in chans] + CANCEL
+        await say(event, "Which channel is this post for?", kb)
+
+    @on_cb(ctx, "nc")
+    async def cb_channel(event, parts):
+        await discard_temp(ctx, event.sender_id)
+        await start_for_channel(event, int(parts[0]))
+
+    @on_cb(ctx, "nn")
+    async def cb_customize(event, parts):
+        await ask_content(event, int(parts[0]))
+
+    @on_cb(ctx, "ns")
+    async def cb_use_suggestion(event, parts):
+        uid, cid = event.sender_id, int(parts[0])
+        sug = await make_suggestion(db, cid)
+        if sug is None:
+            raise UserError("There is nothing to suggest any more - send the post yourself with /new.")
+        await discard_temp(ctx, uid)
+        post = await db.create_post(
+            channel_id=cid,
+            created_by=uid,
+            status="draft",
+            source="bot",
+            text=sug.text,
+            entities=sug.entities,
+            buttons=sug.buttons,
+            media_kind=sug.media_kind,
+            media_file_id=sug.media_file_id,
+            link_preview=False,
+        )
+        set_state(ctx, uid, "new_link", pid=post.id, pending=list(sug.pending), temp=True)
+        await show(event, f"✅ Using the suggestion: <code>{esc(sug.new_label)}</code>")
+        await ask_link(event, post, sug.pending[0])
+
+    @on_text(ctx, "new_link")
+    async def h_new_link(event, st):
+        url = norm_url(event.raw_text or "")
+        if not url:
+            raise UserError("That doesn't look like a link. Send something like https://t.me/yourbot?start=abc")
+        post = await db.get_post(st["pid"])
+        if post is None:
+            clear_state(ctx, event.sender_id)
+            raise UserError("That draft is gone. Start again with /new.")
+        r, c = st["pending"][0]
+        post = await db.update_post(post.id, buttons=set_field(post.buttons, r, c, u=url))
+        st["pending"] = st["pending"][1:]
+        if st["pending"]:
+            await ask_link(event, post, st["pending"][0])
+            return
+        clear_state(ctx, event.sender_id)
+        await show_panel(ctx, event, post.id, note="✅ Ready. Preview it, or tap <b>Publish</b>.", new=True)
+
+    @on_text(ctx, "new_content")
+    async def h_new_content(event, st):
+        m = event.message
+        if m.grouped_id and st.get("group") == m.grouped_id:
+            return  # the other items of an album: only the first one is used
+        if m.grouped_id:
+            st["group"] = m.grouped_id
+        content = extract_content(m)
+        post = await db.create_post(
+            channel_id=st["cid"],
+            created_by=event.sender_id,
+            status="draft",
+            source="bot",
+            buttons=[],
+            link_preview=False,
+            **content,
+        )
+        set_state(ctx, event.sender_id, "new_buttons", pid=post.id, temp=True)
+        await say(event, BUTTON_HELP, CANCEL)
+
+    @on_text(ctx, "new_buttons")
+    async def h_new_buttons(event, st):
+        if event.message.grouped_id:
+            return
+        try:
+            rows = parse_buttons_text(event.raw_text or "")
+        except ValueError as e:
+            raise UserError(f"❌ {e}\n\nTry again, or send /skip.")
+        if not rows:
+            raise UserError("Send at least one button as “Text - link”, or /skip.")
+        await db.update_post(st["pid"], buttons=rows)
+        clear_state(ctx, event.sender_id)
+        await show_panel(ctx, event, st["pid"], note="✅ Ready. Preview it, or tap <b>Publish</b>.", new=True)
+
+    @client.on(cmd("skip"))
+    @guard(ctx)
+    async def h_skip(event):
+        st = ctx.state.get(event.sender_id)
+        if not st or st["mode"] != "new_buttons":
+            raise UserError("There is nothing to skip right now.")
+        clear_state(ctx, event.sender_id)
+        await show_panel(ctx, event, st["pid"], note="✅ Ready (no buttons). Preview it, or tap <b>Publish</b>.", new=True)

app/handlers/panel.py

@@ -0,0 +1,68 @@
+"""Helpers shared by the create and post-management handlers (not a handler module itself)."""
+from __future__ import annotations
+
+from telethon import types
+
+from ..buttons import valid
+from ..common import Ctx, UserError, is_cb, say, show
+from ..tgutil import classify_media, pack_file_id, ser_entities, utf16_len
+from ..ui import button_keyboard, button_text, panel_keyboard, panel_text
+
+CAPTION_MAX = 1024
+TEXT_MAX = 4096
+
+
+async def load_post(ctx: Ctx, pid):
+    post = await ctx.db.get_post(int(pid))
+    if post is None:
+        raise UserError("That post no longer exists.")
+    ch = await ctx.db.get_channel(post.channel_id)
+    if ch is None:
+        raise UserError("Its channel was removed from the bot. Add it again with /addchannel.")
+    return post, ch
+
+
+async def show_panel(ctx: Ctx, event, pid, note=None, new: bool = False) -> None:
+    post, ch = await load_post(ctx, pid)
+    text, kb = panel_text(post, ch, note), panel_keyboard(post)
+    if new or not is_cb(event):
+        await say(event, text, kb)
+    else:
+        await show(event, text, kb)
+
+
+async def show_button_screen(ctx: Ctx, event, pid, r: int, c: int, new: bool = False) -> None:
+    post, _ = await load_post(ctx, pid)
+    if not valid(post.buttons or [], r, c):
+        await show_panel(ctx, event, pid, new=new)
+        return
+    text, kb = button_text(post, r, c), button_keyboard(post, r, c)
+    if new or not is_cb(event):
+        await say(event, text, kb)
+    else:
+        await show(event, text, kb)
+
+
+def check_lengths(text: str, has_media: bool) -> None:
+    n = utf16_len(text or "")
+    if has_media and n > CAPTION_MAX:
+        raise UserError(f"A caption can have at most {CAPTION_MAX} characters (yours has {n}).")
+    if not has_media and n > TEXT_MAX:
+        raise UserError(f"A text post can have at most {TEXT_MAX} characters (yours has {n}).")
+
+
+def extract_content(m) -> dict:
+    """A message from the user -> post fields (text, entities, media)."""
+    kind = classify_media(m)
+    if m.media and kind is None and not isinstance(m.media, types.MessageMediaWebPage):
+        raise UserError("That kind of message can't be used in a post. Send text, a photo, video, GIF, audio or a file.")
+    text = m.raw_text or ""
+    if not kind and not text.strip():
+        raise UserError("Send some text, or a photo / video / GIF / file.")
+    check_lengths(text, bool(kind))
+    return {
+        "text": text,
+        "entities": ser_entities(m.entities),
+        "media_kind": kind,
+        "media_file_id": pack_file_id(m) if kind else None,
+    }

app/handlers/posts.py

@@ -0,0 +1,409 @@
+"""/posts: list, open and edit posts (text, caption, media, buttons), publish drafts, delete."""
+from __future__ import annotations
+
+import logging
+
+from telethon import Button, errors
+
+from ..buttons import (
+    MAX_ROW,
+    add_button,
+    count,
+    delete_button,
+    missing_links,
+    move_button,
+    norm_url,
+    parse_buttons_text,
+    set_field,
+    valid,
+)
+from ..common import (
+    Ctx,
+    UserError,
+    apply_edit,
+    clear_state,
+    cmd,
+    guard,
+    on_cb,
+    on_text,
+    say,
+    send_post,
+    set_state,
+    show,
+)
+from ..db import utcnow
+from ..tgutil import classify_media, esc, explain_rpc, pack_file_id, peer_of, post_link, ser_entities, short
+from ..ui import CANCEL, post_label
+from .panel import (
+    check_lengths,
+    load_post,
+    show_button_screen,
+    show_panel,
+)
+
+log = logging.getLogger(__name__)
+PAGE = 8
+UPDATED = "✅ Updated in the channel."
+
+
+def register(ctx: Ctx) -> None:
+    client, db = ctx.client, ctx.db
+
+    def note_for(post) -> str:
+        return UPDATED if post.status == "sent" else "✅ Saved."
+
+    # ------------------------------------------------------------------ lists
+    async def channel_chooser(event) -> None:
+        chans = await db.list_channels()
+        kb = [[Button.inline(f"📢 {short(c.title, 40)}", f"pc:{c.id}:0")] for c in chans]
+        kb.append([Button.inline("💾 Drafts (all channels)", "pc:d:0")])
+        await show(event, "📚 <b>My posts</b> - pick a channel:", kb)
+
+    @client.on(cmd("posts"))
+    @guard(ctx)
+    async def h_posts(event):
+        await channel_chooser(event)
+
+    @on_cb(ctx, "pl")
+    async def cb_channel_chooser(event, parts):
+        await channel_chooser(event)
+
+    @on_cb(ctx, "pc")
+    async def cb_list(event, parts):
+        key, page = parts[0], int(parts[1])
+        if key == "d":
+            cid, status, title = None, "draft", "Drafts"
+        else:
+            cid, status = int(key), None
+            ch = await db.get_channel(cid)
+            title = ch.title if ch else "Channel"
+        rows, total = await db.list_posts(cid, status, page * PAGE, PAGE)
+        pages = max(1, -(-total // PAGE))
+        if page >= pages:
+            page = pages - 1
+            rows, total = await db.list_posts(cid, status, page * PAGE, PAGE)
+        kb = [[Button.inline(post_label(p), f"po:{p.id}")] for p in rows]
+        if pages > 1:
+            nav = []
+            if page > 0:
+                nav.append(Button.inline("⬅️ Prev", f"pc:{key}:{page - 1}"))
+            nav.append(Button.inline(f"{page + 1}/{pages}", "noop"))
+            if page < pages - 1:
+                nav.append(Button.inline("Next ➡️", f"pc:{key}:{page + 1}"))
+            kb.append(nav)
+        kb.append([Button.inline("🔙 Channels", "pl")])
+        head = f"📚 <b>{esc(title)}</b> - {total} post(s)"
+        if not rows:
+            head += "\n\nNothing here yet. Create a post with /new."
+        await show(event, head, kb)
+
+    @on_cb(ctx, "po")
+    async def cb_open(event, parts):
+        clear_state(ctx, event.sender_id)
+        await show_panel(ctx, event, parts[0])
+
+    # ------------------------------------------------------------ text / caption
+    @on_cb(ctx, "et")
+    async def cb_edit_text(event, parts):
+        post, _ = await load_post(ctx, parts[0])
+        set_state(ctx, event.sender_id, "edit_text", pid=post.id)
+        what = "caption" if post.media_kind else "text"
+        await say(event, f"✏️ Send the new {what}. Formatting is kept.", CANCEL)
+
+    @on_text(ctx, "edit_text")
+    async def h_edit_text(event, st):
+        m = event.message
+        if classify_media(m):
+            raise UserError("Send text only here. To change the media, use 🖼 Media.")
+        post, ch = await load_post(ctx, st["pid"])
+        text = m.raw_text or ""
+        if not post.media_kind and not text.strip():
+            raise UserError("A text post can't be empty.")
+        check_lengths(text, bool(post.media_kind))
+        post = await apply_edit(ctx, post, ch, text=text, entities=ser_entities(m.entities))
+        clear_state(ctx, event.sender_id)
+        await show_panel(ctx, event, post.id, note=note_for(post), new=True)
+
+    # ------------------------------------------------------------------- media
+    @on_cb(ctx, "em")
+    async def cb_edit_media(event, parts):
+        post, _ = await load_post(ctx, parts[0])
+        set_state(ctx, event.sender_id, "edit_media", pid=post.id)
+        extra = "" if post.media_kind else "\nThe current text becomes its caption."
+        await say(event, f"🖼 Send the new photo / video / GIF / audio / file.{extra}", CANCEL)
+
+    @on_text(ctx, "edit_media")
+    async def h_edit_media(event, st):
+        m = event.message
+        if m.grouped_id and st.get("group") == m.grouped_id:
+            return
+        if m.grouped_id:
+            st["group"] = m.grouped_id
+        kind = classify_media(m)
+        if not kind:
+            raise UserError("Send a photo, video, GIF, audio file or document.")
+        post, ch = await load_post(ctx, st["pid"])
+        check_lengths(post.text or "", True)
+        post = await apply_edit(ctx, post, ch, replace_media=True, media_kind=kind, media_file_id=pack_file_id(m))
+        clear_state(ctx, event.sender_id)
+        await show_panel(ctx, event, post.id, note=note_for(post), new=True)
+
+    @on_cb(ctx, "rm")
+    async def cb_remove_media(event, parts):
+        post, ch = await load_post(ctx, parts[0])
+        if post.status != "draft":
+            raise UserError("Media can't be removed from a published post - Telegram doesn't allow it.")
+        if not (post.text or "").strip():
+            raise UserError("Add some text first, then remove the media (a post needs text or media).")
+        await db.update_post(post.id, media_kind=None, media_file_id=None)
+        await show_panel(ctx, event, post.id, note="✅ Media removed.")
+
+    @on_cb(ctx, "lp")
+    async def cb_link_preview(event, parts):
+        post, ch = await load_post(ctx, parts[0])
+        post = await apply_edit(ctx, post, ch, link_preview=not post.link_preview)
+        await show_panel(ctx, event, post.id)
+
+    # ----------------------------------------------------------------- buttons
+    async def commit_buttons(event, post, ch, rows, *, new_msg: bool = True, note: str = None):
+        post = await apply_edit(ctx, post, ch, buttons=rows)
+        await show_panel(ctx, event, post.id, note=note or note_for(post), new=new_msg)
+        return post
+
+    @on_cb(ctx, "ba")
+    async def cb_add_button(event, parts):
+        post, _ = await load_post(ctx, parts[0])
+        if count(post.buttons) >= 100:
+            raise UserError("A post can have at most 100 buttons.")
+        set_state(ctx, event.sender_id, "btn_add_text", pid=post.id)
+        await say(
+            event,
+            "➕ Send the button as <code>Button text - link</code>, or just the button text and I'll ask for the link.",
+            CANCEL,
+        )
+
+    async def place_button(event, pid, btn: dict) -> None:
+        post, ch = await load_post(ctx, pid)
+        if post.buttons and len(post.buttons[-1]) < MAX_ROW:
+            set_state(ctx, event.sender_id, "btn_place", pid=post.id, btn=btn)
+            await say(
+                event,
+                f"Where should <code>{esc(btn['t'])}</code> go?",
+                [
+                    [Button.inline("⬇️ New row", f"bk:{post.id}:n"), Button.inline("➡️ Same row", f"bk:{post.id}:s")],
+                    CANCEL[0],
+                ],
+            )
+            return
+        clear_state(ctx, event.sender_id)
+        await commit_buttons(event, post, ch, add_button(post.buttons, btn, True))
+
+    @on_text(ctx, "btn_add_text")
+    async def h_btn_add_text(event, st):
+        txt = (event.raw_text or "").strip()
+        if not txt:
+            raise UserError("Send the button text.")
+        try:
+            rows = parse_buttons_text(txt)
+        except ValueError:
+            rows = []
+        if rows:
+            if len(rows) == 1 and len(rows[0]) == 1:
+                await place_button(event, st["pid"], rows[0][0])
+                return
+            raise UserError("That's several buttons. Send one at a time, or use 📋 Set buttons to replace them all.")
+        if len(txt) > 64:
+            raise UserError("Keep the button text under 64 characters.")
+        set_state(ctx, event.sender_id, "btn_add_url", pid=st["pid"], text=txt)
+        await say(event, f"🔗 Now send the link for <code>{esc(txt)}</code>.", CANCEL)
+
+    @on_text(ctx, "btn_add_url")
+    async def h_btn_add_url(event, st):
+        url = norm_url(event.raw_text or "")
+        if not url:
+            raise UserError("That doesn't look like a link. Send something like https://t.me/yourbot?start=abc")
+        await place_button(event, st["pid"], {"t": st["text"], "u": url})
+
+    @on_cb(ctx, "bk")
+    async def cb_place(event, parts):
+        st = ctx.state.get(event.sender_id)
+        if not st or st.get("mode") != "btn_place" or str(st.get("pid")) != parts[0]:
+            raise UserError("That step expired. Tap ➕ Button again.")
+        post, ch = await load_post(ctx, parts[0])
+        rows = add_button(post.buttons, st["btn"], new_row=(parts[1] == "n"))
+        clear_state(ctx, event.sender_id)
+        await commit_buttons(event, post, ch, rows, new_msg=False)
+
+    @on_cb(ctx, "bp")
+    async def cb_paste(event, parts):
+        post, _ = await load_post(ctx, parts[0])
+        set_state(ctx, event.sender_id, "btn_paste", pid=post.id)
+        warn = ""
+        if any(b.get("raw") for r in post.buttons for b in r):
+            warn = "\n⚠️ This also removes buttons made by other bots (like reactions)."
+        await say(
+            event,
+            "📋 Send <b>all</b> the buttons - one row per line as <code>Text - link</code>, "
+            "with <code> | </code> between buttons in one row. This replaces the current buttons." + warn,
+            CANCEL,
+        )
+
+    @on_text(ctx, "btn_paste")
+    async def h_btn_paste(event, st):
+        try:
+            rows = parse_buttons_text(event.raw_text or "")
+        except ValueError as e:
+            raise UserError(f"❌ {e}\n\nTry again.")
+        if not rows:
+            raise UserError("Send at least one button as “Text - link”.")
+        post, ch = await load_post(ctx, st["pid"])
+        clear_state(ctx, event.sender_id)
+        await commit_buttons(event, post, ch, rows)
+
+    @on_cb(ctx, "bc")
+    async def cb_clear(event, parts):
+        await show(
+            event,
+            "Remove <b>all</b> buttons from this post?",
+            [[Button.inline("🧹 Yes, remove", f"bcy:{parts[0]}"), Button.inline("↩️ Back", f"po:{parts[0]}")]],
+        )
+
+    @on_cb(ctx, "bcy")
+    async def cb_clear_yes(event, parts):
+        post, ch = await load_post(ctx, parts[0])
+        await commit_buttons(event, post, ch, [], new_msg=False)
+
+    @on_cb(ctx, "bs")
+    async def cb_select(event, parts):
+        clear_state(ctx, event.sender_id)
+        await show_button_screen(ctx, event, parts[0], int(parts[1]), int(parts[2]))
+
+    @on_cb(ctx, "bt")
+    async def cb_btn_text(event, parts):
+        set_state(ctx, event.sender_id, "btn_text", pid=parts[0], r=int(parts[1]), c=int(parts[2]))
+        await say(event, "✏️ Send the new button text.", CANCEL)
+
+    @on_text(ctx, "btn_text")
+    async def h_btn_text(event, st):
+        txt = (event.raw_text or "").strip()
+        if not txt:
+            raise UserError("Send the new button text.")
+        if len(txt) > 64:
+            raise UserError("Keep the button text under 64 characters.")
+        post, ch = await load_post(ctx, st["pid"])
+        if not valid(post.buttons, st["r"], st["c"]):
+            raise UserError("That button no longer exists.")
+        post = await apply_edit(ctx, post, ch, buttons=set_field(post.buttons, st["r"], st["c"], t=txt))
+        clear_state(ctx, event.sender_id)
+        await show_button_screen(ctx, event, post.id, st["r"], st["c"], new=True)
+
+    @on_cb(ctx, "bu")
+    async def cb_btn_url(event, parts):
+        set_state(ctx, event.sender_id, "btn_url", pid=parts[0], r=int(parts[1]), c=int(parts[2]))
+        await say(event, "🔗 Send the new link for this button.", CANCEL)
+
+    @on_text(ctx, "btn_url")
+    async def h_btn_url(event, st):
+        url = norm_url(event.raw_text or "")
+        if not url:
+            raise UserError("That doesn't look like a link. Send something like https://t.me/yourbot?start=abc")
+        post, ch = await load_post(ctx, st["pid"])
+        if not valid(post.buttons, st["r"], st["c"]):
+            raise UserError("That button no longer exists.")
+        post = await apply_edit(ctx, post, ch, buttons=set_field(post.buttons, st["r"], st["c"], u=url))
+        clear_state(ctx, event.sender_id)
+        await show_button_screen(ctx, event, post.id, st["r"], st["c"], new=True)
+
+    @on_cb(ctx, "bm")
+    async def cb_move(event, parts):
+        pid, r, c, d = parts[0], int(parts[1]), int(parts[2]), parts[3]
+        post, ch = await load_post(ctx, pid)
+        rows, nr, nc = move_button(post.buttons, r, c, d)
+        if rows == post.buttons:
+            return  # already at the edge
+        post = await apply_edit(ctx, post, ch, buttons=rows)
+        await show_button_screen(ctx, event, post.id, nr, nc)
+
+    @on_cb(ctx, "bd")
+    async def cb_btn_delete(event, parts):
+        post, ch = await load_post(ctx, parts[0])
+        rows = delete_button(post.buttons, int(parts[1]), int(parts[2]))
+        await commit_buttons(event, post, ch, rows, new_msg=False)
+
+    # ------------------------------------------------------- preview / publish
+    @on_cb(ctx, "pv")
+    async def cb_preview(event, parts):
+        post, _ = await load_post(ctx, parts[0])
+        if not (post.text or "").strip() and not post.media_file_id:
+            raise UserError("The post is empty.")
+        await send_post(client, await event.get_input_chat(), post)
+        miss = missing_links(post.buttons)
+        if miss:
+            await say(event, f"👆 Preview. ⚠️ {miss} button(s) without a link are not shown.")
+
+    @on_cb(ctx, "pb")
+    async def cb_publish(event, parts):
+        post, ch = await load_post(ctx, parts[0])
+        if post.status != "draft":
+            raise UserError("This post is already published.")
+        if missing_links(post.buttons):
+            raise UserError("Some buttons (⚠️) have no link yet. Open them and add a link first.")
+        if not (post.text or "").strip() and not post.media_file_id:
+            raise UserError("The post is empty.")
+        await show(
+            event,
+            f"Publish this post to <b>{esc(ch.title)}</b>?",
+            [[Button.inline("🚀 Yes, publish", f"pby:{post.id}"), Button.inline("↩️ Back", f"po:{post.id}")]],
+        )
+
+    @on_cb(ctx, "pby")
+    async def cb_publish_yes(event, parts):
+        post, ch = await load_post(ctx, parts[0])
+        if post.status != "draft":
+            raise UserError("This post is already published.")
+        try:
+            sent = await send_post(client, peer_of(ch), post)
+        except errors.RPCError as e:
+            raise UserError("❌ " + explain_rpc(e) + "\nThe post was NOT published.")
+        post = await db.update_post(post.id, status="sent", message_id=sent.id, sent_at=utcnow())
+        await show(
+            event,
+            f"✅ <b>Published</b> in <b>{esc(ch.title)}</b>\n<a href=\"{post_link(ch, sent.id)}\">Open the post</a>",
+            [
+                [Button.inline("📝 Manage this post", f"po:{post.id}")],
+                [Button.inline("➕ New post", f"nc:{ch.id}")],
+            ],
+        )
+
+    # ----------------------------------------------------------------- delete
+    @on_cb(ctx, "dl")
+    async def cb_delete(event, parts):
+        post, ch = await load_post(ctx, parts[0])
+        back = Button.inline("↩️ Back", f"po:{post.id}")
+        if post.status == "draft":
+            await show(event, "Discard this draft?", [[Button.inline("🗑 Yes, discard", f"dly:{post.id}:b"), back]])
+            return
+        await show(
+            event,
+            f"Delete this post from <b>{esc(ch.title)}</b>?\n\n"
+            "Telegram only lets a bot delete posts that are less than 48 hours old. For older posts, delete them "
+            "by hand in the channel and then use “Only forget it”.",
+            [
+                [Button.inline("🗑 Delete from channel", f"dly:{post.id}:a")],
+                [Button.inline("🧹 Only forget it in the bot", f"dly:{post.id}:b")],
+                [back],
+            ],
+        )
+
+    @on_cb(ctx, "dly")
+    async def cb_delete_yes(event, parts):
+        post, ch = await load_post(ctx, parts[0])
+        if post.status == "sent" and parts[1] == "a":
+            res = await client.delete_messages(peer_of(ch), [post.message_id])
+            if not sum(getattr(r, "pts_count", 0) or 0 for r in res):
+                raise UserError(
+                    "Telegram did not delete that message - bots can only delete posts younger than 48 hours. "
+                    "Delete it by hand in the channel, then use “Only forget it in the bot”."
+                )
+        await db.delete_post(post.id)
+        await show(event, "🗑 Done.", [[Button.inline("📚 My posts", "pl")]])

app/handlers/replace.py

@@ -0,0 +1,436 @@
+"""/replace, /undo and /testedit (owner only)."""
+from __future__ import annotations
+
+import asyncio
+import logging
+import re
+import secrets
+import time
+from dataclasses import dataclass, field
+
+from telethon import Button, errors, types
+
+from ..common import Ctx, UserError, cmd, edit_callback_message, guard, on_cb, require_owner, say, show
+from ..linkswap import normalize_username
+from ..replace_engine import ApplyResult, ChannelScan, ScanOptions, apply_channel, scan_channel, undo_batch
+from ..tgutil import button_url, edit_raw, esc, explain_rpc, get_rights, peer_of, with_url
+from .channels import parse_channel_ref
+
+log = logging.getLogger(__name__)
+
+USAGE = (
+    "Usage: <code>/replace @old @new</code>\n"
+    "Options: <code>--channel @name</code> (only that channel), <code>--last 200</code> (only the newest 200 "
+    "post ids), <code>--posts</code> (also change t.me/old/123 post links), <code>--no-typed</code> (don't touch "
+    "links typed in the text)."
+)
+TOKEN_TTL = 3600
+
+
+@dataclass
+class Job:
+    user: int
+    opts: ScanOptions
+    scans: list
+    running: bool = False
+    created: float = field(default_factory=time.monotonic)
+
+
+def parse_replace_args(raw: str) -> tuple:
+    toks = (raw or "").split()
+    flags = {"channel": None, "last": None, "posts": False, "typed": None}
+    pos: list = []
+    i = 0
+    while i < len(toks):
+        t = toks[i]
+        if t == "--channel" and i + 1 < len(toks):
+            flags["channel"] = toks[i + 1]
+            i += 2
+        elif t == "--last" and i + 1 < len(toks):
+            if not toks[i + 1].isdigit() or int(toks[i + 1]) < 1:
+                raise ValueError("--last needs a number, for example --last 200")
+            flags["last"] = int(toks[i + 1])
+            i += 2
+        elif t == "--posts":
+            flags["posts"] = True
+            i += 1
+        elif t == "--no-typed":
+            flags["typed"] = False
+            i += 1
+        elif t.startswith("--"):
+            raise ValueError(f"Unknown option {t}")
+        else:
+            pos.append(t)
+            i += 1
+    if len(pos) != 2:
+        raise ValueError("Give the old and the new username.")
+    old, new = normalize_username(pos[0]), normalize_username(pos[1])
+    if not old or not new:
+        raise ValueError("Usernames look like @name (letters, digits and underscores).")
+    if old.lower() == new.lower():
+        raise ValueError("The old and the new username are the same.")
+    return old, new, flags
+
+
+def pick_channels(chans: list, ref) -> list:
+    if not ref:
+        return chans
+    r = parse_channel_ref(ref)
+    out = [c for c in chans if (isinstance(r, int) and c.id == r) or (isinstance(r, str) and (c.username or "").lower() == r.lower())]
+    if not out:
+        raise ValueError("That channel isn't registered (see /channels).")
+    return out
+
+
+def summary_text(job: Job) -> str:
+    o = job.opts
+    lines = [f"🔎 <b>Scan finished</b> - replace <code>@{esc(o.old)}</code> → <code>@{esc(o.new)}</code>"]
+    total = 0
+    for s in job.scans:
+        head = f"\n<b>{esc(s.channel.title)}</b>"
+        if s.error:
+            lines.append(f"{head}\n⚠️ {esc(s.error)}")
+            continue
+        block = f"{head} - looked at post ids {s.first}-{s.scanned}"
+        if s.total == 0:
+            block += "\nNothing to change."
+        else:
+            b = sum(i.buttons for i in s.infos.values())
+            h = sum(i.links for i in s.infos.values())
+            t = sum(i.typed for i in s.infos.values())
+            block += f"\n{s.total} post(s) to change: {b} button link(s), {h} hyperlink(s), {t} typed link(s)"
+            if s.foreign:
+                block += f"\n• {s.foreign} of them were not posted by this bot"
+            cb = sum(1 for i in s.infos.values() if i.callbacks)
+            if cb:
+                block += f"\n• {cb} carry other bots' buttons (e.g. reactions) - those stay as they are"
+        if s.skipped_post_links:
+            block += f"\n• skipped {s.skipped_post_links} link(s) to channel posts (t.me/{o.old}/123) - use --posts to change them too"
+        if s.not_editable:
+            block += f"\n⚠️ {s.not_editable} post(s) by others can't be edited: the bot lacks “Edit messages of others” here"
+        total += s.total
+        lines.append(block)
+    lines.append(f"\n<b>Total: {total} post(s).</b>")
+    if total:
+        lines.append("Nothing has been changed yet. Every edit is logged, so /undo can restore the old versions.")
+    return "\n".join(lines)
+
+
+def register(ctx: Ctx) -> None:
+    client, db, cfg = ctx.client, ctx.db, ctx.cfg
+    lock = asyncio.Lock()
+
+    def purge_tokens() -> None:
+        now = time.monotonic()
+        for k in [k for k, v in ctx.pending.items() if now - getattr(v, "created", now) > TOKEN_TTL]:
+            ctx.pending.pop(k, None)
+
+    def make_updater(event):
+        last = [0.0]
+
+        async def upd(text: str, force: bool = False) -> None:
+            now = time.monotonic()
+            if not force and now - last[0] < 3:
+                return
+            last[0] = now
+            try:
+                await edit_callback_message(event, text)
+            except errors.MessageNotModifiedError:
+                pass
+            except Exception:
+                log.debug("progress update failed", exc_info=True)
+
+        return upd
+
+    # ------------------------------------------------------------------ /replace
+    @client.on(cmd("replace", args=True))
+    @guard(ctx, owner=True)
+    async def h_replace(event):
+        purge_tokens()
+        raw = (event.pattern_match.group(1) or "").strip()
+        if not raw:
+            await say(event, USAGE)
+            return
+        try:
+            old, new, flags = parse_replace_args(raw)
+            chans = pick_channels(await db.list_channels(), flags["channel"])
+        except ValueError as e:
+            raise UserError(f"{e}\n\n" + re.sub(r"<[^>]+>", "", USAGE))
+        if not chans:
+            raise UserError("No channels registered yet. Use /addchannel.")
+        if lock.locked():
+            raise UserError("Another /replace or /undo is still running - wait for it to finish.")
+        opts = ScanOptions(
+            old=old,
+            new=new,
+            include_typed=cfg.replace_typed_links if flags["typed"] is None else flags["typed"],
+            include_posts=flags["posts"],
+            last=flags["last"],
+        )
+        async with lock:
+            status = await say(event, f"🔍 Scanning {len(chans)} channel(s)…")
+            last_edit = [0.0]
+            scans = []
+            for ch in chans:
+                rights = await get_rights(client, ch)
+                if rights is not None and not rights.admin:
+                    s = await _empty_scan(ch, "The bot is not an admin here any more.")
+                    scans.append(s)
+                    continue
+                can_edit = True if rights is None else rights.edit
+
+                async def prog(scan, title=ch.title):
+                    now = time.monotonic()
+                    if now - last_edit[0] < 3:
+                        return
+                    last_edit[0] = now
+                    try:
+                        await status.edit(f"🔍 Scanning <b>{esc(title)}</b>: post id {scan.scanned} of {scan.top or '?'}…")
+                    except Exception:
+                        pass
+
+                try:
+                    scan = await scan_channel(
+                        client, ch, opts, can_edit_others=can_edit, mine_ids=await db.mine_message_ids(ch.id), progress=prog
+                    )
+                except errors.RPCError as e:
+                    scan = await _empty_scan(ch, explain_rpc(e))
+                scan.rights = rights
+                scans.append(scan)
+        job = Job(user=event.sender_id, opts=opts, scans=scans)
+        token = secrets.token_hex(4)
+        ctx.pending[token] = job
+        total = sum(s.total for s in scans)
+        kb = None
+        if total:
+            kb = [[Button.inline(f"✅ Apply to {total} post(s)", f"rp:{token}:y"), Button.inline("✖️ Cancel", f"rp:{token}:n")]]
+        try:
+            await status.edit(summary_text(job), buttons=kb, link_preview=False)
+        except Exception:
+            await say(event, summary_text(job), kb)
+
+    async def _empty_scan(ch, error: str):
+        return ChannelScan(channel=ch, error=error)
+
+    @on_cb(ctx, "rp")
+    async def cb_replace(event, parts):
+        require_owner(ctx, event)
+        token, action = parts[0], parts[1]
+        job = ctx.pending.get(token)
+        if not isinstance(job, Job) or job.user != event.sender_id:
+            raise UserError("That scan has expired. Run /replace again.")
+        if action == "n":
+            ctx.pending.pop(token, None)
+            await show(event, "Cancelled - nothing was changed.")
+            return
+        if job.running or lock.locked():
+            raise UserError("It is already running.")
+        job.running = True
+        upd = make_updater(event)
+        batch_id = secrets.token_hex(6)
+        o = job.opts
+        totals = ApplyResult()
+        async with lock:
+            await db.create_batch(batch_id, o.old, o.new, event.sender_id)
+            todo = sum(s.total for s in job.scans)
+            done_before = 0
+            for s in job.scans:
+                if not s.infos:
+                    continue
+
+                async def prog(res, s=s, base=done_before):
+                    await upd(f"⏳ <b>{esc(s.channel.title)}</b> - {base + res.edited}/{todo} edited…")
+
+                try:
+                    res = await apply_channel(
+                        client, db, s, o, batch_id, event.sender_id, edit_delay=cfg.edit_delay, progress=prog
+                    )
+                except Exception as e:
+                    log.exception("apply failed in %s", s.channel.id)
+                    totals.failed.append((0, f"{s.channel.title}: {type(e).__name__}"))
+                    continue
+                done_before += res.edited
+                totals.edited += res.edited
+                totals.unchanged += res.unchanged
+                totals.missing += res.missing
+                totals.no_perm += res.no_perm
+                totals.failed += res.failed
+        ctx.pending.pop(token, None)
+        lines = [f"✅ <b>Done</b> - <code>@{esc(o.old)}</code> → <code>@{esc(o.new)}</code>", f"• edited: <b>{totals.edited}</b>"]
+        if totals.unchanged:
+            lines.append(f"• already fine / changed meanwhile: {totals.unchanged}")
+        if totals.missing:
+            lines.append(f"• deleted meanwhile: {totals.missing}")
+        if totals.no_perm:
+            lines.append(f"• skipped (no permission): {totals.no_perm}")
+        if totals.failed:
+            sample = ", ".join(f"#{m} {esc(n)}" for m, n in totals.failed[:8])
+            lines.append(f"• <b>failed: {len(totals.failed)}</b> ({sample}{'…' if len(totals.failed) > 8 else ''})")
+            names = {n for _, n in totals.failed}
+            if names & {"MessageAuthorRequiredError", "InlineBotRequiredError", "ChatAdminRequiredError"}:
+                lines.append("  Telegram doesn't let this bot edit those posts (see /testedit).")
+        kb = [[Button.inline("↩️ Undo this replace", f"ruc:{batch_id}")]] if totals.edited else None
+        if kb:
+            try:
+                await edit_callback_message(event, "\n".join(lines), kb)
+            except errors.MessageNotModifiedError:
+                pass
+        else:
+            await upd("\n".join(lines), force=True)
+
+    # -------------------------------------------------------------------- /undo
+    async def ask_undo(event, batch) -> None:
+        n = await db.count_batch_changes(batch.id)
+        await say(
+            event,
+            f"↩️ Undo the replace <code>@{esc(batch.old_username)}</code> → <code>@{esc(batch.new_username)}</code>?\n"
+            f"{n} post(s) will be put back exactly as they were before.",
+            [[Button.inline("✅ Yes, undo", f"ru:{batch.id}"), Button.inline("✖️ No", "cx")]],
+        )
+
+    @client.on(cmd("undo"))
+    @guard(ctx, owner=True)
+    async def h_undo(event):
+        batch = await db.last_batch()
+        if batch is None:
+            raise UserError("There is no /replace run to undo.")
+        await ask_undo(event, batch)
+
+    @on_cb(ctx, "ruc")
+    async def cb_undo_ask(event, parts):
+        require_owner(ctx, event)
+        batch = await db.get_batch(parts[0])
+        if batch is None or batch.undone:
+            raise UserError("That replace was already undone.")
+        await ask_undo(event, batch)
+
+    @on_cb(ctx, "ru")
+    async def cb_undo(event, parts):
+        require_owner(ctx, event)
+        if lock.locked():
+            raise UserError("Another /replace or /undo is still running.")
+        upd = make_updater(event)
+        async with lock:
+            await upd("⏳ Restoring…", force=True)
+
+            async def prog(res):
+                await upd(f"⏳ Restoring… {res.restored} done")
+
+            res = await undo_batch(client, db, parts[0], edit_delay=cfg.edit_delay, progress=prog)
+        text = f"↩️ Restored <b>{res.restored}</b> post(s)."
+        if res.failed:
+            text += f"\n⚠️ {len(res.failed)} could not be restored (" + ", ".join(f"#{m} {esc(n)}" for m, n in res.failed[:6]) + ")."
+        await upd(text, force=True)
+
+    # ---------------------------------------------------------------- /testedit
+    link_rx = re.compile(
+        r"(?i)(?:https?://)?(?:t\.me|telegram\.me)/(?:c/(?P<cid>\d+)|(?P<user>[A-Za-z0-9_]{3,32}))/(?P<mid>\d+)"
+    )
+
+    @client.on(cmd("testedit", args=True))
+    @guard(ctx, owner=True)
+    async def h_testedit(event):
+        purge_tokens()
+        m = link_rx.search(event.pattern_match.group(1) or "")
+        if not m:
+            raise UserError("Usage: /testedit https://t.me/yourchannel/123  (a link to one post that has a link button)")
+        chans = await db.list_channels()
+        ch = None
+        for c in chans:
+            if (m.group("cid") and c.id == int(m.group("cid"))) or (
+                m.group("user") and (c.username or "").lower() == m.group("user").lower()
+            ):
+                ch = c
+        if ch is None:
+            raise UserError("That channel isn't registered. Use /addchannel first.")
+        mid = int(m.group("mid"))
+        msgs = await client.get_messages(peer_of(ch), ids=[mid])
+        msg = msgs[0] if msgs else None
+        if msg is None or isinstance(msg, (types.MessageEmpty, types.MessageService)):
+            raise UserError("I can't read that message - was it deleted?")
+        urls = []
+        if isinstance(msg.reply_markup, types.ReplyInlineMarkup):
+            urls = [button_url(b) for row in msg.reply_markup.rows for b in row.buttons if button_url(b)]
+        if not urls:
+            raise UserError("That post has no link buttons. Pick one that has a button with a link.")
+        rights = await get_rights(client, ch)
+        rtxt = "unknown" if rights is None else ("can edit others' posts" if rights.edit else "⚠️ NO “edit messages of others” right")
+        token = secrets.token_hex(4)
+        ctx.pending[token] = _TestJob(user=event.sender_id, ch=ch, mid=mid)
+        await say(
+            event,
+            f"🧪 <b>Edit test</b> for post {mid} in <b>{esc(ch.title)}</b>\n"
+            f"Posted by this bot: {'yes' if msg.out else 'no (someone else / another bot)'}\n"
+            f"Bot rights: {rtxt}\n"
+            f"First button link: <code>{esc(urls[0][:80])}</code>\n\n"
+            "The test adds <code>x=1</code> to that first link and immediately changes it back. "
+            "Visitors won't notice.",
+            [[Button.inline("🧪 Run the test", f"te:{token}"), Button.inline("✖️ Cancel", "cx")]],
+        )
+
+    @on_cb(ctx, "te")
+    async def cb_testedit(event, parts):
+        require_owner(ctx, event)
+        job = ctx.pending.pop(parts[0], None)
+        if not isinstance(job, _TestJob) or job.user != event.sender_id:
+            raise UserError("That test has expired. Run /testedit again.")
+        peer = peer_of(job.ch)
+        msgs = await client.get_messages(peer, ids=[job.mid])
+        msg = msgs[0]
+        if msg is None or not isinstance(msg.reply_markup, types.ReplyInlineMarkup):
+            raise UserError("The post changed or was deleted. Run /testedit again.")
+        original = msg.reply_markup
+        changed = False
+        rows = []
+        for row in original.rows:
+            btns = []
+            for b in row.buttons:
+                u = button_url(b)
+                if u and not changed:
+                    btns.append(with_url(b, u + ("&" if "?" in u else "?") + "x=1"))
+                    changed = True
+                else:
+                    btns.append(b)
+            rows.append(types.KeyboardButtonRow(btns))
+        try:
+            await edit_raw(client, peer, job.mid, markup=types.ReplyInlineMarkup(rows))
+        except errors.RPCError as e:
+            await show(
+                event,
+                f"❌ <b>Telegram refused the edit</b>\n{esc(explain_rpc(e))}\n\n"
+                "So /replace can NOT change the buttons of this post with this bot.",
+            )
+            return
+        restored, last_err = False, None
+        for _ in range(3):
+            try:
+                await edit_raw(client, peer, job.mid, markup=original)
+                restored = True
+                break
+            except errors.MessageNotModifiedError:
+                restored = True
+                break
+            except errors.RPCError as e:
+                last_err = e
+                await asyncio.sleep(1.5)
+        if restored:
+            await show(
+                event,
+                "✅ <b>Test passed.</b> The bot can edit the buttons of that post, and the link was put back.\n"
+                "/replace will work on posts like this one.",
+            )
+        else:
+            orig_urls = "\n".join(esc(button_url(b)) for row in original.rows for b in row.buttons if button_url(b))
+            await show(
+                event,
+                f"⚠️ The edit worked, but putting the link back failed ({esc(type(last_err).__name__)}).\n"
+                "The first link still ends in x=1 - please fix it by hand. Original links:\n" + orig_urls,
+            )
+
+
+@dataclass
+class _TestJob:
+    user: int
+    ch: object
+    mid: int
+    created: float = field(default_factory=time.monotonic)

app/health.py

@@ -0,0 +1,22 @@
+"""Optional tiny HTTP endpoint for hosts that insist on an open port (set PORT)."""
+import asyncio
+import logging
+
+log = logging.getLogger(__name__)
+
+
+async def start_health_server(port: int):
+    async def handle(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+        try:
+            await asyncio.wait_for(reader.read(1024), timeout=5)
+        except Exception:
+            pass
+        try:
+            writer.write(b"HTTP/1.1 200 OK\r\nContent-Type: text/plain\r\nContent-Length: 2\r\nConnection: close\r\n\r\nok")
+            await writer.drain()
+        finally:
+            writer.close()
+
+    server = await asyncio.start_server(handle, "0.0.0.0", port)
+    log.info("health endpoint listening on :%s", port)
+    return server

app/linkswap.py

@@ -0,0 +1,211 @@
+"""Swap a username inside t.me links: button links, hyperlinks and typed links in message text.
+
+Only the username part of a link changes; everything after it (?start=...) is left untouched.
+Offsets of message entities are UTF-16 based, so text is handled in Telethon's 'surrogate' form.
+"""
+from __future__ import annotations
+
+import copy
+import re
+from dataclasses import dataclass
+from typing import Optional
+
+from telethon import types
+from telethon.helpers import add_surrogate, del_surrogate
+
+from .tgutil import button_url, is_callback_button, with_url
+
+USERNAME_RX = re.compile(r"^[A-Za-z0-9_]{1,32}$")
+
+
+def normalize_username(s: str) -> Optional[str]:
+    s = (s or "").strip()
+    m = re.match(r"(?i)^(?:https?://)?(?:t\.me|telegram\.me)/([A-Za-z0-9_]+)/?$", s)
+    if m:
+        s = m.group(1)
+    s = s.lstrip("@")
+    return s if USERNAME_RX.match(s) else None
+
+
+# ------------------------------------------------------------------------------- urls
+_HTTP_RX = re.compile(
+    r"^(?P<pre>(?:https?://)?(?:www\.)?(?:t\.me|telegram\.me|telegram\.dog)/)(?P<name>[A-Za-z0-9_]+)(?P<rest>[/?#].*)?$",
+    re.I | re.S,
+)
+_TG_RX = re.compile(r"^(?P<pre>tg://resolve\?(?:[^#]*&)?domain=)(?P<name>[A-Za-z0-9_]+)(?P<rest>[&#].*)?$", re.I | re.S)
+
+
+def _split(url: str):
+    for rx in (_HTTP_RX, _TG_RX):
+        m = rx.match(url)
+        if m:
+            return m
+    return None
+
+
+def _is_post_tail(tail: str) -> bool:
+    return bool(re.match(r"/\d", tail)) or bool(re.match(r"&post=\d", tail))
+
+
+def classify_url(url: str, old: str) -> Optional[str]:
+    """'link' (t.me/old?start=..), 'post' (t.me/old/123 - a channel post) or None."""
+    m = _split(url or "")
+    if not m or m.group("name").lower() != old.lower():
+        return None
+    return "post" if _is_post_tail(m.group("rest") or "") else "link"
+
+
+def swap_url(url: str, old: str, new: str) -> str:
+    m = _split(url or "")
+    if not m or m.group("name").lower() != old.lower():
+        return url
+    return url[: m.start("name")] + new + url[m.end("name"):]
+
+
+# ------------------------------------------------------------------- typed links in text
+def _typed_regexes(old: str) -> list:
+    n = re.escape(old)
+    return [
+        re.compile(
+            r"(?<![\w@./-])(?:https?://)?(?:www\.)?(?:t\.me|telegram\.me|telegram\.dog)/(?P<name>" + n + r")(?![A-Za-z0-9_])",
+            re.I,
+        ),
+        re.compile(r"(?<![\w@./-])tg://resolve\?(?:[^\s&#]*&)?domain=(?P<name>" + n + r")(?![A-Za-z0-9_])", re.I),
+    ]
+
+
+def find_typed_spans(sur: str, old: str, include_posts: bool) -> tuple:
+    spans: list = []
+    skipped = 0
+    for rx in _typed_regexes(old):
+        for m in rx.finditer(sur):
+            s, e = m.span("name")
+            if _is_post_tail(sur[e:e + 8]) and not include_posts:
+                skipped += 1
+                continue
+            spans.append((s, e))
+    spans.sort()
+    return spans, skipped
+
+
+def apply_span_replacements(sur: str, entities: list, repls: list) -> tuple:
+    """repls: sorted, non-overlapping (start, end, new_text) in UTF-16 units.
+    Returns (new_text, new_entities) with every entity offset/length kept consistent."""
+    parts: list = []
+    last = 0
+    for s, e, nt in repls:
+        parts.append(sur[last:s])
+        parts.append(nt)
+        last = e
+    parts.append(sur[last:])
+    new_text = "".join(parts)
+
+    def mp(x: int) -> int:
+        acc = 0
+        for s, e, nt in repls:
+            if x >= e:
+                acc += len(nt) - (e - s)
+            elif x > s:
+                return s + acc + min(x - s, len(nt))
+            else:
+                break
+        return x + acc
+
+    out = []
+    for ent in entities:
+        cp = copy.copy(ent)
+        o = mp(ent.offset)
+        end = mp(ent.offset + ent.length)
+        cp.offset = o
+        cp.length = max(0, end - o)
+        out.append(cp)
+    return new_text, out
+
+
+# --------------------------------------------------------------------- whole message
+@dataclass
+class MsgChange:
+    message_id: int
+    new_text: str
+    new_entities: list
+    new_markup: Optional[types.ReplyInlineMarkup]
+    text_changed: bool
+    entities_changed: bool
+    n_buttons: int
+    n_links: int
+    n_typed: int
+    mine: bool
+    callbacks: bool
+
+
+def compute_message_changes(msg, old: str, new: str, *, include_typed: bool = True, include_posts: bool = False) -> tuple:
+    """Returns (MsgChange or None, number_of_skipped_post_links)."""
+    text = msg.message or ""
+    ents = list(msg.entities or [])
+    skipped = 0
+    n_typed = n_links = n_btn = 0
+
+    # 1) links typed as plain text (this changes the text itself)
+    sur = add_surrogate(text)
+    new_sur = sur
+    new_ents = [copy.copy(e) for e in ents]
+    if include_typed and text:
+        spans, sk = find_typed_spans(sur, old, include_posts)
+        skipped += sk
+        if spans:
+            new_sur, new_ents = apply_span_replacements(sur, ents, [(s, e, new) for s, e in spans])
+            n_typed = len(spans)
+
+    # 2) hyperlinks (text with a link behind it)
+    for e in new_ents:
+        if isinstance(e, types.MessageEntityTextUrl):
+            kind = classify_url(e.url, old)
+            if kind == "link" or (kind == "post" and include_posts):
+                e.url = swap_url(e.url, old, new)
+                n_links += 1
+            elif kind == "post":
+                skipped += 1
+
+    # 3) buttons
+    new_markup = None
+    has_cb = False
+    mk = msg.reply_markup
+    if isinstance(mk, types.ReplyInlineMarkup):
+        rows = []
+        for row in mk.rows:
+            btns = []
+            for b in row.buttons:
+                url = button_url(b)
+                if url is not None:
+                    kind = classify_url(url, old)
+                    if kind == "link" or (kind == "post" and include_posts):
+                        btns.append(with_url(b, swap_url(url, old, new)))
+                        n_btn += 1
+                        continue
+                    if kind == "post":
+                        skipped += 1
+                elif is_callback_button(b):
+                    has_cb = True
+                btns.append(b)
+            rows.append(types.KeyboardButtonRow(btns))
+        if n_btn:
+            new_markup = types.ReplyInlineMarkup(rows)
+
+    if not (n_typed or n_links or n_btn):
+        return None, skipped
+    return (
+        MsgChange(
+            message_id=msg.id,
+            new_text=del_surrogate(new_sur),
+            new_entities=new_ents,
+            new_markup=new_markup,
+            text_changed=bool(n_typed),
+            entities_changed=bool(n_typed or n_links),
+            n_buttons=n_btn,
+            n_links=n_links,
+            n_typed=n_typed,
+            mine=bool(getattr(msg, "out", False)),
+            callbacks=has_cb,
+        ),
+        skipped,
+    )

app/replace_engine.py

@@ -0,0 +1,306 @@
+"""/replace engine: scan channels message by message, rewrite links, log every change, undo."""
+from __future__ import annotations
+
+import asyncio
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Awaitable, Callable, Optional
+
+from telethon import errors, functions, types
+
+from .linkswap import compute_message_changes
+from .tgutil import (
+    build_markup,
+    de_entities,
+    edit_raw,
+    flood_retry,
+    media_info,
+    peer_of,
+    ser_entities,
+    ser_markup,
+    state_of,
+)
+
+log = logging.getLogger(__name__)
+
+CHUNK = 100  # Telegram returns at most 100 messages per request
+FALLBACK_EMPTY_BATCHES = 15  # used only when the newest message id can't be determined
+
+
+@dataclass
+class ScanOptions:
+    old: str
+    new: str
+    include_typed: bool = True
+    include_posts: bool = False
+    last: Optional[int] = None
+
+
+@dataclass
+class ChangeInfo:
+    message_id: int
+    buttons: int = 0
+    links: int = 0
+    typed: int = 0
+    mine: bool = False
+    callbacks: bool = False
+
+
+@dataclass
+class ChannelScan:
+    channel: Any
+    can_edit_others: bool = True
+    top: int = 0
+    first: int = 1
+    scanned: int = 0
+    infos: dict = field(default_factory=dict)
+    skipped_post_links: int = 0
+    not_editable: int = 0
+    error: Optional[str] = None
+    rights: Any = None
+
+    @property
+    def total(self) -> int:
+        return len(self.infos)
+
+    @property
+    def foreign(self) -> int:
+        return sum(1 for i in self.infos.values() if not i.mine)
+
+
+@dataclass
+class ApplyResult:
+    edited: int = 0
+    unchanged: int = 0
+    missing: int = 0
+    no_perm: int = 0
+    failed: list = field(default_factory=list)
+
+
+@dataclass
+class UndoResult:
+    restored: int = 0
+    failed: list = field(default_factory=list)
+
+
+async def _fetch(client, peer, ids: list) -> list:
+    res = await flood_retry(lambda: client.get_messages(peer, ids=ids))
+    return list(res)
+
+
+async def get_top_id(client, peer) -> Optional[int]:
+    """Upper bound for the newest message id: the channel's event counter (pts) is never lower."""
+    try:
+        full = await flood_retry(lambda: client(functions.channels.GetFullChannelRequest(peer)))
+        pts = getattr(full.full_chat, "pts", None)
+        if pts:
+            return int(pts)
+    except Exception as e:
+        log.info("could not read channel counter: %s", e)
+    return None
+
+
+def _skip(m) -> bool:
+    return m is None or isinstance(m, (types.MessageEmpty, types.MessageService))
+
+
+async def scan_channel(
+    client,
+    ch,
+    opts: ScanOptions,
+    *,
+    can_edit_others: bool = True,
+    mine_ids: Optional[set] = None,
+    progress: Optional[Callable[[ChannelScan], Awaitable[None]]] = None,
+) -> ChannelScan:
+    scan = ChannelScan(channel=ch, can_edit_others=can_edit_others)
+    peer = peer_of(ch)
+    mine_ids = mine_ids or set()
+    top = await get_top_id(client, peer)
+    first = 1
+    if opts.last and top:
+        first = max(1, top - opts.last + 1)
+    scan.first, scan.top = first, top or 0
+    a, empty_run = first, 0
+    while True:
+        if top is not None and a > top:
+            break
+        hi = a + CHUNK - 1 if top is None else min(a + CHUNK - 1, top)
+        msgs = await _fetch(client, peer, list(range(a, hi + 1)))
+        found = False
+        for m in msgs:
+            if m is None or isinstance(m, types.MessageEmpty):
+                continue
+            found = True
+            if isinstance(m, types.MessageService):
+                continue
+            change, skipped = compute_message_changes(
+                m, opts.old, opts.new, include_typed=opts.include_typed, include_posts=opts.include_posts
+            )
+            scan.skipped_post_links += skipped
+            if not change:
+                continue
+            mine = change.mine or m.id in mine_ids
+            if not mine and not can_edit_others:
+                scan.not_editable += 1
+                continue
+            scan.infos[m.id] = ChangeInfo(
+                m.id, change.n_buttons, change.n_links, change.n_typed, mine, change.callbacks
+            )
+        scan.scanned = hi
+        if top is None:
+            empty_run = 0 if found else empty_run + 1
+            if empty_run >= FALLBACK_EMPTY_BATCHES:
+                break
+        if progress:
+            await progress(scan)
+        a = hi + 1
+    if top is None:
+        scan.top = scan.scanned
+    return scan
+
+
+def preview_flag(m):
+    if isinstance(m.media, types.MessageMediaWebPage):
+        return True
+    return False if m.media is None else None
+
+
+async def _do_edit(client, peer, m, change, markup, preview) -> None:
+    if change.text_changed or change.entities_changed:
+        await edit_raw(
+            client, peer, m.id, text=change.new_text, entities=change.new_entities, markup=markup, preview=preview
+        )
+    else:  # only button links changed: leave the text untouched
+        await edit_raw(client, peer, m.id, markup=markup)
+
+
+async def apply_channel(
+    client,
+    db,
+    scan: ChannelScan,
+    opts: ScanOptions,
+    batch_id: str,
+    user_id: int,
+    *,
+    edit_delay: float = 1.2,
+    progress: Optional[Callable[[ApplyResult], Awaitable[None]]] = None,
+) -> ApplyResult:
+    ch = scan.channel
+    peer = peer_of(ch)
+    mine_ids = await db.mine_message_ids(ch.id)
+    res = ApplyResult()
+    ids = sorted(scan.infos)
+    buf: list = []
+
+    async def flush() -> None:
+        nonlocal buf
+        if buf:
+            batch, buf = buf, []
+            await db.record_changes(batch_id, ch.id, batch, user_id)
+
+    try:
+        for i in range(0, len(ids), CHUNK):
+            chunk = ids[i:i + CHUNK]
+            msgs = await _fetch(client, peer, chunk)
+            for mid, m in zip(chunk, msgs):
+                if _skip(m):
+                    res.missing += 1
+                    continue
+                # re-check against the live message: it may have been edited since the scan
+                change, _ = compute_message_changes(
+                    m, opts.old, opts.new, include_typed=opts.include_typed, include_posts=opts.include_posts
+                )
+                if not change:
+                    res.unchanged += 1
+                    continue
+                if not (change.mine or m.id in mine_ids) and not scan.can_edit_others:
+                    res.no_perm += 1
+                    continue
+                preview = preview_flag(m)
+                markup = change.new_markup if change.new_markup is not None else m.reply_markup
+                old_state = state_of(m.message, m.entities, m.reply_markup, preview)
+                try:
+                    await flood_retry(lambda: _do_edit(client, peer, m, change, markup, preview))
+                except errors.MessageNotModifiedError:
+                    res.unchanged += 1
+                    continue
+                except errors.RPCError as e:
+                    log.warning("edit of %s/%s failed: %s", ch.id, m.id, e)
+                    res.failed.append((m.id, type(e).__name__))
+                    continue
+                res.edited += 1
+                kind, fid = media_info(m)
+                adopt = {
+                    "text": change.new_text,
+                    "entities": ser_entities(change.new_entities),
+                    "buttons": ser_markup(markup),
+                    "link_preview": bool(preview),
+                }
+                if kind:
+                    adopt["media_kind"], adopt["media_file_id"] = kind, fid
+                buf.append(
+                    {
+                        "message_id": m.id,
+                        "old_state": old_state,
+                        "new_state": state_of(change.new_text, change.new_entities, markup, preview),
+                        "adopt": adopt,
+                    }
+                )
+                if len(buf) >= 10:
+                    await flush()
+                if progress:
+                    await progress(res)
+                await asyncio.sleep(edit_delay)
+    finally:
+        await flush()
+    return res
+
+
+async def undo_batch(
+    client,
+    db,
+    batch_id: str,
+    *,
+    edit_delay: float = 1.2,
+    progress: Optional[Callable[[UndoResult], Awaitable[None]]] = None,
+) -> UndoResult:
+    """Put every post touched by a /replace run back exactly as it was."""
+    res = UndoResult()
+    channels: dict = {}
+    done_ids: list = []
+    restored: list = []
+    for c in await db.batch_changes(batch_id):
+        if c.channel_id not in channels:
+            channels[c.channel_id] = await db.get_channel(c.channel_id)
+        ch = channels[c.channel_id]
+        if ch is None:
+            res.failed.append((c.message_id, "ChannelRemoved"))
+            continue
+        old = c.old_state or {}
+        try:
+            await flood_retry(
+                lambda: edit_raw(
+                    client,
+                    peer_of(ch),
+                    c.message_id,
+                    text=old.get("text", ""),
+                    entities=de_entities(old.get("entities")),
+                    markup=build_markup(old.get("buttons")),
+                    preview=old.get("preview"),
+                )
+            )
+        except errors.MessageNotModifiedError:
+            pass
+        except errors.RPCError as e:
+            log.warning("undo of %s/%s failed: %s", c.channel_id, c.message_id, e)
+            res.failed.append((c.message_id, type(e).__name__))
+            continue
+        res.restored += 1
+        done_ids.append(c.id)
+        restored.append((c.channel_id, c.message_id, old))
+        if progress:
+            await progress(res)
+        await asyncio.sleep(edit_delay)
+    await db.finish_undo(batch_id, done_ids, restored, all_done=not res.failed)
+    return res

app/suggest.py

@@ -0,0 +1,124 @@
+"""Auto-suggest the next episode batch: 'Download Episodes 01 to 20' -> 'Download Episodes 21 to 40'."""
+from __future__ import annotations
+
+import copy
+import re
+from dataclasses import dataclass, field
+from typing import Optional
+
+from telethon.helpers import add_surrogate, del_surrogate
+
+from .linkswap import apply_span_replacements
+from .tgutil import de_entities, ser_entities
+
+RANGE_RX = re.compile(r"(?P<a>\d+)(?P<sep>\s*(?:to|[-–—~&])\s*)(?P<pre>(?:ep?\.?\s*)?)(?P<b>\d+)", re.I)
+SINGLE_RX = re.compile(r"(?<![\w.])(?P<label>episodes?|eps?\.?|e)(?P<gap>\s*[-:#]?\s*)(?P<n>\d+)(?!\d)", re.I)
+
+
+@dataclass
+class Advance:
+    new_text: str  # the whole string with the numbers moved on
+    old_span: str  # e.g. "01 to 20"
+    new_span: str  # e.g. "21 to 40"
+
+
+def advance_plain(s: str) -> Optional[Advance]:
+    """Move the first episode range (or single episode) in `s` on to the next batch."""
+    for m in RANGE_RX.finditer(s or ""):
+        a_s, b_s = m.group("a"), m.group("b")
+        a, b = int(a_s), int(b_s)
+        if a > b or b - a > 5000:
+            continue
+        step = b - a + 1
+        width = max(len(a_s), len(b_s)) if (a_s.startswith("0") or b_s.startswith("0")) else 0
+        na, nb = str(b + 1).zfill(width), str(b + step).zfill(width)
+        new_span = na + s[m.end("a"):m.start("b")] + nb
+        return Advance(
+            new_text=s[: m.start("a")] + new_span + s[m.end("b"):],
+            old_span=s[m.start("a"):m.end("b")],
+            new_span=new_span,
+        )
+    for m in SINGLE_RX.finditer(s or ""):
+        n_s = m.group("n")
+        width = len(n_s) if n_s.startswith("0") else 0
+        nn = str(int(n_s) + 1).zfill(width)
+        return Advance(
+            new_text=s[: m.start("n")] + nn + s[m.end("n"):],
+            old_span=s[m.start("label"):m.end("n")],
+            new_span=s[m.start("label"):m.start("n")] + nn,
+        )
+    return None
+
+
+@dataclass
+class Suggestion:
+    text: str
+    entities: list
+    buttons: list
+    media_kind: Optional[str]
+    media_file_id: Optional[str]
+    pending: list = field(default_factory=list)  # [(row, col)] of buttons that still need a link
+    prev_label: str = ""
+    new_label: str = ""
+    source_post_id: int = 0
+
+
+def build_suggestion(post) -> Optional[Suggestion]:
+    rows: list = []
+    pending: list = []
+    first: Optional[Advance] = None
+    prev_label = ""
+    for row in post.buttons or []:
+        new_row: list = []
+        for b in row:
+            if b.get("raw"):  # other bots' buttons (e.g. reactions) are not carried over
+                continue
+            b = dict(b)
+            b.pop("s", None)
+            adv = advance_plain(b.get("t", "")) if b.get("u") else None
+            if adv:
+                if first is None:
+                    first, prev_label = adv, b["t"]
+                b["t"] = adv.new_text
+                b["u"] = None
+                pending.append((len(rows), len(new_row)))
+            new_row.append(b)
+        if new_row:
+            rows.append(new_row)
+    if not pending or first is None:
+        return None
+
+    text = post.text or ""
+    entities = copy.deepcopy(post.entities or [])
+    sur = add_surrogate(text)
+    repls: list = []
+    pos = 0
+    while first.old_span:
+        i = sur.find(first.old_span, pos)
+        if i < 0:
+            break
+        repls.append((i, i + len(first.old_span), first.new_span))
+        pos = i + len(first.old_span)
+    if repls:
+        new_sur, new_ents = apply_span_replacements(sur, de_entities(entities), repls)
+        text, entities = del_surrogate(new_sur), ser_entities(new_ents)
+
+    return Suggestion(
+        text=text,
+        entities=entities,
+        buttons=rows,
+        media_kind=post.media_kind,
+        media_file_id=post.media_file_id,
+        pending=pending,
+        prev_label=prev_label,
+        new_label=rows[pending[0][0]][pending[0][1]]["t"],
+        source_post_id=post.id,
+    )
+
+
+async def make_suggestion(db, channel_id: int) -> Optional[Suggestion]:
+    for p in await db.latest_sent(channel_id, 30):
+        s = build_suggestion(p)
+        if s:
+            return s
+    return None

app/tgutil.py

@@ -0,0 +1,370 @@
+"""Helpers around Telethon types: entity/button (de)serialisation, media info, raw edits, rights."""
+from __future__ import annotations
+
+import asyncio
+import base64
+import copy
+import html
+import logging
+from types import SimpleNamespace
+from typing import Any, Awaitable, Callable, Optional
+
+from telethon import errors, functions, types
+from telethon.extensions import BinaryReader
+
+log = logging.getLogger(__name__)
+esc = html.escape
+
+# ----------------------------------------------------------------------------- entities
+_SIMPLE = {
+    "bold": types.MessageEntityBold,
+    "italic": types.MessageEntityItalic,
+    "underline": types.MessageEntityUnderline,
+    "strike": types.MessageEntityStrike,
+    "code": types.MessageEntityCode,
+}
+if hasattr(types, "MessageEntitySpoiler"):
+    _SIMPLE["spoiler"] = types.MessageEntitySpoiler
+
+# entities Telegram works out by itself from the text - never stored
+_AUTO = tuple(
+    getattr(types, n)
+    for n in (
+        "MessageEntityUrl",
+        "MessageEntityMention",
+        "MessageEntityHashtag",
+        "MessageEntityCashtag",
+        "MessageEntityBotCommand",
+        "MessageEntityEmail",
+        "MessageEntityPhone",
+        "MessageEntityBankCard",
+    )
+    if hasattr(types, n)
+)
+
+
+def _b64(obj: Any) -> str:
+    return base64.b64encode(bytes(obj)).decode()
+
+
+def _unb64(data: str) -> Any:
+    return BinaryReader(base64.b64decode(data)).tgread_object()
+
+
+def ser_entities(entities) -> list:
+    """Message entities -> JSON-friendly list (UTF-16 offsets, as Telegram uses)."""
+    out: list = []
+    for e in entities or []:
+        if isinstance(e, _AUTO):
+            continue
+        done = False
+        for key, cls in _SIMPLE.items():
+            if isinstance(e, cls):
+                out.append({"k": key, "o": e.offset, "l": e.length})
+                done = True
+                break
+        if done:
+            continue
+        if isinstance(e, types.MessageEntityPre):
+            out.append({"k": "pre", "o": e.offset, "l": e.length, "g": e.language or ""})
+        elif isinstance(e, types.MessageEntityTextUrl):
+            out.append({"k": "url", "o": e.offset, "l": e.length, "u": e.url})
+        elif isinstance(e, types.MessageEntityBlockquote):
+            out.append({"k": "quote", "o": e.offset, "l": e.length, "c": bool(getattr(e, "collapsed", False))})
+        elif isinstance(e, types.MessageEntityCustomEmoji):
+            out.append({"k": "emoji", "o": e.offset, "l": e.length, "d": e.document_id})
+        else:
+            try:  # anything else is kept byte-for-byte
+                out.append({"k": "raw", "b": _b64(e)})
+            except Exception:  # pragma: no cover
+                log.warning("cannot store entity %r", e)
+    return out
+
+
+def de_entities(data) -> list:
+    out: list = []
+    for d in data or []:
+        k = d.get("k")
+        try:
+            if k in _SIMPLE:
+                out.append(_SIMPLE[k](d["o"], d["l"]))
+            elif k == "pre":
+                out.append(types.MessageEntityPre(d["o"], d["l"], d.get("g", "")))
+            elif k == "url":
+                out.append(types.MessageEntityTextUrl(d["o"], d["l"], d["u"]))
+            elif k == "quote":
+                out.append(types.MessageEntityBlockquote(d["o"], d["l"], True if d.get("c") else None))
+            elif k == "emoji":
+                out.append(types.MessageEntityCustomEmoji(d["o"], d["l"], d["d"]))
+            elif k == "raw":
+                out.append(_unb64(d["b"]))
+        except Exception:  # pragma: no cover
+            log.warning("bad stored entity %r", d)
+    return out
+
+
+# ------------------------------------------------------------------------------ buttons
+_LEGACY = hasattr(types, "KeyboardButtonUrl")  # Telethon < 1.45 used one class per button kind
+
+
+def button_url(b) -> Optional[str]:
+    """The link of a URL button, else None."""
+    if _LEGACY:
+        return b.url if isinstance(b, types.KeyboardButtonUrl) else None
+    t = getattr(b, "type", None)
+    return t.url if isinstance(t, types.InlineButtonTypeUrl) else None
+
+
+def is_callback_button(b) -> bool:
+    if _LEGACY:
+        return isinstance(b, types.KeyboardButtonCallback)
+    return isinstance(getattr(b, "type", None), types.InlineButtonTypeCallback)
+
+
+def make_url_button(text: str, url: str, style=None):
+    if _LEGACY:
+        return types.KeyboardButtonUrl(text, url)
+    return types.KeyboardButton(text=text, type=types.InlineButtonTypeUrl(url), style=style)
+
+
+def with_url(b, new_url: str):
+    """Copy of URL button `b` pointing to `new_url`; every other attribute (colour, ...) is kept."""
+    nb = copy.copy(b)
+    if _LEGACY:
+        nb.url = new_url
+    else:
+        nb.type = copy.copy(b.type)
+        nb.type.url = new_url
+    return nb
+
+
+def _style_dump(b) -> Optional[str]:
+    st = getattr(b, "style", None)
+    if st is None:
+        return None
+    if not any(getattr(st, f, None) for f in ("bg_primary", "bg_danger", "bg_success", "icon")):
+        return None
+    try:
+        return _b64(st)
+    except Exception:  # pragma: no cover
+        return None
+
+
+def ser_markup(markup) -> list:
+    """Inline keyboard -> rows of {'t': text, 'u': url} (URL buttons) or {'t', 'raw'} (any other kind)."""
+    rows: list = []
+    if isinstance(markup, types.ReplyInlineMarkup):
+        for row in markup.rows:
+            r = []
+            for b in row.buttons:
+                url = button_url(b)
+                if url is not None:
+                    item = {"t": b.text, "u": url}
+                    s = _style_dump(b)
+                    if s:
+                        item["s"] = s
+                    r.append(item)
+                else:
+                    try:
+                        r.append({"t": getattr(b, "text", ""), "raw": _b64(b)})
+                    except Exception:  # pragma: no cover
+                        log.warning("cannot store button %r", b)
+            if r:
+                rows.append(r)
+    return rows
+
+
+def build_markup(rows) -> Optional[types.ReplyInlineMarkup]:
+    out = []
+    for row in rows or []:
+        btns = []
+        for b in row:
+            if b.get("raw"):
+                try:
+                    btns.append(_unb64(b["raw"]))
+                except Exception:  # pragma: no cover
+                    continue
+            elif b.get("u"):
+                style = None
+                if b.get("s"):
+                    try:
+                        style = _unb64(b["s"])
+                    except Exception:  # pragma: no cover
+                        style = None
+                btns.append(make_url_button(b["t"], b["u"], style))
+        if btns:
+            out.append(types.KeyboardButtonRow(btns))
+    return types.ReplyInlineMarkup(out) if out else None
+
+
+def state_of(text, entities, markup, preview) -> dict:
+    """Snapshot used for the undo log."""
+    return {
+        "text": text or "",
+        "entities": ser_entities(entities),
+        "buttons": ser_markup(markup),
+        "preview": preview,  # True/False for text messages, None for media messages
+    }
+
+
+# --------------------------------------------------------------------------------- media
+def classify_media(m) -> Optional[str]:
+    """photo | video | animation | audio | document, or None (text / unsupported)."""
+    media = getattr(m, "media", None)
+    if isinstance(media, types.MessageMediaPhoto) and getattr(media, "photo", None):
+        return "photo"
+    if isinstance(media, types.MessageMediaDocument) and getattr(media, "document", None):
+        if m.gif:
+            return "animation"
+        if m.video:
+            return "video"
+        if m.audio:
+            return "audio"
+        if m.voice or m.video_note or m.sticker:
+            return None
+        return "document"
+    return None
+
+
+# Media is stored as the serialised Telegram media object ("tl:<base64>"). Telethon's Bot-API style
+# file_id helper cannot pack photos with the current Telegram schema, so we don't rely on it.
+_REF_PREFIX = "tl:"
+
+
+def media_ref(m) -> Optional[str]:
+    """A storable reference to the photo / document attached to message `m` (None if it has none)."""
+    media = getattr(m, "media", None)
+    if isinstance(media, (types.MessageMediaPhoto, types.MessageMediaDocument)):
+        try:
+            return _REF_PREFIX + _b64(media)
+        except Exception:  # pragma: no cover
+            log.warning("cannot store media reference", exc_info=True)
+    return None
+
+
+pack_file_id = media_ref  # older name, kept for the callers
+
+
+def media_from_ref(ref: str, *, blank_reference: bool = False):
+    """Rebuild the media object; `blank_reference` drops the (possibly expired) file reference."""
+    media = _unb64(ref[len(_REF_PREFIX):]) if ref.startswith(_REF_PREFIX) else None
+    if media is None:
+        raise ValueError("unknown media reference")
+    if blank_reference:
+        media = copy.copy(media)
+        inner = copy.copy(media.photo if isinstance(media, types.MessageMediaPhoto) else media.document)
+        inner.file_reference = b""
+        if isinstance(media, types.MessageMediaPhoto):
+            media.photo = inner
+        else:
+            media.document = inner
+    return media
+
+
+async def with_media(ref: str, call):
+    """call(media): first with the stored file reference, then (if Telegram says it expired) without it."""
+    try:
+        return await call(media_from_ref(ref))
+    except errors.RPCError as e:
+        if "FileReference" not in type(e).__name__ and type(e).__name__ != "MediaEmptyError":
+            raise
+        log.info("stored file reference rejected (%s) - retrying without it", type(e).__name__)
+        return await call(media_from_ref(ref, blank_reference=True))
+
+
+def media_info(m) -> tuple:
+    kind = classify_media(m)
+    return kind, (media_ref(m) if kind else None)
+
+
+def utf16_len(s: str) -> int:
+    return len(s.encode("utf-16-le")) // 2
+
+
+# --------------------------------------------------------------------------------- misc
+def peer_of(ch) -> types.InputPeerChannel:
+    return types.InputPeerChannel(ch.id, ch.access_hash)
+
+
+def post_link(ch, message_id: int) -> str:
+    if ch.username:
+        return f"https://t.me/{ch.username}/{message_id}"
+    return f"https://t.me/c/{ch.id}/{message_id}"
+
+
+def short(s: str, n: int) -> str:
+    s = " ".join((s or "").split())
+    return s if len(s) <= n else s[: n - 1] + "…"
+
+
+async def flood_retry(factory: Callable[[], Awaitable[Any]], tries: int = 4) -> Any:
+    for _ in range(tries):
+        try:
+            return await factory()
+        except errors.FloodWaitError as e:
+            wait = int(getattr(e, "seconds", 5)) + 1
+            log.warning("flood wait %ss", wait)
+            await asyncio.sleep(min(wait, 900))
+    return await factory()
+
+
+async def edit_raw(client, peer, message_id: int, *, text: Optional[str] = None, entities=None, markup=None, preview=None):
+    """messages.editMessage with every field explicit.
+
+    `markup=None` together with `text` removes the keyboard (that is how Telegram behaves);
+    a markup-only edit (text=None) leaves the text alone.
+    """
+    kw: dict = {"peer": peer, "id": message_id}
+    if markup is not None:
+        kw["reply_markup"] = markup
+    if text is not None:
+        kw["message"] = text
+        kw["entities"] = list(entities or [])
+        if preview is not None:
+            kw["no_webpage"] = not preview
+    return await client(functions.messages.EditMessageRequest(**kw))
+
+
+async def get_rights(client, ch):
+    """The bot's own admin rights in a channel, or None if Telegram won't tell us."""
+    try:
+        res = await client(
+            functions.channels.GetParticipantRequest(channel=peer_of(ch), participant=types.InputPeerSelf())
+        )
+    except Exception as e:
+        log.info("could not read own rights in %s: %s", ch.id, e)
+        return None
+    p = res.participant
+    if isinstance(p, (types.ChannelParticipantCreator, types.ChannelParticipantAdmin)):
+        r = getattr(p, "admin_rights", None)
+        creator = isinstance(p, types.ChannelParticipantCreator)
+
+        def has(name: str) -> bool:
+            return True if (creator and r is None) else bool(getattr(r, name, False))
+
+        return SimpleNamespace(
+            admin=True, post=has("post_messages"), edit=has("edit_messages"), delete=has("delete_messages")
+        )
+    return SimpleNamespace(admin=False, post=False, edit=False, delete=False)
+
+
+_HINTS = {
+    "ChatAdminRequiredError": "The bot needs admin rights in that channel (post / edit / delete messages).",
+    "MessageAuthorRequiredError": "Telegram wants the message author. Give the bot the 'Edit messages of others' right.",
+    "InlineBotRequiredError": "That post was sent through another bot's inline mode, so only that bot can edit it.",
+    "MessageEditTimeExpiredError": "Telegram no longer allows editing that message.",
+    "MessageIdInvalidError": "That message no longer exists in the channel.",
+    "ButtonUrlInvalidError": "Telegram rejected one of the button links.",
+    "ReplyMarkupInvalidError": "Telegram rejected the buttons.",
+    "ChatWriteForbiddenError": "The bot can't post in that channel - check its admin rights.",
+    "ChannelPrivateError": "The bot can't access that channel any more (removed or banned?).",
+    "UserBannedInChannelError": "The bot is banned in that channel.",
+    "FileReferenceExpiredError": "The saved media expired - send the media again.",
+    "MediaEmptyError": "Telegram could not use that media - send it again.",
+    "EntityBoundsInvalidError": "The text formatting doesn't fit the text.",
+}
+
+
+def explain_rpc(e: BaseException) -> str:
+    name = type(e).__name__
+    return f"Telegram refused ({name}). " + _HINTS.get(name, str(e)[:200])

app/ui.py

@@ -0,0 +1,107 @@
+"""Texts and inline keyboards for the post panel."""
+from __future__ import annotations
+
+from telethon import Button
+
+from .buttons import count, grid_label, missing_links
+from .tgutil import esc, post_link, short
+
+CANCEL = [[Button.inline("✖️ Cancel", "cx")]]
+KIND_ICON = {None: "📝", "photo": "🖼", "video": "🎬", "animation": "🎞", "audio": "🎵", "document": "📎"}
+KIND_NAME = {None: "text", "photo": "photo", "video": "video", "animation": "GIF", "audio": "audio", "document": "file"}
+
+
+def post_title(p) -> str:
+    for row in p.buttons or []:
+        for b in row:
+            if b.get("t"):
+                return b["t"]
+    text = (p.text or "").strip()
+    return text.splitlines()[0] if text else (KIND_NAME.get(p.media_kind) or "post")
+
+
+def post_label(p) -> str:
+    icon = "📝" if p.status == "draft" else "✅"
+    return f"{icon} #{p.id} {short(post_title(p), 34)}"
+
+
+def panel_text(p, ch, note=None) -> str:
+    state = "draft (not published yet)" if p.status == "draft" else "published"
+    lines = [f"<b>Post #{p.id}</b> · {state}", f"Channel: <b>{esc(ch.title)}</b>"]
+    if p.status == "sent" and p.message_id:
+        lines.append(f'<a href="{post_link(ch, p.message_id)}">Open in the channel</a>')
+    lines.append(f"Type: {KIND_ICON.get(p.media_kind, '📎')} {KIND_NAME.get(p.media_kind, p.media_kind)}")
+    n, miss = count(p.buttons), missing_links(p.buttons)
+    lines.append(f"Buttons: {n}" + (f" (⚠️ {miss} without a link)" if miss else ""))
+    if p.source == "adopted":
+        lines.append("<i>Picked up from the channel by /replace.</i>")
+    snippet = short(p.text or "", 220) or "(no text)"
+    lines += ["", f"<i>{esc(snippet)}</i>"]
+    if note:
+        lines += ["", note]
+    return "\n".join(lines)
+
+
+def panel_keyboard(p) -> list:
+    pid = p.id
+    kb = []
+    for r, row in enumerate(p.buttons or []):
+        kb.append([Button.inline(grid_label(b), f"bs:{pid}:{r}:{c}") for c, b in enumerate(row)])
+    kb.append(
+        [
+            Button.inline("✏️ Caption" if p.media_kind else "✏️ Text", f"et:{pid}"),
+            Button.inline("🖼 Media", f"em:{pid}"),
+        ]
+    )
+    row3 = [Button.inline("➕ Button", f"ba:{pid}"), Button.inline("📋 Set buttons", f"bp:{pid}")]
+    if p.buttons:
+        row3.append(Button.inline("🧹 Clear", f"bc:{pid}"))
+    kb.append(row3)
+    extra = []
+    if not p.media_kind:
+        extra.append(Button.inline(f"🔗 Link preview: {'on' if p.link_preview else 'off'}", f"lp:{pid}"))
+    if p.media_kind and p.status == "draft":
+        extra.append(Button.inline("🚫 Remove media", f"rm:{pid}"))
+    if extra:
+        kb.append(extra)
+    if p.status == "draft":
+        kb.append([Button.inline("👁 Preview", f"pv:{pid}"), Button.inline("🚀 Publish", f"pb:{pid}")])
+        kb.append([Button.inline("🗑 Discard", f"dl:{pid}"), Button.inline("📚 My posts", "pc:d:0")])
+    else:
+        kb.append([Button.inline("👁 Preview", f"pv:{pid}"), Button.inline("🗑 Delete", f"dl:{pid}")])
+        kb.append([Button.inline("📚 My posts", f"pc:{p.channel_id}:0")])
+    return kb
+
+
+def button_text(p, r: int, c: int) -> str:
+    b = p.buttons[r][c]
+    if b.get("raw"):
+        return (
+            f"🔒 <b>Button from another bot</b> (row {r + 1}, position {c + 1})\n"
+            f"Text: <code>{esc(b.get('t') or '')}</code>\n"
+            "Buttons like reactions only work with the bot that made them, so you can move or delete it, "
+            "but not edit it."
+        )
+    return (
+        f"🔘 <b>Button</b> (row {r + 1}, position {c + 1})\n"
+        f"Text: <code>{esc(b.get('t') or '')}</code>\n"
+        f"Link: <code>{esc(b.get('u') or '- none yet -')}</code>"
+    )
+
+
+def button_keyboard(p, r: int, c: int) -> list:
+    pid, at = p.id, f"{p.id}:{r}:{c}"
+    b = p.buttons[r][c]
+    kb = []
+    if not b.get("raw"):
+        kb.append([Button.inline("✏️ Change text", f"bt:{at}"), Button.inline("🔗 Change link", f"bu:{at}")])
+    kb.append(
+        [
+            Button.inline("⬅️", f"bm:{at}:l"),
+            Button.inline("⬆️", f"bm:{at}:u"),
+            Button.inline("⬇️", f"bm:{at}:d"),
+            Button.inline("➡️", f"bm:{at}:r"),
+        ]
+    )
+    kb.append([Button.inline("🗑 Delete", f"bd:{at}"), Button.inline("🔙 Back", f"po:{pid}")])
+    return kb

assets/rasengan.mp4

@@ -1,3 +0,0 @@
-version https://git-lfs.github.com/spec/v1
-oid sha256:b01eaeae25d0a50f6052d422aac6c14a6a2d848abe0cd20209b909e3b9f950b6
-size 3470021

bot.py

@@ -0,0 +1,88 @@
+"""Channel Post Bot - entry point.  Run:  python bot.py"""
+from __future__ import annotations
+
+import asyncio
+import logging
+import os
+
+from telethon import TelegramClient, functions, types
+from telethon.sessions import StringSession
+
+from app.common import Ctx
+from app.config import Config, load_config
+from app.db import Database
+from app.handlers import basic, channels, create, posts, replace
+from app.health import start_health_server
+
+log = logging.getLogger("bot")
+
+COMMANDS = [
+    ("new", "Create a post"),
+    ("posts", "My posts and drafts"),
+    ("addchannel", "Register a channel"),
+    ("channels", "List channels"),
+    ("replace", "Swap a username in links (owner)"),
+    ("undo", "Undo the last replace (owner)"),
+    ("testedit", "Test editing one post (owner)"),
+    ("export", "Backup as JSON (owner)"),
+    ("cancel", "Cancel what I'm doing"),
+    ("help", "Show help"),
+]
+
+
+def build_client(cfg: Config) -> TelegramClient:
+    if cfg.session_string:
+        session = StringSession(cfg.session_string)
+    else:
+        os.makedirs(os.path.dirname(cfg.session_path) or ".", exist_ok=True)
+        session = cfg.session_path
+    client = TelegramClient(session, cfg.api_id, cfg.api_hash)
+    client.parse_mode = "html"
+    return client
+
+
+def register_all(ctx: Ctx) -> None:
+    for module in (basic, channels, create, posts, replace):
+        module.register(ctx)
+
+
+async def set_commands(client: TelegramClient) -> None:
+    try:
+        await client(
+            functions.bots.SetBotCommandsRequest(
+                scope=types.BotCommandScopeDefault(),
+                lang_code="",
+                commands=[types.BotCommand(command=c, description=d) for c, d in COMMANDS],
+            )
+        )
+    except Exception as e:  # cosmetic only
+        log.warning("could not set the command menu: %s", e)
+
+
+async def main() -> None:
+    cfg = load_config()
+    logging.basicConfig(level=cfg.log_level, format="%(asctime)s %(levelname)s %(name)s: %(message)s")
+    logging.getLogger("telethon").setLevel(logging.WARNING)
+
+    db = Database(cfg.database_url, cfg.db_pool)
+    await db.init()
+    client = build_client(cfg)
+    ctx = Ctx(cfg=cfg, db=db, client=client)
+    register_all(ctx)
+    try:
+        await client.start(bot_token=cfg.bot_token)
+        me = await client.get_me()
+        log.info("Logged in as @%s (owners: %s)", me.username, ", ".join(map(str, sorted(cfg.owners))))
+        await set_commands(client)
+        if cfg.port:
+            await start_health_server(cfg.port)
+        await client.run_until_disconnected()
+    finally:
+        await db.close()
+
+
+if __name__ == "__main__":
+    try:
+        asyncio.run(main())
+    except KeyboardInterrupt:
+        pass

index.html

@@ -1,190 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Rasengan</title>
-
-  <script src="https://cdn.jsdelivr.net/npm/@mediapipe/camera_utils/camera_utils.js" crossorigin="anonymous"></script>
-  <script src="https://cdn.jsdelivr.net/npm/@mediapipe/hands/hands.js" crossorigin="anonymous"></script>
-  <script src="https://cdn.jsdelivr.net/npm/@mediapipe/drawing_utils/drawing_utils.js" crossorigin="anonymous"></script>
-
-  <style>
-    html, body { margin: 0; height: 100%; background: #000; overflow: hidden; font-family: system-ui, sans-serif; }
-
-    .layer {
-      position: fixed; inset: 0;
-      width: 100vw; height: 100vh;
-      object-fit: cover;
-      transform: scaleX(-1);
-    }
-    #cam      { z-index: 0; }
-    #skeleton { z-index: 2; pointer-events: none; }
-
-    .vignette {
-      position: fixed; inset: 0;
-      background: radial-gradient(ellipse at center, transparent 35%, rgba(0,0,0,0.55) 100%);
-      pointer-events: none; z-index: 4;
-    }
-
-    .rasengan {
-      position: fixed; top: 0; left: 0;
-      width: 1500px; height: auto;
-      transform: translate(-50%, -50%);
-      pointer-events: none;
-      mix-blend-mode: screen;
-      opacity: 0;
-      will-change: opacity, left, top;
-      z-index: 10;
-    }
-
-    #hint {
-      position: fixed; bottom: 16px; left: 50%;
-      transform: translateX(-50%);
-      color: #cfe9ff; font-size: 14px; letter-spacing: 0.04em;
-      background: rgba(0,0,0,0.45);
-      padding: 6px 12px; border-radius: 999px;
-      z-index: 6; pointer-events: none;
-    }
-  </style>
-</head>
-<body>
-  <video  id="cam"      class="layer" autoplay playsinline muted></video>
-  <canvas id="skeleton" class="layer"></canvas>
-  <div    class="vignette"></div>
-
-  <video class="rasengan" data-slot="0" src="assets/rasengan.mp4" muted autoplay loop playsinline preload="auto"></video>
-  <video class="rasengan" data-slot="1" src="assets/rasengan.mp4" muted autoplay loop playsinline preload="auto"></video>
-
-  <script>
-    const camVideo = document.getElementById('cam');
-    const canvas   = document.getElementById('skeleton');
-    const pen      = canvas.getContext('2d');
-    const orbs     = Array.from(document.querySelectorAll('.rasengan'));
-
-    // Two distinct palettes so each hand's skeleton is obviously different,
-    // and bones vs joints inside one hand are also different colors.
-    const PALETTES = {
-      Left:  { bone: '#ff8a3d', joint: '#fff36a', glow: '#ff5e1a' }, // warm — Naruto orange
-      Right: { bone: '#62f0ff', joint: '#ff66e0', glow: '#1aa6ff' }  // cool — chakra blue
-    };
-
-    // Per-hand fade-in / fade-out state for the orbs.
-    const orbState = [
-      { charge: 0, wasOpen: false },
-      { charge: 0, wasOpen: false }
-    ];
-
-    const FINGER_TIPS     = [8, 12, 16, 20];
-    const FINGER_KNUCKLES = [6, 10, 14, 18];
-
-    function isPalmOpen(lm) {
-      const wrist = lm[0];
-      let extended = 0;
-      for (let i = 0; i < FINGER_TIPS.length; i++) {
-        const tip = lm[FINGER_TIPS[i]];
-        const knk = lm[FINGER_KNUCKLES[i]];
-        const dTip = Math.hypot(tip.x - wrist.x, tip.y - wrist.y);
-        const dKnk = Math.hypot(knk.x - wrist.x, knk.y - wrist.y);
-        if (dTip > dKnk) extended++;
-      }
-      return extended >= 3;
-    }
-
-    // Draw bones in one color, joints in another, with a colored glow,
-    // so the tracking sticks visibly follow each finger.
-    function paintSkeleton(lm, colors) {
-      pen.save();
-      pen.shadowBlur  = 18;
-      pen.shadowColor = colors.glow;
-      drawConnectors(pen, lm, HAND_CONNECTIONS, { color: colors.bone, lineWidth: 3 });
-      pen.restore();
-
-      pen.save();
-      pen.shadowBlur  = 10;
-      pen.shadowColor = colors.glow;
-      pen.fillStyle   = colors.joint;
-      for (const p of lm) {
-        pen.beginPath();
-        pen.arc(p.x * canvas.width, p.y * canvas.height, 3.5, 0, Math.PI * 2);
-        pen.fill();
-      }
-      pen.restore();
-    }
-
-    function placeOrb(slot, lm, charge) {
-      const wrist  = lm[0];
-      const midKnk = lm[9];
-
-      const cx = (wrist.x + midKnk.x) / 2;
-      const cy = (wrist.y + midKnk.y) / 2;
-      const handSize = Math.hypot(midKnk.x - wrist.x, midKnk.y - wrist.y);
-      const lift = handSize * 1.8;
-
-      const orb = orbs[slot];
-      orb.style.left    = `${(1 - cx) * window.innerWidth}px`;
-      orb.style.top     = `${(cy - lift) * window.innerHeight}px`;
-      orb.style.opacity = charge.toFixed(3);
-    }
-
-    function onResults(res) {
-      canvas.width  = camVideo.videoWidth  || canvas.clientWidth;
-      canvas.height = camVideo.videoHeight || canvas.clientHeight;
-      pen.clearRect(0, 0, canvas.width, canvas.height);
-
-      const seen = [false, false];
-
-      if (res.multiHandLandmarks && res.multiHandedness) {
-        res.multiHandLandmarks.forEach((lm, i) => {
-          const label  = res.multiHandedness[i].label; // "Left" | "Right"
-          const slot   = label === 'Right' ? 1 : 0;
-          const colors = PALETTES[label] || PALETTES.Left;
-          seen[slot]   = true;
-
-          paintSkeleton(lm, colors);
-
-          const open = isPalmOpen(lm);
-          const st   = orbState[slot];
-          st.charge  = Math.max(0, Math.min(1, st.charge + (open ? 0.06 : -0.18)));
-
-          if (open && !st.wasOpen) {
-            const v = orbs[slot];
-            v.currentTime = 0;
-            v.play().catch(err => console.warn('rasengan play failed', err));
-          }
-          st.wasOpen = open;
-
-          if (st.charge > 0.01) placeOrb(slot, lm, st.charge);
-          else orbs[slot].style.opacity = 0;
-        });
-      }
-
-      // Decay any hand we didn't see this frame.
-      for (let i = 0; i < 2; i++) {
-        if (seen[i]) continue;
-        orbState[i].charge  = Math.max(0, orbState[i].charge - 0.18);
-        orbState[i].wasOpen = false;
-        orbs[i].style.opacity = orbState[i].charge.toFixed(3);
-      }
-    }
-
-    const hands = new Hands({
-      locateFile: f => `https://cdn.jsdelivr.net/npm/@mediapipe/hands/${f}`
-    });
-    hands.setOptions({
-      maxNumHands: 2,
-      modelComplexity: 1,
-      minDetectionConfidence: 0.65,
-      minTrackingConfidence:  0.65
-    });
-    hands.onResults(onResults);
-
-    const camera = new Camera(camVideo, {
-      onFrame: async () => { await hands.send({ image: camVideo }); },
-      width:  1280,
-      height: 720
-    });
-    camera.start();
-  </script>
-</body>
-</html>

make_session.py

@@ -0,0 +1,17 @@
+"""Prints a SESSION_STRING for hosts that lose local files on restart:  python make_session.py"""
+import asyncio
+
+from telethon import TelegramClient
+from telethon.sessions import StringSession
+
+from app.config import load_config
+
+
+async def main() -> None:
+    cfg = load_config()
+    async with TelegramClient(StringSession(), cfg.api_id, cfg.api_hash) as client:
+        await client.start(bot_token=cfg.bot_token)
+        print("\nSESSION_STRING=" + client.session.save())
+
+
+asyncio.run(main())

requirements-dev.txt

@@ -0,0 +1,3 @@
+-r requirements.txt
+pytest>=8
+pyflakes

requirements.txt

@@ -0,0 +1,5 @@
+telethon>=1.45,<1.46
+SQLAlchemy[asyncio]>=2.0.30,<2.1
+asyncpg>=0.29
+aiosqlite>=0.20
+python-dotenv>=1.0

tests/dbutil.py

@@ -0,0 +1,16 @@
+"""Tests run on SQLite by default; set TEST_DATABASE_URL to run the very same tests on PostgreSQL."""
+import os
+
+from app.db import Base, Database
+
+
+def db_url_for(tmp_path, name="t.db"):
+    return os.getenv("TEST_DATABASE_URL") or f"sqlite+aiosqlite:///{tmp_path}/{name}"
+
+
+async def fresh_db(url: str) -> Database:
+    db = Database(url)
+    async with db.engine.begin() as conn:
+        await conn.run_sync(Base.metadata.drop_all)
+    await db.init()
+    return db

tests/fakes.py

@@ -0,0 +1,65 @@
+"""Tiny in-memory stand-ins for Telethon, good enough to exercise the engine offline."""
+import datetime
+from types import SimpleNamespace
+
+from telethon import errors, functions, types
+from telethon.tl.custom import Message
+
+from app.tgutil import make_url_button
+
+
+def make_msg(i, text="", entities=None, markup=None, out=False, media=None):
+    return Message(
+        id=i,
+        peer_id=types.PeerChannel(1),
+        date=datetime.datetime.now(datetime.timezone.utc),
+        message=text,
+        out=out,
+        entities=entities,
+        reply_markup=markup,
+        media=media,
+    )
+
+
+def url_btn(text, url):
+    return make_url_button(text, url)
+
+
+def cb_btn(text, data):
+    return types.KeyboardButton(text=text, type=types.InlineButtonTypeCallback(data))
+
+
+def markup(*rows):
+    return types.ReplyInlineMarkup([types.KeyboardButtonRow(list(r)) for r in rows])
+
+
+class FakeClient:
+    def __init__(self, msgs, pts=None):
+        self.msgs = dict(msgs)
+        self.pts = pts
+        self.edits = []
+        self.fail = {}  # message id -> exception to raise on edit
+
+    async def __call__(self, req):
+        if isinstance(req, functions.channels.GetFullChannelRequest):
+            return SimpleNamespace(full_chat=SimpleNamespace(pts=self.pts))
+        if isinstance(req, functions.messages.EditMessageRequest):
+            if req.id in self.fail:
+                raise self.fail[req.id]
+            m = self.msgs[req.id]
+            self.edits.append(req)
+            if req.message is not None:
+                m.message = req.message
+                m.entities = list(req.entities or [])
+                m.reply_markup = req.reply_markup  # like Telegram: no markup sent -> keyboard removed
+            elif req.reply_markup is not None:
+                m.reply_markup = req.reply_markup
+            return None
+        raise NotImplementedError(type(req))
+
+    async def get_messages(self, peer, ids=None):
+        return [self.msgs.get(i) for i in ids]
+
+
+def rpc(name):
+    return getattr(errors, name)(request=None)

tests/harness.py

@@ -0,0 +1,172 @@
+"""Drive the real handlers with fake events and a fake Telegram client (no network)."""
+import datetime
+import itertools
+import re
+from types import SimpleNamespace
+
+from telethon import events, functions, types
+
+from app.common import Ctx
+from app.config import Config
+from app.db import Database
+
+from bot import register_all
+
+from .dbutil import db_url_for
+
+
+class FakeSent:
+    """A message the bot sent to the user (so `.edit()` works on it)."""
+
+    def __init__(self, out, text, buttons):
+        self.out, self.text, self.buttons = out, text, buttons
+
+    async def edit(self, text=None, buttons=None, **kw):
+        if text is not None:
+            self.text = text
+        self.buttons = buttons
+        self.out.log.append(("edit", self.text, buttons))
+
+
+class FakeEvent:
+    def __init__(self, uid, out, text="", data=None, message=None):
+        self.sender_id, self.out = uid, out
+        self.is_private = True
+        self.is_channel = False
+        self.is_group = False
+        self.raw_text = text
+        self.text = text
+        self.message = message or SimpleNamespace(
+            raw_text=text, entities=[], media=None, grouped_id=None, forward=None
+        )
+        self.pattern_match = None
+        self._is_callback = data is not None
+        if data is not None:
+            self.data = data.encode()
+
+    async def respond(self, text=None, buttons=None, file=None, **kw):
+        self.out.log.append(("say", text, buttons))
+        return FakeSent(self.out, text, buttons)
+
+    async def edit(self, text=None, buttons=None, **kw):
+        self.out.log.append(("edit", text, buttons))
+
+    async def answer(self, *a, **kw):
+        return None
+
+    async def get_input_chat(self):
+        return types.InputPeerUser(self.sender_id, 0)
+
+
+class Outbox:
+    def __init__(self):
+        self.log = []
+
+    @property
+    def last_text(self):
+        return self.log[-1][1] if self.log else None
+
+    def last_buttons(self):
+        b = self.log[-1][2]
+        return [[getattr(x, "text", None) for x in row] for row in (b or [])]
+
+    def callback_data(self, label_part):
+        """Data of the first inline button (in the last message) whose label contains `label_part`."""
+        for row in self.log[-1][2] or []:
+            for btn in row:
+                if label_part in btn.text:
+                    t = btn.type if hasattr(btn, "type") else btn
+                    return t.data.decode()
+        raise AssertionError(f"no button {label_part!r} in {self.last_buttons()}")
+
+
+class FakeTG:
+    def __init__(self):
+        self.handlers = []
+        self.sent = []
+        self.edits = []
+        self.deleted = []
+        self.ids = itertools.count(100)
+        self.parse_mode = "html"
+
+    def on(self, builder):
+        def deco(fn):
+            self.handlers.append((builder, fn))
+            return fn
+
+        return deco
+
+    async def send_message(self, peer, message="", **kw):
+        m = SimpleNamespace(id=next(self.ids))
+        self.sent.append(("text", peer, message, kw))
+        return m
+
+    async def send_file(self, peer, file, **kw):
+        m = SimpleNamespace(id=next(self.ids))
+        self.sent.append(("file", peer, file, kw))
+        return m
+
+    async def edit_message(self, peer, message, **kw):
+        self.edits.append(("edit_message", message, kw))
+
+    async def delete_messages(self, peer, ids, **kw):
+        self.deleted.append(list(ids))
+        return [SimpleNamespace(pts_count=len(ids))]
+
+    async def __call__(self, req):
+        if isinstance(req, functions.messages.EditMessageRequest):
+            self.edits.append(("raw", req.id, req))
+            return None
+        if isinstance(req, functions.channels.GetParticipantRequest):
+            rights = types.ChatAdminRights(post_messages=True, edit_messages=True, delete_messages=True)
+            return SimpleNamespace(participant=types.ChannelParticipantAdmin(
+                user_id=1, promoted_by=1, date=datetime.datetime.now(datetime.timezone.utc), admin_rights=rights))
+        raise NotImplementedError(type(req))
+
+
+class App:
+    def __init__(self, tmp_path, owner=1):
+        cfg = Config(api_id=1, api_hash="x", bot_token="1:x", owners=frozenset({owner}), admins=frozenset(),
+                     database_url=db_url_for(tmp_path, "h.db"), db_pool="null", session_path="x", session_string="",
+                     edit_delay=0.3, replace_typed_links=True, port=0, log_level="INFO")
+        self.tg = FakeTG()
+        self.db = Database(cfg.database_url)
+        self.ctx = Ctx(cfg=cfg, db=self.db, client=self.tg)
+        self.uid = owner
+        self.out = Outbox()
+
+    async def start(self):
+        from app.db import Base
+
+        async with self.db.engine.begin() as conn:
+            await conn.run_sync(Base.metadata.drop_all)
+        await self.db.init()
+        register_all(self.ctx)
+
+    async def text(self, s, message=None):
+        ev = FakeEvent(self.uid, self.out, s, message=message)
+        for builder, cb in self.tg.handlers:
+            if not isinstance(builder, events.NewMessage):
+                continue
+            if builder.pattern:
+                m = builder.pattern(s)
+                if not m:
+                    continue
+                ev.pattern_match = m
+            if builder.func and not builder.func(ev):
+                continue
+            await cb(ev)
+        return ev
+
+    async def press(self, data):
+        ev = FakeEvent(self.uid, self.out, data=data)
+        for builder, cb in self.tg.handlers:
+            if isinstance(builder, events.CallbackQuery):
+                await cb(ev)
+        return ev
+
+
+def norm(s):
+    import html
+
+    return html.unescape(re.sub(r"<[^>]+>", "", s or ""))

tests/test_engine.py

@@ -0,0 +1,146 @@
+import asyncio
+from telethon import types
+
+from app.linkswap import compute_message_changes
+from app.replace_engine import ScanOptions, apply_channel, scan_channel, undo_batch
+from app.tgutil import button_url, is_callback_button
+
+from .dbutil import fresh_db, db_url_for
+from .fakes import FakeClient, cb_btn, make_msg, markup, rpc, url_btn
+
+OLD = "https://t.me/bharath?start=BBB"
+
+
+def build():
+    text3 = "Hi 😀 https://t.me/bharath?start=CCC done"
+    msgs = {
+        1: make_msg(1, "Get it now", [types.MessageEntityTextUrl(0, 3, "https://t.me/Bharath?start=AAA")]),
+        2: make_msg(
+            2,
+            "Episodes",
+            markup=markup([url_btn("Ep 1-20", OLD), cb_btn("👍 3", b"r1")], [url_btn("Join", "https://t.me/other")]),
+            out=True,
+        ),
+        3: make_msg(3, text3, [types.MessageEntityBold(37, 4)]),
+        4: make_msg(4, "see https://t.me/bharath_bot?start=1"),
+        5: make_msg(5, "https://t.me/bharath/123"),
+        7: types.MessageEmpty(id=7, peer_id=types.PeerChannel(1)),
+    }
+    return msgs, text3
+
+
+async def setup(tmp_path, msgs, pts=8):
+    db = await fresh_db(db_url_for(tmp_path))
+    await db.save_channel(1, 5, "Test", None, 99)
+    ch = await db.get_channel(1)
+    return db, ch, FakeClient(msgs, pts=pts)
+
+
+def test_scan_apply_undo(tmp_path):
+    async def run():
+        msgs, text3 = build()
+        db, ch, client = await setup(tmp_path, msgs)
+        opts = ScanOptions("bharath", "goku")
+        scan = await scan_channel(client, ch, opts, can_edit_others=True)
+        assert set(scan.infos) == {1, 2, 3}
+        assert scan.skipped_post_links == 1  # t.me/bharath/123 is a channel post, not a bot link
+        assert scan.foreign == 2 and scan.infos[2].mine and scan.infos[2].callbacks
+
+        await db.create_batch("b1", "bharath", "goku", 99)
+        res = await apply_channel(client, db, scan, opts, "b1", 99, edit_delay=0)
+        assert (res.edited, res.failed) == (3, [])
+
+        # hyperlink: only the username changed
+        assert msgs[1].entities[0].url == "https://t.me/goku?start=AAA"
+        # buttons: URL swapped, reaction button + other link untouched, text untouched
+        rows = msgs[2].reply_markup.rows
+        assert button_url(rows[0].buttons[0]) == "https://t.me/goku?start=BBB"
+        assert is_callback_button(rows[0].buttons[1])
+        assert button_url(rows[1].buttons[0]) == "https://t.me/other"
+        assert msgs[2].message == "Episodes"
+        # typed link after an emoji: text swapped and the following entity moved with it
+        assert msgs[3].message == "Hi 😀 https://t.me/goku?start=CCC done"
+        assert (msgs[3].entities[0].offset, msgs[3].entities[0].length) == (34, 4)
+        # untouched
+        assert msgs[4].message == "see https://t.me/bharath_bot?start=1"
+        assert msgs[5].message == "https://t.me/bharath/123"
+
+        # adopted into the database
+        p = await db.find_by_message(1, 3)
+        assert p.source == "adopted" and "goku" in p.text
+        assert (await db.find_by_message(1, 2)).buttons[0][0]["u"].endswith("goku?start=BBB")
+
+        # undo restores everything
+        ures = await undo_batch(client, db, "b1", edit_delay=0)
+        assert ures.restored == 3 and not ures.failed
+        assert msgs[1].entities[0].url == "https://t.me/Bharath?start=AAA"
+        assert msgs[3].message == text3 and msgs[3].entities[0].offset == 37
+        assert button_url(msgs[2].reply_markup.rows[0].buttons[0]) == OLD
+        assert is_callback_button(msgs[2].reply_markup.rows[0].buttons[1])
+        assert (await db.last_batch()) is None  # batch marked as undone
+        await db.close()
+
+    asyncio.run(run())
+
+
+def test_only_own_posts_without_edit_right(tmp_path):
+    async def run():
+        msgs, _ = build()
+        db, ch, client = await setup(tmp_path, msgs)
+        opts = ScanOptions("bharath", "goku")
+        scan = await scan_channel(client, ch, opts, can_edit_others=False)
+        assert set(scan.infos) == {2} and scan.not_editable == 2
+        await db.create_batch("b2", "bharath", "goku", 99)
+        res = await apply_channel(client, db, scan, opts, "b2", 99, edit_delay=0)
+        assert res.edited == 1 and len(client.edits) == 1
+        await db.close()
+
+    asyncio.run(run())
+
+
+def test_failures_are_reported_not_fatal(tmp_path):
+    async def run():
+        msgs, _ = build()
+        db, ch, client = await setup(tmp_path, msgs)
+        client.fail[1] = rpc("MessageAuthorRequiredError")
+        opts = ScanOptions("bharath", "goku")
+        scan = await scan_channel(client, ch, opts)
+        await db.create_batch("b3", "bharath", "goku", 99)
+        res = await apply_channel(client, db, scan, opts, "b3", 99, edit_delay=0)
+        assert res.edited == 2 and res.failed == [(1, "MessageAuthorRequiredError")]
+        await db.close()
+
+    asyncio.run(run())
+
+
+def test_scan_without_counter_falls_back_to_probing(tmp_path):
+    async def run():
+        msgs, _ = build()
+        db, ch, client = await setup(tmp_path, msgs, pts=None)
+        scan = await scan_channel(client, ch, ScanOptions("bharath", "goku"))
+        assert set(scan.infos) == {1, 2, 3}
+        await db.close()
+
+    asyncio.run(run())
+
+
+def test_post_links_can_be_included():
+    m = make_msg(5, "https://t.me/bharath/123")
+    assert compute_message_changes(m, "bharath", "goku")[0] is None
+    ch, skipped = compute_message_changes(m, "bharath", "goku", include_posts=True)
+    assert ch.new_text == "https://t.me/goku/123"
+
+
+def test_tg_scheme_and_hyperlink_and_text_flags():
+    m = make_msg(
+        6,
+        "open tg://resolve?domain=bharath&start=x",
+        [types.MessageEntityTextUrl(0, 4, "tg://resolve?domain=Bharath&start=y")],
+    )
+    ch, _ = compute_message_changes(m, "bharath", "goku")
+    assert ch.new_text == "open tg://resolve?domain=goku&start=x"
+    assert ch.new_entities[0].url == "tg://resolve?domain=goku&start=y"
+    assert ch.n_typed == 1 and ch.n_links == 1
+
+    ch2, _ = compute_message_changes(m, "bharath", "goku", include_typed=False)
+    assert ch2.new_text == m.message and ch2.n_typed == 0

tests/test_flows.py

@@ -0,0 +1,147 @@
+import asyncio
+
+from app.tgutil import button_url
+from .harness import App, norm
+
+SEEDED = [[{"t": "Download Episodes 01 to 20", "u": "https://t.me/oldbot?start=aaa"}]]
+
+
+async def make_app(tmp_path):
+    app = App(tmp_path)
+    await app.start()
+    await app.db.save_channel(1, 5, "Anime Channel", "animech", 1)
+    return app
+
+
+def sent_markup(app, i=-1):
+    return app.tg.sent[i][3]["buttons"]
+
+
+def test_suggestion_flow_end_to_end(tmp_path):
+    async def run():
+        app = await make_app(tmp_path)
+        await app.db.create_post(channel_id=1, message_id=10, status="sent", source="bot", text="Click the button below to download 👇", entities=[], buttons=SEEDED)
+
+        await app.text("/new")
+        assert "Suggestion" in app.out.last_text and "Download Episodes 21 to 40" in app.out.last_text
+        await app.press(app.out.callback_data("Use suggestion"))
+        assert "Send the link" in app.out.last_text
+        await app.text("https://t.me/newbot?start=zzz")
+        assert "Ready" in app.out.last_text and "Publish" in str(app.out.last_buttons())
+
+        pid = int(app.out.callback_data("Publish").split(":")[1])
+        await app.press(f"pb:{pid}")
+        assert "Publish this post" in app.out.last_text
+        await app.press(f"pby:{pid}")
+        assert "Published" in app.out.last_text
+        kind, peer, msg, kw = app.tg.sent[-1]
+        assert msg == "Click the button below to download 👇"
+        btn = sent_markup(app).rows[0].buttons[0]
+        assert btn.text == "Download Episodes 21 to 40" and button_url(btn) == "https://t.me/newbot?start=zzz"
+        p = await app.db.get_post(pid)
+        assert p.status == "sent" and p.message_id == 100
+
+        # the next suggestion moves on again
+        await app.text("/new")
+        assert "Download Episodes 41 to 60" in app.out.last_text
+        await app.db.close()
+
+    asyncio.run(run())
+
+
+def test_customize_new_post_with_buttons_and_edit_live(tmp_path):
+    async def run():
+        app = await make_app(tmp_path)
+        await app.text("/new")  # nothing to suggest yet -> asks for the post
+        assert "Send the post now" in app.out.last_text
+        await app.text("Hello *world*")  # stored literally (no markdown parsing)
+        assert "buttons" in app.out.last_text.lower()
+        await app.text("Get it - https://t.me/bot?start=1 | Join - t.me/animech\nMirror - https://example.com/x")
+        pid = int(app.out.callback_data("Publish").split(":")[1])
+        post = await app.db.get_post(pid)
+        assert post.text == "Hello *world*" and [len(r) for r in post.buttons] == [2, 1]
+        await app.press(f"pb:{pid}")
+        await app.press(f"pby:{pid}")
+        assert app.tg.sent[-1][2] == "Hello *world*"
+
+        # edit the live post: change a button's text, then its link
+        await app.press(f"bs:{pid}:0:0")
+        assert "Get it" in app.out.last_text
+        await app.press(f"bt:{pid}:0:0")
+        await app.text("Download now")
+        await app.press(f"bu:{pid}:0:0")
+        await app.text("https://t.me/goku?start=1")
+        last_edit = app.tg.edits[-1][2]
+        assert last_edit.message == "Hello *world*"
+        b = last_edit.reply_markup.rows[0].buttons[0]
+        assert b.text == "Download now" and button_url(b) == "https://t.me/goku?start=1"
+
+        # reorder: move the first button right, then down into its own row
+        await app.press(f"bm:{pid}:0:0:r")
+        rows = (await app.db.get_post(pid)).buttons
+        assert [b["t"] for b in rows[0]] == ["Join", "Download now"]
+        await app.press(f"bm:{pid}:0:1:d")
+        rows = (await app.db.get_post(pid)).buttons
+        assert [[b["t"] for b in r] for r in rows] == [["Join"], ["Mirror", "Download now"]]
+
+        # delete a button
+        await app.press(f"bd:{pid}:0:0")
+        assert [[b["t"] for b in r] for r in (await app.db.get_post(pid)).buttons] == [["Mirror", "Download now"]]
+        live = app.tg.edits[-1][2].reply_markup
+        assert [b.text for b in live.rows[0].buttons] == ["Mirror", "Download now"]
+
+        # edit text of the live post keeps the buttons
+        await app.press(f"et:{pid}")
+        await app.text("New text")
+        req = app.tg.edits[-1][2]
+        assert req.message == "New text" and len(req.reply_markup.rows[0].buttons) == 2
+
+        # delete from the channel
+        await app.press(f"dly:{pid}:a")
+        assert app.tg.deleted == [[100]] and await app.db.get_post(pid) is None
+        await app.db.close()
+
+    asyncio.run(run())
+
+
+def test_bad_input_and_permissions(tmp_path):
+    async def run():
+        app = await make_app(tmp_path)
+        await app.text("/new")
+        await app.text("A post")
+        await app.text("this has no link")
+        assert "No link found" in norm(app.out.last_text)
+        await app.text("/skip")
+        pid = int(app.out.callback_data("Publish").split(":")[1])
+        await app.press(f"ba:{pid}")
+        await app.text("Only text")  # asks for the link next
+        assert "send the link" in app.out.last_text.lower()
+        await app.text("not a link")
+        assert "doesn't look like a link" in norm(app.out.last_text)
+        await app.text("https://t.me/bot?start=q")
+        assert (await app.db.get_post(pid)).buttons[0][0]["u"] == "https://t.me/bot?start=q"
+
+        # a non-owner is rejected everywhere
+        app.uid = 999
+        await app.text("/replace @a @b")
+        assert "private" in app.out.last_text.lower()
+        await app.db.close()
+
+    asyncio.run(run())
+
+
+def test_drafts_list_and_discard(tmp_path):
+    async def run():
+        app = await make_app(tmp_path)
+        await app.text("/new")
+        await app.text("draft one")
+        await app.text("/skip")
+        await app.text("/posts")
+        await app.press("pc:d:0")
+        assert "Drafts" in app.out.last_text and "draft one" in str(app.out.last_buttons())
+        pid = int(app.out.callback_data("draft one").split(":")[1])
+        await app.press(f"dly:{pid}:b")
+        assert await app.db.get_post(pid) is None
+        await app.db.close()
+
+    asyncio.run(run())

tests/test_units.py

@@ -0,0 +1,248 @@
+import asyncio
+import datetime
+from types import SimpleNamespace
+
+import pytest
+from telethon import TelegramClient, types
+from telethon.sessions import MemorySession
+
+from app import buttons as B
+from app.common import UserError
+from app.db import normalize_db_url
+from app.handlers.channels import parse_channel_ref
+from app.handlers.panel import extract_content
+from app.handlers.replace import parse_replace_args
+from app.linkswap import apply_span_replacements, classify_url, normalize_username, swap_url
+from app.suggest import advance_plain, build_suggestion
+from app.tgutil import (
+    build_markup,
+    button_url,
+    classify_media,
+    de_entities,
+    is_callback_button,
+    media_from_ref,
+    pack_file_id,
+    ser_entities,
+    ser_markup,
+    utf16_len,
+)
+
+from .fakes import cb_btn, make_msg, markup, url_btn
+from .harness import App
+
+NOW = datetime.datetime.now(datetime.timezone.utc)
+
+
+def photo_msg(caption="cap", entities=None):
+    photo = types.Photo(1, 2, b"ref", NOW, [types.PhotoSize("x", 100, 100, 999)], 2)
+    return make_msg(5, caption, entities, media=types.MessageMediaPhoto(photo=photo))
+
+
+def video_msg(gif=False):
+    attrs = [types.DocumentAttributeVideo(3.0, 100, 100)]
+    if gif:
+        attrs.append(types.DocumentAttributeAnimated())
+    doc = types.Document(9, 8, b"ref", NOW, "video/mp4", 1000, 2, attrs)
+    return make_msg(6, "v", media=types.MessageMediaDocument(document=doc))
+
+
+# ------------------------------------------------------------------ entities / markup
+def test_entity_roundtrip_keeps_formatting_and_unknown_types():
+    ents = [
+        types.MessageEntityBold(0, 3),
+        types.MessageEntityTextUrl(4, 2, "https://t.me/x?start=1"),
+        types.MessageEntityPre(7, 3, "python"),
+        types.MessageEntitySpoiler(11, 2),
+        types.MessageEntityUrl(14, 5),  # auto entity: not stored
+        types.MessageEntityFormattedDate(20, 4, NOW),  # unknown to us: kept byte-for-byte
+    ]
+    data = ser_entities(ents)
+    assert [d["k"] for d in data] == ["bold", "url", "pre", "spoiler", "raw"]
+    back = de_entities(data)
+    assert [type(e).__name__ for e in back] == [
+        "MessageEntityBold", "MessageEntityTextUrl", "MessageEntityPre", "MessageEntitySpoiler", "MessageEntityFormattedDate"
+    ]
+    assert back[1].url == "https://t.me/x?start=1" and back[2].language == "python"
+
+
+def test_markup_roundtrip_keeps_other_bots_buttons_and_colours():
+    style = types.KeyboardButtonStyle(bg_success=True)
+    coloured = types.KeyboardButton(text="Go", type=types.InlineButtonTypeUrl("https://t.me/x"), style=style)
+    mk = markup([coloured, cb_btn("👍 3", b"react:1")], [url_btn("Two", "https://t.me/y")])
+    rows = ser_markup(mk)
+    assert rows[0][0]["u"] == "https://t.me/x" and "s" in rows[0][0]
+    assert rows[0][1]["raw"] and rows[1][0]["u"] == "https://t.me/y"
+    rebuilt = build_markup(rows)
+    b0, b1 = rebuilt.rows[0].buttons
+    assert button_url(b0) == "https://t.me/x" and b0.style.bg_success
+    assert is_callback_button(b1) and b1.type.data == b"react:1"
+
+
+def test_utf16_len_counts_emoji_as_two():
+    assert utf16_len("a😀") == 3
+
+
+def test_apply_span_replacements_shifts_entities():
+    ents = [types.MessageEntityBold(14, 3), types.MessageEntityItalic(0, 4), types.MessageEntityCode(5, 13)]
+    text, out = apply_span_replacements("open t.me/abc now", ents, [(10, 13, "longer")])
+    assert text == "open t.me/longer now"
+    assert (out[0].offset, out[0].length) == (17, 3)  # after the change: moved by +3
+    assert (out[1].offset, out[1].length) == (0, 4)  # before it: untouched
+    assert (out[2].offset, out[2].length) == (5, 16)  # spanning it: grows
+
+
+# -------------------------------------------------------------------- media handling
+def test_extract_content_photo_video_gif_and_text():
+    c = extract_content(photo_msg("hello", [types.MessageEntityBold(0, 5)]))
+    assert c["media_kind"] == "photo" and c["text"] == "hello" and c["entities"][0]["k"] == "bold"
+    assert c["media_file_id"]
+    assert classify_media(video_msg()) == "video" and classify_media(video_msg(gif=True)) == "animation"
+    t = extract_content(make_msg(1, "plain"))
+    assert t["media_kind"] is None and t["media_file_id"] is None
+    with pytest.raises(UserError):
+        extract_content(make_msg(1, "   "))
+    with pytest.raises(UserError):
+        extract_content(photo_msg("x" * 1025))
+    with pytest.raises(UserError):  # a poll can't be used in a post
+        extract_content(make_msg(1, "q", media=types.MessageMediaPoll(types.Poll(1, [], types.TextWithEntities("q", []), None), types.PollResults())))
+
+
+def test_link_preview_photo_is_not_mistaken_for_a_photo_post():
+    page = types.WebPage(id=1, url="https://x.com", display_url="x.com", hash=0, photo=types.Photo(1, 2, b"r", NOW, [], 2))
+    m = make_msg(2, "look https://x.com", media=types.MessageMediaWebPage(webpage=page))
+    assert classify_media(m) is None
+    assert extract_content(m)["media_kind"] is None
+
+
+def test_bot_file_id_can_be_reused_when_sending():
+    m = photo_msg()
+    fid = pack_file_id(m)
+    assert fid.startswith("tl:")
+
+    async def go(blank):
+        client = TelegramClient(MemorySession(), 1, "h")
+        # what send_file / edit_message do with the media object
+        _, media, _ = await client._file_to_media(media_from_ref(fid, blank_reference=blank))
+        return media
+
+    assert isinstance(asyncio.run(go(False)), types.InputMediaPhoto)
+    blank = asyncio.run(go(True))
+    assert blank.id.file_reference == b"" and blank.id.id == 1 and blank.id.access_hash == 2
+    doc_ref = pack_file_id(video_msg())
+    assert media_from_ref(doc_ref).document.id == 9
+
+
+# --------------------------------------------------------------------------- parsing
+def test_button_parsing_and_limits():
+    assert B.parse_buttons_text("A - t.me/x | B - https://y.com/?a=1\nC — https://z.com") == [
+        [{"t": "A", "u": "https://t.me/x"}, {"t": "B", "u": "https://y.com/?a=1"}],
+        [{"t": "C", "u": "https://z.com"}],
+    ]
+    for bad in ("no link here", "- https://x.com", "A - htp://x"):
+        with pytest.raises(ValueError):
+            B.parse_buttons_text(bad)
+    with pytest.raises(ValueError):
+        B.parse_buttons_text(" | ".join(f"b{i} - https://x.com/{i}" for i in range(9)))
+
+
+def test_move_button_edges():
+    rows = [[{"t": "a", "u": "u"}, {"t": "b", "u": "u"}], [{"t": "c", "u": "u"}]]
+    assert B.move_button(rows, 0, 0, "l")[0] == rows and B.move_button(rows, 0, 0, "u")[0] == rows
+    r, nr, nc = B.move_button(rows, 1, 0, "u")  # keeps its column when it can
+    assert [[b["t"] for b in x] for x in r] == [["c", "a", "b"]] and (nr, nc) == (0, 0)
+    r, nr, nc = B.move_button(rows, 0, 1, "d")
+    assert [[b["t"] for b in x] for x in r] == [["a"], ["c", "b"]] and (nr, nc) == (1, 1)
+    r, nr, nc = B.move_button([[{"t": "a"}, {"t": "b"}]], 0, 1, "d")  # last row with company -> new row
+    assert [[b["t"] for b in x] for x in r] == [["a"], ["b"]] and (nr, nc) == (1, 0)
+    assert B.delete_button([[{"t": "a"}]], 0, 0) == []
+
+
+def test_replace_args_and_refs():
+    old, new, f = parse_replace_args("@Bharath goku --last 50 --posts --channel @ch")
+    assert (old, new, f["last"], f["posts"], f["channel"]) == ("Bharath", "goku", 50, True, "@ch")
+    for bad in ("@a", "@a @a", "@a @b --wat", "@a @b --last x", "@a b!d"):
+        with pytest.raises(ValueError):
+            parse_replace_args(bad)
+    assert normalize_username("https://t.me/foo_bar/") == "foo_bar" and normalize_username("@x y") is None
+    assert parse_channel_ref("@animech") == "animech" and parse_channel_ref("https://t.me/c/123456/7") == 123456
+    assert parse_channel_ref("-1001234567890") == 1234567890 and parse_channel_ref("???") is None
+
+
+def test_url_helpers():
+    assert classify_url("https://T.me/Bharath?start=x", "bharath") == "link"
+    assert classify_url("https://t.me/bharath/12", "bharath") == "post"
+    assert classify_url("https://t.me/bharath_bot", "bharath") is None
+    assert classify_url("https://example.com/bharath", "bharath") is None
+    assert swap_url("http://telegram.me/Bharath?start=A_b-C", "bharath", "goku") == "http://telegram.me/goku?start=A_b-C"
+
+
+def test_db_url_normalisation():
+    url, args = normalize_db_url("postgres://u:p@ep-x-pooler.eu.neon.tech/db?sslmode=require&channel_binding=require")
+    assert url.startswith("postgresql+asyncpg://") and "sslmode" not in url and "channel_binding" not in url
+    assert args == {"ssl": True, "statement_cache_size": 0} and "prepared_statement_cache_size=0" in url
+    assert normalize_db_url("sqlite:///data/x.db")[0] == "sqlite+aiosqlite:///data/x.db"
+
+
+# ------------------------------------------------------------------------ suggestions
+def test_suggestion_details():
+    post = SimpleNamespace(
+        id=1, text="Episodes 01 to 20 are here 👇", entities=[{"k": "bold", "o": 0, "l": 8}],
+        buttons=[[{"t": "Download Episodes 01 to 20", "u": "https://x"}, {"t": "Join", "u": "https://j"}],
+                 [{"t": "👍 2", "raw": "AAAA"}]],
+        media_kind="photo", media_file_id="FID",
+    )
+    s = build_suggestion(post)
+    assert s.text == "Episodes 21 to 40 are here 👇" and s.entities[0]["l"] == 8
+    assert s.buttons == [[{"t": "Download Episodes 21 to 40", "u": None}, {"t": "Join", "u": "https://j"}]]
+    assert s.pending == [(0, 0)] and s.media_file_id == "FID"  # reactions from another bot are dropped
+    assert advance_plain("no numbers") is None
+    assert build_suggestion(SimpleNamespace(id=2, text="", entities=[], buttons=[[{"t": "Join", "u": "u"}]], media_kind=None, media_file_id=None)) is None
+
+
+# ------------------------------------------------------- channel registration handler
+def test_add_channel_by_forward_and_rights(tmp_path):
+    async def run():
+        app = App(tmp_path)
+        await app.start()
+        ch = types.Channel(id=77, title="Fwd Channel", photo=types.ChatPhotoEmpty(), date=NOW, broadcast=True,
+                           access_hash=1234, username="fwdch")
+        msg = SimpleNamespace(raw_text="", entities=[], media=None, grouped_id=None, forward=SimpleNamespace(chat=ch))
+        await app.text("/addchannel")
+        await app.text("", message=msg)
+        assert "Added" in app.out.last_text
+        saved = await app.db.get_channel(77)
+        assert (saved.access_hash, saved.username, saved.active) == (1234, "fwdch", True)
+
+        # a "min" channel without access details is refused with an explanation
+        mini = types.Channel(id=78, title="Min", photo=types.ChatPhotoEmpty(), date=NOW, broadcast=True, min=True)
+        await app.text("/addchannel")
+        await app.text("", message=SimpleNamespace(raw_text="", entities=[], media=None, grouped_id=None, forward=SimpleNamespace(chat=mini)))
+        assert "access details" in app.out.last_text
+        assert await app.db.get_channel(78) is None
+        await app.db.close()
+
+    asyncio.run(run())
+
+
+def test_media_post_publish_uses_send_file_and_caption_edit(tmp_path):
+    async def run():
+        app = App(tmp_path)
+        await app.start()
+        await app.db.save_channel(1, 5, "C", None, 1)
+        p = await app.db.create_post(channel_id=1, status="draft", source="bot", text="cap", entities=[], media_kind="photo",
+                                     media_file_id=pack_file_id(photo_msg()), buttons=[[{"t": "Go", "u": "https://x.com"}]], created_by=1)
+        await app.press(f"pby:{p.id}")
+        kind, peer, file, kw = app.tg.sent[-1]
+        assert kind == "file" and isinstance(file, types.MessageMediaPhoto) and kw["caption"] == "cap"
+        # editing the caption of the live media post goes through messages.editMessage
+        await app.press(f"et:{p.id}")
+        await app.text("new caption")
+        req = app.tg.edits[-1][2]
+        assert req.message == "new caption" and len(req.reply_markup.rows[0].buttons) == 1
+        # replacing the media uses Telegram's file-edit path
+        await app.press(f"em:{p.id}")
+        await app.text("nope")
+        assert "Send a photo" in app.out.last_text
+        await app.db.close()
+
+    asyncio.run(run())

tests/test_wire.py

@@ -0,0 +1,166 @@
+"""Check that every Telegram call the bot makes builds a valid, serialisable MTProto request.
+
+Telethon's network layer is replaced by a function that captures the request (after Telethon has
+resolved it) and serialises it, so wrong argument types or shapes fail here instead of in production.
+"""
+import asyncio
+import datetime
+
+import pytest
+from telethon import TelegramClient, functions, types, utils
+from telethon.sessions import MemorySession
+
+from app.common import push_edit, send_post
+from app.tgutil import (
+    build_markup,
+    de_entities,
+    edit_raw,
+    media_from_ref,
+    media_ref,
+    peer_of,
+    ser_entities,
+)
+from app.ui import button_keyboard, panel_keyboard
+
+from .fakes import make_msg
+
+NOW = datetime.datetime.now(datetime.timezone.utc)
+CH = type("Ch", (), {"id": 1234, "access_hash": 5678})()
+
+
+class Captured(Exception):
+    def __init__(self, req):
+        self.req = req
+
+
+@pytest.fixture()
+def client(monkeypatch):
+    async def fake_call(self, request, ordered=False, flood_sleep_threshold=None):
+        reqs = list(request) if isinstance(request, (list, tuple)) else [request]
+        for r in reqs:
+            if hasattr(r, "resolve"):
+                await r.resolve(self, utils)
+            assert isinstance(bytes(r), bytes)  # must serialise
+        raise Captured(reqs[0])
+
+    monkeypatch.setattr(TelegramClient, "__call__", fake_call)
+    return TelegramClient(MemorySession(), 1, "h")
+
+
+def capture(coro):
+    async def go():
+        try:
+            await coro
+        except Captured as c:
+            return c.req
+        raise AssertionError("no request was made")
+
+    return asyncio.run(go())
+
+
+def post(**kw):
+    base = dict(
+        id=1, message_id=50, text="Hello 😀", entities=[{"k": "bold", "o": 0, "l": 5}, {"k": "url", "o": 6, "l": 2, "u": "https://x.com"}],
+        media_kind=None, media_file_id=None, link_preview=False,
+        buttons=[[{"t": "Go", "u": "https://t.me/bot?start=a"}, {"t": "Two", "u": "https://t.me/bot?start=b"}]],
+    )
+    base.update(kw)
+    return type("P", (), base)()
+
+
+def photo_ref():
+    photo = types.Photo(11, 22, b"ref", NOW, [types.PhotoSize("x", 100, 100, 999)], 2)
+    return media_ref(make_msg(1, "", media=types.MessageMediaPhoto(photo=photo)))
+
+
+def test_send_text_post(client):
+    req = capture(send_post(client, peer_of(CH), post()))
+    assert isinstance(req, functions.messages.SendMessageRequest)
+    assert req.message == "Hello 😀" and req.no_webpage is True
+    assert [type(e).__name__ for e in req.entities] == ["MessageEntityBold", "MessageEntityTextUrl"]
+    assert req.reply_markup.rows[0].buttons[1].text == "Two"
+    assert isinstance(req.peer, types.InputPeerChannel)
+
+
+def test_send_media_post_with_and_without_file_reference(client):
+    ref = photo_ref()
+    req = capture(send_post(client, peer_of(CH), post(media_kind="photo", media_file_id=ref)))
+    assert isinstance(req, functions.messages.SendMediaRequest)
+    assert isinstance(req.media, types.InputMediaPhoto) and req.media.id.id == 11 and req.media.id.file_reference == b"ref"
+    assert req.message == "Hello 😀" and req.reply_markup is not None
+
+    async def blank():
+        c = client
+        _, media, _ = await c._file_to_media(media_from_ref(ref, blank_reference=True))
+        return media
+
+    assert asyncio.run(blank()).id.file_reference == b""
+
+
+def test_raw_edits(client):
+    p = post()
+    req = capture(push_edit(client, CH, p))
+    assert isinstance(req, functions.messages.EditMessageRequest)
+    assert req.id == 50 and req.message == "Hello 😀" and req.no_webpage is True and req.reply_markup is not None
+    # no buttons -> no reply_markup (Telegram then removes the keyboard)
+    req = capture(push_edit(client, CH, post(buttons=[])))
+    assert req.reply_markup is None and req.message == "Hello 😀"
+    # markup-only edit leaves the text alone
+    req = capture(edit_raw(client, peer_of(CH), 9, markup=build_markup([[{"t": "A", "u": "https://a.com"}]])))
+    assert req.message is None and req.entities is None and req.reply_markup.rows[0].buttons[0].text == "A"
+
+
+def test_media_replacement_edit(client):
+    ref = photo_ref()
+    req = capture(push_edit(client, CH, post(media_kind="photo", media_file_id=ref), replace_media=True))
+    assert isinstance(req, functions.messages.EditMessageRequest)
+    assert isinstance(req.media, types.InputMediaPhoto) and req.message == "Hello 😀"
+    assert req.reply_markup is not None
+
+
+def test_reads_deletes_and_rights_requests(client):
+    peer = peer_of(CH)
+    req = capture(client.get_messages(peer, ids=[1, 2, 3]))
+    assert isinstance(req, functions.channels.GetMessagesRequest)
+    assert isinstance(req.channel, types.InputChannel) and [i.id for i in req.id] == [1, 2, 3]
+    req = capture(client.delete_messages(peer, [7]))
+    assert isinstance(req, functions.channels.DeleteMessagesRequest) and req.id == [7]
+    req = capture(client(functions.channels.GetFullChannelRequest(peer)))
+    assert isinstance(req.channel, types.InputChannel)
+    req = capture(client(functions.channels.GetParticipantRequest(channel=peer, participant=types.InputPeerSelf())))
+    assert isinstance(req.participant, types.InputPeerSelf)
+
+
+def test_entities_with_every_stored_kind_serialise():
+    ents = [
+        types.MessageEntityBold(0, 1), types.MessageEntityItalic(1, 1), types.MessageEntityUnderline(2, 1),
+        types.MessageEntityStrike(3, 1), types.MessageEntitySpoiler(4, 1), types.MessageEntityCode(5, 1),
+        types.MessageEntityPre(6, 1, "py"), types.MessageEntityTextUrl(7, 1, "https://x.com"),
+        types.MessageEntityBlockquote(8, 1, True), types.MessageEntityCustomEmoji(9, 2, 123456789),
+    ]
+    back = de_entities(ser_entities(ents))
+    assert [type(e) for e in back] == [type(e) for e in ents]
+    assert back[8].collapsed is True
+    for e in back:
+        bytes(e)
+
+
+def test_ui_keyboards_serialise(client):
+    p = post()
+    p.status, p.channel_id, p.source = "draft", 1, "bot"
+    p.buttons = [[{"t": "A", "u": "https://a.com"}, {"t": "⚠️ no link", "u": None}], [{"t": "👍", "raw": ""}]]
+    for kb in (panel_keyboard(p), button_keyboard(p, 0, 0), button_keyboard(p, 1, 0)):
+        mk = client.build_reply_markup(kb)
+        assert isinstance(bytes(mk), bytes)
+    for label_row in panel_keyboard(p):
+        for b in label_row:
+            assert len(b.type.data) <= 64  # Telegram's limit for callback data
+
+
+def test_button_callback_data_fits_for_large_ids():
+    p = post(id=2_000_000_000)
+    p.status, p.channel_id, p.source = "sent", -1, "bot"
+    p.buttons = [[{"t": "x", "u": "https://a.com"}] * 8] * 12
+    for row in panel_keyboard(p):
+        for b in row:
+            assert len(b.type.data) <= 64