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

pymax/dispatch/mapping.py

@@ -6,7 +6,7 @@ from typing import TYPE_CHECKING
 from pymax.api.binding import bind_api_model
 from pymax.protocol import InboundFrame, Opcode
 from pymax.protocol.enums import Command
-from pymax.types import Chat, MessageDeleteEvent
+from pymax.types import AudioUploadSignal, Chat, MessageDeleteEvent
 from pymax.types.domain import Message
 from pymax.types.events import (
     FileUploadSignal,
@@ -100,4 +100,6 @@ class EventMapper:
                 return VideoUploadSignal.model_validate(frame.payload)
             elif event_type == EventType.FILE_READY:
                 return FileUploadSignal.model_validate(frame.payload)
+            elif event_type == EventType.VOICE_READY:
+                return AudioUploadSignal.model_validate(frame.payload)
         return frame

pymax/dispatch/resolvers.py

@@ -3,7 +3,7 @@ from pydantic import ValidationError
 from pymax.logging import get_logger
 from pymax.protocol import InboundFrame
 from pymax.protocol.enums import Opcode
-from pymax.types import Message
+from pymax.types import AudioUploadSignal, Message
 from pymax.types.domain.enums import MessageStatus
 from pymax.types.events import FileUploadSignal, VideoUploadSignal
 
@@ -49,6 +49,12 @@ def resolve_attach(frame: InboundFrame) -> EventType | None:
     except ValidationError:
         logger.debug("attach event is not a video upload signal")
 
+    try:
+        AudioUploadSignal.model_validate(frame.payload)
+        return EventType.VOICE_READY
+    except ValidationError:
+        logger.debug("attach event is not a voice upload signal")
+
     return None
 
 

pymax/files/__init__.py

@@ -1,9 +1,12 @@
 from .file import File
 from .photo import Photo
-from .video import Video
+from .video import Video, VideoNote
+from .voice import Voice
 
 __all__ = (
     "File",
     "Photo",
     "Video",
+    "VideoNote",
+    "Voice",
 )

pymax/files/base.py

@@ -1,10 +1,16 @@
 import os
 from abc import ABC, abstractmethod
 from collections.abc import AsyncGenerator
+from io import BytesIO
 
 import aiofiles
 import aiohttp
 
+try:
+    from tinytag import TinyTag
+except ImportError:
+    TinyTag = None
+
 
 class BaseFile(ABC):
     def __init__(
@@ -56,7 +62,7 @@ class BaseFile(ABC):
 
         if self.url:
             async with aiohttp.ClientSession() as session:  # noqa: SIM117
-                async with session.head(self.url) as resp:
+                async with session.head(self.url, allow_redirects=True) as resp:
                     return int(resp.headers["Content-Length"])
         else:
             raise ValueError("Path or Url must be provided")
@@ -85,3 +91,54 @@ class BaseFile(ABC):
                     resp.raise_for_status()
                     async for chunk in resp.content.iter_chunked(size):
                         yield chunk
+
+
+class TimedMediaFile(BaseFile):
+    def __init__(
+        self,
+        raw: bytes | None = None,
+        *,
+        path: str | None,
+        url: str | None,
+        name: str | None,
+        duration: int | None,
+    ) -> None:
+        self.duration = duration
+        super().__init__(raw, path=path, url=url, name=name)
+
+    async def get_duration(self) -> int:
+        if self.duration is not None:
+            return self.duration
+
+        if not TinyTag:
+            raise RuntimeError(
+                "Automatic video duration detection requires the 'video' extra. "
+                "Install it with `uv add 'maxapi-python[video]'` "
+                "or pass duration manually."
+            )
+
+        if self.raw:
+            tag = TinyTag.get(
+                filename=self.name,
+                file_obj=BytesIO(self.raw),
+                tags=False,
+                duration=True,
+            )
+        elif self.path:
+            tag = TinyTag.get(
+                filename=self.path,
+                tags=False,
+                duration=True,
+            )
+        else:
+            tag = TinyTag.get(
+                filename=self.name,
+                file_obj=BytesIO(await self.read()),
+                tags=False,
+                duration=True,
+            )
+
+        if tag.duration is None:
+            raise ValueError("Failed to determine video duration.")
+
+        return round(tag.duration * 1000)

pymax/files/video.py

@@ -1,7 +1,7 @@
 from collections.abc import AsyncGenerator
 from pathlib import Path
 
-from .base import BaseFile
+from .base import BaseFile, TimedMediaFile
 
 
 class Video(BaseFile):
@@ -72,3 +72,53 @@ class Video(BaseFile):
             Async generator с байтами.
         """
         return super().iter_chunks(size)
+
+
+class VideoNote(TimedMediaFile):
+    """Круглое видеосообщение для отправки.
+
+    Принимает те же источники, что и ``Video``. Длительность задается в
+    миллисекундах. Если она не передана, требуется extra ``video`` для
+    автоматического определения длительности.
+
+    Args:
+        raw: Байты видеосообщения.
+        url: URL видеосообщения.
+        path: Локальный путь к видеосообщению.
+        name: Имя файла. Обязательно для ``raw``.
+        duration: Длительность в миллисекундах. ``None`` включает
+            автоматическое определение через extra ``video``.
+
+    Raises:
+        RuntimeError: При определении длительности без extra ``video``.
+    """
+
+    def __init__(
+        self,
+        raw: bytes | None = None,
+        *,
+        url: str | None = None,
+        path: str | None = None,
+        name: str | None = None,
+        duration: int | None = None,
+    ) -> None:
+        self.duration = duration
+        self.name: str = name or ""
+        if not self.name and path:
+            self.name = Path(path).name
+        elif not self.name and url:
+            self.name = Path(url).name
+
+        if not self.name:
+            raise ValueError("Either name, url or path must be provided.")
+
+        super().__init__(raw, url=url, path=path, name=self.name, duration=self.duration)
+
+    async def read(self) -> bytes:
+        return await super().read()
+
+    def iter_chunks(self, size: int) -> AsyncGenerator[bytes, None]:
+        return super().iter_chunks(size)
+
+    async def size(self) -> int:
+        return await super().size()

pymax/files/voice.py

@@ -0,0 +1,53 @@
+from collections.abc import AsyncGenerator
+from pathlib import Path
+
+from .base import TimedMediaFile
+
+
+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__(
+        self,
+        raw: bytes | None = None,
+        *,
+        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:
+            self.name = Path(url).name
+
+        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, duration=self.duration)
+
+    async def read(self) -> bytes:
+        return await super().read()
+
+    async def size(self) -> int:
+        return await super().size()
+
+    def iter_chunks(self, size: int) -> AsyncGenerator[bytes, None]:
+        return super().iter_chunks(size)

pymax/fingerprint/__init__.py

@@ -0,0 +1 @@
+from .fingerprint import FingerprintGenerator

pymax/fingerprint/fingerprint.py

@@ -0,0 +1,30 @@
+import hashlib
+import struct
+
+from .models import ApkBuildFingerprint
+
+
+class FingerprintGenerator:
+    def __init__(self, version_data: ApkBuildFingerprint) -> None:
+        self.data = version_data
+
+    def generate_fingerprint(
+        self,
+        device_id: str,
+        calls_seed: int,
+        arch: str = "arm64-v8a",
+    ) -> bytes | None:
+        seed_bytes = struct.pack(">q", calls_seed)
+        device_bytes = device_id.encode("utf-8")
+
+        h1 = hashlib.sha256(
+            bytes.fromhex(self.data.certificate_meta_sha256) + seed_bytes + device_bytes
+        ).digest()
+        h2 = hashlib.sha256(
+            bytes.fromhex(self.data.dex_meta_sha256) + seed_bytes + device_bytes
+        ).digest()
+        h3 = hashlib.sha256(
+            bytes.fromhex(self.data.so_meta_sha256[arch]) + seed_bytes + device_bytes
+        ).digest()
+
+        return h1 + h2 + h3

pymax/fingerprint/models.py

@@ -0,0 +1,12 @@
+from pydantic import BaseModel
+
+
+class ApkBuildFingerprint(BaseModel):
+    signature_scheme: str
+    certificate_count: int
+    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/auth.py

@@ -95,3 +95,7 @@ class AuthMixin(IClientProtocol):
         """
 
         return await self._app.api.auth.check_2fa()
+
+    def is_update_available(self) -> bool:
+        """Возвращает признак доступного обновления приложения по handshake."""
+        return self._app.api.auth.is_update_available()

pymax/infra/bots.py

@@ -9,14 +9,14 @@ class BotsMixin(IClientProtocol):
     async def get_bot_init_data(
         self,
         bot_id: int,
-        chat_id: int,
+        chat_id: int | None = None,
         start_param: str | None = None,
     ) -> InitData:
-        """Получает начальные данные для бота в контексте конкретного чата.
+        """Получает начальные данные для запуска бота.
 
         Args:
             bot_id: Идентификатор бота.
-            chat_id: Идентификатор чата, в котором бот будет использоваться.
+            chat_id: Необязательный ID чата, в котором бот будет использоваться.
             start_param: Необязательный параметр, передаваемый при запуске
                 бота.
 

pymax/infra/chat.py

@@ -1,3 +1,5 @@
+from pymax.api.chats import ChannelPermissions
+from pymax.files import Photo
 from pymax.types import Chat, Member, Message
 
 from .protocol import IClientProtocol
@@ -130,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:
@@ -211,6 +216,28 @@ class ChatMixin(IClientProtocol):
         """
         return await self._app.api.chats.get_chat(chat_id)
 
+    async def get_chat_members(
+        self,
+        chat_id: int,
+        marker: int | None = None,
+        count: int = 50,
+    ) -> tuple[list[Member], int]:
+        """Возвращает страницу участников чата по ID.
+
+        Args:
+            chat_id: ID чата.
+            marker: Маркер страницы. Если ``None``, запрашивается первая
+                страница.
+            count: Максимальное количество участников в ответе.
+
+        Returns:
+            ``(members, next_marker)``. Если участников больше, чем
+            уместилось в ответ, ``next_marker`` ненулевой — передайте его в
+            следующий вызов, чтобы получить следующую страницу. ``0``
+            означает, что дальше страниц нет.
+        """
+        return await self._app.api.chats.get_chat_members(chat_id, marker, count)
+
     async def leave_group(self, chat_id: int) -> None:
         """Выходит из группы.
 
@@ -372,3 +399,18 @@ class ChatMixin(IClientProtocol):
             Канал, в который вступил клиент.
         """
         return await self._app.api.chats.join_channel(link=link)
+
+    async def add_admin(
+        self,
+        chat_id: int,
+        user_id: int,
+        permissions: list[ChannelPermissions],
+    ) -> None:
+        """Назначает пользователя администратором канала.
+
+        Args:
+            chat_id: ID канала.
+            user_id: ID пользователя.
+            permissions: Непустой список прав администратора.
+        """
+        return await self._app.api.chats.add_admin(chat_id, user_id, permissions)

pymax/infra/message.py

@@ -1,8 +1,10 @@
+from pymax.api.messages import DateTimeUnion
 from pymax.api.messages.enums import ItemType
 from pymax.api.messages.service import SendAttachments
 from pymax.types import (
     FileRequest,
     Message,
+    PollState,
     ReactionInfo,
     ReadState,
     VideoRequest,
@@ -17,23 +19,30 @@ class MessageMixin(IClientProtocol):
     async def send_message(
         self,
         chat_id: int,
-        text: str,
+        text: str | None = None,
         reply_to: int | None = None,
         attachments: SendAttachments = None,
         *,
         notify: bool = True,
-    ) -> Message | None:
+        send_at: DateTimeUnion | None = None,
+    ) -> Message:
         """Отправляет сообщение в чат.
 
         Args:
             chat_id: ID чата.
-            text: Текст сообщения.
+            text: Текст сообщения. Можно не передавать при наличии вложений.
             reply_to: ID сообщения для ответа.
-            attachments: Файлы, фотографии или видео для отправки.
+            attachments: Файлы, фотографии, видео или опросы для отправки.
             notify: Отправить ли получателям push-уведомление.
+            send_at: Время отложенной отправки: ``datetime`` для абсолютного
+                времени, ``timedelta`` для задержки или Unix time в секундах
+                как ``int``. ``None`` и ``0`` отправляют сообщение сразу.
 
         Returns:
-            Отправленное сообщение или ``None``, если сервер не вернул его.
+            Отправленное сообщение.
+
+        Raises:
+            ValueError: Если не переданы ни текст, ни вложения.
         """
         return await self._app.api.messages.send_message(
             chat_id,
@@ -41,6 +50,7 @@ class MessageMixin(IClientProtocol):
             reply_to,
             attachments,
             notify=notify,
+            send_at=send_at,
         )
 
     async def get_message(
@@ -69,7 +79,7 @@ class MessageMixin(IClientProtocol):
         source_chat_id: int | None = None,
         *,
         notify: bool = True,
-    ) -> Message | None:
+    ) -> Message:
         """Пересылает существующее сообщение в чат.
 
         Args:
@@ -80,7 +90,7 @@ class MessageMixin(IClientProtocol):
             notify: Отправить ли получателям push-уведомление.
 
         Returns:
-            Пересланное сообщение или ``None``, если сервер не вернул его.
+            Пересланное сообщение.
         """
         return await self._app.api.messages.forward_message(
             chat_id=chat_id,
@@ -112,7 +122,7 @@ class MessageMixin(IClientProtocol):
         self,
         chat_id: int,
         message_id: int,
-        text: str,
+        text: str | None = None,
         attachments: SendAttachments = None,
     ) -> Message:
         """Редактирует текст и вложения сообщения.
@@ -121,7 +131,7 @@ class MessageMixin(IClientProtocol):
             chat_id: ID чата.
             message_id: ID сообщения.
             text: Новый текст сообщения с поддержкой markdown.
-            attachments: Новые файлы, фотографии или видео для сообщения.
+            attachments: Новые файлы, фотографии, видео или опросы для сообщения.
 
         Returns:
             Отредактированное сообщение.
@@ -145,7 +155,7 @@ class MessageMixin(IClientProtocol):
         get_chat: bool = False,
         get_messages: bool = True,
         interactive: bool = False,
-    ) -> list[Message] | None:
+    ) -> list[Message]:
         """Загружает историю сообщений чата.
 
         Args:
@@ -162,7 +172,7 @@ class MessageMixin(IClientProtocol):
             interactive: Пометить запрос как интерактивный.
 
         Returns:
-            Сообщения или ``None``, если сервер не вернул список.
+            Список сообщений. Если сервер не вернул сообщения, список пуст.
         """
         return await self._app.api.messages.fetch_history(
             chat_id=chat_id,
@@ -268,7 +278,7 @@ class MessageMixin(IClientProtocol):
     async def add_reaction(
         self,
         chat_id: int,
-        message_id: str,
+        message_id: int,
         reaction: str,
     ) -> ReactionInfo | None:
         """Добавляет реакцию к сообщению.
@@ -290,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:
         """Возвращает реакции для нескольких сообщений.
 
@@ -310,7 +320,7 @@ class MessageMixin(IClientProtocol):
     async def remove_reaction(
         self,
         chat_id: int,
-        message_id: str,
+        message_id: int,
     ) -> ReactionInfo | None:
         """Удаляет свою реакцию с сообщения.
 
@@ -344,3 +354,28 @@ class MessageMixin(IClientProtocol):
             message_id=message_id,
             chat_id=chat_id,
         )
+
+    async def vote_poll(
+        self,
+        chat_id: int,
+        message_id: int,
+        poll_id: int,
+        answer_ids: list[int],
+    ) -> PollState:
+        """Отправляет выбранные ответы в опросе.
+
+        Args:
+            chat_id: ID чата с опросом.
+            message_id: ID сообщения с опросом.
+            poll_id: ID опроса из ``PollAttachment.poll_id``.
+            answer_ids: ID выбранных вариантов ответа.
+
+        Returns:
+            Обновленное состояние опроса.
+        """
+        return await self._app.api.messages.vote_poll(
+            chat_id=chat_id,
+            message_id=message_id,
+            poll_id=poll_id,
+            answer_ids=answer_ids,
+        )

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/infra/self.py

@@ -1,5 +1,7 @@
 from typing import Any
 
+from pymax.api.self import PrivacySettingsUpdate
+from pymax.files import Photo
 from pymax.types import FolderList, FolderUpdate
 
 from .protocol import IClientProtocol
@@ -19,7 +21,7 @@ class SelfMixin(IClientProtocol):
         first_name: str,
         last_name: str | None = None,
         description: str | None = None,
-        photo: Any | None = None,
+        photo: Photo | None = None,
         *,
         photo_token: str | None = None,
     ) -> bool:
@@ -133,3 +135,25 @@ class SelfMixin(IClientProtocol):
             ``True``, если сервер принял запрос на выход.
         """
         return await self._app.api.account.logout()
+
+    def set_presence(self, *, online: bool) -> None:
+        """Устанавливает статус присутствия текущего аккаунта.
+
+        Статус применяется не мгновенно, а при следующем запросе login/ping.
+
+        Args:
+            online: ``True``, если нужно установить статус "в сети", иначе
+                ``False``.
+        """
+        self._app.api.account.set_presence(online)
+
+    async def change_profile_settings(self, settings: PrivacySettingsUpdate) -> bool:
+        """Обновляет настройки приватности текущего аккаунта.
+
+        Args:
+            settings: Объект с новыми настройками приватности.
+
+        Returns:
+            ``True``, если сервер принял запрос.
+        """
+        return await self._app.api.account.change_profile_settings(settings=settings)

pymax/protocol/enums.py

@@ -18,6 +18,7 @@ class Opcode(int, Enum):
     RECONNECT = 3
     LOG = 5
     SESSION_INIT = 6
+    LOGIN2 = 8
     PROFILE = 16
     AUTH_REQUEST = 17
     AUTH = 18
@@ -152,6 +153,18 @@ class Opcode(int, Enum):
     PROFILE_DELETE = 199
     PROFILE_DELETE_TIME = 200
     TRANSCRIBE_MEDIA = 202
+    STORIES_LIST = 208
+    STORIES_LIST_BY_OWNER_ID = 209
+    STORIES_GET_BY_OWNER_ID = 210
+    STORIES_GET_STATS = 211
+    STORIES_GET_DETAILED_STATS = 212
+    STORIES_REACT = 213
+    STORIES_MARK = 214
+    STORIES_SEND = 215
+    NOTIF_STORIES_UPDATE = 216
+    STORIES_EDIT = 217
+    STORIES_DELETE = 218
+    STORIES_GET_BY_STORY_ID = 220
     ORG_INFO = 256
     CHAT_REACTIONS_SETTINGS_SET = 257
     REACTIONS_SETTINGS_GET_BY_CHAT_ID = 258