tlgr-cli 2.0.1__py3-none-any.whl

tlgr/models/net.py

@@ -0,0 +1,232 @@
+"""Network, data-centre, proxy and server-configuration shapes.
+
+The distinction these encode is the one v1 never made: **the server's
+configuration** (`help.getConfig`, `help.getAppConfig`) is not the same thing
+as **the connection** (which DC, which transport, how far the clock is off),
+and neither is **the proxy** (a client-side list with credentials in a 0600
+file). Three nouns, three shapes.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from tlgr.models.base import Model
+
+__all__ = [
+    "AppConfigDoc",
+    "Country",
+    "CountryCode",
+    "DcOption",
+    "InfoTopic",
+    "NearestDc",
+    "NetStatus",
+    "NetUsage",
+    "PingResult",
+    "PromoData",
+    "Proxy",
+    "ProxyLink",
+    "ProxyProbe",
+    "ProxySelection",
+    "ServerConfig",
+    "SyncCursors",
+]
+
+
+class DcOption(Model):
+    id: int
+    ip_address: str = ""
+    port: int = 0
+    ipv6: bool = False
+    media_only: bool = False
+    tcpo_only: bool = False
+    cdn: bool = False
+    static: bool = False
+    this_port_only: bool = False
+    secret: str | None = None
+    current: bool = False
+
+
+class NearestDc(Model):
+    country: str = ""
+    this_dc: int = 0
+    nearest_dc: int = 0
+    current_dc: int | None = None
+
+
+class PingResult(Model):
+    account: str = ""
+    dc_id: int | None = None
+    proxy: str | None = None
+    probes: int = 0
+    min_ms: float | None = None
+    avg_ms: float | None = None
+    max_ms: float | None = None
+    loss: float = 0.0
+
+
+class SyncCursors(Model):
+    """pts/qts/seq/date, the four numbers the update transport turns on."""
+
+    pts: int | None = None
+    qts: int | None = None
+    seq: int | None = None
+    date: str | None = None
+    date_unix: int | None = None
+
+
+class NetStatus(Model):
+    account: str = ""
+    authorized: bool = False
+    connected: bool = False
+    phase: str = "disconnected"
+    dc_id: int | None = None
+    dc_address: str | None = None
+    ipv6: bool = False
+    transport: str = ""
+    proxy: str | None = None
+    ping_ms: float | None = None
+    layer: int = 0
+    #: |offset| > 30 s is reported as a warning: it pushes msg_ids outside the
+    #: server's window, and requests are then dropped with no error at all.
+    time_offset_seconds: int = 0
+    exported_senders: int = 0
+    reconnects: int = 0
+    last_error: str | None = None
+    state: SyncCursors | None = None
+    behind_seconds: int | None = None
+    frozen: bool = False
+
+
+class NetUsage(Model):
+    account: str = ""
+    since: str = ""
+    rpc_bytes_sent: int = 0
+    rpc_bytes_received: int = 0
+    download_bytes: int = 0
+    upload_bytes: int = 0
+    requests: int = 0
+    updates_received: int = 0
+    reconnects: int = 0
+
+
+class Proxy(Model):
+    """A saved proxy. Credentials live in a 0600 file and are never printed."""
+
+    id: str
+    name: str = ""
+    type: str = "socks5"
+    host: str = ""
+    port: int = 0
+    user: str | None = None
+    rdns: bool = True
+    active: bool = False
+    order: int = 0
+    last_ping_ms: float | None = None
+    last_ok_at: str | None = None
+    failures: int = 0
+    has_password: bool = False
+    has_secret: bool = False
+
+
+class ProxyProbe(Model):
+    id: str = ""
+    name: str = ""
+    ok: bool = False
+    ping_ms: float | None = None
+    dc_id: int | None = None
+    error: str | None = None
+
+
+class ProxyLink(Model):
+    id: str
+    link: str
+    type: str = ""
+    host: str = ""
+    port: int = 0
+    qr: str | None = None
+
+
+class ProxySelection(Model):
+    active: str | None = None
+    type: str = ""
+    host: str = ""
+    port: int = 0
+    reconnected: bool = False
+    accounts: list[str] = []
+    removed: bool = False
+    was_active: bool = False
+
+
+class ServerConfig(Model):
+    """`help.getConfig`, the fields a client actually acts on."""
+
+    expires: str | None = None
+    test_mode: bool = False
+    this_dc: int = 0
+    date: str | None = None
+    date_unix: int | None = None
+    chat_size_max: int = 0
+    megagroup_size_max: int = 0
+    message_length_max: int = 0
+    caption_length_max: int = 0
+    online_update_period_ms: int = 0
+    offline_blur_timeout_ms: int = 0
+    offline_idle_timeout_ms: int = 0
+    edit_time_limit: int = 0
+    revoke_time_limit: int = 0
+    rating_e_decay: int = 0
+    forwarded_count_max: int = 0
+    push_chat_period_ms: int = 0
+    dc_options: list[DcOption] = []
+    values: dict[str, Any] = {}
+
+
+class AppConfigDoc(Model):
+    """`help.getAppConfig`, hash-cached, with the freeze fields lifted out."""
+
+    hash: int = 0
+    not_modified: bool = False
+    freeze_since_date: str | None = None
+    freeze_until_date: str | None = None
+    freeze_appeal_url: str | None = None
+    values: dict[str, Any] = {}
+    config: ServerConfig | None = None
+
+
+class CountryCode(Model):
+    country_code: str = ""
+    prefixes: list[str] = []
+    patterns: list[str] = []
+
+
+class Country(Model):
+    iso2: str
+    name: str = ""
+    default_name: str = ""
+    hidden: bool = False
+    flag_emoji: str = ""
+    preferred_language: str = ""
+    codes: list[CountryCode] = []
+    #: Filled only by `--phone`: what the number was classified as.
+    matched_prefix: str | None = None
+    valid: bool | None = None
+
+
+class InfoTopic(Model):
+    """One of the flat `help.*` / `langpack.*` read-only endpoints."""
+
+    topic: str
+    items: list[dict[str, Any]] = []
+    raw: dict[str, Any] = {}
+
+
+class PromoData(Model):
+    kind: str = "none"
+    chat_id: int | None = None
+    psa_type: str | None = None
+    psa_message: str | None = None
+    proxy: bool = False
+    expires: str | None = None
+    hidden: bool = False
+    pending_suggestions: list[str] = []

tlgr/models/notify.py

@@ -0,0 +1,105 @@
+"""The Notifications screen: scopes, per-chat exceptions, reactions, sounds.
+
+Telegram spreads one screen over three unrelated APIs — `getNotifySettings`
+for the scopes and the chats, `getReactionsNotifySettings` for the reaction
+alerts, `getContactSignUpNotification` for "X joined Telegram" — so the
+model, like the command, is one shape with a `target` naming which of them
+answered.
+
+`mute_until` is an **absolute UNIX timestamp**, and the second field exists
+to say so. v1 computed it from the asyncio event loop's clock, which is an
+arbitrary monotonic origin: "mute for an hour" produced a timestamp somewhere
+in 1970 and the chat was never muted at all.
+"""
+
+from __future__ import annotations
+
+from tlgr.models.base import Model
+from tlgr.models.dialog import NotifySettings
+from tlgr.models.peer import Peer
+
+__all__ = [
+    "ExceptionsCleared",
+    "NotifyException",
+    "NotifyReset",
+    "NotifyTarget",
+    "Ringtone",
+    "RingtoneSaved",
+]
+
+
+class NotifyTarget(Model):
+    """Notification settings for one target, whatever kind of target it is.
+
+    `target` is the word the caller typed (`private`, `groups`, `channels`,
+    `stories`, `reactions`, `contact-joined`, or a chat reference), so the
+    answer can be piped straight back into `notify set`.
+    """
+
+    target: str
+    kind: str = "scope"
+    chat_id: int | None = None
+    chat: Peer | None = None
+    topic: int | None = None
+    settings: NotifySettings | None = None
+    muted: bool | None = None
+    mute_until: str | None = None
+    mute_until_unix: int | None = None
+    show_previews: bool | None = None
+    sound: str | None = None
+    stories_muted: bool | None = None
+    stories_hide_sender: bool | None = None
+    stories_sound: str | None = None
+    #: `reactions` target: contacts | all | off, one per alert kind.
+    messages_from: str | None = None
+    stories_from: str | None = None
+    poll_votes_from: str | None = None
+    #: `contact-joined` target. Stored inverted on the wire (`silent=true`).
+    contact_joined: bool | None = None
+    changed: list[str] = []
+    already: bool = False
+
+
+class NotifyException(Model):
+    """A chat whose settings differ from its scope default."""
+
+    chat_id: int
+    chat: Peer | None = None
+    title: str = ""
+    muted: bool = False
+    mute_until: str | None = None
+    mute_until_unix: int | None = None
+    show_previews: bool | None = None
+    sound: str | None = None
+    stories_muted: bool | None = None
+    scope: str = ""
+
+
+class ExceptionsCleared(Model):
+    cleared: int = 0
+    chat_ids: list[int] = []
+    scope: str | None = None
+    already: bool = False
+
+
+class NotifyReset(Model):
+    ok: bool
+
+
+class Ringtone(Model):
+    id: int
+    access_hash: int | None = None
+    file_name: str = ""
+    mime_type: str = ""
+    size: int = 0
+    duration: int | None = None
+
+
+class RingtoneSaved(Model):
+    id: int | None = None
+    file_name: str | None = None
+    #: The server may hand back a *new* document id when an existing voice
+    #: message is saved as a ringtone; using the old one afterwards fails.
+    converted: bool = False
+    removed: bool = False
+    already: bool = False

tlgr/models/page.py

@@ -0,0 +1,32 @@
+"""The one paginated shape: `Page[T]`."""
+
+from __future__ import annotations
+
+from typing import Generic, TypeVar
+
+from tlgr.models.base import Model
+
+__all__ = ["Page", "PageInfo"]
+
+T = TypeVar("T")
+
+
+class Page(Model, Generic[T]):
+    """A slice of a longer list.
+
+    `total` is the server's own count where it gives one and `null` otherwise;
+    it is never estimated, because a wrong total is worse than no total.
+    """
+
+    items: list[T] = []
+    has_more: bool = False
+    next_cursor: str | None = None
+    total: int | None = None
+
+
+class PageInfo(Model):
+    """The pagination half of a response envelope, without the items."""
+
+    has_more: bool = False
+    next_cursor: str | None = None
+    total: int | None = None

tlgr/models/payment.py

@@ -0,0 +1,172 @@
+"""Payments, read-only by design.
+
+tlgr models the whole checkout surface — the invoice, the form, the receipt,
+the subscription — and implements every verb that does *not* move money.
+`PaymentForm.payable_here` is therefore always false and carries the reason:
+the shape a caller needs in order to decide is here, the button that would
+charge is deliberately not, and saying so in the payload is better than
+leaving a caller to discover it from an exit code.
+
+Amounts are integers in the smallest unit of `currency`, exactly as Telegram
+sends them (`XTR` means Telegram Stars, whose smallest unit is one Star).
+Rounding them into a float here would lose money in the last decimal on every
+currency that has three of them.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from tlgr.models.base import Model
+
+__all__ = [
+    "BankCard",
+    "Invoice",
+    "InvoiceLink",
+    "InvoiceSent",
+    "PaymentForm",
+    "PaymentInfo",
+    "PaymentInfoCleared",
+    "PriceLine",
+    "Receipt",
+    "StarSubscription",
+    "SubscriptionChange",
+]
+
+
+class PriceLine(Model):
+    label: str = ""
+    amount: int = 0
+
+
+class Invoice(Model):
+    """The invoice itself: what is being charged for, and what it needs."""
+
+    currency: str = ""
+    total_amount: int = 0
+    prices: list[PriceLine] = []
+    test: bool = False
+    name_requested: bool = False
+    phone_requested: bool = False
+    email_requested: bool = False
+    shipping_address_requested: bool = False
+    flexible: bool = False
+    recurring: bool = False
+    terms_url: str | None = None
+    subscription_period: int | None = None
+    max_tip_amount: int | None = None
+    suggested_tip_amounts: list[int] = []
+
+
+class PaymentForm(Model):
+    """A checkout form, read without paying for it."""
+
+    form_kind: str = "form"
+    form_id: int = 0
+    bot_id: int | None = None
+    provider_id: int | None = None
+    title: str | None = None
+    description: str | None = None
+    photo: str | None = None
+    invoice: Invoice | None = None
+    currency: str = ""
+    total_amount: int = 0
+    prices: list[PriceLine] = []
+    tip_amounts: list[int] = []
+    recurring: bool = False
+    terms_url: str | None = None
+    subscription_period: int | None = None
+    url: str | None = None
+    native_provider: str | None = None
+    native_params: Any = None
+    additional_methods: list[dict[str, Any]] = []
+    saved_info: dict[str, Any] | None = None
+    saved_credentials: list[dict[str, Any]] = []
+    can_save_credentials: bool = False
+    password_missing: bool = False
+    expires_at: str | None = None
+    #: Always false, and always *emitted*: an omitted flag would leave a
+    #: caller to infer the policy, and `reason` says which one it is.
+    payable_here: bool | None = None
+    reason: str = ""
+
+
+class Receipt(Model):
+    date: str | None = None
+    date_unix: int | None = None
+    bot_id: int | None = None
+    provider_id: int | None = None
+    title: str | None = None
+    description: str | None = None
+    invoice: Invoice | None = None
+    currency: str = ""
+    total_amount: int = 0
+    tip_amount: int | None = None
+    credentials_title: str | None = None
+    shipping: dict[str, Any] | None = None
+    info: dict[str, Any] | None = None
+    transaction_id: str | None = None
+    recurring: bool = False
+    refunded: bool = False
+
+
+class PaymentInfo(Model):
+    """My saved order information and saved cards. Never a card number."""
+
+    has_saved_credentials: bool | None = None
+    credentials: list[dict[str, Any]] = []
+    saved_info: dict[str, Any] | None = None
+    name: str | None = None
+    phone: str | None = None
+    email: str | None = None
+    shipping: dict[str, Any] | None = None
+    has_saved_info: bool | None = None
+    cleared: bool = False
+
+
+class PaymentInfoCleared(Model):
+    credentials_cleared: bool | None = None
+    info_cleared: bool | None = None
+
+
+class InvoiceLink(Model):
+    url: str = ""
+    slug: str = ""
+
+
+class InvoiceSent(Model):
+    chat_id: int = 0
+    msg_id: int = 0
+    slug: str | None = None
+    currency: str = ""
+    total_amount: int = 0
+
+
+class BankCard(Model):
+    title: str = ""
+    open_urls: list[dict[str, str]] = []
+
+
+class StarSubscription(Model):
+    id: str = ""
+    peer: int | None = None
+    until_date: str | None = None
+    until_date_unix: int | None = None
+    pricing: dict[str, int] | None = None
+    cancelled: bool | None = None
+    #: Re-joining a lapsed subscription debits Stars, so tlgr reports that the
+    #: server would allow it and still refuses to do it.
+    can_refulfill: bool | None = None
+    missing_balance: bool | None = None
+    invoice_slug: str | None = None
+    chat_invite_hash: str | None = None
+    title: str | None = None
+    photo: str | None = None
+
+
+class SubscriptionChange(Model):
+    subscription_id: str | None = None
+    user_id: int | None = None
+    charge_id: str | None = None
+    cancelled: bool | None = None
+    until_date: str | None = None