maxapi-python 1.2.4__py3-none-any.whl → 2.0.0__py3-none-any.whl

pymax/types/domain/message.py

@@ -0,0 +1,378 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Annotated, Any, TypeAlias
+
+from pydantic import Field, PrivateAttr, model_validator
+
+from pymax.files import File, Photo, Video
+from pymax.types.domain import (
+    AudioAttachment,
+    CallAttachment,
+    ContactAttachment,
+    ControlAttachment,
+    FileAttachment,
+    InlineKeyboardAttachment,
+    PhotoAttachment,
+    ShareAttachment,
+    StickerAttachment,
+    VideoAttachment,
+)
+
+from .base import CamelModel
+from .element import Element
+from .enums import MessageStatus
+
+if TYPE_CHECKING:
+    from pymax.api.messages.service import MessageService
+
+
+Attachment: TypeAlias = Annotated[
+    PhotoAttachment
+    | VideoAttachment
+    | FileAttachment
+    | ContactAttachment
+    | StickerAttachment
+    | AudioAttachment
+    | ControlAttachment
+    | InlineKeyboardAttachment
+    | ShareAttachment
+    | CallAttachment,
+    Field(discriminator="type"),
+]
+SendAttachment: TypeAlias = Photo | File | Video
+SendAttachments: TypeAlias = list[SendAttachment] | None
+
+
+class ReactionCounter(CamelModel):
+    """Счетчик одной реакции на сообщение.
+
+    :ivar count: Количество таких реакций.
+    :vartype count: int
+    :ivar reaction: ID emoji-реакции.
+    :vartype reaction: str
+    """
+
+    count: int
+    reaction: str
+
+
+class ReactionInfo(CamelModel):
+    """Сводная информация о реакциях на сообщение.
+
+    :ivar total_count: Общее количество реакций.
+    :vartype total_count: int
+    :ivar counters: Счетчики по каждому типу реакции.
+    :vartype counters: list[ReactionCounter]
+    :ivar your_reaction: Реакция текущего пользователя, если она есть.
+    :vartype your_reaction: str | None
+    """
+
+    total_count: int = 0
+    counters: list[ReactionCounter] = Field(default_factory=list)
+    your_reaction: str | None = None
+
+
+class ReadState(CamelModel):
+    """Состояние прочтения после отметки сообщения прочитанным.
+
+    :ivar unread: Количество непрочитанных сообщений.
+    :vartype unread: int
+    :ivar mark: Текущая отметка прочтения.
+    :vartype mark: int
+    """
+
+    unread: int
+    mark: int
+
+
+class Message(CamelModel):
+    """Сообщение Max с методами для действий над ним.
+
+    Сообщения, полученные через клиент, обычно уже привязаны к сервису
+    сообщений. После этого можно вызывать удобные методы объекта:
+    :meth:`reply`, :meth:`answer`, :meth:`pin`, :meth:`delete`,
+    :meth:`read`, :meth:`react`, :meth:`unreact` и :meth:`get_reactions`.
+
+    Используйте ``Message`` в обработчиках ``on_message`` и при работе с
+    историей. Некоторые поля могут быть ``None``, потому что Max присылает
+    разные payload-ы для разных событий.
+
+    Example:
+        .. code-block:: python
+
+           from pymax import Client
+
+           @client.on_message()
+           async def on_message(message: Message, client: Client) -> None:
+               if message.chat_id is None:
+                   return
+
+               await message.answer("Получил сообщение")
+
+    :ivar id: ID сообщения.
+    :vartype id: int
+    :ivar chat_id: ID чата, если он есть в данных сообщения.
+    :vartype chat_id: int | None
+    :ivar sender: ID отправителя.
+    :vartype sender: int | None
+    :ivar text: Текст сообщения.
+    :vartype text: str
+    :ivar time: Время сообщения в формате Unix time.
+    :vartype time: int
+    :ivar type: Тип сообщения.
+    :vartype type: str
+    :ivar cid: Клиентский ID сообщения, если он есть в payload-е.
+    :vartype cid: int | None
+    :ivar attaches: Вложения сообщения.
+    :vartype attaches: list[Attachment]
+    :ivar stats: Дополнительная статистика сообщения от Max.
+    :vartype stats: dict[str, Any] | None
+    :ivar status: Статус доставки сообщения.
+    :vartype status: MessageStatus | None
+    :ivar reaction_info: Информация о реакциях на сообщение.
+    :vartype reaction_info: ReactionInfo | None
+    :ivar options: Дополнительные параметры сообщения от Max.
+    :vartype options: int | dict[str, Any] | None
+    :ivar prev_message_id: ID предыдущего сообщения.
+    :vartype prev_message_id: int | str | None
+    :ivar ttl: Признак сообщения с ограниченным временем жизни.
+    :vartype ttl: bool | None
+    :ivar unread: Количество непрочитанных сообщений.
+    :vartype unread: int | None
+    :ivar mark: Текущая отметка прочтения.
+    :vartype mark: int | None
+    :ivar elements: Форматированные элементы текста сообщения.
+    :vartype elements: list[Element]
+    """
+
+    id: int
+    chat_id: int | None = None
+    sender: int | None = None
+    text: str = ""
+    time: int
+    type: str
+    cid: int | None = None
+    attaches: list[Attachment] = Field(default_factory=list)
+    stats: dict[str, Any] | None = None
+    status: MessageStatus | None = None
+    reaction_info: ReactionInfo | None = None
+    options: int | dict[str, Any] | None = None
+    prev_message_id: int | str | None = None
+    ttl: bool | None = None
+    unread: int | None = None
+    mark: int | None = None
+    elements: list[Element] = Field(default_factory=list)
+
+    _actions: MessageService | None = PrivateAttr(default=None)
+
+    def bind(self, actions: MessageService) -> Message:
+        """Привязывает сервис сообщений к объекту сообщения.
+
+        :param actions: Сервис сообщений для выполнения действий с сообщением.
+        :type actions: MessageService
+        :returns: Это же сообщение с привязанным сервисом.
+        :rtype: Message
+        """
+        self._actions = actions
+        return self
+
+    async def reply(
+        self,
+        text: str,
+        attachments: SendAttachments = None,
+        *,
+        notify: bool = True,
+    ) -> Message | None:
+        """Отправляет ответ на это сообщение в тот же чат.
+
+        :param text: Текст сообщения.
+        :type text: str
+        :param attachments: Файлы, фотографии или видео для отправки.
+        :type attachments: SendAttachments
+        :param notify: Отправить ли получателям push-уведомление.
+        :type notify: bool
+        :returns: Отправленное сообщение или ``None``, если сервер не вернул
+            его.
+        :rtype: Message | None
+        :raises RuntimeError: Если сообщение не привязано к сервису или не
+            содержит ``chat_id``.
+        """
+        actions, chat_id = self._bound()
+
+        return await actions.send_message(
+            chat_id=chat_id,
+            text=text,
+            reply_to=self.id,
+            attachments=attachments,
+            notify=notify,
+        )
+
+    async def answer(
+        self,
+        text: str,
+        reply_to: int | None = None,
+        attachments: SendAttachments = None,
+        *,
+        notify: bool = True,
+    ) -> Message | None:
+        """Отправляет сообщение в тот же чат.
+
+        :param text: Текст сообщения.
+        :type text: str
+        :param reply_to: ID сообщения для ответа.
+        :type reply_to: int | None
+        :param attachments: Файлы, фотографии или видео для отправки.
+        :type attachments: SendAttachments
+        :param notify: Отправить ли получателям push-уведомление.
+        :type notify: bool
+        :returns: Отправленное сообщение или ``None``, если сервер не вернул
+            его.
+        :rtype: Message | None
+        :raises RuntimeError: Если сообщение не привязано к сервису или не
+            содержит ``chat_id``.
+        """
+        actions, chat_id = self._bound()
+
+        return await actions.send_message(
+            chat_id=chat_id,
+            text=text,
+            reply_to=reply_to,
+            attachments=attachments,
+            notify=notify,
+        )
+
+    async def pin(self, notify_pin: bool = True) -> bool:
+        """Закрепляет это сообщение в чате.
+
+        :param notify_pin: Отправить ли уведомление о закреплении.
+        :type notify_pin: bool
+        :returns: ``True``, если сервер принял запрос.
+        :rtype: bool
+        :raises RuntimeError: Если сообщение не привязано к сервису или не
+            содержит ``chat_id``.
+        """
+        actions, chat_id = self._bound()
+
+        return await actions.pin_message(
+            chat_id=chat_id,
+            message_id=self.id,
+            notify_pin=notify_pin,
+        )
+
+    async def delete(self, for_me: bool = False) -> bool:
+        """Удаляет это сообщение.
+
+        :param for_me: Удалить сообщение только для текущего аккаунта.
+        :type for_me: bool
+        :returns: ``True``, если сервер принял запрос.
+        :rtype: bool
+        :raises RuntimeError: Если сообщение не привязано к сервису или не
+            содержит ``chat_id``.
+        """
+        actions, chat_id = self._bound()
+
+        return await actions.delete_message(
+            chat_id=chat_id,
+            message_ids=[self.id],
+            for_me=for_me,
+        )
+
+    async def read(self) -> ReadState:
+        """Отмечает это сообщение как прочитанное.
+
+        :returns: Состояние прочтения.
+        :rtype: ReadState
+        :raises RuntimeError: Если сообщение не привязано к сервису или не
+            содержит ``chat_id``.
+        """
+        actions, chat_id = self._bound()
+
+        return await actions.read_message(
+            message_id=self.id,
+            chat_id=chat_id,
+        )
+
+    async def react(self, reaction: str) -> ReactionInfo | None:
+        """Добавляет или заменяет свою реакцию на этом сообщении.
+
+        :param reaction: ID emoji-реакции, поддержанный сервером.
+        :type reaction: str
+        :returns: Обновленные реакции или ``None``, если сервер их не вернул.
+        :rtype: ReactionInfo | None
+        :raises RuntimeError: Если сообщение не привязано к сервису или не
+            содержит ``chat_id``.
+        """
+        actions, chat_id = self._bound()
+
+        return await actions.add_reaction(
+            chat_id=chat_id,
+            message_id=str(self.id),  # :C
+            reaction=reaction,
+        )
+
+    async def unreact(self) -> ReactionInfo | None:
+        """Удаляет свою реакцию с этого сообщения.
+
+        :returns: Обновленные реакции или ``None``, если сервер их не вернул.
+        :rtype: ReactionInfo | None
+        :raises RuntimeError: Если сообщение не привязано к сервису или не
+            содержит ``chat_id``.
+        """
+        actions, chat_id = self._bound()
+
+        return await actions.remove_reaction(
+            chat_id=chat_id,
+            message_id=str(self.id),  # :C x2
+        )
+
+    async def get_reactions(self) -> dict[str, ReactionInfo] | None:
+        """Возвращает реакции для этого сообщения.
+
+        :returns: ``{message_id: ReactionInfo}`` или ``None``, если реакций
+            нет в ответе сервера.
+        :rtype: dict[str, ReactionInfo] | None
+        :raises RuntimeError: Если сообщение не привязано к сервису или не
+            содержит ``chat_id``.
+        """
+        actions, chat_id = self._bound()
+
+        return await actions.get_reactions(
+            chat_id=chat_id,
+            message_ids=[str(self.id)],  # :C x3
+        )
+
+    def _bound(self) -> tuple[MessageService, int]:
+        if self._actions is None:
+            raise RuntimeError("Message is not bound to a client.")
+
+        if self.chat_id is None:
+            raise RuntimeError("Message does not contain chat_id.")
+
+        return self._actions, self.chat_id
+
+    @model_validator(mode="before")
+    @classmethod
+    def _unwrap_message_event(cls, value: Any) -> Any:
+        """Преобразует данные события сообщения в данные сообщения.
+
+        :param value: Значение, переданное в валидатор модели.
+        :type value: Any
+        :returns: Данные сообщения или исходное значение, если преобразование
+            не требуется.
+        :rtype: Any
+        """
+        if not isinstance(value, dict):
+            return value
+
+        message = value.get("message")
+        if not isinstance(message, dict):
+            return value
+
+        return {
+            **message,
+            "chatId": value.get("chatId"),
+            "prevMessageId": value.get("prevMessageId"),
+            "ttl": value.get("ttl"),
+            "unread": value.get("unread"),
+            "mark": value.get("mark"),
+        }

