@dementevdev/maxbot-ts

TypeScript SDK для MAX Bot API.

Базовый URL: https://platform-api.max.ru
Node.js >= 18 (встроенный fetch)

Содержание

Начало работы

Установка
Быстрый старт
Стабильность API

Конфигурация

Ограничение параллелизма
Webhook
allowedUpdates — фильтрация типов обновлений

Возможности

Inline‑клавиатура
Загрузка файлов
Работа с ошибками
Метрики и наблюдаемость
Рекомендации по concurrency

Маршрутизация

Middleware-пайплайн
Filter DSL
Composer — суб-роутер
bot.filter() / ctx.has()

Продвинутое использование

Расширение контекста
Паттерны
Migration Guide

Справочник

Локальные примеры
API
Форматы вложений
Sub-entry points
Versioning

Установка

npm i @dementevdev/maxbot-ts

Быстрый старт

import { Bot } from "@dementevdev/maxbot-ts";

const bot = new Bot({
  token: process.env.MAX_BOT_TOKEN!,
  transport: "polling",
});

bot.onMessage(async (ctx) => {
  await ctx.reply("Привет!");
});

// Graceful shutdown: дожидаемся завершения текущих обработчиков
process.once("SIGINT", async () => {
  await bot.stop();
  process.exit(0);
});

await bot.start();

Webhook: замените transport: "polling" на transport: "webhook" и добавьте секцию webhook: { port, url } — см. раздел Webhook ниже.

Стабильность API

Пакет следует SemVer. Список стабильных экспортов с v1.0.0:

Категория	Символы
Бот	`Bot`, `BotConfig`, `Context`, `EventHandler`
Контексты	`MessageContext`, `CallbackContext`, `ChatContext`, `BotStartedContext`
Маршрутизация	`bot.command()`, `bot.hears()`, `bot.action()`, `bot.on()`, `bot.use()`, `bot.filter()`
Триггеры	`HearsTrigger`, `CommandTrigger`, `matchCommand`
Жизненный цикл	`bot.start()`, `bot.stop()`, `bot.getMe()`, `bot.sendMessage()`, `bot.sendPrivateMessage()`
Утилиты	`InlineKeyboard`, `md`, `html`, `Histogram`, `DEFAULT_BUCKETS`
Ошибки	`MaxError`, `RateLimitError`, `AuthError`, `NetworkError`, `ApiError`, `ValidationError`, `NotFoundError`
Composer	`Composer`, `Filter`
Фильтры	`hasText`, `isPrivateChat`, `commandIs`, `hasCallbackPayload`, `payloadIs`
Sub-entry points	`@dementevdev/maxbot-ts/middleware`, `@dementevdev/maxbot-ts/filters`

Experimental (сигнатуры стабильны, могут расширяться до v2.0.0): BotMetrics, onMetrics, HistogramSnapshot.

Полная semver-политика → раздел Versioning в конце документа.

Ограничение параллелизма обновлений

По умолчанию бот обрабатывает не более 10 обновлений одновременно (concurrency: 10). Это защищает от burst-нагрузки: новые обновления ждут в очереди, а не запускают неограниченное число параллельных промисов.

import { Bot } from "@dementevdev/maxbot-ts";

const bot = new Bot({
  token: process.env.MAX_BOT_TOKEN!,
  transport: "polling",
  concurrency: 20, // максимум 20 одновременно обрабатываемых update
});

Ограничение применяется на уровне одного update.
Все хендлеры внутри одного update выполняются параллельно.
Infinity отключает ограничение и возвращает прежнее поведение.

Webhook

import { Bot } from "@dementevdev/maxbot-ts";

const bot = new Bot({
  token: process.env.MAX_BOT_TOKEN!,
  transport: "webhook",
  webhook: {
    port: 3000,
    url: "https://mybot.example.com/webhook",
    autoRegister: true,
    secretToken: process.env.WEBHOOK_SECRET,
  },
});

bot.onMessage(async (ctx) => {
  await ctx.reply("Привет!");
});

bot.start();

allowedUpdates — фильтрация типов обновлений

По умолчанию бот получает все типы обновлений. Опция allowedUpdates в polling позволяет указать только нужные — сервер не будет отправлять остальные, снижая трафик.

const bot = new Bot({
  token: process.env.MAX_BOT_TOKEN!,
  transport: "polling",
  polling: {
    allowedUpdates: ["message_created", "message_callback"],
  },
});

Доступные типы (UpdateType):

