@poncho-ai/messaging 0.2.8 → 0.3.0

package/src/adapters/telegram/index.ts

@@ -0,0 +1,344 @@
+import type http from "node:http";
+import type {
+  FileAttachment,
+  IncomingMessage as PonchoIncomingMessage,
+  IncomingMessageHandler,
+  MessagingAdapter,
+  RouteRegistrar,
+  ThreadRef,
+} from "../../types.js";
+import { verifyTelegramSecret } from "./verify.js";
+import {
+  type TelegramMessage,
+  type TelegramUpdate,
+  downloadFile,
+  getFile,
+  getMe,
+  isBotMentioned,
+  sendChatAction,
+  sendDocument,
+  sendMessage,
+  sendPhoto,
+  splitMessage,
+  stripMention,
+} from "./utils.js";
+
+const TYPING_INTERVAL_MS = 4_000;
+const NEW_COMMAND_RE = /^\/new(?:@(\S+))?$/i;
+
+export interface TelegramAdapterOptions {
+  botTokenEnv?: string;
+  webhookSecretEnv?: string;
+}
+
+const collectBody = (req: http.IncomingMessage): Promise<string> =>
+  new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on("data", (chunk: Buffer) => chunks.push(chunk));
+    req.on("end", () => resolve(Buffer.concat(chunks).toString("utf8")));
+    req.on("error", reject);
+  });
+
+export class TelegramAdapter implements MessagingAdapter {
+  readonly platform = "telegram" as const;
+  readonly autoReply = true;
+  readonly hasSentInCurrentRequest = false;
+
+  private botToken = "";
+  private webhookSecret = "";
+  private botUsername = "";
+  private botId = 0;
+  private readonly botTokenEnv: string;
+  private readonly webhookSecretEnv: string;
+  private handler: IncomingMessageHandler | undefined;
+  private readonly sessionCounters = new Map<string, number>();
+  private lastUpdateId = 0;
+
+  constructor(options: TelegramAdapterOptions = {}) {
+    this.botTokenEnv = options.botTokenEnv ?? "TELEGRAM_BOT_TOKEN";
+    this.webhookSecretEnv =
+      options.webhookSecretEnv ?? "TELEGRAM_WEBHOOK_SECRET";
+  }
+
+  // -----------------------------------------------------------------------
+  // MessagingAdapter implementation
+  // -----------------------------------------------------------------------
+
+  async initialize(): Promise<void> {
+    this.botToken = process.env[this.botTokenEnv] ?? "";
+    this.webhookSecret = process.env[this.webhookSecretEnv] ?? "";
+
+    if (!this.botToken) {
+      throw new Error(
+        `Telegram messaging: ${this.botTokenEnv} environment variable is not set`,
+      );
+    }
+
+    const me = await getMe(this.botToken);
+    this.botUsername = me.username;
+    this.botId = me.id;
+  }
+
+  onMessage(handler: IncomingMessageHandler): void {
+    this.handler = handler;
+  }
+
+  registerRoutes(router: RouteRegistrar): void {
+    router("POST", "/api/messaging/telegram", (req, res) =>
+      this.handleRequest(req, res),
+    );
+  }
+
+  async sendReply(
+    threadRef: ThreadRef,
+    content: string,
+    options?: { files?: FileAttachment[] },
+  ): Promise<void> {
+    const chatId = threadRef.channelId;
+    const replyTo = threadRef.messageId
+      ? Number(threadRef.messageId)
+      : undefined;
+
+    if (content) {
+      const chunks = splitMessage(content);
+      for (const chunk of chunks) {
+        await sendMessage(this.botToken, chatId, chunk, {
+          reply_to_message_id: replyTo,
+        });
+      }
+    }
+
+    if (options?.files) {
+      for (const file of options.files) {
+        if (file.mediaType.startsWith("image/")) {
+          await sendPhoto(this.botToken, chatId, file.data, {
+            reply_to_message_id: replyTo,
+            filename: file.filename,
+          });
+        } else {
+          await sendDocument(this.botToken, chatId, file.data, {
+            reply_to_message_id: replyTo,
+            filename: file.filename,
+            mediaType: file.mediaType,
+          });
+        }
+      }
+    }
+  }
+
+  async indicateProcessing(
+    threadRef: ThreadRef,
+  ): Promise<() => Promise<void>> {
+    const chatId = threadRef.channelId;
+
+    await sendChatAction(this.botToken, chatId, "typing");
+
+    const interval = setInterval(() => {
+      void sendChatAction(this.botToken, chatId, "typing").catch(() => {});
+    }, TYPING_INTERVAL_MS);
+
+    return async () => {
+      clearInterval(interval);
+    };
+  }
+
+  // -----------------------------------------------------------------------
+  // HTTP request handling
+  // -----------------------------------------------------------------------
+
+  private async handleRequest(
+    req: http.IncomingMessage,
+    res: http.ServerResponse,
+  ): Promise<void> {
+    const rawBody = await collectBody(req);
+
+    // -- Secret verification ----------------------------------------------
+    if (this.webhookSecret) {
+      const headerSecret = req.headers[
+        "x-telegram-bot-api-secret-token"
+      ] as string | undefined;
+      if (!verifyTelegramSecret(this.webhookSecret, headerSecret)) {
+        res.writeHead(401);
+        res.end("Invalid secret");
+        return;
+      }
+    }
+
+    let payload: TelegramUpdate;
+    try {
+      payload = JSON.parse(rawBody) as TelegramUpdate;
+    } catch {
+      res.writeHead(400);
+      res.end("Invalid JSON");
+      return;
+    }
+
+    // -- Update deduplication -----------------------------------------------
+    if (payload.update_id <= this.lastUpdateId) {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+    this.lastUpdateId = payload.update_id;
+
+    const message = payload.message;
+    if (!message) {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+
+    const text = message.text ?? message.caption ?? "";
+    const hasFiles = !!(message.photo || message.document);
+
+    if (!text && !hasFiles) {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+
+    const chatId = String(message.chat.id);
+    const chatType = message.chat.type;
+    const isGroup = chatType === "group" || chatType === "supergroup";
+    const entities = message.entities ?? message.caption_entities;
+
+    // -- /new command -----------------------------------------------------
+    const newMatch = text.match(NEW_COMMAND_RE);
+    if (newMatch) {
+      const suffix = newMatch[1];
+      if (
+        isGroup &&
+        suffix &&
+        suffix.toLowerCase() !== this.botUsername.toLowerCase()
+      ) {
+        res.writeHead(200);
+        res.end();
+        return;
+      }
+
+      const key = this.sessionKey(message);
+      const current = this.sessionCounters.get(key) ?? 0;
+      this.sessionCounters.set(key, current + 1);
+
+      res.writeHead(200);
+      res.end();
+
+      await sendMessage(
+        this.botToken,
+        chatId,
+        "Conversation reset. Send a new message to start fresh.",
+        {
+          reply_to_message_id: message.message_id,
+          message_thread_id: message.message_thread_id,
+        },
+      );
+      return;
+    }
+
+    // -- Group mention filter ---------------------------------------------
+    if (isGroup) {
+      if (!isBotMentioned(entities, this.botUsername, this.botId, text)) {
+        res.writeHead(200);
+        res.end();
+        return;
+      }
+    }
+
+    const cleanText = isGroup
+      ? stripMention(text, entities, this.botUsername, this.botId)
+      : text;
+
+    if (!cleanText && !hasFiles) {
+      res.writeHead(200);
+      res.end();
+      return;
+    }
+
+    // Acknowledge immediately so Telegram doesn't retry.
+    res.writeHead(200);
+    res.end();
+
+    if (!this.handler) return;
+
+    // -- File extraction --------------------------------------------------
+    const files = await this.extractFiles(message);
+
+    // -- Build thread ref -------------------------------------------------
+    const key = this.sessionKey(message);
+    const session = this.sessionCounters.get(key) ?? 0;
+    const topicId = message.message_thread_id;
+    const platformThreadId = topicId
+      ? `${chatId}:${topicId}:${session}`
+      : `${chatId}:${session}`;
+
+    const userId = String(message.from?.id ?? "unknown");
+    const userName =
+      [message.from?.first_name, message.from?.last_name]
+        .filter(Boolean)
+        .join(" ") || undefined;
+
+    const ponchoMessage: PonchoIncomingMessage = {
+      text: cleanText,
+      files: files.length > 0 ? files : undefined,
+      threadRef: {
+        platformThreadId,
+        channelId: chatId,
+        messageId: String(message.message_id),
+      },
+      sender: { id: userId, name: userName },
+      platform: "telegram",
+      raw: message,
+    };
+
+    void this.handler(ponchoMessage).catch((err) => {
+      console.error(
+        "[telegram-adapter] unhandled message handler error",
+        err,
+      );
+    });
+  }
+
+  // -----------------------------------------------------------------------
+  // Helpers
+  // -----------------------------------------------------------------------
+
+  private sessionKey(message: TelegramMessage): string {
+    const chatId = String(message.chat.id);
+    return message.message_thread_id
+      ? `${chatId}:${message.message_thread_id}`
+      : chatId;
+  }
+
+  private async extractFiles(
+    message: TelegramMessage,
+  ): Promise<FileAttachment[]> {
+    const files: FileAttachment[] = [];
+    try {
+      if (message.photo && message.photo.length > 0) {
+        const largest = message.photo[message.photo.length - 1]!;
+        const filePath = await getFile(this.botToken, largest.file_id);
+        const { data } = await downloadFile(this.botToken, filePath);
+        files.push({ data, mediaType: "image/jpeg", filename: "photo.jpg" });
+      }
+
+      if (message.document) {
+        const filePath = await getFile(
+          this.botToken,
+          message.document.file_id,
+        );
+        const downloaded = await downloadFile(this.botToken, filePath);
+        files.push({
+          data: downloaded.data,
+          mediaType: message.document.mime_type ?? downloaded.mediaType,
+          filename: message.document.file_name,
+        });
+      }
+    } catch (err) {
+      console.warn(
+        "[telegram-adapter] failed to download file:",
+        err instanceof Error ? err.message : err,
+      );
+    }
+    return files;
+  }
+}

package/src/adapters/telegram/utils.ts

@@ -0,0 +1,369 @@
+const TELEGRAM_API = "https://api.telegram.org";
+const TELEGRAM_MAX_MESSAGE_LENGTH = 4096;
+
+// ---------------------------------------------------------------------------
+// Telegram Bot API object types (subset used by the adapter)
+// ---------------------------------------------------------------------------
+
+export interface TelegramEntity {
+  type: string;
+  offset: number;
+  length: number;
+  user?: { id: number; username?: string };
+}
+
+export interface TelegramUser {
+  id: number;
+  is_bot: boolean;
+  first_name: string;
+  last_name?: string;
+  username?: string;
+}
+
+export interface TelegramChat {
+  id: number;
+  type: "private" | "group" | "supergroup" | "channel";
+}
+
+export interface TelegramPhotoSize {
+  file_id: string;
+  file_unique_id: string;
+  width: number;
+  height: number;
+  file_size?: number;
+}
+
+export interface TelegramDocument {
+  file_id: string;
+  file_unique_id: string;
+  file_name?: string;
+  mime_type?: string;
+  file_size?: number;
+}
+
+export interface TelegramMessage {
+  message_id: number;
+  from?: TelegramUser;
+  chat: TelegramChat;
+  date: number;
+  text?: string;
+  caption?: string;
+  entities?: TelegramEntity[];
+  caption_entities?: TelegramEntity[];
+  photo?: TelegramPhotoSize[];
+  document?: TelegramDocument;
+  message_thread_id?: number;
+}
+
+export interface TelegramUpdate {
+  update_id: number;
+  message?: TelegramMessage;
+}
+
+// ---------------------------------------------------------------------------
+// Low-level fetch helpers
+// ---------------------------------------------------------------------------
+
+interface TelegramApiResult {
+  ok: boolean;
+  result?: unknown;
+  description?: string;
+}
+
+const telegramFetch = async (
+  token: string,
+  method: string,
+  body: Record<string, unknown>,
+): Promise<TelegramApiResult> => {
+  const res = await fetch(`${TELEGRAM_API}/bot${token}/${method}`, {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  return (await res.json()) as TelegramApiResult;
+};
+
+const telegramUpload = async (
+  token: string,
+  method: string,
+  formData: FormData,
+): Promise<TelegramApiResult> => {
+  const res = await fetch(`${TELEGRAM_API}/bot${token}/${method}`, {
+    method: "POST",
+    body: formData,
+  });
+  return (await res.json()) as TelegramApiResult;
+};
+
+// ---------------------------------------------------------------------------
+// Bot info
+// ---------------------------------------------------------------------------
+
+export const getMe = async (
+  token: string,
+): Promise<{ id: number; username: string }> => {
+  const result = await telegramFetch(token, "getMe", {});
+  if (!result.ok) {
+    throw new Error(`Telegram getMe failed: ${result.description}`);
+  }
+  const user = result.result as TelegramUser;
+  return { id: user.id, username: user.username ?? "" };
+};
+
+// ---------------------------------------------------------------------------
+// File download
+// ---------------------------------------------------------------------------
+
+export const getFile = async (
+  token: string,
+  fileId: string,
+): Promise<string> => {
+  const result = await telegramFetch(token, "getFile", { file_id: fileId });
+  if (!result.ok) {
+    throw new Error(`Telegram getFile failed: ${result.description}`);
+  }
+  const file = result.result as { file_id: string; file_path?: string };
+  if (!file.file_path) {
+    throw new Error("Telegram getFile: no file_path returned");
+  }
+  return file.file_path;
+};
+
+const EXTENSION_MEDIA_TYPES: Record<string, string> = {
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  png: "image/png",
+  gif: "image/gif",
+  webp: "image/webp",
+  pdf: "application/pdf",
+  mp4: "video/mp4",
+  ogg: "audio/ogg",
+  mp3: "audio/mpeg",
+};
+
+const inferMediaType = (filePath: string, header: string | null): string => {
+  if (header && header !== "application/octet-stream") return header;
+  const ext = filePath.split(".").pop()?.toLowerCase();
+  if (ext && EXTENSION_MEDIA_TYPES[ext]) return EXTENSION_MEDIA_TYPES[ext];
+  return header ?? "application/octet-stream";
+};
+
+export const downloadFile = async (
+  token: string,
+  filePath: string,
+): Promise<{ data: string; mediaType: string }> => {
+  const url = `${TELEGRAM_API}/file/bot${token}/${filePath}`;
+  const res = await fetch(url);
+  if (!res.ok) {
+    throw new Error(`Telegram file download failed: ${res.status}`);
+  }
+  const buffer = Buffer.from(await res.arrayBuffer());
+  const mediaType = inferMediaType(filePath, res.headers.get("content-type"));
+  return { data: buffer.toString("base64"), mediaType };
+};
+
+// ---------------------------------------------------------------------------
+// Sending messages
+// ---------------------------------------------------------------------------
+
+export const sendMessage = async (
+  token: string,
+  chatId: number | string,
+  text: string,
+  opts?: { reply_to_message_id?: number; message_thread_id?: number },
+): Promise<void> => {
+  const body: Record<string, unknown> = { chat_id: chatId, text };
+  if (opts?.reply_to_message_id) {
+    body.reply_parameters = {
+      message_id: opts.reply_to_message_id,
+      allow_sending_without_reply: true,
+    };
+  }
+  if (opts?.message_thread_id) {
+    body.message_thread_id = opts.message_thread_id;
+  }
+  const result = await telegramFetch(token, "sendMessage", body);
+  if (!result.ok) {
+    throw new Error(`Telegram sendMessage failed: ${result.description}`);
+  }
+};
+
+export const sendPhoto = async (
+  token: string,
+  chatId: number | string,
+  photoData: string,
+  opts?: {
+    caption?: string;
+    reply_to_message_id?: number;
+    message_thread_id?: number;
+    filename?: string;
+  },
+): Promise<void> => {
+  const formData = new FormData();
+  formData.append("chat_id", String(chatId));
+  const blob = new Blob([Buffer.from(photoData, "base64")]);
+  formData.append("photo", blob, opts?.filename ?? "photo.jpg");
+  if (opts?.caption) formData.append("caption", opts.caption);
+  if (opts?.reply_to_message_id) {
+    formData.append(
+      "reply_parameters",
+      JSON.stringify({
+        message_id: opts.reply_to_message_id,
+        allow_sending_without_reply: true,
+      }),
+    );
+  }
+  if (opts?.message_thread_id) {
+    formData.append("message_thread_id", String(opts.message_thread_id));
+  }
+  const result = await telegramUpload(token, "sendPhoto", formData);
+  if (!result.ok) {
+    throw new Error(`Telegram sendPhoto failed: ${result.description}`);
+  }
+};
+
+export const sendDocument = async (
+  token: string,
+  chatId: number | string,
+  docData: string,
+  opts?: {
+    caption?: string;
+    reply_to_message_id?: number;
+    message_thread_id?: number;
+    filename?: string;
+    mediaType?: string;
+  },
+): Promise<void> => {
+  const formData = new FormData();
+  formData.append("chat_id", String(chatId));
+  const blob = new Blob([Buffer.from(docData, "base64")], {
+    type: opts?.mediaType,
+  });
+  formData.append("document", blob, opts?.filename ?? "file");
+  if (opts?.caption) formData.append("caption", opts.caption);
+  if (opts?.reply_to_message_id) {
+    formData.append(
+      "reply_parameters",
+      JSON.stringify({
+        message_id: opts.reply_to_message_id,
+        allow_sending_without_reply: true,
+      }),
+    );
+  }
+  if (opts?.message_thread_id) {
+    formData.append("message_thread_id", String(opts.message_thread_id));
+  }
+  const result = await telegramUpload(token, "sendDocument", formData);
+  if (!result.ok) {
+    throw new Error(`Telegram sendDocument failed: ${result.description}`);
+  }
+};
+
+// ---------------------------------------------------------------------------
+// Typing indicator
+// ---------------------------------------------------------------------------
+
+export const sendChatAction = async (
+  token: string,
+  chatId: number | string,
+  action: string,
+): Promise<void> => {
+  await telegramFetch(token, "sendChatAction", {
+    chat_id: chatId,
+    action,
+  });
+};
+
+// ---------------------------------------------------------------------------
+// Message splitting (same pattern as Slack, adapted for 4096 limit)
+// ---------------------------------------------------------------------------
+
+export const splitMessage = (text: string): string[] => {
+  if (text.length <= TELEGRAM_MAX_MESSAGE_LENGTH) return [text];
+
+  const chunks: string[] = [];
+  let remaining = text;
+
+  while (remaining.length > 0) {
+    if (remaining.length <= TELEGRAM_MAX_MESSAGE_LENGTH) {
+      chunks.push(remaining);
+      break;
+    }
+
+    let cutPoint = remaining.lastIndexOf(
+      "\n",
+      TELEGRAM_MAX_MESSAGE_LENGTH,
+    );
+    if (cutPoint <= 0) {
+      cutPoint = TELEGRAM_MAX_MESSAGE_LENGTH;
+    }
+
+    chunks.push(remaining.slice(0, cutPoint));
+    remaining = remaining.slice(cutPoint).replace(/^\n/, "");
+  }
+
+  return chunks;
+};
+
+// ---------------------------------------------------------------------------
+// Mention detection & stripping
+// ---------------------------------------------------------------------------
+
+/**
+ * Check whether the bot is mentioned in a message's entities.
+ * Works with both `@username` mentions and `text_mention` entities.
+ */
+export const isBotMentioned = (
+  entities: TelegramEntity[] | undefined,
+  botUsername: string,
+  botId: number,
+  text: string,
+): boolean => {
+  if (!entities || entities.length === 0) return false;
+  const lower = botUsername.toLowerCase();
+
+  for (const entity of entities) {
+    if (entity.type === "mention") {
+      const mentioned = text.slice(entity.offset, entity.offset + entity.length);
+      if (mentioned.toLowerCase() === `@${lower}`) return true;
+    }
+    if (entity.type === "text_mention" && entity.user?.id === botId) {
+      return true;
+    }
+  }
+
+  return false;
+};
+
+/**
+ * Remove the first bot mention from the message text, using entity
+ * offsets for accuracy. Falls back to regex if no entity matches.
+ */
+export const stripMention = (
+  text: string,
+  entities: TelegramEntity[] | undefined,
+  botUsername: string,
+  botId: number,
+): string => {
+  if (!entities || entities.length === 0) return text.trim();
+  const lower = botUsername.toLowerCase();
+
+  for (const entity of entities) {
+    let match = false;
+    if (entity.type === "mention") {
+      const mentioned = text.slice(entity.offset, entity.offset + entity.length);
+      if (mentioned.toLowerCase() === `@${lower}`) match = true;
+    }
+    if (entity.type === "text_mention" && entity.user?.id === botId) {
+      match = true;
+    }
+    if (match) {
+      return (
+        text.slice(0, entity.offset) +
+        text.slice(entity.offset + entity.length)
+      ).trim();
+    }
+  }
+
+  return text.trim();
+};