Puregram: типобезопасный SDK для Telegram-ботов на Node.js

Puregram — библиотека для создания Telegram-ботов на Node.js и TypeScript. Она дает типизированный доступ к Telegram Bot API, обработку обновлений, middleware, polling, webhooks и систему расширений. При этом Puregram не пытается заранее решить за разработчика, как должны быть устроены команды, модули и хранилище.

Если нужен современный Telegram-бот на TypeScript, эту библиотеку стоит рассмотреть как модульный SDK, а не как «магический» фреймворк.

Хорошая библиотека не отменяет архитектуру. Она делает правильные решения проще, а неправильные — заметнее.

Что такое Puregram

Puregram работает поверх Telegram Bot API и превращает его методы и обновления в удобные TypeScript-объекты. Когда пользователь пишет боту, Telegram присылает update — событие, например сообщение, нажатие inline-кнопки или inline-запрос.

Puregram принимает это событие, создает типизированный объект, пропускает его через цепочку middleware и передает подходящему обработчику. Ответ можно отправить привычным вызовом message.send(), через короткий метод клиента или через точный метод API.

Именно поэтому Puregram называют SDK, а не полноценным application framework. В ядре есть транспорт, dispatch, фильтры, middleware, hooks и плагины. Сессии, сцены, flow, rate limit и хранилища подключаются отдельно.

SDK оставляет разработчику больше решений, чем крупный фреймворк с готовой структурой проекта. Это удобно, если вы хотите собрать приложение под себя, но требует понимать, какие компоненты действительно нужны.

Три уровня API

В Puregram можно выбрать уровень абстракции под конкретную задачу:

Контекстный API обычно читается проще всего: объект сообщения уже знает, куда отправлять ответ. Сгенерированный API ближе к документации Telegram и полезен в инфраструктурном коде. Универсальный api.call() остается запасным выходом, если для нового или динамического метода еще нет удобной оболочки.

Чем Puregram не является

Puregram не навязывает:

• единственный способ описывать команды;
• обязательную систему dependency injection;
• встроенное хранилище;
• FSM в ядре;
• монолитную структуру проекта;
• конкретный HTTP-фреймворк.

Это не недостаток само по себе. Для небольшого бота готовый фреймворк может привести к результату быстрее. Для растущего TypeScript-проекта полезнее бывает модульность: нужные функции подключаются явно, а ненужные не становятся обязательными зависимостями.

Как устроена обработка обновления

Общий путь выглядит так:

Telegram → polling или webhook → типизированный update → фильтры и middleware → обработчик → запрос к Telegram API

Транспорт и бизнес-логика разделены. Поэтому обработчик сообщения не обязан знать, пришло ли событие через long polling или HTTP webhook.

Диспетчеры и фильтры

Для разных типов событий есть отдельные обработчики: onMessage, onCallbackQuery, onInlineQuery и другие. Это позволяет не писать один большой switch по всем вариантам Telegram update.

Фильтры проверяют тип события, команду, текст, чат и другие признаки. После успешной проверки TypeScript может сузить тип объекта. В результате ошибка вроде «у этого update нет поля, которое я пытаюсь прочитать» обнаруживается раньше запуска бота.

Middleware

Middleware образуют цепочку обработки. Вызов next() передает управление следующему middleware или обработчику. Если next() не вызвать, распространение update останавливается.

Такая onion-модель подходит для логирования, авторизации, метрик, корреляционных идентификаторов и ограничения доступа:

telegram.use(async (update, next) => {
  const startedAt = performance.now()

  try {
    await next()
  } finally {
    const duration = performance.now() - startedAt

    console.log({
      updateId: update.updateId,
      duration
    })
  }
})

Middleware можно использовать и как пропускной пункт. Например, сначала проверить пользователя в базе, а затем передать update дальше только разрешенной группе. Это место для политики доступа, а не повод дублировать проверку в каждом обработчике.

Long polling и webhooks

Polling поддерживает параллельную обработку. Если сообщения одного чата должны идти строго по порядку, можно сериализовать их по ключу, например по chat_id, не делая последовательным весь бот.

Установка и первый бот

Что требуется

Для Puregram v3 нужны:

• Node.js 22 или новее;
• ESM-проект;
• TypeScript с современным разрешением модулей, если вы используете TypeScript;
• токен бота, созданный через BotFather.