Тип	Когда приходит
`message_created`	Новое сообщение в чате или диалоге
`message_edited`	Редактирование сообщения
`message_removed`	Удаление сообщения
`message_callback`	Нажатие inline-кнопки
`bot_started`	Нажатие Start / переход по deep link
`bot_added`	Бот добавлен в чат
`bot_removed`	Бот удалён из чата
`user_added`	Пользователь добавлен в чат через бота
`user_removed`	Пользователь удалён из чата через бота
`chat_title_changed`	Изменение названия чата

Если не указать allowedUpdates — приходят все типы (поведение по умолчанию).

Inline‑клавиатура

import { Bot, InlineKeyboard, md } from "@dementevdev/maxbot-ts";

const bot = new Bot({
  token: process.env.MAX_BOT_TOKEN!,
  transport: "polling",
});

bot.onMessage(async (ctx) => {
  const keyboard = new InlineKeyboard()
    .button("Да", "yes")
    .row()
    .button("Нет", "no")
    .build();

  await ctx.reply(md.bold("Выберите вариант:"), {
    format: "markdown",
    attachments: [keyboard],
  });
});

bot.onCallback(async (ctx) => {
  await ctx.answer({ notification: `Вы нажали: ${ctx.data}` });
});

bot.start();

Загрузка файлов

Ограничения multipart upload:

Максимальный размер файла: 4 ГБ
Можно загружать только один файл за раз

import { Bot } from "@dementevdev/maxbot-ts";
import { readFile } from "node:fs/promises";

const bot = new Bot({
  token: process.env.MAX_BOT_TOKEN!,
  transport: "polling",
});

async function uploadImage() {
  const { url } = await bot.api.uploads.getUploadUrl("image");
  const buffer = await readFile("./image.png");
  const blob = new Blob([buffer]);

  const payload = await bot.api.uploads.uploadFile(url, blob, "image.png");
  return payload;
}

Работа с ошибками

Все ошибки SDK наследуют MaxError. Иерархия:

Класс	HTTP	Поля	Когда возникает
`RateLimitError`	429	`retryAfter: number` (мс)	Превышен лимит запросов к API
`AuthError`	401	—	Невалидный или отсутствующий токен
`ApiError`	4xx/5xx	`statusCode`, `apiCode?`	Ошибка на стороне сервера MAX
`NotFoundError`	404	—	Чат / сообщение / ресурс не найден
`ValidationError`	—	—	Некорректные параметры вызова
`NetworkError`	—	`cause?: Error`	Таймаут, обрыв сети
`MaxError`	—	`message`	Базовый класс всех ошибок SDK

import {
  Bot,
  MaxError,
  RateLimitError,
  AuthError,
  ApiError,
  NetworkError,
} from "@dementevdev/maxbot-ts";

const bot = new Bot({
  token: process.env.MAX_BOT_TOKEN!,
  transport: "polling",
});

bot.onError((error) => {
  if (error instanceof RateLimitError) {
    // retryAfter — мс до следующего окна.
    // Polling-транспорт сам делает паузу; здесь можно залогировать.
    console.warn(`Rate limit, retry через ${error.retryAfter}мс`);
    return;
  }

  if (error instanceof AuthError) {
    console.error("Неверный токен — бот не может работать");
    process.exit(1);
  }

  if (error instanceof NetworkError) {
    // Временная ошибка сети — транспорт восстановится сам
    console.warn("Сеть недоступна:", error.message);
    return;
  }

  if (error instanceof MaxError) {
    console.error("Ошибка SDK:", error.message);
    return;
  }

  console.error("Неизвестная ошибка:", error);
});

Retry-поведение: polling-транспорт при RateLimitError автоматически выдерживает паузу retryAfter мс перед следующим запросом. При NetworkError — экспоненциальный backoff. Приложению не нужно реализовывать retry вручную.

Метрики и наблюдаемость

onMetrics — per-update метрики

import { Bot } from "@dementevdev/maxbot-ts";
import type { BotMetrics } from "@dementevdev/maxbot-ts";

const bot = new Bot({
  token: process.env.MAX_BOT_TOKEN!,
  transport: "polling",
  onMetrics: (m: BotMetrics) => {
    // m.totalMs        — общее время обработки update (middleware + handlers)
    // m.middlewareTimes — массив ms по каждому middleware в порядке регистрации
    // m.queueSizeAtStart — размер очереди ДО захвата слота (backpressure индикатор)
    // m.handlerErrors  — число ошибок в handlers для этого update
    // m.updateType     — тип update ('message_created', 'message_callback', ...)

    if (m.totalMs > 500) {
      console.warn(`Slow update: ${m.updateType} — ${m.totalMs}ms`);
    }
    if (m.queueSizeAtStart > 5) {
      console.warn(`Queue pressure: ${m.queueSizeAtStart} waiting`);
    }
    if (m.handlerErrors > 0) {
      console.error(`Handler errors: ${m.handlerErrors} in ${m.updateType}`);
    }
  },
});

