maxapi-python 1.1.20__py3-none-any.whl → 1.2.1__py3-none-any.whl

pymax/mixins/auth.py

@@ -1,14 +1,17 @@
 import asyncio
+import datetime
 import re
 import sys
 from typing import Any
 
+import qrcode
+
 from pymax.exceptions import Error
 from pymax.interfaces import ClientProtocol
 from pymax.mixins.utils import MixinsUtils
 from pymax.payloads import RegisterPayload, RequestCodePayload, SendCodePayload
 from pymax.static.constant import PHONE_REGEX
-from pymax.static.enum import AuthType, Opcode
+from pymax.static.enum import AuthType, DeviceType, Opcode
 
 
 class AuthMixin(ClientProtocol):
@@ -19,15 +22,20 @@ class AuthMixin(ClientProtocol):
         """
         Запрашивает код аутентификации для указанного номера телефона и возвращает временный токен.
 
-        Note:
-            Использовать только в кастомном login flow.
+        Метод отправляет запрос на получение кода верификации на переданный номер телефона.
+        Используется в процессе аутентификации или регистрации.
 
-        Args:
-            phone (str): Номер телефона в международном формате.
-            language (str, optional): Язык для сообщения с кодом. По умолчанию "ru".
+        :param phone: Номер телефона в международном формате.
+        :type phone: str
+        :param language: Язык для сообщения с кодом. По умолчанию "ru".
+        :type language: str
+        :return: Временный токен для дальнейшей аутентификации.
+        :rtype: str
+        :raises ValueError: Если полученные данные имеют неверный формат.
+        :raises Error: Если сервер вернул ошибку.
 
-        Returns:
-            str: Временный токен для дальнейшей аутентификации.
+        .. note::
+            Используется только в пользовательском flow аутентификации.
         """
         self.logger.info("Requesting auth code")
 
@@ -52,7 +60,54 @@ class AuthMixin(ClientProtocol):
             self.logger.error("Invalid payload data received")
             raise ValueError("Invalid payload data received")
 
+    async def resend_code(self, phone: str, language: str = "ru") -> str:
+        """
+        Повторно запрашивает код аутентификации для указанного номера телефона и возвращает временный токен.
+
+        :param phone: Номер телефона в международном формате.
+        :type phone: str
+        :param language: Язык для сообщения с кодом. По умолчанию "ru".
+        :type language: str
+        :return: Временный токен для дальнейшей аутентификации.
+        :rtype: str
+        :raises ValueError: Если полученные данные имеют неверный формат.
+        :raises Error: Если сервер вернул ошибку.
+        """
+        self.logger.info("Resending auth code")
+
+        payload = RequestCodePayload(
+            phone=phone, type=AuthType.RESEND, language=language
+        ).model_dump(by_alias=True)
+
+        data = await self._send_and_wait(opcode=Opcode.AUTH_REQUEST, payload=payload)
+
+        if data.get("payload", {}).get("error"):
+            MixinsUtils.handle_error(data)
+
+        self.logger.debug(
+            "Code resend response opcode=%s seq=%s",
+            data.get("opcode"),
+            data.get("seq"),
+        )
+        payload_data = data.get("payload")
+        if isinstance(payload_data, dict):
+            return payload_data["token"]
+        else:
+            self.logger.error("Invalid payload data received")
+            raise ValueError("Invalid payload data received")
+
     async def _send_code(self, code: str, token: str) -> dict[str, Any]:
