@nitra/telegram 1.6.0 → 1.8.0

package/README.md

@@ -1 +1,100 @@
 # @nitra/telegram
+
+Мінімальний хелпер для надсилання повідомлень і документів у Telegram.
+
+## Встановлення
+
+```sh
+bun add @nitra/telegram
+```
+
+## Налаштування
+
+Потрібні змінні середовища (перевіряються при імпорті через `@nitra/check-env`):
+
+| Змінна               | Опис                                              |
+| -------------------- | ------------------------------------------------- |
+| `TELEGRAM_BOT_TOKEN` | токен бота                                        |
+| `TELEGRAM_CHAT_ID`   | id чату/каналу для відправки                      |
+| `TELEGRAM_THREAD_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 })
+
+// у топік супергрупи
+await sendMessage('повідомлення в топік', { message_thread_id: 123 })
+```
+
+`params`:
+
+| Поле                   | Тип                              | За замовчуванням | Опис                                    |
+| ---------------------- | -------------------------------- | ---------------- | --------------------------------------- |
+| `parse_mode`           | `'MarkdownV2' \| 'HTML' \| ''`  | `'MarkdownV2'`   | формат розмітки; `''`/`null` — вимкнути |
+| `message_thread_id`    | `number`                         | `TELEGRAM_THREAD_ID` | id топіка; override для env змінної |
+| `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')}`
+})
+
+// у топік супергрупи
+await sendDocument(Buffer.from(csv), {
+  filename: 'report.csv',
+  contentType: 'text/csv',
+  message_thread_id: 123
+})
+```
+
+`params`: `filename`, `contentType`, `caption`, `parse_mode` (дефолт MarkdownV2, лише
+для `caption`), `message_thread_id`, `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.8.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,30 +6,26 @@ checkEnv(['TELEGRAM_BOT_TOKEN', 'TELEGRAM_CHAT_ID'])
 
 export const MAX_TELEGRAM_MSG_LENGTH = 4096
 
-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)
-  }
-
-  let url = `https://api.telegram.org/bot${env.TELEGRAM_BOT_TOKEN}/sendMessage?chat_id=${
-    env.TELEGRAM_CHAT_ID
-  }&text=${encodeURIComponent(text)}`
+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', markdownv2: 'MarkdownV2' }
+  return known[String(raw).toLowerCase()] ?? raw
+}
 
-  if (params?.parse_mode?.toLowerCase() === 'html') {
-    url += '&parse_mode=HTML'
-  }
-
-  // Якщо в неробочий час або відключено сповіщення, то додаємо параметр disable_notification
-  if (!(currentHour >= 8 && currentHour <= 18) || params?.disable_notification === true) {
-    url += '&disable_notification=true'
-  }
+const isWorkingHour = () => { const h = new Date().getHours(); return h >= 8 && h <= 18 }
 
+const telegramRequest = async (url, init, { params, parseMode, onParseError }) => {
   let res
   try {
-    res = await fetch(url)
+    res = await fetch(url, init)
   } catch (error) {
     log.error(error)
     return false
@@ -37,52 +33,64 @@ export const sendMessage = async (text, params) => {
 
   if (res.status >= 400) {
     const data = await res.json()
-
-    log.error(data.description, text)
+    if (parseMode && /can't parse entities/i.test(data.description ?? '')) {
+      return onParseError()
+    }
+    log.error(data.description)
     return false
   }
 }
 
+const resolveCommonParams = params => ({
+  threadId: params?.message_thread_id ?? env.TELEGRAM_THREAD_ID,
+  silent: !isWorkingHour() || params?.disable_notification === true,
+})
+
+export const sendMessage = async (text, params) => {
+  if (text.length >= MAX_TELEGRAM_MSG_LENGTH) {
+    text = text.slice(0, MAX_TELEGRAM_MSG_LENGTH)
+  }
+
+  const parseMode = resolveParseMode(params)
+  const { threadId, silent } = resolveCommonParams(params)
+
+  // Telegram HTML не підтримує <br> — конвертуємо у перенос рядка.
+  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 (parseMode) url += `&parse_mode=${parseMode}`
+  if (threadId) url += `&message_thread_id=${threadId}`
+  if (silent) url += '&disable_notification=true'
+
+  return telegramRequest(url, undefined, {
+    params,
+    parseMode,
+    onParseError: () => sendMessage(text, { ...params, parse_mode: '' }),
+  })
+}
+
 export const sendDocument = async (document, params = {}) => {
-  const currentHour = new Date().getHours()
+  const parseMode = resolveParseMode(params)
+  const { threadId, silent } = resolveCommonParams(params)
 
   const formData = new FormData()
   formData.append('chat_id', env.TELEGRAM_CHAT_ID)
+  formData.append('document', new Blob([document], { type: params.contentType || 'application/octet-stream' }), params.filename || 'document.txt')
 
-  // Додаємо документ як Blob з параметрами
-  const blob = new Blob([document], { type: params.contentType || 'application/octet-stream' })
-  formData.append('document', blob, params.filename || 'document.txt')
-
-  // Додаємо опціональні параметри
   if (params.caption) {
     formData.append('caption', params.caption)
+    if (parseMode) formData.append('parse_mode', parseMode)
   }
-
-  if (params.parse_mode) {
-    formData.append('parse_mode', params.parse_mode)
-  }
-
-  // Якщо в неробочий час або відключено сповіщення, то додаємо параметр disable_notification
-  if (!(currentHour >= 8 && currentHour <= 18) || params?.disable_notification === true) {
-    formData.append('disable_notification', 'true')
-  }
+  if (threadId) formData.append('message_thread_id', String(threadId))
+  if (silent) formData.append('disable_notification', 'true')
 
   const url = `https://api.telegram.org/bot${env.TELEGRAM_BOT_TOKEN}/sendDocument`
 
-  let res
-  try {
-    res = await fetch(url, {
-      method: 'POST',
-      body: formData
-    })
-  } catch (error) {
-    log.error(error)
-    return false
-  }
-
-  if (res.status >= 400) {
-    const data = await res.json()
-    log.error(data.description)
-    return false
-  }
+  return telegramRequest(url, { method: 'POST', body: formData }, {
+    params,
+    parseMode,
+    onParseError: () => sendDocument(document, { ...params, parse_mode: '' }),
+  })
 }