create-bunspace 0.1.0

package/templates/telegram-bot/core/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "@mks2508/telegram-bot-core",
+  "version": "0.1.0",
+  "type": "module",
+  "scripts": {
+    "dev": "bun run --watch src/index.ts",
+    "start": "bun run src/index.ts",
+    "typecheck": "tsgo --noEmit"
+  },
+  "dependencies": {
+    "@mks2508/telegram-bot-utils": "workspace:*",
+    "telegraf": "^4.16.3",
+    "zod": "^3.24.0"
+  }
+}

package/templates/telegram-bot/core/src/config/env.ts

@@ -0,0 +1,131 @@
+import { z } from 'zod'
+import { BotTimeouts, BotLimits } from '../types/constants.js'
+
+export enum Environment {
+  LOCAL = 'local',
+  STAGING = 'staging',
+  PRODUCTION = 'production',
+}
+
+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: Environment
+  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
+}
+
+const envSchema = z.object({
+  TG_BOT_TOKEN: z.string().min(1),
+  TG_MODE: z.enum(['polling', 'webhook']),
+  TG_WEBHOOK_URL: z.string().url().optional(),
+  TG_WEBHOOK_SECRET: z.string().min(16).optional(),
+  TG_LOG_CHAT_ID: z.string().optional(),
+  TG_LOG_TOPIC_ID: z.coerce.number().min(1).optional(),
+  TG_CONTROL_CHAT_ID: z.string().optional(),
+  TG_CONTROL_TOPIC_ID: z.coerce.number().min(1).optional(),
+  TG_AUTHORIZED_USER_IDS: z.string().optional(),
+  LOG_LEVEL: z.enum(['debug', 'info', 'warn', 'error']).default('info'),
+  TG_DEBUG: z.coerce.boolean().default(false),
+  TG_RATE_LIMIT: z.coerce.number().min(1).max(120).default(BotLimits.RATE_LIMIT_PER_MINUTE),
+  TG_TIMEOUT: z.coerce.number().min(1000).default(BotTimeouts.COMMAND_RESPONSE),
+  TG_MAX_RETRIES: z.coerce.number().min(1).max(10).default(3),
+  TG_COMMAND_PREFIX: z.string().max(10).default('/'),
+  // File logging configuration
+  TG_LOG_FILE_ENABLED: z.string().optional(),
+  TG_LOG_DIR: z.string().optional(),
+  TG_LOG_MAX_SIZE: z.coerce.number().min(1024).optional(),
+  TG_LOG_MAX_FILES: z.coerce.number().min(1).max(100).optional(),
+  TG_LOG_LEVELS: z.string().optional(),
+
+  // === Environment Identification ===
+  TG_ENV: z.enum(['local', 'staging', 'production']).default('local'),
+  TG_INSTANCE_NAME: z.string().default('mks-bot'),
+  TG_INSTANCE_ID: z.string().optional(),
+
+  // === Instance Detection ===
+  TG_INSTANCE_CHECK: z.coerce.boolean().default(true),
+  TG_LOCK_BACKEND: z.enum(['pid', 'redis']).default('pid'),
+  TG_REDIS_URL: z.string().optional(),
+
+  // === ngrok Configuration ===
+  TG_NGROK_ENABLED: z.coerce.boolean().default(false),
+  TG_NGROK_PORT: z.coerce.number().default(3000),
+  TG_NGROK_DOMAIN: z.string().optional(),
+  TG_NGROK_REGION: z.string().default('us'),
+  TG_NGROK_AUTH_TOKEN: z.string().optional(),
+}).refine((data) => {
+  // Webhook URL validation when mode is webhook
+  if (data.TG_MODE === 'webhook' && !data.TG_WEBHOOK_URL && !data.TG_NGROK_ENABLED) {
+    return false
+  }
+  return true
+}, {
+  message: 'TG_WEBHOOK_URL is required when TG_MODE=webhook and TG_NGROK_ENABLED=false',
+})
+
+/**
+ * Loads and validates environment variables.
+ * @returns EnvConfig on success, throws on validation failure
+ * @throws Error if environment variables are invalid or required variables are missing
+ */
+export function loadEnvConfig(): EnvConfig {
+  const result = envSchema.safeParse(process.env)
+
+  if (!result.success) {
+    const errors = result.error.errors.map((e) => `  ${e.path.join('.')}: ${e.message}`).join('\n')
+    throw new Error(`Invalid environment variables:\n${errors}`)
+  }
+
+  const env = result.data
+
+  return {
+    botToken: env.TG_BOT_TOKEN,
+    mode: env.TG_MODE,
+    webhookUrl: env.TG_WEBHOOK_URL,
+    webhookSecret: env.TG_WEBHOOK_SECRET,
+    logChatId: env.TG_LOG_CHAT_ID,
+    logTopicId: env.TG_LOG_TOPIC_ID,
+    controlChatId: env.TG_CONTROL_CHAT_ID,
+    controlTopicId: env.TG_CONTROL_TOPIC_ID,
+    logLevel: env.LOG_LEVEL,
+
+    // Environment identification
+    environment: env.TG_ENV as Environment,
+    instanceName: env.TG_INSTANCE_NAME,
+    instanceId: env.TG_INSTANCE_ID,
+
+    // Instance detection
+    instanceCheck: env.TG_INSTANCE_CHECK,
+    lockBackend: env.TG_LOCK_BACKEND,
+    redisUrl: env.TG_REDIS_URL,
+
+    // ngrok configuration
+    ngrokEnabled: env.TG_NGROK_ENABLED,
+    ngrokPort: env.TG_NGROK_PORT,
+    ngrokDomain: env.TG_NGROK_DOMAIN,
+    ngrokRegion: env.TG_NGROK_REGION,
+    ngrokAuthToken: env.TG_NGROK_AUTH_TOKEN,
+  }
+}

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

