Фрагмент Markdown с жирным, курсивом, кодом, цитатой и ссылкой и сообщение Telegram, которым он становится

Библиотека на TypeScript для Telegram-ботов, которые отвечают в Markdown, обычно написанном LLM. Она превращает Markdown в сообщение, которое Telegram примет: без ручного экранирования, без форматирования, которое ломается посреди ответа, и без сообщений, отклонённых из-за одного лишнего символа.

Я написал её для своего бота, который отправляет ответы LLM и обычными сообщениями, и новыми rich-сообщениями Telegram.

Что она делает

Один текст в Markdown, все форматы, которые принимает Telegram:

  • Entities: обычный текст и список сущностей форматирования для sendMessage. parse_mode нет, поэтому и экранировать нечего.
  • Rich-сообщения для sendRichMessage (Bot API 10.1+): настоящие заголовки, таблицы, чекбоксы, формулы, сноски и медиа.
  • MarkdownV2 для мест, где принимается только строка с parse_mode.
  • Страницы Telegraph для текстов, слишком длинных для чата.

У каждого формата есть сплиттер, который режет длинный ответ на сообщения в пределах лимитов Telegram, а помощники для стриминга показывают ответ, пока LLM его ещё пишет, с кнопкой остановки из Bot API 10.3.

Основана на библиотеке для Python

Это порт на TypeScript библиотеки telegramify-markdown на Python от sudoskys, и он следует за её релизами. Перенесено всё, кроме отрисовки диаграмм Mermaid.

Нативный парсер на Rust

Markdown разбирает pulldown-cmark, парсер CommonMark на Rust. Библиотека на Python использует тот же парсер через свои Python-биндинги, а здесь он скомпилирован в нативный модуль Node.js через N-API. Разбор идёт в нативном коде, а TypeScript только обходит события парсера и отрисовывает их. Строки JavaScript считают кодовые единицы UTF-16, как и смещения сущностей Telegram, так что пересчитывать смещения тоже не нужно.

Готовые бинарники собираются для семи платформ: macOS (Intel и Apple silicon), Windows x64 и Linux x64 и arm64 с glibc или musl (Alpine). Установка сама выбирает нужный, на остальных платформах его собирают из исходников.

Проверена на Telegram

Сверх порта в ней больше 300 тестов, а живые тесты отправляют настоящие сообщения через Bot API и проверяют, что Telegram их принимает. Вывод следует API Telegram буквально: rich-сообщения используют собственные имена полей Telegram (незнакомые поля Telegram молча игнорирует), разбиение считает блоки и медиа так же, как Telegram, а смещения сущностей остаются верными после нелатинского текста. Она поддерживает Bot API 10.4.

Установка

Она ставится с GitHub, а не из реестра npm. Команда, требования и замечания о платформах — в разделе Installation в README.

import { convert } from 'tg-md-msg';

const { text, entities } = convert('**Hello** from `tg-md-msg`');
await bot.api.sendMessage(chatId, text, { entities });

Нужен Node.js 18 или новее, только ESM. Код открыт (MIT): github.com/podgorniy/ts-md-msg.

Исходный код на GitHub

Обсуждение

Комментарии загружаются с remark42.podgorniy.net…