+        """
+        Отправляет код верификации на сервер для подтверждения.
+
+        :param code: Код верификации (6 цифр).
+        :type code: str
+        :param token: Временный токен, полученный из request_code.
+        :type token: str
+        :return: Словарь с данными ответа сервера, содержащий токены аутентификации.
+        :rtype: dict[str, Any]
+        :raises Error: Если сервер вернул ошибку.
+        """
         self.logger.info("Sending verification code")
 
         payload = SendCodePayload(
@@ -78,32 +133,176 @@ class AuthMixin(ClientProtocol):
             self.logger.error("Invalid payload data received")
             raise ValueError("Invalid payload data received")
 
+    def _print_qr(self, qr_link: str) -> None:
+        qr = qrcode.QRCode(
+            version=1,
+            error_correction=qrcode.ERROR_CORRECT_L,
+            box_size=1,
+            border=1,
+        )
+        qr.add_data(qr_link)
+        qr.make(fit=True)
+
+        qr.print_ascii()
+
+    async def _request_qr_login(self) -> dict[str, Any]:
+        self.logger.info("Requesting QR login data")
+
+        data = await self._send_and_wait(opcode=Opcode.GET_QR, payload={})
+
+        if data.get("payload", {}).get("error"):
+            MixinsUtils.handle_error(data)
+
+        self.logger.debug(
+            "QR login data response opcode=%s seq=%s",
+            data.get("opcode"),
+            data.get("seq"),
+        )
+        payload_data = data.get("payload")
+        if isinstance(payload_data, dict):
+            return payload_data
+        else:
+            self.logger.error("Invalid payload data received")
+            raise ValueError("Invalid payload data received")
+
+    def _validate_version(self, version: str, min_version: str) -> bool:
+        def version_tuple(v: str) -> tuple[int, ...]:
+            return tuple(map(int, (v.split("."))))
+
+        return version_tuple(version) >= version_tuple(min_version)
+
     async def _login(self) -> None:
         self.logger.info("Starting login flow")
 
-        temp_token = await self.request_code(self.phone)
-        if not temp_token or not isinstance(temp_token, str):
-            self.logger.critical("Failed to request code: token missing")
-            raise ValueError("Failed to request code")
+        if self.user_agent.device_type == DeviceType.WEB.value and self._ws:
+            if not self._validate_version(self.user_agent.app_version, "25.12.13"):
+                self.logger.error("Your app version is too old")
+                raise ValueError("Your app version is too old")
 
-        print("Введите код: ", end="", flush=True)
-        code = await asyncio.to_thread(lambda: sys.stdin.readline().strip())
-        if len(code) != 6 or not code.isdigit():
-            self.logger.error("Invalid code format entered")
-            raise ValueError("Invalid code format")
+            login_resp = await self._login_by_qr()
+        else:
+            temp_token = await self.request_code(self.phone)
+            if not temp_token or not isinstance(temp_token, str):
+                self.logger.critical("Failed to request code: token missing")
+                raise ValueError("Failed to request code")
+
+            print("Введите код: ", end="", flush=True)
+            code = await asyncio.to_thread(lambda: sys.stdin.readline().strip())
+            if len(code) != 6 or not code.isdigit():
+                self.logger.error("Invalid code format entered")
+                raise ValueError("Invalid code format")
+
+            login_resp = await self._send_code(code, temp_token)
+
+        token = login_resp.get("tokenAttrs", {}).get("LOGIN", {}).get("token", "")
 
-        login_resp = await self._send_code(code, temp_token)
-        token: str | None = (
-            login_resp.get("tokenAttrs", {}).get("LOGIN", {}).get("token")
-        )
         if not token:
             self.logger.critical("Failed to login, token not received")
             raise ValueError("Failed to login, token not received")
 
         self._token = token
-        self._database.update_auth_token(self._device_id, self._token)
+        self._database.update_auth_token((self._device_id), self._token)
         self.logger.info("Login successful, token saved to database")
 
+    async def _poll_qr_login(self, track_id: str, poll_interval: int) -> bool:
+        self.logger.info("Polling for QR login confirmation")
+
+        while True:
+            data = await self._send_and_wait(
+                opcode=Opcode.GET_QR_STATUS,
+                payload={"trackId": track_id},
+            )
+
+            payload = data.get("payload", {})
+
+            if payload.get("error"):
+                MixinsUtils.handle_error(data)
+            status = payload.get("status")
+
+            if not status:
+                self.logger.warning("No status in QR login response")
+                continue
+
+            if status.get("loginAvailable"):
+                self.logger.info("QR login confirmed")
+                return True
+            else:
+                exp_at = status.get("expiresAt")
+                if (
+                    exp_at
+                    and isinstance(exp_at, (int, float))
+                    and exp_at < datetime.datetime.now().timestamp() * 1000
+                ):
+                    self.logger.warning("QR code expired")
+                    return False
+
+            await asyncio.sleep(poll_interval / 1000)
+
+    async def _get_qr_login_data(self, track_id: str) -> dict[str, Any]:
+        self.logger.info("Getting QR login data")
+
+        data = await self._send_and_wait(
+            opcode=Opcode.LOGIN_BY_QR,
+            payload={"trackId": track_id},
+        )
+
+        self.logger.debug(
+            "QR login data response opcode=%s seq=%s",
+            data.get("opcode"),
+            data.get("seq"),
+        )
+        payload_data = data.get("payload")
+        if isinstance(payload_data, dict):
+            return payload_data
+        else:
+            self.logger.error("Invalid payload data received")
+            raise ValueError("Invalid payload data received")
+
+    async def _login_by_qr(self) -> dict[str, Any]:
+        data = await self._request_qr_login()
+
+        poll_interval = data.get("pollingInterval")
+        link = data.get("qrLink")
+        track_id = data.get("trackId")
+        expires_at = data.get("expiresAt")
+
+        if not poll_interval or not link or not track_id or not expires_at:
+            self.logger.critical("Invalid QR login data received")
+            raise ValueError("Invalid QR login data received")
+
+        self.logger.info("Starting QR login flow")
+        self._print_qr(link)
+
+        poll_qr_task = asyncio.create_task(self._poll_qr_login(track_id, poll_interval))
+
+        while True:
+            now_ms = datetime.datetime.now().timestamp() * 1000
+
+            done, pending = await asyncio.wait(
+                [poll_qr_task],
+                timeout=1,
+                return_when=asyncio.FIRST_COMPLETED,
+            )
+
+            if now_ms >= expires_at:
+                poll_qr_task.cancel()
+                self.logger.error("QR code expired before confirmation")
+                raise RuntimeError("QR code expired before confirmation")
+
+            if poll_qr_task in done:
+                exc = poll_qr_task.exception()
+                if exc is not None:
+                    raise exc
+                elif poll_qr_task.result():
+                    self.logger.info("QR login successful")
+
+                    data = await self._get_qr_login_data(track_id)
+                    return data
+
+                else:
+                    self.logger.error("QR login failed or expired")
+                    raise RuntimeError("QR login failed or expired")
+
     async def _submit_reg_info(
         self, first_name: str, last_name: str | None, token: str
     ) -> dict[str, Any]:
@@ -116,9 +315,7 @@ class AuthMixin(ClientProtocol):
                 token=token,
             ).model_dump(by_alias=True)
 
