maxapi-python 2.3.1__py3-none-any.whl → 2.4.1__py3-none-any.whl

pymax/protocol/tcp/payload.py

@@ -11,6 +11,8 @@ logger = get_logger(__name__)
 
 
 class MsgpackPayloadCodec:
+    WRAPPED_VALUE_EXT_CODE = 1
+
     def _to_msgpack_value(self, value: Any) -> Any:
         if isinstance(value, Enum):
             return value.value
@@ -30,10 +32,25 @@ class MsgpackPayloadCodec:
     def _unpack_stream(
         self, payload_bytes: bytes, *, raw: bool
     ) -> list[Any]:  # TODO: deprecate? idk
-        unpacker = msgpack.Unpacker(raw=raw, strict_map_key=False)
+        unpacker = msgpack.Unpacker(
+            raw=raw,
+            strict_map_key=False,
+            ext_hook=self._decode_ext,
+        )
         unpacker.feed(payload_bytes)
         return list(unpacker)
 
+    def _decode_ext(self, code: int, data: bytes) -> Any:
+        if code != self.WRAPPED_VALUE_EXT_CODE:
+            return msgpack.ExtType(code, data)
+
+        return msgpack.unpackb(
+            data,
+            raw=False,
+            strict_map_key=False,
+            ext_hook=self._decode_ext,
+        )
+
     def decode(self, payload_bytes: bytes) -> Any:
         if not payload_bytes:
             return {}
@@ -43,6 +60,7 @@ class MsgpackPayloadCodec:
                 payload_bytes,
                 raw=False,
                 strict_map_key=False,
+                ext_hook=self._decode_ext,
             )
 
         except msgpack.exceptions.ExtraData as e:
@@ -81,6 +99,8 @@ class TcpPayloadDecoder:
             return {self._normalize_key(k): self._normalize_keys(v) for k, v in obj.items()}
         if isinstance(obj, list):
             return [self._normalize_keys(item) for item in obj]
+        if isinstance(obj, msgpack.ExtType):
+            return obj
         if isinstance(obj, tuple):
             return tuple(self._normalize_keys(item) for item in obj)
         return obj

pymax/session/__init__.py

@@ -1,3 +1,3 @@
 from .models import SessionInfo
 from .protocol import StoreProtocol
-from .store import SessionStore
+from .store import InMemoryStore, SessionStore

pymax/session/models.py

@@ -1,11 +1,41 @@
 from pydantic import BaseModel, Field
 
+from pymax.api.session.payloads import MobileUserAgentPayload
 from pymax.types.domain.sync import SyncState
 
 
 class SessionInfo(BaseModel):
+    """Состояние авторизованной сессии, сохраняемое через ``StoreProtocol``.
+
+    Args:
+        token: Login token Max.
+        device_id: ID устройства, связанный с сессией.
+        phone: Номер телефона сессии; для web-сессии может быть пустой строкой.
+        mt_instance_id: Instance ID устройства. Пустая строка поддерживается для
+            сессий, созданных предыдущими версиями PyMax.
+        user_agent: Device/user-agent сессии. ``None`` поддерживается для старых
+            или пользовательских store, которые его не сохраняют.
+        sync: Последние sync-маркеры login.
+    """
+
     token: str
     device_id: str
     phone: str
     mt_instance_id: str = ""
+    user_agent: MobileUserAgentPayload | None = None
     sync: SyncState = Field(default_factory=SyncState)
+
+
+def resolve_session_user_agent(
+    current: MobileUserAgentPayload,
+    stored: MobileUserAgentPayload | None,
+) -> MobileUserAgentPayload:
+    if stored is None or stored.device_type != current.device_type:
+        return current
+
+    return stored.model_copy(
+        update={
+            "app_version": current.app_version,
+            "build_number": current.build_number,
+        }
+    )

pymax/session/protocol.py

@@ -5,10 +5,36 @@ from .models import SessionInfo
 
 @runtime_checkable
 class StoreProtocol(Protocol):
