A local-first multi-agent app development platform, built on PenguinHarness
/**
* The Telegram Bot API seam: the methods the Telegram connector uses (`getMe`,
* `getWebhookInfo`, `sendMessage`, `getUpdates`, the file download behind an inbound photo
* or document, and the `sendPhoto` / `sendDocument` uploads behind an outbound one),
* behind an injectable transport so unit
* tests substitute a fake and never open real network. Telegram needs no SDK — the Bot API is plain HTTPS
* POSTs against https://api.telegram.org — so the production transport is a thin fetch
* wrapper.
*
* Wire types below mirror the Bot API JSON verbatim (snake_case): the transport does not
* reshape payloads, so a test fake constructs exactly what the real API returns.
*/
import { FormData, fetch as undiciFetch } from "undici";
import { MessagingChannelError, httpStatusRecovers } from "./connector.js";
import { MessagingMediaTooLargeError, collectUnderCap } from "./media.js";
/** Telegram Bot API host. Deliberately not configurable: bindings carry only the token. */
export const TELEGRAM_API_BASE = "https://api.telegram.org";
/**
* The largest file the Bot API will serve a BOT through `getFile`, whatever the sender was
* allowed to upload. Past it the call is refused with a 400 whose only signal is prose
* Telegram is free to reword, so the connector caps its own transfers here instead: a size
* refusal the user can act on ("send something smaller") must not reach them as an
* unexplained download failure.
*/
export const TELEGRAM_MAX_DOWNLOAD_BYTES = 20 * 1024 * 1024;
/** One credential set (a binding's stored token, or a test request's draft). */
export interface TelegramCredentials {
/** The whole credential: `<numeric bot id>:<secret>` as issued by @BotFather. */
botToken: string;
}
/**
* `getMe` result — the slice of the Bot API `User` object the connector consumes. The
* capability flag is documented as "Returned only in getMe", so this is the one call that
* can report it, and it may be absent from a response that predates it.
*/
export interface TelegramBotUser {
id: number;
first_name?: string;
username?: string;
/**
* "True, if privacy mode is disabled for the bot." Privacy mode is ON for every bot whose
* owner has not turned it off in @BotFather, and it silently withholds ordinary group
* messages wherever the bot is not an administrator of the group — see the connector's
* checkCredentials.
*/
can_read_all_group_messages?: boolean;
}
/**
* One entry of a message's `entities` array: a span over the text with a meaning attached.
*
* `offset` and `length` are counted in UTF-16 code units — which is exactly what a
* JavaScript string index is, so a span applies with `slice(offset, offset + length)` and
* nothing has to be converted anywhere in this codebase.
*/
export interface TelegramMessageEntity {
/** `mention` (the span is a literal `@username`), `text_mention` (a user with no username, carried in `user`), `bold`, `code`, … */
type: string;
offset: number;
length: number;
/** Present on `text_mention` only: the user the span refers to, there being no `@username` in the text to match on. */
user?: { id: number };
}
/**
* One size variant of an inbound photo. The Bot API sends a photo as an ARRAY of these —
* the same picture re-encoded at several resolutions — and the connector picks the largest,
* which is the one the user actually sent.
*/
export interface TelegramPhotoSize {
file_id: string;
width: number;
height: number;
/** The Bot API marks it optional, so the size comparison cannot rely on it alone. */
file_size?: number;
}
/**
* An inbound `document` — a file the sender chose to send AS a file. The Bot API models it
* separately from `audio` / `video` / `voice` precisely because those are media it re-encodes
* for playback, and this is the only one of them that carries the sender's own name.
*/
export interface TelegramDocument {
file_id: string;
/** The sender's file name. Optional on the wire; a client that sends none leaves it absent. */
file_name?: string;
/** The Bot API marks it optional, so it can only refuse a transfer early, never authorize one. */
file_size?: number;
}
/** The slice of a Bot API `Message` the connector consumes. */
export interface TelegramMessage {
message_id: number;
chat: {
id: number;
/** `private` for a direct chat with the bot; `group` / `supergroup` / `channel` otherwise. */
type: string;
/** "True, if the supergroup chat is a forum" — i.e. it is split into topics at all. */
is_forum?: boolean;
};
/** Present only for text messages; anything else (photo, sticker, voice, …) omits it. */
text?: string;
/** Spans over `text` (mentions, formatting, …); absent when the message has none. */
entities?: TelegramMessageEntity[];
/**
* "Unique identifier of a message thread or forum topic to which the message belongs; for
* supergroups and private chats only."
*
* Inbound and outbound are NOT symmetric, and the difference is the whole reason
* `is_topic_message` is read below. This field is also set on an ordinary reply chain — in
* a private chat, and in a supergroup that is no forum — while `sendMessage`'s
* `message_thread_id` is "for forum supergroups only" and answers anything else with
* `Bad Request: message thread not found`. So a value seen here may only be sent back once
* `chat.is_forum` and `is_topic_message` both say it names a forum topic.
*
* Absent in a forum supergroup's General topic — which is why absence has to mean "send
* without a thread" rather than "send to General by id".
*/
message_thread_id?: number;
/**
* "True, if the message is sent to a forum topic." Absent for a forum's General topic and
* for the reply-chain `message_thread_id` above, which is exactly what tells the two apart.
*/
is_topic_message?: boolean;
/** Size variants of an inbound photo, smallest first; absent for every other message kind. */
photo?: TelegramPhotoSize[];
/** An inbound file sent as a file; absent for every other message kind. */
document?: TelegramDocument;
/** The text sent WITH a photo (or another media message) — a text message carries `text` instead. */
caption?: string;
/**
* The same spans over `caption` that `entities` carries over `text`. A captioned photo is
* how a group addresses this bot about a picture, so the caption needs the same mention
* handling the text gets — see the connector's stripBotMention.
*/
caption_entities?: TelegramMessageEntity[];
from?: {
first_name?: string;
username?: string;
};
}
/** The slice of `getFile`'s result the connector consumes. */
export interface TelegramFile {
/**
* Path to pass to the file endpoint (valid at least an hour). Optional on the wire: a
* file the bot may not download resolves without one.
*/
file_path?: string;
file_size?: number;
}
/** A downloaded file: the bytes, plus the path they came from (its extension names the type). */
export interface TelegramFileBytes {
data: Buffer;
filePath: string;
}
/**
* The slice of `getWebhookInfo`'s result the connector consumes. `url` is the empty string
* when no webhook is registered — that is the Bot API's own encoding, not a normalization.
*/
export interface TelegramWebhookInfo {
url: string;
}
/** One `getUpdates` entry. Only `message` updates are processed; the rest are skipped. */
export interface TelegramUpdate {
update_id: number;
message?: TelegramMessage;
}
/** Bot API half of the seam, bound to one token. Every method throws on failure with a readable reason. */
export interface TelegramBotClient {
/** Credential probe: resolves the bot's own account (the test endpoint surfaces its username). */
getMe(): Promise<TelegramBotUser>;
/**
* Reports the webhook registered on the bot, if any. A webhook and `getUpdates` are
* mutually exclusive on the Bot API, so a bot pointed at one cannot be polled at all
* until it is removed — and removing it is the user's call, not this app's: the
* registration belongs to whatever service they pointed it at, and clearing it here
* would silently take that service off the air. Read-only on purpose; the connector
* reports the URL and leaves the bot alone.
*/
getWebhookInfo(): Promise<TelegramWebhookInfo>;
/**
* Sends a text message into a chat; `replyToMessageId` threads it under an inbound message,
* and `messageThreadId` puts it in a forum topic. Without the latter a send lands in a forum
* supergroup's General topic, wherever the conversation actually is — and with it anywhere
* that is not a forum topic the call fails, the parameter being "for forum supergroups only".
*/
sendMessage(args: {
chatId: string;
text: string;
replyToMessageId?: number;
messageThreadId?: number;
/**
* How `text` is to be parsed. Omitted, it is delivered verbatim — which is what every
* fixed notice wants. `"HTML"` reads it as Telegram's closed tag set (see
* telegram-html.ts); a construct it dislikes is a 400 for the WHOLE message, so a
* caller that sets it must have a plain-text send to fall back to.
*/
parseMode?: "HTML";
}): Promise<void>;
/**
* Long-poll for updates: blocks up to `timeoutSec` (0 = return immediately) and resolves
* the pending updates at or after `offset` (confirming everything before it; -1 means
* "the newest update only", the connector's connect-time backlog drain). `signal` aborts
* an in-flight poll when the connection closes.
*/
getUpdates(args: {
offset?: number;
timeoutSec: number;
signal: AbortSignal;
}): Promise<TelegramUpdate[]>;
/**
* Downloads a file the bot can see, in two hops: `getFile` resolves a path, and the FILE
* endpoint serves the bytes. That second URL is not the method endpoint — it is
* `/file/bot<token>/<file_path>` — and it embeds the bot token, so no failure here may
* ever echo it (see fetchErrorText). Throws when the transfer fails or exceeds
* `maxBytes`; the Bot API itself refuses to serve a bot anything over 20MB this way
* (TELEGRAM_MAX_DOWNLOAD_BYTES), so whichever ceiling is lower is the one that bites.
*
* `what` names the transfer in a size error, so the chat and the log say which kind of
* thing was refused. It never carries the URL, which embeds the token.
*/
getFileBytes(args: {
fileId: string;
maxBytes: number;
what?: string;
}): Promise<TelegramFileBytes>;
/**
* Sends a picture into a chat as a photo, so it renders inline. Multipart upload from
* bytes rather than by URL — the file lives in a Workspace this server can read and
* Telegram cannot.
*/
sendPhoto(args: { chatId: string; fileName: string; data: Buffer }): Promise<void>;
/** Sends any other file into a chat as a document (the attachment form). */
sendDocument(args: { chatId: string; fileName: string; data: Buffer }): Promise<void>;
}
/** Factory the Telegram connector is built over: the production fetch adapter, or a test fake. */
export interface TelegramTransport {
createClient(creds: TelegramCredentials): TelegramBotClient;
}
/**
* `fetch` AND `FormData` are imported from undici on purpose, and must stay a matched pair.
*
* The startup entry replaces `globalThis.fetch` with undici's so outbound traffic follows
* the proxy dispatcher (see net/proxy.ts). undici's fetch brand-checks a FormData body
* against ITS OWN class, and Node's built-in `FormData` is a different class, so a global
* `new FormData()` fell through undici's body handling to `String(body)` — the Bot API
* received the 17 bytes `[object FormData]` as `text/plain` and answered "there is no
* document in the request". Every upload failed in production and none did in CI, where
* `globalThis.fetch` is still the runtime's own and the pairing happens to match.
*
* Importing FormData from undici while calling `globalThis.fetch` inverts the same bug, so
* the transport calls undici's fetch directly. That keeps the proxy: undici's fetch
* resolves the global dispatcher per call, which is the contract net/proxy.ts is written
* against. `Blob` needs no such treatment — `globalThis.Blob` IS node:buffer's Blob, and
* undici's FormData accepts it (verified on the wire, not assumed).
*/
type TelegramFetch = typeof undiciFetch;
export interface TelegramTransportOpts {
/**
* Test seam: the `fetch` the transport calls. Only for the tests that assert on request
* shape and error mapping — the multipart pairing above is provable only against a real
* socket, so the tests that cover it drive the default.
*/
fetch?: TelegramFetch;
}
// ---------------------------------------------------------------------------
// Production adapter over fetch
// ---------------------------------------------------------------------------
/** Overall per-request deadline for the short calls (getMe / sendMessage / the drain). */
const CALL_TIMEOUT_MS = 15_000;
/**
* Deadline for a file transfer, in either direction. Far longer than a method call: these
* move megabytes over whatever link the server has, and a 15s ceiling would fail a picture
* that was on its way perfectly well.
*/
const TRANSFER_TIMEOUT_MS = 60_000;
/** The `{ok, result, description, error_code}` envelope every Bot API response carries. */
interface TelegramEnvelope<T> {
ok?: boolean;
result?: T;
description?: string;
error_code?: number;
}
/**
* A Bot API call the server answered with `ok: false`, carrying Telegram's own `error_code`.
*
* The code is the only part of the envelope a caller may branch on: `description` is prose
* Telegram rewords without notice, so a retry keyed on its wording breaks silently. A
* transport failure — a timeout, a reset — has no code and stays out of this class (a
* MessagingChannelError that recovers), which keeps "the request never completed"
* distinguishable from "Telegram refused it"; nothing may retry the former, because the
* message may well have been delivered.
*
* `recovers` follows the code, which is Telegram's copy of the HTTP status (see
* httpStatusRecovers): a 429 flood wait or a 5xx clears by itself, while a revoked token
* (401), a conflicting poller (409) or a chat that blocked the bot (403) repeats until someone
* acts. A body with no code at all is judged by the status it arrived with.
*/
export class TelegramApiError extends MessagingChannelError {
constructor(
message: string,
readonly errorCode: number | undefined,
recovers = httpStatusRecovers(errorCode),
) {
super(message, recovers);
this.name = "TelegramApiError";
}
}
/**
* The two 409s a Bot API caller can actually act on, rewritten to lead with the action.
* Telegram's own wording buries it — "Conflict: terminated by other getUpdates request;
* make sure that only one bot instance is running" reads as an internal detail until the
* end of the sentence, and a status line has room for a few words, not a paragraph. Any
* other description passes through untouched.
*/
function conflictText(description: string): string | null {
if (/terminated by other getUpdates/i.test(description)) {
return "another program is already polling this bot — one bot token can serve only one Adelie server at a time";
}
if (/webhook is active/i.test(description)) {
return "a webhook is set on this bot, which blocks polling — remove it and the connection recovers on its own";
}
return null;
}
/**
* Readable failure text out of fetch's throw shapes. The request URL embeds the bot
* token, so nothing here may echo the URL — only the cause's own message (connect/DNS
* errors name the address, never the path).
*/
function fetchErrorText(err: unknown): string {
if (err instanceof Error) {
if (err.name === "TimeoutError" || err.name === "AbortError") return "request timed out";
const cause = (err as { cause?: unknown }).cause;
if (cause instanceof Error && cause.message !== "") return cause.message;
return err.message;
}
return String(err);
}
/**
* A response body as chunks. `Response.body` is a web ReadableStream, which is only
* async-iterable under some lib configurations; reading it through its reader works under
* all of them. Cancelling on the way out matters for the capped read — a transfer aborted
* over the ceiling must not leave the socket draining the rest of the file.
*/
async function* bodyChunks(body: ReadableStream<Uint8Array>): AsyncGenerator<Uint8Array> {
const reader = body.getReader();
try {
for (;;) {
const { done, value } = await reader.read();
if (done) return;
if (value !== undefined) yield value;
}
} finally {
await reader.cancel().catch(() => {});
}
}
/** The production factory: plain HTTPS against the Bot API. */
export function createTelegramTransport(opts: TelegramTransportOpts = {}): TelegramTransport {
const doFetch = opts.fetch ?? undiciFetch;
return {
createClient(creds: TelegramCredentials): TelegramBotClient {
/** One Bot API method call: POST the body, then unwrap the `{ok, result}` envelope. */
const send = async <T>(
method: string,
// The two body shapes this transport posts: a JSON string, or a multipart upload.
body: string | FormData,
headers: Record<string, string>,
opts?: { signal?: AbortSignal; timeoutMs?: number },
): Promise<T> => {
const deadline = AbortSignal.timeout(opts?.timeoutMs ?? CALL_TIMEOUT_MS);
const signal = opts?.signal ? AbortSignal.any([opts.signal, deadline]) : deadline;
let res: Awaited<ReturnType<TelegramFetch>>;
try {
res = await doFetch(`${TELEGRAM_API_BASE}/bot${creds.botToken}/${method}`, {
method: "POST",
headers,
body,
signal,
});
} catch (err) {
throw new MessagingChannelError(`${method} failed: ${fetchErrorText(err)}`, true);
}
const parsed = (await res.json().catch(() => null)) as TelegramEnvelope<T> | null;
if (parsed === null || parsed.ok !== true) {
const described = parsed?.description;
const detail =
(described !== undefined ? conflictText(described) : null) ??
described ??
`HTTP ${res.status}`;
const code = parsed?.error_code !== undefined ? ` (code ${parsed.error_code})` : "";
throw new TelegramApiError(
`${method} failed: ${detail}${code}`,
parsed?.error_code,
httpStatusRecovers(parsed?.error_code ?? res.status),
);
}
return parsed.result as T;
};
const call = <T>(
method: string,
payload: Record<string, unknown>,
opts?: { signal?: AbortSignal; timeoutMs?: number },
): Promise<T> =>
send<T>(method, JSON.stringify(payload), { "content-type": "application/json" }, opts);
/**
* A file-carrying call. No content-type is set on purpose: fetch derives the
* multipart one from the FormData, boundary included, and a hand-written header
* would name a boundary the body does not use.
*/
const callForm = (method: string, form: FormData): Promise<unknown> =>
send<unknown>(method, form, {}, { timeoutMs: TRANSFER_TIMEOUT_MS });
// Chat ids are stored as text; the API wants the numeric form back (a string works
// for @channel usernames only), so safe integers are converted.
const wireChatId = (chatId: string): number | string => {
const n = Number(chatId);
return Number.isSafeInteger(n) && chatId.trim() !== "" ? n : chatId;
};
return {
getMe: () => call<TelegramBotUser>("getMe", {}),
getWebhookInfo: () => call<TelegramWebhookInfo>("getWebhookInfo", {}),
async sendMessage({
chatId,
text,
replyToMessageId,
messageThreadId,
parseMode,
}): Promise<void> {
await call("sendMessage", {
chat_id: wireChatId(chatId),
text,
...(parseMode !== undefined ? { parse_mode: parseMode } : {}),
...(messageThreadId !== undefined ? { message_thread_id: messageThreadId } : {}),
// Degrade to a plain send when the replied-to message is gone, rather than fail.
...(replyToMessageId !== undefined
? {
reply_parameters: {
message_id: replyToMessageId,
allow_sending_without_reply: true,
},
}
: {}),
});
},
getUpdates: ({ offset, timeoutSec, signal }) =>
call<TelegramUpdate[]>(
"getUpdates",
{
timeout: timeoutSec,
allowed_updates: ["message"],
...(offset !== undefined ? { offset } : {}),
},
// The overall deadline must outlive the server-side long poll.
{ signal, timeoutMs: (timeoutSec + 15) * 1000 },
),
async getFileBytes({ fileId, maxBytes, what = "The file" }): Promise<TelegramFileBytes> {
const file = await call<TelegramFile>("getFile", { file_id: fileId });
if (file.file_path === undefined || file.file_path === "") {
throw new Error("getFile failed: this file cannot be downloaded");
}
// The declared size refuses an oversized transfer before it starts; the capped
// read below is what actually holds, since the claim can be absent or wrong.
if (file.file_size !== undefined && file.file_size > maxBytes) {
throw new MessagingMediaTooLargeError(what, maxBytes);
}
let res: Awaited<ReturnType<TelegramFetch>>;
try {
res = await doFetch(
`${TELEGRAM_API_BASE}/file/bot${creds.botToken}/${file.file_path}`,
{
signal: AbortSignal.timeout(TRANSFER_TIMEOUT_MS),
},
);
} catch (err) {
throw new Error(`file download failed: ${fetchErrorText(err)}`);
}
// The URL carries the token, so a failure names the status and nothing else.
if (!res.ok || res.body === null) {
throw new Error(`file download failed: HTTP ${res.status}`);
}
const data = await collectUnderCap(bodyChunks(res.body), maxBytes, what);
return { data, filePath: file.file_path };
},
async sendPhoto({ chatId, fileName, data }): Promise<void> {
const form = new FormData();
form.append("chat_id", String(wireChatId(chatId)));
form.append("photo", new Blob([data]), fileName);
await callForm("sendPhoto", form);
},
async sendDocument({ chatId, fileName, data }): Promise<void> {
const form = new FormData();
form.append("chat_id", String(wireChatId(chatId)));
form.append("document", new Blob([data]), fileName);
await callForm("sendDocument", form);
},
};
},
};
}