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

pymax/types/domain/attachments/contact.py

@@ -10,8 +10,8 @@ from .enums import AttachmentType
 class ContactAttachment(CamelModel):
     """Контактное вложение сообщения.
 
-    :ivar contact_id: ID контакта.
-    :vartype contact_id: int
+    :ivar contact_id: ID контакта, если Max его прислал.
+    :vartype contact_id: int | None
     :ivar first_name: Имя контакта.
     :vartype first_name: str | None
     :ivar last_name: Фамилия контакта.
@@ -24,7 +24,7 @@ class ContactAttachment(CamelModel):
     :vartype type: Literal[AttachmentType.CONTACT]
     """
 
-    contact_id: int
+    contact_id: int | None = None
     first_name: str | None = None
     last_name: str | None = None
     name: str | None = None

pymax/types/domain/attachments/control.py

@@ -14,7 +14,10 @@ class ControlAttachment(CamelModel):
     :vartype type: Literal[AttachmentType.CONTROL]
     :ivar event: Событие управления.
     :vartype event: str
+    :ivar title: Заголовок служебного события, если он есть в payload-е.
+    :vartype title: str | None
     """
 
     type: Literal[AttachmentType.CONTROL] = Field(alias="_type")
     event: str
+    title: str | None = None

pymax/types/domain/attachments/enums.py

@@ -42,3 +42,19 @@ class PollFlags(IntFlag):
     FLAG_SETTINGS_CLOSED = 8
     FLAG_SETTINGS_QUIZ = 16
     FLAG_SETTINGS_CAN_FORWARD = 32
+
+
+class CallType(str, Enum):
+    """Тип звонка во входящем ``CallAttachment``."""
+
+    AUDIO = "AUDIO"
+    VIDEO = "VIDEO"
+
+
+class HangupType(str, Enum):
+    """Причина завершения звонка во входящем ``CallAttachment``."""
+
+    MISSED = "MISSED"
+    REJECTED = "REJECTED"
+    CANCELED = "CANCELED"
+    HUNGUP = "HUNGUP"

pymax/types/domain/attachments/keyboards/__init__.py

@@ -1 +1 @@
-from .inline import InlineKeyboardAttachment
+from .inline import Button, ButtonType, InlineKeyboardAttachment

pymax/types/domain/attachments/keyboards/enums.py

@@ -0,0 +1,12 @@
+from enum import Enum
+
+
+class ButtonType(str, Enum):
+    CALLBACK = "CALLBACK"
+    LINK = "LINK"
+    CHAT = "CHAT"
+    REQUEST_GEO_LOCATION = "REQUEST_GEO_LOCATION"
+    REQUEST_CONTACT = "REQUEST_CONTACT"
+    OPEN_APP = "OPEN_APP"
+    MESSAGE = "MESSAGE"
+    CLIPBOARD = "CLIPBOARD"

pymax/types/domain/attachments/keyboards/inline.py

@@ -1,10 +1,78 @@
-from typing import Any, Literal
+from typing import Annotated, Literal, TypeAlias
 
 from pydantic import Field
 
 from pymax.types.domain.attachments import AttachmentType
 from pymax.types.domain.base import CamelModel
 
+from .enums import ButtonType
+
+
+class BaseButton(CamelModel):
+    text: str
+
+
+class CallbackButton(BaseButton):
+    type: Literal[ButtonType.CALLBACK] = ButtonType.CALLBACK
+    text: str
+    payload: str
+    intent: str
+
+
+class LinkButton(BaseButton):
+    type: Literal[ButtonType.LINK] = ButtonType.LINK
+    url: str
+
+
+class ChatButton(BaseButton):
+    type: Literal[ButtonType.CHAT] = ButtonType.CHAT
+    payload: str
+
+
+class GeoLocationButton(BaseButton):
+    type: Literal[ButtonType.REQUEST_GEO_LOCATION] = ButtonType.REQUEST_GEO_LOCATION
+    quick: bool | None = None
+
+
+class RequestContactButton(BaseButton):
+    type: Literal[ButtonType.REQUEST_CONTACT] = ButtonType.REQUEST_CONTACT
+
+
+class OpenAppButton(BaseButton):
+    type: Literal[ButtonType.OPEN_APP] = ButtonType.OPEN_APP
+    contact_id: int | None = None
+    payload: str | None = None
+    web_app: str | None = None
+
+
+class MessageButton(BaseButton):
+    type: Literal[ButtonType.MESSAGE] = ButtonType.MESSAGE
+
+
+class ClipboardButton(BaseButton):
+    type: Literal[ButtonType.CLIPBOARD] = ButtonType.CLIPBOARD
+    payload: str
+
+
+Button: TypeAlias = Annotated[
+    CallbackButton
+    | ChatButton
+    | LinkButton
+    | RequestContactButton
+    | GeoLocationButton
+    | OpenAppButton
+    | MessageButton
+    | ClipboardButton,
+    Field(discriminator="type"),
+]
+ButtonRow: TypeAlias = list[Button]
+
+
+class InlineKeyboard(CamelModel):
+    """Inline-клавиатура со списком строк кнопок в ``buttons``."""
+
+    buttons: list[ButtonRow]
+
 
 class InlineKeyboardAttachment(CamelModel):
     """Вложение inline-клавиатуры.
