webmaxsocket 1.1.0 → 1.1.2

package/README.md

@@ -7,14 +7,17 @@
 ## ✨ Особенности / Features
 
 - ✅ **QR-код авторизация** / QR code authentication  
+- ✅ **QR для привязки устройства** (`showLinkDeviceQR`) после входа по SMS/TCP — тот же сценарий, что «Профиль → Устройства → Подключить устройство» в приложении
 - ✅ **Token авторизация** / Token authentication
 - ✅ **Два транспорта:** WebSocket (WEB) и TCP Socket (IOS/ANDROID)
 - ✅ **Автоматическое сохранение сессий** / Automatic session storage
 - ✅ **Автовыбор транспорта** после QR-авторизации (переход на TCP)
 - ✅ **Отправка и получение сообщений** / Send and receive messages
+- ✅ **Скачивание вложений по URL** (`baseUrl` из `attaches`) во временный файл — `downloadUrlToTempFile`, `message.downloadAttachment()`
 - ✅ **Редактирование и удаление сообщений** / Edit and delete messages
 - ✅ **Event-driven архитектура** / Event-driven architecture
 - ✅ **Обработка входящих уведомлений** / Handle incoming notifications
+- ✅ **Встроенный лог входящих** (`logIncoming`, `WEBMAX_DEBUG`, `WEBMAX_SILENT`) — JSON в консоль без ручных обработчиков
 - ✅ **TypeScript-ready** структура / TypeScript-ready structure
 
 ## 📦 Установка / Installation
@@ -61,8 +64,7 @@ async function main() {
     
     // Автоответ / Auto-reply
     await message.reply({
-      text: `Привет! Я получил: "${message.text}"`,
-      cid: Date.now()
+      text: `Привет! Я получил: "${message.text}"`
     });
   });
 
@@ -83,8 +85,7 @@ main().catch(console.error);
 🔐 АВТОРИЗАЦИЯ ЧЕРЕЗ QR-КОД
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 
-📱 Откройте приложение Max на телефоне
-➡️  Настройки → Устройства → Подключить устройство
+📱 На телефоне: Профиль → Устройства / Безопасность → Подключить устройство
 📸 Отсканируйте QR-код
 
 █████████████████████████████
@@ -126,6 +127,29 @@ node example-sms.js
 node example-sms.js +79001234567  # с номером в аргументе
 ```
 
+#### QR после входа: привязка второго устройства (IOS/ANDROID)
+
+Когда вы уже авторизованы по **TCP** (SMS и сохранённая сессия), запрос **`GET_QR` на том же соединении недоступен** (ответ сервера: недопустимое состояние сессии). Для сценария как в приложении — **показать QR, телефон сканирует** — используйте метод **`showLinkDeviceQR()`**: библиотека открывает **отдельное краткоживущее WebSocket-подключение** (как у [web.max.ru](https://web.max.ru)), запрашивает QR, печатает его в консоль и при необходимости ждёт сканирования.
+
+Требования: активное соединение и **`isAuthorized`** (обычно после `await client.start()`).
+
+```javascript
+await client.start();
+
+// Показать QR и ждать, пока отсканируют в приложении Max на телефоне
+await client.showLinkDeviceQR();
+
+// Только показать QR и вернуть данные (без ожидания скана)
+const data = await client.showLinkDeviceQR({ waitForScan: false });
+// data: { qrLink, trackId, pollingInterval, expiresAt }
+```
+
+Опции: `waitForScan` (по умолчанию `true`), `small` — компактный QR в терминале.
+
+**Версия клиента:** для выдачи QR сервер ожидает актуальный **`appVersion`** в User-Agent (не ниже **25.12.13**). В конструкторе по умолчанию используется **25.12.14**; при необходимости передайте `appVersion: '25.21.3'` или новее.
+
+Если сервер отвечает **`qr_login.disabled`**, проверьте версию приложения в опциях, откройте [web.max.ru](https://web.max.ru) в браузере или войдите на втором устройстве по номеру телефона.
+
 #### Способ 3: Token авторизация
 
 Если у вас уже есть токен (от другого сервиса/приложения):
@@ -172,15 +196,39 @@ const client = new WebMaxClient({
   name: 'session',        // Имя сессии (для сохранения авторизации)
   token: 'An_Sx6H...',    // Токен авторизации (опционально)
   configPath: 'myconfig', // Путь к config файлу (опционально)
-  deviceType: 'WEB',      // Тип устройства: 'WEB', 'IOS', 'ANDROID' (опционально)
+  deviceType: 'WEB',      // Тип устройства: 'WEB', 'IOS', 'ANDROID', 'DESKTOP' (опционально)
   saveToken: true,        // Сохранять токен в сессию (по умолчанию true)
-  debug: false,           // Отладочный режим (опционально)
+  debug: false,           // TCP/WebSocket: краткий лог opcode; также учитывается WEBMAX_DEBUG=1, DEBUG=1
+  // Лог входящих (JSON в консоль), см. ниже:
+  logIncoming: undefined, // false | 'messages' | 'verbose' — по умолчанию см. таблицу
+  logIncomingVerbose: false, // явно включить verbose (как logIncoming: 'verbose')
   apiUrl: 'wss://...',    // URL WebSocket API (опционально)
   maxReconnectAttempts: 5,// Максимальное количество попыток переподключения
-  reconnectDelay: 3000    // Задержка между попытками переподключения (мс)
+  reconnectDelay: 3000,   // Задержка между попытками переподключения (мс)
+  // User-Agent / клиент (важно для GET_QR, см. showLinkDeviceQR):
+  appVersion: '25.12.14', // Рекомендуется ≥ 25.12.13 для запроса QR
+  ua: 'Mozilla/5.0 ...', // или headerUserAgent
+  osVersion: 'Windows 11',
+  screen: '1920x1080 1.0x',
+  timezone: 'Europe/Moscow',
+  locale: 'ru',
+  buildNumber: 0x97cb,    // опционально
+  clientSessionId: 1      // опционально
 });
 ```
 
