feat: соответствие swagger

maxapi/bot.py

@@ -692,6 +692,10 @@ async def get_chat_by_link(self, link: str) -> Chat:
         """
         Получает канал по публичной ссылке или алиасу.
 
+        .. deprecated:: 1.2.1
+            Метод удалён из текущей OpenAPI-спецификации API MAX.
+            Использование не рекомендуется.
+
         https://dev.max.ru/docs-api/methods/GET/chats/-chatLink-
 
         Args:
@@ -701,6 +705,14 @@ async def get_chat_by_link(self, link: str) -> Chat:
             Chat: Объект чата.
         """
 
+        warnings.warn(
+            "bot.get_chat_by_link() устарел и отсутствует в текущей "
+            "OpenAPI-спецификации API MAX. "
+            "Использование не рекомендуется.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
         return await GetChatByLink(bot=self, link=link).fetch()
 
     async def get_chat_by_id(self, id: int) -> Chat:
@@ -913,25 +925,32 @@ async def add_list_admin_chat(
         marker: int | None = None,
     ) -> AddedListAdminChat:
         """
-        Добавляет администраторов в чат.
+        Назначает администраторов чата или канала.
 
         https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/members/admins
 
         Args:
             chat_id: ID чата.
             admins: Список администраторов.
-            marker: Указатель на следующую страницу данных.
-                По умолчанию None.
+            marker: Устаревший параметр, больше не отправляется в API.
 
         Returns:
             AddedListAdminChat: Результат добавления.
         """
 
+        if marker is not None:
+            warnings.warn(
+                "Параметр marker в bot.add_list_admin_chat() устарел "
+                "и игнорируется: POST /chats/{chatId}/members/admins "
+                "больше не поддерживает marker.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
         return await AddAdminChat(
             bot=self,
             chat_id=chat_id,
             admins=admins,
-            marker=marker,
         ).fetch()
 
     async def remove_admin(self, chat_id: int, user_id: int) -> RemovedAdmin:
@@ -1021,12 +1040,12 @@ async def add_chat_members(
         user_ids: list[int],
     ) -> AddedMembersChat:
         """
-        Добавляет участников в чат.
+        Добавляет участников в групповой чат.
 
         https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/members
 
         Args:
-            chat_id: ID чата.
+            chat_id: ID группового чата.
             user_ids: Список ID пользователей.
 
         Returns:

maxapi/enums/chat_permission.py

@@ -6,10 +6,11 @@
 @unique
 class ChatPermission(StrEnum):
     """
-    Права доступа пользователя в чате.
+    Права доступа пользователя или бота в чате или канале.
 
-    Используются для управления разрешениями при добавлении участников
-    или изменении настроек чата.
+    `add_remove_members` позволяет ботам добавлять и удалять участников
+    только в групповых чатах. Добавление подписчиков в канал через
+    `POST /chats/{chatId}/members` не поддерживается.
     """
 
     READ_ALL_MESSAGES = auto()

maxapi/methods/add_admin_chat.py

@@ -1,3 +1,4 @@
+import warnings
 from typing import TYPE_CHECKING, Any, cast
 
 from ..connection.base import BaseConnection
@@ -12,16 +13,15 @@
 
 class AddAdminChat(BaseConnection):
     """
-    Класс для добавления списка администраторов в чат через API.
+    Класс для назначения администраторов чата или канала через API.
 
     https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/members/admins
 
     Attributes:
         bot: Экземпляр бота, через который выполняется запрос.
-        chat_id: Идентификатор чата.
-        admins: Список администраторов для добавления.
-        marker: Маркер для пагинации или дополнительных
-            настроек. По умолчанию None.
+        chat_id: Идентификатор чата или канала.
+        admins: Список администраторов для назначения.
+        marker: Устаревший параметр, больше не отправляется в API.
     """
 
     def __init__(
@@ -31,6 +31,15 @@ def __init__(
         admins: list[ChatAdmin],
         marker: int | None = None,
     ):
+        if marker is not None:
+            warnings.warn(
+                "Параметр marker в AddAdminChat устарел и "
+                "игнорируется: POST /chats/{chatId}/members/admins "
+                "больше не поддерживает marker.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
         super().__init__()
         self.bot = bot
         self.chat_id = chat_id
@@ -39,7 +48,7 @@ def __init__(
 
     async def fetch(self) -> AddedListAdminChat:
         """
-        Выполняет HTTP POST запрос для добавления администраторов в чат.
+        Выполняет HTTP POST запрос для назначения администраторов.
 
         Формирует JSON с данными администраторов и отправляет запрос на
         соответствующий API-эндпоинт.
@@ -54,7 +63,6 @@ async def fetch(self) -> AddedListAdminChat:
         json: dict[str, Any] = {}
 
         json["admins"] = [admin.model_dump() for admin in self.admins]
-        json["marker"] = self.marker
 
         response = await super().request(
             method=HTTPMethod.POST,

maxapi/methods/add_members_chat.py

@@ -11,13 +11,13 @@
 
 class AddMembersChat(BaseConnection):
     """
-    Класс для добавления участников в чат через API.
+    Класс для добавления участников в групповой чат через API.
 
     https://dev.max.ru/docs-api/methods/POST/chats/-chatId-/members
 
     Attributes:
         bot: Экземпляр бота, через который выполняется запрос.
-        chat_id: Идентификатор целевого чата.
+        chat_id: Идентификатор группового чата.
         user_ids: Список ID пользователей для добавления в чат.
     """
 

maxapi/methods/get_chat_by_link.py

@@ -1,3 +1,4 @@
+import warnings
 from re import fullmatch
 from typing import TYPE_CHECKING, cast
 from urllib.parse import urlparse
@@ -15,6 +16,10 @@ class GetChatByLink(BaseConnection):
     """
     Класс для получения информации о канале по публичной ссылке.
 
+    .. deprecated:: 1.2.1
+        Метод удалён из текущей OpenAPI-спецификации API MAX.
+        Использование не рекомендуется.
+
     https://dev.max.ru/docs-api/methods/GET/chats/-chatLink-
 
     Attributes:
@@ -25,6 +30,14 @@ class GetChatByLink(BaseConnection):
     PATTERN_LINK: str = r"@?[a-zA-Z]+[a-zA-Z0-9-_]*"
 
     def __init__(self, bot: "Bot", link: str):
+        warnings.warn(
+            "GetChatByLink устарел и отсутствует в текущей "
+            "OpenAPI-спецификации API MAX. "
+            "Использование не рекомендуется.",
+            DeprecationWarning,
+            stacklevel=2,
+        )
+
         super().__init__()
         self.bot = bot
         self.link = self._normalize_link(link)

maxapi/methods/types/added_members_chat.py

@@ -7,7 +7,7 @@
 
 class FailedUserDetails(BaseModel):
     """
-    Детали ошибки для пользователя.
+    Детали ошибки добавления пользователя в групповой чат.
 
     Attributes:
         error_code: Код ошибки.
@@ -21,7 +21,7 @@ class FailedUserDetails(BaseModel):
 
 class AddedMembersChat(BaseModel):
     """
-    Ответ API при добавлении списка пользователей в чат.
+    Ответ API при добавлении списка пользователей в групповой чат.
 
     Attributes:
         success: Статус успешности операции.

maxapi/types/chats.py

@@ -3,6 +3,7 @@
 # нужен в рантайме: get_type_hints() не найдёт `builtins`,
 # если импорт только под TYPE_CHECKING
 import builtins  # noqa: TC003
+import warnings
 from datetime import datetime
 from typing import TYPE_CHECKING, Any
 
@@ -86,7 +87,7 @@ async def _walk_member_pages(
 
 
 class ChatMembersManager(BotMixin):
-    """High-level API для работы с участниками чата."""
+    """High-level API для работы с участниками группового чата."""
 
     def __init__(self, *, bot: Bot | None, chat_id: int) -> None:
         self.bot = bot
@@ -113,6 +114,8 @@ async def get(self, user_id: int) -> ChatMember | None:
         )
 
     async def add(self, user_ids: Sequence[int]) -> AddedMembersChat:
+        """Добавить участников в групповой чат."""
+
         return await self._ensure_bot().add_chat_members(
             chat_id=self.chat_id,
             user_ids=list(user_ids),
@@ -178,10 +181,18 @@ async def add(
         *,
         marker: int | None = None,
     ) -> AddedListAdminChat:
+        if marker is not None:
+            warnings.warn(
+                "Параметр marker в chat.admins.add() устарел и "
+                "игнорируется: POST /chats/{chatId}/members/admins "
+                "больше не поддерживает marker.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
+
         return await self._ensure_bot().add_list_admin_chat(
             chat_id=self.chat_id,
             admins=list(admins),
-            marker=marker,
         )
 
     async def remove(self, user_id: int) -> RemovedAdmin:
@@ -452,7 +463,7 @@ class Chats(BaseModel):
 
 class ChatMember(User):
     """
-    Модель участника чата.
+    Модель участника группового чата или канала.
 
     Attributes:
         last_access_time: Время последнего доступа.

tests/test_highlevel_shortcuts.py

@@ -192,12 +192,35 @@ async def test_chat_high_level_shortcuts_delegate_to_bot():
     bot.get_list_admin_chat.assert_awaited_once_with(100, marker=None)
     admin_call = bot.add_list_admin_chat.await_args.kwargs
     assert admin_call["chat_id"] == 100
-    assert admin_call["marker"] is None
+    assert "marker" not in admin_call
     assert len(admin_call["admins"]) == 1
     assert admin_call["admins"][0].user_id == 9
     bot.remove_admin.assert_awaited_once_with(chat_id=100, user_id=9)
 
 
+async def test_chat_admins_add_ignores_deprecated_marker():
+    """Проверить deprecated marker в high-level API администраторов."""
+    bot = ShortcutBot()
+    chat = Chat(
+        chat_id=100,
+        type=ChatType.CHAT,
+        status=ChatStatus.ACTIVE,
+        last_event_time=1,
+        participants_count=1,
+        is_public=False,
+    )
+    chat.bot = bot
+    admin = ChatAdmin(user_id=9, permissions=[])
+
+    with pytest.warns(DeprecationWarning, match="marker"):
+        await chat.admins.add([admin], marker=42)
+
+    bot.add_list_admin_chat.assert_awaited_once_with(
+        chat_id=100,
+        admins=[admin],
+    )
+
+
 async def test_chat_typing_context_sends_periodic_actions():
     bot = ShortcutBot()
     chat = Chat(