tlgr-cli 2.0.1__py3-none-any.whl

tlgr/data/parity_waivers.toml

@@ -0,0 +1,90 @@
+# Catalog ids that are knowingly not covered, and why.
+#
+# Until PR-12 this file was a backlog: a waiver was a promise with a PR number
+# on it, so `tlgr agent parity` could report "uncovered, waived until PR-9"
+# instead of silently shrinking the denominator. Every one of those promises
+# has now been kept, and what is left is a different thing entirely — nine ids
+# that this build genuinely cannot cover, each naming the reason.
+#
+# **There are no blanket waivers.** No domain is waived, and no id is waived
+# because "another PR owns it": that sentence has no meaning once every PR has
+# landed. `kind` names which of the four permanent reasons applies:
+#
+#   layer-gap        the method arrived in an MTProto layer newer than the one
+#                    Telethon 1.44 speaks; the command is registered and exits
+#                    13 (NOT_SUPPORTED) with the method named
+#   absent-method    the method exists in the layer but Telethon 1.44 ships no
+#                    request class for it; the flag that needs it exits 13
+#   prohibited       tlgr will not do it (spending money, deanonymising)
+#   not-applicable   there is nothing for a CLI to do
+#
+# The gate in tests/test_parity.py enforces all of that: it refuses a domain
+# waiver, refuses an unknown `kind`, refuses a waiver for an id that is in
+# fact covered, and refuses a waiver whose reason does not name a method.
+#
+# Regenerate the catalog index with: python tools/prune_catalog.py
+
+[meta]
+catalog_version = "2026-09-02"
+# The plan's last PR. Kept as a record of when the backlog emptied.
+final_pr = 12
+
+# ---------------------------------------------------------------------------
+# Layer 229: `ephemeral.*` and the rich-message keyboard.
+#
+# Telethon 1.44 speaks layer 227 and has no TL classes for these, so tlgr has
+# no request to send. Each command is registered and refuses with exit 13
+# naming the method, because a command that is absent teaches an agent
+# nothing while a command that refuses teaches it exactly what is missing.
+# ---------------------------------------------------------------------------
+
+[[id]]
+id = "bots.ephemeral-command-send"
+kind = "layer-gap"
+reason = "`ephemeral.sendMessage` is a layer-229 method; `bot command send --ephemeral` is registered and exits 13."
+
+[[id]]
+id = "bots.ephemeral-callback-press"
+kind = "layer-gap"
+reason = "`ephemeral.getCallbackAnswer` is a layer-229 method; `bot press --ephemeral` is registered and exits 13."
+
+[[id]]
+id = "bots.ephemeral-message-send"
+kind = "layer-gap"
+reason = "`ephemeral.sendMessage` is a layer-229 method; the command is registered and exits 13."
+
+[[id]]
+id = "bots.ephemeral-report"
+kind = "layer-gap"
+reason = "`ephemeral.report` is a layer-229 method; the command is registered and exits 13."
+
+[[id]]
+id = "bots.welcome-messages-view"
+kind = "layer-gap"
+reason = "`ephemeral.getWelcomeMessages` is a layer-229 method; `chat welcome list` is registered and exits 13."
+
+[[id]]
+id = "bots.welcome-messages-manage"
+kind = "layer-gap"
+reason = "`ephemeral.sendMessage` / `ephemeral.editMessage` are layer-229 methods; `chat welcome set` is registered and exits 13."
+
+[[id]]
+id = "bots.rich-message-buttons"
+kind = "layer-gap"
+reason = "The rich-message keyboard constructors arrived in layer 229; tlgr refuses rather than guessing at a constructor id."
+
+# ---------------------------------------------------------------------------
+# Methods this Telethon has no request class for. The layer has them; the
+# pinned library does not, so the *flag* that needs one refuses while the rest
+# of its command still works.
+# ---------------------------------------------------------------------------
+
+[[id]]
+id = "bots.chat-join-webview"
+kind = "absent-method"
+reason = "`messages.requestChatJoinWebView` is absent from Telethon 1.44; `webapp open --join-query-id` is registered and exits 13."
+
+[[id]]
+id = "gift.can-send"
+kind = "absent-method"
+reason = "`payments.canSendStarGift` is absent from Telethon 1.44; `gift catalog --until` is registered and exits 13, and the rest of the catalogue still reads."

tlgr/filters/__init__.py

