maxbot-api-client-python 1.1.0__py3-none-any.whl

maxbot_api_client_python/tools/messages.py

@@ -0,0 +1,194 @@
+from maxbot_api_client_python.client import Client, decode, adecode
+from maxbot_api_client_python.types.constants import Paths
+from maxbot_api_client_python.types import models
+
+class Messages:
+    def __init__(self, client: Client):
+        self.client = client
+
+    def GetMessages(self, **kwargs) -> models.MessagesList:
+        """
+        Retrieves a list of messages.
+        It can fetch messages belonging to a specific ChatID or by an exact list of MessageIDs.
+
+        Example:
+            # Fetch messages by Chat ID
+            response = api.messages.GetMessages(chat_id=123456)
+            
+            # Fetch specific messages:
+            response = api.messages.GetMessages(message_ids=["mid:1", "mid:2"])
+        """
+        req = models.GetMessagesReq(**kwargs)
+        return decode(self.client, "GET", Paths.MESSAGES, models.MessagesList, query=req.model_dump(exclude_none=True))
+
+    def SendMessage(self, **kwargs) -> models.SendMessageResp:
+        """
+        Sends a text message or attachment to a specific user or chat.
+        If Notify is False, no push notification will be sent to the user.
+
+        Example:
+            response = api.messages.SendMessage(
+                chat_id=123456,
+                text="Hello, world!",
+                notify=True
+            )
+        """
+        req = models.SendMessageReq(**kwargs)
+        return decode(self.client, "POST", Paths.MESSAGES, models.SendMessageResp, query=req.model_dump(exclude_none=True), payload=req)
+
+    def EditMessage(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Modifies the content of a previously sent message.
+
+        Example:
+            response = api.messages.EditMessage(
+                message_id="mid:987654321...",
+                text="Updated message text!",
+                format="HTML"
+            )
+        """
+        req = models.EditMessageReq(**kwargs)
+        return decode(self.client, "PUT", Paths.MESSAGES, models.SimpleQueryResult, query=req.model_dump(exclude_none=True), payload=req)
+
+    def DeleteMessage(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Removes a previously sent message by its ID.
+
+        Example:
+            response = api.messages.DeleteMessage(
+                message_id="mid:987654321..."
+            )
+        """
+        req = models.DeleteMessageReq(**kwargs)
+        return decode(self.client, "DELETE", Paths.MESSAGES, models.SimpleQueryResult, query=req.model_dump(exclude_none=True))
+
+    def GetMessage(self, **kwargs) -> models.Message:
+        """
+        Retrieves full information about a message by its ID.
+
+        Example:
+            response = api.messages.GetMessage(
+                message_id="mid:987654321..."
+            )
+        """
+        req = models.GetMessageReq(**kwargs)
+        path = f"{Paths.MESSAGES}/{req.message_id}"
+        return decode(self.client, "GET", path, models.Message)
+
+    def GetVideoInfo(self, **kwargs) -> models.GetVideoInfoResp:
+        """
+        Retrieves metadata and the processing status for an uploaded video.
+
+        Example:
+            response = api.messages.GetVideoInfo(
+                video_token="vtok_abc123xyz..."
+            )
+        """
+        req = models.GetVideoInfoReq(**kwargs)
+        path = f"{Paths.VIDEOS}/{req.video_token}"
+        return decode(self.client, "GET", path, models.GetVideoInfoResp)
+
+    def AnswerCallback(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Acknowledges and responds to a user clicking an inline button.
+
+        Example:
+            response = api.messages.AnswerCallback(
+                callback_id="cbk_12345...",
+                message=NewMessageBody(text="Action confirmed!")
+            )
+        """
+        req = models.AnswerCallbackReq(**kwargs)
+        return decode(self.client, "POST", Paths.ANSWERS, models.SimpleQueryResult, query=req.model_dump(exclude_none=True), payload=req)
+
+    async def GetMessagesAsync(self, **kwargs) -> models.MessagesList:
+        """Async version of GetMessages.
+
+        Example:
+            # Fetch messages by Chat ID
+            response = await api.messages.GetMessagesAsync(chat_id=123456)
+            
+            # Fetch specific messages:
+            response = await api.messages.GetMessagesAsync(message_ids=["mid:1", "mid:2"])
+        """
+        req = models.GetMessagesReq(**kwargs)
+        return await adecode(self.client, "GET", Paths.MESSAGES, models.MessagesList, query=req.model_dump(exclude_none=True))
+
+    async def SendMessageAsync(self, **kwargs) -> models.SendMessageResp:
+        """
+        Async version of SendMessage.
+
+        Example:
+            response = await api.messages.SendMessageAsync(
+                chat_id=123456,
+                text="Hello, world!",
+                notify=True
+            )
+        """
+        req = models.SendMessageReq(**kwargs)
+        return await adecode(self.client, "POST", Paths.MESSAGES, models.SendMessageResp, query=req.model_dump(exclude_none=True), payload=req)
+
+    async def EditMessageAsync(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Async version of EditMessage.
+
+        Example:
+            response = await api.messages.EditMessageAsync(
+                message_id="mid:987654321...",
+                text="Updated message text!",
+                format="HTML"
+            )
+        """
+        req = models.EditMessageReq(**kwargs)
+        return await adecode(self.client, "PUT", Paths.MESSAGES, models.SimpleQueryResult, query=req.model_dump(exclude_none=True), payload=req)
+
+    async def DeleteMessageAsync(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Async version of DeleteMessage.
+
+        Example:
+            response = await api.messages.DeleteMessageAsync(
+                message_id="mid:987654321..."
+            )
+        """
+        req = models.DeleteMessageReq(**kwargs)
+        return await adecode(self.client, "DELETE", Paths.MESSAGES, models.SimpleQueryResult, query=req.model_dump(exclude_none=True))
+
+    async def GetMessageAsync(self, **kwargs) -> models.Message:
+        """
+        Async version of GetMessage.
+
+        Example:
+            response = await api.messages.GetMessageAsync(
+                message_id="mid:987654321..."
+            )
+        """
+        req = models.GetMessageReq(**kwargs)
+        path = f"{Paths.MESSAGES}/{req.message_id}"
+        return await adecode(self.client, "GET", path, models.Message)
+
+    async def GetVideoInfoAsync(self, **kwargs) -> models.GetVideoInfoResp:
+        """
+        Async version of GetVideoInfo.
+
+        Example:
+            response = await api.messages.GetVideoInfoAsync(
+                video_token="vtok_abc123xyz..."
+            )
+        """
+        req = models.GetVideoInfoReq(**kwargs)
+        path = f"{Paths.VIDEOS}/{req.video_token}"
+        return await adecode(self.client, "GET", path, models.GetVideoInfoResp)
+
+    async def AnswerCallbackAsync(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Async version of AnswerCallback.
+
+        Example:
+            response = await api.messages.AnswerCallbackAsync(
+                callback_id="cbk_12345...",
+                message=NewMessageBody(text="Action confirmed!")
+            )
+        """
+        req = models.AnswerCallbackReq(**kwargs)
+        return await adecode(self.client, "POST", Paths.ANSWERS, models.SimpleQueryResult, query=req.model_dump(exclude_none=True), payload=req)

maxbot_api_client_python/tools/subscriptions.py

@@ -0,0 +1,101 @@
+from maxbot_api_client_python.client import Client, decode, adecode
+from maxbot_api_client_python.types.constants import Paths
+from maxbot_api_client_python.types import models
+
+class Subscriptions:
+    def __init__(self, client: Client):
+        self.client = client
+
+    def GetSubscriptions(self) -> models.GetSubscriptionsResp:
+        """
+        Returns a list of all subscriptions if your bot receives data via a Webhook.
+
+        Example:
+            response = api.subscriptions.GetSubscriptions()
+        """
+        return decode(self.client, "GET", Paths.SUBSCRIPTIONS, models.GetSubscriptionsResp)
+
+    def Subscribe(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Configures the delivery of bot events via Webhook.
+
+        Example:
+            response = api.subscriptions.Subscribe(
+                url="https://webhook.site/endpoint"
+            )
+        """
+        req = models.SubscribeReq(**kwargs)
+        return decode(self.client, "POST", Paths.SUBSCRIPTIONS, models.SimpleQueryResult, payload=req)
+
+    def Unsubscribe(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Unsubscribes the bot from receiving updates via Webhook.
+
+        Example:
+            response = api.subscriptions.Unsubscribe(
+                url="https://webhook.site/endpoint"
+            )
+        """
+        req = models.UnsubscribeReq(**kwargs)
+        return decode(self.client, "DELETE", Paths.SUBSCRIPTIONS, models.SimpleQueryResult, query=req.model_dump(exclude_none=True))
+
+    def GetUpdates(self, **kwargs) -> models.GetUpdatesResp:
+        """
+        Fetches new events (incoming messages, bot additions, etc.) from the server.
+        Use this method for long-polling. Provide a Marker to acknowledge previous 
+        updates and fetch only new ones.
+
+        Example:
+            response = api.subscriptions.GetUpdates(
+                marker=123456789,
+                timeout=30  # seconds to wait for new updates
+            )
+        """
+        req = models.GetUpdatesReq(**kwargs)
+        return decode(self.client, "GET", Paths.UPDATES, models.GetUpdatesResp, query=req.model_dump(exclude_none=True))
+
+    async def GetSubscriptionsAsync(self) -> models.GetSubscriptionsResp:
+        """
+        Async version of GetSubscriptions.
+
+        Example:
+            response = await api.subscriptions.GetSubscriptionsAsync()
+        """
+        return await adecode(self.client, "GET", Paths.SUBSCRIPTIONS, models.GetSubscriptionsResp)
+
+    async def SubscribeAsync(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Async version of Subscribe.
+
+        Example:
+            response = await api.subscriptions.SubscribeAsync(
+                url="https://webhook.site/endpoint"
+            )
+        """
+        req = models.SubscribeReq(**kwargs)
+        return await adecode(self.client, "POST", Paths.SUBSCRIPTIONS, models.SimpleQueryResult, payload=req)
+    
+    async def UnsubscribeAsync(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Async version of Unsubscribe.
+
+        Example:
+            response = await api.subscriptions.UnsubscribeAsync(
+                url="https://webhook.site/endpoint"
+            )
+        """
+        req = models.UnsubscribeReq(**kwargs)
+        return await adecode(self.client, "DELETE", Paths.SUBSCRIPTIONS, models.SimpleQueryResult, query=req.model_dump(exclude_none=True))
+    
+    async def GetUpdatesAsync(self, **kwargs) -> models.GetUpdatesResp:
+        """
+        Async version of GetUpdates.
+
+        Example:
+            response = await api.subscriptions.GetUpdatesAsync(
+                marker=123456789,
+                timeout=30  # seconds to wait for new updates
+            )
+        """
+        req = models.GetUpdatesReq(**kwargs)
+        return await adecode(self.client, "GET", Paths.UPDATES, models.GetUpdatesResp, query=req.model_dump(exclude_none=True))

maxbot_api_client_python/tools/uploads.py

@@ -0,0 +1,91 @@
+import asyncio, logging
+
+from pathlib import Path
+from typing import Optional
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+from maxbot_api_client_python.client import Client, decode
+from maxbot_api_client_python.types.constants import Paths, UploadType
+from maxbot_api_client_python.types.models import UploadedInfo, UploadFileReq, PhotoAttachmentRequestPayload
+
+logger = logging.getLogger(__name__)
+
+class Uploads:
+    def __init__(self, client: Client):
+        self.client = client
+
+    @retry(
+        stop=stop_after_attempt(3), 
+        wait=wait_exponential(multiplier=1, min=2, max=10),
+        reraise=True,
+    )
+
+    def UploadFile(self, **kwargs) -> UploadedInfo:
+        """
+        Uploads a file to the server and returns the upload metadata.
+        It seamlessly handles both STEP 1 (obtaining the URL) and STEP 2 (streaming the file).
+
+        Example:
+            response = api.uploads.UploadFile(
+                type=UploadType.IMAGE,
+                file_path="/path/to/image.png"
+            )
+        """
+        req = UploadFileReq(**kwargs)
+        init_resp = self.get_upload_url(req.type)
+        
+        if init_resp.url:
+            if not req.file_path:
+                raise ValueError("file_path must be provided for multipart uploads.")
+                
+            multipart_resp = self.upload_multipart(init_resp.url, req.file_path)
+
+            if multipart_resp:
+                if multipart_resp.token:
+                    return multipart_resp
+
+                if multipart_resp.photos:
+                    first_photo = next(iter(multipart_resp.photos.values()), None)
+                    if first_photo and first_photo.token:
+                        multipart_resp.token = first_photo.token
+                        return multipart_resp
+
+        if init_resp.token:
+            return UploadedInfo(token=init_resp.token)
+
+        raise Exception("Server did not return token after upload")
+
+    def get_upload_url(self, upload_type: UploadType) -> PhotoAttachmentRequestPayload:
+        """Internal helper: Obtains the target URL for uploading."""
+        return decode(self.client, "POST", Paths.UPLOADS, PhotoAttachmentRequestPayload, query={"type": upload_type.value})
+
+    def upload_multipart(self, upload_url: str, file_path: str) -> Optional[UploadedInfo]:
+        """Internal helper: Streams the file to the obtained URL."""
+        path = Path(file_path)
+        try:
+            with open(path, "rb") as f:
+                files = {"file": (path.name, f)}
+                return decode(self.client, "POST", upload_url, UploadedInfo, files=files)
+        except OSError as e:
+            logger.error(f"Failed to read file for upload: {e}")
+            return None
+
+    async def UploadFileAsync(self, **kwargs) -> UploadedInfo:
+        """
+        Async version of UploadFile.
+
+        Example:
+            response = await api.uploads.UploadFileAsync(
+                type=UploadType.IMAGE,
+                file_path="/path/to/image.png"
+            )
+        """
+        return await asyncio.to_thread(self.UploadFile, **kwargs)
+
+    async def get_upload_url_async(self, upload_type: UploadType) -> PhotoAttachmentRequestPayload:
+        """Async version of get_upload_url."""
+        return await asyncio.to_thread(self.get_upload_url, upload_type)
+
+    async def upload_multipart_async(self, upload_url: str, file_path: str) -> Optional[UploadedInfo]:
+        """Async version of upload_multipart."""
+        return await asyncio.to_thread(self.upload_multipart, upload_url, file_path)

maxbot_api_client_python/types/__init__.py

@@ -0,0 +1,4 @@
+from maxbot_api_client_python.types import models
+from maxbot_api_client_python.types import constants
+
+__all__ = ["models", "constants"]

maxbot_api_client_python/types/constants.py

@@ -0,0 +1,109 @@
+from enum import Enum
+
+DEFAULT_BASE_URL = "https://platform-api.max.ru"
+
+class Paths(str, Enum):
+    ME = "me"
+    CHATS = "chats"
+    ANSWERS = "answers"
+    UPDATES = "updates"
+    UPLOADS = "uploads"
+    MESSAGES = "messages"
+    SUBSCRIPTIONS = "subscriptions"
+    VIDEOS = "videos"
+
+    CHATS_ID = "chats/{}"
+    CHATS_PIN = "chats/{}/pin"
+    CHATS_ACTIONS = "chats/{}/actions"
+    CHATS_MEMBERS = "chats/{}/members"
+    CHATS_MEMBERS_ME = "chats/{}/members/me"
+    CHATS_MEMBERS_ADMIN = "chats/{}/members/admins"
+    CHATS_MEMBERS_ADMIN_ID = "chats/{}/members/admins/{}"
+
+class AttachmentType(str, Enum):
+    IMAGE = "image"
+    VIDEO = "video"
+    AUDIO = "audio"
+    FILE = "file"
+    STICKER = "sticker"
+    CONTACT = "contact"
+    KEYBOARD = "inline_keyboard"
+    SHARE = "share"
+    LOCATION = "location"
+
+class ChatType(str, Enum):
+    CHANNEL = "channel"
+    CHAT = "chat"
+    DIALOG = "dialog"
+
+class ChatStatus(str, Enum):
+    ACTIVE = "active"
+    CLOSED = "closed"
+    LEFT = "left"
+    REMOVED = "removed"
+
+class MarkupType(str, Enum):
+    STRONG = "strong"
+    EMPHASIZED = "emphasized"
+    MONOSPACED = "monospaced"
+    LINK = "link"
+    STRIKETHROUGH = "strikethrough"
+    UNDERLINE = "underline"
+    USER = "user_mention"
+
+class Format(str, Enum):
+    HTML = "html"
+    MARKDOWN = "markdown"
+
+class UpdateType(str, Enum):
+    BOT_ADDED = "bot_added"
+    BOT_REMOVED = "bot_removed"
+    BOT_STARTED = "bot_started"
+    BOT_STOPPED = "bot_stopped"
+    CHAT_TITLE_CHANGED = "chat_title_changed"
+    DIALOG_MUTED = "dialog_muted"
+    DIALOG_UNMUTED = "dialog_unmuted"
+    DIALOG_CLEARED = "dialog_cleared"
+    DIALOG_REMOVED = "dialog_removed"
+    MESSAGE_CREATED = "message_created"
+    MESSAGE_CALLBACK = "message_callback"
+    MESSAGE_EDITED = "message_edited"
+    MESSAGE_REMOVED = "message_removed"
+    USER_ADDED = "user_added"
+    USER_REMOVED = "user_removed"
+
+class LinkedMessageType(str, Enum):
+    FORWARD = "forward"
+    REPLY = "reply"
+
+class SenderAction(str, Enum):
+    TYPING_ON = "typing_on"
+    TYPING_OFF = "typing_off"
+    SENDING_PHOTO = "sending_photo"
+    SENDING_VIDEO = "sending_video"
+    SENDING_AUDIO = "sending_audio"
+    SENDING_FILE = "sending_file"
+    MARK_SEEN = "mark_seen"
+
+class ChatAdminPermission(str, Enum):
+    READ_ALL_MESSAGES = "read_all_messages"
+    ADD_REMOVE_USERS = "add_remove_members"
+    ADD_ADMINS = "add_admins"
+    CHANGE_CHAT_PHOTO = "change_chat_info"
+    PIN_MESSAGE = "pin_message"
+    WRITE = "write"
+    EDIT_LINK = "edit_link"
+
+class ButtonType(str, Enum):
+    CALLBACK = "callback"
+    LINK = "link"
+    REQUEST_LOCATION = "request_geo_location"
+    REQUEST_CONTACT = "request_contact"
+    OPEN_APP = "open_app"
+    MESSAGE = "message"
+
+class UploadType(str, Enum):
+    IMAGE = "image"
+    VIDEO = "video"
+    AUDIO = "audio"
+    FILE = "file"