-    async def save_session(self, session_info: SessionInfo) -> None: ...
-    async def update_token(self, old_token: str, new_token: str) -> None: ...
-    async def load_session(self) -> SessionInfo | None: ...
-    async def load_session_by_device_id(self, device_id: str) -> SessionInfo | None: ...
-    async def load_session_by_phone(self, phone: str) -> SessionInfo | None: ...
-    async def delete_session(self, token: str) -> None: ...
-    async def close(self) -> None: ...
+    """Асинхронный контракт пользовательского хранилища сессии.
+
+    PyMax использует переданный ``ExtraConfig.store`` только при
+    ``persist_session=True`` и вызывает :meth:`close` при закрытии runtime.
+    """
+
+    async def save_session(self, session_info: SessionInfo) -> None:
+        """Сохраняет или полностью заменяет данные сессии."""
+        ...
+
+    async def update_token(self, old_token: str, new_token: str, /) -> None:
+        """Заменяет ``old_token`` у соответствующей сессии."""
+        ...
+
+    async def load_session(self) -> SessionInfo | None:
+        """Возвращает сессию для запуска клиента или ``None``."""
+        ...
+
+    async def load_session_by_device_id(self, device_id: str) -> SessionInfo | None:
+        """Ищет сессию по device ID."""
+        ...
+
+    async def load_session_by_phone(self, phone: str) -> SessionInfo | None:
+        """Ищет сессию по номеру телефона."""
+        ...
+
+    async def delete_session(self, token: str, /) -> None:
+        """Удаляет сессию с переданным token, если она существует."""
+        ...
+
+    async def close(self) -> None:
+        """Освобождает ресурсы хранилища при закрытии runtime."""
+        ...

pymax/session/store.py

@@ -2,10 +2,12 @@ from pathlib import Path
 
 import aiosqlite
 
+from pymax.api.session.payloads import MobileUserAgentPayload
 from pymax.logging import get_logger
 from pymax.types.domain.sync import DEFAULT_CONFIG_HASH, SyncState
 
 from .models import SessionInfo
+from .protocol import StoreProtocol
 
 logger = get_logger(__name__)
 
@@ -18,11 +20,64 @@ SESSION_COLUMNS = """
     contacts_sync,
     drafts_sync,
     presence_sync,
-    config_hash
+    config_hash,
+    user_agent
 """
 
 
-class SessionStore:
+class InMemoryStore(StoreProtocol):
+    """Хранилище одной сессии в памяти текущего runtime.
+
+    Данные не записываются на диск и становятся недоступны после пересоздания
+    ``App``. Обычно этот store выбирается автоматически при
+    ``ExtraConfig(persist_session=False)``.
+    """
+
+    def __init__(
+        self,
+    ) -> None:
+        self._session: SessionInfo | None = None
+
+    async def save_session(self, session_info: SessionInfo) -> None:
+        self._session = session_info
+
+    async def update_token(self, _: str, new_token: str) -> None:
+        if not self._session:
+            return
+        self._session.token = new_token
+
+    async def load_session(self) -> SessionInfo | None:
+        return self._session
+
+    async def load_session_by_device_id(self, device_id: str) -> SessionInfo | None:
+        if self._session and self._session.device_id != device_id:
+            return None
+
+        return self._session
+
+    async def load_session_by_phone(self, phone: str) -> SessionInfo | None:
+        if self._session and self._session.phone != phone:
+            return None
+
+        return self._session
+
+    async def delete_session(self, _: str) -> None:
+        self._session = None
+
+    async def close(self) -> None:
+        return None
+
+
+class SessionStore(StoreProtocol):
+    """SQLite-хранилище сессий, используемое по умолчанию.
+
+    Args:
+        work_dir: Директория файла базы данных; создается автоматически.
+        db_name: Имя файла базы данных. По умолчанию ``session.db``.
+
+    Схема существующего файла автоматически дополняется недостающими колонками.
+    """
+
     def __init__(self, work_dir: str, db_name: str = "session.db") -> None:
         self.work_dir = Path(work_dir)
         self.work_dir.mkdir(parents=True, exist_ok=True)
@@ -51,7 +106,8 @@ class SessionStore:
                 contacts_sync INTEGER NOT NULL DEFAULT -1,
                 drafts_sync INTEGER NOT NULL DEFAULT -1,
                 presence_sync INTEGER NOT NULL DEFAULT -1,
-                config_hash TEXT NOT NULL DEFAULT ''
+                config_hash TEXT NOT NULL DEFAULT '',
+                user_agent TEXT
             )
             """
         )
@@ -61,6 +117,7 @@ class SessionStore:
         await self._ensure_column(conn, "drafts_sync", "INTEGER NOT NULL DEFAULT -1")
         await self._ensure_column(conn, "presence_sync", "INTEGER NOT NULL DEFAULT -1")
         await self._ensure_column(conn, "config_hash", "TEXT NOT NULL DEFAULT ''")
+        await self._ensure_column(conn, "user_agent", "TEXT")
         await conn.execute(
             """
             UPDATE sessions
