maxbridge-client 0.2.0__py3-none-any.whl

maxbridge/__init__.py

@@ -0,0 +1,6 @@
+from .client import MaxClient
+from . import functions
+from . import models
+from . import exceptions
+
+__all__ = ['MaxClient', 'functions', 'models', 'exceptions']

maxbridge/client.py

@@ -0,0 +1,504 @@
+import asyncio
+import itertools
+import json
+import logging
+import uuid
+from typing import Any ,Callable ,Optional
+
+import aiohttp
+import websockets
+from websockets .asyncio .client import ClientConnection
+
+from functools import wraps
+
+from .exceptions import APIError ,ConnectionError
+from . import models
+
+WS_HOST ="wss://ws-api.oneme.ru/websocket"
+RPC_VERSION =11
+# Match current MAX web client fingerprint from captured traffic
+APP_VERSION ="26.3.6"
+USER_AGENT ="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/145.0.0.0 Safari/537.36"
+
+_logger =logging .getLogger (__name__ )
+
+
+def ensure_connected (method :Callable ):
+    @wraps (method )
+    def wrapper (self ,*args ,**kwargs ):
+        if self ._connection is None :
+            raise RuntimeError ("WebSocket not connected. Call .connect() first.")
+        return method (self ,*args ,**kwargs )
+
+    return wrapper
+
+
+class MaxClient :
+    def __init__ (self ):
+        self ._connection :Optional [ClientConnection ]=None
+        self ._http_pool :Optional [aiohttp .ClientSession ]=None
+        self ._is_logged_in :bool =False
+        self ._device_id :Optional [str ]=None
+        self ._seq =itertools .count (1 )
+        self ._keepalive_task :Optional [asyncio .Task ]=None
+        self ._recv_task :Optional [asyncio .Task ]=None
+        self ._incoming_event_callback =None
+        self ._reconnect_callback =None
+        self ._closed :bool =False
+        self ._pending ={}
+        self ._video_pending ={}
+        self ._file_pending ={}
+
+        self ._cached_chats :dict [int ,dict ]={}
+        self ._cached_users :dict [int ,dict ]={}
+        self ._profile :Optional [dict ]=None
+
+
+
+    async def connect (self ):
+        if self ._connection :
+            raise Exception ("Already connected")
+
+        self ._closed =False
+        _logger .info (f'Connecting to {WS_HOST }...')
+        self ._connection =await websockets .connect (
+        WS_HOST ,
+        origin =websockets .Origin ('https://web.max.ru'),
+        user_agent_header =USER_AGENT
+        )
+
+        self ._recv_task =asyncio .create_task (self ._recv_loop ())
+        _logger .info ('Connected. Receive task started.')
+        return self ._connection
+
+    @ensure_connected
+    async def disconnect (self ):
+        self ._closed =True
+        await self ._stop_keepalive_task ()
+        if self ._recv_task :
+            self ._recv_task .cancel ()
+        await self ._connection .close ()
+        self ._connection =None
+        if self ._http_pool :
+            await self ._http_pool .close ()
+            self ._http_pool =None
+
+    @ensure_connected
+    async def invoke_method (self ,opcode :int ,payload :dict [str ,Any ],retries :int =2 ):
+        seq =next (self ._seq )
+
+        request ={
+        "ver":RPC_VERSION ,
+        "cmd":0 ,
+        "seq":seq ,
+        "opcode":opcode ,
+        "payload":payload
+        }
+        _logger .info (f'-> REQUEST: {request }')
+
+        future =asyncio .get_running_loop ().create_future ()
+        self ._pending [seq ]=future
+
+        try :
+            await self ._connection .send (
+            json .dumps (request )
+            )
+        except websockets .exceptions .ConnectionClosed :
+            _logger .warning ('got ws disconnect in invoke_method')
+            if self ._reconnect_callback :
+                _logger .info ('reconnecting')
+                await self ._reconnect_callback ()
+                if retries >0 :
+                    _logger .info ('retrying invoke_method after reconnect')
+                    await self .invoke_method (opcode ,payload ,retries -1 )
+            return
+
+        try :
+            response =await future
+        except asyncio .CancelledError :
+            self ._pending .pop (seq ,None )
+            raise
+        _logger .info (f'<- RESPONSE: {response }')
+
+
+        if "error" in response .get ("payload", {}):
+            payload = response.get("payload", {})
+            error = payload.get("error")
+            # Some responses return a string error instead of an object
+            if isinstance(error, dict):
+                code = error.get("code", -1)
+                message = error.get("message", payload.get("message", "Unknown error"))
+            else:
+                code = -1
+                message = payload.get("message") or str(error)
+
+            raise APIError(code, message)
+
+        return response
+
+    async def set_callback (self ,function ):
+        import warnings
+        warnings .warn ('switch to set_packet_callback',category =DeprecationWarning )
+        self .set_packet_callback (function )
+
+    def set_packet_callback (self ,function ):
+        if not asyncio .iscoroutinefunction (function ):
+            raise TypeError ('callback must be async')
+        self ._incoming_event_callback =function
+
+    def set_reconnect_callback (self ,function ):
+        if not asyncio .iscoroutinefunction (function ):
+            raise TypeError ('callback must be async')
+        self ._reconnect_callback =function
+    async def debug_invoke (self ,opcode :int ,payload :dict | None =None ,timeout :float =5.0 ):
+        """Invoke an opcode for debugging.
+
+        This helper wraps `invoke_method` and catches exceptions, returning a
+        structured report instead of raising.
+        """
+        payload = payload or {}
+        try :
+            response =await asyncio .wait_for (self .invoke_method (opcode ,payload ),timeout )
+            return {
+            "opcode":opcode ,
+            "payload":payload ,
+            "response":response ,
+            "error":None
+            }
+        except Exception as e :
+            return {
+            "opcode":opcode ,
+            "payload":payload ,
+            "response":None ,
+            "error":repr (e )
+            }
+
+    async def discover_opcodes (self ,start :int =1 ,end :int =120 ,payloads :dict | None =None ,delay :float =0.1 ):
+        """Probe a range of opcodes to see what the server returns.
+
+        **Warning**: This may trigger rate limiting or disconnects.
+        """
+        payloads = payloads or {}
+        results = {}
+        for opcode in range (start ,end +1 ):
+            payload = payloads .get (opcode ,{})
+            results [opcode ]=await self .debug_invoke (opcode ,payload )
+            await asyncio .sleep (delay )
+        return results
+    async def _recv_loop (self ):
+        while not self ._closed :
+            try :
+                packet =await self ._connection .recv ()
+                packet =json .loads (packet )
+
+            except asyncio .CancelledError :
+                _logger .info ('receiver cancelled')
+                return
+
+            except websockets .exceptions .ConnectionClosedError as err :
+                _logger .warning ('got ws disconnect in receiver')
+                if not self ._is_logged_in :
+                    raise err
+                if self ._reconnect_callback :
+                    _logger .info ('reconnecting')
+                    asyncio .create_task (self ._reconnect_callback ())
+                return
+
+            except websockets .exceptions .ConnectionClosedOK :
+                _logger .info ('connection closed by server')
+                return
+
+            except json .JSONDecodeError :
+                _logger .warning ('could not decode packet')
+                continue
+
+            seq =packet ["seq"]
+            future =self ._pending .pop (seq ,None )
+            if future :
+                future .set_result (packet )
+                continue
+
+            if packet .get ("opcode")==136 :
+                payload =packet .get ("payload",{})
+                future =None
+
+                if "videoId"in payload :
+                    future =self ._video_pending .pop (payload ["videoId"],None )
+                elif "fileId"in payload :
+                    future =self ._file_pending .pop (payload ["fileId"],None )
+
+                if future :
+                    future .set_result (None )
+
+            if self ._incoming_event_callback :
+                asyncio .create_task (self ._incoming_event_callback (self ,packet ))
+
+
+
+    @ensure_connected
+    async def _send_keepalive_packet (self ):
+        try :
+            async with asyncio .timeout (15 ):
+                await self .invoke_method (
+                opcode =1 ,
+                payload ={"interactive":True }
+                )
+        except asyncio .TimeoutError :
+            _logger .warning ('keepalive ping timed out')
+            if self ._reconnect_callback :
+                _logger .info ('reconnecting')
+                asyncio .create_task (self ._reconnect_callback ())
+
+    @ensure_connected
+    async def _keepalive_loop (self ):
+        _logger .info (f'keepalive task started')
+        try :
+            while True :
+                await self ._send_keepalive_packet ()
+                await asyncio .sleep (30 )
+        except asyncio .CancelledError :
+            _logger .info ('keepalive task stopped')
+            return
+
+    @ensure_connected
+    async def _start_keepalive_task (self ):
+        if self ._keepalive_task :
+            raise Exception ('Keepalive task already started')
+
+        self ._keepalive_task =asyncio .create_task (self ._keepalive_loop ())
+        return
+
+    async def _stop_keepalive_task (self ):
+        if not self ._keepalive_task :
+            raise Exception ('Keepalive task is not running')
+
+        self ._keepalive_task .cancel ()
+        self ._keepalive_task =None
+        return
+
+
+
+    @ensure_connected
+    async def _send_hello_packet (self ,device_id :Optional [str ]=None ):
+        self ._device_id =device_id or f'{uuid .uuid4 ()}'
+        return await self .invoke_method (
+        opcode =6 ,
+        payload ={
+        "userAgent":{
+        "deviceType":"WEB",
+        "locale":"ru",
+        "deviceLocale":"ru",
+        "osVersion":"Linux",
+        "deviceName":"Chrome",
+        "headerUserAgent":USER_AGENT ,
+        "appVersion":APP_VERSION ,
+        "screen":"720x1280 1.0x",
+        "timezone":"Asia/Yekaterinburg"
+        },
+        "deviceId":self ._device_id ,
+        }
+        )
+
+    @ensure_connected
+    async def send_code (self ,phone :str )->str :
+        """:returns: Login token."""
+        await self ._send_hello_packet ()
+        start_auth_response =await self .invoke_method (
+        opcode =17 ,
+        payload ={
+        "phone":phone ,
+        "type":"START_AUTH",
+        "language":"ru"
+        }
+        )
+        return start_auth_response ["payload"]["token"]
+
+    @ensure_connected
+    async def sign_in (self ,sms_token :str ,sms_code :int ):
+        """
+        Auth token for further login is at ['payload']['tokenAttrs']['LOGIN']['token']
+        :param login_token: Must be obtained via `send_code`.
+        """
+        verification_response =await self .invoke_method (
+        opcode =18 ,
+        payload ={
+        "token":sms_token ,
+        "verifyCode":str (sms_code ),
+        "authTokenType":"CHECK_CODE"
+        }
+        )
+
+        if "error"in verification_response ["payload"]:
+            raise Exception (verification_response ["payload"]["error"])
+
+
+        if "profile"in verification_response ["payload"]:
+            self ._profile =verification_response ["payload"]["profile"]
+
+
+        if "chats"in verification_response ["payload"]:
+            for chat in verification_response ["payload"]["chats"]:
+                self ._cached_chats [chat ["id"]]=chat
+
+
+        if "chats"in verification_response ["payload"]:
+            user_ids =set ()
+            for chat in verification_response ["payload"]["chats"]:
+                if "participants"in chat :
+                    for uid in chat ["participants"].keys ():
+                        user_ids .add (int (uid ))
+            if user_ids :
+
+                try :
+                    users_response =await self .invoke_method (
+                    opcode =32 ,
+                    payload ={"contactIds":list (user_ids )}
+                    )
+                    if "payload"in users_response and "contacts"in users_response ["payload"]:
+                        for user in users_response ["payload"]["contacts"]:
+                            self ._cached_users [user ["id"]]=user
+                except Exception as e :
+                    _logger .warning (f'Failed to fetch users: {e }')
+
+        try :
+            phone =verification_response ["payload"]["profile"]["contact"]["phone"]
+        except :
+            phone ='[?]'
+            _logger .warning ('Got no phone number in server response')
+        _logger .info (f'Successfully logged in as {phone }')
+
+        self ._is_logged_in =True
+        await self ._start_keepalive_task ()
+
+        return verification_response
+
+    @ensure_connected
+    async def login_by_token (self ,token :str ,device_id :Optional [str ]=None ):
+        await self ._send_hello_packet (device_id )
+        _logger .info ("using session")
+        login_response =await self .invoke_method (
+        opcode =19 ,
+        payload ={
+        "interactive":True ,
+        "token":token ,
+        "chatsCount":40 ,
+        "chatsSync":0 ,
+        "contactsSync":0 ,
+        "presenceSync":-1 ,
+        "draftsSync":0
+        }
+        )
+
+        if "error"in login_response ["payload"]:
+            raise Exception (login_response ["payload"]["error"])
+
+
+        if "profile"in login_response ["payload"]:
+            self ._profile =login_response ["payload"]["profile"]
+
+
+        if "chats"in login_response ["payload"]:
+            for chat in login_response ["payload"]["chats"]:
+                self ._cached_chats [chat ["id"]]=chat
+
+
+        if "chats"in login_response ["payload"]:
+            user_ids =set ()
+            for chat in login_response ["payload"]["chats"]:
+                if "participants"in chat :
+                    for uid in chat ["participants"].keys ():
+                        user_ids .add (int (uid ))
+            if user_ids :
+
+                try :
+                    users_response =await self .invoke_method (
+                    opcode =32 ,
+                    payload ={"contactIds":list (user_ids )}
+                    )
+                    if "payload"in users_response and "contacts"in users_response ["payload"]:
+                        for user in users_response ["payload"]["contacts"]:
+                            self ._cached_users [user ["id"]]=user
+                except Exception as e :
+                    _logger .warning (f'Failed to fetch users: {e }')
+
+        try :
+            phone =login_response ["payload"]["profile"]["contact"]["phone"]
+        except :
+            phone ='[?]'
+            _logger .warning ('Got no phone number in server response')
+        _logger .info (f'Successfully logged in as {phone }')
+
+        self ._is_logged_in =True
+        await self ._start_keepalive_task ()
+
+        return login_response
+
+    @property
+    def device_id (self )->Optional [str ]:
+        return self ._device_id
+
+    @property
+    def profile (self )->Optional [dict ]:
+        return self ._profile
+
+    def get_cached_chats (self )->dict [int ,dict ]:
+        return self ._cached_chats
+
+    def get_cached_users (self )->dict [int ,dict ]:
+        return self ._cached_users
+
+    def get_chats_structured (self )->dict [int ,models .Chat ]:
+        """Return cached chats as `Chat` models."""
+        return {cid :models .Chat .from_raw (data )for cid ,data in self ._cached_chats .items ()}
+
+    def get_users_structured (self )->dict [int ,models .User ]:
+        """Return cached users as `User` models."""
+        return {uid :models .User .from_raw (data )for uid ,data in self ._cached_users .items ()}
+
+    @ensure_connected
+    async def get_chat_messages (self ,chat_id :int ,from_ts :Optional [int ]=None ,backward :int =30 ,forward :int =0 ,get_messages :bool =True ):
+        """Get messages from chat using the same opcode/shape as web client.
+
+        :param chat_id: Chat identifier.
+        :param from_ts: Anchor timestamp (ms). If not provided, tries to use lastEventTime/lastMessage.time from cache.
+        :param backward: How many messages to request before ``from_ts``.
+        :param forward: How many messages to request after ``from_ts``.
+        :param get_messages: Whether to include messages in the response (web uses ``true``).
+        """
+        if from_ts is None :
+            cached =self ._cached_chats .get (chat_id )
+            if cached :
+                from_ts =cached .get ("lastEventTime")or cached .get ("lastMessage" ,{}).get ("time")
+        if from_ts is None :
+            # Fallback to zero – server will interpret according to its defaults
+            from_ts =0
+
+        return await self .invoke_method (
+        opcode =49 ,
+        payload ={
+        "chatId":chat_id ,
+        "from":from_ts ,
+        "forward":forward ,
+        "backward":backward ,
+        "getMessages":get_messages
+        }
+        )
+
+    @ensure_connected
+    async def get_chat_messages_structured (self ,chat_id :int ,from_ts :Optional [int ]=None ,backward :int =30 ,forward :int =0 )->list [models .Message ]:
+        """Wrapper over `get_chat_messages` that returns a list of `Message` models."""
+        raw =await self .get_chat_messages (chat_id ,from_ts =from_ts ,backward =backward ,forward =forward ,get_messages =True )
+        payload =raw .get ("payload", {})
+        msgs =payload .get ("messages")or []
+        if isinstance (msgs ,dict ):
+            iterable =msgs .values ()
+        else :
+            iterable =msgs
+        return [models .Message .from_raw (m ,chat_id =chat_id )for m in iterable ]
+
+    async def __aenter__ (self ):
+        await self .connect ()
+        return self
+
+    async def __aexit__ (self ,exc_type ,exc_val ,exc_tb ):
+        await self .disconnect ()