pymax/types/domain/name.py

@@ -0,0 +1,20 @@
+from .base import CamelModel
+
+
+class Name(CamelModel):
+    """Имя пользователя.
+
+    :ivar name: Полное отображаемое имя.
+    :vartype name: str | None
+    :ivar first_name: Имя.
+    :vartype first_name: str | None
+    :ivar last_name: Фамилия.
+    :vartype last_name: str | None
+    :ivar type: Тип имени.
+    :vartype type: str | None
+    """
+
+    name: str | None = None
+    first_name: str | None = None
+    last_name: str | None = None
+    type: str | None = None

pymax/types/domain/profile.py

@@ -0,0 +1,15 @@
+from .base import CamelModel
+from .user import User
+
+
+class Profile(CamelModel):
+    """Профиль текущего аккаунта.
+
+    :ivar contact: Контакт текущего аккаунта.
+    :vartype contact: User
+    :ivar profile_options: Дополнительные флаги профиля текущего аккаунта.
+    :vartype profile_options: list[int] | None
+    """
+
+    contact: User
+    profile_options: list[int] | None = None

pymax/types/domain/session.py

@@ -0,0 +1,52 @@
+from typing import Any
+
+from .base import CamelModel
+
+
+class Session(CamelModel):
+    """Активная сессия аккаунта.
+
+    :ivar id: ID сессии.
+    :vartype id: int | str | None
+    :ivar device_id: ID устройства.
+    :vartype device_id: str | None
+    :ivar current: Является ли сессия текущей.
+    :vartype current: bool | None
+    :ivar user_agent: User-Agent сессии.
+    :vartype user_agent: str | None
+    :ivar app_version: Версия приложения.
+    :vartype app_version: str | None
+    :ivar device_name: Название устройства.
+    :vartype device_name: str | None
+    :ivar device_type: Тип устройства.
+    :vartype device_type: str | None
+    :ivar platform: Платформа устройства.
+    :vartype platform: str | None
+    :ivar ip: IP-адрес сессии.
+    :vartype ip: str | None
+    :ivar location: Локация сессии.
+    :vartype location: str | None
+    :ivar created: Время создания в формате Unix time.
+    :vartype created: int | None
+    :ivar updated: Время обновления в формате Unix time.
+    :vartype updated: int | None
+    :ivar last_activity: Время последней активности в формате Unix time.
+    :vartype last_activity: int | None
+    :ivar options: Дополнительные параметры сессии от Max.
+    :vartype options: dict[str, Any] | list[Any] | None
+    """
+
+    id: int | str | None = None
+    device_id: str | None = None
+    current: bool | None = None
+    user_agent: str | None = None
+    app_version: str | None = None
+    device_name: str | None = None
+    device_type: str | None = None
+    platform: str | None = None
+    ip: str | None = None
+    location: str | None = None
+    created: int | None = None
+    updated: int | None = None
+    last_activity: int | None = None
+    options: dict[str, Any] | list[Any] | None = None

