create-bunspace 0.1.0

package/templates/telegram-bot/core/src/index.ts

@@ -0,0 +1,161 @@
+import { Telegraf } from 'telegraf'
+import { getConfig } from './config/index.js'
+import { errorHandler } from './middleware/error-handler.js'
+import { topicValidation } from './middleware/topics.js'
+import { botLogger, kv, badge, colorText, colors } from './middleware/logging.js'
+import { botManager } from './utils/bot-manager.js'
+import { getInstanceManager } from './utils/instance-manager.js'
+import { handleHealth, handleUptime, handleStats } from './handlers/health.js'
+import { handleStop, handleRestart, handleMode, handleWebhook } from './handlers/control.js'
+import { handleLogsCommand, initializeLogStreamer } from './handlers/logs.js'
+import { auth } from './middleware/auth.js'
+import { initializeFileLogging } from './config/logging.js'
+
+async function main(): Promise<void> {
+  const config = getConfig()
+  const instanceManager = getInstanceManager(config)
+
+  // Initialize file logging first (before any logger usage)
+  initializeFileLogging()
+
+  botLogger.info(
+    `${badge('START', 'pill')} ${kv({
+      environment: colorText(config.environment, colors.info),
+      instance: colorText(config.instanceName, colors.dim),
+      mode: colorText(config.mode, colors.info),
+      logLevel: config.logLevel,
+      instanceCheck: config.instanceCheck ? colorText('enabled', colors.success) : colorText('disabled', colors.dim),
+    })}`
+  )
+
+  // Try to acquire instance lock
+  const lockResult = await instanceManager.acquireLock()
+  if (!lockResult.ok) {
+    botLogger.error(
+      `${badge('INSTANCE', 'rounded')} ${kv({
+        error: colorText('CONFLICT', colors.error),
+        message: lockResult.error.message,
+      })}`
+    )
+    botLogger.error('Cannot start bot due to instance conflict. Exiting...')
+    process.exit(1)
+  }
+
+  botLogger.info(
+    `${badge('CONFIG', 'rounded')} ${kv({
+      logging: hasLoggingConfigured()
+        ? colorText('yes', colors.success)
+        : colorText('no', colors.dim),
+      control: hasControlConfigured()
+        ? colorText('yes', colors.success)
+        : colorText('no', colors.dim),
+    })}`
+  )
+
+  const bot = new Telegraf(config.botToken)
+
+  botManager.setBot(bot)
+
+  initializeLogStreamer(bot)
+
+  bot.use(errorHandler())
+  bot.use(topicValidation())
+
+  bot.command('start', async (ctx) => {
+    botLogger.info(
+      `${badge('CMD', 'rounded')} ${kv({ cmd: '/start', user: colorText(String(ctx.from?.id), colors.user) })}`
+    )
+    ctx.reply(
+      '👋 *Welcome!* I am a Telegram bot template.\n\n' +
+        'Available commands:\n' +
+        '/health - Check bot health\n' +
+        '/uptime - Show bot uptime\n' +
+        '/stats - Show statistics\n' +
+        '/logs - Check log streaming status\n' +
+        '/mode - Check or change bot mode',
+      { parse_mode: 'Markdown' }
+    )
+    botManager.incrementMessages()
+  })
+
+  bot.command('health', handleHealth)
+  bot.command('uptime', handleUptime)
+  bot.command('stats', handleStats)
+
+  bot.use((ctx, next) => {
+    if (ctx.message) {
+      botManager.incrementMessages()
+    }
+    return next()
+  })
+
+  if (hasControlConfigured()) {
+    bot.use(auth())
+
+    bot.command('stop', handleStop)
+    bot.command('restart', handleRestart)
+    bot.command('mode', handleMode)
+    bot.command('webhook', handleWebhook)
+
+    botLogger.info(
+      `${badge('CONTROL', 'rounded')} ${colorText('Commands registered', colors.success)}`
+    )
+  } else {
+    botLogger.warn(
+      `${badge('CONTROL', 'rounded')} ${colorText('Commands not registered', colors.warning)} ${kv({ reason: 'no chat ID configured' })}`
+    )
+  }
+
+  bot.command('logs', handleLogsCommand)
+
+  process.once('SIGINT', async () => {
+    botLogger.info(`${badge('SHUTDOWN', 'pill')} ${colorText('SIGINT received', colors.warning)}`)
+    await instanceManager.releaseLock()
+    bot.stop('SIGINT')
+  })
+
+  process.once('SIGTERM', async () => {
+    botLogger.info(`${badge('SHUTDOWN', 'pill')} ${colorText('SIGTERM received', colors.warning)}`)
+    await instanceManager.releaseLock()
+    bot.stop('SIGTERM')
+  })
+
+  if (config.mode === 'webhook') {
+    if (!config.webhookUrl) {
+      throw new Error('TG_WEBHOOK_URL is required for webhook mode')
+    }
+
+    botLogger.info(
+      `${badge('LAUNCH', 'pill')} ${kv({ mode: colorText('webhook', colors.info), url: config.webhookUrl })}`
+    )
+
+    await bot.launch({
+      webhook: {
+        domain: config.webhookUrl,
+        secretToken: config.webhookSecret,
+      },
+    })
+  } else {
+    botLogger.info(`${badge('LAUNCH', 'pill')} ${kv({ mode: colorText('polling', colors.info) })}`)
+    await bot.launch()
+  }
+
+  botLogger.success(
+    `${badge('READY', 'pill')} ${colorText('Bot started successfully', colors.success)}`
+  )
+}
+
+function hasLoggingConfigured(): boolean {
+  const config = getConfig()
+  return Boolean(config.logChatId)
+}
+
+function hasControlConfigured(): boolean {
+  const config = getConfig()
+  return Boolean(config.controlChatId)
+}
+
+main().catch((error) => {
+  botLogger.critical('Fatal error starting bot:', error)
+  process.exit(1)
+})

