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

pymax/infra/chat.py

@@ -0,0 +1,240 @@
+from pymax.types import Chat, Message
+
+from .protocol import IClientProtocol
+
+
+class ChatMixin(IClientProtocol):
+    """Методы клиента для чатов, групп, каналов и invite-ссылок."""
+
+    async def create_group(
+        self,
+        name: str,
+        participant_ids: list[int] | None = None,
+        notify: bool = True,
+    ) -> tuple[Chat, Message] | None:
+        """Создает группу и возвращает чат со служебным сообщением.
+
+        Args:
+            name: Название группы.
+            participant_ids: ID пользователей для добавления при создании.
+            notify: Отправить ли участникам уведомление.
+
+        Returns:
+            ``(chat, message)`` или ``None``, если сервер не вернул данные
+            созданного чата.
+        """
+        return await self._app.api.chats.create_group(
+            name=name,
+            participant_ids=participant_ids,
+            notify=notify,
+        )
+
+    async def invite_users_to_group(
+        self,
+        chat_id: int,
+        user_ids: list[int],
+        show_history: bool = True,
+    ) -> Chat | None:
+        """Приглашает пользователей в группу.
+
+        Args:
+            chat_id: ID группы.
+            user_ids: ID пользователей.
+            show_history: Показать новым участникам историю сообщений.
+
+        Returns:
+            Обновленная группа или ``None``, если сервер не вернул чат.
+        """
+        return await self._app.api.chats.invite_users_to_group(
+            chat_id=chat_id,
+            user_ids=user_ids,
+            show_history=show_history,
+        )
+
+    async def invite_users_to_channel(
+        self,
+        chat_id: int,
+        user_ids: list[int],
+        show_history: bool = True,
+    ) -> Chat | None:
+        """Приглашает пользователей в канал.
+
+        Args:
+            chat_id: ID канала.
+            user_ids: ID пользователей.
+            show_history: Показать новым участникам историю сообщений.
+
+        Returns:
+            Обновленный канал или ``None``, если сервер не вернул чат.
+        """
+        return await self._app.api.chats.invite_users_to_channel(
+            chat_id=chat_id,
+            user_ids=user_ids,
+            show_history=show_history,
+        )
+
+    async def remove_users_from_group(
+        self,
+        chat_id: int,
+        user_ids: list[int],
+        clean_msg_period: int,
+    ) -> bool:
+        """Удаляет пользователей из группы.
+
+        Args:
+            chat_id: ID группы.
+            user_ids: ID пользователей.
+            clean_msg_period: Период очистки сообщений удаляемых участников.
+
+        Returns:
+            ``True``, если сервер принял запрос.
+        """
+        return await self._app.api.chats.remove_users_from_group(
+            chat_id=chat_id,
+            user_ids=user_ids,
+            clean_msg_period=clean_msg_period,
+        )
+
+    async def change_group_settings(
+        self,
+        chat_id: int,
+        all_can_pin_message: bool | None = None,
+        only_owner_can_change_icon_title: bool | None = None,
+        only_admin_can_add_member: bool | None = None,
+        only_admin_can_call: bool | None = None,
+        members_can_see_private_link: bool | None = None,
+    ) -> None:
+        """Обновляет настройки группы.
+
+        Передавайте только те настройки, которые хотите изменить. ``None``
+        оставляет конкретную настройку без изменений.
+
+        Args:
+            chat_id: ID группы.
+            all_can_pin_message: Все участники могут закреплять сообщения.
+            only_owner_can_change_icon_title: Только владелец меняет иконку
+                и название.
+            only_admin_can_add_member: Только администраторы добавляют людей.
+            only_admin_can_call: Только администраторы начинают звонки.
+            members_can_see_private_link: Участники видят приватную ссылку.
+        """
+        await self._app.api.chats.change_group_settings(
+            chat_id=chat_id,
+            all_can_pin_message=all_can_pin_message,
+            only_owner_can_change_icon_title=only_owner_can_change_icon_title,
+            only_admin_can_add_member=only_admin_can_add_member,
+            only_admin_can_call=only_admin_can_call,
+            members_can_see_private_link=members_can_see_private_link,
+        )
+
+    async def change_group_profile(
+        self,
+        chat_id: int,
+        name: str | None,
+        description: str | None = None,
+    ) -> None:
+        """Обновляет название и описание группы.
+
+        Args:
+            chat_id: ID группы.
+            name: Новое название.
+            description: Новое описание.
+        """
+        await self._app.api.chats.change_group_profile(
+            chat_id=chat_id,
+            name=name,
+            description=description,
+        )
+
+    async def join_group(self, link: str) -> Chat:
+        """Вступает в группу по пригласительной ссылке.
+
+        Args:
+            link: Полная invite-ссылка или ее часть с join-токеном Max.
+
+        Returns:
+            Группа, в которую вступил клиент.
+
+        Raises:
+            ValueError: Если строка не похожа на invite-ссылку.
+        """
+        return await self._app.api.chats.join_group(link)
+
+    async def resolve_group_by_link(self, link: str) -> Chat | None:
+        """Возвращает информацию о группе по invite-ссылке без вступления.
+
+        Args:
+            link: Полная invite-ссылка или ее часть с join-токеном Max.
+
+        Returns:
+            Группа или ``None``, если сервер не вернул чат.
+
+        Raises:
+            ValueError: Если строка не похожа на invite-ссылку.
+        """
+        return await self._app.api.chats.resolve_group_by_link(link)
+
+    async def rework_invite_link(self, chat_id: int) -> Chat:
+        """Перевыпускает приватную invite-ссылку группы.
+
+        Args:
+            chat_id: ID группы.
+
+        Returns:
+            Обновленная группа с новой ссылкой.
+        """
+        return await self._app.api.chats.rework_invite_link(chat_id)
+
+    async def get_chats(self, chat_ids: list[int]) -> list[Chat]:
+        """Возвращает чаты, используя кеш и догружая недостающие данные.
+
+        Args:
+            chat_ids: ID чатов в нужном порядке.
+
+        Returns:
+            Найденные чаты в порядке ``chat_ids``. Чаты, которых нет в
+            ответе сервера, пропускаются.
+        """
+        return await self._app.api.chats.get_chats(chat_ids)
+
+    async def get_chat(self, chat_id: int) -> Chat:
+        """Возвращает чат по ID.
+
+        Args:
+            chat_id: ID чата.
+
+        Returns:
+            Найденный чат.
+
+        Raises:
+            PyMaxError: Если сервер не вернул чат.
+        """
+        return await self._app.api.chats.get_chat(chat_id)
+
+    async def leave_group(self, chat_id: int) -> None:
+        """Выходит из группы.
+
+        Args:
+            chat_id: ID группы.
+        """
+        await self._app.api.chats.leave_group(chat_id)
+
+    async def leave_channel(self, chat_id: int) -> None:
+        """Выходит из канала.
+
+        Args:
+            chat_id: ID канала.
+        """
+        await self._app.api.chats.leave_channel(chat_id)
+
+    async def fetch_chats(self, marker: int | None = None) -> list[Chat]:
+        """Загружает список чатов с сервера и обновляет кеш клиента.
+
+        Args:
+            marker: Маркер пагинации в миллисекундах. Если ``None``,
+                используется текущий момент.
+
+        Returns:
+            Загруженные чаты.
+        """
+        return await self._app.api.chats.fetch_chats(marker=marker)