@@ -0,0 +1,97 @@
+import { loadEnvConfig } from './env.js'
+import type { BotConfig } from '../types/bot.js'
+import { EnvKeys } from '../types/constants.js'
+import { existsSync } from 'fs'
+import { resolve } from 'path'
+
+let cachedConfig: BotConfig | null = null
+
+export function getConfig(): BotConfig {
+  if (cachedConfig) {
+    return cachedConfig
+  }
+
+  const envConfig = loadEnvConfig()
+
+  const authorizedUserIds = new Set<number>()
+  const userIds = process.env[EnvKeys.TG_AUTHORIZED_USER_IDS]
+  if (userIds) {
+    userIds.split(',').forEach((id) => {
+      const num = parseInt(id.trim(), 10)
+      if (!isNaN(num)) {
+        authorizedUserIds.add(num)
+      }
+    })
+  }
+
+  cachedConfig = {
+    ...envConfig,
+    authorizedUserIds,
+  }
+
+  return cachedConfig
+}
+
+export function getEnvFilePath(): string {
+  // 1. Check if explicit environment file path is set
+  const explicitPath = process.env.TG_ENV_FILE
+  if (explicitPath) {
+    return explicitPath
+  }
+
+  // 2. Use TG_ENV to determine which file to load
+  const tgEnv = process.env.TG_ENV || 'local'
+
+  // 3. Check if environment file exists
+  const envPath = resolve('./core/.env.' + tgEnv)
+  if (existsSync(envPath)) {
+    return envPath
+  }
+
+  // 4. Fall back to base .env
+  return resolve('./core/.env')
+}
+
+export function updateConfig(updates: Partial<BotConfig>): BotConfig {
+  cachedConfig = {
+    ...getConfig(),
+    ...updates,
+  }
+
+  return cachedConfig
+}
+
+export function getLogTopicIds(): { chatId: string; topicId?: number } | null {
+  const config = getConfig()
+  if (!config.logChatId) {
+    return null
+  }
+  return {
+    chatId: config.logChatId,
+    topicId: config.logTopicId,
+  }
+}
+
+export function getControlTopicIds(): { chatId: string; topicId?: number } | null {
+  const config = getConfig()
+  if (!config.controlChatId) {
+    return null
+  }
+  return {
+    chatId: config.controlChatId,
+    topicId: config.controlTopicId,
+  }
+}
+
+export function isAuthorized(userId: number): boolean {
+  const config = getConfig()
+  return config.authorizedUserIds.has(userId)
+}
+
+export function hasLoggingConfigured(): boolean {
+  return getLogTopicIds() !== null
+}
+
+export function hasControlConfigured(): boolean {
+  return getControlTopicIds() !== null
+}

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