onMetrics не влияет на производительность если не задан — замер включается только при его наличии.

onSlowHandler — порог по времени

// Срабатывает только если total time >= 200ms
bot.onSlowHandler(200, (ms, updateType) => {
  console.warn(`Slow: ${updateType} — ${ms}ms`);
});

Разница с onMetrics: onSlowHandler — простой threshold-алерт без детализации по middleware.

Histogram — гистограмма задержек

Histogram накапливает измерения totalMs по корзинам (buckets) в формате, совместимом с Prometheus. Удобен для экспорта p50/p95/p99 в любую систему мониторинга.

import { Bot, Histogram } from "@dementevdev/maxbot-ts";

const histogram = new Histogram(); // дефолтные корзины: 5, 10, 25, 50, 100, 250, 500, 1000 мс

const bot = new Bot({
  token: process.env.MAX_BOT_TOKEN!,
  transport: "polling",
  onMetrics: (m) => histogram.observe(m.totalMs),
});

// Публикуем снимок раз в минуту
setInterval(() => {
  const snap = histogram.snapshot();
  // snap.buckets: { "5": 12, "10": 45, "25": 78, ..., "+Inf": 100 } — кумулятивно
  // snap.count: 100   — общее число обновлений
  // snap.sum: 3 200   — суммарное время в мс (для расчёта среднего: sum / count)
  console.log(snap);
  histogram.reset(); // сброс для следующего окна
}, 60_000);

Кастомные корзины — передайте массив границ в мс:

const h = new Histogram([10, 50, 200, 1000, 5000]);

Корзины автоматически сортируются и дедуплицируются.

Структура снимка HistogramSnapshot:

Поле	Тип	Описание
`buckets`	`Record<string, number>`	Кумулятивные счётчики: `"50"` = число наблюдений ≤ 50ms, `"+Inf"` = всего
`sum`	`number`	Сумма всех значений в мс
`count`	`number`	Число наблюдений (= `buckets["+Inf"]`)

Интеграция с Prometheus через prom-client:

import { Registry, Histogram as PromHistogram } from "prom-client";

const registry = new Registry();
const promHist = new PromHistogram({
  name: "bot_update_duration_ms",
  help: "Update processing duration",
  buckets: [5, 10, 25, 50, 100, 250, 500, 1000],
  registers: [registry],
});

bot = new Bot({
  token: process.env.MAX_BOT_TOKEN!,
  transport: "polling",
  onMetrics: (m) => promHist.observe(m.totalMs),
});

Рекомендации по параметру concurrency

Профиль бота	Рекомендуемое значение	Обоснование
Приватные диалоги, быстрые ответы	`10` (по умолчанию)	Баланс параллелизма и защиты
Бот в большой группе / публичный	`20–50`	Больше одновременных пользователей
Webhook-бот с тяжёлой бизнес-логикой	`5–10`	Снизить нагрузку на downstream
Бот с медленными API-вызовами (> 1s)	`20–100`	Большинство времени — I/O ожидание
Минимальный сервис / отладка	`1`	Строгая очерёдность
Без ограничений (legacy-режим)	`Infinity`	Не рекомендуется в проде

Как определить правильное значение:

Запустите с onMetrics и наблюдайте queueSizeAtStart
Если очередь стабильно > 0 — увеличьте concurrency
Если растут ошибки downstream API — уменьшите
Ориентир: concurrency ≈ (среднее время handler) / (желаемая latency) × throughput

// Диагностика: подбор concurrency по метрикам
const bot = new Bot({
  token: process.env.MAX_BOT_TOKEN!,
  transport: "polling",
  concurrency: 10, // начните с дефолта
  onMetrics: (m) => {
    // Если queueSizeAtStart регулярно > 3 — увеличьте concurrency
    // Если totalMs растёт — возможно, downstream перегружен
    console.log(
      JSON.stringify({
        type: m.updateType,
        ms: m.totalMs,
        queue: m.queueSizeAtStart,
        errors: m.handlerErrors,
      }),
    );
  },
});

SDK предоставляет полноценный middleware-пайплайн аналогично Koa/Telegraf.

bot.use() — глобальные middleware

import { Bot } from "@dementevdev/maxbot-ts";

const bot = new Bot({
  token: process.env.MAX_BOT_TOKEN!,
  transport: "polling",
});

// Логирование каждого update
bot.use(async (ctx, next) => {
  const start = Date.now();
  await next();
  console.log(`${ctx.raw.update_type} — ${Date.now() - start}ms`);
});

