@goodandready/dsh-messenger-gateway 0.3.22 → 0.4.1

package/LICENSE

@@ -18,4 +18,4 @@ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
 AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
 LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+SOFTWARE.

package/cordis.patch.yml

@@ -1,4 +1,4 @@
 - insert:
     - id: dsh-messenger-gateway
       name: '@goodandready/dsh-messenger-gateway'
-      config: {}
+      config: {}

package/lib/adapters/discord.js

@@ -190,4 +190,4 @@ export class DiscordAdapter {
     const json = typeof res.json === 'function' ? await res.json().catch(() => ({})) : {}
     return { ok: true, messageId: json?.id }
   }
-}
+}

package/lib/adapters/slack.js

@@ -154,4 +154,4 @@ export class SlackAdapter {
     }
     return { ok: true }
   }
-}
+}

package/lib/adapters/telegram-inbound.js

@@ -0,0 +1,141 @@
+import { basename } from 'node:path'
+import {
+  IMAGE_EXT_TO_MIME, VIDEO_EXT_TO_MIME, classifyDocument,
+  extOf, TELEGRAM_MAX_DOC_BYTES,
+} from '../media.js'
+import { TEXT_INJECT_EXTS } from '../documents.js'
+
+export async function extractTelegramInboundMedia(adapter, msg, initialText, maxDocBytes = TELEGRAM_MAX_DOC_BYTES, maxTextInjectBytes = 100 * 1024) {
+  let text = initialText || ''
+  const attachments = []
+
+    if (msg.photo?.length) {
+      const largest = msg.photo[msg.photo.length - 1]
+      const { path, file } = await adapter.downloadByFileId(largest.file_id, 'photo', extOf('', '') || '.jpg')
+      const ext = extOf(file.file_path, '') || '.jpg'
+      attachments.push({ kind: 'photo', path, mime: IMAGE_EXT_TO_MIME[ext] || 'image/jpeg' })
+    }
+    if (msg.sticker) {
+      const st = msg.sticker
+      if (st.is_video) {
+        try {
+          const { path } = await adapter.downloadByFileId(st.file_id, 'sticker-video', '.webm', st.file_unique_id || '')
+          attachments.push({ kind: 'animation', path, mime: 'video/webm', emoji: st.emoji || '', name: `sticker${st.emoji || ''}.webm` })
+          if (st.emoji) text = `${text}\n[Video sticker ${st.emoji}]`.trim()
+        } catch (e) {
+          text = `${text}\n[Video sticker ${st.emoji || ''} (download failed: ${e.message})]`.trim()
+        }
+      } else if (st.is_animated) {
+        try {
+          const { path } = await adapter.downloadByFileId(st.file_id, 'sticker-anim', '.tgs', st.file_unique_id || '')
+          attachments.push({ kind: 'document', path, mime: 'application/x-tgsticker', emoji: st.emoji || '', name: `sticker${st.emoji || ''}.tgs` })
+          if (st.emoji) text = `${text}\n[Animated sticker ${st.emoji}]`.trim()
+        } catch (e) {
+          text = `${text}\n[Animated sticker ${st.emoji || ''} (download failed: ${e.message})]`.trim()
+        }
+      } else {
+        const { path } = await adapter.downloadByFileId(st.file_id, 'sticker', '.webp', st.file_unique_id || '')
+        attachments.push({ kind: 'sticker', path, mime: 'image/webp', emoji: st.emoji || '', name: `sticker${st.emoji || ''}.webp` })
+      }
+    }
+    if (msg.voice) {
+      const { path } = await adapter.downloadByFileId(msg.voice.file_id, 'voice', '.ogg')
+      attachments.push({ kind: 'voice', path, mime: 'audio/ogg' })
+    }
+    if (msg.audio) {
+      const ext = extOf(msg.audio.file_name, msg.audio.mime_type) || '.mp3'
+      const { path } = await adapter.downloadByFileId(msg.audio.file_id, 'audio', ext, msg.audio.file_name || '')
+      attachments.push({ kind: 'audio', path, mime: msg.audio.mime_type || 'audio/mpeg' })
+    }
+    if (msg.video) {
+      const ext = extOf(msg.video.file_name, msg.video.mime_type) || '.mp4'
+      if ((msg.video.file_size || 0) > maxDocBytes) {
+        text = `${text}\n[Video too large]`.trim()
+      } else {
+        const { path } = await adapter.downloadByFileId(msg.video.file_id, 'video', ext, msg.video.file_name || '')
+        attachments.push({ kind: 'video', path, mime: msg.video.mime_type || VIDEO_EXT_TO_MIME[ext] || 'video/mp4', name: msg.video.file_name || basename(path) })
+      }
+    }
+    if (msg.video_note) {
+      const vn = msg.video_note
+      if ((vn.file_size || 0) > maxDocBytes) {
+        text = `${text}\n[Video note too large]`.trim()
+      } else {
+        const { path } = await adapter.downloadByFileId(vn.file_id, 'videonote', '.mp4')
+        attachments.push({ kind: 'video', path, mime: 'video/mp4', name: 'video_note.mp4' })
+      }
+    }
+    if (msg.animation) {
+      const an = msg.animation
+      const ext = extOf(an.file_name, an.mime_type) || '.mp4'
+      if ((an.file_size || 0) > maxDocBytes) {
+        text = `${text}\n[Animation too large]`.trim()
+      } else {
+        const { path } = await adapter.downloadByFileId(an.file_id, 'anim', ext, an.file_name || '')
+        attachments.push({ kind: 'animation', path, mime: an.mime_type || 'video/mp4', name: an.file_name || basename(path) })
+      }
+    }
+    if (msg.document) {
+      const doc = msg.document
+      const ext = extOf(doc.file_name, doc.mime_type)
+      const kind = classifyDocument(ext, doc.mime_type)
+      if (doc.file_size > maxDocBytes) {
+        text = `${text}\n[Document too large: ${doc.file_name || 'file'}]`.trim()
+      } else if (kind === 'unsupported') {
+        const { path } = await adapter.downloadByFileId(doc.file_id, 'doc', ext, doc.file_name || '')
+        attachments.push({ kind: 'document', path, mime: doc.mime_type || 'application/octet-stream', name: doc.file_name || basename(path) })
+      } else {
+        const { path, bytes } = await adapter.downloadByFileId(doc.file_id, 'doc', ext, doc.file_name || '')
+        if (kind === 'image') attachments.push({ kind: 'photo', path, mime: IMAGE_EXT_TO_MIME[ext] || doc.mime_type || 'image/jpeg', name: doc.file_name })
+        else if (kind === 'video') attachments.push({ kind: 'video', path, mime: VIDEO_EXT_TO_MIME[ext] || doc.mime_type || 'video/mp4', name: doc.file_name })
+        else if (bytes.length <= maxTextInjectBytes && TEXT_INJECT_EXTS.has(ext)) {
+          const body = new TextDecoder('utf-8', { fatal: false }).decode(bytes).slice(0, maxTextInjectBytes)
+          text = `${text}\n\n[Document ${doc.file_name}]\n${body}`.trim()
+        } else attachments.push({ kind: 'document', path, mime: doc.mime_type || 'application/octet-stream', name: doc.file_name || basename(path) })
+      }
+    }
+
+
+  return { text, attachments }
+}
+
+export async function probeTelegramHealth(adapter, timeoutMs = 10000) {
+  if (!adapter.token) {
+    return { ok: false, error: 'Telegram bot token is empty' }
+  }
+  const start = Date.now()
+  try {
+    const res = await fetch(`https://api.telegram.org/bot${adapter.token}/getMe`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({}),
+      signal: AbortSignal.timeout(Math.max(1000, Number(timeoutMs) || 10000)),
+    })
+    const latencyMs = Date.now() - start
+    const json = await res.json().catch(() => ({}))
+    if (!res.ok || json.ok === false) {
+      return {
+        ok: false,
+        latencyMs,
+        error: json.description || `HTTP ${res.status}`,
+      }
+    }
+    const me = json.result || {}
+    adapter.botId = Number(me.id) || adapter.botId
+    adapter.botUsername = String(me.username || adapter.botUsername)
+    return {
+      ok: true,
+      latencyMs,
+      botId: adapter.botId,
+      botUsername: adapter.botUsername,
+      firstName: me.first_name || '',
+    }
+  } catch (err) {
+    return {
+      ok: false,
+      latencyMs: Date.now() - start,
+      error: err instanceof Error ? err.message : String(err),
+    }
+  }
+}
+