maxbridge/exceptions.py

@@ -0,0 +1,17 @@
+class MaxException(Exception):
+    pass
+
+
+class ConnectionError(MaxException):
+    pass
+
+
+class AuthenticationError(MaxException):
+    pass
+
+
+class APIError(MaxException):
+    def __init__(self, error_code: int, message: str):
+        self.error_code = error_code
+        self.message = message
+        super().__init__(f"API Error {error_code}: {message}")

maxbridge/models.py

@@ -0,0 +1,80 @@
+from dataclasses import dataclass
+from typing import Optional ,List ,Dict ,Any
+
+
+@dataclass
+class User :
+    id :int
+    name :str
+    username :Optional [str ]=None
+    avatar :Optional [str ]=None
+
+    @classmethod
+    def from_raw (cls ,raw :Dict [str ,Any ]):
+        contact_id =raw .get ("id")
+        names =raw .get ("names")or []
+        name =names [0 ].get ("name") if names else str (contact_id )
+        username =raw .get ("username")
+        base_url =raw .get ("baseUrl") or raw .get ("baseRawUrl")
+        avatar =None
+        if base_url :
+            avatar =base_url
+        return cls (
+        id =contact_id ,
+        name =name ,
+        username =username ,
+        avatar =avatar ,
+        )
+
+
+@dataclass
+class Chat :
+    id :int
+    title :str
+    type :str
+    participants_count :Optional [int ]=None
+    avatar :Optional [str ]=None
+
+    @classmethod
+    def from_raw (cls ,raw :Dict [str ,Any ]):
+        chat_id =raw .get ("id")
+        title =raw .get ("title")
+        chat_type =raw .get ("type","UNKNOWN")
+        participants =raw .get ("participants")or {}
+        participants_count =len (participants )
+        avatar =raw .get ("avatar") or raw .get ("baseUrl") or raw .get ("baseRawUrl")
+        if not title and chat_type =='DIALOG':
+            # диалоги обычно без своего title, его удобно подставлять снаружи по собеседнику
+            title =f"Dialog {chat_id }"
+        return cls (
+        id =chat_id ,
+        title =title or "" ,
+        type =chat_type ,
+        participants_count =participants_count or None ,
+        avatar =avatar ,
+        )
+
+
+@dataclass
+class Message :
+    id :str
+    chat_id :int
+    user_id :int
+    text :str
+    timestamp :int
+    attaches :List [Dict [str ,Any ]]=None
+
+    def __post_init__ (self ):
+        if self .attaches is None :
+            self .attaches =[]
+
+    @classmethod
+    def from_raw (cls ,raw :Dict [str ,Any ] ,chat_id :Optional [int ]=None ):
+        return cls (
+        id =raw .get ("id" ),
+        chat_id =chat_id if chat_id is not None else int (raw .get ("chatId" ,0 )),
+        user_id =raw .get ("sender" ),
+        text =raw .get ("text" ,""),
+        timestamp =raw .get ("time" ,0 ),
+        attaches =raw .get ("attaches" )or [],
+        )

