webmaxsocket 1.1.3 → 1.1.5

package/README.md

@@ -4,6 +4,8 @@
 
 **WebMaxSocket** — async Node.js библиотека для работы с внутренним API мессенджера Max. Поддерживает **QR-код авторизацию**, **Token авторизацию**, и работу через **WebSocket** (WEB) или **TCP Socket** (IOS/ANDROID).
 
+Сводка всех методов: **[api.package.md](./api.package.md)**.
+
 ## ✨ Особенности / Features
 
 - ✅ **QR-код авторизация** / QR code authentication  
@@ -13,7 +15,10 @@
 - ✅ **Автоматическое сохранение сессий** / Automatic session storage
 - ✅ **Автовыбор транспорта** после QR-авторизации (переход на TCP)
 - ✅ **Отправка и получение сообщений** / Send and receive messages
+- ✅ **Загрузка медиа с диска:** `uploadPhoto`, `uploadVideo`, `uploadFile`, `uploadAudio` → `attachments` в `sendMessage` / `sendMessageChannel` / `reply`
 - ✅ **Скачивание вложений по URL** (`baseUrl` из `attaches`) во временный файл — `downloadUrlToTempFile`, `message.downloadAttachment()`
+- ✅ **Группы и каналы:** создание, инвайты, админы, участники, ссылки, mute, подписка — см. раздел API
+- ✅ **Реакции, пины, настройки профиля и приватности, контакты / блокировка**
 - ✅ **Редактирование и удаление сообщений** / Edit and delete messages
 - ✅ **Event-driven архитектура** / Event-driven architecture
 - ✅ **Обработка входящих уведомлений** / Handle incoming notifications