package/lib/adapters/telegram.js

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises'
 import {
   IMAGE_EXT_TO_MIME, VIDEO_EXT_TO_MIME, basename, cacheName, classifyDocument,
-  extOf, saveToCache, safeName,
+  extOf, saveToCache, safeName, TELEGRAM_MAX_DOC_BYTES,
 } from '../media.js'
 import { TEXT_INJECT_EXTS } from '../documents.js'
 import { splitText } from '../text.js'
@@ -12,21 +12,12 @@ import {
   shouldProcessTelegramMessage, stripBotCommandSuffix,
 } from '../groups.js'
 import { isResendSafeNetworkError, isPollingConflict, isTopicGoneError, computePollBackoffMs } from '../telegram-errors.js'
+import { extractTelegramInboundMedia, probeTelegramHealth } from './telegram-inbound.js'
 
 const API = 'https://api.telegram.org'
 const TELEGRAM_MAX = 4096
 
-export function buildQuickActionsKeyboard() {
-  return {
-    keyboard: [
-      [{ text: '🔄 /new' }, { text: '🛑 /stop' }],
-      [{ text: '🎙️ /voice' }, { text: '📊 /status' }],
-    ],
-    resize_keyboard: true,
-  }
-}
-
-export const REMOVE_REPLY_KEYBOARD = { remove_keyboard: true }
+export { buildQuickActionsKeyboard, REMOVE_REPLY_KEYBOARD } from '../commands.js'
 
 export class TelegramAdapter {
   constructor(opts) {
@@ -138,6 +129,8 @@ export class TelegramAdapter {
     return this.call('createForumTopic', {
       chat_id: chatId,
       name: String(name || '').slice(0, 128),
+      ...(options.iconColor ? { icon_color: options.iconColor } : {}),
+      ...(options.iconCustomEmojiId ? { icon_custom_emoji_id: options.iconCustomEmojiId } : {}),
       ...options,
     })
   }
@@ -180,27 +173,36 @@ export class TelegramAdapter {
     }
     if (this.transport === 'webhook') {
       if (!this.webhookUrl) throw new Error('telegram webhookUrl is required for webhook transport')
+      if (!this.webhookSecret) throw new Error('telegram webhookSecret is required for webhook transport')
       try {
         await this.call('deleteWebhook', { drop_pending_updates: false })
-      } catch {}
+      } catch (err) {
+        this.logger?.debug?.('telegram deleteWebhook failed (safe to ignore):', err?.message || err)
+      }
       const params = {
         url: this.webhookUrl,
         allowed_updates: ['message', 'callback_query'],
         drop_pending_updates: false,
+        secret_token: this.webhookSecret,
       }
-      if (this.webhookSecret) params.secret_token = this.webhookSecret
       await this.call('setWebhook', params)
       this.logger?.info?.(`dsh-messenger-gateway: telegram webhook set → ${this.webhookUrl}`)
       return
     }
-    try { await this.call('deleteWebhook', { drop_pending_updates: false }) } catch {}
+    try {
+      await this.call('deleteWebhook', { drop_pending_updates: false })
+    } catch (err) {
+      this.logger?.debug?.('telegram deleteWebhook failed (safe to ignore):', err?.message || err)
+    }
     this.poll()
   }
 
   stop() {
     this.stopped = true
     if (this.pollTimer) clearTimeout(this.pollTimer)
-    if (this.statusIndicator) this.setStatusIndicator(this.statusOffline).catch(() => {})
+    if (this.statusIndicator) this.setStatusIndicator(this.statusOffline).catch((err) => {
+      this.logger?.debug?.('telegram setStatusIndicator offline failed:', err?.message || err)
+    })
   }
 
   schedulePoll(delayMs) {
@@ -356,9 +358,8 @@ export class TelegramAdapter {
 
     text = stripBotCommandSuffix(text, this.botUsername)
     const threadId = msg.message_thread_id || 0
-    const maxDocBytes = this.media.maxDocBytes ?? 20 * 1024 * 1024
+    const maxDocBytes = this.media.maxDocBytes ?? TELEGRAM_MAX_DOC_BYTES
     const maxTextInjectBytes = this.media.maxTextInjectBytes ?? 100 * 1024
-    const attachments = []
     const replyMsg = msg.reply_to_message
     let replyText = ''
     if (replyMsg) {
@@ -369,95 +370,19 @@ export class TelegramAdapter {
         : quoted
     }
 
-    if (msg.photo?.length) {
-      const largest = msg.photo[msg.photo.length - 1]
-      const { path, file } = await this.downloadByFileId(largest.file_id, 'photo', extOf('', '') || '.jpg')
-      const ext = extOf(file.file_path, '') || '.jpg'
-      attachments.push({ kind: 'photo', path, mime: IMAGE_EXT_TO_MIME[ext] || 'image/jpeg' })
-    }
-    if (msg.sticker) {
-      const st = msg.sticker
-      if (st.is_video) {
-        try {
-          const { path } = await this.downloadByFileId(st.file_id, 'sticker-video', '.webm', st.file_unique_id || '')
-          attachments.push({ kind: 'animation', path, mime: 'video/webm', emoji: st.emoji || '', name: `sticker${st.emoji || ''}.webm` })
-          if (st.emoji) text = `${text}\n[Video sticker ${st.emoji}]`.trim()
-        } catch (e) {
-          text = `${text}\n[Video sticker ${st.emoji || ''} (download failed: ${e.message})]`.trim()
-        }
-      } else if (st.is_animated) {
-        try {
-          const { path } = await this.downloadByFileId(st.file_id, 'sticker-anim', '.tgs', st.file_unique_id || '')
-          attachments.push({ kind: 'document', path, mime: 'application/x-tgsticker', emoji: st.emoji || '', name: `sticker${st.emoji || ''}.tgs` })
-          if (st.emoji) text = `${text}\n[Animated sticker ${st.emoji}]`.trim()
-        } catch (e) {
-          text = `${text}\n[Animated sticker ${st.emoji || ''} (download failed: ${e.message})]`.trim()
-        }
-      } else {
-        const { path } = await this.downloadByFileId(st.file_id, 'sticker', '.webp', st.file_unique_id || '')
-        attachments.push({ kind: 'sticker', path, mime: 'image/webp', emoji: st.emoji || '', name: `sticker${st.emoji || ''}.webp` })
-      }
-    }
-    if (msg.voice) {
-      const { path } = await this.downloadByFileId(msg.voice.file_id, 'voice', '.ogg')
-      attachments.push({ kind: 'voice', path, mime: 'audio/ogg' })
-    }
-    if (msg.audio) {
-      const ext = extOf(msg.audio.file_name, msg.audio.mime_type) || '.mp3'
-      const { path } = await this.downloadByFileId(msg.audio.file_id, 'audio', ext, msg.audio.file_name || '')
-      attachments.push({ kind: 'audio', path, mime: msg.audio.mime_type || 'audio/mpeg' })
-    }
-    if (msg.video) {
-      const ext = extOf(msg.video.file_name, msg.video.mime_type) || '.mp4'
-      if ((msg.video.file_size || 0) > maxDocBytes) {
-        text = `${text}\n[Video too large]`.trim()
-      } else {
-        const { path } = await this.downloadByFileId(msg.video.file_id, 'video', ext, msg.video.file_name || '')
-        attachments.push({ kind: 'video', path, mime: msg.video.mime_type || VIDEO_EXT_TO_MIME[ext] || 'video/mp4', name: msg.video.file_name || basename(path) })
-      }
-    }
-    if (msg.video_note) {
-      const vn = msg.video_note
-      if ((vn.file_size || 0) > maxDocBytes) {
-        text = `${text}\n[Video note too large]`.trim()
-      } else {
-        const { path } = await this.downloadByFileId(vn.file_id, 'videonote', '.mp4')
-        attachments.push({ kind: 'video', path, mime: 'video/mp4', name: 'video_note.mp4' })
-      }
-    }
-    if (msg.animation) {
-      const an = msg.animation
-      const ext = extOf(an.file_name, an.mime_type) || '.mp4'
-      if ((an.file_size || 0) > maxDocBytes) {
-        text = `${text}\n[Animation too large]`.trim()
-      } else {
-        const { path } = await this.downloadByFileId(an.file_id, 'anim', ext, an.file_name || '')
-        attachments.push({ kind: 'animation', path, mime: an.mime_type || 'video/mp4', name: an.file_name || basename(path) })
-      }
-    }
-    if (msg.document) {
-      const doc = msg.document
-      const ext = extOf(doc.file_name, doc.mime_type)
-      const kind = classifyDocument(ext, doc.mime_type)
-      if (doc.file_size > maxDocBytes) {
-        text = `${text}\n[Document too large: ${doc.file_name || 'file'}]`.trim()
-      } else if (kind === 'unsupported') {
-        const { path } = await this.downloadByFileId(doc.file_id, 'doc', ext, doc.file_name || '')
-        attachments.push({ kind: 'document', path, mime: doc.mime_type || 'application/octet-stream', name: doc.file_name || basename(path) })
-      } else {
-        const { path, bytes } = await this.downloadByFileId(doc.file_id, 'doc', ext, doc.file_name || '')
-        if (kind === 'image') attachments.push({ kind: 'photo', path, mime: IMAGE_EXT_TO_MIME[ext] || doc.mime_type || 'image/jpeg', name: doc.file_name })
-        else if (kind === 'video') attachments.push({ kind: 'video', path, mime: VIDEO_EXT_TO_MIME[ext] || doc.mime_type || 'video/mp4', name: doc.file_name })
-        else if (bytes.length <= maxTextInjectBytes && TEXT_INJECT_EXTS.has(ext)) {
-          const body = new TextDecoder('utf-8', { fatal: false }).decode(bytes).slice(0, maxTextInjectBytes)
-          text = `${text}\n\n[Document ${doc.file_name}]\n${body}`.trim()
-        } else attachments.push({ kind: 'document', path, mime: doc.mime_type || 'application/octet-stream', name: doc.file_name || basename(path) })
-      }
-    }
+    const inbound = await extractTelegramInboundMedia(this, msg, text, maxDocBytes, maxTextInjectBytes)
+    text = inbound.text
+    const attachments = inbound.attachments
 
     const messageId = msg.message_id
     const reply = async (payload) => this.sendReply(chatId, messageId, payload, threadId)
-    const typing = async () => { try { await this.call('sendChatAction', { chat_id: chatId, action: 'typing', ...telegramThreadParams(threadId) }) } catch {} }
+    const typing = async () => {
+      try {
+        await this.call('sendChatAction', { chat_id: chatId, action: 'typing', ...telegramThreadParams(threadId) })
+      } catch (err) {
+        this.logger?.debug?.('telegram sendChatAction typing failed:', err?.message || err)
+      }
+    }
     const startStream = async () => this.startStreamMessage(chatId, messageId, threadId)
     const startProgress = async () => this.startProgressMessage(chatId, messageId, threadId)
     const react = async (emoji) => this.setReaction(chatId, messageId, emoji)
@@ -488,7 +413,11 @@ export class TelegramAdapter {
         }
       },
       remove: async () => {
-        try { await this.call('deleteMessage', { chat_id: chatId, message_id: messageId }) } catch {}
+        try {
+          await this.call('deleteMessage', { chat_id: chatId, message_id: messageId })
+        } catch (err) {
+          this.logger?.debug?.('telegram progress deleteMessage failed:', err?.message || err)
+        }
       },
     }
   }
