@mastra/telegram 0.0.0 → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,421 @@
+import { WaitUntilFn, StreamingConfig, ChannelHandlers, ChannelConfig, ChannelAdapterConfig, ChannelProvider, ChannelPlatformInfo, ChannelConnectResult, ChannelInstallationInfo } from '@mastra/core/channels';
+import { Mastra } from '@mastra/core/mastra';
+import { ApiRoute } from '@mastra/core/server';
+import { TelegramAdapterConfig, TelegramAdapter, TelegramUser } from '@chat-adapter/telegram';
+export { TelegramAdapter, createTelegramAdapter } from '@chat-adapter/telegram';
+import { ChannelsStorage } from '@mastra/core/storage';
+
+/** Default Telegram Bot API origin. */
+declare const TELEGRAM_API_BASE_URL = "https://api.telegram.org";
+/**
+ * Transport for receiving updates.
+ * - `webhook` — register a `setWebhook` and receive POSTs (default for hosted/serverless).
+ * - `polling` — long-poll `getUpdates` (the provider clears any webhook first).
+ * - `auto` — webhook when a `baseUrl` is available, otherwise polling.
+ */
+type TelegramMode = 'auto' | 'webhook' | 'polling';
+/**
+ * Default update types requested from Telegram. `message_reaction` must be
+ * listed explicitly (Telegram omits it otherwise).
+ */
+declare const DEFAULT_ALLOWED_UPDATES: readonly ["message", "edited_message", "channel_post", "edited_channel_post", "callback_query", "message_reaction"];
+/**
+ * A Telegram bot command as it goes over the wire (`setMyCommands`).
+ * @see https://core.telegram.org/bots/api#botcommand
+ */
+interface BotCommand {
+    /** 1-32 chars, lowercase `[a-z0-9_]`, no leading slash. */
+    command: string;
+    /** 1-256 chars. */
+    description: string;
+}
+/** Command input accepted by {@link TelegramProvider} — a bare name or a `{ command, description }`. */
+type TelegramCommand = string | {
+    command: string;
+    description?: string;
+};
+/**
+ * Deep link that opens BotFather so an operator can create a new bot with
+ * `/newbot`. Telegram has no OAuth: the resulting BotFather token is pasted
+ * back into {@link TelegramProvider.connect} to finish the installation.
+ */
+declare const BOTFATHER_DEEP_LINK = "https://t.me/botfather";
+/**
+ * Configuration for {@link TelegramProvider}.
+ *
+ * Telegram has no OAuth and no org-level parent credential: a BotFather bot
+ * token *is* the credential (one token per bot). Multi-tenancy is therefore a
+ * store of bot tokens — see {@link TelegramInstallation}.
+ */
+interface TelegramProviderConfig {
+    /**
+     * Public HTTPS base URL used to register per-bot webhooks (`setWebhook`).
+     * May be omitted and auto-detected from the Mastra server config, or set later.
+     */
+    baseUrl?: string;
+    /**
+     * Persistence for bot installations. Defaults to Mastra's channels storage
+     * when the provider is attached to a Mastra instance with storage, and falls
+     * back to an in-memory store otherwise (dev/test — not persisted across restarts).
+     */
+    storage?: ChannelsStorage;
+    /**
+     * Override the Telegram Bot API origin (e.g. a self-hosted Bot API server or
+     * a test mock).
+     *
+     * @default 'https://api.telegram.org'
+     */
+    apiBaseUrl?: string;
+    /**
+     * Passphrase for encrypting `botToken`/`secretToken` at rest (AES-256-GCM).
+     * Defaults to the `MASTRA_ENCRYPTION_KEY` env var. When unset, secrets are
+     * stored in plaintext (fine for the in-memory dev store; set a key for any
+     * persistent backend).
+     */
+    encryptionKey?: string;
+    /**
+     * Receive transport. Setting a webhook and long-polling are mutually
+     * exclusive; the provider manages the switch per bot.
+     *
+     * @default 'auto'
+     */
+    mode?: TelegramMode;
+    /**
+     * Update types to request in `setWebhook`. Defaults to
+     * {@link DEFAULT_ALLOWED_UPDATES}.
+     */
+    allowedUpdates?: string[];
+    /**
+     * Long-polling tuning forwarded to the adapter's `getUpdates` loop when running
+     * in polling mode (`timeout`, `limit`, `allowedUpdates`, `retryDelayMs`, …).
+     * Ignored in webhook mode.
+     */
+    longPolling?: TelegramAdapterConfig['longPolling'];
+    /**
+     * Keep the serverless invocation alive while the agent stream runs after the
+     * webhook returns 200 (Vercel/AWS Lambda). Cloudflare/Netlify resolve this
+     * automatically. See `ChannelConfig.waitUntil`.
+     */
+    waitUntil?: WaitUntilFn;
+    /**
+     * Default commands registered via `setMyCommands` for every connected agent
+     * (a per-agent list can override via {@link TelegramConnectOptions.commands}).
+     * Defaults to the conventional `/start` `/help` `/settings` seed.
+     */
+    commands?: TelegramCommand[];
+    /**
+     * Command scope passed to `setMyCommands` (e.g. `{ type: 'all_private_chats' }`).
+     * Omitted → Telegram's default scope.
+     * @see https://core.telegram.org/bots/api#botcommandscope
+     */
+    commandScope?: Record<string, unknown>;
+    /**
+     * Stream agent text to Telegram as it generates, via the adapter's
+     * post-and-edit (`editMessageText`) loop. Telegram has no native token
+     * streaming, so this chunk-edits the reply (4096-char cap handled by the
+     * adapter).
+     *
+     * @default true
+     */
+    streaming?: StreamingConfig;
+    /**
+     * Keep a typing indicator alive during generation (`sendChatAction`, re-sent
+     * as it auto-clears). Set `false` to disable.
+     *
+     * @default true
+     */
+    typingStatus?: boolean;
+    /**
+     * Override built-in event handlers (`onDirectMessage`, `onMention`,
+     * `onSubscribedMessage`). Forwarded to `AgentChannels`.
+     */
+    handlers?: ChannelHandlers;
+    /** Which media types to send inline to the model. See `ChannelConfig.inlineMedia`. */
+    inlineMedia?: ChannelConfig['inlineMedia'];
+    /** Promote URLs in message text to file parts. See `ChannelConfig.inlineLinks`. */
+    inlineLinks?: ChannelConfig['inlineLinks'];
+    /** State adapter for deduplication, locking, and subscriptions. See `ChannelConfig.state`. */
+    state?: ChannelConfig['state'];
+    /** Fetch recent thread messages when the agent joins mid-conversation. See `ChannelConfig.threadContext`. */
+    threadContext?: ChannelConfig['threadContext'];
+    /** Additional options passed directly to the Chat SDK. See `ChannelConfig.chatOptions`. */
+    chatOptions?: ChannelConfig['chatOptions'];
+    /** Resolve the memory `resourceId` before a channel thread is created. See `ChannelConfig.resolveResourceId`. */
+    resolveResourceId?: ChannelConfig['resolveResourceId'];
+    /**
+     * Resolve `waitUntil` from the request's Hono `Context` (serverless runtimes
+     * whose `waitUntil` derives from the request). See `ChannelConfig.resolveWaitUntil`.
+     */
+    resolveWaitUntil?: ChannelConfig['resolveWaitUntil'];
+    /** CORS configuration for the generated Telegram webhook route. */
+    cors?: ChannelAdapterConfig['cors'];
+    /** Override how errors are rendered in Telegram messages. See `ChannelAdapterConfig.formatError`. */
+    formatError?: ChannelAdapterConfig['formatError'];
+    /**
+     * How tool calls are rendered in the reply. Telegram has no Block Kit, so
+     * `'cards'`/`'grouped'`/`'timeline'` degrade to plain fallback text — this
+     * defaults to `'text'` (unlike Slack's `'grouped'`). See `ChannelAdapterConfig.toolDisplay`.
+     *
+     * @default 'text'
+     */
+    toolDisplay?: ChannelAdapterConfig['toolDisplay'];
+    /**
+     * Whether to expose channel reaction tools (`add_reaction`/`remove_reaction`)
+     * to the agent. Set `false` for models without function calling. See `ChannelConfig.tools`.
+     *
+     * @default true
+     */
+    tools?: ChannelConfig['tools'];
+    /** Logger forwarded to the underlying `TelegramAdapter` for internal error reporting. */
+    logger?: TelegramAdapterConfig['logger'];
+    /** Called after an agent successfully connects a bot and the installation is persisted. */
+    onInstall?: (installation: TelegramInstallation) => void | Promise<void>;
+}
+/** Options accepted by {@link TelegramProvider.connect}. */
+interface TelegramConnectOptions {
+    /**
+     * A BotFather bot token. When supplied it is validated via `getMe` and the
+     * installation becomes active immediately (`{ type: 'immediate' }`). Omit it
+     * to receive a BotFather deep link instead (`{ type: 'deep_link' }`).
+     */
+    botToken?: string;
+    /** Display name for the bot. Defaults to the bot's `@username` from `getMe`. */
+    name?: string;
+    /**
+     * Commands to register via `setMyCommands` for this agent. Overrides
+     * {@link TelegramProviderConfig.commands}. Defaults to the `/start` `/help`
+     * `/settings` seed when neither is set.
+     */
+    commands?: TelegramCommand[];
+}
+/**
+ * A registered Telegram bot bound to a single agent (one bot = one agent).
+ * Persisted through {@link TelegramInstallStore}.
+ */
+interface TelegramInstallation {
+    /** Stable installation id. */
+    id: string;
+    /** The agent this bot is bound to. */
+    agentId: string;
+    /**
+     * Opaque id embedded in the webhook route path (`/telegram/events/:webhookId`).
+     * Never the secret — the secret travels only in the request header.
+     */
+    webhookId: string;
+    /** Whether a bot token has been ingested and validated. */
+    status: 'active' | 'pending';
+    /** BotFather bot token — the full credential. Present once ingested. */
+    botToken?: string;
+    /**
+     * Per-bot webhook shared secret, echoed by Telegram as the
+     * `X-Telegram-Bot-Api-Secret-Token` header on every inbound POST.
+     */
+    secretToken?: string;
+    /** The bot's `@username`, resolved from `getMe`. */
+    username?: string;
+    /** The webhook URL registered with `setWebhook` (M1 — issue `mastra-telegram-i2g.3`). */
+    webhookUrl?: string;
+    /** Normalized commands registered via `setMyCommands`. */
+    commands?: BotCommand[];
+    /** When the installation was created. */
+    installedAt: Date;
+}
+
+/**
+ * Resolve the per-adapter streaming/typing config the provider applies to the
+ * Telegram entry in `AgentChannels.adapters`. This is the wrapper's stream
+ * binding: enabling `streaming` runs the adapter's post-and-edit
+ * (`editMessageText`) chunking loop, and `typingStatus` keeps a `sendChatAction`
+ * indicator alive — both default on.
+ */
+declare function resolveTelegramAdapterConfig(config: Pick<TelegramProviderConfig, 'streaming' | 'typingStatus'>): {
+    streaming: StreamingConfig;
+    typingStatus: boolean;
+};
+/**
+ * Telegram channel provider for Mastra — a {@link ChannelProvider} over
+ * `@chat-adapter/telegram`. The adapter handles the Bot API transport (webhook
+ * parse, send/edit, typing, rich messages); this provider adds the
+ * install/lifecycle layer.
+ *
+ * Implemented:
+ * - **`mastra-telegram-i2g.2`** — multi-token install store (one bot = one
+ *   agent), `connect()`/`disconnect()`, `getMe` token ingestion.
+ * - **`mastra-telegram-i2g.3`** — per-bot `setWebhook` lifecycle,
+ *   `X-Telegram-Bot-Api-Secret-Token` verification, webhook⇄polling exclusion,
+ *   and a mounted POST route that delegates to `AgentChannels.handleWebhookEvent`.
+ *
+ * Later: `setMyCommands` + streaming (`mastra-telegram-i2g.4`).
+ *
+ * @example
+ * ```ts
+ * const telegram = new TelegramProvider({ baseUrl: 'https://my-app.example.com' })
+ * const mastra = new Mastra({ agents: { myAgent }, channels: { telegram } })
+ * await telegram.connect('my-agent', { botToken: '123456:ABC-...' }) // → { type: 'immediate' }
+ * ```
+ */
+declare class TelegramProvider implements ChannelProvider {
+    #private;
+    readonly id = "telegram";
+    constructor(config?: TelegramProviderConfig);
+    /**
+     * Called by Mastra when this channel is registered.
+     * @internal
+     */
+    __attach(mastra: Mastra): void;
+    /**
+     * Per-bot webhook route. A single POST endpoint keyed by an opaque
+     * `webhookId`; the per-bot secret is verified from the request header, never
+     * carried in the URL. Auto-initializes on first hit (mirrors `@mastra/slack`).
+     */
+    getRoutes(): ApiRoute[];
+    /** Discovery metadata for the editor UI. */
+    getInfo(): ChannelPlatformInfo;
+    /**
+     * Restore installations from storage: rebuild an adapter per active bot and
+     * inject `AgentChannels` so the agent can receive events immediately.
+     * Idempotent. Does not re-register webhooks (they persist server-side across
+     * restarts); reconnect an agent if its `baseUrl` changed.
+     */
+    initialize(): Promise<void>;
+    /**
+     * Update runtime provider settings. Telegram has no global auth credential to
+     * clear (per-bot tokens are managed via {@link connect}/{@link disconnect}),
+     * so `null` is a no-op; an object merges `apiBaseUrl`/`baseUrl` overrides.
+     */
+    configure(credentials: {
+        apiBaseUrl?: string;
+        baseUrl?: string;
+    } | null): Promise<void>;
+    /**
+     * Connect an agent to a Telegram bot.
+     *
+     * - With `options.botToken`: validate via `getMe`, mint a per-bot webhook
+     *   secret, persist the installation, register the transport (webhook or
+     *   polling), and return `{ type: 'immediate' }`.
+     * - Without a token: persist a pending installation and return
+     *   `{ type: 'deep_link' }` pointing at BotFather.
+     */
+    connect(agentId: string, options?: TelegramConnectOptions): Promise<ChannelConnectResult>;
+    /** Disconnect an agent from Telegram, removing its webhook and installation. */
+    disconnect(agentId: string): Promise<void>;
+    /** List installations (public info only — no tokens or secrets). */
+    listInstallations(): Promise<ChannelInstallationInfo[]>;
+    /**
+     * Get the full installation for an agent (includes the bot token / secret).
+     * Returns `null` if the agent has no Telegram installation. Mirrors
+     * `SlackProvider.getInstallation`.
+     */
+    getInstallation(agentId: string): Promise<TelegramInstallation | null>;
+    /**
+     * Whether at least one bot is actively registered. Mirrors
+     * `SlackProvider.isConfigured` (Telegram has no global credential to check —
+     * "configured" means an active installation exists).
+     */
+    isConfigured(): boolean;
+    /**
+     * Get the live `TelegramAdapter` for an installation id, if one is active.
+     * Used for message formatting/posting. Mirrors `SlackProvider.getAdapter`.
+     */
+    getAdapter(installationId: string): TelegramAdapter | undefined;
+}
+
+/** Platform identifier used for every stored record and route. */
+declare const PLATFORM = "telegram";
+/**
+ * Persistence for Telegram bot installations, layered over the platform-agnostic
+ * `ChannelsStorage` (the same store `@mastra/slack` uses). Installations are
+ * keyed by agent — one bot = one agent — and the per-bot secret fields live in
+ * the record's `data` blob. When an `encryptionKey` is supplied, `botToken` and
+ * `secretToken` are AES-256-GCM encrypted at rest.
+ */
+declare class TelegramInstallStore {
+    #private;
+    private readonly storage;
+    private readonly encryptionKey?;
+    constructor(storage: ChannelsStorage, encryptionKey?: string | undefined);
+    /** The active or pending installation for an agent, if any. */
+    getByAgent(agentId: string): Promise<TelegramInstallation | null>;
+    /** Look up an installation by the routing id in its webhook path (M1 dispatch). */
+    getByWebhookId(webhookId: string): Promise<TelegramInstallation | null>;
+    /** Insert or replace an installation. */
+    save(installation: TelegramInstallation): Promise<void>;
+    /** All Telegram installations (active and pending). */
+    list(): Promise<TelegramInstallation[]>;
+    /** Remove an agent's installation, if present. */
+    deleteByAgent(agentId: string): Promise<void>;
+}
+/** Project an installation to its public, secret-free info for the editor UI. */
+declare function toInstallationInfo(install: TelegramInstallation): ChannelInstallationInfo;
+
+/**
+ * Validate a bot token via `getMe` and resolve the bot's identity. Throws if
+ * the token is rejected or the returned user is not a bot.
+ *
+ * @see https://core.telegram.org/bots/api#getme
+ */
+declare function getMe(botToken: string, apiBaseUrl?: string): Promise<TelegramUser>;
+/** Options for {@link setWebhook}. */
+interface SetWebhookOptions {
+    /** Public HTTPS URL Telegram will POST updates to. */
+    url: string;
+    /** Shared secret echoed back as `X-Telegram-Bot-Api-Secret-Token` on every POST. */
+    secretToken: string;
+    /** Update types to receive. Note: `message_reaction` must be listed explicitly. */
+    allowedUpdates?: string[];
+    /** Drop the backlog of updates queued while the bot was offline. */
+    dropPendingUpdates?: boolean;
+}
+/**
+ * Register a per-bot webhook. Setting a webhook disables `getUpdates`
+ * (long-polling) for that bot — the two transports are mutually exclusive.
+ *
+ * @see https://core.telegram.org/bots/api#setwebhook
+ */
+declare function setWebhook(botToken: string, options: SetWebhookOptions, apiBaseUrl?: string): Promise<void>;
+/**
+ * Remove a bot's webhook. Required before switching a bot to long-polling
+ * (`getUpdates` fails while a webhook is set).
+ *
+ * @see https://core.telegram.org/bots/api#deletewebhook
+ */
+declare function deleteWebhook(botToken: string, dropPendingUpdates?: boolean, apiBaseUrl?: string): Promise<void>;
+/** Options for {@link setMyCommands}. */
+interface SetMyCommandsOptions {
+    /** The command list to publish (replaces the existing set for the scope). */
+    commands: BotCommand[];
+    /** Command scope (e.g. `{ type: 'all_private_chats' }`). Omit for the default scope. */
+    scope?: Record<string, unknown>;
+    /** Two-letter language code for a localized command set. */
+    languageCode?: string;
+}
+/**
+ * Publish the bot's command list for a scope.
+ *
+ * @see https://core.telegram.org/bots/api#setmycommands
+ */
+declare function setMyCommands(botToken: string, options: SetMyCommandsOptions, apiBaseUrl?: string): Promise<void>;
+/**
+ * Generate a webhook secret token within Telegram's `setWebhook` constraint:
+ * 1-256 chars from `[A-Za-z0-9_-]`. base64url of 32 random bytes yields 43
+ * such chars.
+ *
+ * @see https://core.telegram.org/bots/api#setwebhook
+ */
+declare function generateSecretToken(): string;
+
+/**
+ * Conventional command seed registered when a connect provides none.
+ * @see https://core.telegram.org/bots/features#commands
+ */
+declare const DEFAULT_COMMANDS: readonly TelegramCommand[];
+/**
+ * Map user-supplied commands (agent capabilities) to Telegram `BotCommand[]`,
+ * enforcing the Bot API constraints: `command` is lowercased, stripped of a
+ * leading slash, reduced to `[a-z0-9_]`, and clamped to 1-32 chars;
+ * `description` defaults to `Run /<command>` and is clamped to 256 chars.
+ * Empty or duplicate command names are dropped.
+ */
+declare function normalizeCommands(raw: readonly TelegramCommand[] | undefined): BotCommand[];
+
+export { BOTFATHER_DEEP_LINK, type BotCommand, DEFAULT_ALLOWED_UPDATES, DEFAULT_COMMANDS, PLATFORM, type SetMyCommandsOptions, type SetWebhookOptions, TELEGRAM_API_BASE_URL, type TelegramCommand, type TelegramConnectOptions, TelegramInstallStore, type TelegramInstallation, type TelegramMode, TelegramProvider, type TelegramProviderConfig, deleteWebhook, generateSecretToken, getMe, normalizeCommands, resolveTelegramAdapterConfig, setMyCommands, setWebhook, toInstallationInfo };