luca 1.1.2 → 3.0.0

package/src/node/features/sqlite.ts

@@ -0,0 +1,289 @@
+import { z } from 'zod'
+import { Database } from 'bun:sqlite'
+import { Feature } from '../feature.js'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
+import type { ContainerContext } from '../../container.js'
+
+type SqlValue = string | number | boolean | bigint | Uint8Array | Buffer | null
+
+export const SqliteStateSchema = FeatureStateSchema.extend({
+  connected: z.boolean().default(false).describe('Whether the sqlite database is currently open'),
+  path: z.string().default(':memory:').describe('Path to the sqlite database file'),
+  lastQuery: z.string().optional().describe('Most recent SQL query string that was executed'),
+  lastChanges: z.number().optional().describe('Number of rows changed by the most recent execute call'),
+  lastInsertRowid: z.union([z.number(), z.bigint()]).optional().describe('Last inserted row id from the most recent execute call'),
+  lastError: z.string().optional().describe('Most recent sqlite error message, if any'),
+})
+
+export const SqliteOptionsSchema = FeatureOptionsSchema.extend({
+  path: z.string().optional().describe('Path to sqlite file. Use :memory: for in-memory database'),
+  readonly: z.boolean().optional().describe('Open sqlite database in readonly mode'),
+  readwrite: z.boolean().optional().describe('Open sqlite database in readwrite mode (defaults to true when readonly is false)'),
+  create: z.boolean().optional().describe('Create the sqlite database file if it does not exist'),
+})
+
+export type SqliteState = z.infer<typeof SqliteStateSchema>
+export type SqliteOptions = z.infer<typeof SqliteOptionsSchema>
+
+export const SqliteEventsSchema = FeatureEventsSchema.extend({
+  query: z.tuple([
+    z.string().describe('The SQL query text that was executed'),
+    z.array(z.any()).describe('Bound parameter values'),
+    z.number().describe('Number of rows returned'),
+  ]).describe('Emitted after a SELECT-like query completes successfully'),
+  execute: z.tuple([
+    z.string().describe('The SQL statement text that was executed'),
+    z.array(z.any()).describe('Bound parameter values'),
+    z.number().describe('Number of rows changed'),
+  ]).describe('Emitted after a write/update/delete statement completes successfully'),
+  error: z.tuple([
+    z.any().describe('The error that occurred'),
+  ]).describe('Emitted when a SQL operation fails'),
+  closed: z.tuple([]).describe('Emitted when the database connection is closed'),
+})
+
+/**
+ * SQLite feature for safe SQL execution through Bun's native sqlite binding.
+ *
+ * Supports:
+ * - parameterized query execution (`query` / `execute`)
+ * - tagged-template query execution (`sql`) to avoid manual placeholder wiring
+ *
+ * @example
+ * ```typescript
+ * const sqlite = container.feature('sqlite', { path: 'data/app.db' })
+ *
+ * await sqlite.execute(
+ *   'create table if not exists users (id integer primary key, email text not null unique)'
+ * )
+ *
+ * await sqlite.execute('insert into users (email) values (?)', ['hello@example.com'])
+ *
+ * const users = await sqlite.sql<{ id: number; email: string }>`
+ *   select id, email from users where email = ${'hello@example.com'}
+ * `
+ * ```
+ */
+export class Sqlite extends Feature<SqliteState, SqliteOptions> {
+  static override shortcut = 'features.sqlite' as const
+  static override stateSchema = SqliteStateSchema
+  static override optionsSchema = SqliteOptionsSchema
+  static override eventsSchema = SqliteEventsSchema
+  static { Feature.register(this, 'sqlite') }
+
+  private _db: Database
+
+  /**
+   * Default state for the SQLite feature before a database is opened.
+   * @returns The initial SqliteState with `connected: false` and in-memory path
+   */
+  override get initialState(): SqliteState {
+    return {
+      enabled: false,
+      connected: false,
+      path: ':memory:',
+    }
+  }
+
+  constructor(options: SqliteOptions, context: ContainerContext) {
+    super(options, context)
+
+    const path = options.path || ':memory:'
+    const openOptions = options.readonly
+      ? { readonly: true }
+      : { readwrite: options.readwrite ?? true, create: options.create ?? true }
+
+    this._db = new Database(path, openOptions)
+
+    this.hide('_db')
+    this.setState({
+      connected: true,
+      path,
+    })
+  }
+
+  /** Returns the underlying Bun sqlite database instance. */
+  get db() {
+    return this._db
+  }
+
+  /**
+   * Executes a SELECT-like query and returns result rows.
+   *
+   * Use sqlite placeholders (`?`) for `params`.
+   *
+   * @param queryText - The SQL query string with optional `?` placeholders
+   * @param params - Ordered array of values to bind to the placeholders
+   * @returns Promise resolving to an array of typed result rows
+   * @throws {Error} When query text is empty or params contain `undefined`
+   *
+   * @example
+   * ```typescript
+   * const db = container.feature('sqlite', { path: 'app.db' })
+   * const users = await db.query<{ id: number; email: string }>(
+   *   'SELECT id, email FROM users WHERE active = ?',
+   *   [1]
+   * )
+   * ```
+   */
+  async query<T extends object = Record<string, unknown>>(queryText: string, params: SqlValue[] = []): Promise<T[]> {
+    assertQueryText(queryText)
+    assertParams(params)
+
+    try {
+      const statement = this.db.query(queryText)
+      const rows = statement.all(...params) as T[]
+
+      this.setState({
+        lastQuery: queryText,
+        lastError: undefined,
+      })
+
+      this.emit('query', queryText, params, rows.length)
+      return rows
+    } catch (error: any) {
+      this.setState({
+        lastQuery: queryText,
+        lastError: error?.message || String(error),
+      })
+
+      this.emit('error', error)
+      throw error
+    }
+  }
+
+  /**
+   * Executes a write/update/delete statement and returns metadata.
+   *
+   * Use sqlite placeholders (`?`) for `params`.
+   *
+   * @param queryText - The SQL statement string with optional `?` placeholders
+   * @param params - Ordered array of values to bind to the placeholders
+   * @returns Promise resolving to `{ changes, lastInsertRowid }` metadata
+   * @throws {Error} When query text is empty or params contain `undefined`
+   *
+   * @example
+   * ```typescript
+   * const db = container.feature('sqlite', { path: 'app.db' })
+   * const { changes, lastInsertRowid } = await db.execute(
+   *   'INSERT INTO users (email) VALUES (?)',
+   *   ['hello@example.com']
+   * )
+   * console.log(`Inserted row ${lastInsertRowid}, ${changes} change(s)`)
+   * ```
+   */
+  async execute(queryText: string, params: SqlValue[] = []): Promise<{ changes: number; lastInsertRowid: number | bigint | null }> {
+    assertQueryText(queryText)
+    assertParams(params)
+
+    try {
+      const statement = this.db.query(queryText)
+      const result = statement.run(...params) as { changes: number; lastInsertRowid: number | bigint }
+
+      this.setState({
+        lastQuery: queryText,
+        lastChanges: result.changes,
+        lastInsertRowid: result.lastInsertRowid,
+        lastError: undefined,
+      })
+
+      this.emit('execute', queryText, params, result.changes)
+      return {
+        changes: result.changes,
+        lastInsertRowid: result.lastInsertRowid ?? null,
+      }
+    } catch (error: any) {
+      this.setState({
+        lastQuery: queryText,
+        lastError: error?.message || String(error),
+      })
+
+      this.emit('error', error)
+      throw error
+    }
+  }
+
+  /**
+   * Safe tagged-template SQL helper.
+   *
+   * Values become bound parameters automatically, preventing SQL injection.
+   *
+   * @param strings - Template literal string segments
+   * @param values - Interpolated values that become bound `?` parameters
+   * @returns Promise resolving to an array of typed result rows
+   *
+   * @example
+   * ```typescript
+   * const db = container.feature('sqlite', { path: 'app.db' })
+   * const email = 'hello@example.com'
+   * const rows = await db.sql<{ id: number }>`
+   *   SELECT id FROM users WHERE email = ${email}
+   * `
+   * ```
+   */
+  async sql<T extends object = Record<string, unknown>>(strings: TemplateStringsArray, ...values: SqlValue[]): Promise<T[]> {
+    const built = buildQuestionQuery(strings, values)
+    return this.query<T>(built.text, built.params)
+  }
+
+  /**
+   * Closes the sqlite database and updates feature state.
+   *
+   * Emits `closed` after the database handle is released.
+   *
+   * @returns This Sqlite feature instance for method chaining
+   *
+   * @example
+   * ```typescript
+   * const db = container.feature('sqlite', { path: 'app.db' })
+   * // ... run queries ...
+   * db.close()
+   * ```
+   */
+  close() {
+    this.db.close()
+    this.setState({ connected: false })
+    this.emit('closed')
+    return this
+  }
+}
+
+export default Sqlite
+declare module '../../feature.js' {
+  interface AvailableFeatures {
+    sqlite: typeof Sqlite
+  }
+}
+
+function assertQueryText(queryText: string) {
+  if (typeof queryText !== 'string' || queryText.trim().length === 0) {
+    throw new Error('SQL query text must be a non-empty string')
+  }
+}
+
+function assertParams(params: SqlValue[]) {
+  if (!Array.isArray(params)) {
+    throw new Error('SQL params must be an array')
+  }
+
+  if (params.some((param) => param === undefined)) {
+    throw new Error('SQL params cannot contain undefined values. Use null instead.')
+  }
+}
+
+function buildQuestionQuery(strings: TemplateStringsArray, values: SqlValue[]) {
+  if (strings.length !== values.length + 1) {
+    throw new Error('Invalid SQL template literal input')
+  }
+
+  const chunks: string[] = []
+
+  for (let i = 0; i < strings.length; i++) {
+    chunks.push(strings[i]!)
+    if (i < values.length) {
+      chunks.push('?')
+    }
+  }
+
+  return { text: chunks.join(''), params: values }
+}

