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

pymax/auth/qr.py

@@ -0,0 +1,135 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from typing import TYPE_CHECKING
+
+import qrcode
+
+from pymax.exceptions import ApiError
+from pymax.logging import get_logger
+
+from .models import AuthResult
+from .providers import ConsolePasswordProvider, PasswordProvider, QrHandler
+
+if TYPE_CHECKING:
+    from pymax.app import App
+    from pymax.types.domain.auth import RequestQrResponse
+
+
+logger = get_logger(__name__)
+
+
+class QrAuthFlow:
+    """Стандартная QR-авторизация ``WebClient``.
+
+    Flow получает QR-ссылку, передает ее в ``QrHandler``, ждет подтверждения и
+    возвращает token для сохранения в сессии.
+
+    Args:
+        qr_provider: Handler, который показывает QR пользователю.
+        password_provider: Provider пароля 2FA. Если не передан, используется
+            ``ConsolePasswordProvider``.
+
+    Example:
+        .. code-block:: python
+
+           from pymax import ConsoleQrHandler, QrAuthFlow, WebClient
+
+           flow = QrAuthFlow(ConsoleQrHandler())
+           client = WebClient(auth_flow=flow)
+    """
+
+    def __init__(
+        self,
+        qr_provider: QrHandler,
+        password_provider: PasswordProvider | None = None,
+    ) -> None:
+        self.qr_provider = qr_provider
+        self.password_provider = password_provider or ConsolePasswordProvider()
+
+    async def authenticate(self, app: App) -> AuthResult:
+        """Проходит QR-авторизацию.
+
+        Args:
+            app: Внутренний runtime PyMax.
+
+        Returns:
+            ``AuthResult`` с token.
+
+        Raises:
+            RuntimeError: Если QR истек до подтверждения.
+        """
+        logger.info("starting qr authentication")
+
+        qr_info = await app.api.auth.request_qr()
+
+        logger.debug("got qr track_id=%s", qr_info.track_id)
+
+        await self.qr_provider.show_qr(qr_info.qr_link)
+
+        confirmed = await self._poll_qr(app, qr_info)
+
+        if not confirmed:
+            raise RuntimeError("QR authentication expired")
+
+        result = await app.api.auth.confirm_qr(qr_info.track_id)
+
+        token = result.login_token
+        if not token and result.password_challenge:
+            token = await self._authenticate_with_password(
+                app,
+                track_id=result.password_challenge.track_id,
+                hint=result.password_challenge.hint,
+            )
+
+        return AuthResult(
+            token=token,
+        )
+
+    async def _poll_qr(self, app: App, qr_info: RequestQrResponse) -> bool:
+        interval = qr_info.polling_interval / 1000
+        expires_at = qr_info.expires_at / 1000
+
+        while time.time() < expires_at:
+            response = await app.api.auth.check_qr(qr_info.track_id)
+
+            if response.status.login_available:
+                return True
+
+            await asyncio.sleep(interval)
+
+        return False
+
+    async def _authenticate_with_password(
+        self,
+        app: App,
+        track_id: str,
+        hint: str | None,
+    ) -> str:
+        logger.info("starting 2fa password authentication")
+        while True:
+            password = await self.password_provider.get_password(hint)
+            logger.debug(
+                "2fa password provider returned password_set=%s",
+                bool(password),
+            )
+            if not password:
+                logger.warning("2fa password is empty; retrying")
+                continue
+
+            try:
+                response = await app.api.auth.check_password(track_id, password)
+            except ApiError as e:
+                logger.error("2fa password check failed: %s", e)
+                continue
+
+            if response.error:
+                logger.error("2fa password check failed error=%s", response.error)
+                continue
+
+            if response.login_token:
+                logger.info("2fa password authentication completed")
+                return response.login_token
+
+            logger.error("2fa password response did not contain login token; retrying")

pymax/auth/service.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pymax.logging import get_logger
+
+from .providers import SmsCodeProvider
+from .sms import SmsAuthFlow
+
+if TYPE_CHECKING:
+    from pymax.app import App
+
+
+logger = get_logger(__name__)
+
+
+class AuthService:
+    def __init__(self, app: App, sms_code_provider: SmsCodeProvider) -> None:
+        self.app = app
+        self.sms_code_provider = sms_code_provider
+        self.sms = SmsAuthFlow(self.sms_code_provider)
+        logger.debug(
+            "auth service initialized sms_provider=%s",
+            type(sms_code_provider).__name__,
+        )

