webmaxsocket 1.1.1 → 1.1.3

package/README.md

@@ -13,9 +13,11 @@
 - ✅ **Автоматическое сохранение сессий** / 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
@@ -62,8 +64,7 @@ async function main() {
     
     // Автоответ / Auto-reply
     await message.reply({
-      text: `Привет! Я получил: "${message.text}"`,
-      cid: Date.now()
+      text: `Привет! Я получил: "${message.text}"`
     });
   });
 
@@ -197,7 +198,10 @@ const client = new WebMaxClient({
   configPath: 'myconfig', // Путь к config файлу (опционально)
   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,   // Задержка между попытками переподключения (мс)
@@ -213,6 +217,18 @@ const client = new WebMaxClient({
 });
 ```
 
+**Лог входящих (`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()`
@@ -264,7 +280,7 @@ await client.showLinkDeviceQR({ waitForScan: false, small: false });
 const message = await client.sendMessage({
   chatId: 123,
   text: 'Привет!',
-  cid: Date.now(),
+  // cid опционально; на TCP не используйте Date.now() (нужен int32)
   replyTo: null,        // ID сообщения для ответа (опционально)
   attachments: []       // Вложения (опционально)
 });
@@ -278,7 +294,6 @@ const message = await client.sendMessage({
 const message = await client.sendMessageChannel({
   chatId: 123,
   text: 'Сообщение в канал',
-  cid: Date.now(),
   replyTo: null,        // ID сообщения для ответа (опционально)
   attachments: []       // Вложения (опционально)
 });
@@ -441,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)`
@@ -476,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
 
 Класс, представляющий пользователя.
@@ -597,6 +663,8 @@ webmaxsocket/
 │   ├── userAgent.js        # UserAgent генератор
 │   ├── opcodes.js          # Протокол опкоды
 │   ├── constants.js        # Константы
+│   ├── downloadMedia.js    # Скачивание медиа по URL во временный файл
+│   ├── incomingLog.js      # Режим logIncoming / печать входящих
 │   └── entities/
 │       ├── User.js         # Класс пользователя
 │       ├── Message.js      # Класс сообщения
@@ -634,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);
@@ -673,6 +740,10 @@ DEBUG=1 node example.js
 
 5. **Автоматический выбор транспорта:** Клиент автоматически определяет какой транспорт использовать на основе `deviceType` в сессии или config файле.
 
+6. **`cid` при отправке сообщений (TCP/Socket):** сервер проверяет **signed int32**. Не передавайте `Date.now()` (миллисекунды ~1e12) — будет «Ошибка валидации». Либо не указывайте `cid` (клиент подставит свой), либо передайте целое в диапазоне **−2³¹ … 2³¹−1**.
+
+7. **TCP и keep-alive (PING):** сервер периодически шлёт `PING`. На WebSocket клиент отвечает `sendPong`; на **TCP** раньше ответ не отправлялся — соединение могло обрываться через несколько минут, после чего процесс Node **завершался** (нечем держать event loop). Сейчас на TCP автоматически шлётся тот же ответ, что и у WebSocket (`PING` с пустым payload).
+
 ## 🔗 Ссылки / Links
 
 - [GitHub Repository](https://github.com/Tellarion/webmaxsocket)

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 }
@@ -144,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);
+    });
   }
 
   /**
@@ -896,8 +929,16 @@ class WebMaxClient extends EventEmitter {
           break;
 
         case Opcode.PING:
+          // Иначе сервер рвёт TCP через ~минуты; WebSocket здесь шлёт sendPong (тот же opcode PING + {})
+          if (
+            this._socketTransport &&
+            this._socketTransport.socket &&
+            !this._socketTransport.socket.destroyed
+          ) {
+            this._socketTransport.sendOneWay(Opcode.PING, {});
+          }
           break;
-          
+
         default:
           this.emit('raw_message', data);
       }
@@ -1001,12 +1042,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);
   }
 
@@ -1015,6 +1060,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);
   }
 
@@ -1023,6 +1071,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);
   }
 
@@ -1074,6 +1125,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;
+  }
+
   /**
    * Отправка сообщения (с уведомлением)
    */
@@ -1085,14 +1203,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
     };
 
@@ -1116,14 +1228,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
     };
 
@@ -1252,8 +1358,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 = {
@@ -138,6 +156,16 @@ class MaxSocketTransport {
     };
   }
 
+  /**
+   * Однонаправленная отправка без ожидания ответа (ответ на серверный PING — как WebSocket sendPong).
+   */
+  sendOneWay(opcode, payload = {}, cmd = 0) {
+    if (!this.socket || this.socket.destroyed) return;
+    const msg = this._makeMessage(opcode, payload, cmd);
+    const packet = packPacket(msg.ver, msg.cmd, msg.seq, msg.opcode, msg.payload);
+    this.socket.write(packet);
+  }
+
   _startRecvLoop() {
     const readNext = async () => {
       if (!this.socket || this.socket.destroyed) return;
@@ -180,9 +208,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 +244,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.1",
+  "version": "1.1.3",
   "description": "Node.js client for Max Messenger with QR code and token authentication",
   "main": "index.js",
   "scripts": {