pymax/infra/message.py

@@ -0,0 +1,252 @@
+from pymax.api.messages.enums import ItemType
+from pymax.api.messages.service import SendAttachments
+from pymax.types import (
+    FileRequest,
+    Message,
+    ReactionInfo,
+    ReadState,
+    VideoRequest,
+)
+
+from .protocol import IClientProtocol
+
+
+class MessageMixin(IClientProtocol):
+    """Методы клиента для сообщений, истории, реакций и вложений."""
+
+    async def send_message(
+        self,
+        chat_id: int,
+        text: str,
+        reply_to: int | None = None,
+        attachments: SendAttachments = None,
+        *,
+        notify: bool = True,
+    ) -> Message | None:
+        """Отправляет сообщение в чат.
+
+        Args:
+            chat_id: ID чата.
+            text: Текст сообщения.
+            reply_to: ID сообщения для ответа.
+            attachments: Файлы, фотографии или видео для отправки.
+            notify: Отправить ли получателям push-уведомление.
+
+        Returns:
+            Отправленное сообщение или ``None``, если сервер не вернул его.
+        """
+        return await self._app.api.messages.send_message(
+            chat_id,
+            text,
+            reply_to,
+            attachments,
+            notify=notify,
+        )
+
+    async def fetch_history(
+        self,
+        chat_id: int,
+        forward: int = 0,
+        backward: int = 40,
+        backward_time: int = 0,
+        forward_time: int = 0,
+        from_time: int | None = None,
+        item_type: ItemType = ItemType.REGULAR,
+        get_chat: bool = False,
+        get_messages: bool = True,
+        interactive: bool = False,
+    ) -> list[Message] | None:
+        """Загружает историю сообщений чата.
+
+        Args:
+            chat_id: ID чата.
+            forward: Сколько сообщений загрузить вперед от ``from_time``.
+            backward: Сколько сообщений загрузить назад от ``from_time``.
+            backward_time: Временное окно назад в миллисекундах.
+            forward_time: Временное окно вперед в миллисекундах.
+            from_time: Точка отсчета в миллисекундах Unix time. Если
+                ``None``, используется текущий момент.
+            item_type: Тип элементов истории: обычные или отложенные.
+            get_chat: Запросить данные чата вместе с историей.
+            get_messages: Запросить сами сообщения.
+            interactive: Пометить запрос как интерактивный.
+
+        Returns:
+            Сообщения или ``None``, если сервер не вернул список.
+        """
+        return await self._app.api.messages.fetch_history(
+            chat_id=chat_id,
+            forward=forward,
+            backward=backward,
+            backward_time=backward_time,
+            forward_time=forward_time,
+            from_=from_time,
+            item_type=item_type,
+            get_chat=get_chat,
+            get_messages=get_messages,
+            interactive=interactive,
+        )
+
+    async def delete_message(
+        self,
+        chat_id: int,
+        message_ids: list[int],
+        for_me: bool,
+    ) -> bool:
+        """Удаляет сообщения из чата.
+
+        Args:
+            chat_id: ID чата.
+            message_ids: ID сообщений.
+            for_me: Удалить только для текущего аккаунта.
+
+        Returns:
+            ``True``, если сервер принял запрос.
+        """
+        return await self._app.api.messages.delete_message(
+            chat_id=chat_id,
+            message_ids=message_ids,
+            for_me=for_me,
+        )
+
+    async def pin_message(
+        self,
+        chat_id: int,
+        message_id: int,
+        notify_pin: bool,
+    ) -> bool:
+        """Закрепляет сообщение в чате.
+
+        Args:
+            chat_id: ID чата.
+            message_id: ID сообщения.
+            notify_pin: Отправить ли уведомление о закреплении.
+
+        Returns:
+            ``True``, если сервер принял запрос.
+        """
+        return await self._app.api.messages.pin_message(
+            chat_id=chat_id,
+            message_id=message_id,
+            notify_pin=notify_pin,
+        )
+
+    async def get_video_by_id(
+        self,
+        chat_id: int,
+        message_id: int | str,
+        video_id: int,
+    ) -> VideoRequest | None:
+        """Возвращает данные для просмотра видео-вложения.
+
+        Args:
+            chat_id: ID чата.
+            message_id: ID сообщения с видео.
+            video_id: ID видео-вложения.
+
+        Returns:
+            Данные видео или ``None``, если сервер их не вернул.
+        """
+        return await self._app.api.messages.get_video_by_id(
+            chat_id=chat_id,
+            message_id=message_id,
+            video_id=video_id,
+        )
+
+    async def get_file_by_id(
+        self,
+        chat_id: int,
+        message_id: int | str,
+        file_id: int,
+    ) -> FileRequest | None:
+        """Возвращает данные для скачивания файлового вложения.
+
+        Args:
+            chat_id: ID чата.
+            message_id: ID сообщения с файлом.
+            file_id: ID файлового вложения.
+
+        Returns:
+            Данные файла или ``None``, если сервер их не вернул.
+        """
+        return await self._app.api.messages.get_file_by_id(
+            chat_id=chat_id,
+            message_id=message_id,
+            file_id=file_id,
+        )
+
+    async def add_reaction(
+        self,
+        chat_id: int,
+        message_id: str,
+        reaction: str,
+    ) -> ReactionInfo | None:
+        """Добавляет реакцию к сообщению.
+
+        Args:
+            chat_id: ID чата.
+            message_id: ID сообщения.
+            reaction: ID emoji-реакции, поддержанный сервером.
+
+        Returns:
+            Обновленные реакции или ``None``, если сервер их не вернул.
+        """
+        return await self._app.api.messages.add_reaction(
+            chat_id=chat_id,
+            message_id=message_id,
+            reaction=reaction,
+        )
+
+    async def get_reactions(
+        self,
+        chat_id: int,
+        message_ids: list[str],
+    ) -> dict[str, ReactionInfo] | None:
+        """Возвращает реакции для нескольких сообщений.
+
+        Args:
+            chat_id: ID чата.
+            message_ids: ID сообщений.
+
+        Returns:
+            ``{message_id: ReactionInfo}`` или ``None``, если реакций нет в
+            ответе сервера.
+        """
+        return await self._app.api.messages.get_reactions(
+            chat_id=chat_id,
+            message_ids=message_ids,
+        )
+
+    async def remove_reaction(
+        self,
+        chat_id: int,
+        message_id: str,
+    ) -> ReactionInfo | None:
+        """Удаляет свою реакцию с сообщения.
+
+        Args:
+            chat_id: ID чата.
+            message_id: ID сообщения.
+
+        Returns:
+            Обновленные реакции или ``None``, если сервер их не вернул.
+        """
+        return await self._app.api.messages.remove_reaction(
+            chat_id=chat_id,
+            message_id=message_id,
+        )
+
+    async def read_message(self, message_id: int, chat_id: int) -> ReadState:
+        """Отмечает сообщение как прочитанное.
+
+        Args:
+            message_id: ID сообщения.
+            chat_id: ID чата.
+
+        Returns:
+            Состояние прочтения.
+        """
+        return await self._app.api.messages.read_message(
+            message_id=message_id,
+            chat_id=chat_id,
+        )