@@ -0,0 +1,42 @@
+"""Registry-based message and event filtering.
+
+Every filter is a plain function registered via ``@register_filter``.
+Filters receive an :class:`~tlgr.gateway.event.Event` and a config value
+(whatever was in the YAML) and return ``(matched: bool, reason: str)``.
+
+Modules in this package auto-register their filters on import.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import Any
+
+from tlgr.gateway.event import Event
+
+FilterFunc = Callable[[Event, Any], tuple[bool, str]]
+
+_REGISTRY: dict[str, FilterFunc] = {}
+
+
+def register_filter(name: str):
+    """Decorator that registers a filter function under *name*."""
+
+    def decorator(func: FilterFunc) -> FilterFunc:
+        _REGISTRY[name] = func
+        return func
+
+    return decorator
+
+
+def get_filter(name: str) -> FilterFunc | None:
+    return _REGISTRY.get(name)
+
+
+def list_filters() -> list[str]:
+    return list(_REGISTRY.keys())
+
+
+# Import built-in filter modules so they self-register.
+from tlgr.filters import content, context, message, temporal, user  # noqa: E402, F401
+from tlgr.filters.compose import evaluate, parse_filter_config  # noqa: E402, F401

tlgr/filters/compose.py

@@ -0,0 +1,121 @@
+"""Filter composition engine — AND / OR / NOT trees.
+
+YAML filter blocks are parsed into a tree of :class:`FilterNode` objects
+and evaluated recursively against an :class:`~tlgr.gateway.event.Event`.
+
+Top-level keys are AND'd.  ``any_of`` gives OR, ``none_of`` gives NOT.
+Both ``any_of`` and ``none_of`` accept a list of filter-sets that can
+themselves contain ``any_of`` / ``none_of``, enabling arbitrary nesting.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any
+
+from tlgr.gateway.event import Event
+
+
+class Op(Enum):
+    AND = "and"
+    OR = "or"
+    NOT = "not"
+    LEAF = "leaf"
+
+
+@dataclass
+class FilterNode:
+    op: Op
+    children: list[FilterNode] = field(default_factory=list)
+    filter_name: str = ""
+    filter_value: Any = None
+
+    def __repr__(self) -> str:
+        if self.op is Op.LEAF:
+            return f"Leaf({self.filter_name}={self.filter_value!r})"
+        return f"{self.op.value.upper()}({self.children})"
+
+
+_COMPOSITION_KEYS = {"any_of", "none_of"}
+
+
+def parse_filter_config(raw: dict[str, Any] | None) -> FilterNode | None:
+    """Turn a YAML filter block into a :class:`FilterNode` tree."""
+    if not raw:
+        return None
+
+    and_children: list[FilterNode] = []
+
+    for key, value in raw.items():
+        if key == "any_of":
+            or_children = _parse_child_list(value)
+            if or_children:
+                and_children.append(FilterNode(op=Op.OR, children=or_children))
+        elif key == "none_of":
+            or_children = _parse_child_list(value)
+            if or_children:
+                inner = FilterNode(op=Op.OR, children=or_children)
+                and_children.append(FilterNode(op=Op.NOT, children=[inner]))
+        else:
+            and_children.append(FilterNode(op=Op.LEAF, filter_name=key, filter_value=value))
+
+    if not and_children:
+        return None
+    if len(and_children) == 1:
+        return and_children[0]
+    return FilterNode(op=Op.AND, children=and_children)
+
+
+def _parse_child_list(items: list[dict[str, Any]] | Any) -> list[FilterNode]:
+    """Parse a list of filter-set dicts (used inside ``any_of`` / ``none_of``)."""
+    if not isinstance(items, list):
+        return []
+    nodes: list[FilterNode] = []
+    for item in items:
+        if isinstance(item, dict):
+            child = parse_filter_config(item)
+            if child is not None:
+                nodes.append(child)
+    return nodes
+
+
+def evaluate(node: FilterNode | None, event: Event) -> tuple[bool, str]:
+    """Recursively evaluate *node* against *event*.
+
+    Returns ``(passed, reason)`` just like individual filters.
+    """
+    if node is None:
+        return True, "no filters"
+
+    if node.op is Op.LEAF:
+        from tlgr.filters import get_filter
+
+        func = get_filter(node.filter_name)
+        if func is None:
+            return False, f"unknown filter: {node.filter_name}"
+        return func(event, node.filter_value)
+
+    if node.op is Op.AND:
+        for child in node.children:
+            ok, reason = evaluate(child, event)
+            if not ok:
+                return False, reason
+        return True, "all passed"
+
+    if node.op is Op.OR:
+        reasons: list[str] = []
+        for child in node.children:
+            ok, reason = evaluate(child, event)
+            if ok:
+                return True, reason
+            reasons.append(reason)
+        return False, f"none matched: {'; '.join(reasons)}"
+
+    if node.op is Op.NOT:
+        ok, reason = evaluate(node.children[0], event)
+        if ok:
+            return False, f"excluded: {reason}"
+        return True, "not-match passed"
+
+    return False, "invalid node"

