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

pymax/api/users/enums.py

@@ -0,0 +1,12 @@
+from enum import Enum
+
+
+class ContactAction(str, Enum):
+    ADD = "ADD"
+    REMOVE = "REMOVE"
+
+
+class UserPayloadKey(str, Enum):
+    CONTACT = "contact"
+    CONTACTS = "contacts"
+    SESSIONS = "sessions"

pymax/api/users/payloads.py

@@ -0,0 +1,16 @@
+from pymax.api.models import CamelModel
+
+from .enums import ContactAction
+
+
+class FetchContactsPayload(CamelModel):
+    contact_ids: list[int]
+
+
+class SearchByPhonePayload(CamelModel):
+    phone: str
+
+
+class ContactActionPayload(CamelModel):
+    contact_id: int
+    action: ContactAction

pymax/api/users/service.py

@@ -0,0 +1,124 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Literal
+
+from pymax.api.response import (
+    parse_payload_list,
+    require_payload_dict,
+    require_payload_item_model,
+)
+from pymax.logging import get_logger
+from pymax.protocol import InboundFrame, Opcode
+from pymax.types.domain import Session, User
+
+from .enums import ContactAction, UserPayloadKey
+from .payloads import (
+    ContactActionPayload,
+    FetchContactsPayload,
+    SearchByPhonePayload,
+)
+
+if TYPE_CHECKING:
+    from pymax.app import App
+
+
+logger = get_logger(__name__)
+
+
+class UserService:
+    def __init__(self, app: App) -> None:
+        self.app = app
+
+    def _cache_user(self, user: User) -> User:
+        self.app.users[user.id] = user
+        return user
+
+    def get_cached_user(self, user_id: int) -> User | None:
+        user = self.app.users.get(user_id)
+        logger.debug("get_cached_user id=%s hit=%s", user_id, bool(user))
+        return user
+
+    async def get_users(self, user_ids: list[int]) -> list[User]:
+        cached = {
+            user_id: user
+            for user_id in user_ids
+            if (user := self.get_cached_user(user_id)) is not None
+        }
+        missing_ids = [user_id for user_id in user_ids if user_id not in cached]
+
+        if missing_ids:
+            for user in await self.fetch_users(missing_ids):
+                cached[user.id] = user
+
+        return [cached[user_id] for user_id in user_ids if user_id in cached]
+
+    async def get_user(self, user_id: int) -> User | None:
+        if user := self.get_cached_user(user_id):
+            return user
+
+        users = await self.fetch_users([user_id])
+        return users[0] if users else None
+
+    async def fetch_users(self, user_ids: list[int]) -> list[User]:
+        logger.info("fetching users count=%s", len(user_ids))
+        frame = FetchContactsPayload(contact_ids=user_ids)
+        response = await self.app.invoke(Opcode.CONTACT_INFO, frame.to_payload())
+
+        users = [
+            self._cache_user(user)
+            for user in parse_payload_list(response, UserPayloadKey.CONTACTS, User)
+        ]
+        logger.debug("fetched users count=%s", len(users))
+        return users
+
+    async def search_by_phone(self, phone: str) -> User:
+        logger.info("searching user by phone phone_set=%s", bool(phone))
+        frame = SearchByPhonePayload(phone=phone)
+        response = await self.app.invoke(
+            Opcode.CONTACT_INFO_BY_PHONE,
+            frame.to_payload(),
+        )
+
+        contact = require_payload_item_model(
+            response,
+            UserPayloadKey.CONTACT,
+            User,
+        )
+        return self._cache_user(contact)
+
+    async def get_sessions(self) -> list[Session]:
+        logger.info("fetching sessions")
+        response = await self.app.invoke(Opcode.SESSIONS_INFO, {})
+        return parse_payload_list(response, UserPayloadKey.SESSIONS, Session)
+
+    async def _contact_action(self, payload: ContactActionPayload) -> InboundFrame:
+        response = await self.app.invoke(Opcode.CONTACT_UPDATE, payload.to_payload())
+        require_payload_dict(response)
+        return response
+
+    async def add_contact(self, contact_id: int) -> User:
+        response = await self._contact_action(
+            ContactActionPayload(
+                contact_id=contact_id,
+                action=ContactAction.ADD,
+            )
+        )
+        contact = require_payload_item_model(
+            response,
+            UserPayloadKey.CONTACT,
+            User,
+        )
+        return self._cache_user(contact)
+
+    async def remove_contact(self, contact_id: int) -> Literal[True]:
+        await self._contact_action(
+            ContactActionPayload(
+                contact_id=contact_id,
+                action=ContactAction.REMOVE,
+            )
+        )
+        self.app.users.pop(contact_id, None)
+        return True
+
+    def get_chat_id(self, first_user_id: int, second_user_id: int) -> int:
+        return first_user_id ^ second_user_id