// Ранний выход без вызова next() останавливает пайплайн
bot.use(async (ctx, next) => {
  if (ctx.raw.update_type === "message_created") {
    const chatType = ctx.raw.message?.recipient?.chat_type;
    if (chatType !== "dialog") return; // игнорируем групповые сообщения
  }
  await next();
});

bot.onMessage(async (ctx) => {
  await ctx.reply("Привет из private chat!");
});

bot.start();

Middleware выполняется внутри одного слота семафора — все ограничения concurrency сохраняются даже при длинных middleware-цепочках.

bot.command() / bot.hears() / bot.action()

// Команды (срабатывает на /start и /start <args>)
bot.command("start", async (ctx) => {
  await ctx.reply("Добро пожаловать!");
});

// Произвольный текст: строка, RegExp или массив паттернов (HearsTrigger)
bot.hears(/^ping$/i, async (ctx) => {
  await ctx.reply("pong 🏓");
});

// Массив — срабатывает если ANY из паттернов совпал (первый побеждает)
bot.hears(["привет", "hello", /^hi$/i], async (ctx) => {
  await ctx.reply("Привет!");
});

// Нажатие inline-кнопки по payload (строка, RegExp или массив)
bot.action("confirm", async (ctx) => {
  await ctx.answer({ notification: "Подтверждено ✓" });
});

// Несколько строковых payload — одним обработчиком
bot.action(["yes", "confirm", "ok"], async (ctx) => {
  await ctx.answer({ notification: "Принято!" });
});

// Несколько RegExp-паттернов
bot.action([/^buy:(\d+)$/, /^sell:(\d+)$/], async (ctx) => {
  if (isCallbackContext(ctx) && ctx.match) {
    const id = ctx.match[1];
    await ctx.answer({ notification: `Позиция #${id}` });
  }
});

// Все методы возвращают this — можно чейнить
bot
  .command("help", async (ctx) => ctx.reply("/start — начать"))
  .hears("привет", async (ctx) => ctx.reply("Привет!"));

HearsTrigger — тип паттерна для hears() и action(): string | RegExp | ReadonlyArray<string | RegExp>. При массиве срабатывает первый совпавший паттерн; ctx.match устанавливается только если совпал RegExp.

Variadic middlewares

command(), hears(), action(), on(), onMessage(), onCallback(), onStart() принимают произвольное число middleware перед финальным обработчиком. Промежуточные должны вызвать next(), иначе цепочка прерывается.

// Guard: блокирует неавторизованных
const authMw: Middleware<Context> = async (ctx, next) => {
  if (!isAuthorized(ctx)) return; // next() не вызван → handler не выполнится
  await next();
};

// Логирование
const logMw: Middleware<Context> = async (ctx, next) => {
  console.log("before");
  await next();
  console.log("after");
};

bot.command("pay", authMw, logMw, async (ctx) => {
  /* ... */
});
bot.hears(/^\d+/, authMw, async (ctx) => {
  /* ... */
});
bot.action(/^buy:/, authMw, logMw, async (ctx) => {
  /* ... */
});
bot.on("message_created", logMw, async (ctx) => {
  /* ... */
});

ctx.match — capture-группы RegExp

При использовании RegExp-паттерна в hears() и action() результат exec() сохраняется в ctx.match. Для строкового паттерна ctx.match равен null.

import { isMessageContext, isCallbackContext } from "@dementevdev/maxbot-ts";

// hears: извлекаем числа из текста
bot.hears(/(\d+)\+(\d+)/, async (ctx) => {
  if (isMessageContext(ctx) && ctx.match) {
    const a = Number(ctx.match[1]);
    const b = Number(ctx.match[2]);
    await ctx.reply(`${a} + ${b} = ${a + b}`);
  }
});

// action: извлекаем id из payload кнопки вида "buy:42"
bot.action(/^buy:(\d+)$/, async (ctx) => {
  if (isCallbackContext(ctx) && ctx.match) {
    const productId = ctx.match[1]; // "42"
    await ctx.answer({ notification: `Заказ #${productId} оформлен` });
  }
});

Свойство	Тип	Доступно в	Значение при строковом паттерне
`ctx.match`	`RegExpExecArray \| null`	`MessageContext`, `CallbackContext`	`null`

bot.onStart() — deep link и старт бота

Событие bot_started возникает когда пользователь нажимает кнопку Start в диалоге или переходит по ссылке вида https://max.ru/...?start=<payload>.

ctx.startPayload содержит значение параметра start из ссылки — используйте для реферальных программ, onboarding-флоу и контекстного запуска.

import { Bot, isBotStartedContext } from "@dementevdev/maxbot-ts";

const bot = new Bot({
  token: process.env.MAX_BOT_TOKEN!,
  transport: "polling",
});