@@ -662,51 +591,6 @@ export class TelegramAdapter {
   }
 
   async probeHealth(timeoutMs = 10000) {
-    if (!this.token) {
-      return { ok: false, error: 'Telegram bot token is empty' }
-    }
-    const start = Date.now()
-    try {
-      const res = await fetch(`${API}/bot${this.token}/getMe`, {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({}),
-        signal: AbortSignal.timeout(Math.max(1000, Number(timeoutMs) || 10000)),
-      })
-      const latencyMs = Date.now() - start
-      const json = await res.json().catch(() => ({}))
-      if (!res.ok || json.ok === false) {
-        return {
-          ok: false,
-          latencyMs,
-          error: json.description || `HTTP ${res.status}`,
-        }
-      }
-      const me = json.result || {}
-      this.botId = Number(me.id) || this.botId
-      this.botUsername = String(me.username || this.botUsername)
-      return {
-        ok: true,
-        latencyMs,
-        botId: this.botId,
-        botUsername: this.botUsername,
-        firstName: me.first_name || '',
-      }
-    } catch (err) {
-      return {
-        ok: false,
-        latencyMs: Date.now() - start,
-        error: err instanceof Error ? err.message : String(err),
-      }
-    }
-  }
-
-  async createForumTopic(chatId, name, opts = {}) {
-    return this.call('createForumTopic', {
-      chat_id: chatId,
-      name,
-      icon_color: opts.iconColor,
-      icon_custom_emoji_id: opts.iconCustomEmojiId,
-    })
+    return probeTelegramHealth(this, timeoutMs)
   }
 }