@@ -102,9 +159,10 @@ class SessionStore:
                 contacts_sync,
                 drafts_sync,
                 presence_sync,
-                config_hash
+                config_hash,
+                user_agent
             )
-            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+            VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
             """,
             (
                 session_info.token,
@@ -116,6 +174,11 @@ class SessionStore:
                 session_info.sync.drafts_sync,
                 session_info.sync.presence_sync,
                 session_info.sync.config_hash,
+                (
+                    session_info.user_agent.model_dump_json(by_alias=True, exclude_none=True)
+                    if session_info.user_agent is not None
+                    else None
+                ),
             ),
         )
         await conn.commit()
@@ -233,6 +296,11 @@ class SessionStore:
             device_id=row["device_id"],
             phone=row["phone"],
             mt_instance_id=row["mt_instance_id"] or "",
+            user_agent=(
+                MobileUserAgentPayload.model_validate_json(row["user_agent"])
+                if row["user_agent"] is not None
+                else None
+            ),
             sync=SyncState(
                 chats_sync=row["chats_sync"],
                 contacts_sync=row["contacts_sync"],

pymax/transport/tcp.py

@@ -1,4 +1,6 @@
 import asyncio
+import ssl
+from importlib import resources
 
 from python_socks.async_.asyncio import Proxy
 
@@ -7,6 +9,7 @@ from pymax.logging import get_logger
 from .base import Transport
 
 logger = get_logger(__name__)
+_CLOSE_TIMEOUT = 5.0
 
 
 class TCPTransport(Transport):
@@ -15,6 +18,10 @@ class TCPTransport(Transport):
         self._port = port
         self._proxy = proxy
         self._use_ssl = use_ssl
+        self._ssl_ctx = ssl.create_default_context()
+        self._ssl_ctx.load_verify_locations(
+            str(resources.files("pymax._data") / "rootca_ssl_rsa2022.crt")
+        )
         self._reader = None
         self._writer = None
 
@@ -25,6 +32,9 @@ class TCPTransport(Transport):
             self._port,
             self._use_ssl,
         )
+        ssl_ctx = self._ssl_ctx if self._use_ssl else None
+        server_hostname = self._host if self._use_ssl else None
+
         if self._proxy:
             logger.debug("tcp connecting via proxy %s", self._proxy)
             proxy = Proxy.from_url(self._proxy)
@@ -32,10 +42,9 @@ class TCPTransport(Transport):
                 dest_host=self._host,
                 dest_port=self._port,
             )
-            server_hostname = self._host if self._use_ssl else None
             self._reader, self._writer = await asyncio.open_connection(
                 sock=sock,
-                ssl=self._use_ssl,
+                ssl=ssl_ctx,
                 server_hostname=server_hostname,
             )
             logger.info(
@@ -49,7 +58,7 @@ class TCPTransport(Transport):
             self._reader, self._writer = await asyncio.open_connection(
                 self._host,
                 self._port,
-                ssl=self._use_ssl,
+                ssl=ssl_ctx,
             )
         logger.info(
             "tcp connected host=%s port=%s ssl=%s",
@@ -66,7 +75,11 @@ class TCPTransport(Transport):
         if writer:
             logger.debug("tcp close")
             writer.close()
-            await writer.wait_closed()
+            try:
+                await asyncio.wait_for(writer.wait_closed(), _CLOSE_TIMEOUT)
+            except (OSError, TimeoutError) as e:
+                logger.warning("tcp close did not finish cleanly: %s", e)
+                writer.transport.abort()
             logger.debug("tcp closed")
 
     async def send(self, data: bytes | str) -> None:

pymax/transport/websocket.py

@@ -17,11 +17,14 @@ class WebSocketTransport(Transport):
     async def connect(self) -> None:
         if self.proxy:
             self.ws = await client.connect(
-                self.url, origin=Origin("https://web.max.ru"), proxy=self.proxy
+                self.url,
+                origin=Origin("https://web.max.ru"),
+                proxy=self.proxy,
+                max_size=1024 * 1024 * 10,  # 10 MB
             )
         else:
             self.ws = await client.connect(
-                self.url, origin=Origin("https://web.max.ru")
+                self.url, origin=Origin("https://web.max.ru"), max_size=1024 * 1024 * 10
             )  # TODO: origin should be configurable
 
     async def close(self) -> None:
@@ -41,7 +44,7 @@ class WebSocketTransport(Transport):
         if self.ws is None or not self.connected:
             raise ConnectionError("Not connected to the server")
 
-        return await self.ws.recv(decode=True)
+        return await self.ws.recv(decode=False)
 
     @property
     def connected(self) -> bool:

pymax/types/domain/__init__.py

@@ -3,7 +3,8 @@ from .bots import InitData
 from .chat import Chat
 from .error import MaxApiError
 from .folder import Folder, FolderList, FolderUpdate
-from .login import LoginResponse
+from .handshake import HandshakeResponse
+from .login import Login2Flags, Login2Response, LoginResponse
 from .member import Member
 from .message import Message, ReactionCounter, ReactionInfo, ReadState
 from .name import Name

pymax/types/domain/attachments/__init__.py

@@ -2,10 +2,11 @@ from .audio import AudioAttachment
 from .call import CallAttachment
 from .contact import ContactAttachment
 from .control import ControlAttachment
-from .enums import AttachmentType
+from .enums import AttachmentType, PollFlags
 from .file import FileAttachment, FileRequest
 from .keyboards import InlineKeyboardAttachment
 from .photo import PhotoAttachment
+from .poll import Poll, PollAnswer, PollAttachment, PollState
 from .share import ShareAttachment
 from .sticker import StickerAttachment
 from .unknown import UnknownAttachment

pymax/types/domain/attachments/call.py

@@ -4,7 +4,7 @@ from pydantic import Field
 
 from pymax.types.domain.base import CamelModel
 
-from .enums import AttachmentType
+from .enums import AttachmentType, CallType, HangupType
 
 
 class CallAttachment(CamelModel):
@@ -18,9 +18,15 @@ class CallAttachment(CamelModel):
     :vartype conversation_id: str | int | None
     :ivar contact_ids: ID участников звонка.
     :vartype contact_ids: list[int]
+    :ivar call_type: Тип звонка, если Max его прислал.
+    :vartype call_type: CallType | None
+    :ivar hangup_type: Причина завершения звонка, если она есть в payload-е.
+    :vartype hangup_type: HangupType | None
     """
 
     type: Literal[AttachmentType.CALL] = Field(alias="_type")
     duration: int | None = None
     conversation_id: str | int | None = None
     contact_ids: list[int] = Field(default_factory=list)