pymax/app.py

@@ -0,0 +1,273 @@
+import asyncio
+from typing import Any, Generic, TypeVar
+
+from pymax.api import ApiFacade
+from pymax.auth import AuthFlow
+from pymax.config import ClientConfig
+from pymax.connection import ConnectionManager
+from pymax.dispatch import Dispatcher
+from pymax.dispatch.router import Router
+from pymax.exceptions import ApiError
+from pymax.logging import get_logger
+from pymax.protocol import Command, InboundFrame, OutboundFrame
+from pymax.protocol.enums import Opcode
+from pymax.session import SessionStore
+from pymax.session.models import SessionInfo
+from pymax.telemetry import TelemetryService
+from pymax.types import MaxApiError, Message
+from pymax.types.domain import Chat, Profile, User
+
+logger = get_logger(__name__)
+ClientT = TypeVar("ClientT")
+
+
+class App(Generic[ClientT]):
+    def __init__(
+        self,
+        connection: ConnectionManager,
+        config: ClientConfig,
+        auth_flow: AuthFlow,
+        root_router: Router[ClientT] | None = None,
+    ) -> None:
+        self.connection = connection
+        self.dispatcher: Dispatcher[ClientT] = Dispatcher(self, root_router)
+        self.api = ApiFacade(self)
+        self.config = config
+        self.store = self.config.store or SessionStore(config.work_dir, config.session_name)
+        self.auth_flow = auth_flow
+
+        self.me: Profile | None = None
+        self.chats: list[Chat] | None = None
+        self.users: dict[int, User] = {}
+        self.contacts: list[User | None] = []
+        self.messages: dict[int, list[Message]] = {}
+
+        self.session: SessionInfo | None = None
+
+        self.started = False
+        self._ping_task: asyncio.Task[None] | None = None
+        self._telemetry = TelemetryService(self) if config.telemetry else None
+
+        self.connection.on_event = self.on_event
+        logger.debug(
+            "app initialized session=%s work_dir=%s auth_flow=%s",
+            config.session_name,
+            config.work_dir,
+            type(self.auth_flow).__name__,
+        )
+
+    async def start(self) -> None:
+        if self.started:
+            logger.warning("start skipped: app already started")
+            return
+
+        logger.info("starting pymax client")
+        session_data = await self.store.load_session()
+        if session_data:
+            if session_data.mt_instance_id:
+                self.config.device.mt_instance_id = session_data.mt_instance_id
+            else:
+                session_data.mt_instance_id = self.config.device.mt_instance_id
+
+        try:
+            logger.debug("opening connection")
+            await self.connection.open()
+
+            handshake_device_id = (
+                session_data.device_id if session_data else self.config.device.device_id
+            )
+            logger.debug("running handshake")
+            await self.handshake(handshake_device_id)
+        except (ConnectionError, EOFError, OSError, TimeoutError) as e:
+            logger.exception("failed to connect or handshake")
+            await self.connection.close()
+            raise ConnectionError(f"Failed to connect and handshake: {e}") from e
+
+        self._ping_task = asyncio.create_task(self._ping_loop())
+
+        if not session_data:
+            logger.info("saved session not found; authentication required")
+
+            if self.config.token:
+                await self.store.save_session(
+                    session_data := SessionInfo(
+                        token=self.config.token,
+                        device_id=self.config.device.device_id,
+                        phone=self.config.phone or "",
+                        mt_instance_id=self.config.device.mt_instance_id,
+                    )
+                )
+            else:
+                auth_result = await self.auth_flow.authenticate(self)
+
+                if not auth_result.token:
+                    logger.error("authentication finished without token")
+                    raise RuntimeError("Authentication failed: no token received")
+
+                await self.store.save_session(
+                    session_data := SessionInfo(
+                        token=auth_result.token,
+                        device_id=self.config.device.device_id,
+                        phone=self.config.phone or "",
+                        mt_instance_id=self.config.device.mt_instance_id,
+                    )
+                )
+                logger.info("new session saved")
+        else:
+            logger.debug(
+                "loaded saved session device_id=%s phone_set=%s",
+                session_data.device_id,
+                bool(session_data.phone),
+            )
+
+        self.session = session_data
+
+        logger.debug("logging in")
+        response = await self.api.auth.login(
+            self.config.device.user_agent,
+        )
+
+        self.me = response.profile
+        self.chats = response.chats
+        self.users[self.me.contact.id] = self.me.contact
+        self.contacts = response.contacts
+        self.messages = response.messages
+
+        self.started = True
+        logger.info(
+            "client started profile=%s chats=%s",
+            self.me.contact.id,
+            len(self.chats or []),
+        )
+
+        if self._telemetry:
+            self._telemetry.start()
+
+    async def handshake(self, device_id: str) -> None:
+        await self.api.session.handshake(
+            self.config.device.mt_instance_id,
+            self.config.device.user_agent,
+            device_id,
+        )
+        logger.debug("handshake completed device_id=%s", device_id)
+
+    async def close(self) -> None:
+        if self._telemetry:
+            await self._telemetry.stop()
+
+        if self._ping_task:
+            task = self._ping_task
+            self._ping_task = None
+            if not task.done():
+                task.cancel()
+            try:
+                await task
+            except asyncio.CancelledError:
+                pass
+            except Exception:
+                logger.debug("ping task stopped with error", exc_info=True)
+
+        await self.dispatcher.stop_startup_tasks()
+        await self.connection.close()
+        await self.store.close()
+        self.started = False
+
+    async def invoke(
+        self,
+        opcode: int,
+        payload: dict[str, Any],
+        cmd: int = Command.REQUEST,
+        timeout: float | None = 30.0,
+        compress: bool = False,
+    ) -> InboundFrame:
+        seq = self.connection.next_seq()
+        payload_keys = sorted(payload.keys()) if payload else []
+        frame = OutboundFrame(
+            ver=self.connection.protocol.version,
+            opcode=opcode,
+            cmd=cmd,
+            seq=seq,
+            payload=payload,
+        )
+        logger.debug(
+            "request opcode=%s cmd=%s seq=%s timeout=%s compress=%s payload_keys=%s",
+            opcode,
+            cmd,
+            seq,
+            timeout,
+            compress,
+            payload_keys,
+        )
+        logger.debug("Request data=%s", frame.model_dump())
+        response = await self.connection.request(frame, timeout=timeout)
+        response_keys = sorted(response.payload.keys()) if response.payload else []
+        logger.debug(
+            "response opcode=%s cmd=%s seq=%s payload_keys=%s",
+            response.opcode,
+            response.cmd,
+            response.seq,
+            response_keys,
+        )
+        if response.cmd == Command.ERROR:
+            raise self._build_api_error(response)
+        return response
+
+    async def _ping_loop(self) -> None:
+        try:
+            while True:
+                await self.invoke(
+                    opcode=Opcode.PING,
+                    payload={"interactive": True},
+                    timeout=self.config.request_timeout,
+                )
+                await asyncio.sleep(30)
+        except asyncio.CancelledError:
+            raise
+        except Exception as e:
+            logger.exception("ping loop failed; closing transport")
+            await self.connection.fail(ConnectionError(f"Ping failed: {e}"))
+
+    def _build_api_error(self, response: InboundFrame) -> ApiError:
+        try:
+            error = MaxApiError.model_validate(response.payload)
+        except Exception as e:
+            logger.exception("failed to validate API error")
+            error = MaxApiError(
+                error="unknown_error",
+                title="Unknown error",
+                message=str(e),
+                localized_message=str(e),
+            )
+
+        exc = ApiError(
+            opcode=response.opcode,
+            error=error.error,
+            title=error.title,
+            message=error.message,
+            localized_message=error.localized_message,
+            payload=response.payload,
+        )
+        logger.error(
+            "api error opcode=%s seq=%s error=%s title=%s message=%s localized_message=%s",
+            response.opcode,
+            response.seq,
+            error.error,
+            error.title,
+            error.message,
+            error.localized_message,
+        )
+        return exc
+
+    async def on_event(self, frame: InboundFrame) -> None:
+        logger.debug(
+            "event received opcode=%s cmd=%s seq=%s",
+            frame.opcode,
+            frame.cmd,
+            frame.seq,
+        )
+        logger.debug("Event data=%s", frame.payload)
+        try:
+            await self.dispatcher.dispatch(frame)
+        except Exception as e:
+            logger.exception("failed to dispatch inbound frame")
+            raise RuntimeError(f"Failed to dispatch inbound frame: {e}") from e