// Convenience-метод — алиас для bot.on('bot_started', ...)
bot.onStart(async (ctx) => {
  if (isBotStartedContext(ctx)) {
    if (ctx.startPayload) {
      // Пользователь перешёл по deep link: https://max.ru/...?start=ref_123
      await ctx.reply(`Вы пришли по реферальной ссылке: ${ctx.startPayload}`);
    } else {
      // Обычный запуск без параметра
      await ctx.reply("Добро пожаловать! Введите /help для справки.");
    }
  }
});

bot.start();

Свойство / метод	Тип	Описание
`ctx.startPayload`	`string \| null \| undefined`	Payload из deep link, `null` если нет
`ctx.chatId`	`number`	ID диалога
`ctx.userId`	`number`	ID пользователя, нажавшего Start
`ctx.user`	`User`	Объект пользователя
`isBotStartedContext`	type guard	Сужает `Context` до `BotStartedContext`

ctx.editMessage / ctx.deleteMessage / ctx.sendAction

Методы доступны в MessageContext и CallbackContext. sendAction также доступен в BotStartedContext.

// ── MessageContext ──────────────────────────────────────────────────────────
bot.onMessage(async (ctx) => {
  if (!isMessageContext(ctx)) return;

  // Редактировать входящее сообщение (требует rights, обычно своё)
  await ctx.editMessage("обновлённый текст");

  // Удалить сообщение
  await ctx.deleteMessage();

  // Произвольное действие: 'typing_on', 'sending_photo', 'mark_seen', …
  await ctx.sendAction("sending_file");

  // sendTyping() — удобный псевдоним для sendAction('typing_on')
  await ctx.sendTyping();
});

// ── CallbackContext ─────────────────────────────────────────────────────────
bot.onCallback(async (ctx) => {
  if (!isCallbackContext(ctx)) return;

  // Редактировать сообщение с кнопкой
  await ctx.editMessage("результат обработан", { format: "markdown" });

  // Удалить сообщение с кнопкой
  await ctx.deleteMessage();

  // Показать "печатает..." пока обрабатывается запрос
  await ctx.sendAction("typing_on");
  const result = await processRequest();
  await ctx.reply(result);
});

// ── BotStartedContext ───────────────────────────────────────────────────────
bot.onStart(async (ctx) => {
  if (!isBotStartedContext(ctx)) return;
  await ctx.sendAction("typing_on");
  await ctx.reply("Добро пожаловать!");
});

Метод	Доступен в	Бросает если
`ctx.editMessage(text, opts?)`	`MessageContext`, `CallbackContext`	нет `messageId`
`ctx.deleteMessage()`	`MessageContext`, `CallbackContext`	нет `messageId`
`ctx.sendAction(action)`	`MessageContext`, `CallbackContext`, `BotStartedContext`	нет `chatId`
`ctx.sendTyping()`	`MessageContext`	нет `chatId`

onSlowHandler — см. раздел Метрики и наблюдаемость выше.

Filter DSL

Набор предикатов для type-safe фильтрации контекста в middleware:

import {
  Bot,
  hasText,
  isPrivateChat,
  commandIs,
  hasCallbackPayload,
  payloadIs,
} from "@dementevdev/maxbot-ts";

const bot = new Bot({
  token: process.env.MAX_BOT_TOKEN!,
  transport: "polling",
});

const isStart = commandIs("start");
const isDeleteAction = payloadIs(/^delete:/);

bot.use(async (ctx, next) => {
  if (isStart(ctx)) {
    await ctx.reply("Привет! /help — список команд");
    return;
  }

  if (isDeleteAction(ctx)) {
    const id = ctx.data.split(":")[1]; // ctx: CallbackContext, ctx.data: string
    await ctx.answer({ notification: `Удаляю ${id}` });
    return;
  }

  if (hasText(ctx)) {
    // ctx: MessageContext, ctx.text: string — без undefined
    await ctx.reply(`Эхо: ${ctx.text}`);
    return;
  }

  await next();
});

Предикат	Сужает тип	Описание
`hasText(ctx)`	`MessageContext & { text: string }`	Сообщение с непустым текстом
`isPrivateChat(ctx)`	`MessageContext`	Приватный чат (dialog)
`commandIs(name)`	`MessageContext & { text: string }`	Фабрика — совпадение по команде
`hasCallbackPayload(ctx)`	`CallbackContext & { data: string }`	Callback с непустым payload
`payloadIs(pattern)`	`CallbackContext & { data: string }`	Фабрика — совпадение payload по строке или RegExp

Composer — суб-роутер

Composer — независимый роутер, который собирается отдельно от бота и подключается через bot.use(composer.middleware()). Поддерживает те же методы маршрутизации что и Bot: command, hears, action, on, use, filter.

Базовое использование

