tlgr-cli 2.0.1__py3-none-any.whl

tlgr/models/event.py

@@ -0,0 +1,79 @@
+"""The event envelope, and the shapes that describe the event vocabulary.
+
+The envelope is the wire shape every consumer sees. `EventType` and
+`EventTypeDetail` are the *catalogue* shapes: what `tlgr events list` and
+`tlgr events get` print so that an agent can discover the subscribable surface
+before it opens a stream, rather than learning it from prose.
+
+The vocabulary itself lives in `tlgr/core/eventtypes.py`; only its shape is
+here, because `models/` imports nothing from tlgr (§2.2).
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from tlgr.models.base import Model
+
+__all__ = [
+    "DecodedEvent",
+    "EventEnvelope",
+    "EventType",
+    "EventTypeDetail",
+]
+
+
+class EventEnvelope(Model):
+    seq: int
+    ts: str
+    account: str
+    type: str
+    payload: dict[str, Any] = {}
+    chat_id: int | None = None
+    sender_id: int | None = None
+    # True when this event echoes an action tlgr itself performed, so a
+    # gateway rule cannot loop by reacting to its own output.
+    self_origin: bool = False
+    #: The raw TL update, JSON-safe, when the consumer asked for it
+    #: (`watch --with-raw`). Absent otherwise: it roughly doubles the frame.
+    raw: dict[str, Any] | None = None
+
+
+class EventType(Model):
+    """One row of `tlgr events list`."""
+
+    type: str
+    group: str
+    summary: str
+    #: The `Update*` constructors that produce it.
+    sources: list[str] = []
+    telethon: str = ""
+    #: Which sequence box orders it: pts, qts, seq, channel_pts, version, none.
+    box: str = "none"
+    bot_only: bool = False
+    #: 0 when this build can parse every source; 229 when Telegram has the
+    #: constructor and Telethon 1.44 does not.
+    since_layer: int = 0
+    available: bool = True
+    derived: str = ""
+
+
+class EventTypeDetail(EventType):
+    """`tlgr events get <type>`: the row, plus the payload and an example."""
+
+    payload: dict[str, str] = {}
+    json_schema: dict[str, Any] | None = None
+    filters: list[str] = []
+    example: EventEnvelope | None = None
+
+
+class DecodedEvent(Model):
+    """`tlgr events decode`: one TL update or push payload, made a tlgr event."""
+
+    event: str
+    account: str = ""
+    chat_id: int | None = None
+    sender_id: int | None = None
+    data: dict[str, Any] = {}
+    raw: dict[str, Any] | None = None
+    push: bool = False

tlgr/models/export.py

@@ -0,0 +1,66 @@
+"""Takeout (data export) shapes.
+
+A takeout session is a *mode*, not a request: once `account.initTakeoutSession`
+returns an id, every subsequent call — `upload.getFile` included — has to be
+wrapped in `invokeWithTakeout`, and `file_max_size` can never be changed. The
+model therefore records the scope it was opened with, because a caller that
+forgets it will simply get nothing back and no error.
+"""
+
+from __future__ import annotations
+
+from tlgr.models.base import Model
+
+__all__ = [
+    "ExportResult",
+    "ExportedFile",
+    "MessageRange",
+    "TakeoutSession",
+    "TakeoutStatus",
+]
+
+
+class TakeoutSession(Model):
+    takeout_id: int | None = None
+    scope: list[str] = []
+    started_at: str | None = None
+    expires: str | None = None
+    max_file_size: int = 0
+    #: TAKEOUT_INIT_DELAY_X: another logged-in session has to approve the
+    #: export first (24 h if there is none). Reported, never slept through
+    #: silently.
+    approval_required: bool = False
+    retry_after: int | None = None
+    already: bool = False
+
+
+class MessageRange(Model):
+    min_id: int = 0
+    max_id: int = 0
+
+
+class TakeoutStatus(Model):
+    #: No default: "is an export open" is the question, and a `Model` omits a
+    #: field equal to its default.
+    active: bool
+    takeout_id: int | None = None
+    started_at: str | None = None
+    scope: list[str] = []
+    max_file_size: int = 0
+    ranges: list[MessageRange] = []
+
+
+class ExportedFile(Model):
+    path: str
+    kind: str = ""
+    bytes: int = 0
+
+
+class ExportResult(Model):
+    written: int = 0
+    files: list[ExportedFile] = []
+    out: str = ""
+    finished: bool = False
+    takeout_id: int | None = None
+    success: bool = True
+    skipped: list[str] = []

tlgr/models/gift.py

@@ -0,0 +1,275 @@
+"""Star gifts: the catalogue, the gifts a profile holds, collectibles,
+collections, the resale market and the auctions.
+
+A gift is addressed by a **reference**, not an id, and `ref` is that string
+everywhere in this module: `msg:<id>` for a gift I received in a private
+chat, `<peer>:<saved_id>` for one held by a channel, or a bare collectible
+slug. One spelling, so a `ref` read from a listing can be handed straight to
+`gift set`, `gift convert` or `gift transfer` without a lookup table.
+
+Every time gate the server publishes is surfaced rather than collapsed into
+a boolean. "Can I transfer this?" has three different answers — yes, not yet
+(and here is when), never — and a client that reports only the first two
+sends its user to wait for a date that will not come.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from tlgr.models.base import Model
+from tlgr.models.peer import Peer
+
+__all__ = [
+    "GiftAttribute",
+    "GiftAuction",
+    "GiftAuctionState",
+    "GiftCollection",
+    "GiftConverted",
+    "GiftCrafted",
+    "GiftDisplay",
+    "GiftListing",
+    "GiftOfferResolved",
+    "GiftTransferred",
+    "GiftUpgraded",
+    "GiftVariant",
+    "OwnedGift",
+    "ResaleGift",
+    "StarGift",
+    "UniqueGift",
+]
+
+
+class GiftAttribute(Model):
+    """One model / pattern / backdrop of a collectible, with its rarity."""
+
+    #: model | pattern | backdrop | original-details
+    kind: str = ""
+    name: str = ""
+    document_id: int | None = None
+    rarity_permille: int | None = None
+    backdrop_id: int | None = None
+    center_color: int | None = None
+    edge_color: int | None = None
+    pattern_color: int | None = None
+    text_color: int | None = None
+    crafted: bool = False
+    sender_id: int | None = None
+    recipient_id: int | None = None
+    message: str | None = None
+    date: str | None = None
+
+
+class StarGift(Model):
+    """A gift as the catalogue offers it."""
+
+    gift_id: int = 0
+    title: str = ""
+    stars: int = 0
+    convert_stars: int | None = None
+    upgrade_stars: int | None = None
+    limited: bool = False
+    sold_out: bool = False
+    birthday: bool = False
+    require_premium: bool = False
+    availability_remains: int | None = None
+    availability_total: int | None = None
+    availability_resale: int | None = None
+    first_sale_date: str | None = None
+    last_sale_date: str | None = None
+    document_id: int | None = None
+    resell_min_stars: int | None = None
+    #: Only filled when `--until` named a recipient.
+    can_send: bool | None = None
+    can_send_reason: str | None = None
+    per_user_total: int | None = None
+    per_user_remains: int | None = None
+
+
+class UniqueGift(Model):
+    """A collectible: the upgraded, numbered, tradable form of a gift."""
+
+    slug: str = ""
+    gift_id: int = 0
+    id: int = 0
+    title: str = ""
+    num: int = 0
+    owner_id: int | None = None
+    owner: Peer | None = None
+    owner_name: str | None = None
+    owner_address: str | None = None
+    gift_address: str | None = None
+    availability_issued: int | None = None
+    availability_total: int | None = None
+    attributes: list[GiftAttribute] = []
+    resell_stars: int | None = None
+    resell_ton: int | None = None
+    resale_ton_only: bool = False
+    value_stars: int | None = None
+    value_ton: int | None = None
+    value_currency: str | None = None
+    value_usd: int | None = None
+    #: A TON-hosted collectible lives outside Telegram's own custody.
+    hosted: bool = False
+    burned: bool = False
+    crafted: bool = False
+    theme_available: bool = False
+    peer_color_available: bool = False
+    offer_min_stars: int | None = None
+    craft_chance_permille: int | None = None
+    link: str | None = None
+
+
+class OwnedGift(Model):
+    """A gift a profile holds, with every gate that decides what may be done."""
+
+    ref: str = ""
+    #: gift | collectible
+    kind: str = "gift"
+    gift_id: int | None = None
+    slug: str | None = None
+    title: str = ""
+    num: int | None = None
+    from_id: int | None = None
+    from_peer: Peer | None = None
+    name_hidden: bool = False
+    message: str | None = None
+    date: str | None = None
+    date_unix: int | None = None
+    msg_id: int | None = None
+    saved_id: int | None = None
+    pinned: bool = False
+    displayed: bool = True
+    refunded: bool = False
+    can_upgrade: bool = False
+    convert_stars: int | None = None
+    upgrade_stars: int | None = None
+    transfer_stars: int | None = None
+    can_export_at: str | None = None
+    can_transfer_at: str | None = None
+    can_resell_at: str | None = None
+    can_craft_at: str | None = None
+    locked_until_date: str | None = None
+    resell_stars: int | None = None
+    resell_ton: int | None = None
+    collection_ids: list[int] = []
+    hosted: bool = False
+    attributes: list[GiftAttribute] = []
+    unique: UniqueGift | None = None
+
+
+class GiftCollection(Model):
+    id: int
+    title: str = ""
+    count: int = 0
+    icon_document_id: int | None = None
+    order: int | None = None
+
+
+class GiftDisplay(Model):
+    """The profile-display state of one or more gifts after `gift set`."""
+
+    ref: str = ""
+    refs: list[str] = []
+    displayed: bool | None = None
+    pinned: bool | None = None
+    worn: bool | None = None
+    until: str | None = None
+    already: bool = False
+
+
+class GiftConverted(Model):
+    ref: str
+    stars_received: int
+    balance_after: int | None = None
+
+
+class GiftUpgraded(Model):
+    ref: str
+    upgraded: bool
+    slug: str | None = None
+    num: int | None = None
+    attributes: list[GiftAttribute] = []
+    price_stars: int | None = None
+    refused_reason: str | None = None
+
+
+class GiftTransferred(Model):
+    ref: str
+    transferred: bool
+    to: int | None = None
+    price_stars: int | None = None
+    can_transfer_at: str | None = None
+    refused_reason: str | None = None
+
+
+class GiftListing(Model):
+    """A collectible put on (or taken off) the resale market."""
+
+    ref: str
+    listed: bool
+    price_stars: int | None = None
+    price_ton: int | None = None
+    can_resell_at: str | None = None
+    already: bool = False
+
+
+class ResaleGift(Model):
+    slug: str = ""
+    num: int = 0
+    price_stars: int | None = None
+    price_ton: int | None = None
+    seller_id: int | None = None
+    attributes: list[GiftAttribute] = []
+
+
+class GiftVariant(Model):
+    """One possible outcome of an upgrade, with how likely it is."""
+
+    #: model | pattern | backdrop
+    kind: str = ""
+    name: str = ""
+    document_id: int | None = None
+    rarity_permille: int | None = None
+    count: int | None = None
+    sample: bool = False
+
+
+class GiftCrafted(Model):
+    crafted: bool
+    ref: str | None = None
+    slug: str | None = None
+    burned: list[str] = []
+    candidates: list[OwnedGift] = []
+
+
+class GiftOfferResolved(Model):
+    msg_id: int
+    #: accepted | declined | refused
+    state: str
+    price_stars: int | None = None
+    buyer: int | None = None
+    reason: str | None = None
+
+
+class GiftAuction(Model):
+    auction: str = ""
+    gift_id: int | None = None
+    slug: str | None = None
+    my_bid: int | None = None
+    min_bid: int | None = None
+    ends_at: str | None = None
+    state: str = ""
+
+
+class GiftAuctionState(Model):
+    state: str
+    version: int
+    auction: str = ""
+    min_bid_amount: int | None = None
+    my_bid: int | None = None
+    position: int | None = None
+    ends_at: str | None = None
+    timeout: int | None = None
+    finished: bool = False
+    raw: dict[str, Any] | None = None