@@ -288,14 +293,14 @@ const message = await client.sendMessage({
 
 ##### `sendMessageChannel(options)`
 
-Отправляет сообщение в канал без уведомления (notify: false).
+Отправляет сообщение в канал без уведомления (notify: false). Поля **`text`**, **`replyTo`**, **`attachments`** — те же, что у `sendMessage` (вложения из `uploadPhoto` / `uploadVideo` / `uploadFile` / `uploadAudio`).
 
 ```javascript
 const message = await client.sendMessageChannel({
   chatId: 123,
   text: 'Сообщение в канал',
-  replyTo: null,        // ID сообщения для ответа (опционально)
-  attachments: []       // Вложения (опционально)
+  replyTo: null,
+  attachments: [] // опционально: [attach] после upload*
 });
 ```
 
@@ -307,10 +312,57 @@ const message = await client.sendMessageChannel({
 await client.editMessage({
   messageId: 456,
   chatId: 123,
-  text: 'Исправленный текст'
+  text: 'Исправленный текст',
+  attachments: [] // опционально, после upload*
 });
 ```
 
+##### Пины, реакции
+
+| Метод | Назначение |
+|--------|------------|
+| `pinMessage({ chatId, messageId, notifyPin })` | Закрепить сообщение |
+| `setMessageReaction({ chatId, messageId, emoji })` | Эмодзи-реакция |
+| `cancelMessageReaction({ chatId, messageId })` | Снять реакцию |
+| `getMessageReactions({ chatId, messageId, count })` | Список реакций |
+
+##### Чаты, каналы, группы
+
+| Метод | Назначение |
+|--------|------------|
+| `getChatInfo(chatIds)` | Информация по id (массив или одно число) |
+| `resolveLink(link)` | Разрешить URL / `join/…` (LINK_INFO) |
+| `joinChatByLink(link)` | Вступить по ссылке |
+| `setChatSubscription(chatId, subscribe)` | Подписка на канал |
+| `createGroup({ title, userIds })` | Новая группа |
+| `createChannel({ title })` | Новый канал |
+| `muteChat(chatId, mute)` | Уведомления чата (не беспокоить) |
+| `getChatMembers({ chatId, marker, count, type })` | Участники (count ≤ 500) |
+| `inviteToChat({ chatId, userIds, showHistory })` | Пригласить |
+| `removeFromChat({ chatId, userIds, cleanMsgPeriod })` | Исключить |
+| `addChatAdmins({ chatId, userIds, permissions })` | Выдать админку (по умолчанию `permissions: 120`) |
+| `removeChatAdmins({ chatId, userIds })` | Снять админку |
+| `transferChatOwnership({ chatId, newOwnerId })` | Передать владение |
+| `setGroupOptions({ chatId, options })` | Настройки группы (`ALL_CAN_PIN_MESSAGE`, …) |
+| `resolveChannelByUsername(username)` | Канал по @username |
+| `joinChannelByUsername(username)` | Вступить по @username |
+| `resolveInviteHash(hash)` | Инвайт по хэшу без префикса `join/` |
+
+##### Контакты и профиль
+
+| Метод | Назначение |
+|--------|------------|
+| `getContacts(contactIds)` | Несколько контактов (массив id) |
+| `addContact(userId)` | В контакты |
+| `blockUser(userId)` | Заблокировать |
+| `updateProfile({ firstName, lastName, description })` | Своё имя / описание |
+| `setHiddenOnline(hidden)` | Скрыть «в сети» |
+| `setFindableByPhone(mode)` | `'ALL'` \| `'CONTACTS'` или boolean |
+| `setCallsPrivacyMode(mode)` | Кто может звонить |
+| `setChatsInvitePrivacy(mode)` | Кто может приглашать в чаты |
+
+Часть методов требует прав в чате; ответы сервера зависят от роли и типа чата.
+
 ##### `deleteMessage(options)`
 
 Удаляет сообщение.
@@ -334,6 +386,36 @@ await client.forwardMessage({
 });
 ```
 
+##### Загрузка медиа для `attachments`
+
+Все методы ниже возвращают объект(ы), которые передаются в **`attachments`** у `sendMessage`, **`sendMessageChannel`** и **`message.reply`**. Нужен **Node.js 18+** (`fetch`, `FormData`). Схема: опкод загрузки → `UPLOAD_ATTACH_PREP` (65) → HTTP POST на выданный URL. Для **видео** и **файлов** после POST клиент ждёт **`NOTIF_ATTACH` (opcode 136)**.
+
+| Метод | Результат для `attachments` |
+|--------|-----------------------------|
+| `uploadPhoto(chatId, filePath)` | `{ _type: 'PHOTO', photoToken }` |
+| `uploadVideo(chatId, filePath)` | `{ _type: 'VIDEO', videoId, token }` |
+| `uploadFile(chatId, filePath, options?)` | `{ _type: 'FILE', fileId }` — документы, архивы; `options`: `{ filename, mimeType }` |
+| `uploadAudio(chatId, filePath)` | то же, что `uploadFile` с MIME для `.mp3`, `.ogg`, `.m4a`, `.wav`, … |
+
+```javascript
+const photo = await client.uploadPhoto(chatId, './a.png');
+const video = await client.uploadVideo(chatId, './b.mp4');
+const file = await client.uploadFile(chatId, './doc.pdf');
+const audio = await client.uploadAudio(chatId, './track.mp3');
+
+await client.sendMessage({
+  chatId,
+  text: 'Набор вложений',
+  attachments: [photo, video]
+});
+
+await client.sendMessageChannel({
+  chatId,
+  text: 'В канал с файлом',
+  attachments: [file]
+});
+```
+
 ##### `sendChatAction(chatId, action)`
 
 Отправляет действие в чате (печатает, выбирает стикер и т.д.).
@@ -679,6 +761,7 @@ webmaxsocket/
 ├── example-sms.js          # SMS авторизация
 ├── example-ios.js          # IOS/ANDROID Socket
 ├── package.json
+├── api.package.md          # Справочник API (все методы)
 └── README.md
 ```
 

package/api.package.md

@@ -0,0 +1,193 @@
+# WebMaxSocket — справочник API
+
+Краткий перечень возможностей для работы с библиотекой. Подробности и примеры — в `README.md`.
+
+---
+
+## Экспорт пакета (`require('webmaxsocket')`)
+
+| Символ | Описание |
+|--------|----------|
+| `WebMaxClient` | Основной клиент |
+| `MaxSocketTransport` | Низкоуровневый TCP-транспорт |
+| `User`, `Message`, `ChatAction` | Сущности |
+| `ChatActions`, `EventTypes`, `MessageTypes` | Константы |
+| `Opcode`, `getOpcodeName` | Опкоды протокола |
+| `UserAgentPayload` | User-Agent для handshake |
+| `downloadUrlToTempFile`, `extFromContentType`, `extFromAttachType` | Скачивание медиа по URL |
+| `resolveIncomingLogMode`, `printIncomingLog` | Режим лога входящих |
+
+---
+
+## `WebMaxClient`
+
+Клиент наследует `EventEmitter`: `on`, `once`, `emit`, `off` (в т.ч. событие `connected`, `raw_message`).
+
+### Свойства (полезные)
+
+| Свойство | Описание |
+|----------|----------|
+| `me` | Профиль после авторизации |
+| `session` | Менеджер сессий |
+| `isConnected`, `isAuthorized` | Состояние |
+| `userAgent` | Текущий User-Agent |
+| `deviceId` | ID устройства |
+| `incomingLogMode` | `'off'` \| `'messages'` \| `'verbose'` |
+
+### Запуск и соединение
+
+| Метод | Описание |
+|-------|----------|
+| `start()` | Подключение, авторизация, обработчики `onStart` |
+| `connect()` | Только соединение (низкоуровнево) |
+| `connectWithSession()` | Сессия + синхронизация |
+| `handshake()` | Handshake (WebSocket-путь) |
+| `sync()` | LOGIN по токену |
+| `fetchMyProfile()` | Загрузка `me` |
+| `stop()` | Закрыть транспорт |
+| `logout()` | Остановка + удаление сессии |
+
+### Авторизация
+
+| Метод | Описание |
+|-------|----------|
+| `authorize(phone?)` | Сценарий авторизации по умолчанию |
+| `authorizeByQR()` | QR (WEB) |
+| `authorizeBySMS(phone)` | SMS; возвращает `{ sendCode }` |
+| `requestQR()` | Запрос QR |
+| `checkQRStatus(trackId)` | Статус QR |
+| `loginByQR(trackId)` | Завершение по QR |
+| `pollQRStatus(...)` | Ожидание сканирования QR |
+| `showLinkDeviceQR(options?)` | QR «подключить устройство» после входа |
+
+### Сообщения
+
+| Метод | Описание |
+|-------|----------|
+| `sendMessage({ chatId, text, cid?, replyTo?, attachments? })` | С уведомлением |
+| `sendMessageChannel({ ... })` | Канал, `notify: false` |
+| `editMessage({ chatId, messageId, text, attachments? })` | Редактирование |
+| `deleteMessage({ chatId, messageId, forMe? })` | Удаление |
+| `uploadPhoto(chatId, filePath)` | Вложение фото → `attachments` |
+| `uploadVideo(chatId, filePath)` | Видео |
+| `uploadFile(chatId, filePath, options?)` | Файл |
+| `uploadAudio(chatId, filePath)` | Аудио как файл |
+
+### Пины и реакции
+
+| Метод | Описание |
+|-------|----------|
+| `pinMessage({ chatId, messageId, notifyPin? })` | Закрепить |
+| `setMessageReaction({ chatId, messageId, emoji })` | Реакция |
+| `cancelMessageReaction({ chatId, messageId })` | Снять реакцию |
+| `getMessageReactions({ chatId, messageId, count? })` | Список реакций |
+
+### Чаты, каналы, группы
+
+| Метод | Описание |
+|-------|----------|
+| `getChats(marker?)` | Список чатов |
+| `getHistory(chatId, from?, backward?, forward?)` | История |
+| `getChatInfo(chatIds)` | Инфо по id |
+| `resolveLink(link)` | LINK_INFO |
+| `joinChatByLink(link)` | Вступить по ссылке |
+| `setChatSubscription(chatId, subscribe)` | Подписка на канал |
+| `createGroup({ title, userIds })` | Новая группа |
+| `createChannel({ title })` | Новый канал |
+| `muteChat(chatId, mute?)` | Не беспокоить для чата |
+| `getChatMembers({ chatId, marker?, count?, type? })` | Участники |
+| `inviteToChat({ chatId, userIds, showHistory? })` | Пригласить |
+| `removeFromChat({ chatId, userIds, cleanMsgPeriod? })` | Исключить |
+| `addChatAdmins({ chatId, userIds, permissions? })` | Админы |
+| `removeChatAdmins({ chatId, userIds })` | Снять админов |
+| `transferChatOwnership({ chatId, newOwnerId })` | Смена владельца |
+| `setGroupOptions({ chatId, options })` | Настройки группы |
+| `resolveChannelByUsername(username)` | Канал по @ |
+| `joinChannelByUsername(username)` | Вступить по @ |
+| `resolveInviteHash(hash)` | Инвайт `join/...` |
+
+### Контакты и профиль
+
+| Метод | Описание |
+|-------|----------|
+| `getUser(userId)` | Один контакт → `User` |
+| `getContacts(contactIds)` | Несколько контактов (сырой ответ) |
+| `addContact(userId)` | В контакты |
+| `blockUser(userId)` | Блокировка |
+| `updateProfile({ firstName?, lastName?, description? })` | Профиль |
+| `setHiddenOnline(hidden)` | Скрыть онлайн |
+| `setFindableByPhone(mode)` | Поиск по телефону |
+| `setCallsPrivacyMode(mode)` | Звонки |
+| `setChatsInvitePrivacy(mode)` | Приглашения в чаты |
+
+### Обработчики событий
+
+| Метод | Событие |
+|-------|---------|
+| `onStart(handler)` | Успешный старт |
+| `onMessage(handler)` | Новое сообщение |
+| `onMessageRemoved(handler)` | Удалено сообщение |
+| `onChatAction(handler)` | Действие в чате |
+| `onError(handler)` | Ошибки |
+
+### Прочее
+
+| Метод | Описание |
+|-------|----------|
+| `logIncoming(label, payload)` | Ручной лог `[incoming:…]` |
+| `sendAndWait(opcode, payload, cmd?, timeout?)` | Низкоуровневый RPC |
+| `triggerHandlers(eventType, data?)` | Внутренний вызов обработчиков (редко нужен снаружи) |
+
+---
+
+## `Message`
+
+| Метод / свойство | Описание |
+|------------------|----------|
+| `id`, `cid`, `chatId`, `text`, `senderId`, `sender`, `attachments`, `rawData`, … | Поля |
+| `fetchSender()` | Подгрузить отправителя |
+| `getSenderName()` | Имя для лога |
+| `reply({ text, cid?, attachments?, quote? })` | Ответ в чат |
+| `edit({ text, … })` | Редактировать |
+| `delete()` | Удалить |
+| `forward(chatId)` | В `Message` вызывает `client.forwardMessage` — метод на клиенте может отсутствовать, проверьте версию |
+| `downloadAttachment(index?, options?)` | Скачать вложение по `baseUrl` во временный файл |
+| `toJSON()`, `toString()` | Сериализация |
+
+---
+
+## `ChatAction`
+
+| Свойство | Описание |
+|----------|----------|
+| `type`, `chatId`, `userId`, `user`, `timestamp`, `rawData` | Данные действия |
+| `toString()`, `toJSON()` | Представление |
+
+---
+
+## `User`
+
+Основные поля: `id`, `firstname`, `lastname`, `phone`, `avatar`, `fullname` (getter) и др. — см. `lib/entities/User.js`.
+
+---
+
+## Константы
+
+- **`EventTypes`**: `START`, `MESSAGE`, `MESSAGE_REMOVED`, `CHAT_ACTION`, `ERROR`, `DISCONNECT`
+- **`ChatActions`**: `TYPING`, `STICKER`, `FILE`, `RECORDING_VOICE`, `RECORDING_VIDEO`
+- **`MessageTypes`**: `TEXT`, `IMAGE`, `VIDEO`, `AUDIO`, `DOCUMENT`, `STICKER`
+
+---
+
+## Утилиты (не методы клиента)
+
+| Функция | Описание |
+|---------|----------|
+| `downloadUrlToTempFile(url, { dir?, filename?, extFallback? })` | HTTP → временный файл |
+| `extFromContentType`, `extFromAttachType` | Подбор расширения |
+| `resolveIncomingLogMode(options)` | Режим `logIncoming` из опций конструктора |
+| `printIncomingLog(label, payload)` | Печать JSON в консоль |
+
+---
+
+*Файл для быстрой навигации; при расхождении с кодом приоритет у реализации в `lib/`.*

package/index.js

@@ -13,6 +13,7 @@ const { Opcode, getOpcodeName } = require('./lib/opcodes');
 const { UserAgentPayload } = require('./lib/userAgent');
 const { downloadUrlToTempFile, extFromContentType, extFromAttachType } = require('./lib/downloadMedia');
 const { resolveIncomingLogMode, printIncomingLog } = require('./lib/incomingLog');
+const { parseQrTrackId } = require('./lib/qrWebLogin');
 
 module.exports = {
   WebMaxClient,
@@ -30,6 +31,7 @@ module.exports = {
   extFromContentType,
   extFromAttachType,
   resolveIncomingLogMode,
-  printIncomingLog
+  printIncomingLog,
+  parseQrTrackId
 };