luca 1.1.2 → 3.0.0

package/docs/apis/features/node/sqlite.md

@@ -0,0 +1,233 @@
+# Sqlite (features.sqlite)
+
+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
+
+## Usage
+
+```ts
+container.feature('sqlite', {
+  // Path to sqlite file. Use :memory: for in-memory database
+  path,
+  // Open sqlite database in readonly mode
+  readonly,
+  // Open sqlite database in readwrite mode (defaults to true when readonly is false)
+  readwrite,
+  // Create the sqlite database file if it does not exist
+  create,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `path` | `string` | Path to sqlite file. Use :memory: for in-memory database |
+| `readonly` | `boolean` | Open sqlite database in readonly mode |
+| `readwrite` | `boolean` | Open sqlite database in readwrite mode (defaults to true when readonly is false) |
+| `create` | `boolean` | Create the sqlite database file if it does not exist |
+
+## Methods
+
+### query
+
+Executes a SELECT-like query and returns result rows. Use sqlite placeholders (`?`) for `params`.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `queryText` | `string` | ✓ | The SQL query string with optional `?` placeholders |
+| `params` | `SqlValue[]` |  | Ordered array of values to bind to the placeholders |
+
+**Returns:** `Promise<T[]>`
+
+```ts
+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]
+)
+```
+
+
+
+### execute
+
+Executes a write/update/delete statement and returns metadata. Use sqlite placeholders (`?`) for `params`.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `queryText` | `string` | ✓ | The SQL statement string with optional `?` placeholders |
+| `params` | `SqlValue[]` |  | Ordered array of values to bind to the placeholders |
+
+**Returns:** `Promise<{ changes: number; lastInsertRowid: number | bigint | null }>`
+
+```ts
+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)`)
+```
+
+
+
+### sql
+
+Safe tagged-template SQL helper. Values become bound parameters automatically, preventing SQL injection.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `strings` | `TemplateStringsArray` | ✓ | Template literal string segments |
+| `values` | `SqlValue[]` | ✓ | Interpolated values that become bound `?` parameters |
+
+**Returns:** `Promise<T[]>`
+
+```ts
+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}
+`
+```
+
+
+
+### close
+
+Closes the sqlite database and updates feature state. Emits `closed` after the database handle is released.
+
+**Returns:** `void`
+
+```ts
+const db = container.feature('sqlite', { path: 'app.db' })
+// ... run queries ...
+db.close()
+```
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `db` | `any` | Returns the underlying Bun sqlite database instance. |
+
+## Events (Zod v4 schema)
+
+### query
+
+Emitted after a SELECT-like query completes successfully
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | The SQL query text that was executed |
+| `arg1` | `array` | Bound parameter values |
+| `arg2` | `number` | Number of rows returned |
+
+
+
+### error
+
+Emitted when a SQL operation fails
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The error that occurred |
+
+
+
+### execute
+
+Emitted after a write/update/delete statement completes successfully
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | The SQL statement text that was executed |
+| `arg1` | `array` | Bound parameter values |
+| `arg2` | `number` | Number of rows changed |
+
+
+
+### closed
+
+Emitted when the database connection is closed
+
+
+
+## Examples
+
+**features.sqlite**
+
+```ts
+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'}
+`
+```
+
+
+
+**query**
+
+```ts
+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]
+)
+```
+
+
+
+**execute**
+
+```ts
+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)`)
+```
+
+
+
+**sql**
+
+```ts
+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}
+`
+```
+
+
+
+**close**
+
+```ts
+const db = container.feature('sqlite', { path: 'app.db' })
+// ... run queries ...
+db.close()
+```
+

package/docs/apis/features/node/telegram.md