tlgr/filters/content.py

@@ -0,0 +1,85 @@
+"""Content-based filters — keyword matching, regex, links."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from tlgr.filters import register_filter
+from tlgr.gateway.event import Event
+
+
+def _text(event: Event) -> str:
+    if event.source == "telegram":
+        msg = event.raw.message
+        return (msg.text or getattr(msg, "message", "") or "").lower()
+    raw = event.raw
+    if isinstance(raw, dict):
+        return str(raw.get("text", "")).lower()
+    return ""
+
+
+@register_filter("contains")
+def filter_contains(event: Event, value: Any) -> tuple[bool, str]:
+    """All keywords must appear (AND).  Value: list[str]."""
+    text = _text(event)
+    keywords = value if isinstance(value, list) else [value]
+    for kw in keywords:
+        if str(kw).lower() not in text:
+            return False, f"missing keyword: {kw}"
+    return True, "all keywords found"
+
+
+@register_filter("contains_any")
+def filter_contains_any(event: Event, value: Any) -> tuple[bool, str]:
+    """At least one keyword must appear (OR).  Value: list[str]."""
+    text = _text(event)
+    keywords = value if isinstance(value, list) else [value]
+    if any(str(kw).lower() in text for kw in keywords):
+        return True, "keyword matched"
+    return False, "none of keywords found"
+
+
+@register_filter("excludes")
+def filter_excludes(event: Event, value: Any) -> tuple[bool, str]:
+    """No listed keyword may appear.  Value: list[str]."""
+    text = _text(event)
+    keywords = value if isinstance(value, list) else [value]
+    for kw in keywords:
+        if str(kw).lower() in text:
+            return False, f"excluded keyword: {kw}"
+    return True, "no excluded keywords"
+
+
+@register_filter("regex")
+def filter_regex(event: Event, value: Any) -> tuple[bool, str]:
+    """Text must match the regex pattern.  Value: str."""
+    if event.source == "telegram":
+        msg = event.raw.message
+        text = msg.text or getattr(msg, "message", "") or ""
+    elif isinstance(event.raw, dict):
+        text = str(event.raw.get("text", ""))
+    else:
+        text = ""
+    if re.search(str(value), text, re.IGNORECASE):
+        return True, "regex matched"
+    return False, "regex not matched"
+
+
+@register_filter("has_links")
+def filter_has_links(event: Event, value: Any) -> tuple[bool, str]:
+    """Message must (or must not) contain URL entities.  Value: bool."""
+    if event.source != "telegram":
+        return False, "has_links requires telegram source"
+    msg = event.raw.message
+    has = bool(
+        msg.entities
+        and any(
+            hasattr(e, "url")
+            or e.__class__.__name__ in ("MessageEntityUrl", "MessageEntityTextUrl")
+            for e in msg.entities
+        )
+    )
+    if has == bool(value):
+        return True, "links filter matched"
+    return False, "links filter"

tlgr/filters/context.py

@@ -0,0 +1,114 @@
+"""Event-context filters — chat type, direction, sender metadata."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+from tlgr.filters import register_filter
+from tlgr.gateway.event import Event
+
+
+def _tg_event(event: Event):
+    """Return the raw Telethon event, or *None* if the source is not Telegram."""
+    if event.source != "telegram":
+        return None
+    return event.raw
+
+
+@register_filter("chat_type")
+def filter_chat_type(event: Event, value: Any) -> tuple[bool, str]:
+    """Match chat type: private, group, supergroup, channel, bot."""
+    tg = _tg_event(event)
+    if tg is None:
+        return False, "chat_type requires telegram source"
+
+    expected = value if isinstance(value, list) else [value]
+
+    if tg.is_private:
+        actual = "private"
+    elif tg.is_group:
+        actual = "group"
+    elif tg.is_channel:
+        actual = "channel"
+    else:
+        actual = "unknown"
+
+    # Telethon doesn't expose supergroup directly on the event; check the chat entity.
+    if actual == "group" and hasattr(tg, "chat") and hasattr(tg.chat, "megagroup"):
+        if tg.chat.megagroup:
+            actual = "supergroup"
+
+    if actual in expected:
+        return True, f"chat_type={actual}"
+    return False, f"chat_type {actual} not in {expected}"
+
+
+@register_filter("chat_id")
+def filter_chat_id(event: Event, value: Any) -> tuple[bool, str]:
+    """Match by chat ID or @username.  Value may be a single ref or a list."""
+    tg = _tg_event(event)
+    if tg is None:
+        return False, "chat_id requires telegram source"
+
+    refs = value if isinstance(value, list) else [value]
+    chat_id = tg.chat_id
+
+    for ref in refs:
+        try:
+            if int(ref) == chat_id:
+                return True, f"chat_id matched {ref}"
+        except (ValueError, TypeError):
+            pass
+        # @username matching requires entity resolution at setup time;
+        # the gateway pre-resolves these into the filter value.
+        if isinstance(ref, str) and ref.startswith("@"):
+            continue
+
+    return False, f"chat_id {chat_id} not in {refs}"
+
+
+@register_filter("chat_title")
+def filter_chat_title(event: Event, value: Any) -> tuple[bool, str]:
+    """Regex match against the chat title."""
+    tg = _tg_event(event)
+    if tg is None:
+        return False, "chat_title requires telegram source"
+    title = getattr(tg.chat, "title", "") or ""
+    if re.search(str(value), title, re.IGNORECASE):
+        return True, "chat_title matched"
+    return False, f"chat_title '{title}' does not match '{value}'"
+
+
+@register_filter("is_incoming")
+def filter_is_incoming(event: Event, value: Any) -> tuple[bool, str]:
+    tg = _tg_event(event)
+    if tg is None:
+        return False, "is_incoming requires telegram source"
+    incoming = not tg.message.out
+    if incoming == bool(value):
+        return True, "direction matched"
+    return False, f"is_incoming={incoming}, expected {value}"
+
+
+@register_filter("sender_is_bot")
+def filter_sender_is_bot(event: Event, value: Any) -> tuple[bool, str]:
+    tg = _tg_event(event)
+    if tg is None:
+        return False, "sender_is_bot requires telegram source"
+    sender = tg.message.sender
+    is_bot = getattr(sender, "bot", False) if sender else False
+    if is_bot == bool(value):
+        return True, "bot check matched"
+    return False, f"sender_is_bot={is_bot}, expected {value}"
+
+
+@register_filter("sender_is_self")
+def filter_sender_is_self(event: Event, value: Any) -> tuple[bool, str]:
+    tg = _tg_event(event)
+    if tg is None:
+        return False, "sender_is_self requires telegram source"
+    is_self = tg.message.out
+    if is_self == bool(value):
+        return True, "self check matched"
+    return False, f"sender_is_self={is_self}, expected {value}"

