tlgr-cli 2.0.1__py3-none-any.whl

tlgr/models/settings.py

@@ -0,0 +1,103 @@
+"""Cloud-synced account settings, languages and cloud themes.
+
+`settings get`/`settings set` are one generic pair over a dozen unrelated
+RPCs, so the model is a *key and a value* rather than a struct per toggle.
+That is not laziness: every key prints the exact token vocabulary its setter
+accepts, which makes `tlgr settings get X | tlgr settings set X -` a real
+round trip and keeps twelve near-identical commands out of the surface.
+
+`previous` is always reported on a write. A setting that was already in the
+wanted state answers `already: true` with `previous == value`, which is the
+only way a script can tell "I changed it" from "it was like that".
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from tlgr.models.base import Model
+
+__all__ = [
+    "CloudTheme",
+    "Language",
+    "SettingChange",
+    "SettingUnset",
+    "SettingValue",
+    "ThemeInstalled",
+]
+
+
+class SettingValue(Model):
+    """One cloud setting, read.
+
+    `changeable` is false when the server will refuse the write for a reason
+    that is not an error — Premium-only keys, and the sensitive-content
+    toggle in regions that require an age check first.
+    """
+
+    key: str
+    value: Any = None
+    changeable: bool = True
+    #: server | app-config | derived — where the value came from.
+    source: str = "server"
+    accepts: str = ""
+    reason: str | None = None
+
+
+class SettingChange(Model):
+    key: str
+    value: Any = None
+    previous: Any = None
+    already: bool = False
+    #: `auto-delete --apply-to-existing`: how many chats were rewritten.
+    applied_to: int | None = None
+
+
+class SettingUnset(Model):
+    key: str
+    removed: int
+    values: list[str] = []
+    already: bool = False
+
+
+class Language(Model):
+    lang_code: str
+    name: str = ""
+    native_name: str = ""
+    official: bool = False
+    beta: bool = False
+    rtl: bool = False
+    strings_count: int = 0
+    translated_count: int = 0
+    translations_url: str | None = None
+    plural_code: str | None = None
+    base_lang_code: str | None = None
+
+
+class CloudTheme(Model):
+    """A cloud theme's metadata. tlgr has no theming engine and renders none."""
+
+    id: int = 0
+    access_hash: int | None = None
+    slug: str = ""
+    title: str = ""
+    creator: bool = False
+    default: bool = False
+    for_chat: bool = False
+    installs_count: int | None = None
+    document_id: int | None = None
+    emoticon: str | None = None
+    settings: list[dict[str, Any]] = []
+    link: str | None = None
+
+
+class ThemeInstalled(Model):
+    slug: str | None = None
+    id: int | None = None
+    title: str | None = None
+    installed: bool = False
+    saved: bool = False
+    removed: bool = False
+    dark: bool = False
+    document_id: int | None = None
+    already: bool = False

tlgr/models/stars.py