@@ -0,0 +1,279 @@
+# Telegram (features.telegram)
+
+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.
+
+## Usage
+
+```ts
+container.feature('telegram', {
+  // Bot token from @BotFather (falls back to TELEGRAM_BOT_TOKEN env var)
+  token,
+  // Update mode: polling for long-polling, webhook for HTTP callbacks
+  mode,
+  // Public HTTPS URL for webhook mode
+  webhookUrl,
+  // HTTP path for the webhook endpoint
+  webhookPath,
+  // Port for webhook Express server
+  webhookPort,
+  // Automatically start the bot when enabled
+  autoStart,
+  // Drop pending updates on start (polling mode)
+  dropPendingUpdates,
+  // Long-polling timeout in seconds. Lower = faster response. 0 = short polling (fastest, testing only). Default 1s.
+  pollingTimeout,
+  // Max updates per polling request (1-100, default 100)
+  pollingLimit,
+  // Update types to receive (e.g. ["message", "callback_query"])
+  allowedUpdates,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `token` | `string` | Bot token from @BotFather (falls back to TELEGRAM_BOT_TOKEN env var) |
+| `mode` | `string` | Update mode: polling for long-polling, webhook for HTTP callbacks |
+| `webhookUrl` | `string` | Public HTTPS URL for webhook mode |
+| `webhookPath` | `string` | HTTP path for the webhook endpoint |
+| `webhookPort` | `number` | Port for webhook Express server |
+| `autoStart` | `boolean` | Automatically start the bot when enabled |
+| `dropPendingUpdates` | `boolean` | Drop pending updates on start (polling mode) |
+| `pollingTimeout` | `number` | Long-polling timeout in seconds. Lower = faster response. 0 = short polling (fastest, testing only). Default 1s. |
+| `pollingLimit` | `number` | Max updates per polling request (1-100, default 100) |
+| `allowedUpdates` | `array` | Update types to receive (e.g. ["message", "callback_query"]) |
+
+## Methods
+
+### enable
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `options` | `any` |  | Parameter options |
+
+**Returns:** `Promise<this>`
+
+
+
+### start
+
+Start the bot in the configured mode (polling or webhook).
+
+**Returns:** `Promise<this>`
+
+
+
+### stop
+
+Stop the bot gracefully.
+
+**Returns:** `Promise<this>`
+
+
+
+### command
+
+Register a command handler. Also emits 'command' on the Luca event bus.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `name` | `string` | ✓ | Parameter name |
+| `handler` | `(ctx: Context) => any` | ✓ | Parameter handler |
+
+**Returns:** `this`
+
+
+
+### handle
+
+Register a grammY update handler (filter query). Named 'handle' to avoid collision with the inherited on() event bus method.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `filter` | `Parameters<Bot['on']>[0]` | ✓ | Parameter filter |
+| `handler` | `(ctx: any) => any` | ✓ | Parameter handler |
+
+**Returns:** `this`
+
+```ts
+tg.handle('message:text', (ctx) => ctx.reply('Got text'))
+tg.handle('callback_query:data', (ctx) => ctx.answerCallbackQuery('Clicked'))
+```
+
+
+
+### use
+
+Add grammY middleware.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `middleware` | `Middleware[]` | ✓ | Parameter middleware |
+
+**Returns:** `this`
+
+
+
+### startPolling
+
+Start long-polling mode.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `dropPendingUpdates` | `boolean` |  | Parameter dropPendingUpdates |
+
+**Returns:** `Promise<this>`
+
+
+
+### setupWebhook
+
+Set up webhook mode with an Express server.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `url` | `string` |  | Parameter url |
+| `path` | `string` |  | Parameter path |
+
+**Returns:** `Promise<this>`
+
+
+
+### deleteWebhook
+
+Remove the webhook from Telegram.
+
+**Returns:** `Promise<this>`
+
+
+
+### getMe
+
+Get bot info from Telegram API.
+
+**Returns:** `Promise<UserFromGetMe>`
+
+
+
+### diagnostics
+
+Print a diagnostic summary of the bot's current state.
+
+**Returns:** `this`
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `token` | `string` | Bot token from options or TELEGRAM_BOT_TOKEN env var. |
+| `bot` | `Bot` | The grammY Bot instance. Created lazily on first access. |
+| `isRunning` | `boolean` | Whether the bot is currently receiving updates. |
+| `mode` | `'polling' | 'webhook' | 'idle'` | Current operation mode: 'polling', 'webhook', or 'idle'. |
+
+## Events (Zod v4 schema)
+
+### stopped
+
+Bot stopped
+
+
+
+### command
+
+Command triggered: [name, Context]
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` |  |
+| `arg1` | `any` |  |
+
+
+
+### started
+
+Bot started receiving updates
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `mode` | `string` |  |
+
+
+
+### webhook_ready
+
+Webhook registered and ready
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` |  |
+
+
+
+### error
+
+Error occurred
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` |  |
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `mode` | `string` | Current operation mode |
+| `isRunning` | `boolean` | Whether the bot is currently receiving updates |
+| `webhookUrl` | `string` | Active webhook URL if in webhook mode |
+| `commandsRegistered` | `array` | List of registered command names |
+| `lastError` | `string` | Last error message |
+| `botInfo` | `object` | Bot user information from Telegram API |
+
+## Environment Variables
+
+- `TELEGRAM_BOT_TOKEN`
+
+## Examples
+
+**features.telegram**
+
+```ts
+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}`))
+```
+
+
+
+**handle**
+
+```ts
+tg.handle('message:text', (ctx) => ctx.reply('Got text'))
+tg.handle('callback_query:data', (ctx) => ctx.answerCallbackQuery('Clicked'))
+```
+

package/docs/apis/features/node/transpiler.md

@@ -0,0 +1,74 @@
+# Transpiler (features.transpiler)
+
+Transpile TypeScript, TSX, and JSX to JavaScript at runtime using Bun's built-in transpiler. Compile code strings on the fly without touching the filesystem or spawning external processes.
+
+## Usage
+
+```ts
+container.feature('transpiler')
+```
+
+## Methods
+
+### transformSync
+
+Transform code synchronously
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `code` | `string` | ✓ | The code to transform |
+| `options` | `TransformOptions` |  | Transform options (loader, format, minify) |
+
+`TransformOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `loader` | `'ts' | 'tsx' | 'jsx' | 'js'` |  |
+| `format` | `'esm' | 'cjs'` |  |
+| `minify` | `boolean` |  |
+
+**Returns:** `TransformResult`
+
+
+
+### transform
+
+Transform code asynchronously
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `code` | `string` | ✓ | The code to transform |
+| `options` | `TransformOptions` |  | Transform options (loader, format, minify) |
+
+`TransformOptions` properties:
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `loader` | `'ts' | 'tsx' | 'jsx' | 'js'` |  |
+| `format` | `'esm' | 'cjs'` |  |
+| `minify` | `boolean` |  |
+
+**Returns:** `Promise<TransformResult>`
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+
+## Examples
+
+**features.transpiler**
+
+```ts
+const transpiler = container.feature('transpiler')
+const result = transpiler.transformSync('const x: number = 1')
+console.log(result.code) // 'const x = 1;\n'
+```
+

