@crewhaus/channel-adapter-telegram 0.1.0

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@crewhaus/channel-adapter-telegram",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "Telegram channel adapter: secret_token webhook verification, message/edited_message/callback_query parsing, group + topic session keying (Section 33)",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "scripts": {
+    "test": "bun test src"
+  },
+  "dependencies": {
+    "@crewhaus/errors": "0.0.0"
+  },
+  "license": "Apache-2.0",
+  "author": {
+    "name": "Max Meier",
+    "email": "max@studiomax.io",
+    "url": "https://studiomax.io"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/crewhaus/factory.git",
+    "directory": "packages/channel-adapter-telegram"
+  },
+  "homepage": "https://github.com/crewhaus/factory/tree/main/packages/channel-adapter-telegram#readme",
+  "bugs": {
+    "url": "https://github.com/crewhaus/factory/issues"
+  },
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ]
+}

package/src/fixtures/bot_mention.json

@@ -0,0 +1,10 @@
+{
+  "update_id": 100006,
+  "message": {
+    "message_id": 21,
+    "from": { "id": 4242, "is_bot": false, "username": "alice" },
+    "chat": { "id": -100456, "type": "supergroup" },
+    "text": "@crewhaus_bot summarize this thread",
+    "entities": [{ "type": "mention", "offset": 0, "length": 14 }]
+  }
+}

package/src/fixtures/bot_self.json

@@ -0,0 +1,9 @@
+{
+  "update_id": 100009,
+  "message": {
+    "message_id": 90,
+    "from": { "id": 9999, "is_bot": true, "username": "crewhaus_bot" },
+    "chat": { "id": -100789, "type": "supergroup" },
+    "text": "I am the bot"
+  }
+}

package/src/fixtures/callback_query.json

@@ -0,0 +1,12 @@
+{
+  "update_id": 100005,
+  "callback_query": {
+    "id": "cq-001",
+    "from": { "id": 4242, "is_bot": false, "username": "alice" },
+    "data": "approve:123",
+    "message": {
+      "message_id": 50,
+      "chat": { "id": 4242, "type": "private" }
+    }
+  }
+}

package/src/fixtures/edited_message.json

@@ -0,0 +1,9 @@
+{
+  "update_id": 100004,
+  "edited_message": {
+    "message_id": 7,
+    "from": { "id": 4242, "is_bot": false, "username": "alice" },
+    "chat": { "id": 4242, "type": "private" },
+    "text": "hello bot (edited)"
+  }
+}

package/src/fixtures/group_message.json

@@ -0,0 +1,9 @@
+{
+  "update_id": 100002,
+  "message": {
+    "message_id": 12,
+    "from": { "id": 4242, "is_bot": false, "username": "alice" },
+    "chat": { "id": -100123, "type": "supergroup" },
+    "text": "hi everyone"
+  }
+}

package/src/fixtures/group_topic_message.json

@@ -0,0 +1,10 @@
+{
+  "update_id": 100003,
+  "message": {
+    "message_id": 99,
+    "from": { "id": 4242, "is_bot": false, "username": "alice" },
+    "chat": { "id": -100123, "type": "supergroup" },
+    "message_thread_id": 17,
+    "text": "topic-scoped reply"
+  }
+}

package/src/fixtures/missing_chat.json

@@ -0,0 +1,8 @@
+{
+  "update_id": 100010,
+  "message": {
+    "message_id": 200,
+    "from": { "id": 4242, "is_bot": false, "username": "alice" },
+    "text": "no chat field"
+  }
+}

package/src/fixtures/non_message_update.json

@@ -0,0 +1,7 @@
+{
+  "update_id": 100011,
+  "poll": {
+    "id": "p-1",
+    "question": "best agent framework?"
+  }
+}

package/src/fixtures/photo_with_caption.json

@@ -0,0 +1,9 @@
+{
+  "update_id": 100008,
+  "message": {
+    "message_id": 33,
+    "from": { "id": 4242, "is_bot": false, "username": "alice" },
+    "chat": { "id": 4242, "type": "private" },
+    "caption": "look at this graph"
+  }
+}