+**Лог входящих (`logIncoming`):** печать блоков `📥 [incoming:…]` с JSON.
+
+| Значение / условие | Поведение |
+|--------------------|-----------|
+| `logIncoming: false` | Выкл. |
+| `logIncoming: 'messages'` | Только входящие сообщения (`message.rawData`). |
+| `logIncoming: 'verbose'` или `logIncomingVerbose: true` | Сообщения + `connected`, `raw_message`, `message_removed`, `chat_action`, `error`. |
+| не указано | По умолчанию: как `'messages'`; если **`WEBMAX_DEBUG=1`** — как `'verbose'`. Явное **`logIncoming: 'messages'`** отключает расширенный режим даже при `WEBMAX_DEBUG`. |
+| **`WEBMAX_SILENT=1`** | Выкл. всех дампов. |
+
+Ручной вывод в том же формате: `client.logIncoming('my_label', data)`. Текущий режим: `client.incomingLogMode` (`'off' \| 'messages' \| 'verbose'`). Низкоуровнево: `resolveIncomingLogMode(options)`, `printIncomingLog(label, payload)` из пакета.
+
 #### Методы
 
 ##### `start()`
@@ -206,6 +254,24 @@ const authSession = await client.authorizeBySMS('+79001234567');
 await authSession.sendCode('123456');
 ```
 
+##### `showLinkDeviceQR(options)`
+
+Показать в консоли **QR-код для привязки устройства** (как в приложении Max: телефон сканирует QR). Нужна **уже выполненная авторизация** (`start()` или `connect` + `sync`).
+
+- Для **WEB** запрос выполняется по текущему WebSocket.
+- Для **IOS/ANDROID** после входа по TCP используется **второе** WebSocket-подключение без повторного `LOGIN` на той сессии (иначе `GET_QR` на том же TCP недоступен).
+
+```javascript
+await client.showLinkDeviceQR();
+await client.showLinkDeviceQR({ waitForScan: false, small: false });
+```
+
+Возвращает `Promise<{ qrLink, trackId, pollingInterval, expiresAt }>`.
+
+##### `requestQR()`, `checkQRStatus(trackId)`, `loginByQR(trackId)`, `authorizeByQR()`
+
+Низкоуровневые шаги QR-авторизации для **WEB** (первый вход без SMS). Обычно достаточно `start()` без токена или `authorizeByQR()`.
+
 ##### `sendMessage(options)`
 
 Отправляет сообщение в чат с уведомлением (notify: true).
@@ -214,7 +280,7 @@ await authSession.sendCode('123456');
 const message = await client.sendMessage({
   chatId: 123,
   text: 'Привет!',
-  cid: Date.now(),
+  // cid опционально; на TCP не используйте Date.now() (нужен int32)
   replyTo: null,        // ID сообщения для ответа (опционально)
   attachments: []       // Вложения (опционально)
 });
@@ -228,7 +294,6 @@ const message = await client.sendMessage({
 const message = await client.sendMessageChannel({
   chatId: 123,
   text: 'Сообщение в канал',
-  cid: Date.now(),
   replyTo: null,        // ID сообщения для ответа (опционально)
   attachments: []       // Вложения (опционально)
 });
@@ -391,13 +456,11 @@ client.onError(async (error) => {
 
 ##### `reply(options)`
 
-Отвечает на сообщение.
+Отправляет текст **в тот же чат**. По умолчанию **без** цитаты исходного сообщения (`link REPLY`), т.к. на TCP-сокете сервер часто возвращает «Ошибка валидации» для ответа-цитаты. Чтобы попробовать ответ с цитатой: `{ text: '...', quote: true }`.
 
 ```javascript
-await message.reply({
-  text: 'Ответ на сообщение',
-  cid: Date.now()
-});
+await message.reply({ text: 'Ответ на сообщение' });
+await message.reply({ text: '...', quote: true });
 ```
 
 ##### `edit(options)`
@@ -426,6 +489,59 @@ await message.delete();
 await message.forward(789);
 ```
 
+##### `downloadAttachment(index, options?)`
+
+Скачивает вложение по полю **`baseUrl`** (или `url`) из `message.attachments[index]` в **временный файл**. По умолчанию каталог — `os.tmpdir()` (на Windows обычно `%TEMP%`). Имя файла генерируется автоматически; расширение берётся из заголовка `Content-Type`, при необходимости — из типа вложения (`_type`, например `PHOTO`).
+
+Возвращает `{ path, contentType }`.
+
+```javascript
+if (message.attachments.length) {
+  const { path, contentType } = await message.downloadAttachment(0);
+  console.log('Сохранено:', path, contentType);
+  // после обработки можно удалить: fs.unlinkSync(path)
+}
+
+// Свой каталог или имя файла:
+await message.downloadAttachment(0, {
+  dir: './downloads',
+  filename: 'photo.webp'
+});
+```
+
+### Утилиты скачивания медиа / Media download helpers
+
+Экспортируются из пакета наряду с `WebMaxClient`:
+
+```javascript
+const {
+  downloadUrlToTempFile,
+  extFromContentType,
+  extFromAttachType
+} = require('webmaxsocket');
+```
+
+##### `downloadUrlToTempFile(url, options?)`
+
+HTTP(S)-запрос с следованием редиректам, запись тела ответа в файл.
+
+| Опция | Описание |
+|--------|----------|
+| `dir` | Каталог (по умолчанию `os.tmpdir()`) |
+| `filename` | Имя файла (только basename); если не задано — `max-media-<time>-<random>.<ext>` |
+| `extFallback` | Расширение, если по `Content-Type` определить не удалось (например `'.jpg'`) |
+
+```javascript
+const { path, contentType } = await downloadUrlToTempFile(
+  'https://i.oneme.ru/i?r=...',
+  { extFallback: '.jpg' }
+);
+```
+
+##### `extFromContentType(contentType)` / `extFromAttachType(attachType)`
+
+Вспомогательные функции для подбора расширения по MIME или по `_type` вложения (`PHOTO`, `VIDEO`, …).
+
 ### User
 
 Класс, представляющий пользователя.
