tlgr-cli 2.0.1__py3-none-any.whl

tlgr/models/privacy.py

@@ -0,0 +1,93 @@
+"""Privacy rules, the global privacy switches, and paid-message revenue.
+
+`account.setPrivacy` **replaces** the whole ordered rule vector, and
+`account.setGlobalPrivacySettings` replaces the whole constructor. Both are
+therefore read-modify-write operations, and both need a model that survives
+the round trip without losing anything:
+
+* `PrivacySettings` splits the vector into the four exception lists a human
+  edits *and* keeps `raw_rules` — the constructors in server order — so a
+  rule tlgr does not recognise is still sent back unchanged.
+* `GlobalPrivacy` names every field of the constructor, so patching one and
+  writing the rest back cannot silently clear a switch nobody mentioned.
+"""
+
+from __future__ import annotations
+
+from tlgr.models.base import Model
+from tlgr.models.peer import Peer
+
+__all__ = [
+    "GlobalPrivacy",
+    "PaidMessageRevenue",
+    "PrivacyExceptions",
+    "PrivacyRule",
+    "PrivacySettings",
+]
+
+
+class PrivacyRule(Model):
+    """One `privacyValue*` constructor, in tlgr's vocabulary."""
+
+    #: allow | disallow
+    action: str = "allow"
+    #: all | contacts | close-friends | premium | bots | users | chats
+    scope: str = "all"
+    ids: list[int] = []
+
+
+class PrivacyExceptions(Model):
+    """The four lists the GUI calls "Always allow" / "Never allow"."""
+
+    allow_users: list[int] = []
+    deny_users: list[int] = []
+    allow_chats: list[int] = []
+    deny_chats: list[int] = []
+
+
+class PrivacySettings(Model):
+    """One privacy key, read or written.
+
+    `base` is the headline the GUI shows; the exception lists are what it
+    puts under it. `raw_rules` is the server's own ordered vector, kept so a
+    write can reproduce it exactly.
+    """
+
+    key: str
+    #: everybody | contacts | close-friends | premium | bots | nobody. No
+    #: default: it is the headline, and `omit_defaults` would hide the most
+    #: restrictive answer exactly when a caller most wants to see it.
+    base: str
+    allow_users: list[int] = []
+    deny_users: list[int] = []
+    allow_chats: list[int] = []
+    deny_chats: list[int] = []
+    raw_rules: list[PrivacyRule] = []
+    #: Resolved names for the exception ids, when `--resolve` was given.
+    peers: list[Peer] = []
+
+
+class GlobalPrivacy(Model):
+    """`globalPrivacySettings`, every field named.
+
+    Nothing here defaults to a value the server might disagree with: each
+    flag is a tri-state so "the server did not report it" stays different
+    from "off", which is what makes the read-modify-write safe.
+    """
+
+    hide_read_marks: bool | None = None
+    archive_and_mute_new_noncontact_peers: bool | None = None
+    new_noncontact_peers_require_premium: bool | None = None
+    noncontact_peers_paid_stars: int | None = None
+    keep_archived_unmuted: bool | None = None
+    keep_archived_folders: bool | None = None
+    display_gifts_button: bool | None = None
+    #: unlimited | limited | unique | premium | from-channels
+    disallowed_gifts: list[str] = []
+    changed: list[str] = []
+    already: bool = False
+
+
+class PaidMessageRevenue(Model):
+    user_id: int
+    stars_amount: int = 0

tlgr/models/profile.py

