@chatman-media/channel-telegram 1.1.0

package/src/bot-api/client.ts

@@ -0,0 +1,275 @@
+import type { TgFile, TgReplyMarkup, TgSendMessageResult, TgUser } from "./types.ts";
+
+export type FetchLike = typeof fetch;
+
+export interface TelegramClientOptions {
+  token: string;
+  baseUrl?: string;
+  fetch?: FetchLike;
+}
+
+export class TelegramApiError extends Error {
+  constructor(
+    public method: string,
+    public statusCode: number,
+    public errorCode: number | undefined,
+    public description: string,
+  ) {
+    super(`Telegram ${method} failed (${statusCode}): ${description}`);
+    this.name = "TelegramApiError";
+  }
+}
+
+interface TgResponse<T> {
+  ok: boolean;
+  result?: T;
+  error_code?: number;
+  description?: string;
+}
+
+export class TelegramClient {
+  private readonly token: string;
+  private readonly baseUrl: string;
+  private readonly fetchImpl: FetchLike;
+
+  constructor(opts: TelegramClientOptions) {
+    if (!opts.token) throw new Error("TelegramClient: token is required");
+    this.token = opts.token;
+    this.baseUrl = opts.baseUrl ?? "https://api.telegram.org";
+    this.fetchImpl = opts.fetch ?? globalThis.fetch.bind(globalThis);
+  }
+
+  private async call<T>(method: string, params: Record<string, unknown>): Promise<T> {
+    const url = `${this.baseUrl}/bot${this.token}/${method}`;
+    const res = await this.fetchImpl(url, {
+      method: "POST",
+      headers: { "content-type": "application/json" },
+      body: JSON.stringify(params),
+    });
+    let body: TgResponse<T>;
+    try {
+      body = (await res.json()) as TgResponse<T>;
+    } catch {
+      throw new TelegramApiError(
+        method,
+        res.status,
+        undefined,
+        `non-JSON response (status ${res.status})`,
+      );
+    }
+    if (!res.ok || !body.ok || body.result === undefined) {
+      throw new TelegramApiError(
+        method,
+        res.status,
+        body.error_code,
+        body.description ?? "unknown error",
+      );
+    }
+    return body.result;
+  }
+
+  getMe(): Promise<TgUser> {
+    return this.call<TgUser>("getMe", {});
+  }
+
+  /**
+   * Resolve a file_id to a downloadable path. The path returned is
+   * appended to `<baseUrl>/file/bot<token>/...` (NOT the regular
+   * `<baseUrl>/bot<token>/...` API endpoint) — see `downloadFile` for
+   * the right URL shape.
+   */
+  getFile(fileId: string): Promise<TgFile> {
+    return this.call<TgFile>("getFile", { file_id: fileId });
+  }
+
+  /**
+   * Two-step download for any file_id we hold:
+   *   1. getFile → returns `file_path`
+   *   2. fetch the bytes from `<baseUrl>/file/bot<token>/<file_path>`
+   *
+   * Returns the raw `Response` so the admin layer can stream the body
+   * straight to the browser without buffering. Throws when the file is
+   * too large for the Bot Download API (Telegram's ~20 MB cap leaves
+   * `file_path` undefined).
+   *
+   * The token is held privately by the client — the admin endpoint
+   * proxies through this helper rather than getting the token directly,
+   * so secrets never leave the server.
+   */
+  async downloadFile(fileId: string): Promise<Response> {
+    const info = await this.getFile(fileId);
+    if (!info.file_path) {
+      throw new Error(`Telegram file ${fileId} has no file_path (too large?)`);
+    }
+    const url = `${this.baseUrl}/file/bot${this.token}/${info.file_path}`;
+    return this.fetchImpl(url);
+  }
+
+  sendMessage(input: {
+    chatId: number | string;
+    text: string;
+    parseMode?: "MarkdownV2" | "HTML" | "Markdown";
+    replyMarkup?: TgReplyMarkup;
+    disableWebPagePreview?: boolean;
+    replyToMessageId?: number;
+  }): Promise<TgSendMessageResult> {
+    const params: Record<string, unknown> = {
+      chat_id: input.chatId,
+      text: input.text,
+    };
+    if (input.parseMode) params.parse_mode = input.parseMode;
+    if (input.replyMarkup) params.reply_markup = input.replyMarkup;
+    if (input.disableWebPagePreview) params.disable_web_page_preview = input.disableWebPagePreview;
+    if (input.replyToMessageId !== undefined) params.reply_to_message_id = input.replyToMessageId;
+    return this.call<TgSendMessageResult>("sendMessage", params);
+  }
+
+  /**
+   * Re-send a photo by file_id. Used by the operator-relay path: when the
+   * operator uploads a photo to the ops chat as a reply to a lead card,
+   * the webhook hands the largest size's file_id straight to this method
+   * — Telegram is happy to re-deliver media we've already seen, no need
+   * to download and re-upload bytes.
+   */
+  sendPhoto(input: {
+    chatId: number | string;
+    photoFileId: string;
+    caption?: string;
+  }): Promise<TgSendMessageResult> {
+    const params: Record<string, unknown> = {
+      chat_id: input.chatId,
+      photo: input.photoFileId,
+    };
+    if (input.caption) params.caption = input.caption;
+    return this.call<TgSendMessageResult>("sendPhoto", params);
+  }
+
+  sendVideo(input: {
+    chatId: number | string;
+    videoFileId: string;
+    caption?: string;
+  }): Promise<TgSendMessageResult> {
+    const params: Record<string, unknown> = {
+      chat_id: input.chatId,
+      video: input.videoFileId,
+    };
+    if (input.caption) params.caption = input.caption;
+    return this.call<TgSendMessageResult>("sendVideo", params);
+  }
+
+  /**
+   * Send a video from a local file on disk (not a Telegram `file_id`).
+   * Bot API supports this via multipart upload, but our funnel goes through
+   * the userbot — implemented as a stub here so the symbol resolves; the
+   * real impl lives in `makeUserbotSender` in `userbot.ts` and uses gramjs
+   * `sendFile` under the hood.
+   */
+  sendLocalVideo(_input: {
+    chatId: number | string;
+    localFilePath: string;
+    caption?: string;
+  }): Promise<TgSendMessageResult> {
+    throw new Error("sendLocalVideo: Bot API path not implemented — userbot-only feature");
+  }
+
+  sendDocument(input: {
+    chatId: number | string;
+    documentFileId: string;
+    caption?: string;
+  }): Promise<TgSendMessageResult> {
+    const params: Record<string, unknown> = {
+      chat_id: input.chatId,
+      document: input.documentFileId,
+    };
+    if (input.caption) params.caption = input.caption;
+    return this.call<TgSendMessageResult>("sendDocument", params);
+  }
+
+  /**
+   * Edit a message we previously sent (commonly the lead card after the
+   * operator clicks approve/reject — the card stays in the ops chat with
+   * the new state visible). `text` replaces the body; `replyMarkup`
+   * replaces the inline keyboard (pass `{}` to remove the buttons
+   * entirely on a finalized state).
+   */
+  editMessageText(input: {
+    chatId: number | string;
+    messageId: number;
+    text: string;
+    parseMode?: "MarkdownV2" | "HTML" | "Markdown";
+    replyMarkup?: TgReplyMarkup;
+  }): Promise<TgSendMessageResult | true> {
+    const params: Record<string, unknown> = {
+      chat_id: input.chatId,
+      message_id: input.messageId,
+      text: input.text,
+    };
+    if (input.parseMode) params.parse_mode = input.parseMode;
+    if (input.replyMarkup) params.reply_markup = input.replyMarkup;
+    return this.call<TgSendMessageResult | true>("editMessageText", params);
+  }
+
+  /**
+   * Delete a message we previously sent. Used by the admin "delete message"
+   * action on the Bot-API channel. Telegram lets a bot delete its own
+   * outgoing messages in a private chat with no time limit.
+   */
+  deleteMessage(input: { chatId: number | string; messageId: number }): Promise<true> {
+    return this.call<true>("deleteMessage", {
+      chat_id: input.chatId,
+      message_id: input.messageId,
+    });
+  }
+
+  /**
+   * Acknowledge an inline-keyboard click. Telegram requires a response
+   * within a few seconds or the spinner on the user's button keeps
+   * rotating. Pass `text` to flash a small notification ("Approved!").
+   */
+  answerCallbackQuery(input: {
+    callbackQueryId: string;
+    text?: string;
+    showAlert?: boolean;
+  }): Promise<true> {
+    const params: Record<string, unknown> = {
+      callback_query_id: input.callbackQueryId,
+    };
+    if (input.text) params.text = input.text;
+    if (input.showAlert) params.show_alert = input.showAlert;
+    return this.call<true>("answerCallbackQuery", params);
+  }
+
+  sendChatAction(input: {
+    chatId: number | string;
+    action: "typing" | "upload_photo" | "record_video" | "upload_voice" | "upload_document";
+  }): Promise<true> {
+    return this.call<true>("sendChatAction", {
+      chat_id: input.chatId,
+      action: input.action,
+    });
+  }
+
+  setWebhook(input: {
+    url: string;
+    secretToken?: string;
+    allowedUpdates?: string[];
+    dropPendingUpdates?: boolean;
+  }): Promise<true> {
+    const params: Record<string, unknown> = { url: input.url };
+    if (input.secretToken) params.secret_token = input.secretToken;
+    if (input.allowedUpdates) params.allowed_updates = input.allowedUpdates;
+    if (input.dropPendingUpdates !== undefined)
+      params.drop_pending_updates = input.dropPendingUpdates;
+    return this.call<true>("setWebhook", params);
+  }
+
+  deleteWebhook(dropPending = false): Promise<true> {
+    return this.call<true>("deleteWebhook", {
+      drop_pending_updates: dropPending,
+    });
+  }
+
+  getWebhookInfo(): Promise<{ url: string; pending_update_count: number }> {
+    return this.call<{ url: string; pending_update_count: number }>("getWebhookInfo", {});
+  }
+}