tlgr/filters/message.py

@@ -0,0 +1,161 @@
+"""Message-attribute filters — media type, reply, forward status."""
+
+from __future__ import annotations
+
+from enum import Enum
+from typing import Any
+
+from tlgr.filters import register_filter
+from tlgr.gateway.event import Event
+
+
+class MessageType(Enum):
+    TEXT = "text"
+    PHOTO = "photo"
+    VIDEO = "video"
+    DOCUMENT = "document"
+    STICKER = "sticker"
+    VOICE = "voice"
+    VIDEO_NOTE = "video_note"
+    AUDIO = "audio"
+    POLL = "poll"
+    LOCATION = "location"
+    LIVE_LOCATION = "live_location"
+    CONTACT = "contact"
+    GAME = "game"
+    INVOICE = "invoice"
+    DICE = "dice"
+    GIF = "gif"
+    WEBPAGE = "webpage"
+    UNSUPPORTED = "unsupported"
+
+
+def detect_message_type(message) -> MessageType:
+    from telethon.tl.types import (
+        DocumentAttributeAnimated,
+        DocumentAttributeAudio,
+        DocumentAttributeSticker,
+        DocumentAttributeVideo,
+        MessageMediaContact,
+        MessageMediaDice,
+        MessageMediaDocument,
+        MessageMediaGame,
+        MessageMediaGeo,
+        MessageMediaGeoLive,
+        MessageMediaInvoice,
+        MessageMediaPhoto,
+        MessageMediaPoll,
+        MessageMediaWebPage,
+    )
+
+    if not message.media:
+        return MessageType.TEXT
+    media = message.media
+    if isinstance(media, MessageMediaPhoto):
+        return MessageType.PHOTO
+    if isinstance(media, MessageMediaPoll):
+        return MessageType.POLL
+    if isinstance(media, MessageMediaGeoLive):
+        return MessageType.LIVE_LOCATION
+    if isinstance(media, MessageMediaGeo):
+        return MessageType.LOCATION
+    if isinstance(media, MessageMediaContact):
+        return MessageType.CONTACT
+    if isinstance(media, MessageMediaGame):
+        return MessageType.GAME
+    if isinstance(media, MessageMediaInvoice):
+        return MessageType.INVOICE
+    if isinstance(media, MessageMediaDice):
+        return MessageType.DICE
+    if isinstance(media, MessageMediaWebPage):
+        return MessageType.WEBPAGE
+    if isinstance(media, MessageMediaDocument):
+        doc = media.document
+        if doc is None:
+            return MessageType.UNSUPPORTED
+        is_animated = False
+        for attr in doc.attributes:
+            if isinstance(attr, DocumentAttributeAnimated):
+                is_animated = True
+            if isinstance(attr, DocumentAttributeSticker):
+                return MessageType.STICKER
+            if isinstance(attr, DocumentAttributeVideo):
+                if attr.round_message:
+                    return MessageType.VIDEO_NOTE
+                if is_animated:
+                    return MessageType.GIF
+                return MessageType.VIDEO
+            if isinstance(attr, DocumentAttributeAudio):
+                if attr.voice:
+                    return MessageType.VOICE
+                return MessageType.AUDIO
+        if is_animated or (hasattr(doc, "mime_type") and doc.mime_type == "image/gif"):
+            return MessageType.GIF
+        return MessageType.DOCUMENT
+    return MessageType.UNSUPPORTED
+
+
+def is_forwardable(message) -> tuple[bool, str]:
+    """Quick sanity check used by the forward action."""
+    if message.action is not None:
+        return False, f"Service message: {type(message.action).__name__}"
+    if not message.text and not message.media:
+        return False, "Empty message"
+    if message.media:
+        if hasattr(message.media, "ttl_seconds") and message.media.ttl_seconds:
+            return False, "Self-destructing message"
+    return True, ""
+
+
+@register_filter("types")
+def filter_types(event: Event, value: Any) -> tuple[bool, str]:
+    """Message type must be in *value*.  Value: list[str]."""
+    if event.source != "telegram":
+        return False, "types requires telegram source"
+    mt = detect_message_type(event.raw.message)
+    allowed = value if isinstance(value, list) else [value]
+    if mt.value in allowed:
+        return True, f"type={mt.value}"
+    return False, f"type {mt.value} not in {allowed}"
+
+
+@register_filter("exclude_types")
+def filter_exclude_types(event: Event, value: Any) -> tuple[bool, str]:
+    """Message type must NOT be in *value*.  Value: list[str]."""
+    if event.source != "telegram":
+        return False, "exclude_types requires telegram source"
+    mt = detect_message_type(event.raw.message)
+    excluded = value if isinstance(value, list) else [value]
+    if mt.value in excluded:
+        return False, f"type {mt.value} excluded"
+    return True, f"type {mt.value} allowed"
+
+
+@register_filter("has_media")
+def filter_has_media(event: Event, value: Any) -> tuple[bool, str]:
+    if event.source != "telegram":
+        return False, "has_media requires telegram source"
+    has = event.raw.message.media is not None
+    if has == bool(value):
+        return True, "media filter matched"
+    return False, "media filter"
+
+
+@register_filter("is_reply")
+def filter_is_reply(event: Event, value: Any) -> tuple[bool, str]:
+    if event.source != "telegram":
+        return False, "is_reply requires telegram source"
+    is_reply = event.raw.message.reply_to is not None
+    if is_reply == bool(value):
+        return True, "reply filter matched"
+    return False, "reply filter"
+
+
+@register_filter("is_forward")
+def filter_is_forward(event: Event, value: Any) -> tuple[bool, str]:
+    if event.source != "telegram":
+        return False, "is_forward requires telegram source"
+    is_fwd = event.raw.message.forward is not None
+    if is_fwd == bool(value):
+        return True, "forward filter matched"
+    return False, "forward filter"