package/src/fixtures/private_message.json

@@ -0,0 +1,9 @@
+{
+  "update_id": 100001,
+  "message": {
+    "message_id": 7,
+    "from": { "id": 4242, "is_bot": false, "username": "alice" },
+    "chat": { "id": 4242, "type": "private" },
+    "text": "hello bot"
+  }
+}

package/src/fixtures/sticker_only.json

@@ -0,0 +1,8 @@
+{
+  "update_id": 100007,
+  "message": {
+    "message_id": 88,
+    "from": { "id": 4242, "is_bot": false, "username": "alice" },
+    "chat": { "id": 4242, "type": "private" }
+  }
+}

package/src/index.test.ts

@@ -0,0 +1,278 @@
+import { describe, expect, test } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+import {
+  type ChannelAdapter,
+  type InboundEvent,
+  type ParsedInbound,
+  type RawRequest,
+  TelegramAdapterError,
+  createTelegramAdapter,
+  verifyTelegramSecret,
+} from "./index";
+
+// `tsc -b` also compiles this file into `dist/`; resolve fixtures from the
+// source tree so both the src and dist test copies find them.
+const FIXTURES_DIR = join(import.meta.dir.replace(/([/\\])dist$/, "$1src"), "fixtures");
+const fixture = (name: string) => readFileSync(join(FIXTURES_DIR, `${name}.json`), "utf8");
+
+const SECRET = "tg-secret-shhh";
+const BOT_TOKEN = "1234:test-token";
+const ADAPTER_OPTS = (extras: Record<string, unknown> = {}) => ({
+  apiBaseUrl: "https://test.telegram.local",
+  fetch: extras["fetch"] as typeof fetch | undefined,
+  selfBotId: "9999",
+});
+
+function withHeaders(token: string | undefined, body: string): RawRequest {
+  const h = new Headers();
+  if (token !== undefined) h.set("X-Telegram-Bot-Api-Secret-Token", token);
+  return { headers: h, body };
+}
+
+function adapter(extra: Record<string, unknown> = {}): ChannelAdapter {
+  return createTelegramAdapter({ botToken: BOT_TOKEN, secretToken: SECRET }, ADAPTER_OPTS(extra));
+}
+
+describe("verifyTelegramSecret (T8)", () => {
+  test("matches a valid secret token", () => {
+    const h = new Headers({ "X-Telegram-Bot-Api-Secret-Token": SECRET });
+    expect(verifyTelegramSecret({ headers: h, secretToken: SECRET })).toBe(true);
+  });
+
+  test("rejects a tampered secret", () => {
+    const h = new Headers({ "X-Telegram-Bot-Api-Secret-Token": `${SECRET}-tampered` });
+    expect(verifyTelegramSecret({ headers: h, secretToken: SECRET })).toBe(false);
+  });
+
+  test("rejects a missing header", () => {
+    expect(verifyTelegramSecret({ headers: new Headers(), secretToken: SECRET })).toBe(false);
+  });
+
+  test("constant-time guard rejects different lengths", () => {
+    const h = new Headers({ "X-Telegram-Bot-Api-Secret-Token": "x" });
+    expect(verifyTelegramSecret({ headers: h, secretToken: SECRET })).toBe(false);
+  });
+
+  test("rejects empty supplied token", () => {
+    const h = new Headers({ "X-Telegram-Bot-Api-Secret-Token": "" });
+    expect(verifyTelegramSecret({ headers: h, secretToken: SECRET })).toBe(false);
+  });
+});
+
+describe("createTelegramAdapter.verify()", () => {
+  test("forwards header to verifyTelegramSecret", () => {
+    const a = adapter();
+    expect(a.verify(withHeaders(SECRET, "{}"))).toBe(true);
+    expect(a.verify(withHeaders("wrong-secret-here", "{}"))).toBe(false);
+    expect(a.verify(withHeaders(undefined, "{}"))).toBe(false);
+  });
+});
+
+describe("parseInbound — fixtures (T2)", () => {
+  test("private_message → event with workspaceId=chat.id, channelId=chat.id", () => {
+    const a = adapter();
+    const result = a.parseInbound(withHeaders(SECRET, fixture("private_message"))) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(result.kind).toBe("event");
+    expect(result.event.workspaceId).toBe("4242");
+    expect(result.event.channelId).toBe("4242");
+    expect(result.event.userId).toBe("4242");
+    expect(result.event.text).toBe("hello bot");
+    expect(result.event.idempotencyKey).toBe("100001");
+    expect(result.event.subtype).toBe("message");
+    expect(result.event.threadTs).toBeUndefined();
+  });
+
+  test("group_message → event with workspaceId = supergroup chat.id", () => {
+    const a = adapter();
+    const r = a.parseInbound(withHeaders(SECRET, fixture("group_message"))) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r.kind).toBe("event");
+    expect(r.event.workspaceId).toBe("-100123");
+    expect(r.event.channelId).toBe("-100123");
+    expect(r.event.threadTs).toBeUndefined();
+  });
+
+  test("group_topic_message → channelId = chatId:topicId, threadTs set", () => {
+    const a = adapter();
+    const r = a.parseInbound(withHeaders(SECRET, fixture("group_topic_message"))) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r.event.channelId).toBe("-100123:17");
+    expect(r.event.threadTs).toBe("17");
+  });
+
+  test("edited_message produces a normal event (gateway dedups via update_id)", () => {
+    const a = adapter();
+    const r = a.parseInbound(withHeaders(SECRET, fixture("edited_message"))) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r.kind).toBe("event");
+    expect(r.event.idempotencyKey).toBe("100004");
+    expect(r.event.text).toBe("hello bot (edited)");
+  });
+
+  test("callback_query → event whose text is the callback `data`", () => {
+    const a = adapter();
+    const r = a.parseInbound(withHeaders(SECRET, fixture("callback_query"))) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r.kind).toBe("event");
+    expect(r.event.text).toBe("approve:123");
+    expect(r.event.idempotencyKey).toBe("100005");
+  });
+
+  test("bot_mention with mention entity → subtype app_mention", () => {
+    const a = adapter();
+    const r = a.parseInbound(withHeaders(SECRET, fixture("bot_mention"))) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r.event.subtype).toBe("app_mention");
+  });
+
+  test("sticker_only (no text/caption) → skip", () => {
+    const a = adapter();
+    expect(a.parseInbound(withHeaders(SECRET, fixture("sticker_only"))).kind).toBe("skip");
+  });
+
+  test("photo_with_caption → event with caption as text", () => {
+    const a = adapter();
+    const r = a.parseInbound(withHeaders(SECRET, fixture("photo_with_caption"))) as Extract<
+      ParsedInbound,
+      { kind: "event" }
+    >;
+    expect(r.event.text).toBe("look at this graph");
+  });
+
+  test("bot_self matching selfBotId → skip", () => {
+    const a = adapter();
+    expect(a.parseInbound(withHeaders(SECRET, fixture("bot_self"))).kind).toBe("skip");
+  });
+
+  test("missing_chat → skip", () => {
+    const a = adapter();
+    expect(a.parseInbound(withHeaders(SECRET, fixture("missing_chat"))).kind).toBe("skip");
+  });
+
+  test("non_message_update (poll) → skip", () => {
+    const a = adapter();
+    expect(a.parseInbound(withHeaders(SECRET, fixture("non_message_update"))).kind).toBe("skip");
+  });
+
+  test("malformed JSON body → skip", () => {
+    const a = adapter();
+    expect(a.parseInbound(withHeaders(SECRET, "{not-json")).kind).toBe("skip");
+  });
+
+  test("empty body → skip", () => {
+    const a = adapter();
+    expect(a.parseInbound(withHeaders(SECRET, "null")).kind).toBe("skip");
+  });
+});
+
+describe("sendReply / setTyping (T3)", () => {
+  function captureFetch() {
+    const calls: Array<{ url: string; init: RequestInit }> = [];
+    const f = (async (input: string | Request | URL, init?: RequestInit) => {
+      calls.push({ url: String(input), init: init ?? {} });
+      return new Response(JSON.stringify({ ok: true, result: { message_id: 999 } }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      });
+    }) as unknown as typeof fetch;
+    return { calls, fetch: f };
+  }
+
+  const event: InboundEvent = {
+    idempotencyKey: "100001",
+    workspaceId: "4242",
+    channelId: "4242",
+    userId: "4242",
+    ts: "7",
+    text: "hello",
+    subtype: "message",
+  };
+
+  test("sendReply POSTs sendMessage with correct chat_id + text", async () => {
+    const { calls, fetch: f } = captureFetch();
+    const a = createTelegramAdapter(
+      { botToken: BOT_TOKEN, secretToken: SECRET },
+      { apiBaseUrl: "https://test.telegram.local", fetch: f },
+    );
+    await a.sendReply({ event, text: "hi back" });
+    expect(calls.length).toBe(1);
+    expect(calls[0]?.url).toBe(`https://test.telegram.local/bot${BOT_TOKEN}/sendMessage`);
+    const body = JSON.parse(String(calls[0]?.init.body));
+    expect(body.chat_id).toBe(4242);
+    expect(body.text).toBe("hi back");
+    expect(body.message_thread_id).toBeUndefined();
+  });
+
+  test("sendReply forwards message_thread_id when threadTs set", async () => {
+    const { calls, fetch: f } = captureFetch();
+    const a = createTelegramAdapter(
+      { botToken: BOT_TOKEN, secretToken: SECRET },
+      { apiBaseUrl: "https://test.telegram.local", fetch: f },
+    );
+    await a.sendReply({
+      event: { ...event, threadTs: "17", channelId: "4242:17" },
+      text: "topic reply",
+    });
+    const body = JSON.parse(String(calls[0]?.init.body));
+    expect(body.message_thread_id).toBe(17);
+  });
+
+  test("sendReply throws on HTTP error", async () => {
+    const f = (async () =>
+      new Response("boom", { status: 502, statusText: "Bad Gateway" })) as unknown as typeof fetch;
+    const a = createTelegramAdapter(
+      { botToken: BOT_TOKEN, secretToken: SECRET },
+      { apiBaseUrl: "https://test.telegram.local", fetch: f },
+    );
+    await expect(a.sendReply({ event, text: "x" })).rejects.toThrow(TelegramAdapterError);
+  });
+
+  test("sendReply throws on Telegram-side ok:false", async () => {
+    const f = (async () =>
+      new Response(JSON.stringify({ ok: false, description: "chat not found" }), {
+        status: 200,
+        headers: { "content-type": "application/json" },
+      })) as unknown as typeof fetch;
+    const a = createTelegramAdapter(
+      { botToken: BOT_TOKEN, secretToken: SECRET },
+      { apiBaseUrl: "https://test.telegram.local", fetch: f },
+    );
+    await expect(a.sendReply({ event, text: "x" })).rejects.toThrow(/chat not found/);
+  });
+
+  test("sendReply rejects malformed workspaceId", async () => {
+    const a = adapter();
+    await expect(
+      a.sendReply({ event: { ...event, workspaceId: "not-a-number" }, text: "x" }),
+    ).rejects.toThrow(/invalid workspaceId/);
+  });
+
+  test("setTyping POSTs sendChatAction with action=typing", async () => {
+    const { calls, fetch: f } = captureFetch();
+    const a = createTelegramAdapter(
+      { botToken: BOT_TOKEN, secretToken: SECRET },
+      { apiBaseUrl: "https://test.telegram.local", fetch: f },
+    );
+    await a.setTyping({ event });
+    expect(calls.length).toBe(1);
+    expect(calls[0]?.url).toBe(`https://test.telegram.local/bot${BOT_TOKEN}/sendChatAction`);
+    const body = JSON.parse(String(calls[0]?.init.body));
+    expect(body.chat_id).toBe(4242);
+    expect(body.action).toBe("typing");
+  });
+});