@@ -12,8 +80,11 @@ class InlineKeyboardAttachment(CamelModel):
     :ivar type: Тип вложения.
     :vartype type: Literal[AttachmentType.INLINE_KEYBOARD]
     :ivar keyboard: Данные inline-клавиатуры.
-    :vartype keyboard: dict[str, Any]
+    :vartype keyboard: InlineKeyboard
+    :ivar callback_id: ID клавиатуры для ``client.send_callback()``.
+    :vartype callback_id: str
     """
 
     type: Literal[AttachmentType.INLINE_KEYBOARD] = Field(alias="_type")
-    keyboard: dict[str, Any]
+    keyboard: InlineKeyboard
+    callback_id: str

pymax/types/domain/attachments/video.py

@@ -32,8 +32,8 @@ class VideoAttachment(CamelModel):
     :vartype video_id: int
     :ivar duration: Длительность видео.
     :vartype duration: int | None
-    :ivar preview_data: Данные превью.
-    :vartype preview_data: bytes
+    :ivar preview_data: Данные превью, если Max их прислал.
+    :vartype preview_data: bytes | None
     :ivar type: Тип вложения.
     :vartype type: Literal[AttachmentType.VIDEO]
     :ivar thumbnail: URL миниатюры.
@@ -48,7 +48,7 @@ class VideoAttachment(CamelModel):
     width: int
     video_id: int
     duration: int | None = None
-    preview_data: bytes
+    preview_data: bytes | None = None
     type: Literal[AttachmentType.VIDEO] = Field(alias="_type")
     thumbnail: str
     token: str

pymax/types/domain/callback.py

@@ -0,0 +1,19 @@
+from .base import CamelModel
+from .chat import Chat
+from .message import Message
+
+
+class CallbackResponse(CamelModel):
+    """Результат нажатия inline-кнопки бота.
+
+    ``success`` показывает результат операции. Необязательные ``message`` и
+    ``chat`` содержат дополнительные данные ответа Max и поддерживают методы
+    действий, если ответ получен через клиент.
+    """
+
+    success: bool
+    unread: int
+    mark: int
+    message: Message | None = None
+    chat: Chat | None = None
+    chat_access_token: str | None = None

pymax/types/domain/comment.py

@@ -0,0 +1,24 @@
+from .base import CamelModel
+
+
+class CommentsInfo(CamelModel):
+    """Счетчики комментариев поста.
+
+    :ivar total_count: Общее количество комментариев.
+    :vartype total_count: int
+    """
+
+    total_count: int = 0
+
+
+class CommentsInfoUpdate(CamelModel):
+    """Обновление счетчиков комментариев поста.
+
+    :ivar post_id: ID поста.
+    :vartype post_id: int
+    :ivar comments_info: Счетчики комментариев поста, если Max их прислал.
+    :vartype comments_info: CommentsInfo | None
+    """
+
+    post_id: int
+    comments_info: CommentsInfo | None

pymax/types/domain/enums.py

@@ -22,3 +22,10 @@ class MessageStatus(str, Enum):
 
     EDITED = "EDITED"
     REMOVED = "REMOVED"
+
+
+class LinkType(str, Enum):
+    """Тип связи входящего сообщения с исходным сообщением."""
+
+    REPLY = "REPLY"
+    FORWARD = "FORWARD"

pymax/types/domain/message.py

@@ -1,7 +1,7 @@
 from __future__ import annotations
 
 from collections.abc import Sequence
-from typing import TYPE_CHECKING, Annotated, Any, TypeAlias
+from typing import TYPE_CHECKING, Annotated, Any, Literal, TypeAlias
 
 from pydantic import Field, PrivateAttr, model_validator
 
@@ -24,10 +24,10 @@ from pymax.types.domain import (
 
 from .base import CamelModel
 from .element import Element
-from .enums import MessageStatus
+from .enums import AccessType, LinkType, MessageStatus
 
 if TYPE_CHECKING:
-    from pymax.api.messages.service import MessageService
+    from pymax.api.messages import DateTimeUnion, MessageService
 
 
 KnownAttachment: TypeAlias = Annotated[
@@ -47,6 +47,12 @@ KnownAttachment: TypeAlias = Annotated[
 Attachment: TypeAlias = KnownAttachment | UnknownAttachment
 SendAttachment: TypeAlias = Photo | File | Video | Poll | Voice | VideoNote
 SendAttachments: TypeAlias = Sequence[SendAttachment] | None
+Link: TypeAlias = Annotated["ReplyLink | ForwardLink", Field(discriminator="type")]
+
+
+class MessageLink(CamelModel):
+    message: Message
+    chat_id: int
 
 
 class ReactionCounter(CamelModel):
@@ -91,6 +97,48 @@ class ReadState(CamelModel):
     mark: int
 
 
+class DelayedAttributes(CamelModel):
+    time_to_fire: int
+    notify_sender: bool
+    notify_opponents: bool
+
+
+class ReplyLink(MessageLink):
+    """Источник сообщения, отправленного как reply.
+
+    :ivar message: Сообщение, на которое ответили.
+    :vartype message: Message
+    :ivar chat_id: ID чата исходного сообщения.
+    :vartype chat_id: int
+    """
+
+    type: Literal[LinkType.REPLY] = LinkType.REPLY
+    message: Message
+    chat_id: int
+
+
+class ForwardLink(MessageLink):
+    """Источник пересланного сообщения.
+
+    Помимо исходного сообщения содержит доступные в payload-е имя, ссылку,
+    тип доступа и иконку исходного чата. Для скрытого источника эти метаданные
+    могут быть ``None``.
+
+    :ivar message: Исходное сообщение.
+    :vartype message: Message
+    :ivar chat_id: ID исходного чата.
+    :vartype chat_id: int
+    """
+
+    type: Literal[LinkType.FORWARD] = LinkType.FORWARD
+    message: Message
+    chat_id: int
+    chat_name: str | None = None
+    chat_link: str | None = None
+    chat_access_type: AccessType | None = None
+    chat_icon_url: str | None = None
+
+
 class Message(CamelModel):
     """Сообщение Max с методами для действий над ним.
 