package/templates/telegram-bot/core/src/middleware/auth.ts

@@ -0,0 +1,41 @@
+import type { Context, Middleware } from 'telegraf'
+import { botLogger, badge, kv, colors, colorText } from './logging.js'
+import { botManager } from '../utils/bot-manager.js'
+
+export function auth(): Middleware<Context> {
+  return async (ctx, next) => {
+    if (!ctx.from?.id) {
+      botLogger.warn(
+        `${badge('AUTH', 'rounded')} ${kv({
+          status: colorText('FAILED', colors.warning),
+          reason: 'no user ID',
+        })}`
+      )
+      return
+    }
+
+    const authResult = botManager.authorize(ctx.from.id)
+
+    if (!authResult.ok) {
+      botLogger.warn(
+        `${badge('AUTH', 'rounded')} ${kv({
+          status: colorText('DENIED', colors.error),
+          user: ctx.from.id,
+          username: ctx.from.username ?? 'no-username',
+          reason: authResult.error.message,
+        })}`
+      )
+      await ctx.reply(`⛔ ${authResult.error.message}`)
+      return
+    }
+
+    botLogger.debug(
+      `${badge('AUTH', 'rounded')} ${kv({
+        status: colorText('GRANTED', colors.success),
+        user: ctx.from.id,
+      })}`
+    )
+
+    return next()
+  }
+}

package/templates/telegram-bot/core/src/middleware/error-handler.ts

@@ -0,0 +1,41 @@
+import type { Context, Middleware } from 'telegraf'
+import { botManager } from '../utils/bot-manager.js'
+import { botLogger, badge, kv, colors, colorText } from './logging.js'
+
+export function errorHandler<T extends Context>(): Middleware<T> {
+  return async (ctx, next) => {
+    try {
+      return await next()
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error(String(error))
+      const errorMsg = err.message || 'Unknown error occurred'
+
+      botLogger.error(
+        `${badge('ERROR', 'rounded')} ${kv({
+          error: colorText(errorMsg, colors.error),
+          type: err.name,
+          user: ctx.from?.id ?? 'unknown',
+          chat: ctx.chat?.id ?? 'unknown',
+        })}`,
+        err
+      )
+
+      const message = `❌ *Error:*\n${errorMsg}`
+
+      try {
+        await ctx.reply(message, { parse_mode: 'Markdown' })
+      } catch (replyError) {
+        // eslint-disable-next-line -- Error is logged below
+        botLogger.critical(
+          `${badge('CRITICAL', 'rounded')} ${kv({
+            error: 'Failed to send error message to user',
+            originalError: errorMsg,
+            replyError: replyError instanceof Error ? replyError.message : String(replyError),
+          })}`
+        )
+      }
+
+      botManager.incrementErrors()
+    }
+  }
+}

package/templates/telegram-bot/core/src/middleware/logging.ts

@@ -0,0 +1 @@
+export * from '@mks2508/telegram-bot-utils'

package/templates/telegram-bot/core/src/middleware/topics.ts