package/src/index.ts

@@ -0,0 +1,289 @@
+/**
+ * @crewhaus/channel-adapter-telegram — Telegram channel adapter for the
+ * channel target (Section 33).
+ *
+ * Implements the same `ChannelAdapter` contract used by
+ * @crewhaus/channel-adapter-slack — verify(), parseInbound(), sendReply(),
+ * setTyping(). The Section 12 daemon registers this adapter alongside
+ * Slack and any other channel adapter, with the gateway dispatching
+ * inbound webhooks to whichever adapter id matches.
+ *
+ * Verification: `X-Telegram-Bot-Api-Secret-Token` header (set via
+ * `setWebhook(secret_token=...)`) compared timing-safely to the configured
+ * secret. Telegram does NOT sign the body — the secret token alone
+ * authenticates.
+ *
+ * Parse: handles `message`, `edited_message`, and `callback_query`
+ * (button-press) Update payloads. Group-chat session keying uses
+ * `<chatId>:<topicId>` when topics are enabled (chat type "supergroup"
+ * with `message_thread_id` present); otherwise just `<chatId>`.
+ *
+ * sendReply: POST to `https://api.telegram.org/bot<token>/sendMessage`.
+ * setTyping: POST `sendChatAction` with `action=typing`.
+ */
+import { CrewhausError } from "@crewhaus/errors";
+import { verifyTelegramSecret } from "./verify.js";
+
+export { verifyTelegramSecret } from "./verify.js";
+
+export class TelegramAdapterError extends CrewhausError {
+  override readonly name = "TelegramAdapterError";
+  constructor(message: string, cause?: unknown) {
+    super("channel", message, cause);
+  }
+}
+
+export type RawRequest = {
+  readonly headers: Headers;
+  readonly body: string;
+};
+
+/**
+ * Channel-generic inbound event. Same shape as the Slack adapter's
+ * `InboundEvent` so the gateway and session-router stay channel-agnostic.
+ *
+ * Mappings:
+ *   - workspaceId   → chat.id (Telegram has no "workspace"; we reuse the
+ *                     field for chat-level grouping)
+ *   - channelId     → chat.id : topicId (group-chat thread scope) or
+ *                     chat.id alone for private/group chats
+ *   - userId        → from.id (numeric, stringified)
+ *   - threadTs      → message_thread_id when present
+ *   - ts            → message_id (stringified) — monotonic per chat
+ *   - text          → message.text or callback_query.data
+ *   - subtype       → "message" | "app_mention"
+ *   - idempotencyKey → update_id (stringified)
+ */
+export type InboundEvent = {
+  readonly idempotencyKey: string;
+  readonly workspaceId: string;
+  readonly channelId: string;
+  readonly userId: string;
+  readonly threadTs?: string;
+  readonly ts: string;
+  readonly text: string;
+  readonly subtype: "app_mention" | "message";
+};
+
+export type ParsedInbound =
+  | { readonly kind: "event"; readonly event: InboundEvent }
+  | { readonly kind: "skip" };
+
+export interface ChannelAdapter {
+  readonly id: string;
+  verify(req: RawRequest): boolean;
+  parseInbound(req: RawRequest): ParsedInbound;
+  sendReply(args: { event: InboundEvent; text: string }): Promise<void>;
+  setTyping(args: { event: InboundEvent }): Promise<void>;
+}
+
+export type TelegramAdapterConfig = {
+  readonly botToken: string;
+  readonly secretToken: string;
+};
+
+export type TelegramAdapterOptions = {
+  readonly apiBaseUrl?: string;
+  readonly fetch?: typeof fetch;
+  readonly selfBotId?: string;
+};
+
+const DEFAULT_API_BASE_URL = "https://api.telegram.org";
+
+export function createTelegramAdapter(
+  config: TelegramAdapterConfig,
+  opts: TelegramAdapterOptions = {},
+): ChannelAdapter {
+  const apiBaseUrl =
+    opts.apiBaseUrl ?? process.env["TELEGRAM_API_BASE_URL"] ?? DEFAULT_API_BASE_URL;
+  const doFetch = opts.fetch ?? fetch;
+  const botEndpoint = (method: string) => `${apiBaseUrl}/bot${config.botToken}/${method}`;
+
+  function inboundFromMessage(
+    update: TelegramUpdate,
+    msg: TelegramMessage,
+    subtype: "message" | "app_mention",
+  ): ParsedInbound {
+    const chatId = msg.chat?.id;
+    const userId = msg.from?.id;
+    const text = msg.text ?? msg.caption ?? "";
+    if (chatId === undefined || userId === undefined) return { kind: "skip" };
+    if (
+      opts.selfBotId !== undefined &&
+      msg.from?.is_bot &&
+      String(msg.from.id) === opts.selfBotId
+    ) {
+      return { kind: "skip" };
+    }
+    const threadId = msg.message_thread_id;
+    const channelId = threadId !== undefined ? `${chatId}:${threadId}` : String(chatId);
+    const event: InboundEvent = {
+      idempotencyKey: String(update.update_id),
+      workspaceId: String(chatId),
+      channelId,
+      userId: String(userId),
+      ...(threadId !== undefined ? { threadTs: String(threadId) } : {}),
+      ts: String(msg.message_id),
+      text,
+      subtype,
+    };
+    return { kind: "event", event };
+  }
+
+  return {
+    id: "telegram",
+
+    verify(req: RawRequest): boolean {
+      return verifyTelegramSecret({ headers: req.headers, secretToken: config.secretToken });
+    },
+
+    parseInbound(req: RawRequest): ParsedInbound {
+      let payload: unknown;
+      try {
+        payload = JSON.parse(req.body);
+      } catch {
+        return { kind: "skip" };
+      }
+      if (typeof payload !== "object" || payload === null) return { kind: "skip" };
+      const update = payload as TelegramUpdate;
+      if (typeof update.update_id !== "number") return { kind: "skip" };
+
+      // Determine which slot is populated. Telegram updates are mutually
+      // exclusive over message / edited_message / channel_post / callback_query.
+      if (update.message) {
+        const msg = update.message;
+        // Skip empty messages (sticker-only / photo-only / system messages)
+        if (!msg.text && !msg.caption) return { kind: "skip" };
+        // Detect bot mention via entities (`type: "mention"` or `type: "bot_command"`).
+        const isMention =
+          msg.entities?.some((e) => e.type === "mention" || e.type === "bot_command") ?? false;
+        return inboundFromMessage(update, msg, isMention ? "app_mention" : "message");
+      }
+
+      if (update.edited_message) {
+        // Treat edits as new inbound events (gateway dedups on update_id).
+        const msg = update.edited_message;
+        if (!msg.text && !msg.caption) return { kind: "skip" };
+        return inboundFromMessage(update, msg, "message");
+      }
+
+      if (update.callback_query) {
+        const cq = update.callback_query;
+        const msg = cq.message;
+        const userId = cq.from?.id;
+        const data = cq.data ?? "";
+        if (!msg || userId === undefined) return { kind: "skip" };
+        const chatId = msg.chat?.id;
+        if (chatId === undefined) return { kind: "skip" };
+        const threadId = msg.message_thread_id;
+        const channelId = threadId !== undefined ? `${chatId}:${threadId}` : String(chatId);
+        const event: InboundEvent = {
+          idempotencyKey: String(update.update_id),
+          workspaceId: String(chatId),
+          channelId,
+          userId: String(userId),
+          ...(threadId !== undefined ? { threadTs: String(threadId) } : {}),
+          ts: String(msg.message_id),
+          text: data,
+          subtype: "message",
+        };
+        return { kind: "event", event };
+      }
+
+      return { kind: "skip" };
+    },
+
+    async sendReply(args: { event: InboundEvent; text: string }): Promise<void> {
+      const url = botEndpoint("sendMessage");
+      // Reconstruct chat_id from the workspaceId field (always the raw chat.id).
+      const chatId = Number.parseInt(args.event.workspaceId, 10);
+      if (!Number.isFinite(chatId)) {
+        throw new TelegramAdapterError(`invalid workspaceId in event: ${args.event.workspaceId}`);
+      }
+      const body: Record<string, unknown> = {
+        chat_id: chatId,
+        text: args.text,
+      };
+      const threadId = args.event.threadTs;
+      if (threadId) {
+        body["message_thread_id"] = Number.parseInt(threadId, 10);
+      }
+      const res = await doFetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+      });
+      if (!res.ok) {
+        throw new TelegramAdapterError(`sendMessage failed: ${res.status} ${res.statusText}`);
+      }
+      const ct = res.headers.get("content-type") ?? "";
+      if (ct.includes("application/json")) {
+        const json = (await res.json()) as { ok?: boolean; description?: string };
+        if (json.ok === false) {
+          throw new TelegramAdapterError(`sendMessage error: ${json.description ?? "unknown"}`);
+        }
+      }
+    },
+
+    async setTyping(args: { event: InboundEvent }): Promise<void> {
+      const url = botEndpoint("sendChatAction");
+      const chatId = Number.parseInt(args.event.workspaceId, 10);
+      if (!Number.isFinite(chatId)) {
+        throw new TelegramAdapterError(`invalid workspaceId in event: ${args.event.workspaceId}`);
+      }
+      const body: Record<string, unknown> = { chat_id: chatId, action: "typing" };
+      if (args.event.threadTs) {
+        body["message_thread_id"] = Number.parseInt(args.event.threadTs, 10);
+      }
+      await doFetch(url, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+      });
+      // setTyping is best-effort; a non-200 here should not fail the run.
+    },
+  };
+}
+
+// ─── Telegram Bot API minimal types (no SDK dep) ─────────────────────────────
+
+export type TelegramUpdate = {
+  readonly update_id: number;
+  readonly message?: TelegramMessage;
+  readonly edited_message?: TelegramMessage;
+  readonly callback_query?: TelegramCallbackQuery;
+};
+
+export type TelegramMessage = {
+  readonly message_id: number;
+  readonly from?: TelegramUser;
+  readonly chat: TelegramChat;
+  readonly text?: string;
+  readonly caption?: string;
+  readonly message_thread_id?: number;
+  readonly entities?: ReadonlyArray<TelegramMessageEntity>;
+};
+
+export type TelegramUser = {
+  readonly id: number;
+  readonly is_bot?: boolean;
+  readonly username?: string;
+};
+
+export type TelegramChat = {
+  readonly id: number;
+  readonly type?: "private" | "group" | "supergroup" | "channel";
+};
+
+export type TelegramMessageEntity = {
+  readonly type: string;
+  readonly offset?: number;
+  readonly length?: number;
+};
+
+export type TelegramCallbackQuery = {
+  readonly id: string;
+  readonly from: TelegramUser;
+  readonly data?: string;
+  readonly message?: TelegramMessage;
+};

