yuchatlib 0.2.2__py3-none-any.whl

yuchatlib/__init__.py

@@ -0,0 +1,7 @@
+"""Асинхронная библиотека для ботов YuChat."""
+
+from .bot import Bot
+from .dispatcher import Dispatcher
+from .router import Router
+
+__all__ = ["Bot", "Dispatcher", "Router"]

yuchatlib/api/__init__.py

@@ -0,0 +1,23 @@
+"""Интеграция с публичным API YuChat."""
+
+from .dto.message.button import ButtonDto
+from .dto.message.button_bar import ButtonBarDto
+from .dto.message.button_group import ButtonGroupDto
+from .dto.message.command_button import CommandButtonDto
+from .dto.message.get_messages_response import GetMessagesResponseDto
+from .dto.update.message import MessageDto
+from .dto.update.message_action import MessageActionDto
+from .dto.update.update import UpdateDto
+from .dto.webhook_info import WebhookInfoDto
+
+__all__ = [
+    "ButtonDto",
+    "ButtonBarDto",
+    "ButtonGroupDto",
+    "CommandButtonDto",
+    "GetMessagesResponseDto",
+    "MessageDto",
+    "MessageActionDto",
+    "UpdateDto",
+    "WebhookInfoDto",
+]

yuchatlib/api/_transport.py

@@ -0,0 +1,59 @@
+"""Внутренний HTTP-транспорт публичного API YuChat."""
+
+from typing import Any
+
+import httpx
+
+from yuchatlib.exceptions import ApiError, AuthenticationError, InvalidResponseError, NetworkError, RateLimitError
+
+
+class _YuChatHttpTransport:
+    """Отправляет запросы и преобразует ответы без раскрытия данных."""
+
+    def __init__(self, client: httpx.AsyncClient, base_url: str, token: str) -> None:
+        self._client = client
+        self._base_url = base_url
+        self._token = token
+
+    async def post(self, method: str, body: dict[str, Any] | None = None) -> Any:
+        try:
+            response = await self._client.post(
+                f"{self._base_url}/public/v2/{method}",
+                headers={"Authorization": f"Bearer {self._token}"},
+                json=body,
+            )
+        except httpx.RequestError:
+            pass
+        else:
+            return self.parse_response(response)
+        raise NetworkError("Ошибка соединения с YuChat")
+
+    async def request(self, http_method: str, method: str) -> httpx.Response:
+        try:
+            response = await self._client.request(
+                http_method,
+                f"{self._base_url}/public/v2/{method}",
+                headers={"Authorization": f"Bearer {self._token}"},
+            )
+        except httpx.RequestError:
+            pass
+        else:
+            return response
+        raise NetworkError("Ошибка соединения с YuChat")
+
+    @staticmethod
+    def parse_response(response: httpx.Response) -> Any:
+        """Возвращает JSON или преобразует ошибки API в исключения SDK."""
+        if response.status_code in (401, 403):
+            raise AuthenticationError(response.status_code)
+        if response.status_code == 429:
+            raise RateLimitError(429, response.headers.get("Retry-After"))
+        if not response.is_success:
+            raise ApiError(response.status_code)
+        if not response.content:
+            return None
+        try:
+            return response.json()
+        except ValueError:
+            pass
+        raise InvalidResponseError("Ответ YuChat не содержит корректный JSON")

yuchatlib/api/dto/__init__.py

@@ -0,0 +1 @@
+"""Контракты публичного API YuChat."""

yuchatlib/api/dto/me/__init__.py

@@ -0,0 +1 @@
+"""Модели сведений о боте."""

yuchatlib/api/dto/me/me_info.py