package/src/node/features/telegram.ts

@@ -0,0 +1,343 @@
+import { z } from 'zod'
+import { FeatureStateSchema, FeatureOptionsSchema, FeatureEventsSchema } from '../../schemas/base.js'
+import { Feature } from '../feature.js'
+import { Bot, webhookCallback, type Context, type Middleware } from 'grammy'
+
+type UserFromGetMe = Awaited<ReturnType<Bot['api']['getMe']>>
+
+export const TelegramBotInfoSchema = z.object({
+  id: z.number().describe('Bot user ID'),
+  firstName: z.string().describe('Bot first name'),
+  username: z.string().optional().describe('Bot username'),
+  canJoinGroups: z.boolean().optional().describe('Whether the bot can be added to groups'),
+  canReadAllGroupMessages: z.boolean().optional().describe('Whether the bot can read all group messages'),
+})
+
+export const TelegramStateSchema = FeatureStateSchema.extend({
+  mode: z.enum(['polling', 'webhook', 'idle']).default('idle')
+    .describe('Current operation mode'),
+  isRunning: z.boolean().default(false)
+    .describe('Whether the bot is currently receiving updates'),
+  webhookUrl: z.string().optional()
+    .describe('Active webhook URL if in webhook mode'),
+  commandsRegistered: z.array(z.string()).default([])
+    .describe('List of registered command names'),
+  lastError: z.string().optional()
+    .describe('Last error message'),
+  botInfo: TelegramBotInfoSchema.optional()
+    .describe('Bot user information from Telegram API'),
+})
+export type TelegramState = z.infer<typeof TelegramStateSchema>
+
+export const TelegramOptionsSchema = FeatureOptionsSchema.extend({
+  token: z.string().optional()
+    .describe('Bot token from @BotFather (falls back to TELEGRAM_BOT_TOKEN env var)'),
+  mode: z.enum(['polling', 'webhook']).default('polling')
+    .describe('Update mode: polling for long-polling, webhook for HTTP callbacks'),
+  webhookUrl: z.string().optional()
+    .describe('Public HTTPS URL for webhook mode'),
+  webhookPath: z.string().default('/telegram/webhook')
+    .describe('HTTP path for the webhook endpoint'),
+  webhookPort: z.number().optional()
+    .describe('Port for webhook Express server'),
+  autoStart: z.boolean().optional()
+    .describe('Automatically start the bot when enabled'),
+  dropPendingUpdates: z.boolean().optional()
+    .describe('Drop pending updates on start (polling mode)'),
+  pollingTimeout: z.number().min(0).default(1)
+    .describe('Long-polling timeout in seconds. Lower = faster response. 0 = short polling (fastest, testing only). Default 1s.'),
+  pollingLimit: z.number().min(1).max(100).optional()
+    .describe('Max updates per polling request (1-100, default 100)'),
+  allowedUpdates: z.array(z.string()).optional()
+    .describe('Update types to receive (e.g. ["message", "callback_query"])'),
+})
+export type TelegramOptions = z.infer<typeof TelegramOptionsSchema>
+
+export const TelegramEventsSchema = FeatureEventsSchema.extend({
+  started: z.tuple([z.object({ mode: z.string() })]).describe('Bot started receiving updates'),
+  stopped: z.tuple([]).describe('Bot stopped'),
+  error: z.tuple([z.any()]).describe('Error occurred'),
+  command: z.tuple([z.string(), z.any()]).describe('Command triggered: [name, Context]'),
+  webhook_ready: z.tuple([z.string()]).describe('Webhook registered and ready'),
+})
+
+/**
+ * Telegram bot feature powered by grammY.
+ *
+ * Supports both long-polling and webhook modes. Exposes the grammY Bot instance
+ * directly for full API access while bridging events to Luca's event bus.
+ *
+ * @example
+ * ```typescript
+ * const tg = container.feature('telegram', { autoStart: true })
+ * tg.command('start', (ctx) => ctx.reply('Hello!'))
+ * tg.handle('message:text', (ctx) => ctx.reply(`Echo: ${ctx.message.text}`))
+ * ```
+ */
+export class Telegram extends Feature<TelegramState, TelegramOptions> {
+  static override shortcut = 'features.telegram' as const
+  static override envVars = ['TELEGRAM_BOT_TOKEN']
+  static override stateSchema = TelegramStateSchema
+  static override optionsSchema = TelegramOptionsSchema
+  static override eventsSchema = TelegramEventsSchema
+  static { Feature.register(this, 'telegram') }
+
+  private _bot?: Bot
+
+  override get initialState(): TelegramState {
+    return {
+      ...super.initialState,
+      mode: 'idle',
+      isRunning: false,
+      commandsRegistered: [],
+    }
+  }
+
+  /** Bot token from options or TELEGRAM_BOT_TOKEN env var. */
+  get token(): string {
+    const token = this.options.token || process.env.TELEGRAM_BOT_TOKEN
+    if (!token) {
+      throw new Error('Telegram bot token required. Set options.token or TELEGRAM_BOT_TOKEN env var.')
+    }
+    return token
+  }
+
+  /** The grammY Bot instance. Created lazily on first access. */
+  get bot(): Bot {
+    if (!this._bot) {
+      this._bot = new Bot(this.token)
+      this._setupErrorHandling()
+    }
+    return this._bot
+  }
+
+  /** Whether the bot is currently receiving updates. */
+  get isRunning(): boolean {
+    return this.state.get('isRunning') || false
+  }
+
+  /** Current operation mode: 'polling', 'webhook', or 'idle'. */
+  get mode(): 'polling' | 'webhook' | 'idle' {
+    return this.state.get('mode') || 'idle'
+  }
+
+  /** Access chalk colors via the container's UI feature. */
+  private get c() {
+    return this.container.feature('ui').colors
+  }
+
+  override async enable(options: any = {}): Promise<this> {
+    await super.enable(options)
+
+    const c = this.c
+    console.log(c.cyan.bold('\n🤖 Telegram Bot'))
+    console.log(c.dim('─'.repeat(40)))
+
+    try {
+      const me = await this.bot.api.getMe()
+      this.setState({
+        botInfo: {
+          id: me.id,
+          firstName: me.first_name,
+          username: me.username,
+          canJoinGroups: me.can_join_groups,
+          canReadAllGroupMessages: me.can_read_all_group_messages,
+        }
+      })
+      console.log(`${c.green('✓')} Authenticated as ${c.bold(`@${me.username}`)} ${c.dim(`(id: ${me.id})`)}`)
+    } catch (err: any) {
+      this.setState({ lastError: err.message })
+      console.log(`${c.red('✗')} Auth failed: ${c.red(err.message)}`)
+    }
+
+    console.log(`${c.dim('  mode:')} ${this.options.mode || 'polling'}`)
+
+    if (this.options.autoStart) {
+      await this.start()
+    }
+
+    return this
+  }
+
+  /** Start the bot in the configured mode (polling or webhook). */
+  async start(): Promise<this> {
+    if (this.isRunning) return this
+
+    if (this.options.mode === 'webhook') {
+      await this.setupWebhook()
+    } else {
+      await this.startPolling()
+    }
+
+    return this
+  }
+
+  /** Stop the bot gracefully. */
+  async stop(): Promise<this> {
+    if (!this.isRunning) return this
+
+    const c = this.c
+    if (this.mode === 'polling') {
+      await this.bot.stop()
+    } else if (this.mode === 'webhook') {
+      await this.deleteWebhook()
+    }
+
+    this.setState({ isRunning: false, mode: 'idle' })
+    this.emit('stopped')
+    console.log(`${c.yellow('⏹')} Bot stopped`)
+    return this
+  }
+
+  /** Register a command handler. Also emits 'command' on the Luca event bus. */
+  command(name: string, handler: (ctx: Context) => any): this {
+    this.bot.command(name, async (ctx) => {
+      this.emit('command', name, ctx)
+      await handler(ctx)
+    })
+
+    const registered = this.state.get('commandsRegistered') || []
+    if (!registered.includes(name)) {
+      this.setState({ commandsRegistered: [...registered, name] })
+    }
+    return this
+  }
+
+  /**
+   * Register a grammY update handler (filter query).
+   * Named 'handle' to avoid collision with the inherited on() event bus method.
+   *
+   * @example
+   * ```typescript
+   * tg.handle('message:text', (ctx) => ctx.reply('Got text'))
+   * tg.handle('callback_query:data', (ctx) => ctx.answerCallbackQuery('Clicked'))
+   * ```
+   */
+  handle(filter: Parameters<Bot['on']>[0], handler: (ctx: any) => any): this {
+    this.bot.on(filter, handler)
+    return this
+  }
+
+  /** Add grammY middleware. */
+  use(...middleware: Middleware[]): this {
+    for (const mw of middleware) {
+      this.bot.use(mw)
+    }
+    return this
+  }
+
+  /** Start long-polling mode. */
+  async startPolling(dropPendingUpdates?: boolean): Promise<this> {
+    const drop = dropPendingUpdates ?? this.options.dropPendingUpdates ?? false
+    const c = this.c
+
+    const timeout = this.options.pollingTimeout ?? 1
+    const limit = this.options.pollingLimit
+
+    // bot.start() is non-blocking internally (starts polling loop)
+    this.bot.start({
+      drop_pending_updates: drop,
+      allowed_updates: this.options.allowedUpdates as any,
+      timeout,
+      ...(limit ? { limit } : {}),
+    })
+
+    this.setState({ isRunning: true, mode: 'polling' })
+    this.emit('started', { mode: 'polling' })
+
+    const cmds = this.state.get('commandsRegistered') || []
+    console.log(`${c.green('▶')} Polling for updates ${c.dim(`(timeout: ${timeout}s)`)}${drop ? c.dim(' (dropped pending)') : ''}`)
+    if (cmds.length) {
+      console.log(`${c.dim('  commands:')} ${cmds.map(cmd => c.cyan(`/${cmd}`)).join(', ')}`)
+    }
+    console.log(c.dim('─'.repeat(40)))
+    return this
+  }
+
+  /** Set up webhook mode with an Express server. */
+  async setupWebhook(url?: string, path?: string): Promise<this> {
+    const webhookUrl = url || this.options.webhookUrl
+    const webhookPath = path || this.options.webhookPath || '/telegram/webhook'
+
+    if (!webhookUrl) {
+      throw new Error('webhookUrl required for webhook mode. Set options.webhookUrl or pass it to setupWebhook().')
+    }
+
+    const server = this.container.server('express', {
+      port: this.options.webhookPort,
+    }) as any
+
+    server.app.use(webhookPath, webhookCallback(this.bot, 'express'))
+
+    if (!server.isListening) {
+      const port = this.options.webhookPort || await this.container.networking.findOpenPort(3000)
+      await server.start({ port })
+    }
+
+    const fullUrl = `${webhookUrl.replace(/\/$/, '')}${webhookPath}`
+    await this.bot.api.setWebhook(fullUrl, {
+      allowed_updates: this.options.allowedUpdates as any,
+    })
+
+    this.setState({ isRunning: true, mode: 'webhook', webhookUrl: fullUrl })
+    this.emit('webhook_ready', fullUrl)
+    this.emit('started', { mode: 'webhook' })
+
+    const c = this.c
+    const cmds = this.state.get('commandsRegistered') || []
+    console.log(`${c.green('▶')} Webhook active at ${c.underline(fullUrl)}`)
+    if (cmds.length) {
+      console.log(`${c.dim('  commands:')} ${cmds.map(cmd => c.cyan(`/${cmd}`)).join(', ')}`)
+    }
+    console.log(c.dim('─'.repeat(40)))
+    return this
+  }
+
+  /** Remove the webhook from Telegram. */
+  async deleteWebhook(): Promise<this> {
+    await this.bot.api.deleteWebhook()
+    this.setState({ webhookUrl: undefined })
+    return this
+  }
+
+  /** Get bot info from Telegram API. */
+  async getMe(): Promise<UserFromGetMe> {
+    return await this.bot.api.getMe()
+  }
+
+  /** Print a diagnostic summary of the bot's current state. */
+  diagnostics(): this {
+    const c = this.c
+    const info = this.state.get('botInfo')
+    const cmds = this.state.get('commandsRegistered') || []
+    const err = this.state.get('lastError')
+
+    console.log(c.cyan.bold('\n🤖 Telegram Bot Diagnostics'))
+    console.log(c.dim('─'.repeat(40)))
+    console.log(`  ${c.dim('bot:')}       ${info ? `@${info.username} ${c.dim(`(${info.id})`)}` : c.yellow('not authenticated')}`)
+    console.log(`  ${c.dim('status:')}    ${this.isRunning ? c.green('running') : c.yellow('stopped')}`)
+    console.log(`  ${c.dim('mode:')}      ${this.mode}`)
+    if (this.mode === 'webhook') {
+      console.log(`  ${c.dim('webhook:')}   ${this.state.get('webhookUrl') || 'n/a'}`)
+    }
+    console.log(`  ${c.dim('commands:')}  ${cmds.length ? cmds.map(cmd => c.cyan(`/${cmd}`)).join(', ') : c.dim('none')}`)
+    if (info?.canJoinGroups) {
+      console.log(`  ${c.dim('groups:')}    ${c.green('can join')}`)
+    }
+    if (err) {
+      console.log(`  ${c.dim('error:')}     ${c.red(err)}`)
+    }
+    console.log(c.dim('─'.repeat(40)))
+    return this
+  }
+
+  private _setupErrorHandling(): void {
+    this.bot.catch((err) => {
+      this.setState({ lastError: err.message })
+      this.emit('error', err)
+    })
+  }
+
+}
+
+export default Telegram