pymax/auth/__init__.py

@@ -0,0 +1,25 @@
+from .base import AuthFlow
+from .providers import (
+    ConsolePasswordProvider,
+    ConsoleQrHandler,
+    ConsoleSmsCodeProvider,
+    EmailCodeProvider,
+    PasswordProvider,
+    QrHandler,
+    SmsCodeProvider,
+)
+from .qr import QrAuthFlow
+from .sms import SmsAuthFlow
+
+__all__ = (
+    "AuthFlow",
+    "ConsolePasswordProvider",
+    "ConsoleQrHandler",
+    "ConsoleSmsCodeProvider",
+    "EmailCodeProvider",
+    "PasswordProvider",
+    "QrAuthFlow",
+    "QrHandler",
+    "SmsAuthFlow",
+    "SmsCodeProvider",
+)

pymax/auth/base.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Protocol
+
+from .models import AuthResult
+
+if TYPE_CHECKING:
+    from pymax.app import App
+
+
+class AuthFlow(Protocol):
+    """Протокол полного пользовательского сценария авторизации.
+
+    Используйте полный ``AuthFlow`` только для нестандартной авторизации. Для
+    обычных случаев проще заменить ``SmsCodeProvider``, ``PasswordProvider`` или
+    ``QrHandler``.
+
+    Example:
+        .. code-block:: python
+
+           from pymax import Client
+           from pymax.app import App
+           from pymax.auth.models import AuthResult
+
+           class StaticTokenFlow:
+               async def authenticate(self, app: App) -> AuthResult:
+                   return AuthResult(token="TOKEN")
+
+           client = Client(
+               phone="+79990000000",
+               auth_flow=StaticTokenFlow(),
+           )
+    """
+
+    async def authenticate(self, app: App) -> AuthResult:
+        """Возвращает результат авторизации для новой локальной сессии."""
+        ...