@@ -0,0 +1,110 @@
+/**
+ * @fileoverview File logging configuration for Telegram bot
+ */
+
+import { FileLogHandler, addHandler } from '@mks2508/better-logger'
+import { setupLogger, botLogger } from '@mks2508/telegram-bot-utils'
+import { getConfig } from './index.js'
+import { mkdirSync, existsSync } from 'fs'
+import path from 'path'
+
+export interface FileLoggingConfig {
+  enabled: boolean
+  logDir: string
+  maxFileSize: number
+  maxFiles: number
+  fileLogLevels: ('debug' | 'info' | 'warn' | 'error' | 'critical')[]
+}
+
+const DEFAULT_CONFIG: FileLoggingConfig = {
+  enabled: process.env.TG_LOG_FILE_ENABLED !== 'false',
+  logDir: process.env.TG_LOG_DIR || path.join(process.cwd(), 'logs'),
+  maxFileSize: Number(process.env.TG_LOG_MAX_SIZE) || 1024 * 1024, // 1MB default
+  maxFiles: Number(process.env.TG_LOG_MAX_FILES) || 5,
+  fileLogLevels: (process.env.TG_LOG_LEVELS?.split(',') || [
+    'info',
+    'warn',
+    'error',
+    'critical',
+  ]) as FileLoggingConfig['fileLogLevels'],
+}
+
+let fileHandlersInitialized = false
+
+/**
+ * Initialize file logging with Better Logger FileLogHandler
+ *
+ * Creates separate log files for each log level and adds them as handlers
+ * to the global logger instance.
+ *
+ * @param config - Partial configuration to override defaults
+ *
+ * @example
+ * // Use defaults
+ * initializeFileLogging()
+ *
+ * @example
+ * // Custom configuration
+ * initializeFileLogging({
+ *   enabled: true,
+ *   logDir: './var/log',
+ *   maxFileSize: 5 * 1024 * 1024, // 5MB
+ *   fileLogLevels: ['error', 'critical']
+ * })
+ */
+export function initializeFileLogging(
+  config: Partial<FileLoggingConfig> = {}
+): void {
+  // Setup logger with debug/logLevel options
+  const appConfig = getConfig()
+  setupLogger({ debug: appConfig.debug, logLevel: appConfig.logLevel })
+
+  if (fileHandlersInitialized) {
+    botLogger.warn('File logging already initialized')
+    return
+  }
+
+  const finalConfig = { ...DEFAULT_CONFIG, ...config }
+
+  if (!finalConfig.enabled) {
+    botLogger.info('File logging disabled via configuration')
+    return
+  }
+
+  // Create logs directory if it doesn't exist
+  if (!existsSync(finalConfig.logDir)) {
+    try {
+      mkdirSync(finalConfig.logDir, { recursive: true })
+      botLogger.info(`Created log directory: ${finalConfig.logDir}`)
+    } catch (error) {
+      botLogger.error('Failed to create log directory:', error)
+      return
+    }
+  }
+
+  // Add file handler for each log level
+  for (const level of finalConfig.fileLogLevels) {
+    const fileName = path.join(finalConfig.logDir, `${level}.log`)
+    const handler = new FileLogHandler(fileName, finalConfig.maxFileSize)
+    addHandler(handler)
+  }
+
+  fileHandlersInitialized = true
+  botLogger.success(
+    `File logging initialized: ${finalConfig.logDir} (levels: ${finalConfig.fileLogLevels.join(', ')})`
+  )
+}
+
+/**
+ * Check if file logging is initialized
+ */
+export function isFileLoggingInitialized(): boolean {
+  return fileHandlersInitialized
+}
+
+/**
+ * Get the current file logging configuration
+ */
+export function getFileLoggingConfig(): FileLoggingConfig {
+  return { ...DEFAULT_CONFIG }
+}

package/templates/telegram-bot/core/src/handlers/control.ts