@@ -0,0 +1,101 @@
+"""Telegram Stars: the balance, the ledger, subscriptions and revenue.
+
+A Stars amount is `(amount, nanos)` on the wire, and both halves are kept:
+collapsing them to a float loses the ninth digit that a ledger reconciliation
+depends on, and TON amounts arrive in the same shape with nine decimals of
+their own.
+
+Nothing here moves value. The withdrawal command produces a Fragment URL for
+a human to open, which is why `StarsUrl` is a URL and not a receipt.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from tlgr.models.base import Model
+from tlgr.models.peer import Peer
+
+__all__ = [
+    "StarsBalance",
+    "StarsRating",
+    "StarsRefulfill",
+    "StarsRevenue",
+    "StarsTransaction",
+    "StarsUrl",
+]
+
+
+class StarsBalance(Model):
+    """`payments.getStarsStatus`. `ton` is in nanotons, never rounded."""
+
+    stars: int = 0
+    nanos: int = 0
+    ton: int | None = None
+    currency: str = "XTR"
+    subscriptions_missing_balance: int | None = None
+
+
+class StarsTransaction(Model):
+    id: str = ""
+    date: str | None = None
+    date_unix: int | None = None
+    #: Signed: negative is money leaving the balance.
+    stars: int = 0
+    nanos: int = 0
+    refund: bool = False
+    pending: bool = False
+    failed: bool = False
+    peer: int | None = None
+    peer_kind: str = ""
+    peer_ref: Peer | None = None
+    title: str | None = None
+    description: str | None = None
+    msg_id: int | None = None
+    subscription_period: int | None = None
+    transaction_url: str | None = None
+    #: gift | reaction | subscription | resale | upgrade | ads | …
+    kind: str = ""
+
+
+class StarsRating(Model):
+    level: int = 0
+    stars: int = 0
+    current_level_stars: int = 0
+    next_level_stars: int | None = None
+    pending_stars: int | None = None
+    pending_date: str | None = None
+    learnmore_url: str | None = None
+
+
+class StarsRevenue(Model):
+    chat_id: int = 0
+    current_balance: int | None = None
+    available_balance: int | None = None
+    overall_revenue: int | None = None
+    withdrawal_enabled: bool = False
+    next_withdrawal_at: str | None = None
+    usd_rate: float | None = None
+    revenue_graph: dict[str, Any] | None = None
+    top_hours_graph: dict[str, Any] | None = None
+
+
+class StarsUrl(Model):
+    """A Fragment URL. Opening it — and the transfer — is the human's job."""
+
+    #: withdrawal | ads
+    kind: str
+    url: str = ""
+    chat_id: int = 0
+    amount: int | None = None
+    ton: bool = False
+
+
+class StarsRefulfill(Model):
+    """Re-joining a lapsed Star subscription, reported and not performed."""
+
+    id: str
+    ok: bool
+    can_refulfill: bool | None = None
+    stars: int | None = None
+    reason: str = ""

tlgr/models/sticker.py

