tg-md-msg
Отправка Markdown, обычно ответов LLM, в 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.