maxapi-python 1.2.5__py3-none-any.whl → 2.0.0__py3-none-any.whl

pymax/infra/user.py

@@ -0,0 +1,107 @@
+from typing import Literal
+
+from pymax.types import Session, User
+
+from .protocol import IClientProtocol
+
+
+class UserMixin(IClientProtocol):
+    def get_cached_user(self, user_id: int) -> User | None:
+        """Возвращает пользователя из локального кеша без сетевого запроса.
+
+        Args:
+            user_id: ID пользователя.
+
+        Returns:
+            Контакт из кеша или ``None``, если клиент еще не знает такого
+            пользователя.
+        """
+        return self._app.api.users.get_cached_user(user_id)
+
+    async def get_users(self, user_ids: list[int]) -> list[User]:
+        """Возвращает пользователей, беря известные контакты из кеша.
+
+        Args:
+            user_ids: ID пользователей в нужном порядке.
+
+        Returns:
+            Найденные контакты в порядке ``user_ids``. Недостающие контакты
+            будут загружены с сервера и сохранены в кеш.
+        """
+        return await self._app.api.users.get_users(user_ids)
+
+    async def get_user(self, user_id: int) -> User | None:
+        """Возвращает пользователя из кеша или загружает его с сервера.
+
+        Args:
+            user_id: ID пользователя.
+
+        Returns:
+            Контакт или ``None``, если пользователь не найден.
+        """
+        return await self._app.api.users.get_user(user_id)
+
+    async def fetch_users(self, user_ids: list[int]) -> list[User]:
+        """Загружает пользователей с сервера и обновляет кеш клиента.
+
+        Args:
+            user_ids: ID пользователей.
+
+        Returns:
+            Контакты, которые вернул сервер.
+        """
+        return await self._app.api.users.fetch_users(user_ids)
+
+    async def search_by_phone(self, phone: str) -> User:
+        """Ищет пользователя Max по номеру телефона.
+
+        Args:
+            phone: Телефон в формате, который принимает Max. Обычно это
+                международный формат с кодом страны.
+
+        Returns:
+            Найденный контакт. Результат сохраняется в кеш клиента.
+        """
+        return await self._app.api.users.search_by_phone(phone)
+
+    async def get_sessions(self) -> list[Session]:
+        """Возвращает активные сессии текущего аккаунта.
+
+        Returns:
+            Список сессий, известных серверу.
+        """
+        return await self._app.api.users.get_sessions()
+
+    async def add_contact(self, contact_id: int) -> User:
+        """Добавляет пользователя в контакты.
+
+        Args:
+            contact_id: ID пользователя.
+
+        Returns:
+            Обновленный контакт. Результат сохраняется в кеш клиента.
+        """
+        return await self._app.api.users.add_contact(contact_id)
+
+    async def remove_contact(self, contact_id: int) -> Literal[True]:
+        """Удаляет пользователя из контактов.
+
+        Args:
+            contact_id: ID пользователя.
+
+        Returns:
+            ``True``, если сервер принял запрос.
+        """
+        return await self._app.api.users.remove_contact(contact_id)
+
+    def get_chat_id(self, first_user_id: int, second_user_id: int) -> int:
+        """Вычисляет ID личного чата для пары пользователей.
+
+        Args:
+            first_user_id: ID первого пользователя.
+            second_user_id: ID второго пользователя.
+
+        Returns:
+            ID личного чата. Метод работает локально, без запроса к серверу.
+        """
+        return self._app.api.users.get_chat_id(first_user_id, second_user_id)

pymax/logging.py