package/src/bot-api/types.ts

@@ -0,0 +1,134 @@
+// Minimal subset of Telegram Bot API types we use.
+
+export interface TgUser {
+  id: number;
+  is_bot?: boolean;
+  first_name?: string;
+  last_name?: string;
+  username?: string;
+  language_code?: string;
+}
+
+export interface TgChat {
+  id: number;
+  type: "private" | "group" | "supergroup" | "channel";
+  title?: string;
+  username?: string;
+}
+
+/**
+ * One frame of a Telegram photo upload. Telegram delivers an array of
+ * sizes per photo (thumbnail / medium / original) — we record the
+ * largest for diagnostic purposes; counting is by message, not by size.
+ */
+/**
+ * Result of `getFile`. `file_path` is a relative path the Bot File API
+ * appends to `https://api.telegram.org/file/bot<TOKEN>/...` to download
+ * the bytes. The path is short-lived (~1 hour) and tied to the token.
+ */
+export interface TgFile {
+  file_id: string;
+  file_unique_id: string;
+  file_size?: number;
+  /** Relative path. Undefined when the file is too large (Telegram caps
+   *  download API at ~20 MB). */
+  file_path?: string;
+}
+
+export interface TgPhotoSize {
+  file_id: string;
+  file_unique_id: string;
+  width: number;
+  height: number;
+  file_size?: number;
+}
+
+export interface TgVideo {
+  file_id: string;
+  file_unique_id: string;
+  width: number;
+  height: number;
+  duration: number;
+  mime_type?: string;
+  file_size?: number;
+}
+
+export interface TgVoice {
+  file_id: string;
+  file_unique_id: string;
+  duration: number;
+  mime_type?: string;
+  file_size?: number;
+}
+
+/** «Кружок» — видео-сообщение Telegram (квадратное короткое видео). */
+export interface TgVideoNote {
+  file_id: string;
+  file_unique_id: string;
+  length: number;
+  duration: number;
+  file_size?: number;
+}
+
+export interface TgDocument {
+  file_id: string;
+  file_unique_id: string;
+  file_name?: string;
+  mime_type?: string;
+  file_size?: number;
+}
+
+export interface TgMessage {
+  message_id: number;
+  from?: TgUser;
+  chat: TgChat;
+  date: number;
+  text?: string;
+  /** Caption that can accompany media uploads (photo / video / document /
+   *  voice). Treated as the message's "text" by the persistence layer
+   *  so RAG / extractors see the candidate's words. */
+  caption?: string;
+  /** Photo upload — present on photo messages, includes all delivered sizes. */
+  photo?: TgPhotoSize[];
+  video?: TgVideo;
+  voice?: TgVoice;
+  /** «Кружок» — видео-сообщение (video note). Для видео-верификации. */
+  video_note?: TgVideoNote;
+  document?: TgDocument;
+  /** When this message is a reply to another, Telegram inlines the
+   *  parent message here. We use it to detect operator replies to lead
+   *  cards (matched by the parent's `message_id` against
+   *  `leads.ops_message_id`). */
+  reply_to_message?: TgMessage;
+}
+
+export interface TgCallbackQuery {
+  id: string;
+  from: TgUser;
+  data?: string;
+  message?: TgMessage;
+}
+
+export interface TgUpdate {
+  update_id: number;
+  message?: TgMessage;
+  edited_message?: TgMessage;
+  callback_query?: TgCallbackQuery;
+}
+
+export interface TgSendMessageResult {
+  message_id: number;
+  chat: TgChat;
+  date: number;
+  text?: string;
+}
+
+export interface TgInlineKeyboardButton {
+  text: string;
+  url?: string;
+  callback_data?: string;
+}
+
+export interface TgReplyMarkup {
+  inline_keyboard?: TgInlineKeyboardButton[][];
+}