package/docs/apis/features/node/tts.md

@@ -0,0 +1,133 @@
+# TTS (features.tts)
+
+TTS feature — synthesizes text to audio files via RunPod's Chatterbox Turbo endpoint. Generates high-quality speech audio by calling the Chatterbox Turbo public endpoint on RunPod, downloads the resulting audio, and saves it locally. Supports 20 preset voices and voice cloning via a reference audio URL.
+
+## Usage
+
+```ts
+container.feature('tts', {
+  // RunPod API key (falls back to RUNPOD_API_KEY env var)
+  apiKey,
+  // Default preset voice name
+  voice,
+  // Directory to save generated audio files
+  outputDir,
+  // Audio output format
+  format,
+})
+```
+
+## Options (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `apiKey` | `string` | RunPod API key (falls back to RUNPOD_API_KEY env var) |
+| `voice` | `string` | Default preset voice name |
+| `outputDir` | `string` | Directory to save generated audio files |
+| `format` | `string` | Audio output format |
+
+## Methods
+
+### synthesize
+
+Synthesize text to an audio file using Chatterbox Turbo. Calls the RunPod public endpoint, downloads the generated audio, and saves it to the output directory.
+
+**Parameters:**
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `text` | `string` | ✓ | The text to synthesize into speech |
+| `options` | `{
+    voice?: string
+    format?: 'wav' | 'flac' | 'ogg'
+    voiceUrl?: string
+  }` |  | Override voice, format, or provide a voiceUrl for cloning |
+
+**Returns:** `Promise<string>`
+
+```ts
+// Use a preset voice
+const path = await tts.synthesize('Good morning!', { voice: 'ethan' })
+
+// Clone a voice from a reference audio URL
+const path = await tts.synthesize('Hello world', {
+ voiceUrl: 'https://example.com/reference.wav'
+})
+```
+
+
+
+## Getters
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `apiKey` | `string` | RunPod API key from options or environment. |
+| `outputDir` | `string` | Directory where generated audio files are saved. |
+| `voices` | `readonly string[]` | The 20 preset voice names available in Chatterbox Turbo. |
+
+## Events (Zod v4 schema)
+
+### synthesized
+
+Emitted when audio synthesis completes
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `string` | The text that was synthesized |
+| `arg1` | `string` | Path to the generated audio file |
+| `arg2` | `string` | Voice used |
+| `arg3` | `number` | Duration of the API call in milliseconds |
+
+
+
+### error
+
+Emitted when synthesis fails
+
+**Event Arguments:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `arg0` | `any` | The error |
+
+
+
+## State (Zod v4 schema)
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `enabled` | `boolean` | Whether this feature is currently enabled |
+| `lastFile` | `string` | Path to the last generated audio file |
+| `lastText` | `string` | Text of the last synthesis request |
+| `generating` | `boolean` | Whether audio is currently being generated |
+
+## Environment Variables
+
+- `RUNPOD_API_KEY`
+
+## Examples
+
+**features.tts**
+
+```ts
+const tts = container.feature('tts', { enable: true })
+const path = await tts.synthesize('Hello, how are you?', { voice: 'lucy' })
+console.log(`Audio saved to: ${path}`)
+```
+
+
+
+**synthesize**
+
+```ts
+// Use a preset voice
+const path = await tts.synthesize('Good morning!', { voice: 'ethan' })
+
+// Clone a voice from a reference audio URL
+const path = await tts.synthesize('Hello world', {
+ voiceUrl: 'https://example.com/reference.wav'
+})
+```
+