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

maxbot_api_client_python/tools/chats.py

@@ -0,0 +1,445 @@
+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 Chats:
+    def __init__(self, client: Client):
+        self.client = client
+
+    def GetChats(self, **kwargs) -> models.GetChatsResp:
+        """
+        Returns information about chats that the bot participated in: a result list and a marker pointing to the next page.
+
+        Example:
+            response = api.chats.GetChats(
+                count=20
+            )
+        """
+        req = models.GetChatsReq(**kwargs)
+        return decode(self.client, "GET", Paths.CHATS, models.GetChatsResp, query=req.model_dump(exclude_none=True))
+
+    def GetChat(self, **kwargs) -> models.ChatInfo:
+        """
+        Returns info about a specific chat.
+
+        Example:
+            response = api.chats.GetChat(
+                chat_id=123456789
+            )
+        """
+        req = models.GetChatReq(**kwargs)
+        path = Paths.CHATS_ID.format(req.chat_id)
+        return decode(self.client, "GET", path, models.ChatInfo)
+
+    def EditChat(self, **kwargs) -> models.ChatInfo:
+        """
+        Modifies the properties of a chat, such as its title, icon, or notification settings.
+
+        Example:
+            response = api.chats.EditChat(
+                chat_id=123456789,
+                title="Updated Chat Title",
+                notify=True
+            )
+        """
+        req = models.EditChatReq(**kwargs)
+        path = Paths.CHATS_ID.format(req.chat_id)
+        return decode(self.client, "PATCH", path, models.ChatInfo, payload=req)
+
+    def DeleteChat(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Permanently deletes a chat for the bot.
+
+        Example:
+            response = api.chats.DeleteChat(
+                chat_id=123456789
+            )
+        """
+        req = models.DeleteChatReq(**kwargs)
+        path = Paths.CHATS_ID.format(req.chat_id)
+        return decode(self.client, "DELETE", path, models.SimpleQueryResult)
+
+    def SendAction(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Broadcasts a temporary status action (e.g., "typing...", "recording video...") to the chat participants.
+
+        Example:
+            response = api.chats.SendAction(
+                chat_id=123456789,
+                action="mark_seen"
+            )
+        """
+        req = models.SendActionReq(**kwargs)
+        path = Paths.CHATS_ACTIONS.format(req.chat_id)
+        return decode(self.client, "POST", path, models.SimpleQueryResult, payload=req)
+
+    def GetPinnedMessage(self, **kwargs) -> models.Message:
+        """
+        Retrieves the currently pinned message in the specified chat.
+
+        Example:
+            response = api.chats.GetPinnedMessage(
+                chat_id=123456789
+            )
+        """
+        req = models.GetPinnedMessageReq(**kwargs)
+        path = Paths.CHATS_PIN.format(req.chat_id)
+        return decode(self.client, "GET", path, models.Message)
+
+    def PinMessage(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Pins a specific message in the chat.
+        You can optionally specify whether to notify chat members about the new pinned message.
+
+        Example:
+            response = api.chats.PinMessage(
+                chat_id=123456789,
+                message_id="mid:987654321...",
+                notify=True
+            )
+        """
+        req = models.PinMessageReq(**kwargs)
+        path = Paths.CHATS_PIN.format(req.chat_id)
+        return decode(self.client, "PUT", path, models.SimpleQueryResult, payload=req)
+
+    def UnpinMessage(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Removes the pinned message from the specified chat.
+
+        Example:
+            response = api.chats.UnpinMessage(
+                chat_id=123456789
+            )
+        """
+        req = models.UnpinMessageReq(**kwargs)
+        path = Paths.CHATS_PIN.format(req.chat_id)
+        return decode(self.client, "DELETE", path, models.SimpleQueryResult)
+
+    def GetChatMembership(self, **kwargs) -> models.ChatMember:
+        """
+        Returns chat membership info for the current bot.
+
+        Example:
+            response = api.chats.GetChatMembership(
+                chat_id=123456789
+            )
+        """
+        req = models.GetChatMembershipReq(**kwargs)
+        path = Paths.CHATS_MEMBERS_ME.format(req.chat_id)
+        return decode(self.client, "GET", path, models.ChatMember)
+
+    def LeaveChat(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Removes the bot from chat members.
+
+        Example:
+            response = api.chats.LeaveChat(
+                chat_id=123456789
+            )
+        """
+        req = models.LeaveChatReq(**kwargs)
+        path = Paths.CHATS_MEMBERS_ME.format(req.chat_id)
+        return decode(self.client, "DELETE", path, models.SimpleQueryResult)
+
+    def GetChatAdmins(self, **kwargs) -> models.GetChatAdminsResp:
+        """
+        Retrieves a list of administrators for the specified group chat.
+
+        Example:
+            response = api.chats.GetChatAdmins(
+                chat_id=123456789
+            )
+        """
+        req = models.GetChatAdminsReq(**kwargs)
+        path = Paths.CHATS_MEMBERS_ADMIN.format(req.chat_id)
+        return decode(self.client, "GET", path, models.GetChatAdminsResp)
+
+    def SetChatAdmins(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Assigns administrator rights to specific users in a group chat.
+
+        Example:
+            response = api.chats.SetChatAdmins(
+                chat_id=123456789,
+                admins=[
+                    ChatAdmin(user_id=98765, role="admin"),
+                    ChatAdmin(user_id=43210, role="admin")
+                ]
+            )
+        """
+        req = models.SetChatAdminsReq(**kwargs)
+        path = Paths.CHATS_MEMBERS_ADMIN.format(req.chat_id)
+        return decode(self.client, "POST", path, models.SimpleQueryResult, payload=req)
+
+    def DeleteAdmin(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Revokes administrator rights from a specific user in a group chat.
+
+        Example:
+            response = api.chats.DeleteAdmin(
+                chat_id=123456789,
+                user_id=98765
+            )
+        """
+        req = models.DeleteAdminReq(**kwargs)
+        path = Paths.CHATS_MEMBERS_ADMIN_ID.format(req.chat_id, req.user_id)
+        return decode(self.client, "DELETE", path, models.SimpleQueryResult)
+
+    def GetChatMembers(self, **kwargs) -> models.GetChatAdminsResp:
+        """
+        Returns users participated in the chat.
+
+        Example:
+            response = api.chats.GetChatMembers(
+                chat_id=123456789,
+                count=20
+            )
+        """
+        req = models.GetChatMembersReq(**kwargs)
+        path = Paths.CHATS_MEMBERS.format(req.chat_id)
+        return decode(self.client, "GET", path, models.GetChatAdminsResp, query=req.model_dump(exclude_none=True))
+
+    def AddMembers(self, **kwargs) -> models.AddMembersResp:
+        """
+        Adds one or more users to a group chat.
+
+        Example:
+            response = api.chats.AddMembers(
+                chat_id=123456789,
+                user_ids=[11111, 22222]
+            )
+        """
+        req = models.AddMembersReq(**kwargs)
+        path = Paths.CHATS_MEMBERS.format(req.chat_id)
+        return decode(self.client, "POST", path, models.AddMembersResp, payload=req)
+
+    def DeleteMember(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Removes a specific user from a group chat.
+        You can optionally block the user from rejoining.
+
+        Example:
+            response = api.chats.DeleteMember(
+                chat_id=123456789,
+                user_id=98765,
+                block=True
+            )
+        """
+        req = models.DeleteMemberReq(**kwargs)
+        path = Paths.CHATS_MEMBERS.format(req.chat_id)
+        return decode(self.client, "DELETE", path, models.SimpleQueryResult, query=req.model_dump(exclude_none=True))
+
+    async def GetChatsAsync(self, **kwargs) -> models.GetChatsResp:
+        """
+        Async version of GetChats.
+
+        Example:
+            response = await api.chats.GetChatsAsync(
+                count=20
+            )
+        """
+        req = models.GetChatsReq(**kwargs)
+        return await adecode(self.client, "GET", Paths.CHATS, models.GetChatsResp, query=req.model_dump(exclude_none=True))
+
+    async def GetChatAsync(self, **kwargs) -> models.ChatInfo:
+        """
+        Async version of GetChat.
+
+        Example:
+            response = await api.chats.GetChatAsync(
+                chat_id=123456789
+            )
+        """
+        req = models.GetChatReq(**kwargs)
+        path = Paths.CHATS_ID.format(req.chat_id)
+        return await adecode(self.client, "GET", path, models.ChatInfo)
+
+    async def EditChatAsync(self, **kwargs) -> models.ChatInfo:
+        """
+        Async version of EditChat.
+
+        Example:
+            response = await api.chats.EditChatAsync(
+                chat_id=123456789,
+                title="Updated Chat Title"
+            )
+        """
+        req = models.EditChatReq(**kwargs)
+        path = Paths.CHATS_ID.format(req.chat_id)
+        return await adecode(self.client, "PATCH", path, models.ChatInfo, payload=req)
+
+    async def DeleteChatAsync(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Async version of DeleteChat.
+
+        Example:
+            response = await api.chats.DeleteChatAsync(
+                chat_id=123456789
+            )
+        """
+        req = models.DeleteChatReq(**kwargs)
+        path = Paths.CHATS_ID.format(req.chat_id)
+        return await adecode(self.client, "DELETE", path, models.SimpleQueryResult)
+
+    async def SendActionAsync(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Async version of SendAction.
+
+        Example:
+            response = await api.chats.SendActionAsync(
+                chat_id=123456789,
+                action="typing"
+            )
+        """
+        req = models.SendActionReq(**kwargs)
+        path = Paths.CHATS_ACTIONS.format(req.chat_id)
+        return await adecode(self.client, "POST", path, models.SimpleQueryResult, payload=req)
+
+    async def GetPinnedMessageAsync(self, **kwargs) -> models.Message:
+        """
+        Async version of GetPinnedMessage.
+
+        Example:
+            response = await api.chats.GetPinnedMessageAsync(
+                chat_id=123456789
+            )
+        """
+        req = models.GetPinnedMessageReq(**kwargs)
+        path = Paths.CHATS_PIN.format(req.chat_id)
+        return await adecode(self.client, "GET", path, models.Message)
+
+    async def PinMessageAsync(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Async version of PinMessage.
+
+        Example:
+            response = await api.chats.PinMessageAsync(
+                chat_id=123456789,
+                message_id="mid:987654321..."
+            )
+        """
+        req = models.PinMessageReq(**kwargs)
+        path = Paths.CHATS_PIN.format(req.chat_id)
+        return await adecode(self.client, "PUT", path, models.SimpleQueryResult, payload=req)
+
+    async def UnpinMessageAsync(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Async version of UnpinMessage.
+
+        Example:
+            response = await api.chats.UnpinMessageAsync(
+                chat_id=123456789
+            )
+        """
+        req = models.UnpinMessageReq(**kwargs)
+        path = Paths.CHATS_PIN.format(req.chat_id)
+        return await adecode(self.client, "DELETE", path, models.SimpleQueryResult)
+
+    async def GetChatMembershipAsync(self, **kwargs) -> models.ChatMember:
+        """
+        Async version of GetChatMembership.
+
+        Example:
+            response = await api.chats.GetChatMembershipAsync(
+                chat_id=123456789
+            )
+        """
+        req = models.GetChatMembershipReq(**kwargs)
+        path = Paths.CHATS_MEMBERS_ME.format(req.chat_id)
+        return await adecode(self.client, "GET", path, models.ChatMember)
+
+    async def LeaveChatAsync(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Async version of LeaveChat.
+
+        Example:
+            response = await api.chats.LeaveChatAsync(
+                chat_id=123456789
+            )
+        """
+        req = models.LeaveChatReq(**kwargs)
+        path = Paths.CHATS_MEMBERS_ME.format(req.chat_id)
+        return await adecode(self.client, "DELETE", path, models.SimpleQueryResult)
+
+    async def GetChatAdminsAsync(self, **kwargs) -> models.GetChatAdminsResp:
+        """
+        Async version of GetChatAdmins.
+
+        Example:
+            response = await api.chats.GetChatAdminsAsync(
+                chat_id=123456789
+            )
+        """
+        req = models.GetChatAdminsReq(**kwargs)
+        path = Paths.CHATS_MEMBERS_ADMIN.format(req.chat_id)
+        return await adecode(self.client, "GET", path, models.GetChatAdminsResp)
+
+    async def SetChatAdminsAsync(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Async version of SetChatAdmins.
+
+        Example:
+            response = await api.chats.SetChatAdminsAsync(
+                chat_id=123456789,
+                admins=[ChatAdmin(user_id=98765, role="admin")]
+            )
+        """
+        req = models.SetChatAdminsReq(**kwargs)
+        path = Paths.CHATS_MEMBERS_ADMIN.format(req.chat_id)
+        return await adecode(self.client, "POST", path, models.SimpleQueryResult, payload=req)
+
+    async def DeleteAdminAsync(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Async version of DeleteAdmin.
+
+        Example:
+            response = await api.chats.DeleteAdminAsync(
+                chat_id=123456789,
+                user_id=98765
+            )
+        """
+        req = models.DeleteAdminReq(**kwargs)
+        path = Paths.CHATS_MEMBERS_ADMIN_ID.format(req.chat_id, req.user_id)
+        return await adecode(self.client, "DELETE", path, models.SimpleQueryResult)
+
+    async def GetChatMembersAsync(self, **kwargs) -> models.GetChatAdminsResp:
+        """
+        Async version of GetChatMembers.
+
+        Example:
+            response = await api.chats.GetChatMembersAsync(
+                chat_id=123456789,
+                count=20
+            )
+        """
+        req = models.GetChatMembersReq(**kwargs)
+        path = Paths.CHATS_MEMBERS.format(req.chat_id)
+        return await adecode(self.client, "GET", path, models.GetChatAdminsResp, query=req.model_dump(exclude_none=True))
+
+    async def AddMembersAsync(self, **kwargs) -> models.AddMembersResp:
+        """
+        Async version of AddMembers.
+
+        Example:
+            response = await api.chats.AddMembersAsync(
+                chat_id=123456789,
+                user_ids=[11111, 22222]
+            )
+        """
+        req = models.AddMembersReq(**kwargs)
+        path = Paths.CHATS_MEMBERS.format(req.chat_id)
+        return await adecode(self.client, "POST", path, models.AddMembersResp, payload=req)
+
+    async def DeleteMemberAsync(self, **kwargs) -> models.SimpleQueryResult:
+        """
+        Async version of DeleteMember.
+
+        Example:
+            response = await api.chats.DeleteMemberAsync(
+                chat_id=123456789,
+                user_id=98765
+            )
+        """
+        req = models.DeleteMemberReq(**kwargs)
+        path = Paths.CHATS_MEMBERS.format(req.chat_id)
+        return await adecode(self.client, "DELETE", path, models.SimpleQueryResult, query=req.model_dump(exclude_none=True))

maxbot_api_client_python/tools/helpers.py

@@ -0,0 +1,259 @@
+import aiofiles, asyncio, httpx, logging, mimetypes, os, time
+from typing import Any, List, Optional
+from urllib.parse import urlparse
+from pathlib import Path
+
+from maxbot_api_client_python.tools.uploads import Uploads
+from maxbot_api_client_python.client import Client, decode, adecode
+from maxbot_api_client_python.types.constants import AttachmentType, Paths, UploadType
+from maxbot_api_client_python.types.models import Message, SendFileReq, SendMessageReq, UploadFileReq, Attachment
+
+logger = logging.getLogger(__name__)
+
+class Helpers:
+    def __init__(self, client: Client):
+        self.client = client
+        self.uploads = Uploads(client)
+
+    def SendFile(self, **kwargs) -> Optional[Message]:
+        """
+        A helper that simplifies sending files to a chat.
+        It automatically determines whether the provided file_source is a direct URL or a local file path.
+
+        Example:
+            # Sending a file via URL:
+            response = api.helpers.SendFile(
+                chat_id=123456789,
+                text="Check out this image!",
+                file_source="https://example.com/image.png"
+            )
+
+            # Sending a local file:
+            response = api.helpers.SendFile(
+                chat_id=123456789,
+                text="Here is the report.",
+                file_source="/local/path/to/report.pdf"
+            )
+        """
+        req = SendFileReq(**kwargs)
+        if self._is_url(req.file_source):
+            return self.sendFileByUrl(req)
+        return self.sendFileByUpload(req)
+
+    def sendFileByUrl(self, req: SendFileReq) -> Optional[Message]:
+        ext = self._get_extension(req.file_source)
+        upload_type = self._determine_upload_type(ext)
+
+        if upload_type == UploadType.IMAGE:
+            attachment = Attachment(type=AttachmentType.IMAGE, payload={"url": req.file_source})
+            return self.sendFileInternal(req, attachment)
+
+        temp_path = None
+        try:
+            temp_path = self._download_temp_file(req.file_source)
+            req.file_source = temp_path
+            return self.sendFileByUpload(req)
+        except Exception as e:
+            logger.error(f"File processing/upload error: {e}")
+            return None
+        finally:
+            if temp_path and os.path.exists(temp_path):
+                os.remove(temp_path)
+
+    def sendFileByUpload(self, req: SendFileReq) -> Optional[Message]:
+        ext = self._get_extension(req.file_source)
+        upload_type = self._determine_upload_type(ext)
+
+        upload_req = UploadFileReq(type=upload_type, file_path=req.file_source)
+        upload_resp = self.uploads.UploadFile(**upload_req.model_dump_json(indent=4))
+
+        if not upload_resp or not upload_resp.token:
+            logger.error("Upload failed: No token returned.")
+            return None
+
+        attachment = self._build_attachment_from_token(upload_type, upload_resp.token, Path(req.file_source).name)
+        return self.sendFileInternal(req, attachment)
+
+    def sendFileInternal(self, req: SendFileReq, attachment: Attachment) -> Message:
+        attachments: List[Attachment] = req.attachments or []
+        attachments.append(attachment)
+
+        request_data = SendMessageReq(
+            user_id=req.user_id,
+            chat_id=req.chat_id,
+            text=req.text,
+            format=req.format,
+            attachments=attachments,
+            notify=req.notify,
+            link=req.link,
+            disable_link_preview=req.disable_link_preview
+        )
+
+        last_err: Optional[Exception] = None
+        for _ in range(self.client.max_retries):
+            try:
+                return decode(self.client, "POST", Paths.MESSAGES, Message, query=request_data.model_dump(exclude_none=True), payload=request_data)
+            except Exception as e:
+                last_err = e
+                if "not.ready" in str(e).lower():
+                    time.sleep(self.client.retry_delay_sec)
+                    continue
+                break
+
+        if last_err:
+            raise last_err
+        raise Exception("Unknown error in sendFileInternal")
+
+    async def SendFileAsync(self, **kwargs) -> Optional[Message]:
+        """
+        Async version of SendFile.
+
+        Example:
+        # Sending a local file asynchronously:
+        response = await api.helpers.SendFileAsync(
+            chat_id=123456789,
+            text="Here is the report.",
+            file_source="/local/path/to/report.pdf"
+        )
+        """
+        req = SendFileReq(**kwargs)
+        if self._is_url(req.file_source):
+            return await self.sendFileByUrlAsync(req)
+        return await self.sendFileByUploadAsync(req)
+
+    async def sendFileByUrlAsync(self, req: SendFileReq) -> Optional[Message]:
+        ext = self._get_extension(req.file_source)
+        upload_type = self._determine_upload_type(ext)
+
+        if upload_type == UploadType.IMAGE:
+            attachment = Attachment(type=AttachmentType.IMAGE, payload={"url": req.file_source})
+            return await self.sendFileInternalAsync(req, attachment)
+
+        temp_path = None
+        try:
+            temp_path = await self._download_temp_file_async(req.file_source)
+            req.file_source = temp_path
+            return await self.sendFileByUploadAsync(req)
+        except Exception as e:
+            logger.error(f"Async file processing/upload error: {e}")
+            return None
+        finally:
+            if temp_path and os.path.exists(temp_path):
+                await asyncio.to_thread(os.remove, temp_path)
+
+    async def sendFileByUploadAsync(self, req: SendFileReq) -> Optional[Message]:
+        ext = self._get_extension(req.file_source)
+        u_type = self._determine_upload_type(ext)
+
+        upload_req = UploadFileReq(type=u_type, file_path=req.file_source)
+        upload_resp = await self.uploads.UploadFileAsync(**upload_req.model_dump_json(indent=4)) 
+
+        if not upload_resp or not upload_resp.token:
+            return None
+
+        attachment = self._build_attachment_from_token(u_type, upload_resp.token, Path(req.file_source).name)
+        return await self.sendFileInternalAsync(req, attachment)
+
+    async def sendFileInternalAsync(self, req: SendFileReq, attachment: Attachment) -> Message:
+        attachments: List[Attachment] = req.attachments or []
+        attachments.append(attachment)
+
+        request_data = SendMessageReq(
+            **req.model_dump(exclude={"file_source", "attachments"}),
+            attachments=attachments
+        )
+
+        last_err: Optional[Exception] = None
+        for _ in range(self.client.max_retries):
+            try:
+                return await adecode(
+                    self.client, "POST", Paths.MESSAGES, Message, 
+                    query=request_data.model_dump(exclude_none=True), 
+                    payload=request_data
+                )
+            except Exception as e:
+                last_err = e
+                if "not.ready" in str(e).lower():
+                    await asyncio.sleep(self.client.retry_delay_sec)
+                    continue
+                break
+
+        if last_err:
+            raise last_err
+        raise Exception("Unknown error in sendFileInternalAsync")
+        
+    def _is_url(self, source: str) -> bool:
+        try:
+            result = urlparse(source)
+            return all([result.scheme, result.netloc])
+        except ValueError:
+            return False
+
+    def _get_extension(self, source: str) -> str:
+        parsed = urlparse(source)
+        path = parsed.path if parsed.scheme and parsed.netloc else source
+        return Path(path).suffix.lower()
+
+    def _determine_upload_type(self, ext: str) -> UploadType:
+        if ext in {".jpg", ".jpeg", ".png", ".webp"}:
+            return UploadType.IMAGE
+        if ext in {".mp4", ".avi", ".mov"}:
+            return UploadType.VIDEO
+        if ext in {".mp3", ".ogg", ".wav"}:
+            return UploadType.AUDIO
+        return UploadType.FILE
+
+    def _build_attachment_from_token(self, u_type: UploadType, token: str, filename: str) -> Attachment:
+        payload: dict[str, Any] = {"token": token}
+        if u_type == UploadType.FILE:
+            payload["filename"] = filename
+        return Attachment(type=AttachmentType(u_type.value), payload=payload)
+
+    def _download_temp_file(self, url_str: str) -> str:
+        headers = {"User-Agent": "maxbot-client/1.0"}
+        with httpx.Client() as client:
+            with client.stream("GET", url_str, headers=headers, follow_redirects=True) as resp:
+                resp.raise_for_status() 
+
+                content_disp = resp.headers.get("Content-Disposition", "")
+                filename = None
+                if "filename=" in content_disp:
+                    filename = content_disp.split("filename=")[1].strip('"')
+                
+                if not filename:
+                    content_type = resp.headers.get("Content-Type", "")
+                    ext = mimetypes.guess_extension(content_type.split(";")[0])
+                    if ext:
+                        filename = f"file{ext}"
+
+                if not filename:
+                    filename = Path(urlparse(url_str).path).name or "temp_file.bin"
+
+                temp_path = f"temp_{int(time.time())}_{filename}"
+
+                with open(temp_path, "wb") as f:
+                    for chunk in resp.iter_bytes(chunk_size=8192):
+                        f.write(chunk)
+                return temp_path
+    
+    async def _download_temp_file_async(self, url_str: str) -> str:
+        headers = {"User-Agent": "maxbot-client/1.0"}
+        async with httpx.AsyncClient() as client:
+            async with client.stream("GET", url_str, headers=headers, follow_redirects=True) as resp:
+                resp.raise_for_status()
+
+                content_type = resp.headers.get("Content-Type", "").split(";")[0]
+                extension = mimetypes.guess_extension(content_type) or ".bin"
+
+                url_path_name = Path(urlparse(url_str).path).name
+                if url_path_name == "uc" or not url_path_name:
+                    filename = f"file{extension}"
+                else:
+                    filename = url_path_name if "." in url_path_name else f"{url_path_name}{extension}"
+
+                temp_path = f"temp_{int(time.time())}_{filename}"
+
+                async with aiofiles.open(temp_path, "wb") as f:
+                    async for chunk in resp.aiter_bytes(chunk_size=8192):
+                        await f.write(chunk)
+                return temp_path