Package Exports

webmax-ts

Readme

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

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

TCP Socket после QR-авторизации: После первой успешной QR-авторизации клиент автоматически сохраняет clientSessionId и переключается на TCP Socket транспорт при следующем запуске для повышения стабильности.
Разница между sendMessage и sendMessageChannel:
- sendMessage() - отправка с уведомлением (notify: true) для обычных чатов
- sendMessageChannel() - отправка без уведомления (notify: false) для каналов
Автоматический выбор транспорта: Клиент автоматически определяет какой транспорт использовать на основе deviceType в сессии или config файле.

🔗 Ссылки / Links

📄 Лицензия / License

MIT License - see LICENSE file for details