@@ -0,0 +1,129 @@
+import logging
+import re
+import sys
+from typing import TextIO
+
+DATE_FORMAT = "%H:%M:%S"
+
+RESET = "\x1b[0m"
+DIM = "\x1b[2m"
+BOLD = "\x1b[1m"
+
+LEVEL_STYLES = {
+    logging.DEBUG: ("\x1b[90m", "DEBUG"),
+    logging.INFO: ("\x1b[36m", "INFO"),
+    logging.WARNING: ("\x1b[33m", "WARN"),
+    logging.ERROR: ("\x1b[31m", "ERROR"),
+    logging.CRITICAL: ("\x1b[1;37;41m", "CRIT"),
+}
+
+LEVELS = {
+    "CRITICAL": logging.CRITICAL,
+    "FATAL": logging.FATAL,
+    "ERROR": logging.ERROR,
+    "WARNING": logging.WARNING,
+    "WARN": logging.WARNING,
+    "INFO": logging.INFO,
+    "DEBUG": logging.DEBUG,
+    "NOTSET": logging.NOTSET,
+}
+
+
+class PrettyFormatter(logging.Formatter):
+    def __init__(self, *, use_colors: bool = True) -> None:
+        super().__init__()
+        self.use_colors = use_colors
+
+    def format(self, record: logging.LogRecord) -> str:
+        color, level = LEVEL_STYLES.get(record.levelno, ("", "???"))
+
+        time = self.formatTime(record, DATE_FORMAT)
+        message = record.getMessage()
+
+        line = f"{DIM}{time}{RESET} {color}{BOLD}{level}{RESET} {message}"
+
+        if record.exc_info:
+            line += "\n" + self.formatException(record.exc_info)
+
+        if not self.use_colors:
+            line = _strip_ansi(line)
+
+        return line
+
+
+def configure_logging(
+    level: int | str = logging.INFO,
+    *,
+    stream: TextIO | None = None,
+    use_colors: bool | None = None,
+) -> None:
+    """Настраивает pretty-логи для logger-а ``pymax``.
+
+    Обычно уровень логов задают через ``ExtraConfig(log_level="DEBUG")``.
+    Вызывайте эту функцию вручную, если хотите управлять stream или цветами.
+
+    Args:
+        level: Уровень логирования: строка вроде ``"DEBUG"`` или число из
+            модуля ``logging``.
+        stream: Поток для вывода. По умолчанию ``sys.stderr``.
+        use_colors: Включить ANSI-цвета. Если ``None``, определяется по TTY.
+
+    Returns:
+        ``None``.
+
+    Example:
+        .. code-block:: python
+
+           from pymax import configure_logging
+
+           configure_logging("DEBUG", use_colors=False)
+    """
+    stream = stream or sys.stderr
+
+    if use_colors is None:
+        use_colors = hasattr(stream, "isatty") and stream.isatty()
+
+    logger = logging.getLogger("pymax")
+    logger.handlers.clear()
+    logger.setLevel(_normalize_level(level))
+    logger.propagate = False
+
+    handler = logging.StreamHandler(stream)
+    handler.setLevel(_normalize_level(level))
+    handler.setFormatter(
+        PrettyFormatter(
+            use_colors=use_colors,
+        )
+    )
+
+    logger.addHandler(handler)
+
+
+def get_logger(name: str | None = None) -> logging.Logger:
+    if not name:
+        return logging.getLogger("pymax")
+
+    if name.startswith("pymax"):
+        return logging.getLogger(name)
+
+    return logging.getLogger(f"pymax.{name}")
+
+
+def _normalize_level(level: int | str) -> int:
+    if isinstance(level, int):
+        return level
+
+    value = LEVELS.get(level.upper())
+
+    if isinstance(value, int):
+        return value
+
+    raise ValueError(f"Unknown log level: {level}")
+
+
+def _strip_ansi(text: str) -> str:
+
+    return re.sub(r"\x1b\[[0-9;]*m", "", text)
+
+
+logging.getLogger("pymax").addHandler(logging.NullHandler())

pymax/protocol/__init__.py

@@ -0,0 +1,11 @@
+from .enums import Command, Opcode
+from .models import InboundFrame, OutboundFrame, PackedPacket, TcpPacketHeader
+
+__all__ = (
+    "Command",
+    "InboundFrame",
+    "Opcode",
+    "OutboundFrame",
+    "PackedPacket",
+    "TcpPacketHeader",
+)

pymax/protocol/base.py

@@ -0,0 +1,13 @@
+from abc import ABC, abstractmethod
+
+from .models import InboundFrame, OutboundFrame
+
+
+class BaseProtocol(ABC):
+    version: int
+
+    @abstractmethod
+    def encode(self, frame: OutboundFrame) -> bytes | str: ...
+
+    @abstractmethod
+    def decode(self, raw: bytes | str) -> InboundFrame: ...

pymax/protocol/enums.py

