max-io

v0.1.7

Published

8 days ago

TypeScript framework for Max messenger bots

0High
0Medium
0Low

max max-messenger bot chatbot messenger typescript webhook polling

Max IO — TypeScript-фреймворк для разработки чат-ботов в мессенджере Max. Библиотека даёт middleware-runtime, typed context, long polling, webhook, upload helpers, клавиатуры и дополнительные модули для session/scene/i18n.

Типы API сверяются с актуальным архивом OpenAPI-схем xTCry/max-dev-openapi-schema. Текущий ориентир: схема от 2026-08-18, версия Max Bot API 0.0.33.

Возможности

| Возможность | Что даёт | | ------------------ | ------------------------------------------------------------------------------------------------------- | | Middleware-runtime | bot.use, bot.on, bot.command, bot.hears, bot.action | | Typed Context | ctx.reply, ctx.message, ctx.args, ctx.payload, ctx.state, ctx.api | | Long polling | bot.start(), marker API, режим для разработки и тестирования | | Webhook | bot.start({ webhook }), webhookCallback, createWebhook, deleteWebhook | | Upload | image/video/audio/file, progress, timeout, AbortSignal, повторная отправка при attachment.not.ready | | Клавиатуры | inline keyboard, open_app, message, clipboard, reply keyboard types | | Модули | max-io/lib/session, max-io/lib/scene, max-io/lib/i18n |

Установка

npm i max-io

yarn add max-io

Требуется Node.js >=18.18.0. Библиотека использует встроенные fetch, FormData и Blob для HTTP- и upload-запросов.

Первый бот

Создайте токен бота в Max и передайте его через переменную окружения MAX_BOT_TOKEN.

import 'dotenv/config';

import { Bot, Keyboard } from 'max-io';

const bot = new Bot(process.env.MAX_BOT_TOKEN!);

bot.command('start', async (ctx) => {
  await ctx.reply('Привет! Я бот на Max IO.', {
    attachments: [
      Keyboard.inlineKeyboard([
        [Keyboard.button.callback('Проверить callback', 'demo:callback')],
      ]),
    ],
  });
});

bot.command('echo', async (ctx) => {
  const text = ctx.payload || 'Напиши /echo любой текст';
  await ctx.reply(text);
});

bot.action('demo:callback', async (ctx) => {
  await ctx.answerOnCallback({ notification: 'Callback получен' });
});

bot.start().then();

Команды поддерживают payload и args:

bot.command('ban', async (ctx) => {
  const [userId, ...reasonParts] = ctx.args ?? [];
  const reason = reasonParts.join(' ');

  await ctx.reply(`userId=${userId}; reason=${reason || 'не указана'}`);
});

Подробнее: docs/01-first-bot.md и docs/02-listen-and-respond.md.

Webhook за минуту

import 'dotenv/config';

import { Bot } from 'max-io';

const bot = new Bot(process.env.MAX_BOT_TOKEN!);

bot.command('ping', async (ctx) => {
  await ctx.reply('pong from webhook');
});

await bot.start({
  webhook: {
    domain: 'https://example.com',
    port: 3000,
    secret: process.env.MAX_WEBHOOK_SECRET,
  },
});

Если path не указан, max-io создаёт безопасный стабильный path по токену. Callback принимает только POST с content-type: application/json; входящий JSON body ограничен 5 MiB, а лимит можно изменить через webhook.maxBodySize в байтах. При запуске webhook по умолчанию удаляются старые подписки с другими URL; при запуске polling удаляются все webhook-подписки.

Подробнее: docs/webhook.md.

Polling marker

marker нужен, чтобы продолжить long polling с конкретной позиции. Если marker не передать, Max API возвращает только последнее обновление, поэтому события, накопившиеся пока бот был недоступен, не будут прочитаны автоматически.

const bot = new Bot(process.env.MAX_BOT_TOKEN!, {
  polling: { marker: Number(process.env.MAX_POLLING_MARKER) || undefined },
});
// или
bot.polling.setMarker(123456);
console.log(bot.polling.marker);
// или
await bot.start({ marker: bot.polling.marker });