package/src/bot-api/update-parser.test.ts

@@ -0,0 +1,142 @@
+import { describe, expect, it } from "bun:test";
+import type { TgUpdate } from "./types.ts";
+import { parseUpdate } from "./update-parser.ts";
+
+const CH = "telegram-bot-1";
+
+describe("parseUpdate", () => {
+  it("парсит текстовое сообщение в одну часть kind=text", () => {
+    const update: TgUpdate = {
+      update_id: 1,
+      message: {
+        message_id: 42,
+        chat: { id: 100, type: "private" },
+        from: { id: 100, first_name: "Alice", username: "alice" },
+        date: 1700000000,
+        text: "Привет",
+      },
+    };
+    const inbound = parseUpdate(CH, update);
+    expect(inbound).not.toBeNull();
+    expect(inbound).toMatchObject({
+      channelId: CH,
+      externalMessageId: "42",
+      externalUserId: "100",
+      externalUsername: "alice",
+      parts: [{ kind: "text", text: "Привет" }],
+      receivedAt: 1700000000,
+    });
+  });
+
+  it("парсит фото с caption, выбирая наибольший size", () => {
+    const update: TgUpdate = {
+      update_id: 2,
+      message: {
+        message_id: 7,
+        chat: { id: 200, type: "private" },
+        from: { id: 200 },
+        date: 1700000000,
+        caption: "look",
+        photo: [
+          { file_id: "small", file_unique_id: "u1", width: 90, height: 90 },
+          { file_id: "BIG", file_unique_id: "u2", width: 800, height: 800 },
+          { file_id: "mid", file_unique_id: "u3", width: 400, height: 400 },
+        ],
+      },
+    };
+    const inbound = parseUpdate(CH, update);
+    expect(inbound?.parts).toEqual([
+      {
+        kind: "photo",
+        mediaRef: { channelId: CH, externalRef: "BIG" },
+        caption: "look",
+      },
+    ]);
+  });
+
+  it("парсит voice как InboundPart с durationSec", () => {
+    const update: TgUpdate = {
+      update_id: 3,
+      message: {
+        message_id: 8,
+        chat: { id: 300, type: "private" },
+        from: { id: 300 },
+        date: 1700000000,
+        voice: { file_id: "vox", file_unique_id: "vu", duration: 12, mime_type: "audio/ogg" },
+      },
+    };
+    const inbound = parseUpdate(CH, update);
+    expect(inbound?.parts).toEqual([
+      {
+        kind: "voice",
+        mediaRef: { channelId: CH, externalRef: "vox" },
+        durationSec: 12,
+      },
+    ]);
+  });
+
+  it("парсит document с mimeType и fileName", () => {
+    const update: TgUpdate = {
+      update_id: 4,
+      message: {
+        message_id: 9,
+        chat: { id: 400, type: "private" },
+        from: { id: 400 },
+        date: 1700000000,
+        document: {
+          file_id: "doc1",
+          file_unique_id: "du",
+          file_name: "passport.pdf",
+          mime_type: "application/pdf",
+        },
+      },
+    };
+    const inbound = parseUpdate(CH, update);
+    expect(inbound?.parts).toEqual([
+      {
+        kind: "document",
+        mediaRef: { channelId: CH, externalRef: "doc1" },
+        mimeType: "application/pdf",
+        fileName: "passport.pdf",
+      },
+    ]);
+  });
+
+  it("парсит callback_query как kind=callback_query", () => {
+    const update: TgUpdate = {
+      update_id: 5,
+      callback_query: {
+        id: "cb-123",
+        from: { id: 500, username: "operator" },
+        data: "approve:42",
+        message: {
+          message_id: 999,
+          chat: { id: 500, type: "private" },
+          date: 1700000000,
+        },
+      },
+    };
+    const inbound = parseUpdate(CH, update);
+    expect(inbound?.parts).toEqual([
+      { kind: "callback_query", data: "approve:42", originalMessageId: "999" },
+    ]);
+    expect(inbound?.externalUserId).toBe("500");
+  });
+
+  it("возвращает null для пустого update без message/callback", () => {
+    expect(parseUpdate(CH, { update_id: 6 })).toBeNull();
+  });
+
+  it("возвращает null для сообщения без 'from' (анонимные канал-посты)", () => {
+    const update: TgUpdate = {
+      update_id: 7,
+      message: {
+        message_id: 1,
+        chat: { id: 1, type: "channel" },
+        date: 1700000000,
+        text: "anon",
+      },
+    };
+    expect(parseUpdate(CH, update)).toBeNull();
+  });
+});

