@nitra/telegram 1.6.0 → 1.7.0

package/README.md

@@ -1 +1,88 @@
 # @nitra/telegram
+
+Мінімальний хелпер для надсилання повідомлень і документів у Telegram.
+
+## Встановлення
+
+```sh
+bun add @nitra/telegram
+```
+
+## Налаштування
+
+Потрібні змінні середовища (перевіряються при імпорті через `@nitra/check-env`):
+
+| Змінна               | Опис                         |
+| -------------------- | ---------------------------- |
+| `TELEGRAM_BOT_TOKEN` | токен бота                   |
+| `TELEGRAM_CHAT_ID`   | id чату/каналу для відправки |
+
+## Формат за замовчуванням
+
+Дефолтний `parse_mode` — **MarkdownV2**. Telegram вимагає екранувати спецсимволи
+`_ * [ ] ( ) ~ \` > # + - = | { } . !`— для динамічного контенту (тексти помилок,
+змінні) використовуйте`escapeMarkdownV2()`:
+
+```js
+import { sendMessage, escapeMarkdownV2 } from '@nitra/telegram'
+
+await sendMessage(`*Помилка:* ${escapeMarkdownV2(err.message)}`)
+```
+
+Якщо розмітка все одно невалідна, повідомлення **не губиться** — бібліотека один раз
+повторює запит без розмітки (plain text).
+
+## API
+
+### `sendMessage(text, params?)`
+
+```js
+// MarkdownV2 (дефолт)
+await sendMessage('*жирний* текст')
+
+// HTML
+await sendMessage('<b>жирний</b>', { parse_mode: 'HTML' })
+
+// без розмітки (plain text)
+await sendMessage('будь-який текст', { parse_mode: '' })
+
+// без звуку
+await sendMessage('тихо', { disable_notification: true })
+```
+
+`params`:
+
+| Поле                   | Тип                                          | За замовчуванням | Опис                                    |
+| ---------------------- | -------------------------------------------- | ---------------- | --------------------------------------- |
+| `parse_mode`           | `'MarkdownV2' \| 'Markdown' \| 'HTML' \| ''` | `'MarkdownV2'`   | формат розмітки; `''`/`null` — вимкнути |
+| `disable_notification` | `boolean`                                    | —                | надіслати без звуку                     |
+
+> У робочі години (08:00–18:00) сповіщення зі звуком; поза ними — автоматично тихо.
+> Повідомлення довші за 4096 символів обрізаються.
+
+### `sendDocument(document, params?)`
+
+```js
+await sendDocument(Buffer.from(csv), {
+  filename: 'report.csv',
+  contentType: 'text/csv',
+  caption: `*Звіт:* ${escapeMarkdownV2('users_2026.csv')}`
+})
+```
+
+`params`: `filename`, `contentType`, `caption`, `parse_mode` (дефолт MarkdownV2, лише
+для `caption`), `disable_notification`. Як і в `sendMessage`, невалідна розмітка caption
+не блокує відправку — повтор без розмітки.
+
+### `escapeMarkdownV2(text)`
+
+Екранує всі зарезервовані символи MarkdownV2. Застосовуйте до **динамічних** частин
+(не до всього повідомлення — інакше зникне навмисна розмітка).
+
+```js
+escapeMarkdownV2('a_b.c!') // → 'a\\_b\\.c\\!'
+```
+
+### `DEFAULT_PARSE_MODE`
+
+Константа з дефолтним форматом (`'MarkdownV2'`).

package/package.json

@@ -1,26 +1,26 @@
 {
   "name": "@nitra/telegram",
+  "version": "1.7.0",
   "description": "telegram helper",
-  "version": "1.6.0",
-  "type": "module",
-  "main": "src/index.js",
-  "files": [
-    "src"
-  ],
-  "exports": {
-    ".": "./src/index.js"
-  },
   "keywords": [
     "nitra",
     "telegram"
   ],
+  "homepage": "https://github.com/nitra/telegram",
+  "bugs": "https://github.com/nitra/telegram/issues",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/nitra/telegram.git"
   },
