@spectrum-ts/telegram 5.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License Copyright (c) 2025 Photon AI
+
+Permission is hereby granted,
+free of charge, to any person obtaining a copy of this software and associated
+documentation files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy, modify, merge,
+publish, distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice
+(including the next paragraph) shall be included in all copies or substantial
+portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF
+ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO
+EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,22 @@
+# @spectrum-ts/telegram
+
+Telegram provider for [spectrum-ts](https://github.com/photon-hq/spectrum-ts). Inbound is delivered through Fusor webhooks; outbound goes through the Telegram Bot API.
+
+## Install
+
+```sh
+bun add spectrum-ts @spectrum-ts/telegram
+```
+
+## Use
+
+```ts
+import { Spectrum } from "spectrum-ts";
+import { telegram } from "@spectrum-ts/telegram";
+
+const spectrum = Spectrum({
+  providers: [telegram.config({ botToken: "..." })],
+});
+```
+
+See the [telegram guide](https://github.com/photon-hq/spectrum-ts/blob/main/docs/telegram.md) for the full setup.

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import { FusorClient } from "@spectrum-ts/core";
+import z from "zod";
+
+//#region src/space.d.ts
+interface TelegramSpace {
+  id: string;
+}
+//#endregion
+//#region src/config.d.ts
+declare const configSchema: z.ZodObject<{
+  botToken: z.ZodString;
+  webhookSecret: z.ZodOptional<z.ZodString>;
+  baseUrl: z.ZodDefault<z.ZodURL>;
+}, z.core.$strip>;
+type TelegramConfig = z.infer<typeof configSchema>;
+//#endregion
+//#region src/index.d.ts
+/**
+ * Telegram provider for Spectrum.
+ *
+ * Inbound is delivered through Fusor: `createClient` returns a `fusor(...)`
+ * client whose `verify` checks the Telegram webhook secret token and parses the
+ * `Update` (pure parsing — no client). The `messages` handler reads `config`
+ * from its ctx and builds a photon client inline only to download media bytes.
+ * Outbound (`send`) also builds a photon client inline. Both go through
+ * `@photon-ai/telegram-ts`. Drop `telegram.config({...})` into
+ * `Spectrum({ providers: [...] })`.
+ *
+ * In cloud mode (`projectConfig` present), `createClient` also self-registers
+ * the bot's webhook against the Fusor edge for the project slug — see
+ * `ensureWebhook`. Without a slug (local/direct mode) registration is skipped.
+ */
+declare const telegram: import("@spectrum-ts/core").Platform<import("@spectrum-ts/core").PlatformDef<"telegram", import("zod").ZodObject<{
+  botToken: import("zod").ZodString;
+  webhookSecret: import("zod").ZodOptional<import("zod").ZodString>;
+  baseUrl: import("zod").ZodDefault<import("zod").ZodURL>;
+}, import("zod/v4/core").$strip>, import("zod").ZodType<object, unknown, import("zod/v4/core").$ZodTypeInternals<object, unknown>> | undefined, import("zod").ZodType<object, unknown, import("zod/v4/core").$ZodTypeInternals<object, unknown>> | undefined, import("zod").ZodType<object, unknown, import("zod/v4/core").$ZodTypeInternals<object, unknown>> | undefined, FusorClient<import("@photon-ai/telegram-ts").Update>, {
+  id: string;
+}, TelegramSpace, undefined, import("@spectrum-ts/core").ProviderMessage<{
+  id: string;
+}, TelegramSpace, Record<never, never>>, undefined, Record<never, never>, Record<never, never>, Record<never, never>>> & Readonly<Record<never, never>>;
+//#endregion
+export { type TelegramConfig, telegram };

package/dist/index.js

@@ -0,0 +1,905 @@
+import { UnsupportedError, definePlatform, fusor, toVCard } from "@spectrum-ts/core";
+import z from "zod";
+import { asAttachment, asCustom, asGroup, asMarkdown, asReaction, asText, asVoice, renderInlineTokens } from "@spectrum-ts/core/authoring";
+import { createTelegramClient, editMessageText, getFile, getWebhookInfo, sendChatAction, sendMessageDraft, setMessageReaction, setWebhook } from "@photon-ai/telegram-ts";
+import { Marked } from "marked";
+import { timingSafeEqual } from "node:crypto";
+//#region src/config.ts
+/**
+* The platform identifier — used for ALL THREE of:
+*
+* - the `definePlatform` name (so `message.platform` / `__platform` and
+*   the `platformStates` key are this value),
+* - the `fusor(...)` routing key the handler is registered under, and
+* - the value Fusor tags inbound Telegram events with (`event.platform`).
+*
+* Spectrum's webhook delivery looks the runtime up by `event.platform` against
+* the platform name (`platformStates.get(event.platform)`), while routing is by
+* the fusor key — so these MUST be the same string. It must also match Fusor's
+* configured platform identifier for Telegram (the `<platform>` path segment
+* the webhook is delivered under).
+*/
+const TELEGRAM_PLATFORM = "telegram";
+const configSchema = z.object({
+	/** Bot token from @BotFather (outbound API calls + media downloads). */
+	botToken: z.string().regex(/^\d+:[A-Za-z0-9_-]+$/, "botToken must be in the form '<id>:<token>'"),
+	/**
+	* The `secret_token` passed to `setWebhook`. When present, inbound webhooks
+	* are verified against the `X-Telegram-Bot-Api-Secret-Token` header; when
+	* omitted, the check is skipped. Telegram does not HMAC-sign the body, so
+	* this shared token is the only inbound authentication.
+	*/
+	webhookSecret: z.string().regex(/^[A-Za-z0-9_-]{1,256}$/).optional(),
+	/** Override the Bot API base URL. Defaults to `https://api.telegram.org`. */
+	baseUrl: z.url().default("https://api.telegram.org")
+});
+/**
+* The bot's own numeric id is the prefix of the token (`<id>:<hash>`). Used to
+* drop inbound updates the bot itself produced, so a bot never echoes its own
+* sends.
+*/
+const botIdFromToken = (botToken) => botToken.split(":")[0] ?? "";
+//#endregion
+//#region src/client.ts
+const REQUEST_TIMEOUT_MS = 3e4;
+const TRAILING_SLASHES = /\/+$/;
+/** Build a photon client bound to the bot token. Cheap: no network on construction. */
+const telegramClient = (config) => createTelegramClient({
+	token: config.botToken,
+	baseUrl: config.baseUrl
+});
+const appendFormValue = (form, key, value) => {
+	if (typeof value === "string" || value instanceof Blob) form.append(key, value);
+	else if (value instanceof Date) form.append(key, value.toISOString());
+	else form.append(key, JSON.stringify(value));
+};
+const toFormData = (body) => {
+	const form = new FormData();
+	for (const [key, value] of Object.entries(body)) {
+		if (value === void 0 || value === null) continue;
+		appendFormValue(form, key, value);
+	}
+	return form;
+};
+/**
+* Execute one Bot API call through the photon client and return the sent
+* message. JSON params go out as `application/json`; a `file` is uploaded as
+* `multipart/form-data` — wrapped in a `File` so the part keeps its filename
+* (`formDataBodySerializer` appends without an explicit name), with
+* `Content-Type: null` dropping the default JSON header so fetch sets the
+* multipart boundary. A failed call throws `TelegramApiError` (token-free).
+*/
+const executeSpec = async (client, spec) => {
+	const url = `/${spec.method}`;
+	if (spec.file) {
+		const file = new File([new Uint8Array(spec.file.bytes)], spec.file.filename, { type: spec.file.mimeType });
+		return (await client.post({
+			body: {
+				...spec.params,
+				[spec.file.field]: file
+			},
+			bodySerializer: toFormData,
+			headers: { "Content-Type": null },
+			throwOnError: true,
+			url
+		})).data.result;
+	}
+	return (await client.post({
+		body: spec.params,
+		throwOnError: true,
+		url
+	})).data.result;
+};
+/**
+* Resolve a `file_id` to its bytes. photon has no byte-download helper and the
+* file endpoint is not a Bot API JSON method, so this is the one place that
+* reaches Telegram outside photon: `getFile` (via photon) for the path, then a
+* single authenticated `fetch`. The file URL embeds the bot token, so it is
+* never interpolated into a thrown error.
+*/
+const downloadFile = async (config, fileId) => {
+	const client = telegramClient(config);
+	const filePath = (await getFile({
+		body: { file_id: fileId },
+		client,
+		throwOnError: true
+	})).result?.file_path;
+	if (!filePath) throw new Error(`Telegram getFile returned no file_path for ${fileId}`);
+	const base = config.baseUrl.replace(TRAILING_SLASHES, "");
+	const res = await fetch(`${base}/file/bot${config.botToken}/${filePath}`, { signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS) });
+	if (!res.ok) throw new Error(`Telegram media download failed: ${res.status} ${res.statusText}`);
+	return Buffer.from(await res.arrayBuffer());
+};
+//#endregion
+//#region src/inbound/media.ts
+const DEFAULT_VIDEO_MIME = "video/mp4";
+const DEFAULT_AUDIO_MIME = "audio/mpeg";
+const DEFAULT_VOICE_MIME = "audio/ogg";
+const DEFAULT_DOC_MIME = "application/octet-stream";
+const pixelArea = (photo) => photo.file_size ?? photo.width * photo.height;
+/** Telegram sends several `PhotoSize`s; pick the largest (best quality). */
+const pickLargestPhoto = (photos) => photos.reduce((best, next) => pixelArea(next) > pixelArea(best) ? next : best);
+const lazyRead = (config, fileId) => () => downloadFile(config, fileId);
+/** Build an attachment from any Telegram file, falling back when unnamed/untyped. */
+const fileAttachment = (config, file, fallbackExt, fallbackMime) => asAttachment({
+	id: file.file_id,
+	name: file.file_name ?? `${file.file_unique_id}.${fallbackExt}`,
+	mimeType: file.mime_type ?? fallbackMime,
+	size: file.file_size,
+	read: lazyRead(config, file.file_id)
+});
+const stickerAttachment = (config, sticker) => {
+	let ext = "webp";
+	let mimeType = "image/webp";
+	if (sticker.is_animated) {
+		ext = "tgs";
+		mimeType = "application/x-tgsticker";
+	} else if (sticker.is_video) {
+		ext = "webm";
+		mimeType = "video/webm";
+	}
+	return asAttachment({
+		id: sticker.file_id,
+		name: `${sticker.file_unique_id}.${ext}`,
+		mimeType,
+		size: sticker.file_size,
+		read: lazyRead(config, sticker.file_id)
+	});
+};
+/**
+* Map a Telegram `Message` to its media `Content`, or `undefined` if it carries
+* no media. A message holds at most one media kind, but `animation` also
+* populates `document` (and stickers have sub-types), so detection runs in a
+* fixed first-match order: voice → video_note → animation → video → audio →
+* document → photo → sticker.
+*
+* Bytes are read lazily: each `read()` runs `getFile` + an authenticated
+* download only when the consumer calls it, keeping the webhook ack path free
+* of network I/O. The `as*` builders memoize `read`, so a file downloads once.
+*/
+const mediaToContent = (msg, config) => {
+	if (msg.voice) return asVoice({
+		mimeType: msg.voice.mime_type ?? DEFAULT_VOICE_MIME,
+		duration: msg.voice.duration,
+		size: msg.voice.file_size,
+		read: lazyRead(config, msg.voice.file_id)
+	});
+	if (msg.video_note) return fileAttachment(config, msg.video_note, "mp4", DEFAULT_VIDEO_MIME);
+	if (msg.animation) return fileAttachment(config, msg.animation, "mp4", DEFAULT_VIDEO_MIME);
+	if (msg.video) return fileAttachment(config, msg.video, "mp4", DEFAULT_VIDEO_MIME);
+	if (msg.audio) return fileAttachment(config, msg.audio, "mp3", DEFAULT_AUDIO_MIME);
+	if (msg.document) return fileAttachment(config, msg.document, "bin", DEFAULT_DOC_MIME);
+	if (msg.photo && msg.photo.length > 0) return fileAttachment(config, pickLargestPhoto(msg.photo), "jpg", "image/jpeg");
+	if (msg.sticker) return stickerAttachment(config, msg.sticker);
+};
+/**
+* Map an inbound `Message` to its Spectrum `Content` parts: the media (if any)
+* plus its `caption` as a leading text part, or a bare `text` message. Returns
+* `[]` when nothing is representable (service messages, etc.) so the caller can
+* drop it.
+*/
+const messageToContent = (msg, config) => {
+	const media = mediaToContent(msg, config);
+	if (media) {
+		const caption = msg.caption?.trim();
+		return caption ? [asText(caption), media] : [media];
+	}
+	const text = msg.text;
+	if (text !== void 0 && text.length > 0) return [asText(text)];
+	return [];
+};
+//#endregion
+//#region src/inbound/messages.ts
+const MILLIS_PER_SECOND$2 = 1e3;
+const stubMessage = (id, content) => ({
+	id,
+	content
+});
+const senderRef = (user) => ({
+	id: String(user.id),
+	...user.username ? { handle: user.username } : {},
+	isMe: false
+});
+const toRecordContent = (contents, messageId) => {
+	if (contents.length === 0) return;
+	if (contents.length === 1) return contents[0];
+	return asGroup({ items: contents.map((content, index) => stubMessage(`${messageId}:${index}`, content)) });
+};
+const fromMessage = (msg, config) => {
+	if (msg.from && String(msg.from.id) === botIdFromToken(config.botToken)) return;
+	const content = toRecordContent(messageToContent(msg, config), String(msg.message_id));
+	if (!content) return;
+	return {
+		id: String(msg.message_id),
+		content,
+		...msg.from ? { sender: senderRef(msg.from) } : {},
+		space: { id: String(msg.chat.id) },
+		timestamp: /* @__PURE__ */ new Date(msg.date * MILLIS_PER_SECOND$2)
+	};
+};
+const emojiReactions = (reactions) => reactions.filter((r) => r.type === "emoji").map((r) => r.emoji);
+const fromReaction = (reaction) => {
+	const added = emojiReactions(reaction.new_reaction);
+	if (added.length === 0) return;
+	const previous = new Set(emojiReactions(reaction.old_reaction));
+	const emoji = added.find((e) => !previous.has(e)) ?? added[0];
+	if (!emoji) return;
+	const target = stubMessage(String(reaction.message_id), asCustom({ telegram: "reaction-target" }));
+	const actorId = reaction.user ? String(reaction.user.id) : "anonymous";
+	return {
+		id: `reaction:${reaction.chat.id}:${reaction.message_id}:${reaction.date}:${actorId}:${emoji}`,
+		content: asReaction({
+			emoji,
+			target
+		}),
+		...reaction.user ? { sender: senderRef(reaction.user) } : {},
+		space: { id: String(reaction.chat.id) },
+		timestamp: /* @__PURE__ */ new Date(reaction.date * MILLIS_PER_SECOND$2)
+	};
+};
+/**
+* Map a verified Telegram `Update` to the Spectrum message it represents. v1
+* surfaces new messages and channel posts (text + media, with captions) and
+* emoji reactions (`message_reaction`, which requires the operator to list it
+* in `allowed_updates`). Edits, callback queries, polls, membership changes and
+* other update types are ignored (return `undefined`).
+*/
+const handleMessages = ({ payload: update, config }) => {
+	const message = update.message ?? update.channel_post;
+	if (message) return fromMessage(message, config);
+	if (update.message_reaction) return fromReaction(update.message_reaction);
+};
+//#endregion
+//#region src/reactions.ts
+/**
+* Telegram reactions ARE emoji (unlike LinQ's tapback enum), so inbound and
+* outbound need no translation — the emoji string maps straight to/from
+* Spectrum. The catch: `setMessageReaction` only accepts a fixed set of
+* standard emoji in non-premium chats; anything else fails with
+* `REACTION_INVALID`. This set is exported so callers can pre-check, and the
+* send path uses it to turn that API error into a clearer message.
+*
+* Source: the default `available_reactions` documented for the Bot API. The set
+* is stable but Telegram can extend it; treat membership as a best-effort hint,
+* not a hard guarantee.
+*/
+const ALLOWED_REACTION_EMOJI = new Set([
+	"👍",
+	"👎",
+	"❤",
+	"🔥",
+	"🥰",
+	"👏",
+	"😁",
+	"🤔",
+	"🤯",
+	"😱",
+	"🤬",
+	"😢",
+	"🎉",
+	"🤩",
+	"🤮",
+	"💩",
+	"🙏",
+	"👌",
+	"🕊",
+	"🤡",
+	"🥱",
+	"🥴",
+	"😍",
+	"🐳",
+	"❤‍🔥",
+	"🌚",
+	"🌭",
+	"💯",
+	"🤣",
+	"⚡",
+	"🍌",
+	"🏆",
+	"💔",
+	"🤨",
+	"😐",
+	"🍓",
+	"🍾",
+	"💋",
+	"🖕",
+	"😈",
+	"😴",
+	"😭",
+	"🤓",
+	"👻",
+	"👨‍💻",
+	"👀",
+	"🎃",
+	"🙈",
+	"😇",
+	"😨",
+	"🤝",
+	"✍",
+	"🤗",
+	"🫡",
+	"🎅",
+	"🎄",
+	"☃",
+	"💅",
+	"🤪",
+	"🗿",
+	"🆒",
+	"💘",
+	"🙉",
+	"🦄",
+	"😘",
+	"💊",
+	"🙊",
+	"😎",
+	"👾",
+	"🤷‍♂",
+	"🤷",
+	"🤷‍♀",
+	"😡"
+]);
+const VARIATION_SELECTOR_16 = /️/g;
+const stripVariationSelector = (emoji) => emoji.replace(VARIATION_SELECTOR_16, "");
+/**
+* Telegram's reaction set uses bare codepoints (no U+FE0F variation selector),
+* while clients/Spectrum often carry the emoji-presentation form (e.g. `❤️`).
+* Strip the selector before comparing so both forms validate.
+*/
+const isAllowedReactionEmoji = (emoji) => ALLOWED_REACTION_EMOJI.has(stripVariationSelector(emoji));
+/**
+* The form to send to `setMessageReaction`. Known reactions are normalized to
+* the bare codepoint Telegram expects; unknown emoji pass through unchanged so
+* the API's own validation (and our clearer error) can take over.
+*/
+const normalizeReactionEmoji = (emoji) => isAllowedReactionEmoji(emoji) ? stripVariationSelector(emoji) : emoji;
+//#endregion
+//#region src/outbound/markdown.ts
+const markdownLexer = new Marked();
+const BULLET = "• ";
+const HR_LINE = "———";
+const NESTED_LIST_INDENT = "  ";
+const BLOCK_SEPARATOR = "\n\n";
+const TABLE_CELL_SEPARATOR = " | ";
+const DEFAULT_LIST_START = 1;
+const AMP_PATTERN = /&/g;
+const LT_PATTERN = /</g;
+const GT_PATTERN = />/g;
+const QUOTE_PATTERN = /"/g;
+const escapeHtml = (value) => value.replace(AMP_PATTERN, "&amp;").replace(LT_PATTERN, "&lt;").replace(GT_PATTERN, "&gt;");
+const escapeAttribute = (value) => escapeHtml(value).replace(QUOTE_PATTERN, "&quot;");
+const asMarkedToken = (token) => token;
+const checkboxPrefix = (item) => {
+	if (!item.task) return "";
+	return item.checked ? "[x] " : "[ ] ";
+};
+const listMarker = (list, index) => {
+	if (!list.ordered) return BULLET;
+	return `${(list.start === "" ? DEFAULT_LIST_START : list.start) + index}. `;
+};
+const renderLink = (token) => {
+	if (token.text === token.href) return escapeHtml(token.href);
+	return `<a href="${escapeAttribute(token.href)}">${renderInlineTokens$1(token.tokens)}</a>`;
+};
+const renderImage = (token) => `<a href="${escapeAttribute(token.href)}">${escapeHtml(token.text || token.href)}</a>`;
+const renderText = (token) => {
+	if (token.tokens) return renderInlineTokens$1(token.tokens);
+	return token.escaped ? token.text : escapeHtml(token.text);
+};
+const renderInlineToken = (token) => {
+	switch (token.type) {
+		case "strong": return `<b>${renderInlineTokens$1(token.tokens)}</b>`;
+		case "em": return `<i>${renderInlineTokens$1(token.tokens)}</i>`;
+		case "del": return `<s>${renderInlineTokens$1(token.tokens)}</s>`;
+		case "codespan": return `<code>${escapeHtml(token.text)}</code>`;
+		case "br": return "\n";
+		case "link": return renderLink(token);
+		case "image": return renderImage(token);
+		case "escape": return escapeHtml(token.text);
+		case "text": return renderText(token);
+		case "html": return escapeHtml(token.text);
+		case "checkbox": return "";
+		default: return "raw" in token ? escapeHtml(String(token.raw)) : "";
+	}
+};
+const renderInlineTokens$1 = (tokens) => {
+	let out = "";
+	for (const token of tokens) out += renderInlineToken(asMarkedToken(token));
+	return out;
+};
+const renderCode = (token) => {
+	if (token.lang) return `<pre><code class="language-${escapeAttribute(token.lang)}">${escapeHtml(token.text)}</code></pre>`;
+	return `<pre>${escapeHtml(token.text)}</pre>`;
+};
+const renderQuoteBody = (tokens) => {
+	const blocks = [];
+	for (const token of tokens) {
+		const marked = asMarkedToken(token);
+		const rendered = marked.type === "blockquote" ? renderQuoteBody(marked.tokens) : renderBlockToken(marked);
+		if (rendered) blocks.push(rendered);
+	}
+	return blocks.join("\n");
+};
+const renderList = (list) => {
+	const lines = [];
+	for (const [index, item] of list.items.entries()) {
+		const prefix = `${listMarker(list, index)}${checkboxPrefix(item)}`;
+		const blocks = [];
+		for (const token of item.tokens) {
+			const rendered = renderBlockToken(asMarkedToken(token));
+			if (rendered) blocks.push(rendered);
+		}
+		const [first = "", ...rest] = blocks.join("\n").split("\n");
+		lines.push(`${prefix}${first}`);
+		for (const line of rest) lines.push(`${NESTED_LIST_INDENT}${line}`);
+	}
+	return lines.join("\n");
+};
+const renderTable = (table) => {
+	const renderRow = (cells) => cells.map((cell) => renderInlineTokens(cell.tokens)).join(TABLE_CELL_SEPARATOR);
+	const lines = [renderRow(table.header)];
+	for (const row of table.rows) lines.push(renderRow(row));
+	return `<pre>${escapeHtml(lines.join("\n"))}</pre>`;
+};
+const renderBlockToken = (token) => {
+	switch (token.type) {
+		case "heading": return `<b>${renderInlineTokens$1(token.tokens)}</b>`;
+		case "paragraph": return renderInlineTokens$1(token.tokens);
+		case "code": return renderCode(token);
+		case "blockquote": return `<blockquote>${renderQuoteBody(token.tokens)}</blockquote>`;
+		case "list": return renderList(token);
+		case "table": return renderTable(token);
+		case "hr": return HR_LINE;
+		case "space":
+		case "def": return "";
+		default: return renderInlineToken(token);
+	}
+};
+/**
+* Render standard markdown (CommonMark + GFM) to Telegram-flavored HTML for
+* `parse_mode: "HTML"` sends. Only tags Telegram accepts are emitted; all
+* text (including raw HTML in the source) is entity-escaped so the output
+* can never fail Bot API parsing.
+*/
+const markdownToTelegramHtml = (markdown) => {
+	const blocks = [];
+	for (const token of markdownLexer.lexer(markdown)) {
+		const rendered = renderBlockToken(asMarkedToken(token));
+		if (rendered) blocks.push(rendered);
+	}
+	return blocks.join(BLOCK_SEPARATOR).trim();
+};
+//#endregion
+//#region src/outbound/message.ts
+const VCARD_FILENAME = "contact.vcf";
+const VCARD_MIME = "text/vcard";
+const DEFAULT_VOICE_FILENAME = "voice.ogg";
+/**
+* Telegram message ids are positive integers. Reject anything else up front so a
+* malformed `target.id` surfaces a clear error here instead of being coerced to
+* `NaN` and sent on to the Bot API as a confusing 400.
+*/
+const parseMessageId = (id) => {
+	const messageId = Number(id);
+	if (!Number.isInteger(messageId) || messageId <= 0) throw new Error(`Telegram message id must be a positive integer (got "${id}").`);
+	return messageId;
+};
+const customToSpec = (raw) => {
+	if (typeof raw === "object" && raw !== null && typeof raw.method === "string") {
+		const value = raw;
+		const { params } = value;
+		if (params !== void 0 && (typeof params !== "object" || params === null || Array.isArray(params))) throw new Error("Telegram custom content `raw.params` must be an object when provided.");
+		return {
+			method: value.method,
+			params: params ?? {}
+		};
+	}
+	throw new Error("Telegram custom content `raw` must be a `{ method, params }` Bot API call.");
+};
+const attachmentSpec = async (content) => {
+	const bytes = await content.read();
+	const file = {
+		field: "document",
+		filename: content.name,
+		mimeType: content.mimeType,
+		bytes
+	};
+	if (content.mimeType.startsWith("image/")) return {
+		method: "sendPhoto",
+		params: {},
+		file: {
+			...file,
+			field: "photo"
+		}
+	};
+	if (content.mimeType.startsWith("video/")) return {
+		method: "sendVideo",
+		params: {},
+		file: {
+			...file,
+			field: "video"
+		}
+	};
+	return {
+		method: "sendDocument",
+		params: {},
+		file
+	};
+};
+/**
+* Turn one message-producing `Content` into a single Bot API call. Telegram has
+* no multi-part message — each content type is its own method/endpoint — so
+* this returns a `TelegramSendSpec` (the caller injects `chat_id` and executes
+* it). `reply` recurses and threads `reply_parameters`; `group` is NOT handled
+* here (it becomes N separate sends in `send.ts`). Fire-and-forget content
+* (reaction, typing, edit) and unsupported types never reach this function.
+*/
+const buildSend = async (content) => {
+	switch (content.type) {
+		case "text": return {
+			method: "sendMessage",
+			params: { text: content.text }
+		};
+		case "markdown": return {
+			method: "sendMessage",
+			params: {
+				text: markdownToTelegramHtml(content.markdown),
+				parse_mode: "HTML"
+			}
+		};
+		case "richlink": return {
+			method: "sendMessage",
+			params: { text: content.url }
+		};
+		case "app": return {
+			method: "sendMessage",
+			params: { text: await content.url() }
+		};
+		case "attachment": return await attachmentSpec(content);
+		case "voice": {
+			const bytes = await content.read();
+			return {
+				method: "sendVoice",
+				params: content.duration === void 0 ? {} : { duration: content.duration },
+				file: {
+					field: "voice",
+					filename: content.name ?? DEFAULT_VOICE_FILENAME,
+					mimeType: content.mimeType,
+					bytes
+				}
+			};
+		}
+		case "contact": {
+			const vcf = await toVCard(content);
+			return {
+				method: "sendDocument",
+				params: {},
+				file: {
+					field: "document",
+					filename: VCARD_FILENAME,
+					mimeType: VCARD_MIME,
+					bytes: Buffer.from(vcf, "utf8")
+				}
+			};
+		}
+		case "reply": {
+			const inner = await buildSend(content.content);
+			return {
+				...inner,
+				params: {
+					...inner.params,
+					reply_parameters: { message_id: parseMessageId(content.target.id) }
+				}
+			};
+		}
+		case "custom": return customToSpec(content.raw);
+		default: throw UnsupportedError.content(content.type, TELEGRAM_PLATFORM);
+	}
+};
+//#endregion
+//#region src/outbound/stream-text.ts
+const MILLIS_PER_SECOND$1 = 1e3;
+const DRAFT_THROTTLE_MS = 500;
+let nextDraftId = 1;
+/**
+* Deliver a `streamText` content natively via Telegram message drafts
+* (`sendMessageDraft`): an empty draft shows the client's "Thinking…"
+* placeholder, throttled updates animate the accumulated text while the stream
+* runs, and a final `sendMessage` persists the full text — drafts are
+* ~30-second ephemeral previews, so only a real send lands in the chat.
+* Drafts exist only in private chats; group/channel spaces (non-positive chat
+* ids) throw `UnsupportedError` before the stream is consumed, letting the
+* send pipeline's plain-text fallback deliver the accumulated text instead.
+*/
+const sendStreamText = async (client, space, content) => {
+	const chatId = Number(space.id);
+	if (!(Number.isInteger(chatId) && chatId > 0)) throw UnsupportedError.content("streamText", TELEGRAM_PLATFORM, `message drafts work only in private chats (got chat id "${space.id}").`);
+	const draftId = nextDraftId;
+	nextDraftId += 1;
+	const renderBody = (text) => content.format === "markdown" ? {
+		text: markdownToTelegramHtml(text),
+		parse_mode: "HTML"
+	} : { text };
+	let lastDraftText;
+	let lastDraftAt = 0;
+	let draftsAvailable = true;
+	const updateDraft = async (text) => {
+		if (!draftsAvailable || text === lastDraftText) return;
+		try {
+			await sendMessageDraft({
+				body: {
+					chat_id: chatId,
+					draft_id: draftId,
+					...renderBody(text)
+				},
+				client
+			});
+			lastDraftText = text;
+			lastDraftAt = Date.now();
+		} catch {
+			draftsAvailable = false;
+		}
+	};
+	await updateDraft("");
+	let full = "";
+	for await (const delta of content.stream()) {
+		full += delta;
+		if (Date.now() - lastDraftAt >= DRAFT_THROTTLE_MS) await updateDraft(full);
+	}
+	if (!full) throw UnsupportedError.content("streamText", TELEGRAM_PLATFORM, "stream produced no text — nothing to send.");
+	const sent = await executeSpec(client, {
+		method: "sendMessage",
+		params: {
+			chat_id: space.id,
+			...renderBody(full)
+		}
+	});
+	return {
+		id: String(sent.message_id),
+		content: content.format === "markdown" ? asMarkdown(full) : asText(full),
+		space: { id: space.id },
+		timestamp: /* @__PURE__ */ new Date(sent.date * MILLIS_PER_SECOND$1)
+	};
+};
+//#endregion
+//#region src/outbound/send.ts
+const MILLIS_PER_SECOND = 1e3;
+/** Build one content's spec, inject `chat_id`, execute it, return the record. */
+const sendContent = async (client, space, content) => {
+	const spec = await buildSend(content);
+	const sent = await executeSpec(client, {
+		...spec,
+		params: {
+			chat_id: space.id,
+			...spec.params
+		}
+	});
+	return {
+		id: String(sent.message_id),
+		content,
+		space: { id: space.id },
+		timestamp: /* @__PURE__ */ new Date(sent.date * MILLIS_PER_SECOND)
+	};
+};
+const sendGroup = async (client, space, items) => {
+	let last;
+	for (const item of items) last = await sendContent(client, space, item.content);
+	return last;
+};
+const sendReaction = async (client, space, content) => {
+	const messageId = parseMessageId(content.target.id);
+	const emoji = normalizeReactionEmoji(content.emoji);
+	if (!isAllowedReactionEmoji(emoji)) throw UnsupportedError.content("reaction", TELEGRAM_PLATFORM, `"${content.emoji}" is not an allowed Telegram reaction emoji.`);
+	await setMessageReaction({
+		body: {
+			chat_id: space.id,
+			message_id: messageId,
+			reaction: [{
+				emoji,
+				type: "emoji"
+			}]
+		},
+		client
+	});
+	const timestamp = /* @__PURE__ */ new Date();
+	const unixSeconds = Math.floor(timestamp.getTime() / MILLIS_PER_SECOND);
+	return {
+		id: `reaction:${space.id}:${messageId}:${unixSeconds}:bot:${emoji}`,
+		content,
+		space: { id: space.id },
+		timestamp
+	};
+};
+const sendTyping = async (client, space, state) => {
+	if (state === "start") await sendChatAction({
+		body: {
+			action: "typing",
+			chat_id: space.id
+		},
+		client
+	});
+};
+const sendEdit = async (client, space, content) => {
+	const inner = content.content;
+	if (inner.type !== "text" && inner.type !== "markdown") throw UnsupportedError.content("edit", TELEGRAM_PLATFORM, `only text and markdown content can be edited (got "${inner.type}").`);
+	const body = inner.type === "markdown" ? {
+		text: markdownToTelegramHtml(inner.markdown),
+		parse_mode: "HTML"
+	} : { text: inner.text };
+	await editMessageText({
+		body: {
+			chat_id: space.id,
+			message_id: parseMessageId(content.target.id),
+			...body
+		},
+		client
+	});
+};
+/**
+* Outbound dispatcher. Fire-and-forget signals (typing, edit) return
+* `undefined`; message-producing content returns a record with the Telegram
+* message id. Reactions return a record with a synthetic id (Telegram assigns
+* none). A `group` fans out to one message per item. `streamText` streams
+* natively via message drafts in private chats (see `stream-text.ts`). `poll`,
+* `effect`, `rename` and `avatar` are unsupported in v1 (use `custom` to reach
+* any other Bot API method directly).
+*/
+const send = async ({ space, content, config }) => {
+	const client = telegramClient(config);
+	switch (content.type) {
+		case "reaction": return await sendReaction(client, space, content);
+		case "typing": return await sendTyping(client, space, content.state);
+		case "read": return;
+		case "edit": return await sendEdit(client, space, content);
+		case "group": return await sendGroup(client, space, content.items);
+		case "streamText": return await sendStreamText(client, space, content);
+		case "poll":
+		case "poll_option":
+		case "effect":
+		case "rename":
+		case "avatar": throw UnsupportedError.content(content.type, TELEGRAM_PLATFORM);
+		default: return await sendContent(client, space, content);
+	}
+};
+//#endregion
+//#region src/space.ts
+const resolveUser = ({ input }) => Promise.resolve({ id: input.userID });
+/**
+* Create a space for a Telegram `chat_id`. A bot cannot initiate a
+* conversation or create a group, so creation only works for a private chat:
+* the single recipient's user id equals the chat id. Existing chats (groups,
+* supergroups, channels) are addressed by id via `space.get(chatId)` —
+* Telegram chat ids are numbers in the wire format (negative for
+* groups/supergroups); stringify them with `String(chatId)`.
+*/
+const createSpace = ({ input }) => {
+	const [first, ...rest] = input.users;
+	if (first && rest.length === 0) return Promise.resolve({ id: first.id });
+	if (!first) throw new Error("Telegram space creation requires a recipient user.");
+	throw new Error("Telegram bots cannot create group chats — use space.get(chatId) for an existing chat, or create a space with a single user (their private chat).");
+};
+//#endregion
+//#region src/verify.ts
+/**
+* Telegram echoes the `secret_token` configured in `setWebhook` back in this
+* header (lowercased by Spectrum/Fusor). It is the ONLY inbound authentication
+* — Telegram does not HMAC-sign the request body.
+*/
+const SECRET_TOKEN_HEADER = "x-telegram-bot-api-secret-token";
+const safeEqual = (a, b) => {
+	const left = Buffer.from(a, "utf8");
+	const right = Buffer.from(b, "utf8");
+	if (left.length === 0 || left.length !== right.length) return false;
+	return timingSafeEqual(left, right);
+};
+const verifySecret = (headers, secret) => {
+	const provided = headers[SECRET_TOKEN_HEADER];
+	if (!provided) throw new Error("Telegram webhook is missing the secret token header");
+	if (!safeEqual(provided, secret)) throw new Error("Telegram webhook secret token mismatch");
+};
+const isUpdate = (value) => typeof value === "object" && value !== null && "update_id" in value && typeof value.update_id === "number";
+const parseUpdate = (bodyText) => {
+	let json;
+	try {
+		json = JSON.parse(bodyText);
+	} catch {
+		throw new Error("Telegram webhook body is not valid JSON");
+	}
+	if (!isUpdate(json)) throw new Error("Telegram webhook payload is missing a numeric update_id");
+	return json;
+};
+/**
+* Build the Fusor `verify` hook. Receiving is pure parsing: it closes over
+* `config` only to check the webhook secret token, then parses the raw body
+* into an `Update` and returns it as the payload — no client is involved. When
+* no `webhookSecret` is configured the token check is skipped and the body is
+* parsed directly. Throwing rejects the event (Fusor returns 400 — no retry).
+* The inbound mapper reads `config` from its own ctx and builds a client inline
+* only if it needs to download media.
+*/
+const verify = (config) => (req) => {
+	if (config.webhookSecret) verifySecret(req.headers, config.webhookSecret);
+	return parseUpdate(new TextDecoder().decode(req.rawBody));
+};
+//#endregion
+//#region src/webhook.ts
+/**
+* Base domain of the Fusor "super webhook" edge. Telegram delivers updates to
+* `https://{slug}.{domain}/{platform}`, where Fusor forwards them on to
+* Spectrum. Override per-environment (e.g. `staging.spctrm.dev`) via
+* `SPECTRUM_SUPER_WEBHOOK`.
+*/
+const DEFAULT_SUPER_WEBHOOK_DOMAIN = "spctrm.dev";
+/**
+* The Bot API webhook URL Telegram should POST updates to: the Fusor edge keyed
+* by the project `slug`, on the Telegram platform path segment.
+*/
+const webhookUrl = (slug) => {
+	return `https://${slug}.${process.env.SPECTRUM_SUPER_WEBHOOK ?? DEFAULT_SUPER_WEBHOOK_DOMAIN}/${TELEGRAM_PLATFORM}`;
+};
+/**
+* Make Telegram deliver this bot's updates to the Fusor edge for `slug`.
+*
+* Idempotent: reads the current webhook via `getWebhookInfo` and only calls
+* `setWebhook` when the URL differs, so a restart with an already-registered
+* bot makes no write. `config.webhookSecret`, when set, is registered as the
+* `secret_token` Telegram echoes back for inbound verification (see `verify`);
+* when absent, the webhook is registered without one.
+*
+* Note: `getWebhookInfo` does not return the secret, so a secret-only change
+* (same URL) is not re-applied — change the URL or clear the webhook to force it.
+*
+* Failures throw a token-free error (the bot token is never interpolated),
+* failing `Spectrum()` startup fast: a bot that cannot register its webhook
+* receives nothing.
+*/
+const ensureWebhook = async (config, slug) => {
+	const client = telegramClient(config);
+	const url = webhookUrl(slug);
+	try {
+		if ((await getWebhookInfo({
+			client,
+			throwOnError: true
+		})).result?.url === url) return;
+		await setWebhook({
+			body: {
+				url,
+				...config.webhookSecret ? { secret_token: config.webhookSecret } : {}
+			},
+			client,
+			throwOnError: true
+		});
+	} catch (error) {
+		throw new Error(`Telegram webhook registration failed for ${url}`, { cause: error });
+	}
+};
+//#endregion
+//#region src/index.ts
+/**
+* Telegram provider for Spectrum.
+*
+* Inbound is delivered through Fusor: `createClient` returns a `fusor(...)`
+* client whose `verify` checks the Telegram webhook secret token and parses the
+* `Update` (pure parsing — no client). The `messages` handler reads `config`
+* from its ctx and builds a photon client inline only to download media bytes.
+* Outbound (`send`) also builds a photon client inline. Both go through
+* `@photon-ai/telegram-ts`. Drop `telegram.config({...})` into
+* `Spectrum({ providers: [...] })`.
+*
+* In cloud mode (`projectConfig` present), `createClient` also self-registers
+* the bot's webhook against the Fusor edge for the project slug — see
+* `ensureWebhook`. Without a slug (local/direct mode) registration is skipped.
+*/
+const telegram = definePlatform(TELEGRAM_PLATFORM, {
+	config: configSchema,
+	lifecycle: { createClient: async ({ config, projectConfig }) => {
+		const slug = projectConfig?.slug;
+		if (slug) await ensureWebhook(config, slug);
+		return fusor(TELEGRAM_PLATFORM, verify(config));
+	} },
+	user: { resolve: resolveUser },
+	space: { create: createSpace },
+	messages: handleMessages,
+	send
+});
+//#endregion
+export { telegram };

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@spectrum-ts/telegram",
+  "version": "5.0.0",
+  "description": "Telegram provider for spectrum-ts.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/photon-hq/spectrum-ts.git",
+    "directory": "packages/telegram"
+  },
+  "homepage": "https://photon.codes/spectrum",
+  "bugs": {
+    "url": "https://github.com/photon-hq/spectrum-ts/issues"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "spectrum": {
+    "key": "telegram",
+    "import": "telegram",
+    "label": "telegram"
+  },
+  "dependencies": {
+    "@photon-ai/telegram-ts": "10.0.0",
+    "marked": "^18.0.5",
+    "zod": "^4.2.1"
+  },
+  "peerDependencies": {
+    "@spectrum-ts/core": "^5.0.0",
+    "typescript": "^5 || ^6.0.0"
+  },
+  "license": "MIT"
+}