maxbridge/packet.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass
+from typing import Literal ,Any
+
+
+@dataclass
+class MaxPacket :
+
+    ver :int
+    cmd :Literal [0 ,1 ]
+    opcode :int
+    seq :int
+    payload :dict [str ,Any ]

maxbridge_client-0.2.0.dist-info/METADATA

@@ -0,0 +1,299 @@
+Metadata-Version: 2.4
+Name: maxbridge-client
+Version: 0.2.0
+Summary: Асинхронная Python библиотека для MAX API
+Home-page: https://github.com/username/max-bridge
+Author: VK Max Client Team
+Author-email: 
+Maintainer: VK Max Client Team
+License: MIT License
+        
+        Copyright (c) 2026 MaxBridge contributors
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+Project-URL: Homepage, https://github.com/username/max-bridge
+Project-URL: Documentation, https://github.com/username/max-bridge/docs/
+Project-URL: Repository, https://github.com/username/max-bridge
+Project-URL: Bug Reports, https://github.com/username/max-bridge/issues
+Project-URL: Source, https://github.com/username/max-bridge
+Keywords: vk,max,messenger,api,websocket,async
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Communications :: Chat
+Classifier: Topic :: Internet :: WWW/HTTP
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp>=3.8.0
+Requires-Dist: websockets>=12.0
+Provides-Extra: dev
+Requires-Dist: black; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Dynamic: home-page
+Dynamic: license-file
+Dynamic: requires-python
+
+# MaxBridge
+
+[![Python](https://img.shields.io/badge/Python-3.8+-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Asyncio](https://img.shields.io/badge/Asyncio-Supported-green.svg)](https://docs.python.org/3/library/asyncio.html)
+
+Асинхронная Python библиотека для взаимодействия с API мессенджера MAX через WebSocket соединение.
+
+## Описание
+
+MaxBridge предоставляет удобный интерфейс для работы с мессенджером MAX, позволяя отправлять и получать сообщения, управлять чатами, пользователями и файлами в асинхронном режиме.
+
+## 🚀 Быстрый старт
+
+```python
+import asyncio
+from maxbridge import MaxClient
+
+async def main():
+    async with MaxClient() as client:
+        # Авторизация по токену
+        await client.login_by_token("ваш_токен")
+
+        # Получение списка чатов
+        chats = client.get_cached_chats()
+        print(f"Найдено чатов: {len(chats)}")
+
+asyncio.run(main())
+```
+
+## 📦 Установка
+
+```bash
+# Установка из PyPI (предполагается, что пакет опубликован)
+pip install maxbridge
+
+# Или из исходников
+git clone <repository-url>
+cd max-bridge
+pip install -e .
+```
+
+## 🔐 Авторизация
+
+### По токену
+
+**Важно:** Для авторизации необходимо получить токен доступа из веб-версии MAX.
+
+#### Как получить токен:
+
+1. Откройте https://web.max.ru в браузере
+2. Авторизуйтесь в вашем аккаунте
+3. Откройте DevTools (F12) → Application → Local Storage → https://web.max.ru
+4. Найдите ключ `token` и скопируйте его значение
+
+```python
+async with MaxClient() as client:
+    await client.login_by_token("ваш_длинный_токен")
+```
+
+**Примечание:** Токен является конфиденциальной информацией. Храните его securely.
+
+## 💬 Работа с чатами
+
+### Получение списка чатов
+
+```python
+chats = client.get_cached_chats()
+for chat_id, chat_info in chats.items():
+    print(f"ID: {chat_id}, Тип: {chat_info['type']}, Название: {chat_info.get('title', 'Диалог')}")
+```
+
+### Получение сообщений чата
+
+```python
+messages = await client.get_chat_messages(chat_id=123456, count=50, offset=0)
+if "payload" in messages and "messages" in messages["payload"]:
+    for msg_id, msg in messages["payload"]["messages"].items():
+        print(f"{msg['sender']}: {msg['text']}")
+```
+
+## 📨 Отправка сообщений
+
+```python
+from maxbridge.functions import messages
+
+# Текстовое сообщение
+await messages.send_message(client, chat_id=123456, text="Привет!")
+
+# С фото
+await messages.send_photo(client, chat_id=123456, image_path="photo.jpg", caption="Фото")
+
+# Реплай
+await messages.reply_message(client, chat_id=123456, text="Ответ", reply_to_message_id="msg_id")
+```
+
+## 👥 Управление пользователями
+
+```python
+from maxbridge.functions import users
+
+# Информация о пользователях
+user_info = await users.resolve_users(client, user_ids=[12345, 67890])
+
+# Добавить в контакты
+await users.add_to_contacts(client, user_id=12345)
+```
+
+## 📁 Работа с файлами
+
+```python
+from maxbridge.functions import messages, uploads
+
+# Отправка файла
+await messages.send_file(client, chat_id=123456, file_path="document.pdf", caption="Документ")
+
+# Скачивание файла
+download_url = await uploads.download_file(
+    client, chat_id=123456, message_id="msg_id", file_id=789
+)
+```
+
+## 📺 Работа с медиа
+
+```python
+# Скачивание видео
+video_url = await uploads.download_video(
+    client, chat_id=123456, message_id="msg_id", video_id=101112
+)
+```
+
+## 👥 Группы и каналы
+
+```python
+from maxbridge.functions import groups, channels
+
+# Создание группы
+await groups.create_group(client, "Название группы", participant_ids=[123, 456])
+
+# Присоединение к каналу
+await channels.join_channel(client, "username_канала")
+
+# Информация о канале
+channel_info = await channels.resolve_channel_username(client, "username")
+```
+
+## 🛠️ Обработка ошибок
+
+```python
+from maxbridge.exceptions import APIError, ConnectionError
+
+try:
+    await client.login_by_token("токен")
+except APIError as e:
+    print(f"Ошибка API {e.error_code}: {e.message}")
+except ConnectionError:
+    print("Ошибка подключения")
+```
+
+## 📊 Модели данных
+
+```python
+from maxbridge.models import User, Chat, Message
+
+# Примеры
+user = User(id=123, name="Имя", username="username")
+chat = Chat(id=456, title="Название", type="DIALOG")
+message = Message(id="msg_id", chat_id=456, user_id=123, text="Текст")
+```
+
+## 🔧 Продвинутые возможности
+
+### Обработка событий в реальном времени
+
+```python
+def event_handler(client, packet):
+    if packet.get("opcode") == 64:  # Новое сообщение
+        print("Новое сообщение!")
+
+client.set_packet_callback(event_handler)
+```
+
+### Кастомные настройки
+
+```python
+# Профиль
+profile = client.profile
+
+# Кэшированные пользователи
+users = client.get_cached_users()
+```
+
+## 📚 Документация
+
+- [API Reference](docs/API.md)
+- [Примеры](examples/)
+- [Contributing](CONTRIBUTING.md)
+- [Changelog](CHANGELOG.md)
+
+## 🏗️ Структура проекта
+
+```
+maxbridge/
+├── __init__.py
+├── client.py          # WebSocket клиент
+├── models.py          # Модели данных
+├── exceptions.py      # Исключения
+├── packet.py          # Обработка пакетов
+└── functions/         # API функции
+    ├── __init__.py
+    ├── messages.py    # Сообщения
+    ├── users.py       # Пользователи
+    ├── groups.py      # Группы
+    ├── channels.py    # Каналы
+    ├── profile.py     # Профиль
+    └── uploads.py     # Загрузки
+
+docs/                  # Документация
+examples/              # Примеры
+```
+
+## ⚠️ Важные замечания
+
+- Все методы асинхронные — используйте `await`
+- Рекомендуется `async with MaxClient() as client:`
+- Токены имеют срок действия
+- Соблюдайте лимиты API
+
+## 🐛 Отладка
+
+```python
+import logging
+logging.basicConfig(level=logging.INFO)
+```
+
+## 📄 Лицензия
+
+MIT License

maxbridge_client-0.2.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+maxbridge/__init__.py,sha256=_V805CBVvD7aq0tLHkDVj29-AJero0AmLhV8GvEwIiY,161
+maxbridge/client.py,sha256=MM_UZobtThTDw6Ph0c170SlFUqf4WxzMTbKCQC4sGu4,17792
+maxbridge/exceptions.py,sha256=3SxYA381VWcJE4SkIsd1UWVTeoXAgZJYlbahEZ_jfCo,357
+maxbridge/models.py,sha256=OzElV11wezwdFj4zmelBYVP0NwIeAHKvrkKO0sBDNAs,2318
+maxbridge/packet.py,sha256=gXiE1p1NbcoBveUk0aQjO28JNUtjtTv4eZ-q_CiNnd8,195
+maxbridge_client-0.2.0.dist-info/licenses/LICENSE,sha256=Piagsiu7OcH67ZrpAJBxR_-tPhJQHi07CMWgALgmLyU,1078
+maxbridge_client-0.2.0.dist-info/METADATA,sha256=g_W_uTVWOgEyJ11QuVdnzsYHsZcuvxA9awVRy1WZ_dg,10116
+maxbridge_client-0.2.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+maxbridge_client-0.2.0.dist-info/top_level.txt,sha256=pcPHYIca6HlkF7wuoRfuXgzXDXty6V3-VtGMha7Jjd4,10
+maxbridge_client-0.2.0.dist-info/RECORD,,

maxbridge_client-0.2.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

maxbridge_client-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MaxBridge contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

maxbridge_client-0.2.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+maxbridge