-  "bugs": "https://github.com/nitra/telegram/issues",
-  "homepage": "https://github.com/nitra/telegram",
-  "license": "MIT",
+  "files": [
+    "src/index.js"
+  ],
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
   "dependencies": {
     "@nitra/check-env": "^4.1.0",
     "@nitra/pino": "^2.8.1"

package/src/index.js

@@ -6,20 +6,46 @@ checkEnv(['TELEGRAM_BOT_TOKEN', 'TELEGRAM_CHAT_ID'])
 
 export const MAX_TELEGRAM_MSG_LENGTH = 4096
 
+// Дефолтний формат повідомлень. Викликач може перевизначити через params.parse_mode
+// ('HTML' | 'Markdown' | 'MarkdownV2'), або вимкнути розмітку ('' / null).
+export const DEFAULT_PARSE_MODE = 'MarkdownV2'
+
+// Екранує спецсимволи MarkdownV2. Застосовувати до ДИНАМІЧНОГО контенту (тексти
+// помилок, змінні) — інакше Telegram падає з "can't parse entities". Навмисно не
+// застосовується авто до всього тексту, бо це знищило б навмисну розмітку.
+export const escapeMarkdownV2 = text => String(text).replaceAll(/[_*[\]()~`>#+\-=|{}.!\\]/g, String.raw`\$&`)
+
+// Дефолт — MarkdownV2; явні '' / null / undefined → без розмітки (plain text).
+const resolveParseMode = params => {
+  const raw = params && 'parse_mode' in params ? params.parse_mode : DEFAULT_PARSE_MODE
+  if (!raw) {
+    return ''
+  }
+  const known = { html: 'HTML', markdown: 'Markdown', markdownv2: 'MarkdownV2' }
+  return known[String(raw).toLowerCase()] ?? raw
+}
+
 export const sendMessage = async (text, params) => {
   const currentHour = new Date().getHours()
-  // if (process.env.TELEGRAM_ROUND_CLOCK || (currentHour >= 8 && currentHour <= 18)) {
   // Max length of a Telegram message is 4096 characters
   if (text.length >= MAX_TELEGRAM_MSG_LENGTH) {
     text = text.slice(0, MAX_TELEGRAM_MSG_LENGTH)
   }
 
+  const parseMode = resolveParseMode(params)
+
+  // Telegram HTML не підтримує <br> (і його варіанти </br>, <br/>) — конвертуємо
+  // у звичайний перенос рядка, інакше парсер падає з "can't parse entities".
+  if (parseMode === 'HTML') {
+    text = text.replaceAll(/<\/?br\s*\/?>/gi, '\n')
+  }
+
   let url = `https://api.telegram.org/bot${env.TELEGRAM_BOT_TOKEN}/sendMessage?chat_id=${
     env.TELEGRAM_CHAT_ID
   }&text=${encodeURIComponent(text)}`
 
-  if (params?.parse_mode?.toLowerCase() === 'html') {
-    url += '&parse_mode=HTML'
+  if (parseMode) {
+    url += `&parse_mode=${parseMode}`
   }
 
   // Якщо в неробочий час або відключено сповіщення, то додаємо параметр disable_notification
@@ -38,6 +64,13 @@ export const sendMessage = async (text, params) => {
   if (res.status >= 400) {
     const data = await res.json()
 
+    // Якщо парсер розмітки не впорався з довільним текстом — повторюємо один раз
+    // як plain text (без parse_mode), щоб повідомлення гарантовано дійшло й не
+    // плодило каскад помилок. Повтор без розмітки вже не дасть "can't parse entities".
+    if (parseMode && /can't parse entities/i.test(data.description ?? '')) {
+      return sendMessage(text, { ...params, parse_mode: '' })
+    }
+
     log.error(data.description, text)
     return false
   }
@@ -45,6 +78,7 @@ export const sendMessage = async (text, params) => {
 
 export const sendDocument = async (document, params = {}) => {
   const currentHour = new Date().getHours()
+  const parseMode = resolveParseMode(params)
 
   const formData = new FormData()
   formData.append('chat_id', env.TELEGRAM_CHAT_ID)
@@ -53,13 +87,13 @@ export const sendDocument = async (document, params = {}) => {
   const blob = new Blob([document], { type: params.contentType || 'application/octet-stream' })
   formData.append('document', blob, params.filename || 'document.txt')
 
-  // Додаємо опціональні параметри
+  // Додаємо опціональні параметри. parse_mode стосується лише caption,
+  // тож додаємо його тільки коли є підпис.
   if (params.caption) {
     formData.append('caption', params.caption)
-  }
-
-  if (params.parse_mode) {
-    formData.append('parse_mode', params.parse_mode)
+    if (parseMode) {
+      formData.append('parse_mode', parseMode)
+    }
   }
 
   // Якщо в неробочий час або відключено сповіщення, то додаємо параметр disable_notification
@@ -82,6 +116,13 @@ export const sendDocument = async (document, params = {}) => {
 
   if (res.status >= 400) {
     const data = await res.json()
+
+    // Як і в sendMessage — невалідна розмітка caption не має блокувати відправку
+    // документа: повторюємо один раз без parse_mode.
+    if (parseMode && params.caption && /can't parse entities/i.test(data.description ?? '')) {
+      return sendDocument(document, { ...params, parse_mode: '' })
+    }
+
     log.error(data.description)
     return false
   }