pymax/auth/sms.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pymax.exceptions import ApiError
+from pymax.logging import get_logger
+
+from .models import AuthResult
+from .providers import ConsolePasswordProvider, PasswordProvider, SmsCodeProvider
+
+if TYPE_CHECKING:
+    from pymax.app import App
+
+
+logger = get_logger(__name__)
+
+
+class SmsAuthFlow:
+    """Стандартная SMS-авторизация ``Client``.
+
+    Flow запрашивает SMS-код, отправляет его в Max, при необходимости проходит
+    пароль 2FA и возвращает token для сохранения в сессии.
+
+    Args:
+        code_provider: Provider, который возвращает SMS-код.
+        password_provider: Provider пароля 2FA. Если не передан, используется
+            ``ConsolePasswordProvider``.
+
+    Example:
+        .. code-block:: python
+
+           from pymax import Client, ConsoleSmsCodeProvider, SmsAuthFlow
+
+           flow = SmsAuthFlow(ConsoleSmsCodeProvider())
+           client = Client(
+               phone="+79990000000",
+               auth_flow=flow,
+           )
+    """
+
+    def __init__(
+        self,
+        code_provider: SmsCodeProvider,
+        password_provider: PasswordProvider | None = None,
+    ) -> None:
+        self.code_provider = code_provider
+        self.password_provider = password_provider or ConsolePasswordProvider()
+
+    async def authenticate(self, app: App) -> AuthResult:
+        """Проходит SMS/2FA-авторизацию.
+
+        Args:
+            app: Внутренний runtime PyMax.
+
+        Returns:
+            ``AuthResult`` с token.
+
+        Raises:
+            RuntimeError: Если у клиента нет телефона.
+        """
+        phone = app.config.phone
+        if not phone:
+            logger.error("sms authentication requested without phone")
+            raise RuntimeError("Phone is required for SMS authentication")
+
+        logger.info("starting sms authentication")
+        start = await app.api.auth.request_code(phone)
+        logger.debug("sms token received token_set=%s", bool(start.token))
+        code = await self.code_provider.get_code(phone)
+        logger.debug("sms code provider returned code_set=%s", bool(code))
+        result = await app.api.auth.send_code(start.token, code)
+
+        token = result.login_token
+        if not token and result.password_challenge:
+            token = await self._authenticate_with_password(
+                app,
+                track_id=result.password_challenge.track_id,
+                hint=result.password_challenge.hint,
+            )
+
+        logger.info(
+            "sms authentication completed token_set=%s",
+            bool(token),
+        )
+        return AuthResult(
+            token=token,
+        )
+
+    async def _authenticate_with_password(
+        self,
+        app: App,
+        track_id: str,
+        hint: str | None,
+    ) -> str:
+        logger.info("starting 2fa password authentication")
+        while True:
+            password = await self.password_provider.get_password(hint)
+            logger.debug(
+                "2fa password provider returned password_set=%s",
+                bool(password),
+            )
+            if not password:
+                logger.warning("2fa password is empty; retrying")
+                continue
+
+            try:
+                response = await app.api.auth.check_password(track_id, password)
+            except ApiError as e:
+                logger.error("2fa password check failed: %s", e)
+                continue
+
+            if response.error:
+                logger.error("2fa password check failed error=%s", response.error)
+                continue
+
+            if response.login_token:
+                logger.info("2fa password authentication completed")
+                return response.login_token
+
+            logger.error(
+                "2fa password response did not contain login token; retrying"
+            )

pymax/base.py

