WebMax TS - Node.js Client for Max Messenger

📖 Описание / Description

WebMax TS — async Node.js библиотека для работы с внутренним API мессенджера Max. Поддерживает QR-код авторизацию, Token авторизацию, и работу через WebSocket (WEB) или TCP Socket (IOS/ANDROID). Оригинал: https://github.com/Tellarion/webmaxsocket

✨ Особенности / Features

• ✅ QR-код авторизация / QR code authentication
• ✅ Token авторизация / Token authentication
• ✅ Два транспорта: WebSocket (WEB) и TCP Socket (IOS/ANDROID)
• ✅ Автоматическое сохранение сессий / Automatic session storage
• ✅ Автовыбор транспорта после QR-авторизации (переход на TCP)
• ✅ Отправка и получение сообщений / Send and receive messages
• ✅ Редактирование и удаление сообщений / Edit and delete messages
• ✅ Скачивание файлов / File download helpers
• ✅ Event-driven архитектура / Event-driven architecture
• ✅ Обработка входящих уведомлений / Handle incoming notifications
• ✅ TypeScript-first (типы генерируются из исходников)
• ✅ ESM + CJS сборка

📦 Установка / Installation

npm install webmax-ts

Импорт / Import

ESM / TypeScript

import { WebMaxClient } from 'webmax-ts'

CJS

const { WebMaxClient } = require('webmax-ts')

Зависимости для Socket транспорта (IOS/ANDROID)

Для работы с TCP Socket транспортом требуется библиотека lz4. Если при установке возникают проблемы с node-gyp:

npm install lz4 --ignore-scripts

Примечание: Для обычной QR-авторизации (WEB) дополнительные зависимости не нужны. Socket транспорт используется только после сохранения сессии или при явном указании deviceType: 'IOS'/'ANDROID'.

🚀 Быстрый старт / Quick Start

Базовый пример / Basic Example

const { WebMaxClient } = require('webmax-ts')

async function main() {
	// Инициализация клиента / Initialize client
	const client = new WebMaxClient({
		name: 'my_session', // Имя сессии / Session name
	})

	// Обработчик запуска / Start handler
	client.onStart(async () => {
		console.log('✅ Бот запущен!')
		console.log(`👤 Вы вошли как: ${client.me.fullname}`)
	})

	// Обработчик сообщений / Message handler
	client.onMessage(async message => {
		// Не отвечаем на свои сообщения / Don't reply to own messages
		if (message.senderId === client.me.id) return

		console.log(`💬 ${message.getSenderName()}: ${message.text}`)

		// Автоответ / Auto-reply
		await message.reply({
			text: `Привет! Я получил: "${message.text}"`,
			cid: Date.now(),
		})
	})

	// Запуск / Start
	await client.start()
}

main().catch(console.error)

Авторизация / Authentication

Способ 1: QR-код (рекомендуется для первого запуска)

При первом запуске вы увидите QR-код в консоли:

🔐 АВТОРИЗАЦИЯ ЧЕРЕЗ QR-КОД
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📱 Откройте приложение Max на телефоне
➡️  Настройки → Устройства → Подключить устройство
📸 Отсканируйте QR-код

█████████████████████████████
...

После сканирования:

• Токен и clientSessionId сохраняются автоматически
• При следующем запуске клиент автоматически переключится на TCP Socket для стабильности
• Повторная авторизация не требуется

Способ 2: Token авторизация

Если у вас уже есть токен (от другого сервиса/приложения):

const client = new WebMaxClient({
	name: 'my_session',
	token: 'An_Sx6HQ9HDiftNkVBNf6Q5PG5D8Oyj...', // Ваш токен
	configPath: 'config/myconfig.json', // Или из файла
	saveToken: true,
})

await client.start()

Формат конфига (config/default.json):

{
	"token": "An_Sx6HQ9HDiftNk...",
	"ua": "Mozilla/5.0 (iPhone...)",
	"device_type": 2,
	"deviceType": "IOS"
}

Транспорты

• WEB (deviceType: 'WEB' или device_type: 1) → WebSocket (ws-api.oneme.ru)
• IOS (deviceType: 'IOS' или device_type: 2) → TCP Socket (api.oneme.ru)
• ANDROID (deviceType: 'ANDROID' или device_type: 3) → TCP Socket (api.oneme.ru)

Клиент автоматически выбирает правильный транспорт на основе сохраненного deviceType.

API

WebMaxClient

Основной класс для работы с API Max.

Конструктор