CommonJS в v3 не поддерживается. Для базовой работы отдельный HTTP-клиент не нужен: современный Node.js уже предоставляет fetch.

Установка

npm install puregram

Для других менеджеров пакетов:

pnpm add puregram

yarn add puregram

Минимальный package.json должен включать ESM-режим:

{
  "type": "module",
  "scripts": {
    "dev": "tsx src/bot.ts",
    "start": "node dist/bot.js"
  }
}

Для запуска TypeScript без отдельной сборки можно добавить tsx:

npm install --save-dev typescript tsx @types/node

Минимальный бот

В этом примере нет роутера, базы данных и отдельного сервера. Он показывает базовую идею: создать клиент, зарегистрировать обработчик и запустить получение updates.

В production токен храните в переменной окружения или секретном хранилище. Не записывайте его в репозиторий и не вставляйте в исходный код.

Минимальный чек-лист перед первым запуском

• Выбрана поддерживаемая версия Node.js.
• Проект работает в ESM-режиме.
• Токен не хранится в Git.
• Обработчик проверен на тестовом боте.
• Продуманы логи, обработка ошибок и повторные попытки.

Какие модули подключать

Встроенное ядро закрывает базовый путь от update до ответа. Остальные задачи разделены на официальные пакеты:

Не нужно устанавливать все пакеты сразу. Сначала определите сценарий:

• нужен простой бот — начните с puregram;
• нужны кнопки — добавьте @puregram/markup;
• нужно безопасно разбирать callback data — добавьте @puregram/callback-data;
• нужен диалог — смотрите в сторону @puregram/flow или @puregram/scenes;
• нужно сохранять состояние — добавьте @puregram/session и подходящее хранилище;
• нужны лимиты — разделите входной @puregram/rate-limit и исходящий @puregram/throttler.

Контекстный API помогает писать обработчики короче, но структура приложения всё равно остается вашей ответственностью.

Что на Puregram можно построить

Обычный бот с командами и сообщениями

Для небольшого бота достаточно нескольких диспетчеров, фильтров и контекстных методов. Команды, бизнес-правила и формат ответа можно держать в отдельных модулях, не смешивая их с транспортом.

Inline-кнопки и callback data

Связка @puregram/markup и @puregram/callback-data подходит для:

• пагинации каталогов;
• подтверждения опасных операций;
• выбора настроек;
• inline-меню;
• административных панелей внутри Telegram.

Хорошая практика — кодировать в callback data только короткий идентификатор действия и нужный контекст, а подробные данные читать из базы. Это сохраняет кнопку компактной и уменьшает риск доверять устаревшему payload.

Анкеты и многошаговые процессы

Для onboarding, заявки, заказа или анкеты есть несколько уровней:

• @puregram/flow — когда сценарий удобно описать как последовательность ожиданий;
• @puregram/scenes — когда приложение состоит из переходов между сценами;
• @puregram/session и @puregram/storage — когда состояние нужно сохранить между updates.

Важный момент: эти возможности не находятся в ядре. Это плюс для модульного проекта, но вам придется заранее выбрать модель состояния и политику ее хранения.

Ограничение нагрузки

Telegram может ответить ошибкой 429, если бот отправляет слишком много запросов. Для этой зоны есть rate limit, throttler и повтор после flood wait.

Автоматическая повторная попытка не заменяет очередь и идемпотентность. Если одна и та же операция меняет данные, сначала решите, как отличить безопасный повтор от повторного побочного эффекта.

Coding agents и skills

У Puregram есть отдельный репозиторий skills для coding agents. Это инструкции и lookup-инструменты, которые помогают агенту сверяться с установленной версией API и официальных пакетов.

Такой набор полезен, когда разработчик использует Codex, Claude Code, Cursor или другую среду со skills. Но сгенерированный код все равно нужно проверить компилятором и тестами.

Почему TypeScript здесь имеет смысл

Можно писать на JavaScript, но сильная сторона Puregram раскрывается в TypeScript:

• методы и параметры отражают контракт Telegram Bot API;
• объекты разных типов update не смешиваются без явного приведения;
• фильтры помогают сузить тип;
• опечатки в названиях и параметрах находятся до запуска;
• IDE показывает доступные методы и поля.