@@ -0,0 +1,55 @@
+import type { Context, Middleware } from 'telegraf'
+import { getLogTopicIds, getControlTopicIds } from '../config/index.js'
+import { botLogger, badge, kv, colors, colorText } from './logging.js'
+
+export function topicValidation(): Middleware<Context> {
+  return async (ctx, next) => {
+    const logIds = getLogTopicIds()
+    const controlIds = getControlTopicIds()
+
+    if (!logIds && !controlIds) {
+      return next()
+    }
+
+    const chatId = ctx.chat?.id.toString()
+    const topicId = ctx.message?.message_thread_id
+
+    let isValid = false
+
+    if (logIds && chatId === logIds.chatId) {
+      if (!logIds.topicId || topicId === logIds.topicId) {
+        isValid = true
+      }
+    }
+
+    if (controlIds && chatId === controlIds.chatId) {
+      if (!controlIds.topicId || topicId === controlIds.topicId) {
+        isValid = true
+      }
+    }
+
+    if (!isValid && ctx.chat?.type !== 'private' && (logIds || controlIds)) {
+      botLogger.debug(
+        `${badge('TOPIC', 'rounded')} ${kv({
+          action: colorText('rejected', colors.warning),
+          chat: chatId ?? 'unknown',
+          topic: topicId ?? 'none',
+          type: ctx.chat?.type ?? 'unknown',
+        })}`
+      )
+      return
+    }
+
+    if (topicId && (logIds || controlIds)) {
+      botLogger.debug(
+        `${badge('TOPIC', 'rounded')} ${kv({
+          action: colorText('accepted', colors.success),
+          chat: chatId ?? 'unknown',
+          topic: topicId,
+        })}`
+      )
+    }
+
+    return next()
+  }
+}

package/templates/telegram-bot/core/src/types/bot.ts

@@ -0,0 +1,92 @@
+export interface EnvConfig {
+  botToken: string
+  mode: 'polling' | 'webhook'
+  webhookUrl?: string
+  webhookSecret?: string
+  logChatId?: string
+  logTopicId?: number
+  controlChatId?: string
+  controlTopicId?: number
+  logLevel: 'debug' | 'info' | 'warn' | 'error'
+
+  // Environment identification
+  environment: 'local' | 'staging' | 'production'
+  instanceName: string
+  instanceId?: string
+
+  // Instance detection
+  instanceCheck: boolean
+  lockBackend: 'pid' | 'redis'
+  redisUrl?: string
+
+  // ngrok configuration
+  ngrokEnabled: boolean
+  ngrokPort: number
+  ngrokDomain?: string
+  ngrokRegion: string
+  ngrokAuthToken?: string
+}
+
+export interface BotConfig extends EnvConfig {
+  authorizedUserIds: Set<number>
+  debug?: boolean
+  rateLimit?: number
+  timeout?: number
+  maxRetries?: number
+  commandPrefix?: string
+}
+
+export interface BotStatus {
+  status: 'running' | 'stopped' | 'restarting' | 'error'
+  mode: 'polling' | 'webhook'
+  startTime: number | null
+  uptime: number
+  memoryUsage: {
+    rss: number
+    heapTotal: number
+    heapUsed: number
+    external: number
+    arrayBuffers: number
+  }
+}
+
+export interface LogEntry {
+  timestamp: string
+  level: string
+  component: string
+  message: string
+  metadata?: Record<string, unknown>
+}
+
+export interface TelegramLogEntry extends LogEntry {
+  chatId?: string
+  topicId?: number
+}
+
+export interface HealthCheckResult {
+  healthy: boolean
+  uptime: number
+  startTime: number
+  memoryUsage: {
+    rss: number
+    heapTotal: number
+    heapUsed: number
+    external: number
+    arrayBuffers: number
+  }
+  messageCount: number
+  errorCount: number
+}
+
+export interface BotStats {
+  messagesProcessed: number
+  commandsExecuted: number
+  errorsEncountered: number
+  uptimeStart: number
+  lastActivity: number
+}
+
+export interface TopicIds {
+  chatId: string
+  topicId?: number
+}

package/templates/telegram-bot/core/src/types/constants.ts

@@ -0,0 +1,50 @@
+export const TimeConstants = {
+  SECOND: 1_000,
+  MINUTE: 60_000,
+  HOUR: 3_600_000,
+  DAY: 86_400_000,
+} as const
+
+export const BotTimeouts = {
+  STARTUP: 30_000,
+  STOP: 10_000,
+  COMMAND_RESPONSE: 5_000,
+  WEBHOOK_SETUP: 10_000,
+  LOG_BUFFER_FLUSH: 5_000,
+  POLLING_TIMEOUT: 20_000,
+} as const
+
+export const BotLimits = {
+  LOG_BUFFER_SIZE: 10,
+  MAX_MESSAGE_LENGTH: 4_096,
+  MAX_CAPTION_LENGTH: 1_024,
+  MAX_RETRIES: 3,
+  RATE_LIMIT_PER_MINUTE: 60,
+  MAX_WEBHOOK_CONNECTIONS: 40,
+} as const
+
+export const EnvKeys = {
+  TG_BOT_TOKEN: 'TG_BOT_TOKEN',
+  TG_MODE: 'TG_MODE',
+  TG_WEBHOOK_URL: 'TG_WEBHOOK_URL',
+  TG_WEBHOOK_SECRET: 'TG_WEBHOOK_SECRET',
+  TG_LOG_CHAT_ID: 'TG_LOG_CHAT_ID',
+  TG_LOG_TOPIC_ID: 'TG_LOG_TOPIC_ID',
+  TG_CONTROL_CHAT_ID: 'TG_CONTROL_CHAT_ID',
+  TG_CONTROL_TOPIC_ID: 'TG_CONTROL_TOPIC_ID',
+  TG_AUTHORIZED_USER_IDS: 'TG_AUTHORIZED_USER_IDS',
+  LOG_LEVEL: 'LOG_LEVEL',
+  TG_DEBUG: 'TG_DEBUG',
+  TG_RATE_LIMIT: 'TG_RATE_LIMIT',
+  TG_TIMEOUT: 'TG_TIMEOUT',
+  TG_MAX_RETRIES: 'TG_MAX_RETRIES',
+  TG_COMMAND_PREFIX: 'TG_COMMAND_PREFIX',
+} as const
+
+export function getEnvTimeout(timeout: number): number {
+  return timeout || BotTimeouts.STARTUP
+}
+
+export function getEnvLimit(limit?: number): number {
+  return limit || BotLimits.RATE_LIMIT_PER_MINUTE
+}