import { Bot, Composer } from "@dementevdev/maxbot-ts";

const bot = new Bot({
  token: process.env.MAX_BOT_TOKEN!,
  transport: "polling",
});

const router = new Composer();
router.command("start", async (ctx) => ctx.reply("Привет!"));
router.hears(/(\d+)\+(\d+)/, async (ctx) => {
  const [, a, b] = ctx.match!;
  await ctx.reply(`${a} + ${b} = ${Number(a) + Number(b)}`);
});

bot.use(router.middleware());
await bot.start();

Изоляция модулей

Разбивайте большой бот на независимые файлы — каждый экспортирует один Composer:

// shop.ts
import { Composer } from "@dementevdev/maxbot-ts";
export const shopRouter = new Composer();

shopRouter.command("catalog", catalogHandler);
shopRouter.command("cart", cartHandler);
shopRouter.action(/^add:(\d+)/, addToCartHandler);

// admin.ts
import { Composer } from "@dementevdev/maxbot-ts";
import { isAdmin } from "./guards.js";
export const adminRouter = new Composer();

adminRouter.use(isAdmin); // middleware только для этого роутера
adminRouter.command("stats", statsHandler);
adminRouter.command("ban", banHandler);

// bot.ts
import { Bot } from "@dementevdev/maxbot-ts";
import { shopRouter } from "./shop.js";
import { adminRouter } from "./admin.js";

const bot = new Bot({
  token: process.env.MAX_BOT_TOKEN!,
  transport: "polling",
});
bot.use(shopRouter.middleware());
bot.use(adminRouter.middleware());
await bot.start();

Вложенные Composer (under-router)

const outer = new Composer();
const inner = new Composer();

inner.command("nested", handler);
outer.use(inner.middleware());

bot.use(outer.middleware());

API

Метод	Описание
`use(middleware)`	Добавить middleware в цепочку
`on(event, ...fns)`	Подписаться на `UpdateType`
`command(name, ...fns)`	Обработать команду `/name`
`hears(pattern, ...fns)`	Обработать текст (строка или RegExp, устанавливает `match`)
`action(pattern, ...fns)`	Обработать callback payload
`filter(predicate, ...fns)`	Запустить `fns` только если `predicate` вернул `true`
`middleware()`	Вернуть `Middleware` для `bot.use()`

bot.filter() / ctx.has()

bot.filter()

Подключить middleware только для контекстов, удовлетворяющих предикату. Несовпадающие обновления прозрачно перетекают к следующим обработчикам.

import { Bot, hasText, isPrivateChat } from "@dementevdev/maxbot-ts";

const bot = new Bot({
  token: process.env.MAX_BOT_TOKEN!,
  transport: "polling",
});

// Только приватные чаты с текстом
bot.filter(isPrivateChat, async (ctx, next) => {
  console.log("приватный чат");
  await next();
});

// Только сообщения с текстом — ctx.text: string (не undefined)
bot.filter(hasText, async (ctx) => {
  await ctx.reply(`Эхо: ${ctx.text}`);
});

// Комбинация: Composer подключается только для приватных чатов
const privateRouter = new Composer();
privateRouter.command("start", startHandler);

bot.filter(isPrivateChat, privateRouter.middleware());

ctx.has()

Проверить тип контекста прямо внутри обработчика с автоматическим сужением типа:

bot.use(async (ctx, next) => {
  if (ctx.has(hasText)) {
    // ctx: MessageContext & { text: string }
    console.log(ctx.text.toUpperCase()); // ctx.text — string, не undefined
    await ctx.sendTyping();
  }

  if (ctx.has(isCallbackContext)) {
    // ctx: CallbackContext
    await ctx.answer();
  }

  await next();
});

Доступен на всех контекстах: MessageContext, CallbackContext, ChatContext, BotStartedContext.

bot.onStart(async (ctx) => {
  if (ctx.has(isPrivateChat)) {
    // обрабатываем только приватный старт
  }
});

Расширение контекста (Custom Context)

import { Bot } from "@dementevdev/maxbot-ts";
import type { Context } from "@dementevdev/maxbot-ts";

// Тип расширенного контекста — intersection с базовым
type SessionCtx = Context & { session: { userId: number; count: number } };

const sessions = new Map<number, { userId: number; count: number }>();

const bot = new Bot<SessionCtx>({
  token: process.env.MAX_BOT_TOKEN!,
  transport: "polling",
  contextFactory: (base): SessionCtx => {
    const userId =
      base.raw.update_type === "message_created"
        ? base.raw.message.sender.user_id
        : 0;
    const session = sessions.get(userId) ?? { userId, count: 0 };
    sessions.set(userId, session);
    return Object.assign(base as SessionCtx, { session });
  },
});

