Merge pull request #68 from MaxApiTeam/dev/2.3.1

Dev/2.3.1

Author: ink-developer

docs/client.rst

@@ -300,9 +300,9 @@ Debug-логи показывают handshake, login, входящие собы
 Клиент собирает несколько API-направлений:
 
 Сообщения
-   ``send_message()``, ``fetch_history()``, ``delete_message()``,
-   ``pin_message()``, ``read_message()``, реакции и получение URL для входящих
-   файлов/видео.
+   ``send_message()``, ``forward_message()``, ``fetch_history()``,
+   ``delete_message()``, ``pin_message()``, ``read_message()``, реакции и
+   получение URL для входящих файлов/видео.
 
 Чаты
    ``get_chat()``, ``fetch_chats()``, создание групп, invite-ссылки,

docs/index.rst

@@ -22,6 +22,7 @@ PyMax - асинхронная Python-библиотека для Max API. Он
    :maxdepth: 1
    :caption: Новости
 
+   release-2-3-1
    release-2-3-0
    release-2-2-0
    release-2-1-3

docs/messages.rst

@@ -70,6 +70,18 @@ Messages
    async def on_message(message: Message, client: Client) -> None:
        await message.answer("Ответ в тот же чат")
        await message.reply("Ответ реплаем")
+       await message.forward(chat_id=654321)
+
+Переслать сообщение напрямую через клиент можно с указанием исходного и
+целевого чатов:
+
+.. code-block:: python
+
+   await client.forward_message(
+       chat_id=654321,
+       message_id=987654,
+       source_chat_id=123456,
+   )
 
 Ответ, реакции, удаление и прочтение
 ----------------------------------------

docs/release-2-3-1.rst

@@ -0,0 +1,23 @@
+PyMax 2.3.1
+===========
+
+Изменения относительно ``2.3.0``.
+
+Добавлено
+---------
+
+* ``forward_message()`` на клиенте и ``Message.forward()`` на bound-объекте
+  сообщения. Для пересылки между разными чатами укажите ``source_chat_id``.
+
+Исправлено
+----------
+
+* Декодирование сжатых TCP payload-ов: коэффициенты LZ4 теперь обрабатываются
+  корректно, а payload-ы с флагом ``0xFF`` декодируются через Zstandard.
+* Разбор профилей bot-аккаунтов, в которых ``gender`` приходит числом, а
+  ``web_app`` — URL-строкой.
+
+Зависимости
+-----------
+
+* Добавлена runtime-зависимость ``zstandard`` для декодирования TCP payload-ов.

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "maxapi-python"
-version = "2.3.0"
+version = "2.3.1"
 description = "Python wrapper для API мессенджера Max"
 readme = "README.md"
 requires-python = ">=3.10"
@@ -31,6 +31,7 @@ dependencies = [
   "python-socks[asyncio]>=2.8.1",
   "qrcode>=8.2",
   "websockets>=16.0",
+  "zstandard>=0.25.0",
 ]
 
 [project.urls]

src/pymax/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "2.3.0"
+__version__ = "2.3.1"
 
 
 from .auth import (

src/pymax/api/messages/payloads.py

@@ -1,4 +1,4 @@
-from typing import Any
+from typing import Any, Literal
 
 from pydantic import Field
 
@@ -46,6 +46,26 @@ class SendMessagePayload(CamelModel):
     notify: bool = False
 
 
+class ForwardLink(CamelModel):
+    type: Literal["FORWARD"] = "FORWARD"
+    message_id: str
+    chat_id: int
+
+
+class ForwardMessagePayloadMessage(CamelModel):
+    cid: int
+    link: ForwardLink
+    attaches: list[AttachPhotoPayload | VideoAttachPayload | AttachFilePayload] = Field(
+        default_factory=list
+    )
+
+
+class ForwardMessagePayload(CamelModel):
+    chat_id: int
+    message: ForwardMessagePayloadMessage
+    notify: bool = True
+
+
 class ChatHistoryPayload(CamelModel):
     chat_id: int
     forward: int

src/pymax/api/messages/service.py

@@ -36,6 +36,9 @@
     ChatHistoryPayload,
     DeleteMessagePayload,
     EditMessagePayload,
+    ForwardLink,
+    ForwardMessagePayload,
+    ForwardMessagePayloadMessage,
     GetFilePayload,
     GetMessagesPayload,
     GetReactionsPayload,
@@ -139,6 +142,42 @@ async def send_message(
         logger.info("message sent chat_id=%s", chat_id)
         return message
 
+    async def forward_message(
+        self,
+        chat_id: int,
+        message_id: int | str,
+        source_chat_id: int | None = None,
+        *,
+        notify: bool = True,
+    ) -> Message | None:
+        source_chat_id = chat_id if source_chat_id is None else source_chat_id
+        logger.info(
+            "forwarding message source_chat_id=%s chat_id=%s message_id=%s",
+            source_chat_id,
+            chat_id,
+            message_id,
+        )
+
+        frame = ForwardMessagePayload(
+            chat_id=chat_id,
+            message=ForwardMessagePayloadMessage(
+                cid=-self._next_cid(),
+                link=ForwardLink(
+                    message_id=str(message_id),
+                    chat_id=source_chat_id,
+                ),
+            ),
+            notify=notify,
+        )
+
+        response = await self.app.invoke(Opcode.MSG_SEND, frame.to_payload())
+        message = bind_api_model(
+            self.app,
+            require_payload_model(response, Message),
+        )
+        logger.info("message forwarded source_chat_id=%s chat_id=%s", source_chat_id, chat_id)
+        return message
+
     async def get_messages(
         self,
         chat_id: int,

src/pymax/infra/message.py

@@ -62,6 +62,33 @@ async def get_message(
             message_id=message_id,
         )
 
+    async def forward_message(
+        self,
+        chat_id: int,
+        message_id: int | str,
+        source_chat_id: int | None = None,
+        *,
+        notify: bool = True,
+    ) -> Message | None:
+        """Пересылает существующее сообщение в чат.
+
+        Args:
+            chat_id: ID целевого чата.
+            message_id: ID пересылаемого сообщения.
+            source_chat_id: ID исходного чата. Если не указан, используется
+                целевой чат.
+            notify: Отправить ли получателям push-уведомление.
+
+        Returns:
+            Пересланное сообщение или ``None``, если сервер не вернул его.
+        """
+        return await self._app.api.messages.forward_message(
+            chat_id=chat_id,
+            message_id=message_id,
+            source_chat_id=source_chat_id,
+            notify=notify,
+        )
+
     async def get_messages(
         self,
         chat_id: int,

src/pymax/protocol/tcp/compression.py

@@ -1,3 +1,8 @@
+from io import BytesIO
+
+import zstandard
+
+
 class Lz4BlockCompression:
     def decompress(self, src: bytes, max_output: int = 5 * 1024 * 1024) -> bytes:
         dst = bytearray()
@@ -95,3 +100,16 @@ def compress(self, src: bytes) -> bytes:
                 dst.extend(src[lit_start : lit_start + lit_len])
 
         return bytes(dst)
+
+
+class ZstdCompression:
+    def decompress(self, src: bytes, max_output: int = 5 * 1024 * 1024) -> bytes:
+        try:
+            with zstandard.ZstdDecompressor().stream_reader(BytesIO(src)) as reader:
+                result = reader.read(max_output + 1)
+        except zstandard.ZstdError as e:
+            raise ValueError("Zstd: failed to decompress payload") from e
+
+        if len(result) > max_output:
+            raise ValueError("Zstd: output too large")
+        return result