webmaxsocket 1.1.3 → 1.1.4

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/lib/client.js

@@ -154,6 +154,9 @@ class WebMaxClient extends EventEmitter {
     this._wireIncomingLogListeners();
     /** client id локальных исходящих сообщений (int32, часто ждут валидацию на сервере) */
     this._clientSendCid = 1 + Math.floor(Math.random() * 0xfffff);
+    /** После HTTP POST видео/файла — ждём NOTIF_ATTACH */
+    this._uploadPendingVideo = new Map();
+    this._uploadPendingFile = new Map();
   }
 
   /**
@@ -939,6 +942,10 @@ class WebMaxClient extends EventEmitter {
           }
           break;
 
+        case Opcode.NOTIF_ATTACH:
+          this._handleNotifAttach(data.payload);
+          break;
+
         default:
           this.emit('raw_message', data);
       }
@@ -1006,7 +1013,11 @@ class WebMaxClient extends EventEmitter {
         case Opcode.PING:
           await this.sendPong();
           break;
-          
+
+        case Opcode.NOTIF_ATTACH:
+          this._handleNotifAttach(message.payload);
+          break;
+
         default:
           this.emit('raw_message', message);
       }
@@ -1192,6 +1203,73 @@ class WebMaxClient extends EventEmitter {
     return Number.isNaN(n) ? chatId : n;
   }
 
+  /**
+   * NOTIF_ATTACH (136): готовность вложения после загрузки видео/файла.
+   */
+  _handleNotifAttach(payload) {
+    if (!payload || typeof payload !== 'object') return;
+    const vid = payload.videoId;
+    if (vid != null) {
+      const k = String(vid);
+      const fn = this._uploadPendingVideo.get(k);
+      if (fn) {
+        this._uploadPendingVideo.delete(k);
+        fn();
+      }
+    }
+    const fid = payload.fileId;
+    if (fid != null) {
+      const k = String(fid);
+      const fn = this._uploadPendingFile.get(k);
+      if (fn) {
+        this._uploadPendingFile.delete(k);
+        fn();
+      }
+    }
+  }
+
+  /**
+   * @param {Map<string, function(): void>} map
+   */
+  _waitUploadNotif(map, id, label, timeoutMs = 120000) {
+    return new Promise((resolve, reject) => {
+      const k = String(id);
+      const t = setTimeout(() => {
+        map.delete(k);
+        reject(new Error(`Таймаут ожидания NOTIF_ATTACH (${label})`));
+      }, timeoutMs);
+      map.set(k, () => {
+        clearTimeout(t);
+        resolve();
+      });
+    });
+  }
+
+  async _postMultipartUpload(uploadUrl, buf, fname, mime) {
+    const { Blob } = require('buffer');
+    if (typeof fetch !== 'function') {
+      throw new Error('upload: нужен Node.js 18+ с глобальным fetch');
+    }
+    const form = new FormData();
+    form.append('file', new Blob([buf], { type: mime }), fname);
+    const res = await fetch(uploadUrl, {
+      method: 'POST',
+      body: form,
+      headers: {
+        Accept: '*/*',
+        'Accept-Language': 'ru-RU,ru;q=0.9',
+        Origin: 'https://web.max.ru',
+        Referer: 'https://web.max.ru/',
+        'User-Agent': this.userAgent.headerUserAgent || 'Mozilla/5.0'
+      }
+    });
+    if (!res.ok) {
+      const t = await res.text();
+      throw new Error(`HTTP загрузка: ${res.status} ${t.slice(0, 300)}`);
+    }
+    return res;
+  }
+
   /**
    * Отправка сообщения (с уведомлением)
    */
@@ -1242,18 +1320,218 @@ class WebMaxClient extends EventEmitter {
     return response.payload;
   }
 