@@ -0,0 +1,85 @@
+import type { Context } from 'telegraf'
+import { updateConfig, getConfig } from '../config/index.js'
+import { botLogger, controlLogger, badge, kv, colors, colorText } from '../middleware/logging.js'
+import { botManager } from '../utils/bot-manager.js'
+
+export async function handleStop(ctx: Context): Promise<void> {
+  const userId = ctx.from?.id ?? 'unknown'
+
+  botLogger.info(
+    `${badge('CONTROL', 'rounded')} ${kv({
+      cmd: colorText('/stop', colors.command),
+      user: colorText(String(userId), colors.user),
+    })}`
+  )
+
+  ctx.reply('🛑 Shutting down bot...')
+  process.exit(0)
+}
+
+export async function handleRestart(ctx: Context): Promise<void> {
+  const userId = ctx.from?.id ?? 'unknown'
+
+  botLogger.info(
+    `${badge('CONTROL', 'rounded')} ${kv({
+      cmd: colorText('/restart', colors.command),
+      user: colorText(String(userId), colors.user),
+    })}`
+  )
+
+  ctx.reply('🔄 Restarting bot...')
+  botManager.resetStats()
+  ctx.reply('✅ Bot stats reset. Restarting...')
+  process.exit(0)
+}
+
+export async function handleMode(ctx: Context): Promise<void> {
+  const text = ctx.message && 'text' in ctx.message ? ctx.message.text : ''
+  const parts = text.split(' ')
+  const mode = parts[1] as 'polling' | 'webhook' | undefined
+
+  if (!mode || (mode !== 'polling' && mode !== 'webhook')) {
+    const config = getConfig()
+    ctx.reply(`📡 *Current Mode:* \`${config.mode}\`\n\nUsage: /mode <polling|webhook>`, {
+      parse_mode: 'Markdown',
+    })
+    return
+  }
+
+  if (mode === 'webhook') {
+    const config = getConfig()
+    if (!config.webhookUrl) {
+      ctx.reply('❌ Webhook URL not configured. Set TG_WEBHOOK_URL environment variable.')
+      return
+    }
+  }
+
+  updateConfig({ mode })
+  ctx.reply(`✅ Mode changed to: \`${mode}\``, { parse_mode: 'Markdown' })
+
+  controlLogger.info(
+    `${badge('MODE', 'rounded')} ${kv({
+      newMode: colorText(mode, colors.info),
+      user: ctx.from?.id ?? 'unknown',
+    })}`
+  )
+}
+
+export async function handleWebhook(ctx: Context): Promise<void> {
+  const config = getConfig()
+
+  if (config.mode !== 'webhook') {
+    ctx.reply('❌ Bot is not in webhook mode. Use /mode webhook first.')
+    return
+  }
+
+  const message = `🔗 *Webhook Configuration:*\n\nURL: \`${config.webhookUrl || 'Not set'}\``
+  ctx.reply(message, { parse_mode: 'Markdown' })
+
+  controlLogger.info(
+    `${badge('WEBHOOK', 'rounded')} ${kv({
+      url: config.webhookUrl ?? 'not configured',
+      user: ctx.from?.id ?? 'unknown',
+    })}`
+  )
+}

package/templates/telegram-bot/core/src/handlers/health.ts

@@ -0,0 +1,83 @@
+import type { Context } from 'telegraf'
+import { getConfig } from '../config/index.js'
+import { formatHealthMessage } from '../utils/formatters.js'
+import { healthLogger, badge, kv, colors, colorText } from '../middleware/logging.js'
+
+export async function handleHealth(ctx: Context): Promise<void> {
+  const userId = ctx.from?.id ?? 'unknown'
+
+  healthLogger.debug(
+    `${badge('HEALTH', 'rounded')} ${kv({
+      cmd: '/health',
+      user: colorText(String(userId), colors.user),
+    })}`
+  )
+
+  const config = getConfig()
+  const uptime = Date.now() - (Date.now() - 10000)
+  const memoryUsage = process.memoryUsage()
+
+  const message = formatHealthMessage({
+    status: 'running' as const,
+    mode: config.mode,
+    startTime: Date.now() - 10000,
+    uptime,
+    memoryUsage,
+  })
+
+  await ctx.reply(message, { parse_mode: 'Markdown' })
+}
+
+export async function handleUptime(ctx: Context): Promise<void> {
+  const userId = ctx.from?.id ?? 'unknown'
+
+  healthLogger.debug(
+    `${badge('UPTIME', 'rounded')} ${kv({
+      cmd: '/uptime',
+      user: colorText(String(userId), colors.user),
+    })}`
+  )
+
+  const uptime = Date.now() - (Date.now() - 10000)
+  const days = Math.floor(uptime / 86400000)
+  const hours = Math.floor((uptime % 86400000) / 3600000)
+  const minutes = Math.floor((uptime % 3600000) / 60000)
+  const seconds = Math.floor((uptime % 60000) / 1000)
+
+  let formatted = ''
+  if (days > 0) formatted += `${days}d `
+  if (hours > 0) formatted += `${hours}h `
+  if (minutes > 0) formatted += `${minutes}m `
+  formatted += `${seconds}s`
+
+  await ctx.reply(`⏱️ *Uptime:*\n${formatted}`, { parse_mode: 'Markdown' })
+}
+
+export async function handleStats(ctx: Context): Promise<void> {
+  const userId = ctx.from?.id ?? 'unknown'
+
+  healthLogger.debug(
+    `${badge('STATS', 'rounded')} ${kv({
+      cmd: '/stats',
+      user: colorText(String(userId), colors.user),
+    })}`
+  )
+
+  const config = getConfig()
+
+  const message = `📊 *Bot Statistics*
+
+*Performance:*
+Messages Processed: 0
+Commands Executed: 0
+Errors Encountered: 0
+
+*Configuration:*
+Mode: ${config.mode.toUpperCase()}
+Log Level: ${config.logLevel.toUpperCase()}
+Logging Enabled: ${config.logChatId ? '✅' : '❌'}
+Control Enabled: ${config.controlChatId ? '✅' : '❌'}
+  `
+
+  await ctx.reply(message, { parse_mode: 'Markdown' })
+}