const client = new WebMaxClient({
	name: 'session', // Имя сессии (для сохранения авторизации)
	token: 'An_Sx6H...', // Токен авторизации (опционально)
	configPath: 'myconfig', // Путь к config файлу (опционально)
	deviceType: 'WEB', // Тип устройства: 'WEB', 'IOS', 'ANDROID' (опционально)
	saveToken: true, // Сохранять токен в сессию (по умолчанию true)
	debug: false, // Отладочный режим (опционально)
	apiUrl: 'wss://...', // URL WebSocket API (опционально)
	maxReconnectAttempts: 5, // Максимальное количество попыток переподключения
	reconnectDelay: 3000, // Задержка между попытками переподключения (мс)
})

Методы

start()

Запускает клиент и устанавливает соединение.

await client.start()

sendMessage(options)

Отправляет сообщение в чат с уведомлением (notify: true).

const message = await client.sendMessage({
	chatId: 123,
	text: 'Привет!',
	cid: Date.now(),
	replyTo: null, // ID сообщения для ответа (опционально)
	attachments: [], // Вложения (опционально)
})

sendMessageChannel(options)

Отправляет сообщение в канал без уведомления (notify: false).

const message = await client.sendMessageChannel({
	chatId: 123,
	text: 'Сообщение в канал',
	cid: Date.now(),
	replyTo: null, // ID сообщения для ответа (опционально)
	attachments: [], // Вложения (опционально)
})

editMessage(options)

Редактирует сообщение.

await client.editMessage({
	messageId: 456,
	chatId: 123,
	text: 'Исправленный текст',
})

deleteMessage(options)

Удаляет сообщение.

await client.deleteMessage({
	messageId: 456,
	chatId: 123,
})

forwardMessage(options)

Пересылает сообщение.

await client.forwardMessage({
	messageId: 456,
	fromChatId: 123,
	toChatId: 789,
})

sendChatAction(chatId, action)

Отправляет действие в чате (печатает, выбирает стикер и т.д.).

await client.sendChatAction(123, ChatActions.TYPING)

getUser(userId)

Получает информацию о пользователе.

const user = await client.getUser(123)

getChats(limit, offset)

Получает список чатов.

const chats = await client.getChats(50, 0)

getHistory(chatId, limit, offset)

Получает историю сообщений.

const messages = await client.getHistory(123, 50, 0)

getFileLink({ fileId, chatId, messageId })

Получает прямую ссылку на файл.

const { url, unsafe } = await client.getFileLink({
	fileId: 999,
	chatId: 123,
	messageId: 456,
})

downloadFile({ fileId, chatId, messageId, output? })

Скачивает файл. Если указан output — сохранит на диск и вернёт { path, url, unsafe }. Если output не указан — вернёт Buffer.

const buffer = await client.downloadFile({ fileId: 999, chatId: 123, messageId: 456 })

const saved = await client.downloadFile({
	fileId: 999,
	chatId: 123,
	messageId: 456,
	output: './downloads/file.bin',
})

stop()

Останавливает клиент.

await client.stop()

logout()

Выполняет выход из аккаунта и удаляет сессию.

await client.logout()

Обработчики событий

onStart(handler)

Регистрирует обработчик запуска клиента.

client.onStart(async () => {
	console.log('Клиент запущен!')
})

onMessage(handler)

Регистрирует обработчик новых сообщений.

client.onMessage(async message => {
	console.log('Новое сообщение:', message.text)
})

onMessageRemoved(handler)

Регистрирует обработчик удаленных сообщений.

client.onMessageRemoved(async message => {
	console.log('Сообщение удалено:', message.text)
})

onChatAction(handler)

Регистрирует обработчик действий в чате.

client.onChatAction(async action => {
	console.log('Действие в чате:', action.type)
})

onError(handler)

Регистрирует обработчик ошибок.

client.onError(async error => {
	console.error('Ошибка:', error.message)
})

Message

Класс, представляющий сообщение.

Свойства

• id - ID сообщения
• cid - Client ID сообщения
• chatId - ID чата
• text - Текст сообщения
• senderId - ID отправителя
• sender - Объект отправителя (User)
• timestamp - Время отправки
• type - Тип сообщения
• isEdited - Флаг редактирования
• replyTo - ID сообщения, на которое это является ответом
• attachments - Вложения

Методы

reply(options)

Отвечает на сообщение.

await message.reply({
	text: 'Ответ на сообщение',
	cid: Date.now(),
})

edit(options)

Редактирует сообщение.

await message.edit({
	text: 'Новый текст',
})

delete()

Удаляет сообщение.