package/lib/alerts.js

@@ -1,5 +1,6 @@
 import { escapeHtml } from './telegram-format.js'
 import { normalizeThreadId } from './topics.js'
+import { t } from './locales/index.js'
 
 export function formatAlertMessage(type, payload = {}) {
   const timestamp = new Date().toLocaleTimeString()
@@ -61,4 +62,44 @@ export function resolveAlertTarget(gateway) {
     chatId,
     threadId: normalizeThreadId(alertsCfg.threadId),
   }
-}
+}
+
+export async function handleSetAlertCommand(gw, input, locale) {
+  const { reply, userId, chatId, threadId = 0 } = input
+  if (!gw.isUserAllowed(userId)) return reply(t('msg.not_allowed', {}, locale))
+  const nextTg = {
+    ...gw.tg(),
+    alerts: {
+      ...(gw.tg().alerts || {}),
+      enabled: true,
+      chatId,
+      threadId: threadId || 0,
+    },
+  }
+  gw.config.telegram = nextTg
+  try { await gw.hooks?.persistHomes?.(nextTg) } catch (err) { gw.logger?.warn?.('persistHomes error:', err?.message || err) }
+  return reply(`🔔 This chat assigned as alert channel (chat: ${chatId}${threadId ? `, topic: ${threadId}` : ''}).`)
+}
+
+export async function handleAlertCommand(gw, input, parts) {
+  const { reply, userId } = input
+  const sub = parts[1]?.toLowerCase()
+  if (sub === 'test') {
+    const target = resolveAlertTarget(gw)
+    if (!target) return reply('Alert channel not configured. Configure: /setalert')
+    await gw.sendAlert('status', { title: 'Test Alert', details: `Sent by user ID ${userId}` })
+    return reply('Test alert sent to alert channel.')
+  }
+  const target = resolveAlertTarget(gw)
+  const alertsCfg = gw.tg().alerts || {}
+  return reply([
+    '🔔 <b>Alert Channel:</b>',
+    `Status: ${alertsCfg.enabled ? 'enabled' : 'disabled'}`,
+    `Chat: ${target ? `${target.chatId}${target.threadId ? ` (topic: ${target.threadId})` : ''}` : '(not assigned)'}`,
+    `Events: ${(alertsCfg.events || ['error', 'pairing']).join(', ')}`,
+    '',
+    'Commands:',
+    '/setalert — assign current chat as alert channel',
+    '/alert test — send test alert',
+  ].join('\n'))
+}