package/templates/telegram-bot/core/src/types/result.ts

@@ -0,0 +1 @@
+export * from '@mks2508/telegram-bot-utils'

package/templates/telegram-bot/core/src/utils/bot-manager.test.ts

@@ -0,0 +1,111 @@
+/**
+ * @fileoverview Tests for BotManager
+ */
+
+import { describe, test, expect, beforeEach, afterEach } from 'bun:test'
+import { botManager } from './bot-manager.js'
+import { Telegraf } from 'telegraf'
+
+describe('BotManager', () => {
+  let bot: Telegraf
+
+  beforeEach(() => {
+    bot = new Telegraf('test:token')
+  })
+
+  afterEach(() => {
+    // Clean up after each test
+    botManager.stop('test cleanup').catch(() => {})
+  })
+
+  describe('Lifecycle', () => {
+    test('setBot initializes the bot', () => {
+      botManager.setBot(bot)
+
+      const status = botManager.getStatus()
+      expect(status.ok).toBe(true)
+      if (status.ok) {
+        expect(status.value.status).toBe('running')
+      }
+    })
+
+    test('getStatus returns bot status after setBot', () => {
+      botManager.setBot(bot)
+      const status = botManager.getStatus()
+
+      expect(status.ok).toBe(true)
+      if (status.ok) {
+        expect(['running', 'stopped']).toContain(status.value.status)
+      }
+    })
+  })
+
+  describe('Stats', () => {
+    test('getStats returns initial stats', () => {
+      const stats = botManager.getStats()
+      expect(stats.ok).toBe(true)
+      if (stats.ok) {
+        expect(stats.value.messagesProcessed).toBe(0)
+        expect(stats.value.commandsExecuted).toBe(0)
+        expect(stats.value.errorsEncountered).toBe(0)
+      }
+    })
+
+    test('incrementMessages updates message count', () => {
+      botManager.setBot(bot)
+      botManager.incrementMessages()
+
+      const stats = botManager.getStats()
+      if (stats.ok) {
+        expect(stats.value.messagesProcessed).toBe(1)
+      }
+    })
+
+    test('incrementCommands updates command count', () => {
+      botManager.setBot(bot)
+      botManager.incrementCommands()
+
+      const stats = botManager.getStats()
+      if (stats.ok) {
+        expect(stats.value.commandsExecuted).toBe(1)
+      }
+    })
+
+    test('incrementErrors updates error count', () => {
+      botManager.setBot(bot)
+      botManager.incrementErrors()
+
+      const stats = botManager.getStats()
+      if (stats.ok) {
+        expect(stats.value.errorsEncountered).toBe(1)
+      }
+    })
+
+    test('resetStats resets all stats', () => {
+      botManager.setBot(bot)
+      botManager.incrementMessages()
+      botManager.incrementCommands()
+      botManager.incrementErrors()
+
+      const result = botManager.resetStats()
+      expect(result.ok).toBe(true)
+
+      const stats = botManager.getStats()
+      if (stats.ok) {
+        expect(stats.value.messagesProcessed).toBe(0)
+        expect(stats.value.commandsExecuted).toBe(0)
+        expect(stats.value.errorsEncountered).toBe(0)
+      }
+    })
+  })
+
+  describe('Authorization', () => {
+    test('authorize returns ok for authorized users', () => {
+      // This test depends on env configuration
+      // In real tests, you'd mock getConfig() or set TG_AUTHORIZED_USER_IDS
+      // For now, we test the type safety
+      const result = botManager.authorize(123456789)
+      expect(result).toBeDefined()
+    })
+  })
+})