@@ -120,6 +168,8 @@ class Message(CamelModel):
     :vartype id: int
     :ivar chat_id: ID чата, если он есть в данных сообщения.
     :vartype chat_id: int | None
+    :ivar post_id: ID поста канала, если сообщение является комментарием.
+    :vartype post_id: int | None
     :ivar sender: ID отправителя.
     :vartype sender: int | None
     :ivar text: Текст сообщения.
@@ -130,7 +180,8 @@ class Message(CamelModel):
     :vartype type: str
     :ivar cid: Клиентский ID сообщения, если он есть в payload-е.
     :vartype cid: int | None
-    :ivar attaches: Вложения сообщения.
+    :ivar attaches: Вложения сообщения. Неизвестный ``_type`` представлен как
+        ``UnknownAttachment`` с сохраненными дополнительными полями.
     :vartype attaches: list[Attachment]
     :ivar stats: Дополнительная статистика сообщения от Max.
     :vartype stats: dict[str, Any] | None
@@ -150,10 +201,17 @@ class Message(CamelModel):
     :vartype mark: int | None
     :ivar elements: Форматированные элементы текста сообщения.
     :vartype elements: list[Element]
+    :ivar delayed_attributes: Время срабатывания в миллисекундах и настройки
+        уведомлений для отложенного сообщения; ``None`` для обычного.
+    :vartype delayed_attributes: DelayedAttributes | None
+    :ivar link: Исходное сообщение и чат для reply или forward; ``None`` для
+        обычного сообщения без связи.
+    :vartype link: ReplyLink | ForwardLink | None
     """
 
     id: int
     chat_id: int | None = None
+    post_id: int | None = None
     sender: int | None = None
     text: str = ""
     time: int
@@ -169,6 +227,8 @@ class Message(CamelModel):
     unread: int | None = None
     mark: int | None = None
     elements: list[Element] = Field(default_factory=list)
+    delayed_attributes: DelayedAttributes | None = None
+    link: Link | None = None
 
     _actions: MessageService | None = PrivateAttr(default=None)
 
@@ -189,8 +249,9 @@ class Message(CamelModel):
         attachments: SendAttachments = None,
         *,
         notify: bool = True,
+        send_at: DateTimeUnion | None = None,
     ) -> Message:
-        """Отправляет ответ на это сообщение в тот же чат.
+        """Отправляет ответ в тот же чат или ветку комментариев.
 
         :param text: Текст сообщения.
         :type text: str | None
@@ -198,19 +259,43 @@ class Message(CamelModel):
         :type attachments: SendAttachments
         :param notify: Отправить ли получателям push-уведомление.
         :type notify: bool
+        :param send_at: Абсолютный ``datetime``, относительный ``timedelta``
+            или Unix time в секундах. ``None`` и ``0`` отправляют сразу.
+        :type send_at: DateTimeUnion | None
         :returns: Отправленное сообщение.
         :rtype: Message
         :raises RuntimeError: Если сообщение не привязано к сервису или не
             содержит ``chat_id``.
+        :raises ValueError: Если для комментария задана отложенная отправка.
         """
         actions, chat_id = self._bound()
 
