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

pymax/files/voice.py

@@ -1,14 +1,26 @@
 from collections.abc import AsyncGenerator
 from pathlib import Path
 
-from .base import BaseFile
+from .base import TimedMediaFile
 
 
-class Voice(BaseFile):
+class Voice(TimedMediaFile):
     """Голосовое сообщение в формате OGG для отправки.
 
     Принимает ``path``, ``url`` или ``raw``. Для ``raw`` необходимо явно
-    передать имя файла.
+    передать имя файла. Длительность задается в миллисекундах; если она не
+    передана, требуется extra ``video`` для автоматического определения.
+
+    Args:
+        raw: Байты голосового сообщения.
+        path: Локальный путь к OGG-файлу.
+        url: URL OGG-файла.
+        name: Имя файла. Обязательно для ``raw``.
+        duration: Длительность в миллисекундах. ``None`` включает
+            автоматическое определение через extra ``video``.
+
+    Raises:
+        RuntimeError: При определении длительности без extra ``video``.
     """
 
     def __init__(
@@ -18,8 +30,10 @@ class Voice(BaseFile):
         path: str | None = None,
         url: str | None = None,
         name: str | None = None,
+        duration: int | None = None,
     ) -> None:
         self.name: str = name or ""
+        self.duration = duration
         if not self.name and path:
             self.name = Path(path).name
         elif not self.name and url:
@@ -27,7 +41,7 @@ class Voice(BaseFile):
 
         if not self.name:
             raise ValueError("Either name, url or path must be provided.")
-        super().__init__(raw=raw, url=url, path=path, name=self.name)
+        super().__init__(raw=raw, url=url, path=path, name=self.name, duration=self.duration)
 
     async def read(self) -> bytes:
         return await super().read()

pymax/fingerprint/fingerprint.py

@@ -1,47 +1,30 @@
 import hashlib
-import json
 import struct
-from importlib import resources
-from typing import Any
 
 from .models import ApkBuildFingerprint
 
 
 class FingerprintGenerator:
-    def __init__(
-        self,
-    ) -> None:
-        self.path = resources.files("pymax._data") / "apk_fingerprints.json"
-        self.data = self.load_fingerprints()
-
-    def load_fingerprints(self) -> Any:
-        with self.path.open("r", encoding="utf-8") as f:
-            return json.load(f)
+    def __init__(self, version_data: ApkBuildFingerprint) -> None:
+        self.data = version_data
 
     def generate_fingerprint(
         self,
-        version: str,
         device_id: str,
         calls_seed: int,
         arch: str = "arm64-v8a",
     ) -> bytes | None:
-        data = self.data.get(version)
-        if not data:
-            return None
-
-        model = ApkBuildFingerprint.model_validate(data)
-
         seed_bytes = struct.pack(">q", calls_seed)
         device_bytes = device_id.encode("utf-8")
 
         h1 = hashlib.sha256(
-            bytes.fromhex(model.certificate_meta_sha256) + seed_bytes + device_bytes
+            bytes.fromhex(self.data.certificate_meta_sha256) + seed_bytes + device_bytes
         ).digest()
         h2 = hashlib.sha256(
-            bytes.fromhex(model.dex_meta_sha256) + seed_bytes + device_bytes
+            bytes.fromhex(self.data.dex_meta_sha256) + seed_bytes + device_bytes
         ).digest()
         h3 = hashlib.sha256(
-            bytes.fromhex(model.so_meta_sha256[arch]) + seed_bytes + device_bytes
+            bytes.fromhex(self.data.so_meta_sha256[arch]) + seed_bytes + device_bytes
         ).digest()
 
         return h1 + h2 + h3

pymax/fingerprint/models.py

@@ -7,5 +7,6 @@ class ApkBuildFingerprint(BaseModel):
     certificate_meta_sha256: str
     certificate_sha256: list[str]
     dex_meta_sha256: str
+    so_meta_sha256_arm64_v8a: str
     so_meta_sha256: dict[str, str]
     build_number: int

pymax/infra/chat.py

@@ -1,4 +1,5 @@
 from pymax.api.chats import ChannelPermissions
+from pymax.files import Photo
 from pymax.types import Chat, Member, Message
 
 from .protocol import IClientProtocol
@@ -131,20 +132,23 @@ class ChatMixin(IClientProtocol):
     async def change_group_profile(
         self,
         chat_id: int,
-        name: str | None,
+        name: str | None = None,
         description: str | None = None,
+        photo: Photo | None = None,
     ) -> None:
