@mastra/telegram 0.0.0-aggregate-trace-20261015182851
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE.md +32 -0
- package/README.md +49 -0
- package/dist/index.cjs +24938 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.ts +482 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +834 -0
- package/dist/index.js.map +1 -0
- package/package.json +67 -0
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,482 @@
|
|
|
1
|
+
import { ChannelAdapterConfig, ChannelConfig, ChannelConnectResult, ChannelHandlers, ChannelInstallationInfo, ChannelPlatformInfo, ChannelProvider, StreamingConfig, WaitUntilFn } from "@mastra/core/channels";
|
|
2
|
+
import { ChannelsStorage } from "@mastra/core/storage";
|
|
3
|
+
import { TelegramAdapter, TelegramAdapter as TelegramAdapter$1, TelegramAdapterConfig, TelegramUser, createTelegramAdapter } from "@chat-adapter/telegram";
|
|
4
|
+
import { Mastra } from "@mastra/core/mastra";
|
|
5
|
+
import { ApiRoute } from "@mastra/core/server";
|
|
6
|
+
//#region src/types.d.ts
|
|
7
|
+
/** Default Telegram Bot API origin. */
|
|
8
|
+
declare const TELEGRAM_API_BASE_URL = "https://api.telegram.org";
|
|
9
|
+
/**
|
|
10
|
+
* Transport for receiving updates.
|
|
11
|
+
* - `webhook` — register a `setWebhook` and receive POSTs (default for hosted/serverless).
|
|
12
|
+
* - `polling` — long-poll `getUpdates` (the provider clears any webhook first).
|
|
13
|
+
* - `auto` — webhook when a `baseUrl` is available, otherwise polling.
|
|
14
|
+
*/
|
|
15
|
+
type TelegramMode = 'auto' | 'webhook' | 'polling';
|
|
16
|
+
/**
|
|
17
|
+
* Default update types requested from Telegram. `message_reaction` must be
|
|
18
|
+
* listed explicitly (Telegram omits it otherwise).
|
|
19
|
+
*/
|
|
20
|
+
declare const DEFAULT_ALLOWED_UPDATES: readonly ['message', 'edited_message', 'channel_post', 'edited_channel_post', 'callback_query', 'message_reaction'];
|
|
21
|
+
/**
|
|
22
|
+
* A Telegram bot command as it goes over the wire (`setMyCommands`).
|
|
23
|
+
* @see https://core.telegram.org/bots/api#botcommand
|
|
24
|
+
*/
|
|
25
|
+
interface BotCommand {
|
|
26
|
+
/** 1-32 chars, lowercase `[a-z0-9_]`, no leading slash. */
|
|
27
|
+
command: string;
|
|
28
|
+
/** 1-256 chars. */
|
|
29
|
+
description: string;
|
|
30
|
+
}
|
|
31
|
+
/** Command input accepted by {@link TelegramProvider} — a bare name or a `{ command, description }`. */
|
|
32
|
+
type TelegramCommand = string | {
|
|
33
|
+
command: string;
|
|
34
|
+
description?: string;
|
|
35
|
+
};
|
|
36
|
+
/**
|
|
37
|
+
* Deep link that opens BotFather so an operator can create a new bot with
|
|
38
|
+
* `/newbot`. Telegram has no OAuth: the resulting BotFather token is pasted
|
|
39
|
+
* back into {@link TelegramProvider.connect} to finish the installation.
|
|
40
|
+
*/
|
|
41
|
+
declare const BOTFATHER_DEEP_LINK = "https://t.me/botfather";
|
|
42
|
+
/**
|
|
43
|
+
* Self-managed credentials: bot tokens are supplied directly (provider default
|
|
44
|
+
* and/or per-`connect()`) and persisted in the install store. Mutually
|
|
45
|
+
* exclusive with {@link TelegramDelegatedCredentialsConfig}.
|
|
46
|
+
*/
|
|
47
|
+
interface TelegramSelfManagedCredentialsConfig {
|
|
48
|
+
/**
|
|
49
|
+
* BotFather bot token to use as the default for {@link TelegramProvider.connect}
|
|
50
|
+
* when the caller does not supply one per-agent. Setting this here matches the
|
|
51
|
+
* shape of {@link SlackProvider} / {@link DiscordProvider} and lets the token
|
|
52
|
+
* live in one place instead of on every `connect()` call site. When both are
|
|
53
|
+
* set, an explicit {@link TelegramConnectOptions.botToken} wins.
|
|
54
|
+
*/
|
|
55
|
+
botToken?: string;
|
|
56
|
+
tokenResolver?: never;
|
|
57
|
+
}
|
|
58
|
+
/**
|
|
59
|
+
* Delegated credentials: an external credential manager (e.g. the Mastra
|
|
60
|
+
* platform) owns the bot token. The provider never persists the token — it
|
|
61
|
+
* asks the resolver for the current token before each Bot API call, so a
|
|
62
|
+
* token re-pasted or rotated upstream takes effect without a restart.
|
|
63
|
+
*
|
|
64
|
+
* The resolver is the single source of truth: a direct `botToken` (config,
|
|
65
|
+
* `configure()`, or per-`connect()`) cannot be combined with it.
|
|
66
|
+
*/
|
|
67
|
+
interface TelegramDelegatedCredentialsConfig {
|
|
68
|
+
/** Resolve the current BotFather bot token on demand. */
|
|
69
|
+
tokenResolver: () => Promise<string>;
|
|
70
|
+
botToken?: never;
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* How the provider obtains bot tokens: either directly (`botToken`,
|
|
74
|
+
* self-managed) or via a `tokenResolver` (externally managed) — never both.
|
|
75
|
+
*/
|
|
76
|
+
type TelegramCredentialsConfig = TelegramSelfManagedCredentialsConfig | TelegramDelegatedCredentialsConfig;
|
|
77
|
+
/**
|
|
78
|
+
* Configuration for {@link TelegramProvider}.
|
|
79
|
+
*
|
|
80
|
+
* Telegram has no OAuth and no org-level parent credential: a BotFather bot
|
|
81
|
+
* token *is* the credential (one token per bot). Multi-tenancy is therefore a
|
|
82
|
+
* store of bot tokens — see {@link TelegramInstallation}. Credentials are
|
|
83
|
+
* either self-managed (`botToken`) or delegated (`tokenResolver`), never both
|
|
84
|
+
* — see {@link TelegramCredentialsConfig}.
|
|
85
|
+
*/
|
|
86
|
+
interface TelegramProviderConfigBase {
|
|
87
|
+
/**
|
|
88
|
+
* Public HTTPS base URL used to register per-bot webhooks (`setWebhook`).
|
|
89
|
+
* May be omitted and auto-detected from the Mastra server config, or set later.
|
|
90
|
+
*/
|
|
91
|
+
baseUrl?: string;
|
|
92
|
+
/**
|
|
93
|
+
* Persistence for bot installations. Defaults to Mastra's channels storage
|
|
94
|
+
* when the provider is attached to a Mastra instance with storage, and falls
|
|
95
|
+
* back to an in-memory store otherwise (dev/test — not persisted across restarts).
|
|
96
|
+
*/
|
|
97
|
+
storage?: ChannelsStorage;
|
|
98
|
+
/**
|
|
99
|
+
* Override the Telegram Bot API origin (e.g. a self-hosted Bot API server or
|
|
100
|
+
* a test mock).
|
|
101
|
+
*
|
|
102
|
+
* @default 'https://api.telegram.org'
|
|
103
|
+
*/
|
|
104
|
+
apiBaseUrl?: string;
|
|
105
|
+
/**
|
|
106
|
+
* Passphrase for encrypting `botToken`/`secretToken` at rest (AES-256-GCM).
|
|
107
|
+
* Defaults to the `MASTRA_ENCRYPTION_KEY` env var. When unset, secrets are
|
|
108
|
+
* stored in plaintext (fine for the in-memory dev store; set a key for any
|
|
109
|
+
* persistent backend).
|
|
110
|
+
*/
|
|
111
|
+
encryptionKey?: string;
|
|
112
|
+
/**
|
|
113
|
+
* Receive transport. Setting a webhook and long-polling are mutually
|
|
114
|
+
* exclusive; the provider manages the switch per bot.
|
|
115
|
+
*
|
|
116
|
+
* @default 'auto'
|
|
117
|
+
*/
|
|
118
|
+
mode?: TelegramMode;
|
|
119
|
+
/**
|
|
120
|
+
* Update types to request in `setWebhook`. Defaults to
|
|
121
|
+
* {@link DEFAULT_ALLOWED_UPDATES}.
|
|
122
|
+
*/
|
|
123
|
+
allowedUpdates?: string[];
|
|
124
|
+
/**
|
|
125
|
+
* Long-polling tuning forwarded to the adapter's `getUpdates` loop when running
|
|
126
|
+
* in polling mode (`timeout`, `limit`, `allowedUpdates`, `retryDelayMs`, …).
|
|
127
|
+
* Ignored in webhook mode.
|
|
128
|
+
*/
|
|
129
|
+
longPolling?: TelegramAdapterConfig['longPolling'];
|
|
130
|
+
/**
|
|
131
|
+
* Keep the serverless invocation alive while the agent stream runs after the
|
|
132
|
+
* webhook returns 200 (Vercel/AWS Lambda). Cloudflare/Netlify resolve this
|
|
133
|
+
* automatically. See `ChannelConfig.waitUntil`.
|
|
134
|
+
*/
|
|
135
|
+
waitUntil?: WaitUntilFn;
|
|
136
|
+
/**
|
|
137
|
+
* Default commands registered via `setMyCommands` for every connected agent
|
|
138
|
+
* (a per-agent list can override via {@link TelegramConnectOptions.commands}).
|
|
139
|
+
* Defaults to the conventional `/start` `/help` `/settings` seed.
|
|
140
|
+
*/
|
|
141
|
+
commands?: TelegramCommand[];
|
|
142
|
+
/**
|
|
143
|
+
* Command scope passed to `setMyCommands` (e.g. `{ type: 'all_private_chats' }`).
|
|
144
|
+
* Omitted → Telegram's default scope.
|
|
145
|
+
* @see https://core.telegram.org/bots/api#botcommandscope
|
|
146
|
+
*/
|
|
147
|
+
commandScope?: Record<string, unknown>;
|
|
148
|
+
/**
|
|
149
|
+
* Stream agent text to Telegram as it generates, via the adapter's
|
|
150
|
+
* post-and-edit (`editMessageText`) loop. Telegram has no native token
|
|
151
|
+
* streaming, so this chunk-edits the reply (4096-char cap handled by the
|
|
152
|
+
* adapter).
|
|
153
|
+
*
|
|
154
|
+
* @default true
|
|
155
|
+
*/
|
|
156
|
+
streaming?: StreamingConfig;
|
|
157
|
+
/**
|
|
158
|
+
* Keep a typing indicator alive during generation (`sendChatAction`, re-sent
|
|
159
|
+
* as it auto-clears). Set `false` to disable.
|
|
160
|
+
*
|
|
161
|
+
* @default true
|
|
162
|
+
*/
|
|
163
|
+
typingStatus?: boolean;
|
|
164
|
+
/**
|
|
165
|
+
* Override built-in event handlers (`onDirectMessage`, `onMention`,
|
|
166
|
+
* `onSubscribedMessage`). Forwarded to `AgentChannels`.
|
|
167
|
+
*/
|
|
168
|
+
handlers?: ChannelHandlers;
|
|
169
|
+
/** Which media types to send inline to the model. See `ChannelConfig.inlineMedia`. */
|
|
170
|
+
inlineMedia?: ChannelConfig['inlineMedia'];
|
|
171
|
+
/** Promote URLs in message text to file parts. See `ChannelConfig.inlineLinks`. */
|
|
172
|
+
inlineLinks?: ChannelConfig['inlineLinks'];
|
|
173
|
+
/** State adapter for deduplication, locking, and subscriptions. See `ChannelConfig.state`. */
|
|
174
|
+
state?: ChannelConfig['state'];
|
|
175
|
+
/** Fetch recent thread messages when the agent joins mid-conversation. See `ChannelConfig.threadContext`. */
|
|
176
|
+
threadContext?: ChannelConfig['threadContext'];
|
|
177
|
+
/** Additional options passed directly to the Chat SDK. See `ChannelConfig.chatOptions`. */
|
|
178
|
+
chatOptions?: ChannelConfig['chatOptions'];
|
|
179
|
+
/** Resolve the memory `resourceId` before a channel thread is created. See `ChannelConfig.resolveResourceId`. */
|
|
180
|
+
resolveResourceId?: ChannelConfig['resolveResourceId'];
|
|
181
|
+
/**
|
|
182
|
+
* Resolve `waitUntil` from the request's Hono `Context` (serverless runtimes
|
|
183
|
+
* whose `waitUntil` derives from the request). See `ChannelConfig.resolveWaitUntil`.
|
|
184
|
+
*/
|
|
185
|
+
resolveWaitUntil?: ChannelConfig['resolveWaitUntil'];
|
|
186
|
+
/** CORS configuration for the generated Telegram webhook route. */
|
|
187
|
+
cors?: ChannelAdapterConfig['cors'];
|
|
188
|
+
/** Override how errors are rendered in Telegram messages. See `ChannelAdapterConfig.formatError`. */
|
|
189
|
+
formatError?: ChannelAdapterConfig['formatError'];
|
|
190
|
+
/**
|
|
191
|
+
* How tool calls are rendered in the reply. Telegram has no Block Kit, so
|
|
192
|
+
* `'cards'`/`'grouped'`/`'timeline'` degrade to plain fallback text — this
|
|
193
|
+
* defaults to `'text'` (unlike Slack's `'grouped'`). See `ChannelAdapterConfig.toolDisplay`.
|
|
194
|
+
*
|
|
195
|
+
* @default 'text'
|
|
196
|
+
*/
|
|
197
|
+
toolDisplay?: ChannelAdapterConfig['toolDisplay'];
|
|
198
|
+
/**
|
|
199
|
+
* Whether to expose channel reaction tools (`add_reaction`/`remove_reaction`)
|
|
200
|
+
* to the agent. Set `false` for models without function calling. See `ChannelConfig.tools`.
|
|
201
|
+
*
|
|
202
|
+
* @default true
|
|
203
|
+
*/
|
|
204
|
+
tools?: ChannelConfig['tools'];
|
|
205
|
+
/** Logger forwarded to the underlying `TelegramAdapter` for internal error reporting. */
|
|
206
|
+
logger?: TelegramAdapterConfig['logger'];
|
|
207
|
+
/** Called after an agent successfully connects a bot and the installation is persisted. */
|
|
208
|
+
onInstall?: (installation: TelegramInstallation) => void | Promise<void>;
|
|
209
|
+
}
|
|
210
|
+
/** See {@link TelegramProviderConfigBase} and {@link TelegramCredentialsConfig}. */
|
|
211
|
+
type TelegramProviderConfig = TelegramProviderConfigBase & TelegramCredentialsConfig;
|
|
212
|
+
/** Options accepted by {@link TelegramProvider.connect}. */
|
|
213
|
+
interface TelegramConnectOptions {
|
|
214
|
+
/**
|
|
215
|
+
* A BotFather bot token. When supplied it is validated via `getMe` and the
|
|
216
|
+
* installation becomes active immediately (`{ type: 'immediate' }`). Omit it
|
|
217
|
+
* to receive a BotFather deep link instead (`{ type: 'deep_link' }`).
|
|
218
|
+
*/
|
|
219
|
+
botToken?: string;
|
|
220
|
+
/** Display name for the bot. Defaults to the bot's `@username` from `getMe`. */
|
|
221
|
+
name?: string;
|
|
222
|
+
/**
|
|
223
|
+
* Commands to register via `setMyCommands` for this agent. Overrides
|
|
224
|
+
* {@link TelegramProviderConfig.commands}. Defaults to the `/start` `/help`
|
|
225
|
+
* `/settings` seed when neither is set.
|
|
226
|
+
*/
|
|
227
|
+
commands?: TelegramCommand[];
|
|
228
|
+
}
|
|
229
|
+
/**
|
|
230
|
+
* A registered Telegram bot bound to a single agent (one bot = one agent).
|
|
231
|
+
* Persisted through {@link TelegramInstallStore}.
|
|
232
|
+
*/
|
|
233
|
+
interface TelegramInstallation {
|
|
234
|
+
/** Stable installation id. */
|
|
235
|
+
id: string;
|
|
236
|
+
/** The agent this bot is bound to. */
|
|
237
|
+
agentId: string;
|
|
238
|
+
/**
|
|
239
|
+
* Opaque id embedded in the webhook route path (`/telegram/events/:webhookId`).
|
|
240
|
+
* Never the secret — the secret travels only in the request header.
|
|
241
|
+
*/
|
|
242
|
+
webhookId: string;
|
|
243
|
+
/** Whether a bot token has been ingested and validated. */
|
|
244
|
+
status: 'active' | 'pending';
|
|
245
|
+
/**
|
|
246
|
+
* BotFather bot token — the full credential. Present once ingested in
|
|
247
|
+
* self-managed mode. Absent in delegated mode (`tokenResolver`), where the
|
|
248
|
+
* external credential manager is the single source of truth and the token
|
|
249
|
+
* is never persisted locally.
|
|
250
|
+
*/
|
|
251
|
+
botToken?: string;
|
|
252
|
+
/**
|
|
253
|
+
* Telegram user id of the bot (from `getMe`). Used to detect two agents
|
|
254
|
+
* connecting the same bot when the token itself is not stored (delegated
|
|
255
|
+
* mode).
|
|
256
|
+
*/
|
|
257
|
+
botUserId?: number;
|
|
258
|
+
/**
|
|
259
|
+
* Per-bot webhook shared secret, echoed by Telegram as the
|
|
260
|
+
* `X-Telegram-Bot-Api-Secret-Token` header on every inbound POST.
|
|
261
|
+
*/
|
|
262
|
+
secretToken?: string;
|
|
263
|
+
/** The bot's `@username`, resolved from `getMe`. */
|
|
264
|
+
username?: string;
|
|
265
|
+
/** The webhook URL registered with `setWebhook` (M1 — issue `mastra-telegram-i2g.3`). */
|
|
266
|
+
webhookUrl?: string;
|
|
267
|
+
/** Normalized commands registered via `setMyCommands`. */
|
|
268
|
+
commands?: BotCommand[];
|
|
269
|
+
/** When the installation was created. */
|
|
270
|
+
installedAt: Date;
|
|
271
|
+
}
|
|
272
|
+
//#endregion
|
|
273
|
+
//#region src/telegram-provider.d.ts
|
|
274
|
+
/**
|
|
275
|
+
* Resolve the per-adapter streaming/typing config the provider applies to the
|
|
276
|
+
* Telegram entry in `AgentChannels.adapters`. This is the wrapper's stream
|
|
277
|
+
* binding: enabling `streaming` runs the adapter's post-and-edit
|
|
278
|
+
* (`editMessageText`) chunking loop, and `typingStatus` keeps a `sendChatAction`
|
|
279
|
+
* indicator alive — both default on.
|
|
280
|
+
*/
|
|
281
|
+
declare function resolveTelegramAdapterConfig(config: Pick<TelegramProviderConfig, 'streaming' | 'typingStatus'>): {
|
|
282
|
+
streaming: StreamingConfig;
|
|
283
|
+
typingStatus: boolean;
|
|
284
|
+
};
|
|
285
|
+
/**
|
|
286
|
+
* Telegram channel provider for Mastra — a {@link ChannelProvider} over
|
|
287
|
+
* `@chat-adapter/telegram`. The adapter handles the Bot API transport (webhook
|
|
288
|
+
* parse, send/edit, typing, rich messages); this provider adds the
|
|
289
|
+
* install/lifecycle layer.
|
|
290
|
+
*
|
|
291
|
+
* Implemented:
|
|
292
|
+
* - **`mastra-telegram-i2g.2`** — multi-token install store (one bot = one
|
|
293
|
+
* agent), `connect()`/`disconnect()`, `getMe` token ingestion.
|
|
294
|
+
* - **`mastra-telegram-i2g.3`** — per-bot `setWebhook` lifecycle,
|
|
295
|
+
* `X-Telegram-Bot-Api-Secret-Token` verification, webhook⇄polling exclusion,
|
|
296
|
+
* and a mounted POST route that delegates to `AgentChannels.handleWebhookEvent`.
|
|
297
|
+
*
|
|
298
|
+
* Later: `setMyCommands` + streaming (`mastra-telegram-i2g.4`).
|
|
299
|
+
*
|
|
300
|
+
* @example
|
|
301
|
+
* ```ts
|
|
302
|
+
* const telegram = new TelegramProvider({ baseUrl: 'https://my-app.example.com' })
|
|
303
|
+
* const mastra = new Mastra({ agents: { myAgent }, channels: { telegram } })
|
|
304
|
+
* await telegram.connect('my-agent', { botToken: '123456:ABC-...' }) // → { type: 'immediate' }
|
|
305
|
+
* ```
|
|
306
|
+
*/
|
|
307
|
+
declare class TelegramProvider implements ChannelProvider {
|
|
308
|
+
#private;
|
|
309
|
+
readonly id = "telegram";
|
|
310
|
+
constructor(config?: TelegramProviderConfig);
|
|
311
|
+
/**
|
|
312
|
+
* Called by Mastra when this channel is registered.
|
|
313
|
+
* @internal
|
|
314
|
+
*/
|
|
315
|
+
__attach(mastra: Mastra): void;
|
|
316
|
+
/**
|
|
317
|
+
* Per-bot webhook route. A single POST endpoint keyed by an opaque
|
|
318
|
+
* `webhookId`; the per-bot secret is verified from the request header, never
|
|
319
|
+
* carried in the URL. Auto-initializes on first hit (mirrors `@mastra/slack`).
|
|
320
|
+
*/
|
|
321
|
+
getRoutes(): ApiRoute[];
|
|
322
|
+
/** Discovery metadata for the editor UI. */
|
|
323
|
+
getInfo(): ChannelPlatformInfo;
|
|
324
|
+
/**
|
|
325
|
+
* Restore installations from storage: rebuild an adapter per active bot and
|
|
326
|
+
* inject `AgentChannels` so the agent can receive events immediately.
|
|
327
|
+
* Idempotent. Does not re-register webhooks (they persist server-side across
|
|
328
|
+
* restarts); reconnect an agent if its `baseUrl` changed.
|
|
329
|
+
*/
|
|
330
|
+
initialize(): Promise<void>;
|
|
331
|
+
/**
|
|
332
|
+
* Update runtime provider settings. Pass `botToken` to change the default
|
|
333
|
+
* bot token new {@link connect} calls fall back to when none is supplied
|
|
334
|
+
* per-agent (matching {@link SlackProvider.configure}'s rotation pattern);
|
|
335
|
+
* pass `apiBaseUrl`/`baseUrl` to point the adapter at a different host.
|
|
336
|
+
* `null` clears the default `botToken` only — per-bot installs are managed
|
|
337
|
+
* via {@link connect}/{@link disconnect}.
|
|
338
|
+
*/
|
|
339
|
+
configure(credentials: {
|
|
340
|
+
apiBaseUrl?: string;
|
|
341
|
+
baseUrl?: string;
|
|
342
|
+
botToken?: string;
|
|
343
|
+
} | null): Promise<void>;
|
|
344
|
+
/**
|
|
345
|
+
* Connect an agent to a Telegram bot.
|
|
346
|
+
*
|
|
347
|
+
* - With `options.botToken` or a provider default token: validate via `getMe`,
|
|
348
|
+
* mint a per-bot webhook secret, persist the installation, register the
|
|
349
|
+
* transport (webhook or polling), and return `{ type: 'immediate' }`.
|
|
350
|
+
* - Without either token: persist a pending installation and return
|
|
351
|
+
* `{ type: 'deep_link' }` pointing at BotFather.
|
|
352
|
+
*/
|
|
353
|
+
connect(agentId: string, options?: TelegramConnectOptions): Promise<ChannelConnectResult>;
|
|
354
|
+
/** Disconnect an agent from Telegram, removing its webhook and installation. */
|
|
355
|
+
disconnect(agentId: string): Promise<void>;
|
|
356
|
+
/** List installations (public info only — no tokens or secrets). */
|
|
357
|
+
listInstallations(): Promise<ChannelInstallationInfo[]>;
|
|
358
|
+
/**
|
|
359
|
+
* Get the full installation for an agent (includes the bot token / secret).
|
|
360
|
+
* Returns `null` if the agent has no Telegram installation. Mirrors
|
|
361
|
+
* `SlackProvider.getInstallation`.
|
|
362
|
+
*/
|
|
363
|
+
getInstallation(agentId: string): Promise<TelegramInstallation | null>;
|
|
364
|
+
/**
|
|
365
|
+
* Whether the provider is ready to connect agents: either a bot is already
|
|
366
|
+
* registered (#configured) or a credential source exists — a default
|
|
367
|
+
* `botToken`, or a `tokenResolver` in delegated mode (@mastra/connect).
|
|
368
|
+
* Without the credential-source half, a freshly attached platform credential
|
|
369
|
+
* reports unconfigured and UIs hide the connect action entirely. Mirrors
|
|
370
|
+
* `DiscordProvider.isConfigured` / `SlackProvider.isConfigured`.
|
|
371
|
+
*/
|
|
372
|
+
isConfigured(): boolean;
|
|
373
|
+
/**
|
|
374
|
+
* Get the live `TelegramAdapter` for an installation id, if one is active.
|
|
375
|
+
* Used for message formatting/posting. Mirrors `SlackProvider.getAdapter`.
|
|
376
|
+
*/
|
|
377
|
+
getAdapter(installationId: string): TelegramAdapter$1 | undefined;
|
|
378
|
+
}
|
|
379
|
+
//#endregion
|
|
380
|
+
//#region src/install-store.d.ts
|
|
381
|
+
/** Platform identifier used for every stored record and route. */
|
|
382
|
+
declare const PLATFORM = "telegram";
|
|
383
|
+
/**
|
|
384
|
+
* Persistence for Telegram bot installations, layered over the platform-agnostic
|
|
385
|
+
* `ChannelsStorage` (the same store `@mastra/slack` uses). Installations are
|
|
386
|
+
* keyed by agent — one bot = one agent — and the per-bot secret fields live in
|
|
387
|
+
* the record's `data` blob. When an `encryptionKey` is supplied, `botToken` and
|
|
388
|
+
* `secretToken` are AES-256-GCM encrypted at rest.
|
|
389
|
+
*/
|
|
390
|
+
declare class TelegramInstallStore {
|
|
391
|
+
#private;
|
|
392
|
+
private readonly storage;
|
|
393
|
+
private readonly encryptionKey?;
|
|
394
|
+
constructor(storage: ChannelsStorage, encryptionKey?: string | undefined);
|
|
395
|
+
/** The active or pending installation for an agent, if any. */
|
|
396
|
+
getByAgent(agentId: string): Promise<TelegramInstallation | null>;
|
|
397
|
+
/** Look up an installation by the routing id in its webhook path (M1 dispatch). */
|
|
398
|
+
getByWebhookId(webhookId: string): Promise<TelegramInstallation | null>;
|
|
399
|
+
/** Insert or replace an installation. */
|
|
400
|
+
save(installation: TelegramInstallation): Promise<void>;
|
|
401
|
+
/** All Telegram installations (active and pending). */
|
|
402
|
+
list(): Promise<TelegramInstallation[]>;
|
|
403
|
+
/** Remove an agent's installation, if present. */
|
|
404
|
+
deleteByAgent(agentId: string): Promise<void>;
|
|
405
|
+
}
|
|
406
|
+
/** Project an installation to its public, secret-free info for the editor UI. */
|
|
407
|
+
declare function toInstallationInfo(install: TelegramInstallation): ChannelInstallationInfo;
|
|
408
|
+
//#endregion
|
|
409
|
+
//#region src/telegram-client.d.ts
|
|
410
|
+
/**
|
|
411
|
+
* Validate a bot token via `getMe` and resolve the bot's identity. Throws if
|
|
412
|
+
* the token is rejected or the returned user is not a bot.
|
|
413
|
+
*
|
|
414
|
+
* @see https://core.telegram.org/bots/api#getme
|
|
415
|
+
*/
|
|
416
|
+
declare function getMe(botToken: string, apiBaseUrl?: string): Promise<TelegramUser>;
|
|
417
|
+
/** Options for {@link setWebhook}. */
|
|
418
|
+
interface SetWebhookOptions {
|
|
419
|
+
/** Public HTTPS URL Telegram will POST updates to. */
|
|
420
|
+
url: string;
|
|
421
|
+
/** Shared secret echoed back as `X-Telegram-Bot-Api-Secret-Token` on every POST. */
|
|
422
|
+
secretToken: string;
|
|
423
|
+
/** Update types to receive. Note: `message_reaction` must be listed explicitly. */
|
|
424
|
+
allowedUpdates?: string[];
|
|
425
|
+
/** Drop the backlog of updates queued while the bot was offline. */
|
|
426
|
+
dropPendingUpdates?: boolean;
|
|
427
|
+
}
|
|
428
|
+
/**
|
|
429
|
+
* Register a per-bot webhook. Setting a webhook disables `getUpdates`
|
|
430
|
+
* (long-polling) for that bot — the two transports are mutually exclusive.
|
|
431
|
+
*
|
|
432
|
+
* @see https://core.telegram.org/bots/api#setwebhook
|
|
433
|
+
*/
|
|
434
|
+
declare function setWebhook(botToken: string, options: SetWebhookOptions, apiBaseUrl?: string): Promise<void>;
|
|
435
|
+
/**
|
|
436
|
+
* Remove a bot's webhook. Required before switching a bot to long-polling
|
|
437
|
+
* (`getUpdates` fails while a webhook is set).
|
|
438
|
+
*
|
|
439
|
+
* @see https://core.telegram.org/bots/api#deletewebhook
|
|
440
|
+
*/
|
|
441
|
+
declare function deleteWebhook(botToken: string, dropPendingUpdates?: boolean, apiBaseUrl?: string): Promise<void>;
|
|
442
|
+
/** Options for {@link setMyCommands}. */
|
|
443
|
+
interface SetMyCommandsOptions {
|
|
444
|
+
/** The command list to publish (replaces the existing set for the scope). */
|
|
445
|
+
commands: BotCommand[];
|
|
446
|
+
/** Command scope (e.g. `{ type: 'all_private_chats' }`). Omit for the default scope. */
|
|
447
|
+
scope?: Record<string, unknown>;
|
|
448
|
+
/** Two-letter language code for a localized command set. */
|
|
449
|
+
languageCode?: string;
|
|
450
|
+
}
|
|
451
|
+
/**
|
|
452
|
+
* Publish the bot's command list for a scope.
|
|
453
|
+
*
|
|
454
|
+
* @see https://core.telegram.org/bots/api#setmycommands
|
|
455
|
+
*/
|
|
456
|
+
declare function setMyCommands(botToken: string, options: SetMyCommandsOptions, apiBaseUrl?: string): Promise<void>;
|
|
457
|
+
/**
|
|
458
|
+
* Generate a webhook secret token within Telegram's `setWebhook` constraint:
|
|
459
|
+
* 1-256 chars from `[A-Za-z0-9_-]`. base64url of 32 random bytes yields 43
|
|
460
|
+
* such chars.
|
|
461
|
+
*
|
|
462
|
+
* @see https://core.telegram.org/bots/api#setwebhook
|
|
463
|
+
*/
|
|
464
|
+
declare function generateSecretToken(): string;
|
|
465
|
+
//#endregion
|
|
466
|
+
//#region src/commands.d.ts
|
|
467
|
+
/**
|
|
468
|
+
* Conventional command seed registered when a connect provides none.
|
|
469
|
+
* @see https://core.telegram.org/bots/features#commands
|
|
470
|
+
*/
|
|
471
|
+
declare const DEFAULT_COMMANDS: readonly TelegramCommand[];
|
|
472
|
+
/**
|
|
473
|
+
* Map user-supplied commands (agent capabilities) to Telegram `BotCommand[]`,
|
|
474
|
+
* enforcing the Bot API constraints: `command` is lowercased, stripped of a
|
|
475
|
+
* leading slash, reduced to `[a-z0-9_]`, and clamped to 1-32 chars;
|
|
476
|
+
* `description` defaults to `Run /<command>` and is clamped to 256 chars.
|
|
477
|
+
* Empty or duplicate command names are dropped.
|
|
478
|
+
*/
|
|
479
|
+
declare function normalizeCommands(raw: readonly TelegramCommand[] | undefined): BotCommand[];
|
|
480
|
+
//#endregion
|
|
481
|
+
export { BOTFATHER_DEEP_LINK, type BotCommand, DEFAULT_ALLOWED_UPDATES, DEFAULT_COMMANDS, PLATFORM, type SetMyCommandsOptions, type SetWebhookOptions, TELEGRAM_API_BASE_URL, TelegramAdapter, type TelegramCommand, type TelegramConnectOptions, TelegramInstallStore, type TelegramInstallation, type TelegramMode, TelegramProvider, type TelegramProviderConfig, createTelegramAdapter, deleteWebhook, generateSecretToken, getMe, normalizeCommands, resolveTelegramAdapterConfig, setMyCommands, setWebhook, toInstallationInfo };
|
|
482
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +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;;;;;;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;;EAiHxE,WAAW,kBAAkB;;EAkD7B,qBAAqB,QAAQ;;;;;;EAW7B,gBAAgB,kBAAkB,QAAQ;;;;;;;;;EAahD;;;;;EAQA,WAAW,yBAAyB;;;;;cCpfzB;;;;;;;;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;;;;;;;;;iBC1D7C,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;;;;;;;cC1JH,2BAA2B;;;;;;;;iBAaxB,kBAAkB,cAAc,gCAAgC"}
|