+        if self.post_id is not None:
+            if send_at:
+                raise ValueError("Scheduled comments are not supported")
+
+            message = await actions.send_comment(
+                chat_id=chat_id,
+                post_id=self.post_id,
+                text=text,
+                reply_to=self.id,
+                attachments=attachments,
+                notify=notify,
+            )
+            if message.chat_id is None:
+                message.chat_id = chat_id
+            if message.post_id is None:
+                message.post_id = self.post_id
+
+            return message
+
         return await actions.send_message(
             chat_id=chat_id,
             text=text,
             reply_to=self.id,
             attachments=attachments,
             notify=notify,
+            send_at=send_at,
         )
 
     async def answer(
@@ -220,8 +305,9 @@ class Message(CamelModel):
         attachments: SendAttachments = None,
         *,
         notify: bool = True,
+        send_at: DateTimeUnion | None = None,
     ) -> Message:
-        """Отправляет сообщение в тот же чат.
+        """Отправляет сообщение в тот же чат или ветку комментариев.
 
         :param text: Текст сообщения.
         :type text: str | None
@@ -231,19 +317,43 @@ class Message(CamelModel):
         :type attachments: SendAttachments
         :param notify: Отправить ли получателям push-уведомление.
         :type notify: bool
+        :param send_at: Абсолютный ``datetime``, относительный ``timedelta``
+            или Unix time в секундах. ``None`` и ``0`` отправляют сразу.
+        :type send_at: DateTimeUnion | None
         :returns: Отправленное сообщение.
         :rtype: Message
         :raises RuntimeError: Если сообщение не привязано к сервису или не
             содержит ``chat_id``.