-        """Обновляет название и описание группы.
+        """Обновляет название, описание или фотографию группы.
+
+        ``None`` исключает соответствующее поле из запроса. Фотография
+        автоматически загружается перед обновлением профиля.
 
         Args:
             chat_id: ID группы.
             name: Новое название.
             description: Новое описание.
+            photo: Новая фотография группы.
         """
         await self._app.api.chats.change_group_profile(
-            chat_id=chat_id,
-            name=name,
-            description=description,
+            chat_id=chat_id, name=name, description=description, photo=photo
         )
 
     async def join_group(self, link: str) -> Chat:

pymax/infra/message.py

@@ -1,3 +1,4 @@
+from pymax.api.messages import DateTimeUnion
 from pymax.api.messages.enums import ItemType
 from pymax.api.messages.service import SendAttachments
 from pymax.types import (
@@ -23,6 +24,7 @@ class MessageMixin(IClientProtocol):
         attachments: SendAttachments = None,
         *,
         notify: bool = True,
+        send_at: DateTimeUnion | None = None,
     ) -> Message:
         """Отправляет сообщение в чат.
 
@@ -32,6 +34,9 @@ class MessageMixin(IClientProtocol):
             reply_to: ID сообщения для ответа.
             attachments: Файлы, фотографии, видео или опросы для отправки.
             notify: Отправить ли получателям push-уведомление.
+            send_at: Время отложенной отправки: ``datetime`` для абсолютного
+                времени, ``timedelta`` для задержки или Unix time в секундах
+                как ``int``. ``None`` и ``0`` отправляют сообщение сразу.
 
         Returns:
             Отправленное сообщение.
@@ -45,6 +50,7 @@ class MessageMixin(IClientProtocol):
             reply_to,
             attachments,
             notify=notify,
+            send_at=send_at,
         )
 
     async def get_message(
@@ -272,7 +278,7 @@ class MessageMixin(IClientProtocol):
     async def add_reaction(
         self,
         chat_id: int,
-        message_id: str,
+        message_id: int,
         reaction: str,
     ) -> ReactionInfo | None:
         """Добавляет реакцию к сообщению.
@@ -294,7 +300,7 @@ class MessageMixin(IClientProtocol):
     async def get_reactions(
         self,
         chat_id: int,
-        message_ids: list[str],
+        message_ids: list[int],
     ) -> dict[str, ReactionInfo] | None:
         """Возвращает реакции для нескольких сообщений.
 
@@ -314,7 +320,7 @@ class MessageMixin(IClientProtocol):
     async def remove_reaction(
         self,
         chat_id: int,
-        message_id: str,
+        message_id: int,
     ) -> ReactionInfo | None:
         """Удаляет свою реакцию с сообщения.
 

pymax/infra/protocol.py

@@ -6,4 +6,8 @@ from pymax.app import App
 class IClientProtocol(Protocol):
     """Описывает минимальный клиент, нужный infra-миксинам."""
 
-    _app: App
+    @property
+    def _app(self) -> App: ...
+
+    @_app.setter
+    def _app(self, value: App) -> None: ...

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
 
@@ -16,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
 
@@ -26,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)
@@ -33,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(
@@ -50,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",

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

@@ -42,3 +42,19 @@ class PollFlags(IntFlag):
     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/video.py

@@ -32,8 +32,8 @@ class VideoAttachment(CamelModel):
     :vartype video_id: int
     :ivar duration: Длительность видео.
     :vartype duration: int | None
-    :ivar preview_data: Данные превью.
-    :vartype preview_data: bytes
+    :ivar preview_data: Данные превью, если Max их прислал.
+    :vartype preview_data: bytes | None
     :ivar type: Тип вложения.
     :vartype type: Literal[AttachmentType.VIDEO]
     :ivar thumbnail: URL миниатюры.
@@ -48,7 +48,7 @@ class VideoAttachment(CamelModel):
     width: int
     video_id: int
     duration: int | None = None
-    preview_data: bytes
+    preview_data: bytes | None = None
     type: Literal[AttachmentType.VIDEO] = Field(alias="_type")
     thumbnail: str
     token: str

pymax/types/domain/enums.py

@@ -22,3 +22,10 @@ class MessageStatus(str, Enum):
 
     EDITED = "EDITED"
     REMOVED = "REMOVED"
+
+
+class LinkType(str, Enum):
+    """Тип связи входящего сообщения с исходным сообщением."""
+
+    REPLY = "REPLY"
+    FORWARD = "FORWARD"