// В middleware ctx.session типизирован без кастов
bot.use(async (ctx, next) => {
  ctx.session.count += 1;
  await next();
});

bot.command("stats", async (ctx) => {
  await ctx.reply(`Сообщений: ${ctx.session.count}`);
});

Паттерны (Patterns)

Паттерн 1: Слоистая middleware-архитектура

// 1. Глобальная инфраструктура (логи, трейсинг)
bot.use(loggingMiddleware);
bot.use(tracingMiddleware);

// 2. Безопасность (auth, rate-limit)
bot.use(authMiddleware);
bot.use(rateLimitMiddleware);

// 3. Бизнес-роутинг
bot.command("start", startHandler);
bot.action(/^order:/, orderHandler);
bot.onMessage(fallbackHandler);

Паттерн 2: Переиспользуемые предикаты

// predicates.ts
export const isAdminMessage =
  (adminIds: number[]) =>
  (ctx: Context): ctx is MessageContext =>
    ctx instanceof MessageContext &&
    adminIds.includes(ctx.message.sender.user_id);

// bot.ts
const isAdmin = isAdminMessage([123456789]);

bot.use(async (ctx, next) => {
  if (!isAdmin(ctx)) {
    await ctx.reply("Нет доступа");
    return;
  }
  await next();
});

Паттерн 3: Корректный graceful shutdown

import { Bot } from "@dementevdev/maxbot-ts";

const bot = new Bot({
  token: process.env.MAX_BOT_TOKEN!,
  transport: "polling",
});

bot.onMessage(async (ctx) => {
  await ctx.reply("OK");
});

async function main() {
  await bot.start();
  console.log("Бот запущен");

  // Graceful shutdown: ждём завершения текущих обработчиков
  process.once("SIGINT", async () => {
    console.log("Останавливаем бота...");
    await bot.stop();
    process.exit(0);
  });
}

main().catch(console.error);

Migration Guide: от handlers к middleware

Было (handlers-only)

const bot = new Bot({ token, transport: "polling" });

bot.onMessage(async (ctx) => {
  if (!ctx.text) return;
  if (ctx.text === "/start") {
    await ctx.reply("Привет!");
    return;
  }
  await ctx.reply(`Эхо: ${ctx.text}`);
});

bot.onCallback(async (ctx) => {
  if (ctx.data === "yes") await ctx.answer({ notification: "Да!" });
});

Стало (middleware/composer — те же гарантии, лучший DX)

const bot = new Bot({ token, transport: "polling" });

// Опциональный глобальный middleware добавляется через use()
// Старые onMessage/onCallback продолжают работать без изменений

bot.command("start", async (ctx) => {
  await ctx.reply("Привет!");
});

bot.onMessage(async (ctx) => {
  if (!ctx.text || ctx.text.startsWith("/")) return;
  await ctx.reply(`Эхо: ${ctx.text}`);
});

bot.action("yes", async (ctx) => {
  await ctx.answer({ notification: "Да!" });
});

Что изменилось:

onMessage/onCallback — полная обратная совместимость, работают как раньше
bot.use() добавляет middleware до всех существующих handlers
bot.command(), bot.hears(), bot.action() — sugar поверх bot.on()
Все middleware и handlers выполняются внутри одного semaphore-slot → concurrency по-прежнему работает

Локальные примеры

В папке examples/ лежат готовые сценарии:

Файл	Описание
`echo-bot.js`	Минимальный эхо-бот
`keyboard-bot.js`	Inline-клавиатура и callback
`command-bot.js`	Команды, hears, action
`middleware-bot.js`	Middleware-пайплайн, логирование, rate-limit, variadic мw
`custom-context-bot.js`	Расширение контекста через contextFactory
`filters-bot.js`	Filter DSL (hasText, payloadIs, commandIs)
`webhook-bot.js`	Webhook-режим
`send-media-bot.js`	Загрузка и отправка медиа
`all-buttons-bot.js`	Все типы кнопок: callback/link/contact/geo/openApp
`graceful-shutdown-bot.js`	onMetrics, onSlowHandler, onUnknownUpdate, SIGTERM
`broadcast-bot.js`	Рассылка подписчикам, sendPrivateMessage, getMe
`wizard-bot.js`	Многошаговый диалог (FSM по шагам)
`group-bot.js`	Группы: bot_added, user_added, chat_title_changed
`typing-bot.js`	sendTyping() + replyWithQuote() + /typingtest
`match-bot.js`	ctx.match: capture-группы в hears() и action()
`start-payload-bot.js`	bot.onStart(), ctx.startPayload, deep link

Эта папка не публикуется в npm-пакет (ограничение через поле files в package.json).

Для запуска примеров локально:

