luca 3.0.0 → 3.1.0

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

@@ -1,233 +0,0 @@
-# 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

@@ -1,279 +0,0 @@
-# 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

@@ -1,74 +0,0 @@
-# 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

@@ -1,133 +0,0 @@
-# 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'
-})
-```
-