-            data = await self._send_and_wait(
-                opcode=Opcode.AUTH_CONFIRM, payload=payload
-            )
+            data = await self._send_and_wait(opcode=Opcode.AUTH_CONFIRM, payload=payload)
             if data.get("payload", {}).get("error"):
                 MixinsUtils.handle_error(data)
 
@@ -152,9 +349,7 @@ class AuthMixin(ClientProtocol):
             raise ValueError("Invalid code format")
 
         registration_response = await self._send_code(code, temp_token)
-        token: str | None = (
-            registration_response.get("tokenAttrs", {}).get("REGISTER", {}).get("token")
-        )
+        token = registration_response.get("tokenAttrs", {}).get("REGISTER", {}).get("token", "")
         if not token:
             self.logger.critical("Failed to register, token not received")
             raise ValueError("Failed to register, token not received")
@@ -165,5 +360,9 @@ class AuthMixin(ClientProtocol):
             self.logger.critical("Failed to register, token not received")
             raise ValueError("Failed to register, token not received")
 
-        self._database.update_auth_token(self._device_id, self._token)
-        self.logger.info("Registration successful, token saved to database")
+        self.logger.info("Registration successful")
+        self.logger.info("Token: %s", self._token)
+        self.logger.warning(
+            "IMPORTANT: Use this token ONLY with device_type='DESKTOP' and the special init user agent"
+        )
+        self.logger.warning("This token MUST NOT be used in web clients")