package/lib/api-health.js

@@ -0,0 +1,38 @@
+export class ApiHealthTracker {
+  constructor(options = {}) {
+    this.logger = options.logger || console
+    this.degradedThreshold = Number(options.degradedThreshold) || 3
+    this.warnThreshold = Number(options.warnThreshold) || 5
+    this.consecutiveFailures = 0
+    this.lastError = null
+  }
+
+  recordFailure(op, err) {
+    this.consecutiveFailures++
+    this.lastError = {
+      op,
+      message: err?.message || String(err),
+      time: Date.now(),
+    }
+    this.logger?.debug?.(`dsh-messenger-gateway: Telegram API ${op} failed (${this.consecutiveFailures} consecutive):`, err?.message || err)
+    if (this.consecutiveFailures >= this.warnThreshold && this.consecutiveFailures % this.warnThreshold === 0) {
+      this.logger?.warn?.(`dsh-messenger-gateway: Telegram API experiencing repeated failures (${this.consecutiveFailures} in a row). Last op: ${op}, error: ${err?.message || err}`)
+    }
+  }
+
+  recordSuccess() {
+    this.consecutiveFailures = 0
+  }
+
+  isDegraded() {
+    return this.consecutiveFailures >= this.degradedThreshold
+  }
+
+  getSnapshot() {
+    return {
+      degraded: this.isDegraded(),
+      consecutiveFailures: this.consecutiveFailures,
+      lastError: this.lastError,
+    }
+  }
+}