Telegraf.js умер. Как мы оживили фреймворк, переписали ядро на Native Fetch и затащили Bot API 9.6

Каждый, кто пишет Telegram-ботов на Node.js / TypeScript, знает про библиотеку Telegraf.js. Это был стандарт индустрии. Ключевое слово — «был». Оригинальный репозиторий фактически заброшен майнтейнерами, пулл-реквесты годами висят без ответа, а сам фреймворк застрял в прошлом.

Пока Telegram один за другим выкатывает масштабные апдейты (Звёзды, Подарки, Бизнес-аккаунты, Улучшенные медиа), официальный Telegraf не поддерживает ничего из этого.

Мне надоело смотреть на падающие в продакшене боты и городить костыли, поэтому я создал форк — telegraf-hardened ^[1]. На прошлой неделе мы выпустили мажорный релиз v6.0.0. Рассказываю, как под капотом устроена обновленная либа.

Что не так с оригинальным Telegraf.js?

Главная проблема старой библиотеки — её сетевой слой и тотальное игнорирование современных стандартов Node.js. Она до сих пор тянет за собой кучу древних зависимостей вроде node-fetch, abort-controller и sandwich-stream.

Вторая проблема — полное отсутствие архитектурной отказоустойчивости (fail-fast). Бот мог запуститься с битым токеном, никак об этом не сообщить, а упасть в бесконечный цикл перезапусков (crash-loop) только через час, когда прилетит первый запрос или сработает вебхук.

Что я переписал в ядре (Hardened-фичи)

Моей главной задачей было избавление от легаси-мусора и повышение стабильности. Вот что было сделано:

1. Native Node.js Fetch API: Я полностью вырезал node-fetch и сопутствующие обёртки. Теперь ядро работает исключительно на нативном Fetch (начиная с Node.js 18+). Это дало прирост к производительности и убрало лишние уязвимости из supply-chain.

2. Встроенные прокси (SOCKS5/TOR/HTTP): Больше никаких внешних fetch-селекторов. Поддержка прокси теперь работает «из коробки» на базе undici и socks. Настройка инжектится напрямую в клиент.

3. Борьба с 409 Conflict: В Docker или PM2 при быстром перезапуске контейнера Telegram часто возвращает ошибку 409: Conflict (старое соединение еще не закрылось, а новое уже ломится). Раньше бот от этого падал. Я реализовал опциональный экспоненциальный бэкoff (retryOnConflict), который плавно удерживает getUpdates, предотвращая цикличный краш.

4. Fail-Fast валидация: Токен теперь проверяется строго при инициализации конструктора. Добавлен асинхронный метод bot.validateTokenAsync(), который делает пред-запрос к getMe и падает с понятным 401 Unauthorized до того, как бот успеет развернуть невалидный стейт.

Сила опенсорса: Синхронизация с Bot API 9.6

Когда архитектурный фундамент был готов, к проекту подключился крутой зарубежный разработчик Sixia "Leask" Huang (@LeaskH). Он прислал огромный пулл-реквест на 1700+ строк кода, полностью закрыв наш стратегический Roadmap v3.

Совместными усилиями мы затащили в релиз v6.0.0:

• Полный паритет с Telegram Bot API 9.6 (включая методы работы со Звёздами, возвратами платежей, Подарками getUserGifts и методами для Бизнес-аккаунтов).

• Строгую типизацию: Обновили и алиаснули @telegraf-hardened/types. Теперь TypeScript на этапе компиляции бьёт по рукам, если вы пытаетесь передать несовместимые параметры (например, одновременно chat_id и inline_message_id в editMessageText).

• Тесты на дрифт API: Добавили автоматический AVA smoke-тест, который сравнивает текущий рантайм-сёрфейс методов класса Telegram с актуальным массивом типов. Если Telegram добавит метод, а мы его не опишем — тесты упадут в CI.

Как попробовать?

Библиотека является drop-in replacement (бесшовной заменой) для оригинального Телеграфа. Для установки пишем:

Bash

npm install telegraf-hardened

Минимальный пример с новыми фичами API 9.6:

JavaScript

const { Telegraf } = require('telegraf-hardened')

const bot = new Telegraf(process.env.BOT_TOKEN);

(async () => {
    // Fail-fast проверка токена на старте
    await bot.validateTokenAsync()
    
    // Пример обработки подарков из API 9.6
    bot.command('my_gifts', async (ctx) => {
        const { total_count, gifts } = await ctx.telegram.getUserGifts(ctx.from.id)
        return ctx.reply(`У вас ${total_count} подарков!`)
    })
    
    // Включаем устойчивый полинг с защитой от 409 ошибок
    bot.launch({
        polling: {
            retryOnConflict: true,
            maxRetryDelay: 30000
        }
    })
})()

Проект полностью открытый, бесплатный и поддерживается комьюнити. Если вы устали от того, что оригинальный Telegraf.js заброшен — переезжайте на hardened-версию. Будем рады вашим ишью, пулл-реквестам и звёздам на Гитхабе!

Репозиторий проекта на GitHub ^[1]