pymax/types/domain/sync.py

@@ -0,0 +1,80 @@
+from pydantic import BaseModel
+
+DEFAULT_CONFIG_HASH = (
+    "00000000-0000000000000000-00000000-"
+    "0000000000000000-0000000000000000-0-"
+    "0000000000000000-00000000"
+)
+
+ConfigHash = str | int
+
+
+class SyncState(BaseModel):
+    """Полное сохраненное состояние синхронизации Max.
+
+    Обычно PyMax управляет этим объектом сам и хранит его в файле сессии.
+    Пользователю чаще нужен ``SyncOverrides`` для временного сброса одного или
+    нескольких маркеров.
+
+    Args:
+        chats_sync: Маркер sync для списка чатов.
+        contacts_sync: Маркер sync для контактов.
+        drafts_sync: Маркер sync для черновиков.
+        presence_sync: Маркер sync для presence.
+        config_hash: Хеш конфигурации Max.
+
+    Example:
+        .. code-block:: python
+
+           from pymax import SyncState
+
+           state = SyncState(chats_sync=-1)
+    """
+
+    chats_sync: int = -1
+    contacts_sync: int = -1
+    drafts_sync: int = -1
+    presence_sync: int = -1
+    config_hash: ConfigHash = DEFAULT_CONFIG_HASH
+
+
+class SyncOverrides(BaseModel):
+    """Частичные переопределения состояния синхронизации.
+
+    :ivar chats_sync: Новая метка синхронизации чатов.
+    :vartype chats_sync: int | None
+    :ivar contacts_sync: Новая метка синхронизации контактов.
+    :vartype contacts_sync: int | None
+    :ivar drafts_sync: Новая метка синхронизации черновиков.
+    :vartype drafts_sync: int | None
+    :ivar presence_sync: Новая метка синхронизации присутствия.
+    :vartype presence_sync: int | None
+    :ivar config_hash: Новый хеш конфигурации.
+    :vartype config_hash: ConfigHash | None
+    """
+
+    chats_sync: int | None = None
+    contacts_sync: int | None = None
+    drafts_sync: int | None = None
+    presence_sync: int | None = None
+    config_hash: ConfigHash | None = None
+
+    def resolve(self, saved: SyncState) -> SyncState:
+        """Собирает полное состояние из переопределений и сохраненных данных.
+
+        :param saved: Сохраненное состояние синхронизации.
+        :type saved: SyncState
+        :returns: Полное состояние синхронизации.
+        :rtype: SyncState
+        """
+        return SyncState(
+            chats_sync=(self.chats_sync if self.chats_sync is not None else saved.chats_sync),
+            contacts_sync=(
+                self.contacts_sync if self.contacts_sync is not None else saved.contacts_sync
+            ),
+            drafts_sync=(self.drafts_sync if self.drafts_sync is not None else saved.drafts_sync),
+            presence_sync=(
+                self.presence_sync if self.presence_sync is not None else saved.presence_sync
+            ),
+            config_hash=(self.config_hash if self.config_hash is not None else saved.config_hash),
+        )