@@ -0,0 +1,204 @@
+from __future__ import annotations
+
+import asyncio
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, Generic, TypeVar
+from uuid import uuid4
+
+from pymax.dispatch import Router
+from pymax.infra import BaseMixin
+from pymax.logging import get_logger
+
+from .app import App
+from .config import ClientConfig, DeviceConfig, ExtraConfig
+
+if TYPE_CHECKING:
+    from pymax.api.session.payloads import MobileUserAgentPayload
+    from pymax.auth import AuthFlow
+    from pymax.connection import ConnectionManager
+    from pymax.dispatch.router import (
+        FilterCallback,
+        HandlerDecorator,
+        StartDecorator,
+    )
+    from pymax.protocol import InboundFrame
+    from pymax.types import Chat, MessageDeleteEvent, User
+    from pymax.types.domain import Message, Profile
+
+logger = get_logger(__name__)
+ClientT = TypeVar("ClientT", bound="BaseClient[Any]")
+
+
+class BaseClient(BaseMixin, ABC, Generic[ClientT]):
+    extra_config: ExtraConfig
+    session_name: str
+    work_dir: str
+    _config: ClientConfig
+    _connection: ConnectionManager
+    _auth_flow: AuthFlow
+    _router: Router[ClientT]
+    _app: App[ClientT]
+
+    @property
+    def me(self) -> Profile | None:
+        """Профиль текущего аккаунта после успешного ``start``."""
+        return self._app.me
+
+    @property
+    def chats(self) -> list[Chat] | None:
+        """Чаты, которые Max вернул на login/sync."""
+        return self._app.chats
+
+    @property
+    def contacts(self) -> list[User | None]:
+        """Контакты, которые Max вернул на login/sync."""
+        return self._app.contacts
+
+    @property
+    def messages(self) -> dict[int, list[Message]] | None:
+        """Сообщения, которые Max вернул на login/sync."""
+        return self._app.messages
+
+    def _build_config(
+        self,
+        *,
+        phone: str | None,
+        user_agent: MobileUserAgentPayload,
+    ) -> ClientConfig:
+        logger.debug(
+            "building client config token_set=%s",
+            bool(self.extra_config.token),
+        )
+        return ClientConfig(
+            phone=phone,
+            session_name=self.session_name,
+            work_dir=self.work_dir,
+            token=self.extra_config.token,
+            host=self.extra_config.host,
+            port=self.extra_config.port,
+            use_ssl=self.extra_config.use_ssl,
+            request_timeout=self.extra_config.request_timeout,
+            log_level=self.extra_config.log_level,
+            telemetry=self.extra_config.telemetry,
+            sync=self.extra_config.sync,
+            store=self.extra_config.store,
+            device=DeviceConfig(
+                mt_instance_id=self.extra_config.mt_instance_id,
+                device_id=self.extra_config.device_id or str(uuid4()),
+                user_agent=user_agent,
+            ),
+        )
+
+    @abstractmethod
+    def _build_connection(self) -> ConnectionManager:
+        raise NotImplementedError
+
+    def _init_runtime(self: ClientT, *, auth_flow: AuthFlow) -> None:  # noqa: PYI019
+        self._connection = self._build_connection()
+        self._auth_flow = auth_flow
+        self._router = Router()
+        self._app = self._build_app()
+
+    def _build_app(self: ClientT) -> App[ClientT]:  # noqa: PYI019
+        app: App[ClientT] = App(
+            connection=self._connection,
+            config=self._config,
+            auth_flow=self._auth_flow,
+            root_router=self._router,
+        )
+        app.dispatcher.bind_client(self)
+        return app
+
+    def _reset_runtime(self: ClientT) -> None:  # noqa: PYI019
+        self._connection = self._build_connection()
+        self._app = self._build_app()
+
+    async def start(self: ClientT) -> None:  # noqa: PYI019
+        """Запускает клиента и слушает события до закрытия соединения."""
+        while True:
+            try:
+                await self._app.start()
+                await self._app.dispatcher.emit_start(self)
+                await self._connection.wait_closed()
+            except asyncio.CancelledError:
+                await self.close()
+                raise
+            except (  # noqa: PERF203
+                ConnectionError,
+                EOFError,
+                OSError,
+                TimeoutError,
+            ):
+                await self.close()
+                if not self.extra_config.reconnect:
+                    raise
+
+                logger.exception(
+                    "client connection failed; reconnecting in %s seconds",
+                    self.extra_config.reconnect_delay,
+                )
+                await asyncio.sleep(self.extra_config.reconnect_delay)
+                self._reset_runtime()
+            except Exception:
+                await self.close()
+                raise
+            else:
+                await self.close()
+                return
+
+    async def close(self) -> None:
+        """Закрывает соединение, фоновые задачи и файл сессии."""
+        await self._app.close()
+
+    async def stop(self) -> None:
+        """Останавливает клиента."""
+        await self.close()
+
+    async def __aenter__(self: ClientT) -> ClientT:  # noqa: PYI019
+        return self
+
+    async def __aexit__(self, *args: object) -> None:
+        await self.close()
+
+    def on_start(self) -> StartDecorator[ClientT]:
+        """Регистрирует обработчик успешного запуска."""
+        return self._router.on_start()
+
+    def on_message(
+        self,
+        *filters: FilterCallback[Message],
+    ) -> HandlerDecorator[Message, ClientT]:
+        """Регистрирует обработчик новых сообщений."""
+        return self._router.on_message(*filters)
+
+    def on_message_edit(
+        self,
+        *filters: FilterCallback[Message],
+    ) -> HandlerDecorator[Message, ClientT]:
+        """Регистрирует обработчик редактирования сообщений."""
+        return self._router.on_message_edit(*filters)
+
+    def on_message_delete(
+        self,
+        *filters: FilterCallback[MessageDeleteEvent],
+    ) -> HandlerDecorator[MessageDeleteEvent, ClientT]:
+        """Регистрирует обработчик удаления сообщений."""
+        return self._router.on_message_delete(*filters)
+
+    def on_chat_update(
+        self,
+        *filters: FilterCallback[Chat],
+    ) -> HandlerDecorator[Chat, ClientT]:
+        """Регистрирует обработчик обновления чата."""
+        return self._router.on_chat_update(*filters)
+
+    def on_raw(
+        self,
+        *filters: FilterCallback[InboundFrame],
+    ) -> HandlerDecorator[InboundFrame, ClientT]:
+        """Регистрирует обработчик исходных входящих frame-ов."""
+        return self._router.on_raw(*filters)
+
+    def include_router(self, router: Router[ClientT]) -> None:
+        """Подключает дочерний router к root router клиента."""
+        self._router.include_router(router)