package/src/bot-api/update-parser.ts

@@ -0,0 +1,112 @@
+import type { Inbound, InboundPart, MediaRef } from "@chatman-media/channel-core";
+import type { TgMessage, TgPhotoSize, TgUpdate } from "./types.ts";
+
+const ref = (channelId: string, externalRef: string): MediaRef => ({
+  channelId,
+  externalRef,
+});
+
+/**
+ * Берёт самую крупную доступную size фотографии. Telegram отдаёт массив
+ * sizes отсортированный по размеру; мы хотим original.
+ */
+function largestPhoto(photo: TgPhotoSize[]): TgPhotoSize | undefined {
+  if (photo.length === 0) return undefined;
+  return photo.reduce((biggest, current) =>
+    current.width * current.height > biggest.width * biggest.height ? current : biggest,
+  );
+}
+
+function partsFromMessage(channelId: string, msg: TgMessage): InboundPart[] {
+  const parts: InboundPart[] = [];
+
+  // Caption у photo/video/document обрабатывается ВНУТРИ соответствующего part'а,
+  // а у голого текстового message живёт в .text.
+  if (msg.text) {
+    parts.push({ kind: "text", text: msg.text });
+  }
+
+  if (msg.photo && msg.photo.length > 0) {
+    const biggest = largestPhoto(msg.photo);
+    if (biggest) {
+      const caption = msg.caption ?? undefined;
+      parts.push({
+        kind: "photo",
+        mediaRef: ref(channelId, biggest.file_id),
+        ...(caption ? { caption } : {}),
+      });
+    }
+  } else if (msg.video) {
+    parts.push({
+      kind: "video",
+      mediaRef: ref(channelId, msg.video.file_id),
+      ...(msg.caption ? { caption: msg.caption } : {}),
+    });
+  } else if (msg.voice) {
+    parts.push({
+      kind: "voice",
+      mediaRef: ref(channelId, msg.voice.file_id),
+      durationSec: msg.voice.duration,
+    });
+  } else if (msg.video_note) {
+    // «Кружок» — видео-сообщение Telegram. Используется для видео-верификации.
+    parts.push({
+      kind: "video_note",
+      mediaRef: ref(channelId, msg.video_note.file_id),
+      ...(msg.video_note.duration ? { durationSec: msg.video_note.duration } : {}),
+    });
+  } else if (msg.document) {
+    parts.push({
+      kind: "document",
+      mediaRef: ref(channelId, msg.document.file_id),
+      ...(msg.document.mime_type ? { mimeType: msg.document.mime_type } : {}),
+      ...(msg.document.file_name ? { fileName: msg.document.file_name } : {}),
+    });
+  } else if (!msg.text && msg.caption) {
+    // Caption без media — теоретически невозможно по Bot API, но обработаем как text.
+    parts.push({ kind: "text", text: msg.caption });
+  }
+
+  return parts;
+}
+
+/**
+ * Маппит сырой Telegram Update в канал-агностичный Inbound (или null если
+ * update не относится к диалогу — например, чисто edited_message без изменений
+ * нашему пайплайну неинтересен).
+ */
+export function parseUpdate(channelId: string, update: TgUpdate): Inbound | null {
+  if (update.callback_query) {
+    const cb = update.callback_query;
+    const messageId = cb.message?.message_id;
+    if (cb.data === undefined || messageId === undefined) return null;
+    return {
+      channelId,
+      externalMessageId: String(cb.message?.message_id ?? cb.id),
+      externalUserId: String(cb.from.id),
+      ...(cb.from.username ? { externalUsername: cb.from.username } : {}),
+      parts: [
+        { kind: "callback_query", data: cb.data, originalMessageId: String(messageId) },
+      ],
+      receivedAt: Math.floor(Date.now() / 1000),
+      raw: update,
+    };
+  }
+
+  const msg = update.message ?? update.edited_message;
+  if (!msg) return null;
+  if (!msg.from) return null;
+
+  const parts = partsFromMessage(channelId, msg);
+  if (parts.length === 0) return null;
+
+  return {
+    channelId,
+    externalMessageId: String(msg.message_id),
+    externalUserId: String(msg.from.id),
+    ...(msg.from.username ? { externalUsername: msg.from.username } : {}),
+    parts,
+    receivedAt: msg.date,
+    raw: update,
+  };
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+export {
+  TelegramBotAdapter,
+  type TelegramBotAdapterOptions,
+} from "./bot-api/adapter.ts";
+export type { FetchLike, TelegramClientOptions } from "./bot-api/client.ts";
+export { TelegramApiError, TelegramClient } from "./bot-api/client.ts";
+export type {
+  TgCallbackQuery,
+  TgChat,
+  TgDocument,
+  TgFile,
+  TgInlineKeyboardButton,
+  TgMessage,
+  TgPhotoSize,
+  TgReplyMarkup,
+  TgSendMessageResult,
+  TgUpdate,
+  TgUser,
+  TgVideo,
+  TgVoice,
+} from "./bot-api/types.ts";
+export { parseUpdate } from "./bot-api/update-parser.ts";
+export {
+  TelegramUserbotAdapter,
+  type TelegramUserbotAdapterOptions,
+  type UserbotHealthEvent,
+  type UserbotHealthStatus,
+} from "./userbot/adapter.ts";
+export {
+  type FinishedUserbotLogin,
+  finishUserbotLogin,
+  type StartedUserbotLogin,
+  startUserbotLogin,
+  submitUserbot2fa,
+  submitUserbotCode,
+  UserbotLoginError,
+  type UserbotLoginErrorCode,
+} from "./userbot/login.ts";