chat 4.18.0 → 4.20.0

package/docs/adapters/telegram.mdx

@@ -1,161 +0,0 @@
----
-title: Telegram
-description: Configure the Telegram adapter for bot webhooks and messaging.
-type: integration
-prerequisites:
-  - /docs/getting-started
----
-
-## Installation
-
-```sh title="Terminal"
-pnpm add @chat-adapter/telegram
-```
-
-## Usage
-
-The adapter auto-detects `TELEGRAM_BOT_TOKEN`, `TELEGRAM_WEBHOOK_SECRET_TOKEN`, `TELEGRAM_BOT_USERNAME`, and `TELEGRAM_API_BASE_URL` from environment variables:
-
-```typescript title="lib/bot.ts" lineNumbers
-import { Chat } from "chat";
-import { createTelegramAdapter } from "@chat-adapter/telegram";
-
-const bot = new Chat({
-  userName: "mybot",
-  adapters: {
-    telegram: createTelegramAdapter(),
-  },
-});
-
-bot.onNewMention(async (thread, message) => {
-  await thread.post(`You said: ${message.text}`);
-});
-```
-
-## Webhook route
-
-```typescript title="app/api/webhooks/telegram/route.ts" lineNumbers
-import { bot } from "@/lib/bot";
-
-export async function POST(request: Request): Promise<Response> {
-  return bot.webhooks.telegram(request);
-}
-```
-
-Configure this URL as your bot webhook in BotFather / Telegram API:
-
-```sh title="Terminal"
-curl -X POST "https://api.telegram.org/bot$TELEGRAM_BOT_TOKEN/setWebhook" \
-  -H "Content-Type: application/json" \
-  -d '{
-    "url": "https://your-domain.com/api/webhooks/telegram",
-    "secret_token": "your-secret-token"
-  }'
-```
-
-## Polling (local development)
-
-When developing locally you typically can't expose a public URL for Telegram to deliver webhooks to. Polling mode uses `getUpdates` to fetch messages directly from Telegram instead — no public endpoint needed.
-
-The `longPolling` option is entirely optional. Sensible defaults are applied when omitted.
-
-```typescript title="lib/bot.ts" lineNumbers
-import { Chat } from "chat";
-import { createTelegramAdapter } from "@chat-adapter/telegram";
-import { createMemoryState } from "@chat-adapter/state-memory";
-
-const telegram = createTelegramAdapter({
-  mode: "polling",
-  // Optional — fine-tune polling behavior:
-  // longPolling: { timeout: 30, dropPendingUpdates: false },
-});
-
-const bot = new Chat({
-  userName: "mybot",
-  adapters: { telegram },
-  state: createMemoryState(),
-});
-
-// Optional manual lifecycle control:
-// await telegram.resetWebhook();
-// await telegram.startPolling();
-// await telegram.stopPolling();
-```
-
-### Auto mode
-
-With `mode: "auto"` (the default), the adapter picks the right strategy for you. When deployed to a serverless environment like Vercel it uses webhooks; everywhere else (e.g. local dev) it falls back to polling automatically.
-
-```typescript title="lib/bot.ts" lineNumbers
-import { Chat } from "chat";
-import { createTelegramAdapter } from "@chat-adapter/telegram";
-import { createMemoryState } from "@chat-adapter/state-memory";
-
-const telegram = createTelegramAdapter({
-  mode: "auto", // default
-});
-
-export const bot = new Chat({
-  userName: "mybot",
-  adapters: { telegram },
-  state: createMemoryState(),
-});
-
-// Call initialize() so polling can start in long-running local processes:
-void bot.initialize();
-
-console.log(telegram.runtimeMode); // "webhook" | "polling"
-```
-
-## Configuration
-
-All options are auto-detected from environment variables when not provided.
-
-| Option | Required | Description |
-|--------|----------|-------------|
-| `botToken` | No* | Telegram bot token. Auto-detected from `TELEGRAM_BOT_TOKEN` |
-| `secretToken` | No | Optional webhook secret token. Auto-detected from `TELEGRAM_WEBHOOK_SECRET_TOKEN` |
-| `mode` | No | Adapter mode: `auto` (default), `webhook`, or `polling` |
-| `longPolling` | No | Optional long polling config for `getUpdates` (`timeout`, `limit`, `allowedUpdates`, `deleteWebhook`, `dropPendingUpdates`, `retryDelayMs`) |
-| `userName` | No | Bot username used for mention detection. Auto-detected from `TELEGRAM_BOT_USERNAME` or `getMe` |
-| `apiBaseUrl` | No | Telegram API base URL. Auto-detected from `TELEGRAM_API_BASE_URL` |
-| `logger` | No | Logger instance (defaults to `ConsoleLogger("info")`) |
-
-*`botToken` is required — either via config or env vars.
-
-## Environment variables
-
-```bash title=".env.local"
-TELEGRAM_BOT_TOKEN=123456:ABCDEF...
-TELEGRAM_WEBHOOK_SECRET_TOKEN=your-webhook-secret
-TELEGRAM_BOT_USERNAME=mybot
-# Optional (self-hosted API gateway)
-TELEGRAM_API_BASE_URL=https://api.telegram.org
-```
-
-## Features
-
-| Feature | Supported |
-|---------|-----------|
-| Mentions | Yes |
-| Reactions (add/remove) | Yes |
-| Cards | Text fallback + inline keyboard buttons/link buttons |
-| Modals | No |
-| Streaming | Post+Edit fallback |
-| DMs | Yes |
-| Ephemeral messages | No |
-| File uploads | Single file (`sendDocument`) |
-| Typing indicator | Yes |
-| Message history | Cached messages seen/sent by the adapter |
-
-## Notes
-
-- Telegram does not expose full historical message APIs to bots. `fetchMessages` / `fetchChannelMessages` return adapter-cached messages from the current process.
-- `listThreads` is not available for Telegram chats.
-- Polling and webhooks are mutually exclusive in Telegram.
-- `mode: "polling"` deletes webhook by default before calling `getUpdates`.
-- `mode: "auto"` checks `getWebhookInfo`: if a webhook URL exists it uses webhook mode; if it is empty it falls back to polling on non-serverless runtimes without deleting webhook.
-- If `getWebhookInfo` fails in `mode: "auto"`, the adapter stays in webhook mode (safe fallback).
-- `Button` and `LinkButton` in card `Actions` render as inline keyboard buttons.
-- Telegram callback data is limited to 64 bytes. Keep button `id`/`value` payloads short.
-- Other rich card elements (images/select menus/radios) render as fallback text only.