+    call_type: CallType | None = None
+    hangup_type: HangupType | None = None

pymax/types/domain/attachments/contact.py

@@ -10,8 +10,8 @@ from .enums import AttachmentType
 class ContactAttachment(CamelModel):
     """Контактное вложение сообщения.
 
-    :ivar contact_id: ID контакта.
-    :vartype contact_id: int
+    :ivar contact_id: ID контакта, если Max его прислал.
+    :vartype contact_id: int | None
     :ivar first_name: Имя контакта.
     :vartype first_name: str | None
     :ivar last_name: Фамилия контакта.
@@ -24,7 +24,7 @@ class ContactAttachment(CamelModel):
     :vartype type: Literal[AttachmentType.CONTACT]
     """
 
-    contact_id: int
+    contact_id: int | None = None
     first_name: str | None = None
     last_name: str | None = None
     name: str | None = None

pymax/types/domain/attachments/control.py

@@ -14,7 +14,10 @@ class ControlAttachment(CamelModel):
     :vartype type: Literal[AttachmentType.CONTROL]
     :ivar event: Событие управления.
     :vartype event: str
+    :ivar title: Заголовок служебного события, если он есть в payload-е.
+    :vartype title: str | None
     """
 
     type: Literal[AttachmentType.CONTROL] = Field(alias="_type")
     event: str
+    title: str | None = None

pymax/types/domain/attachments/enums.py

@@ -1,4 +1,4 @@
-from enum import Enum
+from enum import Enum, IntFlag
 
 
 class AttachmentType(str, Enum):
@@ -14,6 +14,7 @@ class AttachmentType(str, Enum):
     CALL = "CALL"
     SHARE = "SHARE"
     INLINE_KEYBOARD = "INLINE_KEYBOARD"
+    POLL = "POLL"
     UNKNOWN = "UNKNOWN"
 
 
@@ -26,3 +27,34 @@ class TranscriptionStatus(str, Enum):
     PROCESSING = "PROCESSING"
     SUCCESS = "SUCCESS"
     UNKNOWN = "UNKNOWN"
+
+
+class PollFlags(IntFlag):
+    """Настройки опроса, представленные битовой маской.
+
+    Несколько настроек объединяются оператором ``|``. Числовые значения,
+    полученные от Max, автоматически преобразуются в ``PollFlags``.
+    """
+
+    FLAG_SETTINGS_ANONYMOUS = 1
+    FLAG_SETTINGS_MULTISELECT = 2
+    FLAG_SETTINGS_REVOTE = 4
+    FLAG_SETTINGS_CLOSED = 8
+    FLAG_SETTINGS_QUIZ = 16
+    FLAG_SETTINGS_CAN_FORWARD = 32
+
+
+class CallType(str, Enum):
+    """Тип звонка во входящем ``CallAttachment``."""
+
+    AUDIO = "AUDIO"
+    VIDEO = "VIDEO"
+
+
+class HangupType(str, Enum):
+    """Причина завершения звонка во входящем ``CallAttachment``."""
+
+    MISSED = "MISSED"
+    REJECTED = "REJECTED"
+    CANCELED = "CANCELED"
+    HUNGUP = "HUNGUP"

pymax/types/domain/attachments/poll.py

@@ -0,0 +1,111 @@
+from typing import Literal
+
+from pydantic import Field
+
+from pymax.types.domain.base import CamelModel
+
+from .enums import AttachmentType, PollFlags
+
+
+class PollAnswer(CamelModel):
+    """Вариант ответа в опросе.
+
+    :ivar text: Текст варианта ответа.
+    :vartype text: str
+    :ivar answer_id: ID варианта, назначенный Max.
+    :vartype answer_id: int | None
+    """
+
+    text: str
+    answer_id: int | None = None
+
+
+class PollVote(CamelModel):
+    """Голос пользователя за один вариант ответа.
+
+    :ivar timestamp: Время голосования в формате Unix time.
+    :vartype timestamp: int
+    :ivar user_id: ID проголосовавшего пользователя.
+    :vartype user_id: int
+    """
+
+    timestamp: int
+    user_id: int
+
+
+class PollResult(CamelModel):
+    """Результат голосования по одному варианту ответа.
+
+    :ivar answer_id: ID варианта ответа.
+    :vartype answer_id: int
+    :ivar vote_count: Количество голосов.
+    :vartype vote_count: int
+    :ivar votes: Голоса пользователей, доступные текущему аккаунту.
+    :vartype votes: list[PollVote]
+    :ivar rate: Доля голосов в формате, возвращаемом Max.
+    :vartype rate: int
+    :ivar options: Дополнительные параметры результата от Max.
+    :vartype options: int
+    """
+
+    answer_id: int
+    vote_count: int
+    votes: list[PollVote]
+    rate: int
+    options: int
+
+
+class PollState(CamelModel):
+    """Текущее состояние голосования.
+
+    :ivar total: Общее количество голосов.
+    :vartype total: int
+    :ivar result: Результаты по вариантам ответа.
+    :vartype result: list[PollResult] | None
+    :ivar voter_preview_ids: ID пользователей для предпросмотра списка
+        проголосовавших.
+    :vartype voter_preview_ids: list[int]
+    """
+
+    total: int = 0
+    result: list[PollResult] | None = None
+    voter_preview_ids: list[int]
+
+
+class Poll(CamelModel):
+    """Опрос для отправки в сообщении.
+
+    :ivar title: Вопрос или заголовок опроса.
+    :vartype title: str
+    :ivar answers: Варианты ответа.
+    :vartype answers: list[PollAnswer]
+    :ivar settings: Настройки опроса. Несколько ``PollFlags`` объединяются
+        оператором ``|``.
+    :vartype settings: PollFlags
+    :ivar type: Тип вложения.
+    :vartype type: Literal[AttachmentType.POLL]
+    """
+
+    title: str
+    answers: list[PollAnswer]
+    settings: PollFlags
+    type: Literal[AttachmentType.POLL] = Field(alias="_type", default=AttachmentType.POLL)
+
+
+class PollAttachment(Poll):
+    """Опрос, полученный как вложение сообщения.
+
+    Помимо параметров опроса содержит назначенный Max ID, версию и текущее
+    состояние голосования.
+
+    :ivar poll_id: ID опроса.
+    :vartype poll_id: int
+    :ivar version: Версия данных опроса.
+    :vartype version: int
+    :ivar state: Текущее состояние голосования.
+    :vartype state: PollState
+    """
+
+    poll_id: int
+    version: int
+    state: PollState

pymax/types/domain/attachments/sticker.py

@@ -42,7 +42,7 @@ class StickerAttachment(CamelModel):
     sticker_id: int
     tags: list[str] | None = None
     width: int
-    set_id: int
+    set_id: int | None = None
     time: int
     sticker_type: str
     audio: bool