+  /**
+   * Загрузка локального изображения на сервер Max; результат передать в `attachments` у sendMessage / reply.
+   * Схема: PHOTO_UPLOAD → UPLOAD_ATTACH_PREP → HTTP POST на выданный URL. Нужен Node 18+ (fetch, FormData).
+   *
+   * @param {number|string|bigint} chatId
+   * @param {string} filePath путь к файлу (.png, .jpg, …)
+   * @returns {Promise<{ _type: 'PHOTO', photoToken: string }>}
+   */
+  async uploadPhoto(chatId, filePath) {
+    const fsp = require('fs/promises');
+    const path = require('path');
+
+    const buf = await fsp.readFile(filePath);
+    const ext = path.extname(filePath).toLowerCase();
+    const mime =
+      ext === '.png'
+        ? 'image/png'
+        : ext === '.webp'
+          ? 'image/webp'
+          : ext === '.gif'
+            ? 'image/gif'
+            : 'image/jpeg';
+    const fname = path.basename(filePath) || 'image.jpg';
+
+    const r1 = await this.sendAndWait(Opcode.PHOTO_UPLOAD, { count: 1 });
+    const p1 = r1.payload;
+    if (p1 && p1.error) {
+      const e = new Error(
+        typeof p1.error === 'string' ? p1.error : JSON.stringify(p1.error)
+      );
+      e.rawPayload = p1;
+      throw e;
+    }
+    const uploadUrl = p1 && p1.url;
+    if (!uploadUrl) {
+      throw new Error('PHOTO_UPLOAD: нет url в ответе');
+    }
+
+    await this.sendAndWait(Opcode.UPLOAD_ATTACH_PREP, {
+      chatId: this._normalizeChatId(chatId),
+      type: 'PHOTO'
+    });
+
+    const res = await this._postMultipartUpload(uploadUrl, buf, fname, mime);
+    const obj = await res.json();
+    const photos = obj.photos;
+    let first;
+    if (Array.isArray(photos)) {
+      [first] = photos;
+    } else if (photos && typeof photos === 'object') {
+      first = Object.values(photos)[0];
+    }
+    const token = first && first.token;
+    if (!token) {
+      throw new Error(`PHOTO upload: неожиданный JSON: ${JSON.stringify(obj).slice(0, 400)}`);
+    }
+
+    return {
+      _type: 'PHOTO',
+      photoToken: token
+    };
+  }
+
+  /**
+   * Загрузка видео; результат для `attachments: [{ _type: 'VIDEO', videoId, token }]`.
+   * После HTTP POST ждёт NOTIF_ATTACH (opcode 136).
+   */
+  async uploadVideo(chatId, filePath) {
+    const fsp = require('fs/promises');
+    const path = require('path');
+
+    const buf = await fsp.readFile(filePath);
+    const ext = path.extname(filePath).toLowerCase();
+    const fname = path.basename(filePath) || 'video.mp4';
+    const mime =
+      ext === '.webm' ? 'video/webm' : ext === '.mov' ? 'video/quicktime' : 'video/mp4';
+
+    const r = await this.sendAndWait(Opcode.VIDEO_UPLOAD, { count: 1 });
+    const p = r.payload;
+    if (p && p.error) {
+      const e = new Error(
+        typeof p.error === 'string' ? p.error : JSON.stringify(p.error)
+      );
+      e.rawPayload = p;
+      throw e;
+    }
+    const info = p && p.info && p.info[0];
+    if (!info) {
+      throw new Error('VIDEO_UPLOAD: нет info в ответе');
+    }
+    const { url: uploadUrl, videoId, token } = info;
+    if (!uploadUrl || videoId == null || token == null) {
+      throw new Error('VIDEO_UPLOAD: нет url, videoId или token');
+    }
+
+    const waitReady = this._waitUploadNotif(this._uploadPendingVideo, videoId, 'VIDEO');
+
+    await this.sendAndWait(Opcode.UPLOAD_ATTACH_PREP, {
+      chatId: this._normalizeChatId(chatId),
+      type: 'VIDEO'
+    });
+
+    await this._postMultipartUpload(uploadUrl, buf, fname, mime);
+
+    await waitReady;
+
+    return { _type: 'VIDEO', videoId, token };
+  }
+
+  /**
+   * Загрузка произвольного файла (документ, архив, **аудио** и т.д.) для `attachments: [{ _type: 'FILE', fileId }]`.
+   * После HTTP POST ждёт NOTIF_ATTACH.
+   *
+   * @param {{ filename?: string, mimeType?: string }} [options]
+   */
+  async uploadFile(chatId, filePath, options = {}) {
+    const fsp = require('fs/promises');
+    const path = require('path');
+
+    const buf = await fsp.readFile(filePath);
+    const ext = path.extname(filePath).toLowerCase();
+    const fname = options.filename || path.basename(filePath) || 'file.bin';
+    const mime =
+      options.mimeType ||
+      this._mimeGuessForFile(ext);
+
+    const r = await this.sendAndWait(Opcode.FILE_UPLOAD, { count: 1 });
+    const p = r.payload;
+    if (p && p.error) {
+      const e = new Error(
+        typeof p.error === 'string' ? p.error : JSON.stringify(p.error)
+      );
+      e.rawPayload = p;
+      throw e;
+    }
+    const info = p && p.info && p.info[0];
+    if (!info) {
+      throw new Error('FILE_UPLOAD: нет info в ответе');
+    }
+    const { url: uploadUrl, fileId } = info;
+    if (!uploadUrl || fileId == null) {
+      throw new Error('FILE_UPLOAD: нет url или fileId');
+    }
+
+    const waitReady = this._waitUploadNotif(this._uploadPendingFile, fileId, 'FILE');
+
+    await this.sendAndWait(Opcode.UPLOAD_ATTACH_PREP, {
+      chatId: this._normalizeChatId(chatId),
+      type: 'FILE'
+    });
+
+    await this._postMultipartUpload(uploadUrl, buf, fname, mime);
+
+    await waitReady;
+
+    return { _type: 'FILE', fileId };
+  }
+
+  /**
+   * Загрузка аудио как файла (удобно для .mp3, .ogg, .m4a, .wav).
+   * Внутри вызывает uploadFile() с подходящим MIME.
+   */
+  async uploadAudio(chatId, filePath) {
+    const path = require('path');
+    const ext = path.extname(filePath).toLowerCase();
+    const mime =
+      ext === '.mp3'
+        ? 'audio/mpeg'
+        : ext === '.ogg' || ext === '.oga'
+          ? 'audio/ogg'
+          : ext === '.m4a' || ext === '.aac'
+            ? 'audio/mp4'
+            : ext === '.wav'
+              ? 'audio/wav'
+              : ext === '.flac'
+                ? 'audio/flac'
+                : 'audio/mpeg';
+    return this.uploadFile(chatId, filePath, { mimeType: mime });
+  }
+
+  _mimeGuessForFile(ext) {
+    const m = {
+      '.png': 'image/png',
+      '.jpg': 'image/jpeg',
+      '.jpeg': 'image/jpeg',
+      '.gif': 'image/gif',
+      '.webp': 'image/webp',
+      '.pdf': 'application/pdf',
+      '.zip': 'application/zip',
+      '.mp3': 'audio/mpeg',
+      '.ogg': 'audio/ogg',
+      '.m4a': 'audio/mp4',
+      '.wav': 'audio/wav',
+      '.flac': 'audio/flac',
+      '.mp4': 'video/mp4',
+      '.webm': 'video/webm'
+    };
+    return m[ext] || 'application/octet-stream';
+  }
+
   /**
    * Редактирование сообщения
    */
   async editMessage(options) {
-    const { messageId, chatId, text } = options;
+    const { messageId, chatId, text, attachments } = options;
 
     const payload = {
       chatId: chatId,
       messageId: messageId,
       text: text || '',
       elements: [],
-      attaches: []
+      attaches: Array.isArray(attachments) && attachments.length ? attachments : []
     };
 
     const response = await this.sendAndWait(Opcode.MSG_EDIT, payload);
@@ -1354,6 +1632,360 @@ class WebMaxClient extends EventEmitter {
     return messages.map(msg => new Message(msg, this));
   }
 
+  /**
+   * Закрепить сообщение в чате (CHAT_UPDATE).
+   */
+  async pinMessage({ chatId, messageId, notifyPin = false }) {
+    return await this.sendAndWait(Opcode.CHAT_UPDATE, {
+      chatId: this._normalizeChatId(chatId),
+      messageId: String(messageId),
+      notifyPin: !!notifyPin
+    });
+  }
+
+  /**
+   * Поставить реакцию-эмодзи на сообщение.
+   */
+  async setMessageReaction({ chatId, messageId, emoji }) {
+    return await this.sendAndWait(Opcode.MSG_REACTION, {
+      chatId: this._normalizeChatId(chatId),
+      messageId: String(messageId),
+      reaction: {
+        reactionType: 'EMOJI',
+        id: String(emoji)
+      }
+    });
+  }
+
+  /**
+   * Снять свою реакцию с сообщения.
+   */
+  async cancelMessageReaction({ chatId, messageId }) {
+    return await this.sendAndWait(Opcode.MSG_CANCEL_REACTION, {
+      chatId: this._normalizeChatId(chatId),
+      messageId: String(messageId)
+    });
+  }
+
+  /**
+   * Список реакций на сообщение.
+   */
+  async getMessageReactions({ chatId, messageId, count = 100 }) {
+    return await this.sendAndWait(Opcode.MSG_GET_REACTIONS, {
+      chatId: this._normalizeChatId(chatId),
+      messageId: String(messageId),
+      count
+    });
+  }
+
+  /**
+   * Информация о чатах по id (opcode 48).
+   */
+  async getChatInfo(chatIds) {
+    const ids = Array.isArray(chatIds) ? chatIds : [chatIds];
+    const response = await this.sendAndWait(Opcode.CHAT_INFO, { chatIds: ids });
+    return response.payload;
+  }
+
+  /**
+   * Разрешить ссылку: канал, инвайт join/…, URL max.ru (LINK_INFO).
+   */
+  async resolveLink(link) {
+    const response = await this.sendAndWait(Opcode.LINK_INFO, { link: String(link) });
+    return response.payload;
+  }
+
+  /**
+   * Вступить по ссылке (канал, группа и т.д.).
+   */
+  async joinChatByLink(link) {
+    const response = await this.sendAndWait(Opcode.CHAT_JOIN, { link: String(link) });
+    return response.payload;
+  }
+
+  /**
+   * Подписка / отписка на канал.
+   */
+  async setChatSubscription(chatId, subscribe) {
+    return await this.sendAndWait(Opcode.CHAT_SUBSCRIBE, {
+      chatId: this._normalizeChatId(chatId),
+      subscribe: !!subscribe
+    });
+  }
+
+  /**
+   * Создать групповой чат (CONTROL в MSG_SEND).
+   */
+  async createGroup({ title, userIds }) {
+    const cid = this._nextClientMessageId();
+    return await this.sendAndWait(Opcode.MSG_SEND, {
+      message: {
+        text: '',
+        cid,
+        elements: [],
+        attaches: [
+          {
+            _type: 'CONTROL',
+            event: 'new',
+            chatType: 'CHAT',
+            title,
+            userIds
+          }
+        ]
+      },
+      notify: true
+    });
+  }
+
+  /**
+   * Создать канал (CONTROL в MSG_SEND).
+   */
+  async createChannel({ title }) {
+    const cid = this._nextClientMessageId();
+    return await this.sendAndWait(Opcode.MSG_SEND, {
+      message: {
+        text: '',
+        cid,
+        elements: [],
+        attaches: [
+          {
+            _type: 'CONTROL',
+            event: 'new',
+            title,
+            chatType: 'CHANNEL'
+          }
+        ]
+      },
+      notify: true
+    });
+  }
+
+  /**
+   * Отключить уведомления в чате (CONFIG), как «не беспокоить» для чата.
+   */
+  async muteChat(chatId, mute = true) {
+    const id = String(this._normalizeChatId(chatId));
+    return await this.sendAndWait(Opcode.CONFIG, {
+      settings: {
+        chats: {
+          [id]: {
+            dontDisturbUntil: mute ? -1 : 0
+          }
+        }
+      }
+    });
+  }
+
+  /**
+   * Участники чата (не более 500 за запрос).
+   */
+  async getChatMembers({ chatId, marker = 0, count = 500, type = 'MEMBER' }) {
+    if (count > 500) {
+      throw new Error('getChatMembers: count не больше 500');
+    }
+    return await this.sendAndWait(Opcode.CHAT_MEMBERS, {
+      type,
+      marker,
+      chatId: this._normalizeChatId(chatId),
+      count
+    });
+  }
+
+  /**
+   * Пригласить пользователей в чат.
+   */
+  async inviteToChat({ chatId, userIds, showHistory = true }) {
+    return await this.sendAndWait(Opcode.CHAT_MEMBERS_UPDATE, {
+      chatId: this._normalizeChatId(chatId),
+      userIds,
+      showHistory,
+      operation: 'add'
+    });
+  }
+
+  /**
+   * Исключить пользователей из чата.
+   */
+  async removeFromChat({ chatId, userIds, cleanMsgPeriod = 0 }) {
+    return await this.sendAndWait(Opcode.CHAT_MEMBERS_UPDATE, {
+      chatId: this._normalizeChatId(chatId),
+      userIds,
+      operation: 'remove',
+      cleanMsgPeriod
+    });
+  }
+
+  /**
+   * Назначить администраторов. `permissions` — битовая маска прав (по умолчанию 120).
+   */
+  async addChatAdmins({ chatId, userIds, permissions = 120 }) {
+    return await this.sendAndWait(Opcode.CHAT_MEMBERS_UPDATE, {
+      chatId: this._normalizeChatId(chatId),
+      userIds,
+      type: 'ADMIN',
+      operation: 'add',
+      permissions
+    });
+  }
+
+  /**
+   * Снять права администратора.
+   */
+  async removeChatAdmins({ chatId, userIds }) {
+    return await this.sendAndWait(Opcode.CHAT_MEMBERS_UPDATE, {
+      chatId: this._normalizeChatId(chatId),
+      userIds,
+      type: 'ADMIN',
+      operation: 'remove'
+    });
+  }
+
+  /**
+   * Передать владение группой.
+   */
+  async transferChatOwnership({ chatId, newOwnerId }) {
+    return await this.sendAndWait(Opcode.CHAT_UPDATE, {
+      chatId: this._normalizeChatId(chatId),
+      changeOwnerId: newOwnerId
+    });
+  }
+
+  /**
+   * Настройки группы: например ONLY_OWNER_CAN_CHANGE_ICON_TITLE, ALL_CAN_PIN_MESSAGE, ONLY_ADMIN_CAN_ADD_MEMBER.
+   */
+  async setGroupOptions({ chatId, options }) {
+    return await this.sendAndWait(Opcode.CHAT_UPDATE, {
+      chatId: this._normalizeChatId(chatId),
+      options
+    });
+  }
+
+  /**
+   * Несколько контактов по id (сырой ответ CONTACT_INFO).
+   */
+  async getContacts(contactIds) {
+    const ids = Array.isArray(contactIds) ? contactIds : [contactIds];
+    const response = await this.sendAndWait(Opcode.CONTACT_INFO, { contactIds: ids });
+    return response.payload;
+  }
+
+  /**
+   * Добавить пользователя в контакты.
+   */
+  async addContact(userId) {
+    return await this.sendAndWait(Opcode.CONTACT_UPDATE, {
+      contactId: userId,
+      action: 'ADD'
+    });
+  }
+
+  /**
+   * Заблокировать пользователя.
+   */
+  async blockUser(userId) {
+    return await this.sendAndWait(Opcode.CONTACT_UPDATE, {
+      contactId: userId,
+      action: 'BLOCK'
+    });
+  }
+
+  /**
+   * Изменить своё имя / описание (PROFILE).
+   */
+  async updateProfile({ firstName, lastName, description } = {}) {
+    const payload = {};
+    if (firstName !== undefined) payload.firstName = firstName;
+    if (lastName !== undefined) payload.lastName = lastName;
+    if (description !== undefined) payload.description = description;
+    return await this.sendAndWait(Opcode.PROFILE, payload);
+  }
+
+  /**
+   * Скрыть статус «в сети» для других.
+   */
+  async setHiddenOnline(hidden) {
+    return await this.sendAndWait(Opcode.CONFIG, {
+      settings: {
+        user: { HIDDEN: !!hidden }
+      }
+    });
+  }
+
+  /**
+   * Кто может найти вас по телефону: 'ALL' | 'CONTACTS' или true/false (как ALL/CONTACTS).
+   */
+  async setFindableByPhone(mode) {
+    const v =
+      mode === true || mode === 'ALL'
+        ? 'ALL'
+        : mode === false || mode === 'CONTACTS'
+          ? 'CONTACTS'
+          : String(mode);
+    return await this.sendAndWait(Opcode.CONFIG, {
+      settings: {
+        user: { SEARCH_BY_PHONE: v }
+      }
+    });
+  }
+
+  /**
+   * Кто может звонить: 'ALL' | 'CONTACTS'.
+   */
+  async setCallsPrivacyMode(mode) {
+    const v =
+      mode === true || mode === 'ALL'
+        ? 'ALL'
+        : mode === false || mode === 'CONTACTS'
+          ? 'CONTACTS'
+          : String(mode);
+    return await this.sendAndWait(Opcode.CONFIG, {
+      settings: {
+        user: { INCOMING_CALL: v }
+      }
+    });
+  }
+
+  /**
+   * Кто может приглашать вас в чаты: 'ALL' | 'CONTACTS'.
+   */
+  async setChatsInvitePrivacy(mode) {
+    const v =
+      mode === true || mode === 'ALL'
+        ? 'ALL'
+        : mode === false || mode === 'CONTACTS'
+          ? 'CONTACTS'
+          : String(mode);
+    return await this.sendAndWait(Opcode.CONFIG, {
+      settings: {
+        user: { CHATS_INVITE: v }
+      }
+    });
+  }
+
+  /**
+   * Удобно: канал по @username (resolveLink на https://max.ru/username).
+   */
+  async resolveChannelByUsername(username) {
+    const u = String(username).replace(/^@/, '');
+    return this.resolveLink(`https://max.ru/${u}`);
+  }
+
+  /**
+   * Вступить в канал по @username.
+   */
+  async joinChannelByUsername(username) {
+    const u = String(username).replace(/^@/, '');
+    return this.joinChatByLink(`https://max.ru/${u}`);
+  }
+
+  /**
+   * Инвайт по хэшу из ссылки join/XXXX.
+   */
+  async resolveInviteHash(hash) {
+    const h = String(hash).replace(/^join\//, '');
+    return this.resolveLink(`join/${h}`);
+  }
+
   /**
    * Выполнение зарегистрированных обработчиков
    */

package/lib/opcodes.js

@@ -27,8 +27,11 @@ const Opcode = {
   CHAT_LEAVE: 58,
   CHAT_MEMBERS: 59,
   MSG_SEND: 64,
+  UPLOAD_ATTACH_PREP: 65,
   MSG_DELETE: 66,
   MSG_EDIT: 67,
+  /** Подписка / отписка на канал (subscribe: true|false) */
+  CHAT_SUBSCRIBE: 75,
   CHAT_MEMBERS_UPDATE: 77,
   PHOTO_UPLOAD: 80,
   VIDEO_UPLOAD: 82,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webmaxsocket",
-  "version": "1.1.3",
+  "version": "1.1.4",
   "description": "Node.js client for Max Messenger with QR code and token authentication",
   "main": "index.js",
   "scripts": {
@@ -58,7 +58,8 @@
     "example-token.js",
     "example-sms.js",
     "example-ios.js",
-    "README.md"
+    "README.md",
+    "api.package.md"
   ]
 }