@@ -0,0 +1,217 @@
+"""My own profile — the Settings ▸ Edit Profile screen, as data.
+
+Everything here describes *this* account rather than somebody else's: the
+name and bio the world sees, the usernames (including the Fragment
+collectibles), the avatar history, the accent colours, the emoji status and
+the presence switch.
+
+Two shapes are deliberate.
+
+* **`ProfileFull` is one object, not a union of three RPCs.** `users.getUsers`
+  answers the name, `users.getFullUser` the bio, birthday, personal channel
+  and gift counters. v1 fetched only the first and hard-coded `bio` to `""`,
+  which is a wrong answer dressed as a real one. One model, both calls.
+* **A username is a row, not a string.** A collectible bought on Fragment can
+  be active or parked, and only the *first* active one is the main handle;
+  flattening the vector to `username` is how a script deactivates the wrong
+  name.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from tlgr.models.base import Model
+from tlgr.models.peer import Peer
+
+__all__ = [
+    "AdminedChannel",
+    "ColorPalette",
+    "ColorSet",
+    "EmojiStatusItem",
+    "EmojiStatusSet",
+    "PhotosDeleted",
+    "PresenceSet",
+    "ProfileFull",
+    "ProfileLink",
+    "ProfilePhotoSet",
+    "ProfileUpdated",
+    "ProfileUsername",
+    "UsernameSet",
+]
+
+
+class ProfileUsername(Model):
+    """One entry of `user.usernames`.
+
+    `main` is derived rather than reported: the server marks the basic
+    username with `editable`, and the first *active* entry is what a link
+    resolves to. Both facts matter and neither is the other.
+    """
+
+    username: str
+    active: bool = True
+    editable: bool = False
+    main: bool = False
+
+
+class ProfileFull(Model):
+    """My profile as the Edit Profile screen shows it."""
+
+    id: int = 0
+    first_name: str = ""
+    last_name: str = ""
+    username: str | None = None
+    usernames: list[ProfileUsername] = []
+    phone: str | None = None
+    premium: bool = False
+    bot: bool = False
+    #: Only present with `--full`; `""` means "fetched and empty", `None`
+    #: means "not fetched", which v1 could not tell apart.
+    bio: str | None = None
+    birthday: str | None = None
+    personal_channel_id: int | None = None
+    personal_channel: Peer | None = None
+    emoji_status: int | None = None
+    emoji_status_collectible_id: int | None = None
+    emoji_status_until: str | None = None
+    color: int | None = None
+    color_collectible_id: int | None = None
+    background_emoji_id: int | None = None
+    profile_color: int | None = None
+    profile_background_emoji_id: int | None = None
+    #: Which tab the profile page opens on (`stargifts`, `posts`, …).
+    main_tab: str | None = None
+    stargifts_count: int | None = None
+    stars_rating: int | None = None
+    ttl_period: int | None = None
+    sponsored_enabled: bool | None = None
+    #: Gift categories this account refuses, from `disallowed_gifts`.
+    disallowed_gifts: list[str] = []
+    photo_id: int | None = None
+    fallback_photo_id: int | None = None
+    contacts_count: int | None = None
+    common_chats_count: int | None = None
+
+
+class ProfileUpdated(Model):
+    """What `profile update` actually changed, field by field.
+
+    Only the fields the caller named appear, because the command spans three
+    RPCs and "I asked for a birthday and got a name back" is a report nobody
+    can act on.
+    """
+
+    first_name: str | None = None
+    last_name: str | None = None
+    bio: str | None = None
+    birthday: str | None = None
+    personal_channel_id: int | None = None
+    photo_id: int | None = None
+    changed: list[str] = []
+    already: bool = False
+
+
+class UsernameSet(Model):
+    """`profile username set`, in all five of its moods."""
+
+    username: str | None = None
+    active: bool | None = None
+    #: Only for `--check`: whether the name may be taken right now.
+    available: bool | None = None
+    #: Set when the server says `USERNAME_PURCHASE_AVAILABLE`: the name is
+    #: free only on Fragment, which is a different answer from "taken".
+    purchasable: bool = False
+    usernames: list[ProfileUsername] = []
+    already: bool = False
+
+
+class ColorPalette(Model):
+    """One entry of `help.getPeerColors` / `getPeerProfileColors`."""
+
+    color_id: int
+    colors: list[str] = []
+    dark_colors: list[str] = []
+    min_level: int = 0
+    hidden: bool = False
+    channel_min_level: int | None = None
+    group_min_level: int | None = None
+    #: True for palettes 0-6, whose colours every client hard-codes.
+    builtin: bool = False
+
+
+class ColorSet(Model):
+    """`profile color set`: the palette now in force."""
+
+    color: int | None = None
+    collectible_id: int | None = None
+    background_emoji_id: int | None = None
+    for_profile: bool = False
+    already: bool = False
+
+
+class EmojiStatusItem(Model):
+    """A wearable emoji status, from any of the four suggestion lists."""
+
+    document_id: int = 0
+    collectible_id: int | None = None
+    title: str | None = None
+    slug: str | None = None
+    group: str = ""
+    until: str | None = None
+
+
+class EmojiStatusSet(Model):
+    document_id: int | None = None
+    collectible_id: int | None = None
+    until: str | None = None
+    until_unix: int | None = None
+    cleared: bool = False
+    already: bool = False
+
+
+class PresenceSet(Model):
+    """`profile presence set`. `online` is what was *reported*, not measured."""
+
+    online: bool
+    already: bool = False
+
+
+class ProfilePhotoSet(Model):
+    photo_id: int | None = None
+    is_video: bool = False
+    fallback: bool = False
+    #: Set when the avatar was built server-side from a custom emoji.
+    emoji_markup: bool = False
+
+
+class PhotosDeleted(Model):
+    deleted: int = 0
+    photo_ids: list[int] = []
+    already: bool = False
+
+
+class ProfileLink(Model):
+    """`profile link`: the public handle, and what Fragment knows about it."""
+
+    #: No default: `omit_defaults` would drop the reassuring answer and
+    #: leave a caller unable to tell "public" from "not reported".
+    resolvable_by_strangers: bool
+    link: str = ""
+    username: str | None = None
+    user_id: int | None = None
+    #: A unicode-block QR, when `--qr` was given.
+    qr: str | None = None
+    qr_path: str | None = None
+    #: `fragment.getCollectibleInfo`, when `--collectible` was given.
+    collectible: dict[str, Any] | None = None
+
+
+class AdminedChannel(Model):
+    """A public channel eligible to be shown on the profile."""
+
+    id: int
+    title: str = ""
+    username: str | None = None
+    participants_count: int | None = None
+    current: bool = False

tlgr/models/reaction.py

@@ -0,0 +1,160 @@
+"""Reactions: what is on a message, who put it there, and what a chat allows.
+
+One spelling for a reaction across the whole group: a unicode emoji is itself
+(`"👍"`) and a custom (Premium) emoji is `"custom:<document_id>"`. The pair
+`(emoji, custom)` is accepted on input and the same string comes back on
+output, so a reaction read from `reaction list` can be handed straight back to
+`reaction remove` without the caller knowing which kind it was.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from tlgr.models.base import Model
+from tlgr.models.message import ReactionSummary
+
+__all__ = [
+    "AvailableReaction",
+    "ChatReactions",
+    "MessageReactionState",
+    "PaidReactionResult",
+    "ReactionPrivacy",
+    "ReactionPurge",
+    "ReactionReport",
+    "ReactionResult",
+    "ReactionTag",
+    "ReactionUser",
+    "TopReactor",
+]
+
+
+class ReactionResult(Model):
+    """What `reaction add` / `reaction remove` did.
+
+    `emoji` and `reacted` are v1's `message react` keys and stay spelled that
+    way; `mine` is the full set my account now holds, because `sendReaction`
+    takes the whole desired state and a caller that wants to add a second
+    reaction has to know what the first one was.
+    """
+
+    chat_id: int
+    msg_id: int
+    emoji: str = ""
+    reacted: bool = False
+    already: bool = False
+    mine: list[str] = []
+    reactions: ReactionSummary | None = None
+
+
+class TopReactor(Model):
+    """A row of the Star-reaction leaderboard on a channel post."""
+
+    user_id: int | None = None
+    stars: int = 0
+    anonymous: bool = False
+    mine: bool = False
+
+
+class MessageReactionState(Model):
+    """The reaction state of one message, refreshed from the server."""
+
+    chat_id: int = 0
+    msg_id: int = 0
+    reactions: ReactionSummary | None = None
+    can_see_list: bool = False
+    as_tags: bool = False
+    top_reactors: list[TopReactor] = []
+
+
+class ReactionUser(Model):
+    """Who reacted, with what, and when."""
+
+    user_id: int
+    reaction: str = ""
+    date: str | None = None
+    date_unix: int | None = None
+    big: bool = False
+    unread: bool = False
+    mine: bool = False
+
+
+class AvailableReaction(Model):
+    """One entry of the reaction catalogue.
+
+    `source` says which list it came from, because the standard catalogue,
+    the featured list and my own recent reactions are three different
+    questions with three different endpoints and the same row shape.
+    """
+
+    emoticon: str
+    source: Literal["available", "top", "recent"]
+    title: str = ""
+    premium: bool = False
+    inactive: bool = False
+    static_icon_id: int | None = None
+    select_animation_id: int | None = None
+
+
+class ChatReactions(Model):
+    """What a chat (or one message in it) allows.
+
+    `mode` is the `chatReactions*` variant flattened to a word, because
+    `setChatAvailableReactions` demands the whole value on every write: a
+    caller changing only `reactions_limit` still has to resend the mode.
+    """
+
+    mode: Literal["all", "some", "none"]
+    chat_id: int = 0
+    msg_id: int | None = None
+    reactions: list[str] = []
+    allow_custom: bool = False
+    reactions_limit: int | None = None
+    paid_enabled: bool | None = None
+
+
+class ReactionTag(Model):
+    """A Saved Messages reaction tag, and the name I gave it."""
+
+    reaction: str
+    title: str | None = None
+    count: int = 0
+    suggested: bool = False
+
+
+class ReactionPrivacy(Model):
+    """How my paid reactions are attributed."""
+
+    privacy: Literal["default", "anonymous", "peer"]
+    peer_id: int | None = None
+    msg_id: int | None = None
+
+
+class PaidReactionResult(Model):
+    """A Star reaction that was actually paid for."""
+
+    chat_id: int
+    msg_id: int
+    stars_sent: int = 0
+    privacy: Literal["default", "anonymous", "peer"] = "default"
+    top_reactors: list[TopReactor] = []
+    #: `reaction pay --senders`: the peers I may pay as, listed without paying.
+    senders: list[int] = []
+
+
+class ReactionPurge(Model):
+    """A moderator's removal of somebody else's reactions."""
+
+    chat_id: int
+    user_id: int
+    scope: Literal["message", "chat"]
+    msg_id: int | None = None
+    deleted: bool = False
+
+
+class ReactionReport(Model):
+    ok: bool = False
+    banned: bool = False
+    chat_id: int = 0
+    msg_id: int = 0
+    user_id: int = 0