@@ -0,0 +1,19 @@
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .profile import ProfileDto
+
+
+class MeInfoDto(BaseModel):
+    """Сведения о боте и настройках обновлений."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+    profile: ProfileDto = Field(description="Профиль бота.")
+    workspaces: list[str] = Field(description="Рабочие пространства бота.")
+    update_api_version: int = Field(alias="updateApiVersion", description="Версия API обновлений.")
+    update_settings: list[str] = Field(alias="updateSettings", description="Включённые типы обновлений.")
+    auto_accept_workspace_invites: bool = Field(
+        alias="autoAcceptWorkspaceInvites", description="Автоматическое принятие приглашений."
+    )
+    scope: dict[str, Any] = Field(description="Область действия бота.")

yuchatlib/api/dto/me/profile.py

@@ -0,0 +1,13 @@
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ProfileDto(BaseModel):
+    """Профиль аккаунта бота."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+    account_id: str = Field(alias="accountId", description="Идентификатор аккаунта.")
+    created_at: datetime = Field(alias="createdAt", description="Время создания аккаунта.")
+    updated_at: datetime = Field(alias="updatedAt", description="Время изменения аккаунта.")
+    account_type: str = Field(alias="accountType", description="Тип аккаунта.")

yuchatlib/api/dto/message/__init__.py

@@ -0,0 +1 @@
+"""Модели операций с сообщениями."""

yuchatlib/api/dto/message/button.py

@@ -0,0 +1,13 @@
+"""Контракт кнопки сообщения."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .command_button import CommandButtonDto
+
+
+class ButtonDto(BaseModel):
+    """Командная кнопка сообщения."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    command_button: CommandButtonDto = Field(alias="commandButton", description="Командная кнопка.")

yuchatlib/api/dto/message/button_bar.py

@@ -0,0 +1,13 @@
+"""Контракт панели кнопок."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .button_group import ButtonGroupDto
+
+
+class ButtonBarDto(BaseModel):
+    """Панель кнопок сообщения."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    button_groups: list[ButtonGroupDto] = Field(alias="buttonGroups", description="Ряды кнопок.")

yuchatlib/api/dto/message/button_group.py

@@ -0,0 +1,11 @@
+"""Контракт группы кнопок."""
+
+from pydantic import BaseModel, Field
+
+from .button import ButtonDto
+
+
+class ButtonGroupDto(BaseModel):
+    """Ряд кнопок сообщения."""
+
+    buttons: list[ButtonDto] = Field(description="Кнопки в ряду.")

yuchatlib/api/dto/message/command_button.py

@@ -0,0 +1,12 @@
+"""Контракт командной кнопки."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class CommandButtonDto(BaseModel):
+    """Команда и отображаемый текст кнопки."""
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    display_text: str = Field(alias="displayText", description="Текст кнопки.")
+    command_key: str = Field(alias="commandKey", description="Команда нажатой кнопки.")

yuchatlib/api/dto/message/get_messages_response.py

@@ -0,0 +1,11 @@
+from pydantic import BaseModel, ConfigDict, Field
+
+from yuchatlib.api.dto.update.message import MessageDto
+
+
+class GetMessagesResponseDto(BaseModel):
+    """Список сообщений, полученных из чата."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    messages: list[MessageDto] = Field(description="Сообщения чата.")

yuchatlib/api/dto/message/send_message_response.py

@@ -0,0 +1,8 @@
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class SendMessageResponseDto(BaseModel):
+    """Результат отправки сообщения."""
+
+    model_config = ConfigDict(populate_by_name=True, extra="allow")
+    message_id: str = Field(alias="messageId", description="Идентификатор отправленного сообщения.")

yuchatlib/api/dto/update/__init__.py

@@ -0,0 +1 @@
+"""Модели получаемых обновлений."""

yuchatlib/api/dto/update/message.py

@@ -0,0 +1,20 @@
+from datetime import datetime
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .message_content import MessageContentDto
+
+
+class MessageDto(BaseModel):
+    """Сообщение в чате YuChat."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+    workspace_id: str = Field(alias="workspaceId", description="Идентификатор рабочего пространства.")
+    chat_id: str = Field(alias="chatId", description="Идентификатор чата.")
+    message_id: str = Field(alias="messageId", description="Идентификатор сообщения.")
+    message_type: Literal["USER", "SYSTEM"] = Field(alias="messageType", description="Тип сообщения.")
+    membership_id: str = Field(alias="membershipId", description="Идентификатор автора в рабочем пространстве.")
+    created_at: datetime = Field(alias="createdAt", description="Время создания сообщения.")
+    updated_at: datetime = Field(alias="updatedAt", description="Время изменения сообщения.")
+    content: MessageContentDto = Field(description="Содержимое сообщения.")

yuchatlib/api/dto/update/message_action.py

@@ -0,0 +1,15 @@
+from pydantic import BaseModel, ConfigDict, Field
+
+from .pressed_button_command import PressedButtonCommandDto
+
+
+class MessageActionDto(BaseModel):
+    """Действие с кнопкой сообщения."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+    workspace_id: str = Field(alias="workspaceId", description="Идентификатор рабочего пространства.")
+    chat_id: str = Field(alias="chatId", description="Идентификатор чата.")
+    message_id: str = Field(alias="messageId", description="Идентификатор сообщения.")
+    pressed_button_command: PressedButtonCommandDto | None = Field(
+        default=None, alias="pressedButtonCommand", description="Команда нажатой кнопки, если передана."
+    )