+        :raises ValueError: Если для комментария задана отложенная отправка.
         """
         actions, chat_id = self._bound()
 
+        if self.post_id is not None:
+            if send_at:
+                raise ValueError("Scheduled comments are not supported")
+
+            message = await actions.send_comment(
+                chat_id=chat_id,
+                post_id=self.post_id,
+                text=text,
+                reply_to=reply_to,
+                attachments=attachments,
+                notify=notify,
+            )
+            if message.chat_id is None:
+                message.chat_id = chat_id
+            if message.post_id is None:
+                message.post_id = self.post_id
+
+            return message
+
         return await actions.send_message(
             chat_id=chat_id,
             text=text,
             reply_to=reply_to,
             attachments=attachments,
             notify=notify,
+            send_at=send_at,
         )
 
     async def forward(
@@ -308,6 +418,21 @@ class Message(CamelModel):
         """
         actions, chat_id = self._bound()
 
+        if self.post_id is not None:
+            message = await actions.edit_comment(
+                chat_id=chat_id,
+                post_id=self.post_id,
+                message_id=self.id,
+                text=text,
+                attachments=attachments,
+            )
+            if message.chat_id is None:
+                message.chat_id = chat_id
+            if message.post_id is None:
+                message.post_id = self.post_id
+
+            return message
+
         return await actions.edit_message(
             chat_id=chat_id,
             message_id=self.id,
@@ -327,6 +452,14 @@ class Message(CamelModel):
         """
         actions, chat_id = self._bound()
 
+        if self.post_id is not None:
+            return await actions.delete_comment(
+                chat_id=chat_id,
+                post_id=self.post_id,
+                message_ids=[self.id],
+                for_me=for_me,
+            )
+
         return await actions.delete_message(
             chat_id=chat_id,
             message_ids=[self.id],
@@ -360,9 +493,17 @@ class Message(CamelModel):
         """
         actions, chat_id = self._bound()
 
+        if self.post_id is not None:
+            return await actions.add_comment_reaction(
+                chat_id=chat_id,
+                post_id=self.post_id,
+                message_id=self.id,
+                reaction=reaction,
+            )
+
         return await actions.add_reaction(
             chat_id=chat_id,
-            message_id=str(self.id),  # :C
+            message_id=self.id,
             reaction=reaction,
         )
 
@@ -376,9 +517,16 @@ class Message(CamelModel):
         """
         actions, chat_id = self._bound()
 
+        if self.post_id is not None:
+            return await actions.remove_comment_reaction(
+                chat_id=chat_id,
+                post_id=self.post_id,
+                message_id=self.id,
+            )
+
         return await actions.remove_reaction(
             chat_id=chat_id,
-            message_id=str(self.id),  # :C x2
+            message_id=self.id,
         )
 
     async def get_reactions(self) -> dict[str, ReactionInfo] | None:
@@ -394,7 +542,7 @@ class Message(CamelModel):
 
         return await actions.get_reactions(
             chat_id=chat_id,
-            message_ids=[str(self.id)],  # :C x3
+            message_ids=[self.id],
         )
 
     def _bound(self) -> tuple[MessageService, int]:
@@ -427,6 +575,7 @@ class Message(CamelModel):
         return {
             **message,
             "chatId": value.get("chatId"),
+            "postId": value.get("postId"),
             "prevMessageId": value.get("prevMessageId"),
             "ttl": value.get("ttl"),
             "unread": value.get("unread"),

pymax/types/domain/story.py

@@ -0,0 +1,126 @@
+from typing import Annotated, Literal, TypeAlias
+
+from pydantic import Field
+
+from .attachments.enums import AttachmentType
+from .base import CamelModel
+
+
+class StoryCoordinates(CamelModel):
+    """Положение слоя сторис в долях ширины и высоты кадра."""
+
+    x: float
+    y: float
+    w: float
+    h: float
+    rotation: float = 0
+
+
+class StoryClickableLink(CamelModel):
+    """Ссылка слоя сторис и результат ее проверки сервером."""
+
+    url: str
+    check_result: int | None = None
+
+
+class StoryLayer(CamelModel):
+    """Слой сторис со ссылкой и координатами."""
+
+    type: int = 0
+    coordinates: StoryCoordinates
+    clickable_link: StoryClickableLink
+
+
+class StoryPhotoMedia(CamelModel):
+    """Фото сторис, полученное от Max, без обязательного токена загрузки."""
+
+    base_url: str
+    height: int
+    width: int
+    photo_id: int
+    preview_data: bytes | None = None
+    type: Literal[AttachmentType.PHOTO] = Field(alias="_type")
+
+
+class StoryVideoMedia(CamelModel):
+    """Видео сторис, полученное от Max.
+
+    В отличие от ``VideoAttachment``, не требует токен загрузки и
+    ``video_type``, которые используются при публикации.
+    """
+
+    height: int
+    width: int
+    video_id: int
+    duration: int | None = None
+    preview_data: bytes | None = None
+    type: Literal[AttachmentType.VIDEO] = Field(alias="_type")
+    thumbnail: str
+
+
+StoryMedia: TypeAlias = Annotated[
+    StoryPhotoMedia | StoryVideoMedia,
+    Field(discriminator="type"),
+]
+
+
+class Story(CamelModel):
+    """Сторис, возвращенная после публикации или при чтении.
+
+    :ivar id: ID сторис.
+    :ivar cid: Идентификатор публикации, сформированный клиентом.
+    :ivar media: Фото или видео сторис.
+    :ivar layers: Слои поверх кадра.
+    :ivar settings: Настройки сторис в формате Max.
+    :ivar expiration: Время жизни сторис в миллисекундах.
+    """
+
+    id: int
+    cid: int | None = None
+    media: StoryMedia
+    layers: list[StoryLayer] = Field(default_factory=list)
+    settings: int
+    expiration: int
+
+
+class StoryOwner(CamelModel):
+    """Владелец сторис.
+
+    :ivar owner_id: ID владельца, а не отдельной сторис.
+    :ivar type: Числовой тип владельца из Max. ``0`` — пользователь.
+    """
+
+    owner_id: int
+    type: int = 0
+
+
+class StoryPreview(CamelModel):
+    """Сводная информация о сторис владельца в ленте и обновлениях.
+
+    ID отдельных сторис в превью нет. Для их получения передайте
+    ``owner.owner_id`` и ``owner.type`` в ``client.get_stories()``.
+
+    :ivar owner: Владелец сторис.
+    :ivar total_count: Общее количество сторис владельца.
+    :ivar read_count: Количество просмотренных сторис владельца.
+    """
+
+    owner: StoryOwner
+    total_count: int = 0
+    read_count: int = 0
+    last_story_expiration_time: int = 0
+    settings: int = 0
+    update_time: int = 0
+
+
+class StoryDetailedStats(CamelModel):
+    """Запись подробной статистики просмотра или реакции на сторис.
+
+    Типизировано только ``user_id``. Дополнительные поля доступны в
+    ``model_extra`` с исходными именами ответа Max, без преобразования
+    camelCase. Поле ``reaction``, если оно пришло, остается словарем.
+
+    :ivar user_id: ID пользователя.
+    """
+
+    user_id: int