Это не отменяет runtime-проверки. Telegram может вернуть ошибку из-за прав бота, лимита, состояния чата или неверных данных. Типы помогают не передать очевидно неправильную структуру, но не могут проверить внешний мир.

TypeScript уменьшает класс ошибок, а не обещает отсутствие всех ошибок.

Как подключаются плагины

Расширения подключаются явно через telegram.extend(plugin). Плагин может добавлять методы, API, hooks или логику жизненного цикла. Puregram учитывает зависимости между плагинами и может обнаружить отсутствующую зависимость, конфликт или цикл.

Это лучше воспринимать как договор между компонентами:

1. приложение явно подключает расширение; 2. расширение объявляет, от чего зависит; 3. Puregram проверяет порядок и совместимость; 4. код получает добавленную возможность через понятный API.

Явный плагин читается лучше, чем скрытая магия, которая меняет поведение клиента при одном импорте.

Puregram, Telegraf, grammY или aiogram

У этих библиотек разные исходные идеи. Сравнивать их только по длине примера несправедливо.

Puregram не обязан быть лучшим выбором для каждого проекта. Если команда уже пишет на Python, aiogram будет естественнее. Если важнее большое количество готовых рецептов, Telegraf или grammY могут сократить путь до первой версии. Если нужен Node.js, TypeScript и явная модульная архитектура, Puregram выглядит логичным кандидатом.

Как сравнить библиотеки честно

Если выбор влияет на production, соберите одинаковый прототип на двух-трех вариантах и измерьте:

• время запуска;
• задержки p50, p95 и p99;
• потребление памяти;
• нагрузку CPU;
• скорость обработки burst-нагрузки;
• долю ошибок;
• размер очереди при ограничении Telegram API;
• удобство тестирования и сопровождения.

Сетевую задержку Telegram отделяйте от overhead библиотеки. Для этого можно записывать updates, воспроизводить их локально и направлять исходящие запросы в mock-сервер.

Сильные стороны и ограничения

Что может понравиться

• Точная типизация вокруг Telegram Bot API.
• Модульность: сессии, сцены и лимиты подключаются по необходимости.
• Явная плагинная модель с зависимостями и lifecycle hooks.
• Несколько уровней API — от message.send() до низкоуровневого метода.
• Middleware, фильтры, приоритеты и hooks для наблюдаемой обработки.
• Polling и webhooks для разных вариантов развертывания.
• Небольшое ядро без обязательного набора runtime-зависимостей.

Что нужно принять

• Node.js 22+ и ESM исключают часть старых проектов без миграции.
• Готовых сторонних решений и учебных материалов меньше, чем у более популярных библиотек.
• Архитектуру команд, доменные модули, dependency injection и хранение состояния нужно продумать самостоятельно.
• Переход с Puregram v2 на v3 несовместимый: автоматического codemod и режима совместимости нет.
• Публичных сопоставимых benchmark’ов нет.
• Официальные модули нужно фиксировать в lock-файле и проверять вместе с версией ядра.

Кому подойдет Puregram

Puregram стоит рассматривать, если:

• проект начинается на современном Node.js и TypeScript;
• команда хочет опираться на точные типы Telegram Bot API;
• бот будет расти и делиться на доменные модули;
• middleware, hooks и observability важны с самого начала;
• нужно самостоятельно выбрать storage, модель состояний и транспорт;
• команда готова поддерживать lock-файл и проверять официальные пакеты вместе.

Не обязательно выбирать Puregram, если:

• основной язык команды — Python;
• приложение должно использовать CommonJS без миграции;
• нужен самый короткий путь к первой команде и максимум готовых рецептов;
• команде не хочется проектировать state management и структуру модулей.

Частые вопросы

Что читать дальше

• Официальный сайт Puregram
• Документация Puregram
• Репозиторий puregram/puregram
• Официальные примеры
• Репозиторий skills
• Telegram Bot API
• Документация Telegraf
• Документация grammY
• Документация aiogram

Puregram — не кнопка «сделать бота автоматически». Это аккуратный типизированный слой над Telegram, который дает Node.js/TypeScript-разработчику выбор: писать коротко через контекст, работать точно через API или собрать собственную архитектуру из официальных модулей.