@nitra/telegram 1.7.0 → 1.8.0

package/README.md

@@ -12,10 +12,11 @@ bun add @nitra/telegram
 
 Потрібні змінні середовища (перевіряються при імпорті через `@nitra/check-env`):
 
-| Змінна               | Опис                         |
-| -------------------- | ---------------------------- |
-| `TELEGRAM_BOT_TOKEN` | токен бота                   |
-| `TELEGRAM_CHAT_ID`   | id чату/каналу для відправки |
+| Змінна               | Опис                                              |
+| -------------------- | ------------------------------------------------- |
+| `TELEGRAM_BOT_TOKEN` | токен бота                                        |
+| `TELEGRAM_CHAT_ID`   | id чату/каналу для відправки                      |
+| `TELEGRAM_THREAD_ID` | id топіка в супергрупі (опційно, дефолтний топік) |
 
 ## Формат за замовчуванням
 
@@ -48,14 +49,18 @@ await sendMessage('будь-який текст', { parse_mode: '' })
 
 // без звуку
 await sendMessage('тихо', { disable_notification: true })
+
+// у топік супергрупи
+await sendMessage('повідомлення в топік', { message_thread_id: 123 })
 ```
 
 `params`:
 
-| Поле                   | Тип                                          | За замовчуванням | Опис                                    |
-| ---------------------- | -------------------------------------------- | ---------------- | --------------------------------------- |
-| `parse_mode`           | `'MarkdownV2' \| 'Markdown' \| 'HTML' \| ''` | `'MarkdownV2'`   | формат розмітки; `''`/`null` — вимкнути |
-| `disable_notification` | `boolean`                                    | —                | надіслати без звуку                     |
+| Поле                   | Тип                              | За замовчуванням | Опис                                    |
+| ---------------------- | -------------------------------- | ---------------- | --------------------------------------- |
+| `parse_mode`           | `'MarkdownV2' \| 'HTML' \| ''`  | `'MarkdownV2'`   | формат розмітки; `''`/`null` — вимкнути |
+| `message_thread_id`    | `number`                         | `TELEGRAM_THREAD_ID` | id топіка; override для env змінної |
+| `disable_notification` | `boolean`                        | —                | надіслати без звуку                     |
 
 > У робочі години (08:00–18:00) сповіщення зі звуком; поза ними — автоматично тихо.
 > Повідомлення довші за 4096 символів обрізаються.
@@ -68,11 +73,18 @@ await sendDocument(Buffer.from(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`), `disable_notification`. Як і в `sendMessage`, невалідна розмітка caption
-не блокує відправку — повтор без розмітки.
+для `caption`), `message_thread_id`, `disable_notification`. Як і в `sendMessage`,
+невалідна розмітка caption не блокує відправку — повтор без розмітки.
 
 ### `escapeMarkdownV2(text)`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nitra/telegram",
-  "version": "1.7.0",
+  "version": "1.8.0",
   "description": "telegram helper",
   "keywords": [
     "nitra",

package/src/index.js

@@ -6,56 +6,26 @@ 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". Навмисно не
-// застосовується авто до всього тексту, бо це знищило б навмисну розмітку.
+// помилок, змінні) — інакше 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' }
+  if (!raw) return ''
+  const known = { html: 'HTML', markdownv2: 'MarkdownV2' }
   return known[String(raw).toLowerCase()] ?? raw
 }
 
-export const sendMessage = async (text, params) => {
-  const currentHour = new Date().getHours()
-  // 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 (parseMode) {
-    url += `&parse_mode=${parseMode}`
-  }
-
-  // Якщо в неробочий час або відключено сповіщення, то додаємо параметр 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
@@ -63,67 +33,64 @@ 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: '' })
+      return onParseError()
     }
-
-    log.error(data.description, text)
+    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')
-
-  // Додаємо опціональні параметри. parse_mode стосується лише caption,
-  // тож додаємо його тільки коли є підпис.
   if (params.caption) {
     formData.append('caption', params.caption)
-    if (parseMode) {
-      formData.append('parse_mode', parseMode)
-    }
-  }
-
-  // Якщо в неробочий час або відключено сповіщення, то додаємо параметр disable_notification
-  if (!(currentHour >= 8 && currentHour <= 18) || params?.disable_notification === true) {
-    formData.append('disable_notification', 'true')
+    if (parseMode) formData.append('parse_mode', parseMode)
   }
+  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()
-
-    // Як і в 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
-  }
+  return telegramRequest(url, { method: 'POST', body: formData }, {
+    params,
+    parseMode,
+    onParseError: () => sendDocument(document, { ...params, parse_mode: '' }),
+  })
 }