Фрагмент 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…