@@ -0,0 +1,180 @@
+from enum import Enum
+
+
+class Command(int, Enum):
+    """Низкоуровневый тип frame-а в протоколе Max."""
+
+    REQUEST = 0
+    RESPONSE = 1
+    EVENT = 2
+    ERROR = 3
+
+
+class Opcode(int, Enum):
+    """Низкоуровневые opcode-ы внутреннего протокола Max."""
+
+    PING = 1
+    DEBUG = 2
+    RECONNECT = 3
+    LOG = 5
+    SESSION_INIT = 6
+    PROFILE = 16
+    AUTH_REQUEST = 17
+    AUTH = 18
+    LOGIN = 19
+    LOGOUT = 20
+    SYNC = 21
+    CONFIG = 22
+    AUTH_CONFIRM = 23
+    PRESET_AVATARS = 25
+    ASSETS_GET = 26
+    ASSETS_UPDATE = 27
+    ASSETS_GET_BY_IDS = 28
+    ASSETS_ADD = 29
+    SEARCH_FEEDBACK = 31
+    CONTACT_INFO = 32
+    CONTACT_ADD = 33
+    CONTACT_UPDATE = 34
+    CONTACT_PRESENCE = 35
+    CONTACT_LIST = 36
+    CONTACT_SEARCH = 37
+    CONTACT_MUTUAL = 38
+    CONTACT_PHOTOS = 39
+    CONTACT_SORT = 40
+    CONTACT_VERIFY = 42
+    REMOVE_CONTACT_PHOTO = 43
+    CONTACT_INFO_BY_PHONE = 46
+    CHAT_INFO = 48
+    CHAT_HISTORY = 49
+    CHAT_MARK = 50
+    CHAT_MEDIA = 51
+    CHAT_DELETE = 52
+    CHATS_LIST = 53
+    CHAT_CLEAR = 54
+    CHAT_UPDATE = 55
+    CHAT_CHECK_LINK = 56
+    CHAT_JOIN = 57
+    CHAT_LEAVE = 58
+    CHAT_MEMBERS = 59
+    PUBLIC_SEARCH = 60
+    CHAT_PERSONAL_CONFIG = 61
+    CHAT_LIVESTREAM_INFO = 62
+    CHAT_CREATE = 63
+    MSG_SEND = 64
+    MSG_TYPING = 65
+    MSG_DELETE = 66
+    MSG_EDIT = 67
+    CHAT_SEARCH = 68
+    MSG_SHARE_PREVIEW = 70
+    MSG_GET = 71
+    MSG_SEARCH_TOUCH = 72
+    MSG_SEARCH = 73
+    MSG_GET_STAT = 74
+    CHAT_SUBSCRIBE = 75
+    VIDEO_CHAT_START = 76
+    CHAT_MEMBERS_UPDATE = 77
+    VIDEO_CHAT_START_ACTIVE = 78
+    VIDEO_CHAT_HISTORY = 79
+    PHOTO_UPLOAD = 80
+    STICKER_UPLOAD = 81
+    VIDEO_UPLOAD = 82
+    VIDEO_PLAY = 83
+    VIDEO_CHAT_CREATE_JOIN_LINK = 84
+    CHAT_PIN_SET_VISIBILITY = 86
+    FILE_UPLOAD = 87
+    FILE_DOWNLOAD = 88
+    LINK_INFO = 89
+    MSG_DELETE_RANGE = 92
+    SESSIONS_INFO = 96
+    SESSIONS_CLOSE = 97
+    PHONE_BIND_REQUEST = 98
+    PHONE_BIND_CONFIRM = 99
+    AUTH_LOGIN_RESTORE_PASSWORD = 101
+    GET_INBOUND_CALLS = 103
+    AUTH_2FA_DETAILS = 104
+    EXTERNAL_CALLBACK = 105
+    AUTH_VALIDATE_PASSWORD = 107
+    AUTH_VALIDATE_HINT = 108
+    AUTH_VERIFY_EMAIL = 109
+    AUTH_CHECK_EMAIL = 110
+    AUTH_SET_2FA = 111
+    AUTH_CREATE_TRACK = 112
+    AUTH_CHECK_PASSWORD = 113
+    AUTH_LOGIN_CHECK_PASSWORD = 115
+    AUTH_LOGIN_PROFILE_DELETE = 116
+    CHAT_COMPLAIN = 117
+    MSG_SEND_CALLBACK = 118
+    SUSPEND_BOT = 119
+    LOCATION_STOP = 124
+    LOCATION_SEND = 125
+    LOCATION_REQUEST = 126
+    GET_LAST_MENTIONS = 127
+    NOTIF_MESSAGE = 128
+    NOTIF_TYPING = 129
+    NOTIF_MARK = 130
+    NOTIF_CONTACT = 131
+    NOTIF_PRESENCE = 132
+    NOTIF_CONFIG = 134
+    NOTIF_CHAT = 135
+    NOTIF_ATTACH = 136
+    NOTIF_CALL_START = 137
+    NOTIF_CONTACT_SORT = 139
+    NOTIF_MSG_DELETE_RANGE = 140
+    NOTIF_MSG_DELETE = 142
+    NOTIF_CALLBACK_ANSWER = 143
+    CHAT_BOT_COMMANDS = 144
+    BOT_INFO = 145
+    NOTIF_LOCATION = 147
+    NOTIF_LOCATION_REQUEST = 148
+    NOTIF_ASSETS_UPDATE = 150
+    NOTIF_DRAFT = 152
+    NOTIF_DRAFT_DISCARD = 153
+    NOTIF_MSG_DELAYED = 154
+    NOTIF_MSG_REACTIONS_CHANGED = 155
+    NOTIF_MSG_YOU_REACTED = 156
+    CALLS_TOKEN = 158
+    NOTIF_PROFILE = 159
+    WEB_APP_INIT_DATA = 160
+    COMPLAIN = 161
+    COMPLAIN_REASONS_GET = 162
+    VIDEO_CHAT_JOIN = 166
+    DRAFT_SAVE = 176
+    DRAFT_DISCARD = 177
+    MSG_REACTION = 178
+    MSG_CANCEL_REACTION = 179
+    MSG_GET_REACTIONS = 180
+    MSG_GET_DETAILED_REACTIONS = 181
+    STICKER_CREATE = 193
+    STICKER_SUGGEST = 194
+    VIDEO_CHAT_MEMBERS = 195
+    CHAT_HIDE = 196
+    CHAT_SEARCH_COMMON_PARTICIPANTS = 198
+    PROFILE_DELETE = 199
+    PROFILE_DELETE_TIME = 200
+    TRANSCRIBE_MEDIA = 202
+    ORG_INFO = 256
+    CHAT_REACTIONS_SETTINGS_SET = 257
+    REACTIONS_SETTINGS_GET_BY_CHAT_ID = 258
+    ASSETS_REMOVE = 259
+    ASSETS_MOVE = 260
+    ASSETS_LIST_MODIFY = 261
+    FOLDERS_GET = 272
+    FOLDERS_GET_BY_ID = 273
+    FOLDERS_UPDATE = 274
+    FOLDERS_REORDER = 275
+    FOLDERS_DELETE = 276
+    NOTIF_FOLDERS = 277
+
+    GET_QR = 288
+    GET_QR_STATUS = 289
+    AUTH_QR_APPROVE = 290
+    LOGIN_BY_QR = 291
+    NOTIF_BANNERS = 292
+    NOTIF_TRANSCRIPTION = 293
+    CHAT_SUGGEST = 300
+    AUDIO_PLAY = 301
+    BANNERS_GET = 302
+    MSG_DELIVERY = 303
+    SEND_VOTE = 304
+    VOTERS_LIST_BY_ANSWER = 305
+    GET_POLL_UPDATES = 306

