@mastra/telegram 0.1.3 → 0.2.0

package/dist/index.d.ts

@@ -40,22 +40,50 @@ type TelegramCommand = string | {
  */
 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}.
+ * Self-managed credentials: bot tokens are supplied directly (provider default
+ * and/or per-`connect()`) and persisted in the install store. Mutually
+ * exclusive with {@link TelegramDelegatedCredentialsConfig}.
  */
-interface TelegramProviderConfig {
+interface TelegramSelfManagedCredentialsConfig {
   /**
    * BotFather bot token to use as the default for {@link TelegramProvider.connect}
    * when the caller does not supply one per-agent. Setting this here matches the
    * shape of {@link SlackProvider} / {@link DiscordProvider} and lets the token
-   * live on a Mastra Connect credential (or another vault) instead of on every
-   * `connect()` call site. When both are set, an explicit
-   * {@link TelegramConnectOptions.botToken} wins.
+   * live in one place instead of on every `connect()` call site. When both are
+   * set, an explicit {@link TelegramConnectOptions.botToken} wins.
    */
   botToken?: string;
+  tokenResolver?: never;
+}
+/**
+ * Delegated credentials: an external credential manager (e.g. the Mastra
+ * platform) owns the bot token. The provider never persists the token — it
+ * asks the resolver for the current token before each Bot API call, so a
+ * token re-pasted or rotated upstream takes effect without a restart.
+ *
+ * The resolver is the single source of truth: a direct `botToken` (config,
+ * `configure()`, or per-`connect()`) cannot be combined with it.
+ */
+interface TelegramDelegatedCredentialsConfig {
+  /** Resolve the current BotFather bot token on demand. */
+  tokenResolver: () => Promise<string>;
+  botToken?: never;
+}
+/**
+ * How the provider obtains bot tokens: either directly (`botToken`,
+ * self-managed) or via a `tokenResolver` (externally managed) — never both.
+ */
+type TelegramCredentialsConfig = TelegramSelfManagedCredentialsConfig | TelegramDelegatedCredentialsConfig;
+/**
+ * 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}. Credentials are
+ * either self-managed (`botToken`) or delegated (`tokenResolver`), never both
+ * — see {@link TelegramCredentialsConfig}.
+ */
+interface TelegramProviderConfigBase {
   /**
    * 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.
@@ -179,6 +207,8 @@ interface TelegramProviderConfig {
   /** Called after an agent successfully connects a bot and the installation is persisted. */
   onInstall?: (installation: TelegramInstallation) => void | Promise<void>;
 }
+/** See {@link TelegramProviderConfigBase} and {@link TelegramCredentialsConfig}. */
+type TelegramProviderConfig = TelegramProviderConfigBase & TelegramCredentialsConfig;
 /** Options accepted by {@link TelegramProvider.connect}. */
 interface TelegramConnectOptions {
   /**
@@ -212,8 +242,19 @@ interface TelegramInstallation {
   webhookId: string;
   /** Whether a bot token has been ingested and validated. */
   status: 'active' | 'pending';
-  /** BotFather bot token — the full credential. Present once ingested. */
+  /**
+   * BotFather bot token — the full credential. Present once ingested in
+   * self-managed mode. Absent in delegated mode (`tokenResolver`), where the
+   * external credential manager is the single source of truth and the token
+   * is never persisted locally.
+   */
   botToken?: string;
+  /**
+   * Telegram user id of the bot (from `getMe`). Used to detect two agents
+   * connecting the same bot when the token itself is not stored (delegated
+   * mode).
+   */
+  botUserId?: number;
   /**
    * Per-bot webhook shared secret, echoed by Telegram as the
    * `X-Telegram-Bot-Api-Secret-Token` header on every inbound POST.

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/telegram-provider.ts","../src/install-store.ts","../src/telegram-client.ts","../src/commands.ts"],"mappings":";;;;;;;cAWa;;;;;;;KAQD;;;;;cAMC;;;;;UAaI;;EAEf;;EAEA;;;KAIU;EAA6B;EAAiB;;;;;;;cAO7C;;;;;;;;UASI;;;;;;;;;EASf;;;;;EAKA;;;;;;EAMA,UAAU;;;;;;;EAOV;;;;;;;EAOA;;;;;;;EAOA,OAAO;;;;;EAKP;;;;;;EAMA,cAAc;;;;;;EAMd,YAAY;;;;;;EAMZ,WAAW;;;;;;EAMX,eAAe;;;;;;;;;EASf,YAAY;;;;;;;EAOZ;;;;;EAYA,WAAW;;EAEX,cAAc;;EAEd,cAAc;;EAEd,QAAQ;;EAER,gBAAgB;;EAEhB,cAAc;;EAEd,oBAAoB;;;;;EAKpB,mBAAmB;;EAEnB,OAAO;;EAEP,cAAc;;;;;;;;EAQd,cAAc;;;;;;;EAOd,QAAQ;;EAER,SAAS;;EAET,aAAa,cAAc,gCAAgC;;;UAI5C;;;;;;EAMf;;EAEA;;;;;;EAMA,WAAW;;;;;;UAOI;;EAEf;;EAEA;;;;;EAKA;;EAEA;;EAEA;;;;;EAKA;;EAEA;;EAEA;;EAEA,WAAW;;EAEX,aAAa;;;;;;;;;;;iBC7NC,6BAA6B,QAAQ,KAAK;EACxD,WAAW;EACX;;;;;;;;;;;;;;;;;;;;;;;;cAiCW,4BAA4B;;WAC9B;EAYT,YAAY,SAAQ;;;;;EAQpB,SAAS,QAAQ;;;;;;EAejB,aAAa;;EAoBb,WAAW;;;;;;;EA4BL,cAAc;;;;;;;;;EAgCd,UAAU;IAAe;IAAqB;IAAkB;aAA6B;;;;;;;;;;EAkC7F,QAAQ,iBAAiB,UAAS,yBAA8B,QAAQ;;EAgFxE,WAAW,kBAAkB;;EA4B7B,qBAAqB,QAAQ;;;;;;EAW7B,gBAAgB,kBAAkB,QAAQ;;;;;;EAUhD;;;;;EAQA,WAAW,yBAAyB;;;;;cC1VzB;;;;;;;;cAkBA;;mBAEQ;mBACA;EAFnB,YACmB,SAAS,iBACT;;EAIb,WAAW,kBAAkB,QAAQ;;EAMrC,eAAe,oBAAoB,QAAQ;;EAM3C,KAAK,cAAc,uBAAuB;;EAK1C,QAAQ,QAAQ;;EAMhB,cAAc,kBAAkB;;;iBA4DxB,mBAAmB,SAAS,uBAAuB;;;;;;;;;iBCtD7C,MAAM,kBAAkB,sBAA6C,QAAQ;;UAqBlF;;EAEf;;EAEA;;EAEA;;EAEA;;;;;;;;iBASoB,WACpB,kBACA,SAAS,mBACT,sBACC;;;;;;;iBAemB,cACpB,kBACA,8BACA,sBACC;;UAOc;;EAEf,UAAU;;EAEV,QAAQ;;EAER;;;;;;;iBAQoB,cACpB,kBACA,SAAS,sBACT,sBACC;;;;;;;;iBAea;;;;;;;cC3JH,2BAA2B;;;;;;;;iBAaxB,kBAAkB,cAAc,gCAAgC"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/telegram-provider.ts","../src/install-store.ts","../src/telegram-client.ts","../src/commands.ts"],"mappings":";;;;;;;cAWa;;;;;;;KAQD;;;;;cAMC;;;;;UAaI;;EAEf;;EAEA;;;KAIU;EAA6B;EAAiB;;;;;;;cAO7C;;;;;;UAOI;;;;;;;;EAQf;EAEA;;;;;;;;;;;UAYe;;EAEf,qBAAqB;EACrB;;;;;;KAOU,4BAA4B,uCAAuC;;;;;;;;;;UAW9D;;;;;EAKf;;;;;;EAMA,UAAU;;;;;;;EAOV;;;;;;;EAOA;;;;;;;EAOA,OAAO;;;;;EAKP;;;;;;EAMA,cAAc;;;;;;EAMd,YAAY;;;;;;EAMZ,WAAW;;;;;;EAMX,eAAe;;;;;;;;;EASf,YAAY;;;;;;;EAOZ;;;;;EAYA,WAAW;;EAEX,cAAc;;EAEd,cAAc;;EAEd,QAAQ;;EAER,gBAAgB;;EAEhB,cAAc;;EAEd,oBAAoB;;;;;EAKpB,mBAAmB;;EAEnB,OAAO;;EAEP,cAAc;;;;;;;;EAQd,cAAc;;;;;;;EAOd,QAAQ;;EAER,SAAS;;EAET,aAAa,cAAc,gCAAgC;;;KAIjD,yBAAyB,6BAA6B;;UAGjD;;;;;;EAMf;;EAEA;;;;;;EAMA,WAAW;;;;;;UAOI;;EAEf;;EAEA;;;;;EAKA;;EAEA;;;;;;;EAOA;;;;;;EAMA;;;;;EAKA;;EAEA;;EAEA;;EAEA,WAAW;;EAEX,aAAa;;;;;;;;;;;iBC3QC,6BAA6B,QAAQ,KAAK;EACxD,WAAW;EACX;;;;;;;;;;;;;;;;;;;;;;;;cAiCW,4BAA4B;;WAC9B;EAYT,YAAY,SAAQ;;;;;EAkBpB,SAAS,QAAQ;;;;;;EAejB,aAAa;;EAoBb,WAAW;;;;;;;EA4BL,cAAc;;;;;;;;;EA8Gd,UAAU;IAAe;IAAqB;IAAkB;aAA6B;;;;;;;;;;EA0C7F,QAAQ,iBAAiB,UAAS,yBAA8B,QAAQ;;EAqHxE,WAAW,kBAAkB;;EAkD7B,qBAAqB,QAAQ;;;;;;EAW7B,gBAAgB,kBAAkB,QAAQ;;;;;;EAUhD;;;;;EAQA,WAAW,yBAAyB;;;;;cCrfzB;;;;;;;;cAmBA;;mBAEQ;mBACA;EAFnB,YACmB,SAAS,iBACT;;EAIb,WAAW,kBAAkB,QAAQ;;EAMrC,eAAe,oBAAoB,QAAQ;;EAM3C,KAAK,cAAc,uBAAuB;;EAK1C,QAAQ,QAAQ;;EAMhB,cAAc,kBAAkB;;;iBA8DxB,mBAAmB,SAAS,uBAAuB;;;;;;;;;iBCzD7C,MAAM,kBAAkB,sBAA6C,QAAQ;;UAqBlF;;EAEf;;EAEA;;EAEA;;EAEA;;;;;;;;iBASoB,WACpB,kBACA,SAAS,mBACT,sBACC;;;;;;;iBAemB,cACpB,kBACA,8BACA,sBACC;;UAOc;;EAEf,UAAU;;EAEV,QAAQ;;EAER;;;;;;;iBAQoB,cACpB,kBACA,SAAS,sBACT,sBACC;;;;;;;;iBAea;;;;;;;cC3JH,2BAA2B;;;;;;;;iBAaxB,kBAAkB,cAAc,gCAAgC"}

package/dist/index.js

@@ -252,6 +252,7 @@ var TelegramInstallStore = class {
 	#toRecord(install) {
 		const data = {
 			botToken: this.#enc(install.botToken),
+			botUserId: install.botUserId,
 			secretToken: this.#enc(install.secretToken),
 			username: install.username,
 			webhookUrl: install.webhookUrl,
@@ -276,6 +277,7 @@ var TelegramInstallStore = class {
 			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,
@@ -346,6 +348,7 @@ var TelegramProvider = class {
 	#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;
 	}
 	/**
@@ -420,15 +423,73 @@ var TelegramProvider = class {
 		}
 	}
 	async #doInitialize() {
-		const active = (await (await this.#getStore()).list()).filter((i) => i.status === "active");
+		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 {
-			await this.#activateInstallation(installation);
+			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);
@@ -437,6 +498,7 @@ var TelegramProvider = class {
 	* 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,
@@ -473,7 +535,13 @@ var TelegramProvider = class {
 		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.`);
-		const botToken = options.botToken ?? this.#config.botToken;
+		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 ?? randomUUID();
 			await store.save({
@@ -497,11 +565,11 @@ var TelegramProvider = class {
 			this.#connectingBotTokens.add(botToken);
 		}
 		try {
+			const me = await getMe(botToken, this.#apiBaseUrl());
 			if (mode === "webhook") {
-				const duplicate = (await store.list()).find((i) => i.status === "active" && i.botToken === botToken);
+				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 me = await getMe(botToken, this.#apiBaseUrl());
 			const installationId = existing?.id ?? randomUUID();
 			const webhookId = existing?.webhookId ?? randomUUID();
 			const webhookUrl = mode === "webhook" ? `${baseUrl}/${PLATFORM}/events/${webhookId}` : void 0;
@@ -511,15 +579,16 @@ var TelegramProvider = class {
 				agentId,
 				webhookId,
 				status: "active",
-				botToken,
+				...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);
-			await this.#registerCommands(installation);
+			await this.#registerTransport(installation, mode, botToken);
+			await this.#registerCommands(installation, botToken);
 			await store.save(installation);
 			await this.#activateInstallation(installation);
 			this.#configured = true;
@@ -543,8 +612,18 @@ var TelegramProvider = class {
 		} catch (err) {
 			console.warn(`[Telegram] Failed to stop polling for agent "${agentId}":`, err);
 		}
-		if (existing.botToken) try {
-			await deleteWebhook(existing.botToken, true, this.#apiBaseUrl());
+		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);
 		}
@@ -618,22 +697,25 @@ var TelegramProvider = class {
 		if (mode === "auto") return baseUrl ? "webhook" : "polling";
 		return mode;
 	}
-	/** Register (or clear) the receive transport for a bot, enforcing the exclusion. */
-	async #registerTransport(installation, mode) {
-		if (!installation.botToken) return;
-		if (mode === "webhook" && installation.webhookUrl && installation.secretToken) await setWebhook(installation.botToken, {
+	/**
+	* 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(installation.botToken, 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) {
-		if (!installation.botToken || !installation.commands?.length) return;
+	async #registerCommands(installation, botToken) {
+		if (!installation.commands?.length) return;
 		try {
-			await setMyCommands(installation.botToken, {
+			await setMyCommands(botToken, {
 				commands: installation.commands,
 				scope: this.#config.commandScope
 			}, this.#apiBaseUrl());
@@ -645,7 +727,7 @@ var TelegramProvider = class {
 		const existing = this.#adapters.get(installation.id);
 		if (existing) return existing;
 		const adapter = createTelegramAdapter$1({
-			botToken: installation.botToken,
+			botToken: installation.botToken ?? this.#config.tokenResolver,
 			secretToken: installation.secretToken,
 			userName: installation.username,
 			apiBaseUrl: this.#apiBaseUrl(),