npm run build
node examples/echo-bot.js

API

Доступ к низкоуровневым методам через bot.api:

bot.api.bots.getMe()
bot.api.chats.*
bot.api.messages.*
bot.api.subscriptions.*
bot.api.uploads.*

Полные типы экспортируются из пакета:

import type { Message, Update, Chat, BotInfo } from "@dementevdev/maxbot-ts";

Формат contact‑вложения (request_contact)

При нажатии кнопки request_contact бот получает сообщение с вложением типа contact. Полезные поля payload:

vcf_info: vCard строка
vcf_phone: телефон
max_info: объект пользователя (User)

Формат location‑вложения (request_geo_location)

При нажатии кнопки request_geo_location бот получает сообщение с вложением типа location:

latitude: число
longitude: число

Sub-entry points (tree-shaking)

Модули middleware и filters доступны как отдельные точки входа — они не попадают в бандл тех, кто их не импортирует:

// Только core SDK — middleware и filters не включаются
import { Bot } from "@dementevdev/maxbot-ts";

// Только middleware-типы — без остального SDK
import type { Middleware, NextFn } from "@dementevdev/maxbot-ts/middleware";

// Только фильтры
import { hasText, payloadIs } from "@dementevdev/maxbot-ts/filters";

Декларации типов (*.d.ts) включены в каждый sub-entry point.

Versioning (Semver policy)

Тип изменения	Версия	Примеры
Новые публичные методы / опции конфига	minor	`bot.use()`, `BotConfig.onMetrics`, `commandIs()`
Изменение поведения без смены сигнатуры	minor	новый параметр с дефолтом
Breaking change типов публичного API	major	изменение `Context`, `Middleware<Ctx>`
Breaking change рантайм-поведения	major	изменение семантики `next()`, `concurrency`
Bugfixes, внутренние рефакторинги	patch	—

Стабильный API (c v1.0.0):

Bot, BotConfig, Context, EventHandler
MessageContext, CallbackContext, ChatContext, BotStartedContext
ctx.match — результат RegExp capture-групп из hears()/action()
ctx.startPayload — payload из deep link в BotStartedContext
ctx.editMessage(), ctx.deleteMessage(), ctx.sendAction() — редактирование, удаление, действие
bot.onMessage(), bot.onCallback(), bot.onStart(), bot.on(), bot.start(), bot.stop()
bot.command(), bot.hears(), bot.action() — variadic middlewares: bot.command('x', mw1, mw2, handler)
HearsTrigger — массив паттернов: bot.hears([/^\d+$/, 'помощь'], handler) срабатывает на любой из паттернов
polling.allowedUpdates — фильтр типов обновлений
bot.api.*

Experimental (могут поменяться до v2.0.0 minor-версией):

BotMetrics, onMetrics — если понадобится расширить структуру метрик
Filter predicates — могут добавляться новые, сигнатуры существующих стабильны

Лицензия

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 15 Commits
examples		examples
scripts		scripts
src		src
tests/unit		tests/unit
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
tsconfig.base.json		tsconfig.base.json
tsconfig.cjs.json		tsconfig.cjs.json
tsconfig.esm.json		tsconfig.esm.json
tsconfig.json		tsconfig.json
tsconfig.types.json		tsconfig.types.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

@dementevdev/maxbot-ts

Содержание

Установка

Быстрый старт

Стабильность API

Ограничение параллелизма обновлений

Webhook

allowedUpdates — фильтрация типов обновлений

Inline‑клавиатура

Загрузка файлов

Работа с ошибками

Метрики и наблюдаемость

onMetrics — per-update метрики

onSlowHandler — порог по времени

Histogram — гистограмма задержек

Рекомендации по параметру concurrency

bot.use() — глобальные middleware

bot.command() / bot.hears() / bot.action()

Variadic middlewares

ctx.match — capture-группы RegExp

bot.onStart() — deep link и старт бота

ctx.editMessage / ctx.deleteMessage / ctx.sendAction

Filter DSL

Composer — суб-роутер

Базовое использование

Изоляция модулей

Вложенные Composer (under-router)

API

bot.filter() / ctx.has()

bot.filter()

ctx.has()

Расширение контекста (Custom Context)

Паттерны (Patterns)

Паттерн 1: Слоистая middleware-архитектура

Паттерн 2: Переиспользуемые предикаты

Паттерн 3: Корректный graceful shutdown

Migration Guide: от handlers к middleware

Было (handlers-only)

Стало (middleware/composer — те же гарантии, лучший DX)

Локальные примеры

API

Формат contact‑вложения (request_contact)

Формат location‑вложения (request_geo_location)

Sub-entry points (tree-shaking)

Versioning (Semver policy)

Лицензия

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages