@mastra/telegram 0.0.0-aggregate-trace-20261015182851

package/dist/index.js

@@ -0,0 +1,834 @@
+import { createCipheriv, createDecipheriv, hkdfSync, timingSafeEqual } from "crypto";
+import { AgentChannels, resolveWaitUntil } from "@mastra/core/channels";
+import { InMemoryChannelsStorage } from "@mastra/core/storage";
+import { TelegramAdapter, createTelegramAdapter, createTelegramAdapter as createTelegramAdapter$1 } from "@chat-adapter/telegram";
+//#region src/types.ts
+/** Default Telegram Bot API origin. */
+const TELEGRAM_API_BASE_URL = "https://api.telegram.org";
+/**
+* Default update types requested from Telegram. `message_reaction` must be
+* listed explicitly (Telegram omits it otherwise).
+*/
+const DEFAULT_ALLOWED_UPDATES = [
+	"message",
+	"edited_message",
+	"channel_post",
+	"edited_channel_post",
+	"callback_query",
+	"message_reaction"
+];
+/**
+* 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.
+*/
+const BOTFATHER_DEEP_LINK = "https://t.me/botfather";
+//#endregion
+//#region src/telegram-client.ts
+/**
+* Call a Bot API method. Sends a `GET` when `payload` is omitted and a JSON
+* `POST` otherwise. Throws when the transport fails or the API returns
+* `ok: false`.
+*/
+async function botApiRequest(botToken, method, apiBaseUrl, payload) {
+	const init = payload === void 0 ? void 0 : {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify(payload)
+	};
+	let response;
+	try {
+		response = await fetch(`${apiBaseUrl}/bot${botToken}/${method}`, {
+			...init,
+			signal: AbortSignal.timeout(1e4)
+		});
+	} catch (cause) {
+		throw Object.assign(new Error(`Telegram ${method} request failed`, { cause }), { isTransportError: true });
+	}
+	const body = await response.json().catch(() => null);
+	if (!response.ok || !body?.ok) {
+		const detail = body?.description ?? `HTTP ${response.status}`;
+		throw new Error(`Telegram ${method} failed: ${detail}`);
+	}
+	return body.result;
+}
+/**
+* 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
+*/
+async function getMe(botToken, apiBaseUrl = TELEGRAM_API_BASE_URL) {
+	let result;
+	try {
+		result = await botApiRequest(botToken, "getMe", apiBaseUrl);
+	} catch (cause) {
+		if (cause instanceof Error && cause.isTransportError) throw cause;
+		throw new Error(`Telegram rejected the bot token: ${cause instanceof Error ? cause.message : String(cause)}`, { cause });
+	}
+	if (!result?.is_bot) throw new Error("Telegram getMe returned a non-bot user; expected a BotFather token");
+	return result;
+}
+/**
+* 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
+*/
+async function setWebhook(botToken, options, apiBaseUrl = TELEGRAM_API_BASE_URL) {
+	await botApiRequest(botToken, "setWebhook", apiBaseUrl, {
+		url: options.url,
+		secret_token: options.secretToken,
+		allowed_updates: options.allowedUpdates,
+		drop_pending_updates: options.dropPendingUpdates
+	});
+}
+/**
+* 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
+*/
+async function deleteWebhook(botToken, dropPendingUpdates = false, apiBaseUrl = TELEGRAM_API_BASE_URL) {
+	await botApiRequest(botToken, "deleteWebhook", apiBaseUrl, { drop_pending_updates: dropPendingUpdates });
+}
+/**
+* Publish the bot's command list for a scope.
+*
+* @see https://core.telegram.org/bots/api#setmycommands
+*/
+async function setMyCommands(botToken, options, apiBaseUrl = TELEGRAM_API_BASE_URL) {
+	await botApiRequest(botToken, "setMyCommands", apiBaseUrl, {
+		commands: options.commands,
+		scope: options.scope,
+		language_code: options.languageCode
+	});
+}
+/**
+* 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
+*/
+function generateSecretToken() {
+	return Buffer.from(globalThis.crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(32))).toString("base64url");
+}
+//#endregion
+//#region src/commands.ts
+/**
+* Conventional command seed registered when a connect provides none.
+* @see https://core.telegram.org/bots/features#commands
+*/
+const DEFAULT_COMMANDS = [
+	{
+		command: "start",
+		description: "Start a conversation"
+	},
+	{
+		command: "help",
+		description: "Show what this bot can do"
+	},
+	{
+		command: "settings",
+		description: "Manage your preferences"
+	}
+];
+/**
+* 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.
+*/
+function normalizeCommands(raw) {
+	if (!raw) return [];
+	const seen = /* @__PURE__ */ new Set();
+	const commands = [];
+	for (const item of raw) {
+		const input = typeof item === "string" ? { command: item } : item;
+		const command = input.command.replace(/^\//, "").toLowerCase().replace(/[^a-z0-9_]/g, "").slice(0, 32);
+		if (!command || seen.has(command)) continue;
+		seen.add(command);
+		const description = (input.description?.trim() || `Run /${command}`).slice(0, 256);
+		commands.push({
+			command,
+			description
+		});
+	}
+	return commands;
+}
+//#endregion
+//#region src/crypto.ts
+/**
+* Opt-in AES-256-GCM encryption for installation secrets at rest, with
+* HKDF-SHA256 key derivation (mirrors `@mastra/slack`'s `crypto.ts`). Each value
+* gets a fresh random 16-byte salt + 12-byte IV; the salt travels in the
+* ciphertext, so the same passphrase never derives the same key twice. The
+* algorithm prefix lets plaintext and encrypted values coexist during migration,
+* so {@link decrypt} can no-op on plaintext.
+*
+* Format: `aes-256-gcm-hkdf:base64(salt):base64(iv):base64(authTag):base64(ciphertext)`
+*/
+const ALGO_PREFIX = "aes-256-gcm-hkdf";
+const HKDF_INFO = "mastra-telegram-encryption";
+function deriveKey(passphrase, salt) {
+	return Buffer.from(hkdfSync("sha256", passphrase, salt, HKDF_INFO, 32));
+}
+/** Whether a stored value was produced by {@link encrypt}. */
+function isEncrypted(value) {
+	return value.startsWith(`${ALGO_PREFIX}:`);
+}
+/** Encrypt a UTF-8 string with a per-value random salt + IV. */
+function encrypt(plaintext, passphrase) {
+	const salt = Buffer.from(globalThis.crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(16)));
+	const iv = Buffer.from(globalThis.crypto.getRandomValues(/* @__PURE__ */ new Uint8Array(12)));
+	const cipher = createCipheriv("aes-256-gcm", deriveKey(passphrase, salt), iv);
+	const enc = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+	const tag = cipher.getAuthTag();
+	return `${ALGO_PREFIX}:${salt.toString("base64")}:${iv.toString("base64")}:${tag.toString("base64")}:${enc.toString("base64")}`;
+}
+/** Decrypt a value from {@link encrypt}. Plaintext (unprefixed) is returned unchanged. */
+function decrypt(value, passphrase) {
+	if (!isEncrypted(value)) return value;
+	const [, saltB64, ivB64, tagB64, ctB64] = value.split(":");
+	if (!saltB64 || !ivB64 || !tagB64 || ctB64 === void 0) throw new Error("Invalid ciphertext payload");
+	const decipher = createDecipheriv("aes-256-gcm", deriveKey(passphrase, Buffer.from(saltB64, "base64")), Buffer.from(ivB64, "base64"));
+	decipher.setAuthTag(Buffer.from(tagB64, "base64"));
+	return Buffer.concat([decipher.update(Buffer.from(ctB64, "base64")), decipher.final()]).toString("utf8");
+}
+//#endregion
+//#region src/install-store.ts
+/** Platform identifier used for every stored record and route. */
+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.
+*/
+var TelegramInstallStore = class {
+	storage;
+	encryptionKey;
+	constructor(storage, encryptionKey) {
+		this.storage = storage;
+		this.encryptionKey = encryptionKey;
+	}
+	/** The active or pending installation for an agent, if any. */
+	async getByAgent(agentId) {
+		const record = await this.storage.getInstallationByAgent(PLATFORM, agentId);
+		return record ? this.#fromRecord(record) : null;
+	}
+	/** Look up an installation by the routing id in its webhook path (M1 dispatch). */
+	async getByWebhookId(webhookId) {
+		const record = await this.storage.getInstallationByWebhookId(webhookId);
+		return record && record.platform === "telegram" ? this.#fromRecord(record) : null;
+	}
+	/** Insert or replace an installation. */
+	async save(installation) {
+		await this.storage.saveInstallation(this.#toRecord(installation));
+	}
+	/** All Telegram installations (active and pending). */
+	async list() {
+		return (await this.storage.listInstallations(PLATFORM)).map((r) => this.#fromRecord(r));
+	}
+	/** Remove an agent's installation, if present. */
+	async deleteByAgent(agentId) {
+		const record = await this.storage.getInstallationByAgent(PLATFORM, agentId);
+		if (record) await this.storage.deleteInstallation(record.id);
+	}
+	#enc(value) {
+		return value && this.encryptionKey ? encrypt(value, this.encryptionKey) : value;
+	}
+	#dec(value) {
+		if (!value) return value;
+		if (!this.encryptionKey) {
+			if (isEncrypted(value)) throw new Error("Telegram installation secrets are encrypted at rest, but no encryption key is configured. Set `encryptionKey` on TelegramProvider or MASTRA_ENCRYPTION_KEY.");
+			return value;
+		}
+		return decrypt(value, this.encryptionKey);
+	}
+	#toRecord(install) {
+		const data = {
+			botToken: this.#enc(install.botToken),
+			botUserId: install.botUserId,
+			secretToken: this.#enc(install.secretToken),
+			username: install.username,
+			webhookUrl: install.webhookUrl,
+			commands: install.commands
+		};
+		return {
+			id: install.id,
+			platform: PLATFORM,
+			agentId: install.agentId,
+			status: install.status,
+			webhookId: install.webhookId,
+			data,
+			createdAt: install.installedAt,
+			updatedAt: /* @__PURE__ */ new Date()
+		};
+	}
+	#fromRecord(record) {
+		const data = record.data ?? {};
+		return {
+			id: record.id,
+			agentId: record.agentId,
+			webhookId: record.webhookId ?? "",
+			status: record.status === "active" ? "active" : "pending",
+			botToken: this.#dec(data.botToken),
+			botUserId: data.botUserId,
+			secretToken: this.#dec(data.secretToken),
+			username: data.username,
+			webhookUrl: data.webhookUrl,
+			commands: data.commands,
+			installedAt: record.createdAt
+		};
+	}
+};
+/** Project an installation to its public, secret-free info for the editor UI. */
+function toInstallationInfo(install) {
+	return {
+		id: install.id,
+		platform: PLATFORM,
+		agentId: install.agentId,
+		status: install.status,
+		displayName: install.username,
+		installedAt: install.installedAt
+	};
+}
+//#endregion
+//#region src/telegram-provider.ts
+/**
+* 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.
+*/
+function resolveTelegramAdapterConfig(config) {
+	return {
+		streaming: config.streaming ?? true,
+		typingStatus: config.typingStatus ?? true
+	};
+}
+/** Header Telegram echoes the per-bot secret on for every webhook POST. */
+const SECRET_HEADER = "x-telegram-bot-api-secret-token";
+/**
+* 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' }
+* ```
+*/
+var TelegramProvider = class {
+	id = PLATFORM;
+	#config;
+	#mastra;
+	#store;
+	/** Live adapters, keyed by installation id. */
+	#adapters = /* @__PURE__ */ new Map();
+	/** Cached sync view of whether any active bot is registered (for {@link getInfo}). */
+	#configured = false;
+	#initPromise = null;
+	#connectingBotTokens = /* @__PURE__ */ new Set();
+	constructor(config = {}) {
+		if ("tokenResolver" in config && config.tokenResolver && "botToken" in config && config.botToken) throw new Error("TelegramProvider cannot be constructed with both `botToken` and `tokenResolver` — pick one credential mode (self-managed or delegated).");
+		this.#config = config;
+	}
+	/**
+	* Called by Mastra when this channel is registered.
+	* @internal
+	*/
+	__attach(mastra) {
+		if (this.#mastra && this.#mastra !== mastra) {
+			this.#initPromise = null;
+			this.#store = void 0;
+			this.#adapters.clear();
+			this.#configured = false;
+		}
+		this.#mastra = mastra;
+	}
+	/**
+	* 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() {
+		const self = this;
+		const withInit = (handler) => {
+			return async ({ mastra }) => {
+				self.#mastra = mastra;
+				await self.#autoInitialize();
+				return handler.bind(self);
+			};
+		};
+		return [{
+			path: `/${PLATFORM}/events/:webhookId`,
+			method: "POST",
+			requiresAuth: false,
+			createHandler: withInit(this.#handleWebhook)
+		}];
+	}
+	/** Discovery metadata for the editor UI. */
+	getInfo() {
+		return {
+			id: this.id,
+			name: "Telegram",
+			isConfigured: this.isConfigured(),
+			connectOptionsSchema: {
+				type: "object",
+				properties: {
+					botToken: {
+						type: "string",
+						description: "BotFather bot token. Omit to use the provider default token. If neither is set, returns a BotFather deep link."
+					},
+					name: {
+						type: "string",
+						description: "Display name for the bot (defaults to the bot's @username)."
+					}
+				}
+			}
+		};
+	}
+	/**
+	* 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.
+	*/
+	async initialize() {
+		if (this.#initPromise) return this.#initPromise;
+		this.#initPromise = this.#doInitialize();
+		try {
+			await this.#initPromise;
+		} catch (err) {
+			this.#initPromise = null;
+			throw err;
+		}
+	}
+	async #doInitialize() {
+		const store = await this.#getStore();
+		const active = (await store.list()).filter((i) => i.status === "active");
+		this.#configured = active.length > 0;
+		for (const installation of active) try {
+			const prepared = await this.#migrateInstallation(installation, store);
+			if (!prepared) continue;
+			await this.#activateInstallation(prepared);
+		} catch (err) {
+			console.error(`[Telegram] Failed to restore installation "${installation.id}":`, err);
+		}
+	}
+	/**
+	* Bring a stored installation up to the provider's current credential mode.
+	*
+	* When {@link TelegramProviderConfig.tokenResolver} is configured but the
+	* record was written under self-managed mode, the record still carries a
+	* `botToken` and may be missing `botUserId`. Left as-is, the adapter would
+	* keep using that stale token (bypassing rotation) and duplicate detection
+	* would fall back to token comparison. Resolve the current token, verify it
+	* points at the same bot, populate `botUserId` if missing, and drop the
+	* persisted token so future rotations flow through the resolver.
+	*
+	* For a legacy record with no `botUserId`, the "same bot" check needs an
+	* expected identity — so we `getMe` the stored `botToken` first and compare
+	* that identity to the resolver's. A stored-token lookup failure leaves the
+	* record untouched (we cannot prove it's still the same bot, and silently
+	* assigning `me.id` would let a repointed resolver retarget the install and
+	* orphan the old bot's webhook).
+	*
+	* A resolver failure — or an identity mismatch — is not fatal here: we log
+	* and leave the record untouched, so the operator can investigate before
+	* connect/disconnect on that installation.
+	*/
+	async #migrateInstallation(installation, store) {
+		if (!this.#config.tokenResolver) return installation;
+		const needsMigration = installation.botToken !== void 0 || installation.botUserId === void 0;
+		const needsIdentityCheck = installation.botUserId !== void 0;
+		if (!needsMigration && !needsIdentityCheck) return installation;
+		try {
+			const resolved = await this.#config.tokenResolver();
+			if (!resolved) return installation;
+			const me = await getMe(resolved, this.#apiBaseUrl());
+			let expectedBotUserId = installation.botUserId;
+			if (expectedBotUserId === void 0 && installation.botToken) try {
+				expectedBotUserId = (await getMe(installation.botToken, this.#apiBaseUrl())).id;
+			} catch (err) {
+				console.warn(`[Telegram] Could not verify stored bot identity for installation "${installation.id}" during delegated-mode migration; leaving the record untouched.`, err);
+				return installation;
+			}
+			if (expectedBotUserId !== void 0 && expectedBotUserId !== me.id) {
+				console.warn(`[Telegram] Delegated credential for installation "${installation.id}" now resolves to bot ${me.id} but was bot ${expectedBotUserId}. Disconnect and reconnect the agent to adopt the new bot.`);
+				return null;
+			}
+			if (!needsMigration) return installation;
+			const { botToken: _dropped, ...rest } = installation;
+			const migrated = {
+				...rest,
+				botUserId: me.id
+			};
+			await store.save(migrated);
+			return migrated;
+		} catch (err) {
+			console.warn(`[Telegram] Delegated-mode migration failed for installation "${installation.id}":`, err);
+			return installation;
+		}
+	}
+	/**
+	* Update runtime provider settings. Pass `botToken` to change the default
+	* bot token new {@link connect} calls fall back to when none is supplied
+	* per-agent (matching {@link SlackProvider.configure}'s rotation pattern);
+	* pass `apiBaseUrl`/`baseUrl` to point the adapter at a different host.
+	* `null` clears the default `botToken` only — per-bot installs are managed
+	* via {@link connect}/{@link disconnect}.
+	*/
+	async configure(credentials) {
+		if (this.#config.tokenResolver && credentials?.botToken !== void 0) throw new Error("TelegramProvider was constructed with a tokenResolver — bot tokens are managed externally. Remove the tokenResolver to manage credentials manually via configure().");
+		if (credentials === null) {
+			this.#config = {
+				...this.#config,
+				botToken: void 0
+			};
+			return;
+		}
+		const apiBaseUrlChanged = credentials.apiBaseUrl !== void 0 && credentials.apiBaseUrl !== this.#config.apiBaseUrl;
+		this.#config = {
+			...this.#config,
+			...credentials
+		};
+		if (!apiBaseUrlChanged) return;
+		const wasInitialized = this.#initPromise !== null;
+		for (const adapter of this.#adapters.values()) try {
+			await adapter.stopPolling();
+		} catch (err) {
+			console.warn("[Telegram] Failed to stop polling while reconfiguring:", err);
+		}
+		this.#adapters.clear();
+		this.#initPromise = null;
+		if (wasInitialized) await this.initialize();
+	}
+	/**
+	* Connect an agent to a Telegram bot.
+	*
+	* - With `options.botToken` or a provider default token: validate via `getMe`,
+	*   mint a per-bot webhook secret, persist the installation, register the
+	*   transport (webhook or polling), and return `{ type: 'immediate' }`.
+	* - Without either token: persist a pending installation and return
+	*   `{ type: 'deep_link' }` pointing at BotFather.
+	*/
+	async connect(agentId, options = {}) {
+		const store = await this.#getStore();
+		const existing = await store.getByAgent(agentId);
+		if (existing?.status === "active") throw new Error(`Agent "${agentId}" is already connected to Telegram. Disconnect first to reconnect.`);
+		if (this.#config.tokenResolver && options.botToken !== void 0) throw new Error("TelegramProvider was constructed with a tokenResolver — bot tokens are managed externally and cannot be supplied per connect() call.");
+		let botToken;
+		if (this.#config.tokenResolver) {
+			const resolved = await this.#config.tokenResolver();
+			if (!resolved) throw new Error("TelegramProvider tokenResolver returned an empty bot token. Attach a Telegram bot credential upstream before connecting an agent.");
+			botToken = resolved;
+		} else botToken = options.botToken ?? this.#config.botToken;
+		if (!botToken) {
+			const installationId = existing?.id ?? globalThis.crypto.randomUUID();
+			await store.save({
+				id: installationId,
+				agentId,
+				webhookId: existing?.webhookId ?? globalThis.crypto.randomUUID(),
+				status: "pending",
+				installedAt: existing?.installedAt ?? /* @__PURE__ */ new Date()
+			});
+			return {
+				type: "deep_link",
+				url: BOTFATHER_DEEP_LINK,
+				installationId
+			};
+		}
+		const baseUrl = this.#getBaseUrl();
+		const mode = this.#resolveMode(baseUrl);
+		if (mode === "webhook" && !baseUrl) throw new Error("TelegramProvider needs a baseUrl to register a webhook. Set `baseUrl`, configure the Mastra server, or use `mode: \"polling\"`.");
+		if (this.#connectingBotTokens.has(botToken)) throw new Error("This Telegram bot is already being connected. Wait for that connection to finish.");
+		this.#connectingBotTokens.add(botToken);
+		try {
+			const me = await getMe(botToken, this.#apiBaseUrl());
+			const duplicate = (await store.list()).find((i) => i.status === "active" && i.agentId !== agentId && (i.botUserId !== void 0 ? i.botUserId === me.id : i.botToken === botToken));
+			if (duplicate) throw new Error(`This Telegram bot is already connected to agent "${duplicate.agentId}". Disconnect it before connecting another agent.`);
+			const installationId = existing?.id ?? globalThis.crypto.randomUUID();
+			const webhookId = existing?.webhookId ?? globalThis.crypto.randomUUID();
+			const webhookUrl = mode === "webhook" ? `${baseUrl}/${PLATFORM}/events/${webhookId}` : void 0;
+			const commands = normalizeCommands(options.commands ?? this.#config.commands ?? DEFAULT_COMMANDS);
+			const installation = {
+				id: installationId,
+				agentId,
+				webhookId,
+				status: "active",
+				...this.#config.tokenResolver ? {} : { botToken },
+				botUserId: me.id,
+				secretToken: generateSecretToken(),
+				username: options.name ?? me.username ?? me.first_name,
+				webhookUrl,
+				commands: commands.length ? commands : void 0,
+				installedAt: existing?.installedAt ?? /* @__PURE__ */ new Date()
+			};
+			await this.#registerTransport(installation, mode, botToken);
+			await this.#registerCommands(installation, botToken);
+			await store.save(installation);
+			await this.#activateInstallation(installation);
+			this.#configured = true;
+			await this.#config.onInstall?.(installation);
+			return {
+				type: "immediate",
+				installationId
+			};
+		} finally {
+			this.#connectingBotTokens.delete(botToken);
+		}
+	}
+	/** Disconnect an agent from Telegram, removing its webhook and installation. */
+	async disconnect(agentId) {
+		const store = await this.#getStore();
+		const existing = await store.getByAgent(agentId);
+		if (!existing) throw new Error(`No Telegram installation found for agent "${agentId}"`);
+		const adapter = this.#adapters.get(existing.id);
+		if (adapter) try {
+			await adapter.stopPolling();
+		} catch (err) {
+			console.warn(`[Telegram] Failed to stop polling for agent "${agentId}":`, err);
+		}
+		try {
+			let botToken;
+			if (existing.botToken) botToken = existing.botToken;
+			else if (this.#config.tokenResolver) {
+				const resolved = await this.#config.tokenResolver();
+				if (resolved && existing.botUserId !== void 0) {
+					const me = await getMe(resolved, this.#apiBaseUrl());
+					if (me.id !== existing.botUserId) console.warn(`[Telegram] Skipping deleteWebhook for agent "${agentId}": resolver now points at bot ${me.id} but this installation was bot ${existing.botUserId}.`);
+					else botToken = resolved;
+				} else if (resolved) botToken = resolved;
+			}
+			if (botToken) await deleteWebhook(botToken, true, this.#apiBaseUrl());
+		} catch (err) {
+			console.warn(`[Telegram] Failed to delete webhook for agent "${agentId}":`, err);
+		}
+		this.#adapters.delete(existing.id);
+		await store.deleteByAgent(agentId);
+		this.#configured = (await store.list()).some((i) => i.status === "active");
+	}
+	/** List installations (public info only — no tokens or secrets). */
+	async listInstallations() {
+		return (await (await this.#getStore()).list()).map(toInstallationInfo);
+	}
+	/**
+	* Get the full installation for an agent (includes the bot token / secret).
+	* Returns `null` if the agent has no Telegram installation. Mirrors
+	* `SlackProvider.getInstallation`.
+	*/
+	async getInstallation(agentId) {
+		return await (await this.#getStore()).getByAgent(agentId) ?? null;
+	}
+	/**
+	* Whether the provider is ready to connect agents: either a bot is already
+	* registered (#configured) or a credential source exists — a default
+	* `botToken`, or a `tokenResolver` in delegated mode (@mastra/connect).
+	* Without the credential-source half, a freshly attached platform credential
+	* reports unconfigured and UIs hide the connect action entirely. Mirrors
+	* `DiscordProvider.isConfigured` / `SlackProvider.isConfigured`.
+	*/
+	isConfigured() {
+		return this.#configured || Boolean(this.#config.tokenResolver ?? this.#config.botToken);
+	}
+	/**
+	* Get the live `TelegramAdapter` for an installation id, if one is active.
+	* Used for message formatting/posting. Mirrors `SlackProvider.getAdapter`.
+	*/
+	getAdapter(installationId) {
+		return this.#adapters.get(installationId);
+	}
+	async #handleWebhook(c) {
+		const webhookId = c.req.param("webhookId");
+		if (!webhookId) return c.json({
+			ok: false,
+			error: "Missing webhookId"
+		}, 400);
+		const installation = await (await this.#getStore()).getByWebhookId(webhookId);
+		if (!installation || installation.status !== "active") return c.json({
+			ok: false,
+			error: "Unknown webhook"
+		}, 404);
+		if (!secretMatches(c.req.header(SECRET_HEADER), installation.secretToken)) return c.json({
+			ok: false,
+			error: "Invalid secret token"
+		}, 401);
+		const agent = this.#resolveAgent(installation.agentId);
+		if (!agent || !this.#mastra) return c.json({ ok: true });
+		const adapter = this.#getOrCreateAdapter(installation);
+		let channels = agent.getChannels();
+		if (!channels || channels.adapters["telegram"] !== adapter) {
+			channels = this.#createAgentChannels(agent, adapter);
+			await channels.initialize(this.#mastra);
+		}
+		const waitUntil = this.#config.waitUntil ?? resolveWaitUntil(c);
+		try {
+			return await channels.handleWebhookEvent(PLATFORM, c.req.raw, waitUntil ? { waitUntil } : void 0);
+		} catch (err) {
+			console.error("[Telegram] Error delegating to AgentChannels:", err);
+			return c.json({ ok: true });
+		}
+	}
+	#apiBaseUrl() {
+		return this.#config.apiBaseUrl ?? "https://api.telegram.org";
+	}
+	#resolveMode(baseUrl) {
+		const mode = this.#config.mode ?? "auto";
+		if (mode === "auto") return baseUrl ? "webhook" : "polling";
+		return mode;
+	}
+	/**
+	* Register (or clear) the receive transport for a bot, enforcing the
+	* exclusion. The token is passed explicitly — delegated-mode installations
+	* do not persist one.
+	*/
+	async #registerTransport(installation, mode, botToken) {
+		if (mode === "webhook" && installation.webhookUrl && installation.secretToken) await setWebhook(botToken, {
+			url: installation.webhookUrl,
+			secretToken: installation.secretToken,
+			allowedUpdates: this.#config.allowedUpdates ?? [...DEFAULT_ALLOWED_UPDATES],
+			dropPendingUpdates: true
+		}, this.#apiBaseUrl());
+		else await deleteWebhook(botToken, true, this.#apiBaseUrl());
+	}
+	/** Publish the bot's command list (best-effort — a failure won't block connect). */
+	async #registerCommands(installation, botToken) {
+		if (!installation.commands?.length) return;
+		try {
+			await setMyCommands(botToken, {
+				commands: installation.commands,
+				scope: this.#config.commandScope
+			}, this.#apiBaseUrl());
+		} catch (err) {
+			console.warn(`[Telegram] Failed to register commands for agent "${installation.agentId}":`, err);
+		}
+	}
+	#getOrCreateAdapter(installation) {
+		const existing = this.#adapters.get(installation.id);
+		if (existing) return existing;
+		const adapter = createTelegramAdapter$1({
+			botToken: installation.botToken ?? this.#config.tokenResolver,
+			secretToken: installation.secretToken,
+			userName: installation.username,
+			apiBaseUrl: this.#apiBaseUrl(),
+			mode: installation.webhookUrl ? "webhook" : this.#config.mode ?? "auto",
+			...this.#config.logger !== void 0 ? { logger: this.#config.logger } : {},
+			...this.#config.longPolling !== void 0 ? { longPolling: this.#config.longPolling } : {}
+		});
+		this.#adapters.set(installation.id, adapter);
+		return adapter;
+	}
+	/** Rebuild the adapter and inject AgentChannels for an active installation. */
+	async #activateInstallation(installation) {
+		const agent = this.#resolveAgent(installation.agentId);
+		const adapter = this.#getOrCreateAdapter(installation);
+		if (agent && this.#mastra) await this.#createAgentChannels(agent, adapter).initialize(this.#mastra);
+	}
+	/**
+	* Create AgentChannels for an agent with the Telegram adapter, preserving any
+	* adapters/config the agent author already configured (mirrors `@mastra/slack`).
+	*/
+	#createAgentChannels(agent, adapter) {
+		const existingConfig = agent.getChannels()?.channelConfig;
+		const cfg = this.#config;
+		const entry = {
+			adapter,
+			...resolveTelegramAdapterConfig(cfg),
+			toolDisplay: cfg.toolDisplay ?? "text",
+			...cfg.cors !== void 0 ? { cors: cfg.cors } : {},
+			...cfg.formatError !== void 0 ? { formatError: cfg.formatError } : {}
+		};
+		const channels = new AgentChannels({
+			...existingConfig,
+			adapters: {
+				...existingConfig?.adapters,
+				[PLATFORM]: entry
+			},
+			userName: agent.name,
+			handlers: cfg.handlers ?? existingConfig?.handlers,
+			inlineMedia: cfg.inlineMedia ?? existingConfig?.inlineMedia,
+			inlineLinks: cfg.inlineLinks ?? existingConfig?.inlineLinks,
+			state: cfg.state ?? existingConfig?.state,
+			threadContext: cfg.threadContext ?? existingConfig?.threadContext,
+			chatOptions: cfg.chatOptions ?? existingConfig?.chatOptions,
+			tools: cfg.tools ?? existingConfig?.tools,
+			resolveResourceId: cfg.resolveResourceId ?? existingConfig?.resolveResourceId,
+			waitUntil: cfg.waitUntil ?? existingConfig?.waitUntil,
+			resolveWaitUntil: cfg.resolveWaitUntil ?? existingConfig?.resolveWaitUntil
+		});
+		agent.setChannels(channels);
+		return channels;
+	}
+	async #autoInitialize() {
+		if (!this.#mastra) return;
+		await this.initialize();
+	}
+	#resolveAgent(agentId) {
+		try {
+			return this.#mastra?.getAgentById(agentId);
+		} catch {
+			return;
+		}
+	}
+	async #getStore() {
+		if (this.#store) return this.#store;
+		const encryptionKey = this.#config.encryptionKey ?? process.env.MASTRA_ENCRYPTION_KEY;
+		this.#store = new TelegramInstallStore(await this.#resolveStorage(), encryptionKey);
+		return this.#store;
+	}
+	async #resolveStorage() {
+		if (this.#config.storage) return this.#config.storage;
+		const mastraStore = this.#mastra?.getStorage();
+		if (mastraStore) try {
+			await mastraStore.init();
+			const channels = await mastraStore.getStore("channels");
+			if (channels) return channels;
+		} catch {}
+		return new InMemoryChannelsStorage();
+	}
+	#getBaseUrl() {
+		if (this.#config.baseUrl) return stripTrailingSlash(this.#config.baseUrl);
+		const server = this.#mastra?.getServer();
+		const hasPublicOverride = server?.studioHost != null || server?.studioPort != null || server?.studioProtocol != null;
+		const envUrl = process.env.MASTRA_SERVER_URL?.trim();
+		if (!hasPublicOverride && envUrl) return stripTrailingSlash(envUrl);
+		if (!server) return void 0;
+		const protocol = server.studioProtocol ?? "http";
+		const host = server.studioHost ?? server.host ?? "localhost";
+		const port = server.studioPort ?? server.port ?? (Number(process.env.PORT) || 4111);
+		return !(protocol === "https" && port === 443 || protocol === "http" && port === 80) ? `${protocol}://${host}:${port}` : `${protocol}://${host}`;
+	}
+};
+/** Constant-time comparison of the webhook secret header. */
+function secretMatches(provided, expected) {
+	if (!provided || !expected) return false;
+	const a = Buffer.from(provided);
+	const b = Buffer.from(expected);
+	return a.length === b.length && timingSafeEqual(a, b);
+}
+function stripTrailingSlash(url) {
+	return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+//#endregion
+export { BOTFATHER_DEEP_LINK, DEFAULT_ALLOWED_UPDATES, DEFAULT_COMMANDS, PLATFORM, TELEGRAM_API_BASE_URL, TelegramAdapter, TelegramInstallStore, TelegramProvider, createTelegramAdapter, deleteWebhook, generateSecretToken, getMe, normalizeCommands, resolveTelegramAdapterConfig, setMyCommands, setWebhook, toInstallationInfo };
+
+//# sourceMappingURL=index.js.map