package/src/verify.ts

@@ -0,0 +1,29 @@
+import { timingSafeEqual } from "node:crypto";
+
+/**
+ * Telegram webhook verification.
+ *
+ * Telegram authenticates webhooks by sending the secret token (configured
+ * via `setWebhook(secret_token=...)` on the Bot API) in the
+ * `X-Telegram-Bot-Api-Secret-Token` header on every POST. We compare it
+ * to the secret we hold using `timingSafeEqual` to avoid nibble-leak
+ * side channels.
+ *
+ * Telegram does not sign the body, so there is no replay-window check
+ * (the secret token alone authenticates). The Bot API secret is
+ * 1–256 chars, A–Z / a–z / 0–9 / _ / -.
+ */
+export type TelegramVerifyArgs = {
+  readonly headers: Headers;
+  readonly secretToken: string;
+};
+
+export function verifyTelegramSecret(args: TelegramVerifyArgs): boolean {
+  const supplied = args.headers.get("x-telegram-bot-api-secret-token");
+  if (!supplied) return false;
+  if (supplied.length !== args.secretToken.length) return false;
+  const a = Buffer.from(supplied, "utf8");
+  const b = Buffer.from(args.secretToken, "utf8");
+  if (a.length !== b.length) return false;
+  return timingSafeEqual(a, b);
+}