pymax/protocol/models.py

@@ -0,0 +1,33 @@
+from typing import Any
+
+from pydantic import BaseModel
+
+
+class OutboundFrame(BaseModel):
+    ver: int
+    opcode: int
+    cmd: int = 0
+    seq: int
+    payload: dict[Any, Any] | None = None
+
+
+class InboundFrame(BaseModel):
+    opcode: int
+    cmd: int = 0
+    seq: int | None = None
+    payload: dict[Any, Any] | None = None
+    raw: dict[Any, Any] | None = None
+
+
+class TcpPacketHeader(BaseModel):
+    ver: int
+    cmd: int
+    seq: int
+    opcode: int
+    flags: int = 0
+    payload_len: int = 0
+
+
+class PackedPacket(BaseModel):
+    header: TcpPacketHeader
+    payload_bytes: bytes

pymax/protocol/tcp/__init__.py

@@ -0,0 +1 @@
+from .protocol import TcpProtocol

pymax/protocol/tcp/compression.py

@@ -0,0 +1,97 @@
+class Lz4BlockCompression:
+    def decompress(self, src: bytes, max_output: int = 5 * 1024 * 1024) -> bytes:
+        dst = bytearray()
+        pos = 0
+
+        while pos < len(src):
+            token = src[pos]
+            pos += 1
+
+            lit_len = token >> 4
+            if lit_len == 15:
+                while pos < len(src):
+                    b = src[pos]
+                    pos += 1
+                    lit_len += b
+                    if b != 255:
+                        break
+
+            if lit_len > 0:
+                if pos + lit_len > len(src):
+                    raise ValueError("LZ4: literal length out of bounds")
+                dst.extend(src[pos : pos + lit_len])
+                pos += lit_len
+                if len(dst) > max_output:
+                    raise ValueError("LZ4: output too large")
+
+            if pos >= len(src):
+                break
+
+            if pos + 1 >= len(src):
+                raise ValueError("LZ4: incomplete offset")
+
+            offset = src[pos] | (src[pos + 1] << 8)
+            pos += 2
+
+            if offset == 0:
+                raise ValueError("LZ4: zero offset")
+
+            match_len = (token & 0x0F) + 4
+            if (token & 0x0F) == 0x0F:
+                while pos < len(src):
+                    b = src[pos]
+                    pos += 1
+                    match_len += b
+                    if b != 255:
+                        break
+
+            match_pos = len(dst) - offset
+            if match_pos < 0:
+                raise ValueError("LZ4: match out of bounds")
+
+            for i in range(match_len):
+                dst.append(dst[match_pos + (i % offset)])
+
+            if len(dst) > max_output:
+                raise ValueError("LZ4: output too large")
+
+        return bytes(dst)
+
+    def compress(self, src: bytes) -> bytes:
+        dst = bytearray()
+        pos = 0
+
+        while pos < len(src):
+            lit_start = pos
+            while pos < len(src) and (pos - lit_start) < 15:
+                pos += 1
+
+            lit_len = pos - lit_start
+            token = (lit_len << 4) & 0xF0
+
+            match_offset = 0
+            match_len = 0
+
+            for i in range(max(0, lit_start - 65535), lit_start):
+                j = i
+                k = lit_start
+                while j < i + 65535 and k < len(src) and src[j] == src[k]:
+                    j += 1
+                    k += 1
+                if j - i > match_len:
+                    match_offset = lit_start - i
+                    match_len = j - i
+
+            if match_len >= 4:
+                token |= (match_len - 4) & 0x0F
+                dst.append(token)
+                dst.extend(src[lit_start : lit_start + lit_len])
+                dst.append(match_offset & 0xFF)
+                dst.append((match_offset >> 8) & 0xFF)
+                pos += match_len
+            else:
+                token |= lit_len & 0x0F
+                dst.append(token)
+                dst.extend(src[lit_start : lit_start + lit_len])
+
+        return bytes(dst)