@@ -0,0 +1,243 @@
+"""Stickers, GIFs and custom emoji.
+
+Three surfaces that look like three products in the GUI and are one thing on
+the wire: a `Document` carrying `DocumentAttributeSticker` or
+`DocumentAttributeCustomEmoji`, grouped into sets. Modelling them once is why
+`sticker set list --type emoji` and `emoji set list` can be the same
+operation, and why a saved GIF and a sticker share the file handle.
+
+The split that *is* real is `set` versus `pack`: a **set** is somebody's
+collection you install, archive or reorder; a **pack** is one you created and
+can edit. Every model here keeps that boundary, because the API does: the
+`stickers.*` namespace answers only to a set's creator.
+"""
+
+from __future__ import annotations
+
+from tlgr.models.base import Model
+from tlgr.models.media import MediaFile
+
+__all__ = [
+    "EmojiGroup",
+    "EmojiKeyword",
+    "FaveResult",
+    "GifResult",
+    "GifSaved",
+    "GifSent",
+    "PackCreated",
+    "PackDeleted",
+    "PackEdited",
+    "PackStickerAdded",
+    "PackStickerRemoved",
+    "RecentResult",
+    "SavedGif",
+    "Sticker",
+    "StickerSet",
+    "StickerSetOrder",
+    "StickerSetsChanged",
+]
+
+
+class Sticker(Model):
+    """One sticker or custom-emoji document.
+
+    `emoji` is `DocumentAttributeSticker.alt` — the plain emoji the sticker
+    stands for — and `index` is its position in the set, which is what
+    `message send --sticker <set>/<n>` consumes.
+    """
+
+    doc_id: int
+    access_hash: int | None = None
+    file_reference_b64: str | None = None
+    emoji: str | None = None
+    keywords: list[str] = []
+    index: int | None = None
+    set_id: int | None = None
+    set_short_name: str | None = None
+    set: str | None = None
+    mime: str | None = None
+    size: int | None = None
+    width: int | None = None
+    height: int | None = None
+    dc_id: int | None = None
+    premium: bool = False
+    mask: bool = False
+    #: Custom emoji only: `free` says a non-Premium account may send it, and
+    #: `text_color` that it renders in the message's text colour.
+    custom_emoji: bool = False
+    free: bool | None = None
+    text_color: bool | None = None
+    file_id: str | None = None
+    path: str | None = None
+
+
+class StickerSet(Model):
+    """A sticker, mask or custom-emoji set.
+
+    `stickers`, `packs` and `keywords` are filled only by `sticker set get`;
+    a listing carries the metadata and, for a search result, the cover
+    stickers the server sent with it.
+    """
+
+    id: int
+    access_hash: int | None = None
+    short_name: str = ""
+    title: str = ""
+    count: int = 0
+    type: str = "sticker"
+    installed: bool = False
+    archived: bool = False
+    official: bool = False
+    creator: bool = False
+    unread: bool = False
+    text_color: bool = False
+    installed_date: str | None = None
+    thumb: MediaFile | None = None
+    link: str | None = None
+    stickers: list[Sticker] = []
+    covers: list[Sticker] = []
+    #: emoji → the document ids in this set that carry it.
+    packs: dict[str, list[int]] = {}
+    #: document id → its search keywords.
+    keywords: dict[str, list[str]] = {}
+
+
+class StickerSetsChanged(Model):
+    """The result of installing, removing, archiving or unarchiving sets.
+
+    Counts rather than booleans because every one of these verbs is variadic,
+    and `already` because asking for a state the account is already in is a
+    no-op, not a failure.
+    """
+
+    short_names: list[str] = []
+    installed: int = 0
+    removed: int = 0
+    archived: int = 0
+    unarchived: int = 0
+    already: bool = False
+    #: Sets the server archived to keep under the installed-sets limit.
+    archived_sets: list[str] = []
+
+
+class StickerSetOrder(Model):
+    type: str = "sticker"
+    order: list[int] = []
+    ok: bool = True
+
+
+class FaveResult(Model):
+    doc_ids: list[int] = []
+    faved: int = 0
+    unfaved: int = 0
+    already: bool = False
+    evicted: list[int] = []
+
+
+class RecentResult(Model):
+    doc_ids: list[int] = []
+    removed: int = 0
+    cleared: bool = False
+    already: bool = False
+
+
+class PackCreated(Model):
+    id: int = 0
+    short_name: str = ""
+    title: str = ""
+    type: str = "sticker"
+    count: int = 0
+    link: str | None = None
+    stickers: list[Sticker] = []
+    #: `--dry-run`: the short name the server would accept.
+    available: bool | None = None
+
+
+class PackStickerAdded(Model):
+    short_name: str
+    doc_id: int = 0
+    position: int | None = None
+    count: int = 0
+    replaced: int | None = None
+
+
+class PackStickerRemoved(Model):
+    short_name: str
+    removed: list[int] = []
+    count: int = 0
+
+
+class PackEdited(Model):
+    short_name: str
+    title: str | None = None
+    thumb: MediaFile | None = None
+    sticker: int | None = None
+    changed: list[str] = []
+
+
+class PackDeleted(Model):
+    short_name: str
+    deleted: bool = False
+
+
+class SavedGif(Model):
+    doc_id: int
+    access_hash: int | None = None
+    file_reference_b64: str | None = None
+    index: int | None = None
+    mime: str | None = None
+    size: int | None = None
+    duration: int | None = None
+    width: int | None = None
+    height: int | None = None
+    file_id: str | None = None
+    path: str | None = None
+
+
+class GifSaved(Model):
+    doc_ids: list[int] = []
+    saved: int = 0
+    removed: int = 0
+    already: bool = False
+    evicted: list[int] = []
+
+
+class GifResult(Model):
+    """One inline-bot result from the GIF search bot."""
+
+    result_id: str = ""
+    query_id: int = 0
+    type: str = "gif"
+    title: str | None = None
+    url: str | None = None
+    thumb: str | None = None
+    duration: int | None = None
+    width: int | None = None
+    height: int | None = None
+    doc_id: int | None = None
+
+
+class GifSent(Model):
+    chat_id: int
+    msg_id: int = 0
+    doc_id: int | None = None
+    via_bot: str | None = None
+    saved: bool = False
+
+
+class EmojiGroup(Model):
+    """A category chip above the sticker / emoji / GIF search box."""
+
+    kind: str = "groups"
+    title: str = ""
+    icon_emoji_id: int | None = None
+    emoticons: list[str] = []
+    document_ids: list[int] = []
+
+
+class EmojiKeyword(Model):
+    emoticon: str = ""
+    keyword: str = ""
+    lang: str = ""
+    doc_id: int | None = None
+    set_short_name: str | None = None