pymax/infra/protocol.py

@@ -0,0 +1,9 @@
+from typing import Protocol
+
+from pymax.app import App
+
+
+class IClientProtocol(Protocol):
+    """Описывает минимальный клиент, нужный infra-миксинам."""
+
+    _app: App

pymax/infra/self.py

@@ -0,0 +1,139 @@
+from typing import Any
+
+from pymax.types import FolderList, FolderUpdate
+
+from .protocol import IClientProtocol
+
+
+class SelfMixin(IClientProtocol):
+    async def request_profile_photo_upload_url(self) -> str:
+        """Запрашивает временный URL для загрузки фотографии профиля.
+
+        Returns:
+            URL, на который можно загрузить фото профиля.
+        """
+        return await self._app.api.account.request_profile_photo_upload_url()
+
+    async def change_profile(
+        self,
+        first_name: str,
+        last_name: str | None = None,
+        description: str | None = None,
+        photo: Any | None = None,
+        *,
+        photo_token: str | None = None,
+    ) -> bool:
+        """Обновляет профиль текущего аккаунта.
+
+        Args:
+            first_name: Имя профиля.
+            last_name: Фамилия профиля.
+            description: Описание профиля.
+            photo: Файл или объект фото. Прямая загрузка через этот
+                параметр пока не реализована.
+            photo_token: Токен фотографии, уже загруженной через API Max.
+
+        Returns:
+            ``True`` после успешного обновления. Клиент также обновит
+            ``client.me`` и кеш текущего контакта.
+
+        Raises:
+            NotImplementedError: Если передан ``photo`` вместо
+                ``photo_token``.
+        """
+        return await self._app.api.account.change_profile(
+            first_name=first_name,
+            last_name=last_name,
+            description=description,
+            photo=photo,
+            photo_token=photo_token,
+        )
+
+    async def create_folder(
+        self,
+        title: str,
+        chat_include: list[int],
+        filters: list[Any] | None = None,
+    ) -> FolderUpdate:
+        """Создает папку чатов.
+
+        Args:
+            title: Название папки.
+            chat_include: ID чатов, которые попадут в папку.
+            filters: Дополнительные фильтры Max для папки.
+
+        Returns:
+            Обновленное состояние папок.
+        """
+        return await self._app.api.account.create_folder(
+            title=title,
+            chat_include=chat_include,
+            filters=filters,
+        )
+
+    async def get_folders(self, folder_sync: int = 0) -> FolderList:
+        """Возвращает папки текущего аккаунта.
+
+        Args:
+            folder_sync: Маркер синхронизации. Для первой загрузки оставьте
+                ``0``.
+
+        Returns:
+            Список папок и актуальный маркер синхронизации.
+        """
+        return await self._app.api.account.get_folders(folder_sync=folder_sync)
+
+    async def update_folder(
+        self,
+        folder_id: str,
+        title: str,
+        chat_include: list[int] | None = None,
+        filters: list[Any] | None = None,
+        options: list[Any] | None = None,
+    ) -> FolderUpdate:
+        """Обновляет папку чатов.
+
+        Args:
+            folder_id: ID папки.
+            title: Новое название.
+            chat_include: Новый список ID включенных чатов.
+            filters: Новый список фильтров.
+            options: Новый список опций.
+
+        Returns:
+            Обновленное состояние папок.
+        """
+        return await self._app.api.account.update_folder(
+            folder_id=folder_id,
+            title=title,
+            chat_include=chat_include,
+            filters=filters,
+            options=options,
+        )
+
+    async def delete_folder(self, folder_id: str) -> FolderUpdate:
+        """Удаляет папку чатов.
+
+        Args:
+            folder_id: ID папки.
+
+        Returns:
+            Обновленное состояние папок.
+        """
+        return await self._app.api.account.delete_folder(folder_id)
+
+    async def close_all_sessions(self) -> bool:
+        """Закрывает остальные активные сессии аккаунта.
+
+        Returns:
+            ``True``, если сервер принял запрос.
+        """
+        return await self._app.api.account.close_all_sessions()
+
+    async def logout(self) -> bool:
+        """Завершает текущую сессию клиента.
+
+        Returns:
+            ``True``, если сервер принял запрос на выход.
+        """
+        return await self._app.api.account.logout()