pymax/protocol/tcp/framing.py

@@ -0,0 +1,68 @@
+import struct
+
+from pymax.protocol import PackedPacket, TcpPacketHeader
+
+
+class TcpPacketFramer:
+    HEADER_STRUCT = struct.Struct(">BHBHI")
+    HEADER_SIZE = HEADER_STRUCT.size
+
+    def _pack_cmd(self, cmd: int) -> int:
+        return (cmd & 0xFF) << 8
+
+    def _unpack_cmd(self, packed_cmd: int) -> int:
+        return (packed_cmd >> 8) & 0xFF
+
+    def pack(
+        self,
+        *,
+        ver: int,
+        cmd: int,
+        seq: int,
+        opcode: int,
+        flags: int,
+        payload_bytes: bytes,
+    ) -> bytes:
+        packed_len = ((flags & 0xFF) << 24) | (len(payload_bytes) & 0x00FFFFFF)
+        header = self.HEADER_STRUCT.pack(
+            ver,
+            self._pack_cmd(cmd),
+            seq,
+            opcode,
+            packed_len,
+        )
+        return header + payload_bytes
+
+    def unpack(self, data: bytes) -> PackedPacket | None:
+        if len(data) < self.HEADER_SIZE:
+            return None
+
+        ver, cmd, seq, opcode, packed_len = self.HEADER_STRUCT.unpack_from(data, 0)
+        flags = (packed_len >> 24) & 0xFF
+        payload_len = packed_len & 0x00FFFFFF
+
+        total_len = self.HEADER_SIZE + payload_len
+        if len(data) < total_len:
+            return None
+
+        return PackedPacket(
+            header=TcpPacketHeader(
+                ver=ver,
+                cmd=self._unpack_cmd(cmd),
+                seq=seq,
+                opcode=opcode,
+                flags=flags,
+                payload_len=payload_len,
+            ),
+            payload_bytes=data[self.HEADER_SIZE : total_len],
+        )
+
+    def unpack_header(self, data: bytes) -> int | None:
+        if len(data) < self.HEADER_SIZE:
+            return None
+
+        _, _, _, _, packed_len = self.HEADER_STRUCT.unpack_from(data, 0)
+        flags = (packed_len >> 24) & 0xFF
+        payload_len = packed_len & 0x00FFFFFF
+
+        return payload_len