pymax/auth/models.py

@@ -0,0 +1,5 @@
+from pydantic import BaseModel
+
+
+class AuthResult(BaseModel):
+    token: str | None = None

pymax/auth/providers.py

@@ -0,0 +1,127 @@
+import asyncio
+import getpass
+from typing import Protocol
+
+import qrcode
+
+
+class SmsCodeProvider(Protocol):
+    """Протокол получения SMS-кода.
+
+    Реализуйте его, если код приходит не из консоли: из UI, очереди, callback
+    или внешнего сервиса.
+    """
+
+    async def get_code(self, phone: str) -> str:
+        """Возвращает SMS-код для указанного телефона."""
+        ...
+
+
+class ConsoleSmsCodeProvider:
+    """Консольный provider SMS-кода.
+
+    При авторизации печатает prompt и читает код через ``input``.
+    """
+
+    async def get_code(self, phone: str) -> str:
+        """Запрашивает SMS-код в консоли.
+
+        Args:
+            phone: Телефон, для которого запрошен код.
+
+        Returns:
+            Введенный пользователем код.
+        """
+        prompt = f"Enter SMS code for {phone}: "
+        return (await asyncio.to_thread(input, prompt)).strip()
+
+
+class PasswordProvider(Protocol):
+    """Протокол получения пароля 2FA.
+
+    Вызывается только если Max потребовал дополнительный пароль после SMS-кода.
+    """
+
+    async def get_password(self, hint: str | None = None) -> str:
+        """Возвращает пароль 2FA с учетом подсказки, если она есть."""
+        ...
+
+
+class ConsolePasswordProvider:
+    """Консольный provider пароля 2FA.
+
+    Читает пароль через ``getpass`` и не выводит его на экран.
+    """
+
+    async def get_password(self, hint: str | None = None) -> str:
+        """Запрашивает пароль 2FA в консоли.
+
+        Args:
+            hint: Подсказка пароля от Max, если сервер ее прислал.
+
+        Returns:
+            Введенный пароль.
+        """
+        prompt = "Enter 2FA password"
+        if hint:
+            prompt += f" (hint: {hint})"
+        prompt += ": "
+        return (await asyncio.to_thread(getpass.getpass, prompt)).strip()
+
+
+class QrHandler(Protocol):
+    """Протокол показа QR-ссылки пользователю.
+
+    Handler должен только показать ``qr_url``. Подтверждение и polling делает
+    ``QrAuthFlow``.
+    """
+
+    async def show_qr(self, qr_url: str) -> None:
+        """Показывает пользователю QR-ссылку для подтверждения входа."""
+        ...
+
+
+#    async def on_confirmed(self) -> None: ...
+
+
+class ConsoleQrHandler:
+    """Консольный QR handler.
+
+    Печатает QR-код ASCII-графикой в терминал.
+    """
+
+    async def show_qr(self, qr_url: str) -> None:
+        """Показывает QR-ссылку в терминале.
+
+        Args:
+            qr_url: Ссылка, которую нужно открыть или отсканировать.
+
+        Returns:
+            ``None``.
+        """
+        qr = qrcode.QRCode()
+        qr.add_data(qr_url)
+        qr.print_ascii()
+
+
+class EmailCodeProvider(Protocol):
+    """Протокол получения кода подтверждения email для настройки 2FA."""
+
+    async def get_code(self, email: str) -> str:
+        """Возвращает код подтверждения, отправленный на email."""
+        ...
+
+
+class ConsoleEmailCodeProvider:
+    """Консольный provider кода подтверждения email для 2FA."""
+
+    async def get_code(self, email: str) -> str:
+        """Запрашивает email-код в консоли.
+
+        Args:
+            email: Адрес, на который Max отправил код подтверждения.
+
+        Returns:
+            Введенный пользователем код.
+        """
+        return input(f"Enter 2FA email code for {email}: ").strip()