tlgr/models/resolve.py

@@ -0,0 +1,175 @@
+"""Resolution results: what a reference, a link or a cache entry turns into.
+
+`resolve` is the one group whose whole job is to be honest about *how* an
+answer was reached, so every shape here carries provenance:
+
+* `ResolvedRef.source` says which strategy answered (cache, username, phone,
+  dialog scan, arithmetic on a `t.me/c/` link).
+* `ResolvedPhone.reason` exists because `PHONE_NOT_OCCUPIED` is genuinely
+  ambiguous — no account, or an owner who refuses phone lookups — and the op
+  exits 13 rather than claiming "not found".
+* `ResolvedLink.delegated_to` names the command that would *act* on a link.
+  Resolution never joins, starts, installs, boosts or redeems anything; it
+  says what the link is and which verb would.
+
+No access hash is ever emitted, only `access_hash_cached`.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Literal
+
+from tlgr.models.base import Model
+from tlgr.models.peer import Peer
+
+__all__ = [
+    "CachedPeerRow",
+    "LinkKind",
+    "ResolvedLink",
+    "ResolvedPhone",
+    "ResolvedRef",
+    "ResolvedUsername",
+]
+
+#: Every shape a t.me / tg:// reference can take. `unknown` is a real answer:
+#: Telegram adds deep links faster than any client learns them, and reporting
+#: `unknown` with the raw path beats guessing wrong.
+LinkKind = Literal[
+    "public-username",
+    "phone",
+    "invite",
+    "chatlist-invite",
+    "message",
+    "private-post",
+    "story",
+    "bot-start",
+    "bot-startgroup",
+    "bot-startchannel",
+    "webapp",
+    "business-chat-link",
+    "contact-token",
+    "proxy",
+    "boost",
+    "giftcode",
+    "unique-gift",
+    "stars-topup",
+    "wallpaper",
+    "theme",
+    "stickerset",
+    "emojiset",
+    "share-url",
+    "settings-section",
+    "contacts-section",
+    "login-code",
+    "confirm-phone",
+    "invoice",
+    "premium-offer",
+    "folder",
+    "unknown",
+]
+
+
+class ResolvedRef(Model, omit_defaults=False):
+    """One `resolve peer` answer, with the strategy that produced it."""
+
+    ref: str = ""
+    kind: str = ""
+    id: int | None = None
+    marked_id: int | None = None
+    botapi_id: int | None = None
+    type: str = ""
+    title: str = ""
+    username: str | None = None
+    access_hash_cached: bool = False
+    min: bool = False
+    source: str = ""
+    resolved: bool = False
+    reason: str | None = None
+
+
+class ResolvedUsername(Model, omit_defaults=False):
+    kind: str = ""
+    peer: Peer | None = None
+    username: str = ""
+    access_hash_cached: bool = False
+
+
+class ResolvedPhone(Model, omit_defaults=False):
+    """A phone lookup. `resolved=false` with a `reason` is exit 13, not 5."""
+
+    phone: str = ""
+    e164: str = ""
+    country: str | None = None
+    prefix: str | None = None
+    pattern: str | None = None
+    resolved: bool = False
+    peer: Peer | None = None
+    reason: str | None = None
+    countries: list[dict[str, Any]] = []
+
+
+class ResolvedLink(Model):
+    """A t.me / tg:// link, classified and (optionally) read.
+
+    One discriminated shape rather than one command per link type: a human
+    pasting a link does not know which of twenty kinds it is, and that is
+    precisely the question.
+    """
+
+    kind: LinkKind
+    raw_url: str = ""
+    scheme: str = ""
+    peer: Peer | None = None
+    username: str | None = None
+    phone: str | None = None
+    invite_hash: str | None = None
+    chatlist_slug: str | None = None
+    msg_id: int | None = None
+    thread_id: int | None = None
+    comment_id: int | None = None
+    story_id: int | None = None
+    bot: str | None = None
+    start_param: str | None = None
+    start_target: str | None = None
+    boost: bool | None = None
+    gift: str | None = None
+    stars: int | None = None
+    proxy: dict[str, Any] | None = None
+    theme: str | None = None
+    wallpaper: str | None = None
+    stickerset: str | None = None
+    share: dict[str, Any] | None = None
+    contact_token: str | None = None
+    section: str | None = None
+    deeplink_info: str | None = None
+    title: str | None = None
+    #: Set only with `--open`: the follow-up read for the classified kind.
+    opened: dict[str, Any] | None = None
+    requires_action: bool = False
+    #: The command that would act on this link. Naming it is the alternative
+    #: to acting: joining, starting a bot or redeeming a gift are separate,
+    #: confirmed verbs in their own groups.
+    delegated_to: str | None = None
+    draft_saved: bool = False
+
+
+class CachedPeerRow(Model, omit_defaults=False):
+    """One entry of the per-account resolver cache.
+
+    `min_context` is the `(chat, message)` where a `min` user was seen —
+    Telethon stores none, and without it a stranger who posted in a channel
+    is unaddressable.
+    """
+
+    id: int = 0
+    marked_id: int = 0
+    type: str = ""
+    username: str | None = None
+    phone: str | None = None
+    access_hash_cached: bool = False
+    min: bool = False
+    min_context: str | None = None
+    seen_at: str | None = None
+    seen_at_unix: int | None = None
+    refreshed: bool = False
+    purged: bool = False