Long polling стоит использовать для разработки и ручной проверки. Для production Max рекомендует Webhook; с 11.05.2026 для polling заявлены ограничения: 2 RPS, timeout 30 секунд, batch до 100 событий и TTL событий 24 часа.

API endpoint

По умолчанию max-io использует https://platform-api.max.ru. Альтернативный https://platform-api2.max.ru может использовать сертификат, который не входит в доверенное хранилище конкретной ОС или runtime. Если соединение с ним завершается TLS-ошибкой, используйте основной endpoint либо настройте доверие к сертификату в своём окружении.

Если нужно проверить альтернативный endpoint API, его можно переопределить при создании бота:

const bot = new Bot(process.env.MAX_BOT_TOKEN!, {
  apiBaseUrl: 'https://platform-api2.max.ru',
});

Низкоуровневый клиент принимает тот же URL через createClient(token, { baseUrl }) или new Bot(token, { clientOptions: { baseUrl } }).

Upload и вложения

bot.command('video', async (ctx) => {
  const video = await ctx.api.uploadVideo({
    source: './public/video.mp4',
    onProgress: ({ loaded, total }) => {
      if (total) console.log(`upload ${Math.round((loaded / total) * 100)}%`);
    },
  });

  await ctx.reply('Видео загружено', {
    attachments: [video.toJson()],
  });
});

Подробнее: docs/03-attachments-and-uploads.md.

Клавиатуры

const keyboard = Keyboard.inlineKeyboard([
  [Keyboard.button.callback('Callback', 'payload')],
  [Keyboard.button.openApp('Открыть mini app', 'my_bot', 'demo')],
  [Keyboard.button.clipboard('Скопировать', 'promo-code')],
]);

Подробнее: docs/04-keyboards.md.

Дополнительные модули

import { I18n } from 'max-io/lib/i18n';
import { SceneManager, StepScene } from 'max-io/lib/scene';
import { SessionManager } from 'max-io/lib/session';

max-io/lib/session — session middleware с memory/Redis storage.
max-io/lib/scene — сцены и step-сценарии поверх session.
max-io/lib/i18n — YAML/JSON-локализация с поддержкой session.

Подробнее: docs/05-sessions-scenes-i18n.md.

Документация

docs/01-first-bot.md — установка, токен, первый запуск.
docs/02-listen-and-respond.md — updates, команды, ответы, форматирование.
docs/03-attachments-and-uploads.md — вложения, upload, progress, cancel.
docs/04-keyboards.md — inline/reply клавиатуры и типы кнопок.
docs/webhook.md — webhook runtime, custom server, subscriptions.
docs/05-sessions-scenes-i18n.md — session, scene, i18n.
docs/api-notes.md — важные оговорки по поведению Max API.

Entry points

| Import | Назначение | | -------------------- | --------------------------------------------------------------------- | | max-io | Runtime, Bot, Context, Api, helpers и типы конфигурации runtime | | max-io/types | Типы данных и DTO Max Bot API | | max-io/lib/session | Session middleware | | max-io/lib/scene | Scene manager | | max-io/lib/i18n | I18n middleware |

Проверка проекта

yarn test
yarn typecheck
yarn lint
yarn build
yarn test:coverage

Примеры

В репозитории есть отдельные TypeScript-проекты для ручной проверки:

examples/01-basic-minimum — базовые команды, вложения, клавиатуры, upload.
examples/02-chat-admin-management — управление администраторами чата.
examples/03-webhook-subscriptions — webhook runtime, subscribe/unsubscribe, custom server mode.
examples/04-sessions-scenes-i18n — typed context, session, scene и i18n.
examples/pr-scenarios — сценарии для проверки PR/issues и спорного поведения API.

Полезные модули

nestjs-max — интеграция Max IO с NestJS.

Статус API

Max Bot API развивается, а часть поведения зависит от серверной реализации и клиента Max. В проекте есть ручные сценарии проверки для upload, webhook, reply keyboard, chat admin API и video details. Если поведение API не подтверждено схемой или живой проверкой, лучше фиксировать это отдельно перед изменением публичных типов.

Лицензия

MIT. Подробности по сторонним ориентирам и лицензиям см. в THIRD_PARTY_NOTICES.md.