pymax/client.py

@@ -0,0 +1,106 @@
+from __future__ import annotations
+
+from pymax.auth import (
+    AuthFlow,
+    ConsoleSmsCodeProvider,
+    PasswordProvider,
+    SmsAuthFlow,
+    SmsCodeProvider,
+)
+from pymax.connection import ConnectionManager
+from pymax.connection.readers import TCPReader
+from pymax.logging import configure_logging, get_logger
+from pymax.protocol.tcp import TcpProtocol
+from pymax.protocol.tcp.framing import TcpPacketFramer
+from pymax.transport.tcp import TCPTransport
+
+from .base import BaseClient
+from .config import ExtraConfig
+
+logger = get_logger(__name__)
+
+
+class Client(BaseClient["Client"]):
+    """TCP-клиент PyMax с SMS-авторизацией.
+
+    Используйте ``Client`` как основной long-running клиент: он открывает
+    соединение, проходит авторизацию, хранит сессию в ``work_dir``.
+    Клиент вызывает роутеры и предоставляет методы для сообщений, чатов,
+    пользователей и профиля.
+
+    Args:
+        phone: Номер телефона для первой авторизации.
+        session_name: Имя SQLite-файла сессии внутри ``work_dir``.
+        work_dir: Директория для файла сессии и служебного cache.
+        extra_config: Дополнительные настройки соединения, логов, reconnect
+            и sync.
+        auth_flow: Полностью пользовательский сценарий авторизации.
+        sms_code_provider: Провайдер SMS-кода для стандартного ``SmsAuthFlow``.
+        password_provider: Провайдер пароля 2FA, если аккаунт его требует.
+    """
+
+    def __init__(
+        self,
+        phone: str,
+        session_name: str = "session.db",
+        work_dir: str = ".",
+        extra_config: ExtraConfig | None = None,
+        auth_flow: AuthFlow | None = None,
+        sms_code_provider: SmsCodeProvider | None = None,
+        password_provider: PasswordProvider | None = None,
+    ) -> None:
+        self.phone = phone
+        self.extra_config = extra_config or ExtraConfig()
+        self.session_name = session_name
+        self.work_dir = work_dir
+
+        configure_logging(self.extra_config.log_level)
+        logger.debug(
+            "creating client phone_set=%s session=%s work_dir=%s proxy_set=%s reconnect=%s",
+            bool(phone),
+            self.session_name,
+            self.work_dir,
+            bool(self.extra_config.proxy),
+            self.extra_config.reconnect,
+        )
+
+        self._config = self._build_config(
+            phone=phone,
+            user_agent=(self.extra_config.user_agent or self.extra_config.generate_user_agent()),
+        )
+
+        if auth_flow is None:
+            auth_flow = SmsAuthFlow(
+                sms_code_provider or ConsoleSmsCodeProvider(),
+                password_provider,
+            )
+        self._init_runtime(auth_flow=auth_flow)
+
+        logger.debug(
+            "client created transport=tcp host=%s port=%s",
+            self.extra_config.host,
+            self.extra_config.port,
+        )
+
+    def _build_connection(self) -> ConnectionManager:
+        logger.debug(
+            "building tcp connection host=%s port=%s ssl=%s",
+            self.extra_config.host,
+            self.extra_config.port,
+            self.extra_config.use_ssl,
+        )
+        transport = TCPTransport(
+            port=self.extra_config.port,
+            host=self.extra_config.host,
+            use_ssl=self.extra_config.use_ssl,
+            proxy=self.extra_config.proxy,
+        )
+        reader = TCPReader(
+            transport=transport,
+            framer=TcpPacketFramer(),
+        )
+        return ConnectionManager(
+            reader=reader,
+            transport=transport,
+            protocol=TcpProtocol(),
+        )