pymax/types/domain/user.py

@@ -0,0 +1,117 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from pydantic import Field, PrivateAttr
+
+from .base import CamelModel
+from .name import Name
+
+if TYPE_CHECKING:
+    from pymax.api.users.service import UserService
+
+
+class User(CamelModel):
+    """Контакт или пользователь Max.
+
+    :ivar id: ID пользователя.
+    :vartype id: int
+    :ivar account_status: Статус аккаунта в кодировке Max.
+    :vartype account_status: int | None
+    :ivar base_raw_url: Исходный URL аватара.
+    :vartype base_raw_url: str | None
+    :ivar base_url: URL аватара.
+    :vartype base_url: str | None
+    :ivar names: Имена пользователя.
+    :vartype names: list[Name]
+    :ivar options: Дополнительные флаги контакта.
+    :vartype options: list[str]
+    :ivar photo_id: ID фотографии профиля.
+    :vartype photo_id: int | None
+    :ivar update_time: Время обновления в формате Unix time.
+    :vartype update_time: int | None
+    :ivar description: Описание профиля.
+    :vartype description: str | None
+    :ivar gender: Пол пользователя.
+    :vartype gender: str | None
+    :ivar link: Ссылка на профиль.
+    :vartype link: str | None
+    :ivar web_app: Данные связанного web-приложения, если есть.
+    :vartype web_app: dict[str, Any] | None
+    :ivar menu_button: Данные кнопки меню профиля, если есть.
+    :vartype menu_button: dict[str, Any] | None
+    """
+
+    id: int
+    account_status: int | None = None
+    base_raw_url: str | None = None
+    base_url: str | None = None
+    names: list[Name] = Field(default_factory=list)
+    options: list[str] = Field(default_factory=list)
+    photo_id: int | None = None
+    update_time: int | None = None
+    description: str | None = None
+    gender: str | None = None
+    link: str | None = None
+    web_app: dict[str, Any] | None = None
+    menu_button: dict[str, Any] | None = None
+
+    _actions: UserService | None = PrivateAttr(default=None)
+
+    def bind(self, actions: UserService) -> "User":
+        """Привязывает сервис пользователей к объекту пользователя."""
+        self._actions = actions
+        return self
+
+    async def add_contact(self) -> "User":
+        """Добавляет пользователя в контакты.
+
+        Метод использует ID текущего пользователя и вызывает API через
+        привязанный сервис пользователей.
+
+        :raises RuntimeError: Если объект пользователя не привязан к клиенту.
+        :return: Обновленный объект пользователя.
+        :rtype: User
+        """
+
+        actions = self._bound()
+
+        return await actions.add_contact(self.id)
+
+    async def remove_contact(self) -> bool:
+        """Удаляет пользователя из контактов.
+
+        Метод использует ID текущего пользователя и вызывает API через
+        привязанный сервис пользователей.
+
+        :raises RuntimeError: Если объект пользователя не привязан к клиенту.
+        :return: ``True``, если удаление прошло успешно.
+        :rtype: bool
+        """
+
+        actions = self._bound()
+
+        return await actions.remove_contact(self.id)
+
+    def get_chat_id(self, user_id: int) -> int:
+        """Возвращает ID личного чата между двумя пользователями.
+
+        ID чата строится из ID переданного пользователя и ID текущего
+        пользователя.
+
+        :param user_id: ID второго пользователя.
+        :type user_id: int
+        :raises RuntimeError: Если объект пользователя не привязан к клиенту.
+        :return: ID личного чата.
+        :rtype: int
+        """
+
+        actions = self._bound()
+
+        return actions.get_chat_id(user_id, self.id)
+
+    def _bound(self) -> UserService:
+        if self._actions is None:
+            raise RuntimeError("Class is not bound to a client")
+
+        return self._actions

pymax/types/events/__init__.py

@@ -0,0 +1,3 @@
+from .file import FileUploadSignal
+from .message import MessageDeleteEvent
+from .video import VideoUploadSignal

pymax/types/events/file.py

@@ -0,0 +1,5 @@
+from pymax.types.domain.base import CamelModel
+
+
+class FileUploadSignal(CamelModel):
+    file_id: int