await message.delete()

forward(chatId)

Пересылает сообщение.

await message.forward(789)

downloadFile(index?, { output? })

Скачивает вложение типа FILE из сообщения. Работает только когда _type === 'FILE'.

const buffer = await message.downloadFile()

await message.downloadFile(0, { output: './downloads/file.bin' })

User

Класс, представляющий пользователя.

Свойства

• id - ID пользователя
• firstname - Имя
• lastname - Фамилия
• username - Имя пользователя
• phone - Номер телефона
• avatar - URL аватара
• status - Статус
• bio - Биография
• fullname - Полное имя (getter)

ChatAction

Класс, представляющий действие в чате.

Свойства

• type - Тип действия
• chatId - ID чата
• userId - ID пользователя
• user - Объект пользователя (User)
• timestamp - Время действия

Константы

ChatActions

const { ChatActions } = require('webmax-ts')

ChatActions.TYPING // Печатает
ChatActions.STICKER // Выбирает стикер
ChatActions.FILE // Отправляет файл
ChatActions.RECORDING_VOICE // Записывает голосовое
ChatActions.RECORDING_VIDEO // Записывает видео

MaxSocketTransport

Низкоуровневый TCP Socket транспорт для IOS/ANDROID (api.oneme.ru).

Прямое использование (advanced)

const { MaxSocketTransport } = require('webmax-ts')

const transport = new MaxSocketTransport({
	deviceType: 'IOS',
	ua: 'Mozilla/5.0 (iPhone...)',
	deviceId: 'your-device-id',
	debug: true,
})

await transport.connect()
await transport.handshake(userAgentPayload)
const syncData = await transport.sync(token, userAgent)

Примечание: В большинстве случаев используйте WebMaxClient, который автоматически выбирает нужный транспорт.

📚 Примеры

Пример 1: QR-авторизация (example.js)

node example.js

Первый запуск - QR-авторизация, повторные запуски - автоматический вход через TCP Socket.

Пример 2: Token авторизация (example-token.js)

# Через config файл
node example-token.js
node example-token.js myconfig  # config/myconfig.json

# Через переменную окружения
TOKEN="ваш_токен" node example-token.js

Пример 3: IOS/ANDROID Socket (example-ios.js)

# С готовым конфигом
node example-ios.js

# С отладкой
node example-ios.js --debug

Структура проекта

webmax-ts/
├── src/
│   ├── lib/                # Исходники TS
│   └── index.ts            # Экспорт публичного API
├── dist/
│   ├── esm/                # ESM сборка
│   ├── cjs/                # CJS сборка
│   └── types/              # Сгенерированные типы
├── config/                 # Конфигурационные файлы
│   └── example.json        # Пример конфига
├── sessions/               # Директория с сохраненными сессиями
├── example.js              # QR-авторизация
├── example-token.js        # Token авторизация
├── example-ios.js          # IOS/ANDROID Socket
├── package.json
└── README.md

Сессии

Библиотека автоматически сохраняет сессии в директории sessions/. При повторном запуске с тем же именем сессии авторизация не требуется.

// Создание новой сессии
const client1 = new WebMaxClient({ name: 'account1', phone: '+1234567890' })

// Использование существующей сессии
const client2 = new WebMaxClient({ name: 'account1' }) // phone не требуется

Обработка ошибок

Рекомендуется всегда оборачивать вызовы API в try-catch блоки:

try {
	const message = await client.sendMessage({
		chatId: 123,
		text: 'Привет!',
		cid: Date.now(),
	})
} catch (error) {
	console.error('Ошибка:', error.message)
}

🔧 Отладка / Debug

Для включения отладочного вывода:

const client = new WebMaxClient({
	name: 'my_session',
	debug: true, // или process.env.DEBUG = '1'
})

Или через переменную окружения:

DEBUG=1 node example.js

💡 Важные замечания

1. TCP Socket после QR-авторизации: После первой успешной QR-авторизации клиент автоматически сохраняет clientSessionId и переключается на TCP Socket транспорт при следующем запуске для повышения стабильности.

2. Разница между sendMessage и sendMessageChannel:

   • sendMessage() - отправка с уведомлением (notify: true) для обычных чатов
   • sendMessageChannel() - отправка без уведомления (notify: false) для каналов

3. Автоматический выбор транспорта: Клиент автоматически определяет какой транспорт использовать на основе deviceType в сессии или config файле.

🔗 Ссылки / Links

• Original GitHub Repository
• NPM Package

📄 Лицензия / License

MIT License - see LICENSE file for details