pymax/mixins/channel.py

@@ -12,23 +12,18 @@ from pymax.static.constant import (
     DEFAULT_MARKER_VALUE,
 )
 from pymax.static.enum import Opcode
-from pymax.types import Member
+from pymax.types import Channel, Member
 
 
 class ChannelMixin(ClientProtocol):
-    async def resolve_channel_by_name(self, name: str) -> bool:
+    async def resolve_channel_by_name(self, name: str) -> Channel | None:
         """
-        Пытается найти канал по его имени
+        Получает информацию о канале по его имени
 
-        Args:
-            name (str): Имя канала
-
-        Exceptions:
-            ResponseError: Ошибка в ответе сервера
-            ResponseStructureError: Ошибка структуры ответа сервера
-
-        Returns:
-            bool: True, если канал найден
+        :param name: Имя канала
+        :type name: str
+        :return: Объект Channel или None, если канал не найден
+        :rtype: Channel | None
         """
         payload = ResolveLinkPayload(
             link=f"https://max.ru/{name}",
@@ -37,21 +32,20 @@ class ChannelMixin(ClientProtocol):
         data = await self._send_and_wait(opcode=Opcode.LINK_INFO, payload=payload)
         if data.get("payload", {}).get("error"):
             MixinsUtils.handle_error(data)
-        return True
 
-    async def join_channel(self, link: str) -> bool:
+        channel = Channel.from_dict(data.get("payload", {}).get("chat", {}))
+        if channel not in self.channels:
+            self.channels.append(channel)
+        return channel
+
+    async def join_channel(self, link: str) -> Channel | None:
         """
         Присоединяется к каналу по ссылке
 
-        Args:
-            link (str): Ссылка на канал
-
-        Exceptions:
-            ResponseError: Ошибка в ответе сервера
-            ResponseStructureError: Ошибка структуры ответа сервера
-
-        Returns:
-            bool: True, если присоединение прошло успешно
+        :param link: Ссылка на канал
+        :type link: str
+        :return: Объект канала, если присоединение прошло успешно, иначе None
+        :rtype: Channel | None
         """
         payload = JoinChatPayload(
             link=link,
@@ -60,7 +54,11 @@ class ChannelMixin(ClientProtocol):
         data = await self._send_and_wait(opcode=Opcode.CHAT_JOIN, payload=payload)
         if data.get("payload", {}).get("error"):
             MixinsUtils.handle_error(data)
-        return True
+
+        channel = Channel.from_dict(data.get("payload", {}).get("chat", {}))
+        if channel not in self.channels:
+            self.channels.append(channel)
+        return channel
 
     async def _query_members(
         self, payload: GetGroupMembersPayload | SearchGroupMembersPayload
@@ -102,13 +100,14 @@ class ChannelMixin(ClientProtocol):
         """
         Загружает членов канала
 
-        Args:
-            chat_id (int): Идентификатор канала
-            marker (int, optional): Маркер для пагинации. По умолчанию DEFAULT_MARKER_VALUE
-            count (int, optional): Количество членов для загрузки. По умолчанию DEFAULT_CHAT_MEMBERS_LIMIT.
-
-        Returns:
-            tuple[list[Member], int | None]: Список участников канала и маркер для следующей страницы
+        :param chat_id: Идентификатор канала
+        :type chat_id: int
+        :param marker: Маркер для пагинации. По умолчанию DEFAULT_MARKER_VALUE
+        :type marker: int | None
+        :param count: Количество членов для загрузки. По умолчанию DEFAULT_CHAT_MEMBERS_LIMIT.
+        :type count: int
+        :return: Список участников канала и маркер для следующей страницы
+        :rtype: tuple[list[Member], int | None]
         """
 
         payload = GetGroupMembersPayload(chat_id=chat_id, marker=marker, count=count)
@@ -122,12 +121,12 @@ class ChannelMixin(ClientProtocol):
         Внимание! веб-клиент всегда возвращает только определённое количество пользователей,
         тоесть пагинация здесь не реализована!
 
-        Args:
-            chat_id (int): Идентификатор канала
-            query (str): Строка для поиска участников
-
-        Returns:
-            list[Member]: Список участников канала
+        :param chat_id: Идентификатор канала
+        :type chat_id: int
+        :param query: Строка для поиска участников
+        :type query: str
+        :return: Список участников канала
+        :rtype: tuple[list[Member], int | None]
         """
         payload = SearchGroupMembersPayload(chat_id=chat_id, query=query)
         return await self._query_members(payload)

pymax/mixins/group.py

@@ -10,9 +10,11 @@ from pymax.payloads import (
     CreateGroupAttach,
     CreateGroupMessage,
     CreateGroupPayload,
+    FetchChatsPayload,
     GetChatInfoPayload,
     InviteUsersPayload,
     JoinChatPayload,
+    LeaveChatPayload,
     RemoveUsersPayload,
     ReworkInviteLinkPayload,
 )
@@ -74,7 +76,7 @@ class GroupMixin(ClientProtocol):
         chat_id: int,
         user_ids: list[int],
         show_history: bool = True,
-    ) -> bool:
+    ) -> Chat | None:
         """
         Приглашает пользователей в группу
 
@@ -84,7 +86,7 @@ class GroupMixin(ClientProtocol):
             show_history (bool, optional): Флаг оповещения. Defaults to True.
 
         Returns:
-            bool: True, если пользователи успешно приглашены
+            Chat | None: Объект Chat или None при ошибке.
         """
         payload = InviteUsersPayload(
             chat_id=chat_id,
@@ -109,7 +111,26 @@ class GroupMixin(ClientProtocol):
                 idx = self.chats.index(cached_chat)
                 self.chats[idx] = chat
 
-        return True
+        return chat
+
+    async def invite_users_to_channel(
+        self,
+        chat_id: int,
+        user_ids: list[int],
+        show_history: bool = True,
+    ) -> Chat | None:
+        """
+        Приглашает пользователей в канал
+
+        Args:
+            chat_id (int): ID канала.
+            user_ids (list[int]): Список идентификаторов пользователей.
+            show_history (bool, optional): Флаг оповещения. Defaults to True.
+
+        Returns:
+            Chat | None: Объект Chat или None при ошибке.
+        """
+        return await self.invite_users_to_group(chat_id, user_ids, show_history)
 
     async def remove_users_from_group(
         self,
@@ -117,6 +138,17 @@ class GroupMixin(ClientProtocol):
         user_ids: list[int],
         clean_msg_period: int,
     ) -> bool:
+        """
+        Удаляет пользователей из группы
+
+        Args:
+            chat_id (int): ID группы.
+            user_ids (list[int]): Список идентификаторов пользователей.
+            clean_msg_period (int): Период очистки сообщений.
+
+        Returns:
+            bool: True, если удаление прошло успешно, иначе False.
+        """
         payload = RemoveUsersPayload(
             chat_id=chat_id,
             user_ids=user_ids,
@@ -150,6 +182,19 @@ class GroupMixin(ClientProtocol):
         only_admin_can_call: bool | None = None,
         members_can_see_private_link: bool | None = None,
     ) -> None:
+        """
+        Изменяет настройки группы
+
+        Args:
+            chat_id (int): ID группы.
+            all_can_pin_message (bool | None, optional): Все могут закреплять сообщения. Defaults to None.
+            only_owner_can_change_icon_title (bool | None, optional): Только владелец может менять иконку и название. Defaults to None.
+            only_admin_can_add_member (bool | None, optional): Только администраторы могут добавлять участников. Defaults to None.
+            only_admin_can_call (bool | None, optional): Только администраторы могут звонить. Defaults to None.
+            members_can_see_private_link (bool | None, optional): Участники могут видеть приватную ссылку. Defaults to None.
+        Returns:
+            None
+        """
         payload = ChangeGroupSettingsPayload(
             chat_id=chat_id,
             options=ChangeGroupSettingsOptions(
@@ -181,6 +226,17 @@ class GroupMixin(ClientProtocol):
         name: str | None,
         description: str | None = None,
     ) -> None:
+        """
+        Изменяет профиль группы
+
+        Args:
+            chat_id (int): ID группы.
+            name (str | None): Название группы.
+            description (str | None, optional): Описание группы. Defaults to None.
+
+        Returns:
+            None
+        """
         payload = ChangeGroupProfilePayload(
             chat_id=chat_id,
             theme=name,
@@ -264,11 +320,10 @@ class GroupMixin(ClientProtocol):
         """
         Получает информацию о группах по их ID
 
-        Args:
-            chat_ids (list[int]): Список идентификаторов групп.
-
-        Returns:
-            list[Chat]: Список объектов Chat.
+        :param chat_ids: Список идентификаторов групп.
+        :type chat_ids: list[int]
+        :return: Список объектов Chat.
+        :rtype: list[Chat]
         """
         missed_chat_ids = [
             chat_id for chat_id in chat_ids if await self._get_chat(chat_id) is None
@@ -318,3 +373,67 @@ class GroupMixin(ClientProtocol):
         if not chats:
             raise Error("no_chat", "Chat not found in response", "Chat Error")
         return chats[0]
+
+    async def leave_group(self, chat_id: int) -> None:
+        """
+        Покидает группу
+
+        :param chat_id: Идентификатор группы.
+        :type chat_id: int
+        :return: None
+        :rtype: None
+        """
+        payload = LeaveChatPayload(chat_id=chat_id).model_dump(by_alias=True)
+
+        data = await self._send_and_wait(opcode=Opcode.CHAT_LEAVE, payload=payload)
+
+        if data.get("payload", {}).get("error"):
+            MixinsUtils.handle_error(data)
+
+        cached_chat = await self._get_chat(chat_id)
+        if cached_chat is not None:
+            self.chats.remove(cached_chat)
+
+    async def leave_channel(self, chat_id: int) -> None:
+        """
+        Покидает канал
+
+        :param chat_id: Идентификатор канала.
+        :type chat_id: int
+        :return: None
+        :rtype: None
+        """
+        await self.leave_group(chat_id)
+
+    async def fetch_chats(self, marker: int | None = None) -> list[Chat]:
+        """
+        Загружает список чатов
+
+        :param marker: Маркер для пагинации, по умолчанию None
+        :type marker: int | None
+        :return: Список объектов Chat
+        :rtype: list[Chat]
+        """
+        if marker is None:
+            marker = int(time.time() * 1000)
+
+        payload = FetchChatsPayload(marker=marker).model_dump(by_alias=True)
+
+        data = await self._send_and_wait(opcode=Opcode.CHATS_LIST, payload=payload)
+
+        if data.get("payload", {}).get("error"):
+            MixinsUtils.handle_error(data)
+
+        chats_data = data["payload"].get("chats", [])
+        chats: list[Chat] = []
+        for chat_dict in chats_data:
+            chat = Chat.from_dict(chat_dict)
+            chats.append(chat)
+            cached_chat = await self._get_chat(chat.id)
+            if cached_chat is None:
+                self.chats.append(chat)
+            else:
+                idx = self.chats.index(cached_chat)
+                self.chats[idx] = chat
+
+        return chats