package/templates/telegram-bot/core/src/handlers/logs.ts

@@ -0,0 +1,126 @@
+import type { Context, Telegraf } from 'telegraf'
+import { getConfig, hasLoggingConfigured } from '../config/index.js'
+import { streamLogger, botLogger, badge, kv, colors, colorText } from '../middleware/logging.js'
+import { formatLogEntry } from '../utils/formatters.js'
+
+const LOG_BUFFER_SIZE = 10
+const LOG_BUFFER_TIMEOUT = 5000
+
+class LogStreamer {
+  private logBuffer: string[] = []
+  private bufferTimeout: NodeJS.Timeout | null = null
+  private isEnabled = false
+
+  constructor(private bot: Telegraf) {
+    this.isEnabled = hasLoggingConfigured()
+  }
+
+  async sendLog(level: string, component: string, message: string): Promise<void> {
+    if (!this.isEnabled) return
+
+    const timestamp = new Date().toISOString()
+    const formattedLog = formatLogEntry(timestamp, level, component, message)
+
+    this.logBuffer.push(formattedLog)
+
+    if (this.bufferTimeout) {
+      clearTimeout(this.bufferTimeout)
+    }
+
+    if (this.logBuffer.length >= LOG_BUFFER_SIZE) {
+      await this.flushBuffer()
+    } else {
+      this.bufferTimeout = setTimeout(() => {
+        this.flushBuffer()
+      }, LOG_BUFFER_TIMEOUT)
+    }
+  }
+
+  private async flushBuffer(): Promise<void> {
+    if (this.logBuffer.length === 0) return
+
+    const config = getConfig()
+    if (!config.logChatId) return
+
+    const fullMessage = this.logBuffer.join('\n\n')
+
+    try {
+      const extra = {
+        parse_mode: 'Markdown' as const,
+      }
+
+      if (config.logTopicId) {
+        Object.assign(extra, { message_thread_id: config.logTopicId })
+      }
+
+      await this.bot.telegram.sendMessage(config.logChatId, fullMessage, extra)
+    } catch (error) {
+      botLogger.error(
+        `${badge('STREAM', 'rounded')} ${kv({
+          status: colorText('FAILED', colors.error),
+          error: error instanceof Error ? error.message : String(error),
+        })}`
+      )
+    }
+
+    this.logBuffer = []
+    this.bufferTimeout = null
+  }
+
+  stop(): void {
+    if (this.bufferTimeout) {
+      clearTimeout(this.bufferTimeout)
+    }
+    this.flushBuffer()
+  }
+}
+
+let logStreamer: LogStreamer | null = null
+
+export function initializeLogStreamer(bot: Telegraf): void {
+  logStreamer = new LogStreamer(bot)
+  streamLogger.success(
+    `${badge('STREAM', 'rounded')} ${kv({
+      status: colorText('initialized', colors.success),
+      bufferSize: LOG_BUFFER_SIZE,
+      bufferTimeout: `${LOG_BUFFER_TIMEOUT}ms`,
+    })}`
+  )
+}
+
+export async function sendLogToTelegram(
+  level: string,
+  component: string,
+  message: string
+): Promise<void> {
+  if (logStreamer) {
+    await logStreamer.sendLog(level, component, message)
+  }
+}
+
+export async function handleLogsCommand(ctx: Context): Promise<void> {
+  const config = getConfig()
+
+  if (!hasLoggingConfigured()) {
+    await ctx.reply('❌ Logging is not configured. Set TG_LOG_CHAT_ID environment variable.')
+    return
+  }
+
+  const isEnabled = logStreamer !== null
+  const status = isEnabled ? 'enabled' : 'disabled'
+
+  streamLogger.info(
+    `${badge('QUERY', 'rounded')} ${kv({
+      cmd: '/logs',
+      status: colorText(status, isEnabled ? colors.success : colors.dim),
+      user: ctx.from?.id ?? 'unknown',
+    })}`
+  )
+
+  await ctx.reply(
+    `📝 *Log Streaming Status:* \`${status}\`\n\nChat ID: \`${config.logChatId}\`${
+      config.logTopicId ? `\nTopic ID: \`${config.logTopicId}\`` : ''
+    }`,
+    { parse_mode: 'Markdown' }
+  )
+}