@@ -532,6 +648,10 @@ node example-ios.js
 node example-ios.js --debug
 ```
 
+### Пример 5: QR для второго устройства после SMS
+
+После успешного `start()` с сохранённой сессией IOS/Android вызовите `showLinkDeviceQR()` (см. раздел **«QR после входа»** выше).
+
 ## Структура проекта
 
 ```
@@ -543,6 +663,8 @@ webmaxsocket/
 │   ├── userAgent.js        # UserAgent генератор
 │   ├── opcodes.js          # Протокол опкоды
 │   ├── constants.js        # Константы
+│   ├── downloadMedia.js    # Скачивание медиа по URL во временный файл
+│   ├── incomingLog.js      # Режим logIncoming / печать входящих
 │   └── entities/
 │       ├── User.js         # Класс пользователя
 │       ├── Message.js      # Класс сообщения
@@ -580,8 +702,7 @@ const client2 = new WebMaxClient({ name: 'account1' }); // phone не требу
 try {
   const message = await client.sendMessage({
     chatId: 123,
-    text: 'Привет!',
-    cid: Date.now()
+    text: 'Привет!'
   });
 } catch (error) {
   console.error('Ошибка:', error.message);
@@ -609,11 +730,17 @@ DEBUG=1 node example.js
 
 1. **TCP Socket после QR-авторизации:** После первой успешной QR-авторизации клиент автоматически сохраняет `clientSessionId` и переключается на TCP Socket транспорт при следующем запуске для повышения стабильности.
 
-2. **Разница между sendMessage и sendMessageChannel:**
+2. **QR для нового устройства после входа по SMS/TCP:** Используйте `showLinkDeviceQR()`. Это не отдельный опкод в протоколе, а тот же `GET_QR`, что и у веб-клиента; для уже залогиненного TCP-сокета запрос выполняется через **эфемерное WebSocket-подключение** (временный файл сессии `_link_qr_*` удаляется после завершения).
+
+3. **Версия `appVersion` и QR:** Слишком старая версия в User-Agent может привести к ответу `qr_login.disabled` на `GET_QR`. Задайте в конструкторе актуальную строку (по умолчанию **25.12.14**).
+
+4. **Разница между sendMessage и sendMessageChannel:**
    - `sendMessage()` - отправка с уведомлением (notify: true) для обычных чатов
    - `sendMessageChannel()` - отправка без уведомления (notify: false) для каналов
 
-3. **Автоматический выбор транспорта:** Клиент автоматически определяет какой транспорт использовать на основе `deviceType` в сессии или config файле.
+5. **Автоматический выбор транспорта:** Клиент автоматически определяет какой транспорт использовать на основе `deviceType` в сессии или config файле.
+
+6. **`cid` при отправке сообщений (TCP/Socket):** сервер проверяет **signed int32**. Не передавайте `Date.now()` (миллисекунды ~1e12) — будет «Ошибка валидации». Либо не указывайте `cid` (клиент подставит свой), либо передайте целое в диапазоне **−2³¹ … 2³¹−1**.
 
 ## 🔗 Ссылки / Links
 

package/index.js

@@ -11,6 +11,8 @@ const { User, Message, ChatAction } = require('./lib/entities');
 const { ChatActions, EventTypes, MessageTypes } = require('./lib/constants');
 const { Opcode, getOpcodeName } = require('./lib/opcodes');
 const { UserAgentPayload } = require('./lib/userAgent');
+const { downloadUrlToTempFile, extFromContentType, extFromAttachType } = require('./lib/downloadMedia');
+const { resolveIncomingLogMode, printIncomingLog } = require('./lib/incomingLog');
 
 module.exports = {
   WebMaxClient,
@@ -23,6 +25,11 @@ module.exports = {
   MessageTypes,
   Opcode,
   getOpcodeName,
-  UserAgentPayload
+  UserAgentPayload,
+  downloadUrlToTempFile,
+  extFromContentType,
+  extFromAttachType,
+  resolveIncomingLogMode,
+  printIncomingLog
 };
 

package/lib/client.js

@@ -10,6 +10,7 @@ const { Message, ChatAction, User } = require('./entities');
 const { EventTypes, ChatActions } = require('./constants');
 const { Opcode, DeviceType, getOpcodeName } = require('./opcodes');
 const { UserAgentPayload } = require('./userAgent');
+const { resolveIncomingLogMode, printIncomingLog } = require('./incomingLog');
 
 /**
  * Загружает конфиг: { token, agent }
@@ -30,6 +31,30 @@ function loadSessionConfig(configPath) {
   return JSON.parse(data);
 }
 
+/**
+ * Понятная ошибка при отказе сервера отдать QR (часто qr_login.disabled для неофициального WEB-handshake).
+ */
+function throwIfGetQRRejected(payload) {
+  if (!payload || !payload.error) {
+    return;
+  }
+  const err = payload.error;
+  const text =
+    typeof err === 'string'
+      ? err
+      : err && typeof err.message === 'string'
+        ? err.message
+        : JSON.stringify(err);
+  if (String(text).includes('qr_login.disabled')) {
+    throw new Error(
+      'Сервер Max отказал в выдаче QR (qr_login.disabled). Частые причины: устаревший appVersion в User-Agent (нужно ≥ 25.12.13), ' +
+      'или отключение QR для данного клиента на стороне VK. Проверьте https://web.max.ru в браузере. ' +
+      'Второй телефон к аккаунту можно добавить и обычным входом по номеру в приложении Max.'
+    );
+  }
+  throw new Error(`QR request error: ${text}`);
+}
+
 /**
  * Основной клиент для работы с API Max
  */
@@ -63,17 +88,27 @@ class WebMaxClient extends EventEmitter {
     const uaString = agent || configObj.headerUserAgent || configObj.ua || 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36';
     const webDefaults = {
       deviceType: deviceType,
-      locale: configObj.locale || 'ru',
-      deviceLocale: configObj.deviceLocale || configObj.locale || 'ru',
-      osVersion: configObj.osVersion || (deviceType === 'IOS' ? '18.6.2' : deviceType === 'ANDROID' ? '14' : 'Linux'),
-      deviceName: configObj.deviceName || (deviceType === 'IOS' ? 'Safari' : deviceType === 'ANDROID' ? 'Chrome' : 'Chrome'),
-      headerUserAgent: uaString,
-      appVersion: configObj.appVersion || '25.10.5',
-      screen: configObj.screen || (deviceType === 'IOS' ? '390x844 3.0x' : deviceType === 'ANDROID' ? '360x780 3.0x' : '1080x1920 1.0x'),
-      timezone: configObj.timezone || 'Europe/Moscow',
-      buildNumber: configObj.buildNumber,
-      clientSessionId: configObj.clientSessionId || this.session.get('clientSessionId'),
-      release: configObj.release
+      locale: options.locale || configObj.locale || 'ru',
+      deviceLocale: options.deviceLocale || configObj.deviceLocale || configObj.locale || 'ru',
+      osVersion:
+        options.osVersion ||
+        configObj.osVersion ||
+        (deviceType === 'IOS' ? '18.6.2' : deviceType === 'ANDROID' ? '14' : 'Windows 11'),
+      deviceName:
+        options.deviceName ||
+        configObj.deviceName ||
+        (deviceType === 'IOS' ? 'Safari' : deviceType === 'ANDROID' ? 'Chrome' : 'Chrome'),
+      headerUserAgent: options.headerUserAgent || options.ua || uaString,
+      // Ниже 25.12.13 сервер может отвечать qr_login.disabled на GET_QR (см. PyMax _login).
+      appVersion: options.appVersion || configObj.appVersion || '25.12.14',
+      screen:
+        options.screen ||
+        configObj.screen ||
+        (deviceType === 'IOS' ? '390x844 3.0x' : deviceType === 'ANDROID' ? '360x780 3.0x' : '1080x1920 1.0x'),
+      timezone: options.timezone || configObj.timezone || 'Europe/Moscow',
+      buildNumber: options.buildNumber ?? configObj.buildNumber,
+      clientSessionId: options.clientSessionId ?? configObj.clientSessionId ?? this.session.get('clientSessionId'),
+      release: options.release ?? configObj.release
     };
     this._handshakeUserAgent = new UserAgentPayload(webDefaults);
     this.userAgent = this._handshakeUserAgent;
@@ -110,7 +145,39 @@ class WebMaxClient extends EventEmitter {
 
     this.messageQueue = [];
     this.pendingRequests = new Map();
-    this.debug = options.debug || process.env.DEBUG === '1';
+    this.debug =
+      Boolean(options.debug) ||
+      process.env.DEBUG === '1' ||
+      process.env.WEBMAX_DEBUG === '1';
+    /** Режим JSON-лога входящих: off | messages | verbose (см. logIncoming в README) */
+    this._incomingLogMode = resolveIncomingLogMode(options);
+    this._wireIncomingLogListeners();
+    /** client id локальных исходящих сообщений (int32, часто ждут валидацию на сервере) */
+    this._clientSendCid = 1 + Math.floor(Math.random() * 0xfffff);
+  }
+
+  /**
+   * Текущий режим лога входящих: `off` | `messages` | `verbose`.
+   */
+  get incomingLogMode() {
+    return this._incomingLogMode;
+  }
+
+  /**
+   * Ручной вывод в формате `[incoming:label]` (как внутренний лог).
+   */
+  logIncoming(label, payload) {
+    printIncomingLog(label, payload);
+  }
+
+  _wireIncomingLogListeners() {
+    if (this._incomingLogMode !== 'verbose') return;
+    this.once('connected', () => {
+      printIncomingLog('connected', { event: 'connected' });
+    });
+    this.on('raw_message', (data) => {
+      printIncomingLog('raw_message', data);
+    });
   }
 
   /**
@@ -247,11 +314,9 @@ class WebMaxClient extends EventEmitter {
     console.log('Запрос QR-кода для авторизации...');
     
     const response = await this.sendAndWait(Opcode.GET_QR, {});
-    
-    if (response.payload && response.payload.error) {
-      throw new Error(`QR request error: ${JSON.stringify(response.payload.error)}`);
-    }
-    
+
+    throwIfGetQRRejected(response.payload);
+
     return response.payload;
   }
 
@@ -315,6 +380,127 @@ class WebMaxClient extends EventEmitter {
     }
   }
 
+  /**
+   * Вывести в консоль QR-код для привязки нового устройства (тот же поток, что и веб-вход).
+   * Требуется уже авторизованная сессия (после SMS/QR и sync).
+   * На телефоне: Профиль → Устройства / Безопасность → Подключить устройство (QR).
+   *
+   * @param {object} [options]
+   * @param {boolean} [options.waitForScan=true] — ждать, пока QR отсканируют
+   * @param {boolean} [options.small=true] — компактный QR в терминале
+   * @returns {Promise<{ qrLink: string, trackId: string, pollingInterval: number, expiresAt: number }>}
+   */
+  async showLinkDeviceQR(options = {}) {
+    const { waitForScan = true, small = true } = options;
+
+    if (!this.isConnected) {
+      throw new Error('Нет соединения: сначала await client.connect()');
+    }
+    if (!this.isAuthorized) {
+      throw new Error('Нужна авторизация: войдите в аккаунт и выполните sync, затем вызывайте showLinkDeviceQR');
+    }
+
+    // После LOGIN по TCP сервер не принимает GET_QR («Недопустимое состояние сессии») — тот же QR, что в веб-клиенте, только до авторизации по WebSocket.
+    if (this._useSocketTransport) {
+      return await this._showLinkDeviceQRViaEphemeralWeb(options);
+    }
+
+    console.log('Запрос QR-кода для привязки устройства...');
+    const response = await this.sendAndWait(Opcode.GET_QR, {});
+
+    throwIfGetQRRejected(response.payload);
+
+    const qrData = response.payload;
+    if (!qrData.qrLink || !qrData.trackId || !qrData.pollingInterval || !qrData.expiresAt) {
+      throw new Error('Неполные данные QR-кода от сервера');
+    }
+
+    await this._printLinkDeviceQRConsole(qrData.qrLink, small);
+    console.log('\n💡 Или откройте ссылку: ' + qrData.qrLink);
+    console.log('='.repeat(70) + '\n');
+
+    if (waitForScan) {
+      await this.pollQRStatus(qrData.trackId, qrData.pollingInterval, qrData.expiresAt);
+      console.log('\n✅ Устройство подключено. Проверьте вход на телефоне.');
+    }
+
+    return {
+      qrLink: qrData.qrLink,
+      trackId: qrData.trackId,
+      pollingInterval: qrData.pollingInterval,
+      expiresAt: qrData.expiresAt
+    };
+  }
+
+  _printLinkDeviceQRConsole(qrLink, small = true) {
+    console.log('\n' + '='.repeat(70));
+    console.log('📱 ПРИВЯЗКА НОВОГО УСТРОЙСТВА');
+    console.log('='.repeat(70));
+    console.log('\nНа телефоне откройте Max — как при добавлении устройства в приложении:');
+    console.log('➡️  Профиль → Устройства / Безопасность → Подключить устройство (вход по QR)');
+    console.log('📸 Наведите камеру на QR ниже — это тот же поток, что у веб-клиента:\n');
+    return new Promise((resolve) => {
+      qrcode.generate(qrLink, { small }, (qrCode) => {
+        console.log(qrCode);
+        resolve();
+      });
+    });
+  }
+
+  /**
+   * QR для привязки устройства при основой сессии на TCP (IOS/ANDROID): кратковременный WEB-клиент без LOGIN.
+   */
+  async _showLinkDeviceQRViaEphemeralWeb(options = {}) {
+    const { waitForScan = true, small = true } = options;
+    const ephemeralName = `_link_qr_${uuidv4().replace(/-/g, '').slice(0, 12)}`;
+    const webQr = new this.constructor({
+      name: ephemeralName,
+      deviceType: 'WEB',
+      debug: this.debug,
+      apiUrl: this.apiUrl,
+      origin: this.origin,
+      maxReconnectAttempts: 0
+    });
+
+    try {
+      console.log(
+        'Отдельное WebSocket-подключение (как у web.max.ru): на уже залогиненном TCP запрос QR другим способом недоступен.'
+      );
+      await webQr.connect();
+
+      const response = await webQr.sendAndWait(Opcode.GET_QR, {});
+      throwIfGetQRRejected(response.payload);
+
+      const qrData = response.payload;
+      if (!qrData.qrLink || !qrData.trackId || !qrData.pollingInterval || !qrData.expiresAt) {
+        throw new Error('Неполные данные QR-кода от сервера');
+      }
+
+      await this._printLinkDeviceQRConsole(qrData.qrLink, small);
+
+      console.log('\n💡 Или откройте ссылку: ' + qrData.qrLink);
+      console.log('='.repeat(70) + '\n');
+
+      if (waitForScan) {
+        await webQr.pollQRStatus(qrData.trackId, qrData.pollingInterval, qrData.expiresAt);
+        await webQr.loginByQR(qrData.trackId);
+        console.log('\n✅ Устройство подключено. Проверьте телефон.');
+      }
+
+      return {
+        qrLink: qrData.qrLink,
+        trackId: qrData.trackId,
+        pollingInterval: qrData.pollingInterval,
+        expiresAt: qrData.expiresAt
+      };
+    } finally {
+      try {
+        await webQr.stop();
+        webQr.session.destroy();
+      } catch (_) {}
+    }
+  }
+
   /**
    * Авторизация через QR-код
    */
@@ -331,13 +517,15 @@ class WebMaxClient extends EventEmitter {
       console.log('\n' + '='.repeat(70));
       console.log('🔐 АВТОРИЗАЦИЯ ЧЕРЕЗ QR-КОД');
       console.log('='.repeat(70));
-      console.log('\n📱 Откройте приложение Max на телефоне');
-      console.log('➡️  Настройки → Устройства → Подключить устройство');
+      console.log('\n📱 На телефоне: Профиль → Устройства / Безопасность → Подключить устройство');
       console.log('📸 Отсканируйте QR-код ниже:\n');
       
-      // Отображаем QR-код в консоли
-      qrcode.generate(qrData.qrLink, { small: true }, (qrCode) => {
-        console.log(qrCode);
+      // Отображаем QR-код в консоли (ждём вывод, затем опрос статуса)
+      await new Promise((resolve) => {
+        qrcode.generate(qrData.qrLink, { small: true }, (qrCode) => {
+          console.log(qrCode);
+          resolve();
+        });
       });
       
       console.log('\n💡 Или откройте ссылку: ' + qrData.qrLink);
@@ -846,12 +1034,16 @@ class WebMaxClient extends EventEmitter {
     }
     
     const message = new Message(messageData, this);
-    
+
+    if (this._incomingLogMode === 'messages' || this._incomingLogMode === 'verbose') {
+      printIncomingLog('message', message.rawData);
+    }
+
     // Попытка загрузить информацию об отправителе если её нет
     if (!message.sender && message.senderId && message.senderId !== this.me?.id) {
       await message.fetchSender();
     }
-    
+
     await this.triggerHandlers(EventTypes.MESSAGE, message);
   }
 
@@ -860,6 +1052,9 @@ class WebMaxClient extends EventEmitter {
    */
   async handleRemovedMessage(data) {
     const message = new Message(data, this);
+    if (this._incomingLogMode === 'verbose') {
+      printIncomingLog('message_removed', message.rawData);
+    }
     await this.triggerHandlers(EventTypes.MESSAGE_REMOVED, message);
   }
 
@@ -868,6 +1063,9 @@ class WebMaxClient extends EventEmitter {
    */
   async handleChatAction(data) {
     const action = new ChatAction(data, this);
+    if (this._incomingLogMode === 'verbose') {
+      printIncomingLog('chat_action', action.rawData);
+    }
     await this.triggerHandlers(EventTypes.CHAT_ACTION, action);
   }
 
@@ -919,6 +1117,73 @@ class WebMaxClient extends EventEmitter {
     });
   }
 
+  _nextClientMessageId() {
+    const n = this._clientSendCid;
+    this._clientSendCid = (this._clientSendCid % 0x7fffffff) + 1;
+    return n;
+  }
+
+  /** int32: Date.now() и большие числа ломают валидацию MSG_SEND на TCP */
+  _normalizeOutgoingCid(cid) {
+    if (cid == null || cid === '') return this._nextClientMessageId();
+    const n = Number(cid);
+    if (!Number.isFinite(n)) return this._nextClientMessageId();
+    const x = Math.trunc(n);
+    if (x > 2147483647 || x < -2147483648) {
+      return this._nextClientMessageId();
+    }
+    return x;
+  }
+
+  /**
+   * messageId для REPLY: int, если безопасно, иначе строка (длинные id).
+   */
+  _normalizeReplyMessageId(replyTo) {
+    if (replyTo == null || replyTo === '') return null;
+    if (typeof replyTo === 'number' && Number.isFinite(replyTo)) return replyTo;
+    if (typeof replyTo === 'bigint') return Number(replyTo);
+    if (typeof replyTo === 'string' && /^-?\d+$/.test(replyTo)) {
+      const n = Number(replyTo);
+      if (Number.isSafeInteger(n)) return n;
+      return replyTo;
+    }
+    return String(replyTo);
+  }
+
+  /**
+   * Собирает тело message для MSG_SEND: без link: null; cid в int32; elements для текста.
+   */
+  _buildOutgoingMessageBody(text, cid, replyTo, attachments) {
+    const t = text == null ? '' : String(text);
+    const cidVal = this._normalizeOutgoingCid(cid);
+
+    const body = {
+      text: t,
+      cid: cidVal,
+      elements: []
+    };
+
+    const att = attachments || [];
+    if (att.length) {
+      body.attaches = att;
+    }
+
+    if (replyTo != null && replyTo !== '') {
+      body.link = {
+        type: 'REPLY',
+        messageId: this._normalizeReplyMessageId(replyTo)
+      };
+    }
+    return body;
+  }
+
+  _normalizeChatId(chatId) {
+    if (chatId == null) return chatId;
+    if (typeof chatId === 'bigint') return Number(chatId);
+    const n = Number(chatId);
+    return Number.isNaN(n) ? chatId : n;
+  }
+
   /**
    * Отправка сообщения (с уведомлением)
    */
@@ -930,14 +1195,8 @@ class WebMaxClient extends EventEmitter {
     const { chatId, text, cid, replyTo, attachments } = options;
 
     const payload = {
-      chatId: chatId,
-      message: {
-        text: text || '',
-        cid: cid || Date.now(),
-        elements: [],
-        attaches: attachments || [],
-        link: replyTo ? { type: 'REPLY', messageId: replyTo } : null
-      },
+      chatId: this._normalizeChatId(chatId),
+      message: this._buildOutgoingMessageBody(text, cid, replyTo, attachments),
       notify: true
     };
 
@@ -961,14 +1220,8 @@ class WebMaxClient extends EventEmitter {
     const { chatId, text, cid, replyTo, attachments } = options;
 
     const payload = {
-      chatId: chatId,
-      message: {
-        text: text || '',
-        cid: cid || Date.now(),
-        elements: [],
-        attaches: attachments || [],
-        link: replyTo ? { type: 'REPLY', messageId: replyTo } : null
-      },
+      chatId: this._normalizeChatId(chatId),
+      message: this._buildOutgoingMessageBody(text, cid, replyTo, attachments),
       notify: false
     };
 
@@ -1097,8 +1350,19 @@ class WebMaxClient extends EventEmitter {
    * Выполнение зарегистрированных обработчиков
    */
   async triggerHandlers(eventType, data = null) {
+    if (
+      eventType === EventTypes.ERROR &&
+      data !== null &&
+      this._incomingLogMode === 'verbose'
+    ) {
+      printIncomingLog('error', {
+        message: data && data.message,
+        stack: data && data.stack
+      });
+    }
+
     const handlers = this.handlers[eventType] || [];
-    
+
     for (const handler of handlers) {
       try {
         if (data !== null) {

package/lib/downloadMedia.js

@@ -0,0 +1,124 @@
+/**
+ * Скачивание медиа по публичному URL (например baseUrl из attaches) во временный файл.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const https = require('https');
+const http = require('http');
+const { pipeline } = require('stream/promises');
+
+const UA = 'Mozilla/5.0 (compatible; WebMaxSocket/1.1)';
+
+const CONTENT_TYPE_EXT = {
+  'image/jpeg': '.jpg',
+  'image/jpg': '.jpg',
+  'image/png': '.png',
+  'image/webp': '.webp',
+  'image/gif': '.gif',
+  'video/mp4': '.mp4',
+  'video/webm': '.webm',
+  'application/octet-stream': '.bin'
+};
+
+function extFromContentType(ct) {
+  if (!ct) return '';
+  const main = String(ct).split(';')[0].trim().toLowerCase();
+  return CONTENT_TYPE_EXT[main] || '';
+}
+
+function extFromAttachType(t) {
+  if (!t) return '';
+  const u = String(t).toUpperCase();
+  if (u === 'PHOTO' || u === 'IMAGE') return '.jpg';
+  if (u === 'VIDEO') return '.mp4';
+  if (u === 'VOICE' || u === 'AUDIO') return '.ogg';
+  if (u === 'FILE') return '.bin';
+  return '';
+}
+
+/**
+ * @param {string} urlString
+ * @param {number} maxRedirects
+ * @returns {Promise<import('http').IncomingMessage>}
+ */
+async function getFinalResponse(urlString, maxRedirects = 10) {
+  let url = String(urlString);
+  for (let i = 0; i < maxRedirects; i++) {
+    const res = await new Promise((resolve, reject) => {
+      const lib = url.startsWith('https') ? https : http;
+      const req = lib.request(
+        url,
+        { method: 'GET', headers: { 'User-Agent': UA } },
+        resolve
+      );
+      req.on('error', reject);
+      req.end();
+    });
+
+    if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+      res.resume();
+      url = new URL(res.headers.location, url).href;
+      continue;
+    }
+
+    if (res.statusCode !== 200) {
+      res.resume();
+      const err = new Error(`HTTP ${res.statusCode}`);
+      err.statusCode = res.statusCode;
+      throw err;
+    }
+
+    return res;
+  }
+  throw new Error('Too many redirects');
+}
+
+/**
+ * Скачивает URL во временный файл (по умолчанию каталог ОС: os.tmpdir()).
+ *
+ * @param {string} url
+ * @param {{ dir?: string, filename?: string, extFallback?: string }} [options]
+ * @returns {Promise<{ path: string, contentType: string }>}
+ */
+async function downloadUrlToTempFile(url, options = {}) {
+  if (!url || typeof url !== 'string') {
+    throw new Error('downloadUrlToTempFile: нужен URL строкой');
+  }
+
+  const dir = options.dir != null ? String(options.dir) : os.tmpdir();
+  const res = await getFinalResponse(url);
+  const ct = (res.headers['content-type'] || '').trim();
+  let ext = extFromContentType(ct);
+  if (!ext && options.extFallback) {
+    ext = options.extFallback.startsWith('.')
+      ? options.extFallback
+      : `.${options.extFallback}`;
+  }
+  if (!ext) ext = '.bin';
+
+  const base =
+    options.filename ||
+    `max-media-${Date.now()}-${Math.random().toString(36).slice(2, 11)}${ext}`;
+  const safeName = path.basename(base);
+  const destPath = path.join(dir, safeName);
+
+  const ws = fs.createWriteStream(destPath);
+  try {
+    await pipeline(res, ws);
+  } catch (e) {
+    try {
+      await fs.promises.unlink(destPath);
+    } catch (_) {}
+    throw e;
+  }
+
+  return { path: destPath, contentType: ct };
+}
+
+module.exports = {
+  downloadUrlToTempFile,
+  extFromContentType,
+  extFromAttachType
+};

package/lib/entities/Message.js

@@ -1,4 +1,5 @@
 const User = require('./User');
+const { downloadUrlToTempFile, extFromAttachType } = require('../downloadMedia');
 
 /**
  * Класс представляющий сообщение
@@ -6,7 +7,12 @@ const User = require('./User');
 class Message {
   constructor(data, client) {
     this.client = client;
-    this.id = data.id || data.messageId || null;
+    this.id =
+      data.id ??
+      data.messageId ??
+      data.message_id ??
+      (data.message && (data.message.id ?? data.message.messageId)) ??
+      null;
     this.cid = data.cid || null;
     this.chatId = data.chatId || data.chat_id || null;
     
@@ -68,20 +74,26 @@ class Message {
   }
 
   /**
-   * Ответить на сообщение
+   * Отправить текст в этот же чат (как ответ собеседнику).
+   * По умолчанию без цитаты (без link REPLY): на TCP-сокете сервер часто отклоняет MSG_SEND с link.
+   * Цитата/ветка: reply({ text, quote: true }) — если сервер вернёт ошибку, оставьте quote: false.
    */
   async reply(options) {
     if (typeof options === 'string') {
       options = { text: options };
     }
 
-    return await this.client.sendMessage({
+    const { text, cid, attachments, quote = false } = options;
+    const payload = {
       chatId: this.chatId,
-      text: options.text,
-      cid: options.cid || Date.now(),
-      replyTo: this.id,
-      ...options
-    });
+      text,
+      cid,
+      attachments
+    };
+    if (quote && this.id != null && this.id !== '') {
+      payload.replyTo = this.id;
+    }
+    return await this.client.sendMessage(payload);
   }
 
   /**
@@ -110,6 +122,27 @@ class Message {
     });
   }
 
+  /**
+   * Скачать вложение по его baseUrl (HTTPS) во временный файл.
+   * По умолчанию каталог: {@link https://nodejs.org/api/os.html#ostmpdir os.tmpdir()}.
+   *
+   * @param {number} [index=0] индекс в массиве attachments
+   * @param {{ dir?: string, filename?: string }} [options]
+   * @returns {Promise<{ path: string, contentType: string }>}
+   */
+  async downloadAttachment(index = 0, options = {}) {
+    const att = this.attachments[index];
+    if (!att) {
+      throw new Error(`Нет вложения с индексом ${index}`);
+    }
+    const url = att.baseUrl || att.url;
+    if (!url || typeof url !== 'string') {
+      throw new Error('У вложения нет baseUrl/url для скачивания');
+    }
+    const extFallback = extFromAttachType(att._type || att.type);
+    return downloadUrlToTempFile(url, { ...options, extFallback });
+  }
+
   /**
    * Переслать сообщение
    */

package/lib/incomingLog.js

@@ -0,0 +1,59 @@
+/**
+ * Режим логирования входящих событий для WebMaxClient.
+ */
+
+/**
+ * @param {object} [options] опции конструктора WebMaxClient (`logIncoming`, `logIncomingVerbose`, …)
+ * @returns {{ mode: 'off' | 'messages' | 'verbose' }}
+ *
+ * - `logIncoming: false` — выкл.
+ * - `logIncoming: 'verbose'` или `logIncomingVerbose: true` — JSON сообщений + connected, raw_message, removed, chat_action, error.
+ * - `logIncoming: 'messages'` — только JSON входящих сообщений (даже при WEBMAX_DEBUG).
+ * - `WEBMAX_SILENT=1` — выкл. дампов.
+ * - `WEBMAX_DEBUG=1` — режим verbose, если не задано явно `logIncoming: 'messages'`.
+ */
+function resolveIncomingLogMode(options = {}) {
+  const silent = process.env.WEBMAX_SILENT === '1';
+  const envVerbose = process.env.WEBMAX_DEBUG === '1';
+
+  const li = options.logIncoming;
+
+  if (li === false) {
+    return { mode: 'off' };
+  }
+  if (li === 'verbose' || options.logIncomingVerbose === true) {
+    return { mode: 'verbose' };
+  }
+  if (silent) {
+    return { mode: 'off' };
+  }
+  if (li === 'messages') {
+    return { mode: 'messages' };
+  }
+  if (envVerbose) {
+    return { mode: 'verbose' };
+  }
+  return { mode: 'messages' };
+}
+
+/**
+ * @param {string} label
+ * @param {unknown} payload
+ */
+function printIncomingLog(label, payload) {
+  try {
+    const s = JSON.stringify(
+      payload,
+      (k, v) => (typeof v === 'bigint' ? v.toString() : v),
+      2
+    );
+    console.log(`\n📥 [incoming:${label}]\n${s}\n`);
+  } catch (_) {
+    console.log(`\n📥 [incoming:${label}]`, payload, '\n');
+  }
+}
+
+module.exports = {
+  resolveIncomingLogMode,
+  printIncomingLog
+};

package/lib/socketTransport.js

@@ -63,6 +63,20 @@ function unpackPacket(data) {
   return { ver, cmd, seq, opcode, payload };
 }
 
+/** JSON для логов: bigint → string, обрезка длинных строк */
+function safeJsonForLog(obj, maxLen = 12000) {
+  try {
+    const s = JSON.stringify(
+      obj,
+      (k, v) => (typeof v === 'bigint' ? v.toString() : v),
+      2
+    );
+    return s.length > maxLen ? `${s.slice(0, maxLen)}\n… [truncated ${s.length - maxLen} chars]` : s;
+  } catch (_) {
+    return String(obj);
+  }
+}
+
 function readExactlyFromBuffer(transport, n) {
   return new Promise((resolve) => {
     const tryResolve = () => {
@@ -104,6 +118,10 @@ class MaxSocketTransport {
     if (this.debug) console.log('[Socket]', ...args);
   }
 
+  _debugErr(...args) {
+    if (this.debug) console.error('[Socket]', ...args);
+  }
+
   connect() {
     return new Promise((resolve, reject) => {
       const opts = {
@@ -180,9 +198,13 @@ class MaxSocketTransport {
   async sendAndWait(opcode, payload, cmd = 0, timeout = 20000) {
     if (!this.socket || this.socket.destroyed) throw new Error('Socket not connected');
 
-    const msg = this._makeMessage(opcode, payload, cmd);
-    const seqKey = msg.seq % 256;
-    const packet = packPacket(msg.ver, msg.cmd, msg.seq, msg.opcode, msg.payload);
+    const outMsg = this._makeMessage(opcode, payload, cmd);
+    const seqKey = outMsg.seq % 256;
+    const packet = packPacket(outMsg.ver, outMsg.cmd, outMsg.seq, outMsg.opcode, outMsg.payload);
+
+    if (this.debug) {
+      this._log('→', getOpcodeName(opcode), `(seq=${outMsg.seq})`, safeJsonForLog(payload));
+    }
 
     let pendingRef;
     const promise = new Promise((resolve, reject) => {
@@ -212,8 +234,26 @@ class MaxSocketTransport {
 
     const result = await promise;
     if (result.payload && result.payload.error) {
-      const errMsg = result.payload.localizedMessage || result.payload.error?.message || JSON.stringify(result.payload.error);
-      throw new Error(errMsg);
+      const err = result.payload.error;
+      const localized = result.payload.localizedMessage;
+      const errText =
+        localized ||
+        (typeof err === 'string' ? err : err && err.message != null ? String(err.message) : '') ||
+        JSON.stringify(err);
+
+      if (this.debug) {
+        this._debugErr('RPC error response', {
+          opcode: getOpcodeName(opcode),
+          opcodeNum: opcode,
+          seq: outMsg.seq,
+          outgoingPayload: safeJsonForLog(payload),
+          fullResponsePayload: safeJsonForLog(result.payload)
+        });
+      }
+
+      const e = new Error(errText);
+      if (this.debug) e.rawPayload = result.payload;
+      throw e;
     }
     return result;
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "webmaxsocket",
-  "version": "1.1.0",
+  "version": "1.1.2",
   "description": "Node.js client for Max Messenger with QR code and token authentication",
   "main": "index.js",
   "scripts": {