package/docs/state/ioredis.mdx

@@ -1,81 +0,0 @@
----
-title: ioredis
-description: Alternative Redis state adapter using ioredis with Cluster and Sentinel support.
-type: reference
-prerequisites:
-  - /docs/getting-started
----
-
-An alternative Redis state adapter using [ioredis](https://www.npmjs.com/package/ioredis). Use this if you already have ioredis in your project or need Redis Cluster/Sentinel support.
-
-## Installation
-
-```sh title="Terminal"
-pnpm add @chat-adapter/state-ioredis
-```
-
-## Usage
-
-```typescript title="lib/bot.ts" lineNumbers
-import { Chat } from "chat";
-import { createIORedisState } from "@chat-adapter/state-ioredis";
-
-const bot = new Chat({
-  userName: "mybot",
-  adapters: { /* ... */ },
-  state: createIORedisState({
-    url: process.env.REDIS_URL!,
-  }),
-});
-```
-
-### Using an existing client
-
-```typescript title="lib/bot.ts" lineNumbers
-import Redis from "ioredis";
-
-const client = new Redis("redis://localhost:6379");
-
-const state = createIORedisState({ client });
-```
-
-## Configuration
-
-| Option | Required | Description |
-|--------|----------|-------------|
-| `url` | Yes* | Redis connection URL |
-| `client` | No | Existing `ioredis` client instance |
-| `keyPrefix` | No | Prefix for all keys (default: `"chat-sdk"`) |
-
-*Either `url` or `client` is required.
-
-## When to use ioredis vs redis
-
-**Use `@chat-adapter/state-ioredis` when:**
-
-- You already use ioredis in your project
-- You need Redis Cluster support
-- You need Redis Sentinel support
-- You prefer the ioredis API
-
-**Use `@chat-adapter/state-redis` when:**
-
-- You want the official Redis client
-- You're starting a new project
-- You don't need Cluster or Sentinel
-
-## Key structure
-
-```
-{keyPrefix}:subscriptions     - SET of subscribed thread IDs
-{keyPrefix}:lock:{threadId}   - Lock key with TTL
-```
-
-## Features
-
-- Persistent subscriptions across restarts
-- Distributed locking across multiple instances
-- Automatic reconnection
-- Redis Cluster support
-- Redis Sentinel support
-- Key prefix namespacing

package/docs/state/memory.mdx

@@ -1,52 +0,0 @@
----
-title: Memory
-description: In-memory state adapter for local development and testing.
-type: reference
-prerequisites:
-  - /docs/getting-started
----
-
-An in-memory state adapter for development and testing. Zero configuration required.
-
-<Callout type="warn">
-Only use the memory adapter for local development and testing. State is lost on restart and locks don't work across multiple instances. For production, use [Redis](/docs/state/redis), [ioredis](/docs/state/ioredis), or [PostgreSQL](/docs/state/postgres).
-</Callout>
-
-## Installation
-
-```sh title="Terminal"
-pnpm add @chat-adapter/state-memory
-```
-
-## Usage
-
-```typescript title="lib/bot.ts" lineNumbers
-import { Chat } from "chat";
-import { createMemoryState } from "@chat-adapter/state-memory";
-
-const bot = new Chat({
-  userName: "mybot",
-  adapters: { /* ... */ },
-  state: createMemoryState(),
-});
-```
-
-No configuration options are needed.
-
-## Features
-
-- Thread subscriptions (in-memory)
-- Locking (single-process only)
-- Zero configuration
-
-## Limitations
-
-- **Not suitable for production** — state is lost on restart
-- **Single process only** — locks don't work across multiple instances
-- **No persistence** — subscriptions reset when the process restarts
-
-## When to use
-
-- Local development
-- Unit testing
-- Quick prototyping

package/docs/state/meta.json

@@ -1,4 +0,0 @@
-{
-  "title": "State",
-  "pages": ["index", "redis", "ioredis", "postgres", "memory"]
-}

package/docs/state/postgres.mdx

@@ -1,98 +0,0 @@
----
-title: PostgreSQL
-description: Production state adapter using pg (node-postgres).
-type: reference
-prerequisites:
-  - /docs/getting-started
----
-
-Production PostgreSQL state adapter built with [pg](https://www.npmjs.com/package/pg) (node-postgres). Use this when PostgreSQL is your primary datastore and you want state persistence without a separate Redis dependency.
-
-## Installation
-
-```sh title="Terminal"
-pnpm add @chat-adapter/state-pg
-```
-
-## Usage
-
-`createPostgresState()` auto-detects `POSTGRES_URL` (or `DATABASE_URL`) so you can call it with no arguments:
-
-```typescript title="lib/bot.ts" lineNumbers
-import { Chat } from "chat";
-import { createPostgresState } from "@chat-adapter/state-pg";
-
-const bot = new Chat({
-  userName: "mybot",
-  adapters: { /* ... */ },
-  state: createPostgresState(),
-});
-```
-
-To provide a URL explicitly:
-
-```typescript title="lib/bot.ts"
-const state = createPostgresState({
-  url: "postgres://postgres:postgres@localhost:5432/chat",
-});
-```
-
-### Using an existing client
-
-```typescript title="lib/bot.ts" lineNumbers
-import pg from "pg";
-
-const client = new pg.Pool({ connectionString: process.env.POSTGRES_URL! });
-const state = createPostgresState({ client });
-```
-
-## Configuration
-
-| Option | Required | Description |
-|--------|----------|-------------|
-| `url` | No* | Postgres connection URL |
-| `client` | No | Existing `pg.Pool` instance |
-| `keyPrefix` | No | Prefix for all state rows (default: `"chat-sdk"`) |
-| `logger` | No | Logger instance (defaults to `ConsoleLogger("info").child("postgres")`) |
-
-*Either `url`, `POSTGRES_URL`/`DATABASE_URL`, or `client` is required.
-
-## Environment variables
-
-```bash title=".env.local"
-POSTGRES_URL=postgres://postgres:postgres@localhost:5432/chat
-```
-
-## Data model
-
-The adapter creates these tables automatically on `connect()`:
-
-```sql
-chat_state_subscriptions
-chat_state_locks
-chat_state_cache
-```
-
-All rows are namespaced by `key_prefix`.
-
-## Features
-
-- Persistent subscriptions across restarts
-- Distributed locking across multiple instances
-- Key-value caching with TTL
-- Automatic table creation on first connect
-
-## Locking considerations
-
-The Redis state adapters use atomic `SET NX PX` for lock acquisition, which is a single atomic operation. The PostgreSQL adapter uses `INSERT ... ON CONFLICT DO UPDATE WHERE expires_at <= now()`, which relies on Postgres row-level locking. This is safe for most workloads but under extreme contention (many processes competing for the same lock simultaneously) may behave slightly differently than Redis. For high-contention distributed locking, prefer the Redis adapter.
-
-## Expired row cleanup
-
-Unlike Redis (which handles TTL expiry natively), PostgreSQL does not automatically delete expired rows. The adapter performs opportunistic cleanup — expired locks are overwritten on the next `acquireLock()` call, and expired cache entries are deleted on the next `get()` call for that key.
-
-For high-throughput deployments, you may want to run a periodic cleanup job:
-
-```sql
-DELETE FROM chat_state_locks WHERE expires_at <= now();
-DELETE FROM chat_state_cache WHERE expires_at <= now();
-```

package/docs/state/redis.mdx

@@ -1,100 +0,0 @@
----
-title: Redis
-description: Production state adapter using the official redis package.
-type: reference
-prerequisites:
-  - /docs/getting-started
----
-
-The recommended state adapter for production. Uses the official [redis](https://www.npmjs.com/package/redis) package.
-
-## Installation
-
-```sh title="Terminal"
-pnpm add @chat-adapter/state-redis
-```
-
-## Usage
-
-`createRedisState()` auto-detects the `REDIS_URL` environment variable, so you can call it with no arguments:
-
-```typescript title="lib/bot.ts" lineNumbers
-import { Chat } from "chat";
-import { createRedisState } from "@chat-adapter/state-redis";
-
-const bot = new Chat({
-  userName: "mybot",
-  adapters: { /* ... */ },
-  state: createRedisState(),
-});
-```
-
-To provide a URL explicitly:
-
-```typescript title="lib/bot.ts"
-const state = createRedisState({ url: "redis://localhost:6379" });
-```
-
-### Using an existing client
-
-If you already have a connected Redis client, pass it directly:
-
-```typescript title="lib/bot.ts" lineNumbers
-import { createClient } from "redis";
-
-const client = createClient({ url: "redis://localhost:6379" });
-await client.connect();
-
-const state = createRedisState({ client });
-```
-
-### Key prefix
-
-All keys are namespaced under a configurable prefix (default: `"chat-sdk"`):
-
-```typescript title="lib/bot.ts" lineNumbers
-const state = createRedisState({
-  url: process.env.REDIS_URL!,
-  keyPrefix: "my-bot",
-});
-```
-
-## Configuration
-
-| Option | Required | Description |
-|--------|----------|-------------|
-| `url` | No* | Redis connection URL (auto-detected from `REDIS_URL`) |
-| `client` | No | Existing `redis` client instance |
-| `keyPrefix` | No | Prefix for all keys (default: `"chat-sdk"`) |
-| `logger` | No | Logger instance (defaults to `ConsoleLogger("info")`) |
-
-*Either `url`, `REDIS_URL` env var, or `client` is required.
-
-## Environment variables
-
-```bash title=".env.local"
-REDIS_URL=redis://localhost:6379
-```
-
-For serverless deployments (Vercel, AWS Lambda), use a serverless-compatible Redis provider like [Upstash](https://upstash.com).
-
-## Key structure
-
-```
-{keyPrefix}:subscriptions     - SET of subscribed thread IDs
-{keyPrefix}:lock:{threadId}   - Lock key with TTL
-```
-
-## Production recommendations
-
-- Use Redis 6.0+ for best performance
-- Enable Redis persistence (RDB or AOF)
-- Use Redis Cluster for high availability
-- Set appropriate memory limits
-
-## Features
-
-- Persistent subscriptions across restarts
-- Distributed locking across multiple instances
-- Automatic reconnection
-- Key prefix namespacing

package/dist/{jsx-runtime-BYavlUk9.d.ts → jsx-runtime-C2ATKxHQ.d.ts}

@@ -1,98 +1,3 @@
-/**
- * Modal elements for form dialogs.
- */
-
-type ModalChild = TextInputElement | SelectElement | RadioSelectElement | TextElement | FieldsElement;
-interface ModalElement {
-    callbackId: string;
-    children: ModalChild[];
-    closeLabel?: string;
-    notifyOnClose?: boolean;
-    /** Arbitrary string passed through the modal lifecycle (e.g., JSON context). */
-    privateMetadata?: string;
-    submitLabel?: string;
-    title: string;
-    type: "modal";
-}
-interface TextInputElement {
-    id: string;
-    initialValue?: string;
-    label: string;
-    maxLength?: number;
-    multiline?: boolean;
-    optional?: boolean;
-    placeholder?: string;
-    type: "text_input";
-}
-interface SelectElement {
-    id: string;
-    initialOption?: string;
-    label: string;
-    optional?: boolean;
-    options: SelectOptionElement[];
-    placeholder?: string;
-    type: "select";
-}
-interface SelectOptionElement {
-    description?: string;
-    label: string;
-    value: string;
-}
-interface RadioSelectElement {
-    id: string;
-    initialOption?: string;
-    label: string;
-    optional?: boolean;
-    options: SelectOptionElement[];
-    type: "radio_select";
-}
-declare function isModalElement(value: unknown): value is ModalElement;
-interface ModalOptions {
-    callbackId: string;
-    children?: ModalChild[];
-    closeLabel?: string;
-    notifyOnClose?: boolean;
-    /** Arbitrary string passed through the modal lifecycle (e.g., JSON context). */
-    privateMetadata?: string;
-    submitLabel?: string;
-    title: string;
-}
-declare function Modal(options: ModalOptions): ModalElement;
-interface TextInputOptions {
-    id: string;
-    initialValue?: string;
-    label: string;
-    maxLength?: number;
-    multiline?: boolean;
-    optional?: boolean;
-    placeholder?: string;
-}
-declare function TextInput(options: TextInputOptions): TextInputElement;
-interface SelectOptions {
-    id: string;
-    initialOption?: string;
-    label: string;
-    optional?: boolean;
-    options: SelectOptionElement[];
-    placeholder?: string;
-}
-declare function Select(options: SelectOptions): SelectElement;
-declare function SelectOption(options: {
-    label: string;
-    value: string;
-    description?: string;
-}): SelectOptionElement;
-interface RadioSelectOptions {
-    id: string;
-    initialOption?: string;
-    label: string;
-    optional?: boolean;
-    options: SelectOptionElement[];
-}
-declare function RadioSelect(options: RadioSelectOptions): RadioSelectElement;
-type AnyModalElement = ModalElement | ModalChild | SelectOptionElement;
-declare function fromReactModalElement(element: unknown): AnyModalElement | null;
-
 /**
  * Card elements for cross-platform rich messaging.
  *
@@ -458,6 +363,101 @@ declare function fromReactElement(element: unknown): AnyCardElement | null;
  */
 declare function cardChildToFallbackText(child: CardChild): string | null;
 
+/**
+ * Modal elements for form dialogs.
+ */
+
+type ModalChild = TextInputElement | SelectElement | RadioSelectElement | TextElement | FieldsElement;
+interface ModalElement {
+    callbackId: string;
+    children: ModalChild[];
+    closeLabel?: string;
+    notifyOnClose?: boolean;
+    /** Arbitrary string passed through the modal lifecycle (e.g., JSON context). */
+    privateMetadata?: string;
+    submitLabel?: string;
+    title: string;
+    type: "modal";
+}
+interface TextInputElement {
+    id: string;
+    initialValue?: string;
+    label: string;
+    maxLength?: number;
+    multiline?: boolean;
+    optional?: boolean;
+    placeholder?: string;
+    type: "text_input";
+}
+interface SelectElement {
+    id: string;
+    initialOption?: string;
+    label: string;
+    optional?: boolean;
+    options: SelectOptionElement[];
+    placeholder?: string;
+    type: "select";
+}
+interface SelectOptionElement {
+    description?: string;
+    label: string;
+    value: string;
+}
+interface RadioSelectElement {
+    id: string;
+    initialOption?: string;
+    label: string;
+    optional?: boolean;
+    options: SelectOptionElement[];
+    type: "radio_select";
+}
+declare function isModalElement(value: unknown): value is ModalElement;
+interface ModalOptions {
+    callbackId: string;
+    children?: ModalChild[];
+    closeLabel?: string;
+    notifyOnClose?: boolean;
+    /** Arbitrary string passed through the modal lifecycle (e.g., JSON context). */
+    privateMetadata?: string;
+    submitLabel?: string;
+    title: string;
+}
+declare function Modal(options: ModalOptions): ModalElement;
+interface TextInputOptions {
+    id: string;
+    initialValue?: string;
+    label: string;
+    maxLength?: number;
+    multiline?: boolean;
+    optional?: boolean;
+    placeholder?: string;
+}
+declare function TextInput(options: TextInputOptions): TextInputElement;
+interface SelectOptions {
+    id: string;
+    initialOption?: string;
+    label: string;
+    optional?: boolean;
+    options: SelectOptionElement[];
+    placeholder?: string;
+}
+declare function Select(options: SelectOptions): SelectElement;
+declare function SelectOption(options: {
+    label: string;
+    value: string;
+    description?: string;
+}): SelectOptionElement;
+interface RadioSelectOptions {
+    id: string;
+    initialOption?: string;
+    label: string;
+    optional?: boolean;
+    options: SelectOptionElement[];
+}
+declare function RadioSelect(options: RadioSelectOptions): RadioSelectElement;
+type AnyModalElement = ModalElement | ModalChild | SelectOptionElement;
+declare function fromReactModalElement(element: unknown): AnyModalElement | null;
+
 /**
  * Custom JSX runtime for chat cards.
  *