yuchatlib/api/dto/update/message_content.py

@@ -0,0 +1,11 @@
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class MessageContentDto(BaseModel):
+    """Содержимое сообщения YuChat."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+    text: str | None = Field(default=None, description="Текст сообщения в формате Markdown.")
+    file_ids: list[str] | None = Field(
+        default=None, alias="fileIds", description="Идентификаторы прикреплённых файлов."
+    )

yuchatlib/api/dto/update/pressed_button_command.py

@@ -0,0 +1,9 @@
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class PressedButtonCommandDto(BaseModel):
+    """Команда нажатой кнопки."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+    display_text: str = Field(alias="displayText", description="Текст кнопки.")
+    command_key: str = Field(alias="commandKey", description="Команда нажатой кнопки.")

yuchatlib/api/dto/update/update.py

@@ -0,0 +1,21 @@
+from typing import Any
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from .message import MessageDto
+from .message_action import MessageActionDto
+
+
+class UpdateDto(BaseModel):
+    """Обновление, полученное ботом."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+    update_id: int | None = Field(default=None, alias="updateId", description="Идентификатор обновления.")
+    message: MessageDto | None = Field(default=None, description="Новое сообщение.")
+    message_action: MessageActionDto | None = Field(
+        default=None, alias="messageAction", description="Действие с сообщением."
+    )
+    notification: dict[str, Any] | None = Field(default=None, description="Уведомление.")
+    workspace_invite: dict[str, Any] | None = Field(
+        default=None, alias="workspaceInvite", description="Приглашение в рабочее пространство."
+    )

yuchatlib/api/dto/update/updates_response.py

@@ -0,0 +1,9 @@
+from pydantic import BaseModel, Field
+
+from .update import UpdateDto
+
+
+class UpdatesResponseDto(BaseModel):
+    """Список полученных обновлений."""
+
+    updates: list[UpdateDto] = Field(description="Полученные обновления.")

yuchatlib/api/dto/webhook_info.py

@@ -0,0 +1,19 @@
+from datetime import datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class WebhookInfoDto(BaseModel):
+    """Сведения о зарегистрированном webhook."""
+
+    model_config = ConfigDict(extra="allow", populate_by_name=True)
+
+    url: str = Field(description="Адрес webhook.")
+    has_custom_certificate: bool = Field(alias="hasCustomCertificate", description="Признак собственного сертификата.")
+    pending_update_count: int | None = Field(
+        default=None, alias="pendingUpdateCount", description="Число ожидающих событий."
+    )
+    last_error_date: datetime | None = Field(default=None, alias="lastErrorDate", description="Время последней ошибки.")
+    last_error_message: str | None = Field(
+        default=None, alias="lastErrorMessage", description="Описание последней ошибки."
+    )

yuchatlib/bot.py

@@ -0,0 +1,220 @@
+"""Клиент публичного API YuChat."""
+
+from typing import Any, Literal
+from uuid import uuid4
+
+import httpx
+from pydantic import ValidationError
+
+from yuchatlib.api._transport import _YuChatHttpTransport
+from yuchatlib.api.dto.me.me_info import MeInfoDto
+from yuchatlib.api.dto.message.button_bar import ButtonBarDto
+from yuchatlib.api.dto.message.get_messages_response import GetMessagesResponseDto
+from yuchatlib.api.dto.message.send_message_response import SendMessageResponseDto
+from yuchatlib.api.dto.update.message import MessageDto
+from yuchatlib.api.dto.update.updates_response import UpdatesResponseDto
+from yuchatlib.api.dto.webhook_info import WebhookInfoDto
+from yuchatlib.exceptions import InvalidResponseError
+
+
+class Bot:
+    """Управляет запросами к API и собственной HTTP-сессией."""
+
+    def __init__(
+        self,
+        token: str,
+        *,
+        base_url: str,
+        client: httpx.AsyncClient | None = None,
+        timeout: float = 30.0,
+        fsm_namespace: str | None = None,
+    ) -> None:
+        if not token:
+            raise ValueError("Токен не должен быть пустым")
+        if not base_url or not base_url.strip():
+            raise ValueError("Адрес API не должен быть пустым")
+        if fsm_namespace is not None and (not isinstance(fsm_namespace, str) or not fsm_namespace.strip()):
+            raise ValueError("Namespace FSM должен быть непустой строкой")
+        if fsm_namespace == token:
+            raise ValueError("Токен нельзя использовать как namespace FSM")
+        self._token = token
+        self._fsm_id = fsm_namespace if fsm_namespace is not None else uuid4().hex
+        self._fsm_stable = fsm_namespace is not None
+        self._base_url = base_url.rstrip("/")
+        self._owns_client = client is None
+        self._client = client or httpx.AsyncClient(timeout=timeout)
+        self._transport = _YuChatHttpTransport(self._client, self._base_url, self._token)
+
+    async def __aenter__(self) -> "Bot":
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+    async def close(self) -> None:
+        """Закрывает HTTP-клиент, созданный библиотекой."""
+        if self._owns_client:
+            await self._client.aclose()
+
+    async def _post(self, method: str, body: dict[str, Any] | None = None) -> Any:
+        return await self._transport.post(method, body)
+
+    async def _webhook_request(self, http_method: str, method: str) -> httpx.Response:
+        return await self._transport.request(http_method, method)
+
+    @staticmethod
+    def _parse_response(response: httpx.Response) -> Any:
+        return _YuChatHttpTransport.parse_response(response)
+
+    async def get_updates(self, *, offset: int | None = None, limit: int = 20) -> UpdatesResponseDto:
+        """Получает пакет обновлений."""
+        if not 1 <= limit <= 1000:
+            raise ValueError("limit должен находиться в диапазоне от 1 до 1000")
+        body = {"limit": limit}
+        if offset is not None:
+            body["offset"] = offset
+        payload = await self._post("getUpdates", body)
+        try:
+            return UpdatesResponseDto.model_validate(payload)
+        except ValidationError:
+            pass
+        raise InvalidResponseError("Некорректный ответ getUpdates")
+
+    async def get_me(self) -> MeInfoDto:
+        """Получает сведения о боте."""
+        payload = await self._post("getMe")
+        try:
+            return MeInfoDto.model_validate(payload)
+        except ValidationError:
+            pass
+        raise InvalidResponseError("Некорректный ответ getMe")
+
+    async def set_update_settings(
+        self,
+        update_settings: list[Literal["MESSAGE", "MESSAGE_ACTION", "NOTIFICATION", "WORKSPACE_INVITE"]],
+        *,
+        update_api_version: Literal[1, 2] = 2,
+        auto_accept_workspace_invites: bool | None = None,
+    ) -> None:
+        """Явно изменяет настройки обновлений бота."""
+        body: dict[str, Any] = {"updateSettings": update_settings, "updateApiVersion": update_api_version}
+        if auto_accept_workspace_invites is not None:
+            body["autoAcceptWorkspaceInvites"] = auto_accept_workspace_invites
+        await self._post("setUpdateSettings", body)
+
+    async def send_message(
+        self, *, workspace_id: str, chat_id: str, text: str, button_bar: ButtonBarDto | None = None
+    ) -> SendMessageResponseDto:
+        """Отправляет текстовое сообщение с необязательными кнопками."""
+        body: dict[str, Any] = {"workspaceId": workspace_id, "chatId": chat_id, "text": text}
+        if button_bar is not None:
+            body["buttonBar"] = button_bar.model_dump(by_alias=True, mode="json", exclude_none=True)
+        payload = await self._post("sendMessage", body)
+        try:
+            return SendMessageResponseDto.model_validate(payload)
+        except ValidationError:
+            pass
+        raise InvalidResponseError("Некорректный ответ sendMessage")
+
+    async def get_messages(
+        self,
+        *,
+        workspace_id: str,
+        chat_id: str,
+        page_size: int | None = None,
+        anchor_message_id: str | None = None,
+        get_before: bool | None = None,
+    ) -> GetMessagesResponseDto:
+        """Получает сообщения чата с необязательной пагинацией."""
+        if page_size is not None and not 1 <= page_size <= 100:
+            raise ValueError("page_size должен находиться в диапазоне от 1 до 100")
+        body: dict[str, Any] = {"workspaceId": workspace_id, "chatId": chat_id}
+        if page_size is not None:
+            body["pageSize"] = page_size
+        if anchor_message_id is not None:
+            body["anchorMessageId"] = anchor_message_id
+        if get_before is not None:
+            body["getBefore"] = get_before
+        payload = await self._post("getMessages", body)
+        try:
+            return GetMessagesResponseDto.model_validate(payload)
+        except ValidationError:
+            pass
+        raise InvalidResponseError("Некорректный ответ getMessages")
+
+    async def get_message_by_id(self, *, workspace_id: str, chat_id: str, message_id: str) -> MessageDto:
+        """Получает сообщение по идентификатору."""
+        payload = await self._post(
+            "getMessageById",
+            {"workspaceId": workspace_id, "chatId": chat_id, "messageId": message_id},
+        )
+        try:
+            return MessageDto.model_validate(payload)
+        except ValidationError:
+            pass
+        raise InvalidResponseError("Некорректный ответ getMessageById")
+
+    async def edit_message(
+        self,
+        *,
+        workspace_id: str,
+        chat_id: str,
+        message_id: str,
+        text: str | None = None,
+        file_ids: list[str] | None = None,
+        button_bar: ButtonBarDto | None = None,
+    ) -> None:
+        """Редактирует сообщение в чате."""
+        body: dict[str, Any] = {"workspaceId": workspace_id, "chatId": chat_id, "messageId": message_id}
+        if text is not None:
+            body["text"] = text
+        if file_ids is not None:
+            body["fileIds"] = file_ids
+        if button_bar is not None:
+            body["buttonBar"] = button_bar.model_dump(by_alias=True, mode="json", exclude_none=True)
+        payload = await self._post("editMessage", body)
+        if payload is not None and not isinstance(payload, dict):
+            raise InvalidResponseError("Некорректный ответ editMessage")
+
+    async def set_webhook(self, *, url: str, secret_token: str | None = None, certificate: str | None = None) -> None:
+        """Явно регистрирует webhook бота."""
+        body = {"url": url}
+        if secret_token is not None:
+            body["secretToken"] = secret_token
+        if certificate is not None:
+            body["certificate"] = certificate
+        payload = await self._post("setWebhook", body)
+        if payload is not None and not isinstance(payload, dict):
+            raise InvalidResponseError("Некорректный ответ setWebhook")
+
+    async def delete_webhook(self) -> None:
+        """Явно удаляет регистрацию webhook бота."""
+        response = await self._webhook_request("DELETE", "deleteWebhook")
+        payload = self._parse_response(response)
+        if payload is not None and not isinstance(payload, dict):
+            raise InvalidResponseError("Некорректный ответ deleteWebhook")
+
+    async def get_webhook_info(self) -> WebhookInfoDto | None:
+        """Возвращает настройки webhook или None, если он не найден."""
+        response = await self._webhook_request("GET", "getWebhookInfo")
+        if response.status_code == 404:
+            return None
+        payload = self._parse_response(response)
+        try:
+            return WebhookInfoDto.model_validate(payload)
+        except ValidationError:
+            pass
+        raise InvalidResponseError("Некорректный ответ getWebhookInfo")
+
+
+def _fsm_identity(bot: Bot) -> str:
+    """Возвращает внутренний идентификатор экземпляра для изоляции FSM."""
+    # Функция представляет внутренний контракт модуля для диспетчера.
+    # noinspection PyProtectedMember
+    return bot._fsm_id
+
+
+def _has_stable_fsm_identity(bot: Bot) -> bool:
+    """Проверяет, задана ли постоянная идентичность для FSM."""
+    # noinspection PyProtectedMember
+    return bot._fsm_stable