maxapi-python 1.2.4__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/{static/enum.py → protocol/enums.py}

@@ -1,7 +1,18 @@
 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
@@ -46,7 +57,8 @@ class Opcode(int, Enum):
     CHAT_LEAVE = 58
     CHAT_MEMBERS = 59
     PUBLIC_SEARCH = 60
-    CHAT_CLOSE = 61
+    CHAT_PERSONAL_CONFIG = 61
+    CHAT_LIVESTREAM_INFO = 62
     CHAT_CREATE = 63
     MSG_SEND = 64
     MSG_TYPING = 65
@@ -61,11 +73,13 @@ class Opcode(int, Enum):
     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
@@ -75,8 +89,9 @@ class Opcode(int, Enum):
     SESSIONS_CLOSE = 97
     PHONE_BIND_REQUEST = 98
     PHONE_BIND_CONFIRM = 99
-    CONFIRM_PRESENT = 101
+    AUTH_LOGIN_RESTORE_PASSWORD = 101
     GET_INBOUND_CALLS = 103
+    AUTH_2FA_DETAILS = 104
     EXTERNAL_CALLBACK = 105
     AUTH_VALIDATE_PASSWORD = 107
     AUTH_VALIDATE_HINT = 108
@@ -84,7 +99,9 @@ class Opcode(int, Enum):
     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
@@ -118,6 +135,9 @@ class Opcode(int, Enum):
     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
@@ -131,6 +151,10 @@ class Opcode(int, Enum):
     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
@@ -143,81 +167,14 @@ class Opcode(int, Enum):
 
     GET_QR = 288
     GET_QR_STATUS = 289
+    AUTH_QR_APPROVE = 290
     LOGIN_BY_QR = 291
-
-
-class ChatType(str, Enum):
-    DIALOG = "DIALOG"
-    CHAT = "CHAT"
-    CHANNEL = "CHANNEL"
-
-
-class MessageType(str, Enum):
-    TEXT = "TEXT"
-    SYSTEM = "SYSTEM"
-    SERVICE = "SERVICE"
-
-
-class MessageStatus(str, Enum):
-    EDITED = "EDITED"
-    REMOVED = "REMOVED"
-
-
-class ElementType(str, Enum):
-    TEXT = "text"
-    MENTION = "mention"
-    LINK = "link"
-    EMOJI = "emoji"
-
-
-class AuthType(str, Enum):
-    START_AUTH = "START_AUTH"
-    CHECK_CODE = "CHECK_CODE"
-    REGISTER = "REGISTER"
-    RESEND = "RESEND"
-
-
-class AccessType(str, Enum):
-    PUBLIC = "PUBLIC"
-    PRIVATE = "PRIVATE"
-    SECRET = "SECRET"  # nosec B105
-
-
-class DeviceType(str, Enum):
-    WEB = "WEB"
-    ANDROID = "ANDROID"
-    IOS = "IOS"
-
-
-class AttachType(str, Enum):
-    PHOTO = "PHOTO"
-    VIDEO = "VIDEO"
-    FILE = "FILE"
-    STICKER = "STICKER"
-    AUDIO = "AUDIO"
-    CONTROL = "CONTROL"
-    CONTACT = "CONTACT"
-
-
-class FormattingType(str, Enum):
-    STRONG = "STRONG"
-    EMPHASIZED = "EMPHASIZED"
-    UNDERLINE = "UNDERLINE"
-    STRIKETHROUGH = "STRIKETHROUGH"
-
-
-class MarkupType(str, Enum):
-    BOLD = "**"
-    ITALIC = "*"
-    UNDERLINE = "__"
-    STRIKETHROUGH = "~~"
-
-
-class ContactAction(str, Enum):
-    ADD = "ADD"
-    REMOVE = "REMOVE"
-
-
-class ReadAction(str, Enum):
-    READ_MESSAGE = "READ_MESSAGE"
-    READ_REACTION = "READ_REACTION"
+    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