eve

import type { TelegramInstrumentationMetadata } from "#public/channels/telegram/index.js"; import type { SessionAuthContext } from "#channel/types.js"; import type { SessionContext } from "#public/definitions/callback-context.js"; import type { ChannelSessionOps } from "#public/definitions/defineChannel.js"; import type { HandleMessageStreamEvent } from "#protocol/message.js"; import { type TelegramApiOptions, type TelegramApiResponse, type TelegramCredentials, type TelegramMessageBody, type TelegramMessageResult } from "#public/channels/telegram/api.js"; import { type TelegramHitlState } from "#public/channels/telegram/hitl.js"; import { type TelegramCallbackQuery, type TelegramChatType, type TelegramMessage } from "#public/channels/telegram/inbound.js"; import { type UploadPolicyInput } from "#public/channels/upload-policy.js"; import { type TelegramWebhookSecretToken, type TelegramWebhookVerifier } from "#public/channels/telegram/verify.js"; import { type Channel } from "#public/definitions/defineChannel.js"; import { type JsonObject } from "#shared/json.js"; type EventData<T extends HandleMessageStreamEvent["type"]> = Extract<HandleMessageStreamEvent, { type: T; }> extends { data: infer D; } ? D : undefined; /** Minimal Telegram context (only `telegram`, no `state` or session ops), passed to `onMessage` and `onCallbackQuery` hooks before a session exists. Event handlers receive the richer {@link TelegramEventContext}. */ export interface TelegramContext { readonly telegram: TelegramHandle; } /** Channel-owned Telegram context returned by `context()`. */ export interface TelegramChannelContext extends TelegramContext { state: TelegramChannelState; } /** Event-handler Telegram context, including session operations. */ export interface TelegramEventContext extends TelegramChannelContext, ChannelSessionOps { } /** JSON-serializable Telegram channel state. */ export interface TelegramChannelState extends TelegramHitlState { /** Telegram bot username used for group mention detection, when configured. */ botUsername?: string | null; /** Telegram chat id. */ chatId: string | null; /** Telegram chat type, when known from an inbound update. */ chatType: TelegramChatType | null; /** Group/supergroup conversation anchor message id. */ conversationId: string | null; /** Forum topic id, when known. */ messageThreadId: number | null; /** Telegram user id that triggered the current session/turn. */ triggeringUserId?: string | null; } /** Telegram channel credentials. `webhookVerifier` is a custom inbound webhook verifier for forwarded webhooks. */ export interface TelegramChannelCredentials extends TelegramCredentials { /** Webhook secret token configured via setWebhook. Falls back to `TELEGRAM_WEBHOOK_SECRET_TOKEN` when neither this nor `webhookVerifier` is set. */ readonly webhookSecretToken?: TelegramWebhookSecretToken; readonly webhookVerifier?: TelegramWebhookVerifier; } /** Target for `receive(telegram, { target })` proactive sessions. `chatId` is required. `conversationId` resumes an existing thread; `initialMessage` posts a seed message and starts a new thread from it. The two are mutually exclusive: supplying both throws. */ export interface TelegramReceiveTarget { readonly chatId: number | string; readonly conversationId?: number | string; readonly initialMessage?: string | TelegramMessageBody; readonly messageThreadId?: number; } /** Result of an inbound Telegram message hook. Return `null` to drop the update. */ export type TelegramInboundResult = { readonly auth: SessionAuthContext | null; readonly context?: readonly string[]; } | null; /** Sync or async {@link TelegramInboundResult}. */ export type TelegramInboundResultOrPromise = TelegramInboundResult | Promise<TelegramInboundResult>; type TelegramEventHandler<T extends HandleMessageStreamEvent["type"]> = (data: EventData<T>, channel: TelegramEventContext, ctx: SessionContext) => void | Promise<void>; type TelegramSessionFailedHandler = (data: EventData<"session.failed">, channel: TelegramEventContext) => void | Promise<void>; /** Per-event handlers for `telegramChannel({ events })`. Each entry overrides the built-in default (handlers merge over {@link defaultEvents}). `session.failed` receives `(data, channel)`; all others also receive the {@link SessionContext}. */ export interface TelegramChannelEvents { readonly "turn.started"?: TelegramEventHandler<"turn.started">; readonly "actions.requested"?: TelegramEventHandler<"actions.requested">; readonly "action.result"?: TelegramEventHandler<"action.result">; readonly "message.completed"?: TelegramEventHandler<"message.completed">; readonly "message.appended"?: TelegramEventHandler<"message.appended">; readonly "input.requested"?: TelegramEventHandler<"input.requested">; readonly "turn.failed"?: TelegramEventHandler<"turn.failed">; readonly "turn.completed"?: TelegramEventHandler<"turn.completed">; readonly "session.failed"?: TelegramSessionFailedHandler; readonly "session.completed"?: TelegramEventHandler<"session.completed">; readonly "session.waiting"?: TelegramEventHandler<"session.waiting">; readonly "authorization.required"?: TelegramEventHandler<"authorization.required">; readonly "authorization.completed"?: TelegramEventHandler<"authorization.completed">; } /** Configuration for {@link telegramChannel}. */ export interface TelegramChannelConfig { /** API transport overrides (base URLs, custom fetch). Credentials are supplied separately via `credentials`. */ readonly api?: Omit<TelegramApiOptions, "credentials">; /** Bot username (without `@`) used to detect mentions and `/command@bot` in group chats. */ readonly botUsername?: string; /** Bot token and inbound webhook verification settings. */ readonly credentials?: TelegramChannelCredentials; /** Per-event handler overrides. See {@link TelegramChannelEvents}. */ readonly events?: TelegramChannelEvents; /** Handler for non-HITL callback queries. */ readonly onCallbackQuery?: (ctx: TelegramContext, query: TelegramCallbackQuery) => void | Promise<void>; /** Inbound message hook. Defaults to Telegram user auth and dispatch gating. */ readonly onMessage?: (ctx: TelegramContext, message: TelegramMessage) => TelegramInboundResultOrPromise; /** Override the default webhook route path (`/eve/v1/telegram`). */ readonly route?: string; /** Inbound upload policy for Telegram photos and documents. */ readonly uploadPolicy?: UploadPolicyInput; } /** Low-level Telegram handle on every channel context as `ctx.telegram`. `request` issues a raw Bot API call by method name and returns the decoded response. `post` and `sendMessage` are identical: each sends a message, splitting text over the 4096-character cap into multiple messages and resolving to the first. `startTyping` sends a chat action (defaults to `typing`) and never throws: it logs and swallows failures. */ export interface TelegramHandle { readonly botUsername: string | undefined; readonly chatId: string; readonly chatType: TelegramChatType | undefined; readonly conversationId: string | undefined; readonly messageThreadId: number | undefined; request(method: string, body?: JsonObject): Promise<TelegramApiResponse>; post(message: string | TelegramMessageBody): Promise<TelegramMessageResult>; sendMessage(message: string | TelegramMessageBody): Promise<TelegramMessageResult>; startTyping(action?: string): Promise<void>; answerCallbackQuery(input: { readonly callbackQueryId: string; readonly showAlert?: boolean; readonly text?: string; }): Promise<TelegramApiResponse>; editMessageReplyMarkup(input: { readonly messageId: number | string; readonly replyMarkup?: Readonly<Record<string, unknown>>; }): Promise<TelegramApiResponse>; } /** Concrete return type of {@link telegramChannel}. */ export interface TelegramChannel extends Channel<TelegramChannelState, TelegramReceiveTarget, TelegramInstrumentationMetadata> { } /** Telegram channel factory for webhook updates and proactive messages. */ export declare function telegramChannel(config?: TelegramChannelConfig): TelegramChannel; export {};