pymax/client_web.py

@@ -0,0 +1,83 @@
+from __future__ import annotations
+
+from pymax.auth.providers import ConsoleQrHandler, QrHandler
+from pymax.auth.qr import QrAuthFlow
+from pymax.connection import ConnectionManager
+from pymax.connection.readers import WSReader
+from pymax.logging import configure_logging, get_logger
+from pymax.protocol.ws import WsProtocol
+from pymax.transport.websocket import WebSocketTransport
+
+from .base import BaseClient
+from .config import ExtraConfig
+
+logger = get_logger(__name__)
+
+
+class WebClient(BaseClient["WebClient"]):
+    """WebSocket-клиент PyMax с QR-авторизацией.
+
+    Используйте ``WebClient``, когда нужен web-режим Max: клиент открывает
+    WebSocket, показывает QR через ``qr_provider`` и после подтверждения
+    сохраняет сессию в ``work_dir/session_name``.
+
+    Args:
+        session_name: Имя SQLite-файла сессии внутри ``work_dir``.
+        work_dir: Директория для файла сессии.
+        extra_config: Настройки URL, логов, reconnect, device и sync.
+        auth_flow: Пользовательский QR auth-flow.
+        qr_provider: Обработчик, который показывает QR пользователю.
+    """
+
+    def __init__(
+        self,
+        session_name: str = "session.db",
+        work_dir: str = ".",
+        extra_config: ExtraConfig | None = None,
+        auth_flow: QrAuthFlow | None = None,
+        qr_provider: QrHandler | None = None,
+    ) -> None:
+        self.extra_config = extra_config or ExtraConfig()
+        self.session_name = session_name
+        self.work_dir = work_dir
+
+        configure_logging(self.extra_config.log_level)
+        logger.debug(
+            "creating web client session=%s work_dir=%s proxy_set=%s reconnect=%s",
+            self.session_name,
+            self.work_dir,
+            bool(self.extra_config.proxy),
+            self.extra_config.reconnect,
+        )
+
+        self._config = self._build_config(
+            phone=None,
+            user_agent=(
+                self.extra_config.user_agent or self.extra_config.generate_web_user_agent()
+            ),
+        )
+
+        if auth_flow is None:
+            auth_flow = QrAuthFlow(qr_provider or ConsoleQrHandler())
+        self._init_runtime(auth_flow=auth_flow)
+
+        logger.debug(
+            "web client created transport=ws url=%s",
+            self.extra_config.url,
+        )
+
+    def _build_connection(self) -> ConnectionManager:
+        logger.debug(
+            "building websocket connection url=%s",
+            self.extra_config.url,
+        )
+        transport = WebSocketTransport(
+            url=self.extra_config.url,
+            proxy=self.extra_config.proxy,
+        )
+        reader = WSReader(transport=transport)
+        return ConnectionManager(
+            reader=reader,
+            transport=transport,
+            protocol=WsProtocol(),
+        )