@dementevdev/maxbot-ts 1.0.0

package/README.md

@@ -0,0 +1,1176 @@
+# @dementevdev/maxbot-ts
+
+TypeScript SDK для MAX Bot API.
+
+- Базовый URL: <https://platform-api.max.ru>
+- Node.js >= 18 (встроенный fetch)
+
+## Содержание
+
+**Начало работы**
+
+- [Установка](#установка)
+- [Быстрый старт](#быстрый-старт)
+- [Стабильность API](#стабильность-api)
+
+**Конфигурация**
+
+- [Ограничение параллелизма](#ограничение-параллелизма-обновлений)
+- [Webhook](#webhook)
+- [allowedUpdates — фильтрация типов обновлений](#allowedupdates--фильтрация-типов-обновлений)
+
+**Возможности**
+
+- [Inline‑клавиатура](#inline-клавиатура)
+- [Загрузка файлов](#загрузка-файлов)
+- [Работа с ошибками](#работа-с-ошибками)
+- [Метрики и наблюдаемость](#метрики-и-наблюдаемость)
+- [Рекомендации по concurrency](#рекомендации-по-параметру-concurrency)
+
+**Маршрутизация**
+
+- [Middleware-пайплайн](#bot-use--глобальные-middleware)
+- [Filter DSL](#filter-dsl)
+- [Composer — суб-роутер](#composer--суб-роутер)
+- [bot.filter() / ctx.has()](#botfilter--ctxhas)
+
+**Продвинутое использование**
+
+- [Расширение контекста](#расширение-контекста-custom-context)
+- [Паттерны](#паттерны-patterns)
+- [Migration Guide](#migration-guide-от-handlers-к-middleware)
+
+**Справочник**
+
+- [Локальные примеры](#локальные-примеры)
+- [API](#api)
+- [Форматы вложений](#формат-contact-вложения-request_contact)
+- [Sub-entry points](#sub-entry-points-tree-shaking)
+- [Versioning](#versioning-semver-policy)
+
+---
+
+## Установка
+
+```bash
+npm i @dementevdev/maxbot-ts
+```
+
+## Быстрый старт
+
+```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](#webhook) ниже.
+
+## Стабильность API
+
+Пакет следует [SemVer](https://semver.org/). Список **стабильных** экспортов с 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](#versioning-semver-policy) в конце документа.
+
+---
+
+## Ограничение параллелизма обновлений
+
+По умолчанию бот обрабатывает не более 10 обновлений одновременно (`concurrency: 10`).
+Это защищает от burst-нагрузки: новые обновления ждут в очереди, а не запускают
+неограниченное число параллельных промисов.
+
+```ts
+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
+
+```ts
+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` позволяет
+указать только нужные — сервер не будет отправлять остальные, снижая трафик.
+
+```ts
+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‑клавиатура
+
+```ts
+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 ГБ
+- Можно загружать только один файл за раз
+
+```ts
+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      |
+
+```ts
+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 метрики
+
+```ts
+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 — порог по времени
+
+```ts
+// Срабатывает только если 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 в любую систему мониторинга.
+
+```ts
+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);
+```
+
+**Кастомные корзины** — передайте массив границ в мс:
+
+```ts
+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`:
+
+```ts
+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`             | Не рекомендуется в проде           |
+
+**Как определить правильное значение:**
+
+1. Запустите с `onMetrics` и наблюдайте `queueSizeAtStart`
+2. Если очередь стабильно > 0 — увеличьте `concurrency`
+3. Если растут ошибки downstream API — уменьшите
+4. Ориентир: `concurrency ≈ (среднее время handler) / (желаемая latency) × throughput`
+
+```ts
+// Диагностика: подбор 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
+
+```ts
+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()
+
+```ts
+// Команды (срабатывает на /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()`, иначе цепочка прерывается.
+
+```ts
+// 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`.
+
+```ts
+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-флоу и контекстного запуска.
+
+```ts
+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`.
+
+```ts
+// ── 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:
+
+```ts
+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`.
+
+### Базовое использование
+
+```ts
+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`:
+
+```ts
+// 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)
+
+```ts
+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 только для контекстов, удовлетворяющих предикату. Несовпадающие обновления прозрачно перетекают к следующим обработчикам.
+
+```ts
+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()
+
+Проверить тип контекста прямо внутри обработчика с автоматическим сужением типа:
+
+```ts
+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`.
+
+```ts
+bot.onStart(async (ctx) => {
+  if (ctx.has(isPrivateChat)) {
+    // обрабатываем только приватный старт
+  }
+});
+```
+
+---
+
+## Расширение контекста (Custom Context)
+
+```ts
+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-архитектура
+
+```ts
+// 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: Переиспользуемые предикаты
+
+```ts
+// 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
+
+```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("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)
+
+```ts
+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)
+
+```ts
+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).
+
+Для запуска примеров локально:
+
+```bash
+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.*`
+
+Полные типы экспортируются из пакета:
+
+```ts
+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` доступны как отдельные точки входа — они **не попадают в бандл** тех, кто их не импортирует:
+
+```ts
+// Только 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](./LICENSE)