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

pymax/infra/stories.py

@@ -0,0 +1,205 @@
+from pymax.api.stories import StoryStatsFilter
+from pymax.files import Photo, Video
+from pymax.types.domain import Story, StoryDetailedStats, StoryPreview
+
+from .protocol import IClientProtocol
+
+
+class StoriesMixin(IClientProtocol):
+    """Методы клиента для публикации, чтения и удаления сторис."""
+
+    async def send_story(
+        self,
+        media: Photo | Video,
+        *,
+        duration: int | None = None,
+        link: str | None = None,
+    ) -> Story:
+        """Публикует фото или видео в сторис на 48 часов.
+
+        Args:
+            media: Фото или видео. Принимает локальный файл, URL или байты
+                через ``Photo`` или ``Video``.
+            duration: Положительная длительность видео в миллисекундах.
+                Обязательна для ``Video``; автоматически не определяется.
+            link: Необязательная ссылка в нижней части кадра.
+
+        Returns:
+            Опубликованная сторис.
+
+        Raises:
+            ValueError: Если длительность видео не задана или неположительна.
+            TypeError: Если передан неподдерживаемый тип медиа.
+        """
+        return await self._app.api.stories.send_story(
+            media=media,
+            duration=duration,
+            link=link,
+        )
+
+    async def get_stories(self, owner_id: int, owner_type: int = 0) -> list[Story]:
+        """Возвращает сторис указанного владельца.
+
+        Args:
+            owner_id: ID владельца, чьи сторис нужно получить.
+            owner_type: Тип из ``StoryPreview.owner.type``. ``0`` — пользователь.
+
+        Returns:
+            Список сторис. Если сторис нет, возвращается пустой список.
+        """
+        return await self._app.api.stories.get_stories(owner_id=owner_id, owner_type=owner_type)
+
+    async def delete_story(self, story_id: int) -> bool:
+        """Удаляет сторис по ее ID.
+
+        Args:
+            story_id: ID удаляемой сторис.
+
+        Returns:
+            ``True``, если запрос завершился без API-ошибки.
+        """
+        return await self._app.api.stories.delete_story(story_id=story_id)
+
+    async def get_stories_feed(
+        self,
+        cursor: str = "0",
+        count: int = 15,
+    ) -> tuple[list[StoryPreview], str]:
+        """Возвращает страницу превью владельцев сторис.
+
+        Превью не содержит ID отдельных сторис. Для их получения используйте
+        ``get_stories(preview.owner.owner_id, preview.owner.type)``.
+
+        Args:
+            cursor: Курсор страницы. ``"0"`` запрашивает первую страницу.
+            count: Количество превью в запрашиваемой странице.
+
+        Returns:
+            ``(previews, next_cursor)``. Передайте ``next_cursor`` в следующий
+            вызов. Пустая строка означает, что дальше страниц нет.
+        """
+        return await self._app.api.stories.get_stories_feed(cursor=cursor, count=count)
+
+    async def get_stories_by_id(
+        self,
+        owner_id: int,
+        story_ids: list[int],
+        owner_type: int = 0,
+    ) -> list[Story]:
+        """Возвращает конкретные сторис владельца по их ID.
+
+        Args:
+            owner_id: ID владельца сторис.
+            story_ids: ID запрашиваемых сторис.
+            owner_type: Тип из ``StoryPreview.owner.type``. ``0`` — пользователь.
+
+        Returns:
+            Список найденных сторис.
+        """
+        return await self._app.api.stories.get_stories_by_id(
+            owner_id=owner_id,
+            story_ids=story_ids,
+            owner_type=owner_type,
+        )
+
+    async def get_story_detailed_stats(
+        self,
+        story_id: int,
+        filter: StoryStatsFilter,
+        marker: int = 0,
+    ) -> tuple[list[StoryDetailedStats], int]:
+        """Возвращает страницу подробной статистики сторис.
+
+        Args:
+            story_id: ID сторис.
+            filter: ``StoryStatsFilter.VIEWS`` — просмотры,
+                ``StoryStatsFilter.REACTIONS`` — реакции.
+            marker: Маркер страницы. ``0`` запрашивает первую страницу.
+
+        Returns:
+            ``(stats, next_marker)``. Нулевой маркер означает конец списка.
+        """
+        return await self._app.api.stories.get_story_detailed_stats(
+            story_id=story_id,
+            filter=filter,
+            marker=marker,
+        )
+
+    async def read_story(self, story_id: int, owner_id: int, owner_type: int = 0) -> bool:
+        """Отмечает сторис просмотренной.
+
+        Args:
+            story_id: ID просмотренной сторис.
+            owner_id: ID владельца сторис.
+            owner_type: Тип из ``StoryPreview.owner.type``. ``0`` — пользователь.
+
+        Returns:
+            ``True``, если запрос завершился без API-ошибки.
+        """
+        return await self._app.api.stories.read_story(
+            story_id=story_id,
+            owner_id=owner_id,
+            owner_type=owner_type,
+        )
+
+    async def edit_story(self, story_id: int, settings: int) -> Story:
+        """Меняет настройки опубликованной сторис.
+
+        Args:
+            story_id: ID редактируемой сторис.
+            settings: Битовая маска настроек в формате Max.
+
+        Returns:
+            Обновленная сторис.
+        """
+        return await self._app.api.stories.edit_story(story_id=story_id, settings=settings)
+
+    async def add_story_reaction(
+        self,
+        owner_id: int,
+        story_id: int,
+        reaction: str,
+        reaction_type: int = 0,
+        owner_type: int = 0,
+    ) -> bool:
+        """Добавляет или заменяет свою реакцию на сторис.
+
+        Args:
+            owner_id: ID владельца сторис.
+            story_id: ID сторис.
+            reaction: Эмодзи или строковый ID реакции.
+            reaction_type: ``0`` для эмодзи, ``1`` для реакции по ID.
+            owner_type: Тип из ``StoryPreview.owner.type``. ``0`` — пользователь.
+
+        Returns:
+            Значение ``success`` из ответа Max.
+        """
+        return await self._app.api.stories.add_story_reaction(
+            owner_id=owner_id,
+            story_id=story_id,
+            reaction=reaction,
+            reaction_type=reaction_type,
+            owner_type=owner_type,
+        )
+
+    async def remove_story_reaction(
+        self,
+        owner_id: int,
+        story_id: int,
+        owner_type: int = 0,
+    ) -> bool:
+        """Снимает свою реакцию со сторис.
+
+        Args:
+            owner_id: ID владельца сторис.
+            story_id: ID сторис.
+            owner_type: Тип из ``StoryPreview.owner.type``. ``0`` — пользователь.
+
+        Returns:
+            Значение ``success`` из ответа Max.
+        """
+        return await self._app.api.stories.remove_story_reaction(
+            owner_id=owner_id,
+            story_id=story_id,
+            owner_type=owner_type,
+        )

pymax/integrations/dishka.py

@@ -0,0 +1,109 @@
+from pymax import Router
+
+try:
+    from dishka import AsyncContainer
+    from dishka.integrations.base import is_dishka_injected, wrap_injection
+except ImportError as e:
+    raise RuntimeError(
+        "Dishka integration requires the 'dishka' extra. "
+        "Install it with `uv add 'maxapi-python[dishka]'`"
+    ) from e
+
+from collections.abc import Callable, Generator
+from typing import Any, ParamSpec, TypeVar
+from weakref import WeakKeyDictionary
+
+from pymax.base import BaseClient
+
+P = ParamSpec("P")
+T = TypeVar("T")
+
+_containers: WeakKeyDictionary[BaseClient[Any], AsyncContainer] = WeakKeyDictionary()
+ClientT = TypeVar("ClientT", bound=BaseClient)
+
+
+def _get_client(
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+) -> BaseClient[Any]:
+    client = kwargs.get("client")
+
+    if isinstance(client, BaseClient):
+        return client
+
+    for arg in reversed(args):
+        if isinstance(arg, BaseClient):
+            return arg
+
+    raise RuntimeError("Cannot resolve PyMax client for Dishka injection")
+
+
+def _get_container(
+    args: tuple[Any, ...],
+    kwargs: dict[str, Any],
+) -> AsyncContainer:
+    client = _get_client(args, kwargs)
+
+    try:
+        return _containers[client]
+    except KeyError:
+        raise RuntimeError(
+            "Dishka is not configured for this client. Call setup_dishka(container, client)."
+        ) from None
+
+
+def inject(func: Callable[P, T]) -> Callable[P, T]:
+    """Внедряет параметры ``FromDishka[T]`` в обработчик события.
+
+    Размещайте ``@inject`` под декоратором регистрации обработчика,
+    например ``@router.on_message()``. Контейнер для переданного в обработчик
+    клиента должен быть зарегистрирован через ``setup_dishka()``.
+    """
+    return wrap_injection(
+        func=func,
+        is_async=True,
+        container_getter=_get_container,
+    )
+
+
+def inject_router(router: Router[ClientT]) -> None:
+    """Оборачивает уже зарегистрированные обработчики роутера и его детей.
+
+    Пропускает обработчики, уже обернутые через ``inject``. Не затрагивает
+    ``on_start``, ``on_error``, ``on_disconnect`` и последующие регистрации.
+    """
+    for current_router in _iter_routers(router):
+        for entries in current_router.handlers.values():
+            for entry in entries:
+                if not is_dishka_injected(entry.callback):
+                    entry.callback = inject(entry.callback)
+
+
+def _iter_routers(router: Router[ClientT]) -> Generator[Router[ClientT] | Any, Any, None]:
+    yield router
+
+    for child in router.children:
+        yield from _iter_routers(child)
+
+
+def setup_dishka(
+    container: AsyncContainer,
+    client: BaseClient[Any],
+    *,
+    auto_inject: bool = False,
+) -> None:
+    """Привязывает контейнер Dishka к клиенту.
+
+    Args:
+        container: Контейнер, из которого обработчики получают зависимости.
+        client: Клиент, для которого включается интеграция.
+        auto_inject: Обернуть уже зарегистрированные обработчики всего дерева
+            роутеров клиента. По умолчанию используется явный ``@inject``.
+
+    Интеграция не открывает отдельный scope для события, не добавляет событие
+    или клиента в контекст Dishka и не закрывает контейнер автоматически.
+    """
+    _containers[client] = container
+
+    if auto_inject:
+        inject_router(client._router)

pymax/protocol/enums.py

@@ -85,7 +85,9 @@ class Opcode(int, Enum):
     FILE_UPLOAD = 87
     FILE_DOWNLOAD = 88
     LINK_INFO = 89
+    MSG_GET_COMMENTS_INFO = 91
     MSG_DELETE_RANGE = 92
+    MSG_DELETE_USER_COMMENTS = 94
     SESSIONS_INFO = 96
     SESSIONS_CLOSE = 97
     PHONE_BIND_REQUEST = 98

pymax/protocol/tcp/payload.py

@@ -128,8 +128,6 @@ class TcpPayloadDecoder:
             except ValueError:
                 logger.debug("tcp Zstd payload decompression failed", exc_info=True)
                 raise
-        elif flags > 0x7F:
-            raise ValueError(f"invalid TCP compression factor: {flags}")
         elif flags > 0:
             if self.compression is None:
                 raise ValueError("LZ4-compressed TCP payload without a decoder")

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/__init__.py

@@ -1,15 +1,37 @@
 from .attachments import *
 from .bots import InitData
+from .callback import CallbackResponse
 from .chat import Chat
+from .comment import CommentsInfo, CommentsInfoUpdate
 from .error import MaxApiError
 from .folder import Folder, FolderList, FolderUpdate
 from .handshake import HandshakeResponse
 from .login import Login2Flags, Login2Response, LoginResponse
 from .member import Member
-from .message import Message, ReactionCounter, ReactionInfo, ReadState
+from .message import (
+    ForwardLink,
+    LinkType,
+    Message,
+    ReactionCounter,
+    ReactionInfo,
+    ReadState,
+    ReplyLink,
+)
 from .name import Name
 from .presence import Presence
 from .profile import Profile
 from .session import Session
+from .story import (
+    Story,
+    StoryClickableLink,
+    StoryCoordinates,
+    StoryDetailedStats,
+    StoryLayer,
+    StoryMedia,
+    StoryOwner,
+    StoryPhotoMedia,
+    StoryPreview,
+    StoryVideoMedia,
+)
 from .sync import SyncOverrides, SyncState
 from .user import ContactInfo, User

pymax/types/domain/attachments/__init__.py

@@ -4,7 +4,7 @@ from .contact import ContactAttachment
 from .control import ControlAttachment
 from .enums import AttachmentType, PollFlags
 from .file import FileAttachment, FileRequest
-from .keyboards import InlineKeyboardAttachment
+from .keyboards import Button, ButtonType, InlineKeyboardAttachment
 from .photo import PhotoAttachment
 from .poll import Poll, PollAnswer, PollAttachment, PollState
 from .share import ShareAttachment

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