tlgr/models/inline.py

@@ -0,0 +1,84 @@
+"""Inline mode: what a bot answers a query with, and what sending one produces.
+
+`InlineResult` flattens the two constructors Telegram uses — `botInlineResult`
+(a URL and a `WebDocument` thumbnail the client has to fetch) and
+`botInlineMediaResult` (a `Photo`/`Document` already on Telegram) — into one
+row, because the difference is about where the bytes live and not about what
+the caller is choosing between. `content` names which of the two it was, so a
+caller that does care can still tell.
+
+`query_id` travels on every row on purpose: it is only valid *paired* with a
+result id, and only for `cache_time` seconds, so a row that carried the id
+alone would be a row that cannot be sent.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from tlgr.models.base import Model
+
+__all__ = [
+    "InlineEdited",
+    "InlineResult",
+    "InlineSent",
+    "PreparedMessage",
+    "PreparedSaved",
+]
+
+
+class InlineResult(Model):
+    """One result out of `messages.getInlineBotResults`."""
+
+    #: Flat row-major index within the page — what `inline send --pick` takes.
+    #: -1 rather than 0 as the default, because `omit_defaults` would
+    #: otherwise drop the first result's index and only the first result's.
+    n: int = -1
+    id: str = ""
+    type: str = ""
+    title: str | None = None
+    description: str | None = None
+    url: str | None = None
+    thumb: str | None = None
+    #: `url` for a `botInlineResult`, `media` for a `botInlineMediaResult`.
+    #: Always emitted: it is the one field that says where the bytes live.
+    content: str = ""
+    #: The kind of message this result would send: text, media_auto, geo,
+    #: venue, contact, invoice, webpage, game or rich.
+    send_message: str | None = None
+    query_id: str = ""
+    doc_id: int | None = None
+    photo_id: int | None = None
+    gallery: bool = False
+    cache_time: int | None = None
+    next_offset: str | None = None
+    switch_pm: dict[str, Any] | None = None
+    switch_webview: dict[str, Any] | None = None
+
+
+class InlineSent(Model):
+    chat_id: int = 0
+    msg_id: int = 0
+    result_id: str = ""
+    via_bot_id: int | None = None
+    quick_reply: str | None = None
+
+
+class InlineEdited(Model):
+    inline_msg_id: str = ""
+    edited: bool = False
+
+
+class PreparedMessage(Model):
+    """A message a mini app prepared for the user to share."""
+
+    query_id: str = ""
+    result: InlineResult | None = None
+    peer_types: list[str] = []
+    cache_time: int | None = None
+    expires_at: str | None = None
+
+
+class PreparedSaved(Model):
+    id: str = ""
+    expires_at: str | None = None

tlgr/models/location.py

@@ -0,0 +1,115 @@
+"""Locations: points, venues, live shares and who is nearby.
+
+`GeoPoint` carries `access_hash` because the map-thumbnail endpoint needs it,
+and it is exactly the kind of value `--redact` exists for: it is a capability
+token for a place somebody is standing.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from tlgr.models.base import Model
+
+__all__ = [
+    "GeoPoint",
+    "LiveLocation",
+    "LiveStopped",
+    "MapPreview",
+    "Nearby",
+    "NearbyPeer",
+    "SentLocation",
+    "Venue",
+]
+
+
+class GeoPoint(Model):
+    lat: float = 0.0
+    lon: float = 0.0
+    accuracy: int | None = None
+    access_hash: int | None = None
+
+
+class Venue(Model):
+    title: str = ""
+    address: str = ""
+    provider: str = ""
+    venue_id: str = ""
+    venue_type: str = ""
+    geo: GeoPoint | None = None
+
+
+class SentLocation(Model):
+    """What a `location send` / `location venue send` produced."""
+
+    id: int = 0
+    chat_id: int = 0
+    date: str = ""
+    date_unix: int = 0
+    geo: GeoPoint | None = None
+    venue: Venue | None = None
+
+
+class LiveLocation(Model):
+    """One live share — mine or somebody else's.
+
+    `expires_at` rather than `period` alone: a caller resuming after a restart
+    needs to know whether the share is still running, and a duration measured
+    from a start time it never saw does not answer that.
+    """
+
+    chat_id: int = 0
+    msg_id: int = 0
+    id: int = 0
+    peer_id: int | None = None
+    geo: GeoPoint | None = None
+    heading: int | None = None
+    proximity: int | None = None
+    period: int | None = None
+    expires_at: str | None = None
+    expires_at_unix: int | None = None
+    stopped: bool = False
+    mine: bool = False
+    date: str = ""
+    date_unix: int = 0
+
+
+class LiveStopped(Model):
+    """`location live stop`, which may have stopped several shares at once."""
+
+    stopped: bool = False
+    count: int = 0
+    items: list[LiveLocation] = []
+    already: bool = False
+
+
+class NearbyPeer(Model):
+    """A `updatePeerLocated` row: a person or a group near a point."""
+
+    peer_id: int = 0
+    kind: Literal["user", "group", "channel", "self"] = "user"
+    distance: int | None = None
+    expires: str | None = None
+    expires_unix: int | None = None
+
+
+class Nearby(Model):
+    """The people-nearby answer, plus what I published about myself."""
+
+    items: list[NearbyPeer] = []
+    self_expires: int | None = None
+    published: bool = False
+
+
+class MapPreview(Model):
+    """The rendered map thumbnail for a location message."""
+
+    chat_id: int = 0
+    msg_id: int = 0
+    path: str | None = None
+    bytes: int = 0
+    mime_type: str | None = None
+    zoom: int = 15
+    size: str = "512x512"
+    scale: int = 2
+    base64: str | None = None