@chatman-media/channel-telegram 1.1.0

package/dist/userbot/adapter.d.ts

@@ -0,0 +1,121 @@
+import type { ChannelAdapter, ChannelCapabilities, DeleteOpts, EditOpts, Inbound, MediaRef, OutboundEnvelope, Sent } from "@chatman-media/channel-core";
+/**
+ * Healthcheck-статусы MTProto userbot'а. apps/worker отслеживает их через
+ * healthEvents() async iterable и:
+ *   - "connected" → нормальная работа
+ *   - "auth_key_duplicated" → session revoked (оператор нажал "Terminate
+ *     other sessions" в TG-клиенте, либо Telegram сам killед). Требует
+ *     re-auth через admin-UI; supervisor НЕ должен respawn в петле.
+ *   - "connection_failed" → transient (network blip); supervisor respawn'ит.
+ */
+export type UserbotHealthStatus = "connected" | "auth_key_duplicated" | "connection_failed";
+export interface UserbotHealthEvent {
+    status: UserbotHealthStatus;
+    reason?: string;
+    at: number;
+}
+/**
+ * MTProto userbot адаптер (личный аккаунт оператора через gramjs).
+ *
+ * Минимальная функциональность: connect, receive (NewMessage → Inbound),
+ * send (text), downloadMedia (через client.downloadMedia). Полная legacy-codebase
+ * импл'я имеет +supervisor для AUTH_KEY_DUPLICATED, delete-queue, per-
+ * conversation serialization, vision/photo-classify — это всё надстраивается
+ * сверху в conversation-engine и apps/worker.
+ *
+ * Жизненный цикл:
+ *   1. new TelegramUserbotAdapter({ id, apiId, apiHash, sessionString,
+ *      onSessionUpdated })
+ *   2. await adapter.connect() — gramjs client.connect() с retry, при
+ *      обновлённой session сохраняется callback'ом onSessionUpdated.
+ *   3. await for inbound of adapter.receive() — push'ит NewMessage events.
+ *   4. adapter.send(envelope) — text via gramjs.sendMessage(peer).
+ *   5. adapter.close() / signal.abort() — disconnect.
+ */
+export interface TelegramUserbotAdapterOptions {
+    id: string;
+    apiId: number;
+    apiHash: string;
+    /**
+     * StringSession строка. Пустая = первичная auth (требует операторского
+     * вмешательства через admin /userbot-login flow). При успешном connect
+     * gramjs может выдать обновлённый session — это сохраняется через
+     * onSessionUpdated callback.
+     */
+    sessionString: string;
+    /**
+     * Callback при обновлении session-string'а после connect или re-auth.
+     * apps/worker записывает её в userbot_session таблицу.
+     */
+    onSessionUpdated?: (sessionString: string) => Promise<void> | void;
+    /** Количество retry connect'ов, default 5. */
+    connectionRetries?: number;
+    /** ms между connect-попытками, default 5000. */
+    retryDelayMs?: number;
+}
+export declare class TelegramUserbotAdapter implements ChannelAdapter {
+    readonly kind: "telegram_userbot";
+    readonly id: string;
+    readonly capabilities: ChannelCapabilities;
+    private readonly opts;
+    private client;
+    private readonly inbox;
+    private waiters;
+    private closed;
+    /**
+     * LRU-кэш Message-объектов для последующего downloadMedia. Ключ —
+     * `${external_user_id}:${msg_id}`. Размер ограничен MAX_RECENT_MESSAGES
+     * чтобы long-running процесс не утекал. Если worker'у нужен старый
+     * media — он должен скачать его сразу в onInbound, не отсрочивать.
+     */
+    private static readonly MAX_RECENT_MESSAGES;
+    private readonly recentMessages;
+    /** Healthcheck events queue (separate от inbox'а). */
+    private readonly healthQueue;
+    private healthWaiters;
+    constructor(opts: TelegramUserbotAdapterOptions);
+    /**
+     * Установить MTProto-соединение. Бросает Error если все retry'и failед —
+     * supervisor в apps/worker делает respawn. Идемпотентно при повторных
+     * вызовах (no-op если уже connected).
+     */
+    connect(): Promise<void>;
+    private emitHealth;
+    /**
+     * Async iterable healthcheck-events для supervisor'а в apps/worker.
+     * Emit'ится при connect success ("connected") / connect failure
+     * ("connection_failed") / auth revocation ("auth_key_duplicated").
+     * Supervisor читает их и решает: respawn vs notify-operator-and-stop.
+     */
+    healthEvents(): AsyncIterable<UserbotHealthEvent>;
+    private registerHandler;
+    private cacheMessage;
+    private eventToInbound;
+    private hasMedia;
+    private mediaToPart;
+    private enqueue;
+    close(): Promise<void>;
+    receive(signal?: AbortSignal): AsyncIterable<Inbound>;
+    send(envelope: OutboundEnvelope): Promise<Sent>;
+    edit(_opts: EditOpts): Promise<void>;
+    delete(opts: DeleteOpts): Promise<void>;
+    /**
+     * Скачивает медиа через cached Message-объект. mediaRef.externalRef —
+     * msg.id из last-received Inbound; caller вызывает downloadMedia сразу
+     * после inbound'а (worker pipe'ит в media-кэш).
+     *
+     * mediaRef.externalRef сам по себе не хватает (gramjs.downloadMedia
+     * требует Message), поэтому мы кэшируем последние MAX_RECENT_MESSAGES
+     * объектов в recentMessages Map при registerHandler.
+     *
+     * Throws если: client не подключён / mediaRef не найден в кэше /
+     * downloadMedia ошибается.
+     */
+    downloadMedia(mediaRef: MediaRef, opts?: {
+        externalUserId?: string;
+    }): Promise<Response>;
+    signalTyping(externalUserId: string): Promise<void>;
+    /** Резолв peer'а по external_user_id (string из Inbound). */
+    private resolvePeer;
+}
+//# sourceMappingURL=adapter.d.ts.map

package/dist/userbot/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../src/userbot/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,mBAAmB,EACnB,UAAU,EACV,QAAQ,EACR,OAAO,EAEP,QAAQ,EACR,gBAAgB,EAChB,IAAI,EACL,MAAM,6BAA6B,CAAC;AAMrC;;;;;;;;GAQG;AACH,MAAM,MAAM,mBAAmB,GAAG,WAAW,GAAG,qBAAqB,GAAG,mBAAmB,CAAC;AAE5F,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,mBAAmB,CAAC;IAC5B,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,6BAA6B;IAC5C,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;OAKG;IACH,aAAa,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,CAAC,aAAa,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IACnE,8CAA8C;IAC9C,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAcD,qBAAa,sBAAuB,YAAW,cAAc;IAC3D,QAAQ,CAAC,IAAI,EAAG,kBAAkB,CAAU;IAC5C,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,YAAY,sBAA2B;IAEhD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAgC;IACrD,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiB;IACvC,OAAO,CAAC,OAAO,CAAmD;IAClE,OAAO,CAAC,MAAM,CAAS;IACvB;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAO;IAClD,OAAO,CAAC,QAAQ,CAAC,cAAc,CAA8B;IAC7D,sDAAsD;IACtD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAA4B;IACxD,OAAO,CAAC,aAAa,CAA8D;gBAEvE,IAAI,EAAE,6BAA6B;IAK/C;;;;OAIG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAwD9B,OAAO,CAAC,UAAU;IAUlB;;;;;OAKG;IACH,YAAY,IAAI,aAAa,CAAC,kBAAkB,CAAC;IAqBjD,OAAO,CAAC,eAAe;IAgBvB,OAAO,CAAC,YAAY;IAepB,OAAO,CAAC,cAAc;IA+BtB,OAAO,CAAC,QAAQ;IAKhB,OAAO,CAAC,WAAW;IAgDnB,OAAO,CAAC,OAAO;IAST,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB5B,OAAO,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,aAAa,CAAC,OAAO,CAAC;IAoC/C,IAAI,CAAC,QAAQ,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAsC/C,IAAI,CAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAIpC,MAAM,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAgB7C;;;;;;;;;;;OAWG;IACG,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,IAAI,CAAC,EAAE;QAAE,cAAc,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,QAAQ,CAAC;IA2BxF,YAAY,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmBzD,6DAA6D;YAC/C,WAAW;CAQ1B"}

package/dist/userbot/login.d.ts

@@ -0,0 +1,62 @@
+import { TelegramClient } from "telegram";
+/**
+ * Пошаговый MTProto-логин для onboarding'а personal-account userbot'а.
+ *
+ * GramJS высокоуровневый `client.start()` интерактивен (callback'и для кода
+ * и пароля) — не годится для stateless HTTP. Здесь логин разбит на шаги:
+ *   1. startUserbotLogin(phone) → connect + sendCode → { client, phoneCodeHash }
+ *   2. submitUserbotCode({client, code}) → auth.SignIn; при 2FA → needs2fa:true
+ *   3. submitUserbot2fa({client, password}) → account.GetPassword + SRP CheckPassword
+ *
+ * Между шагами вызывающая сторона (apps/api) ДОЛЖНА держать тот же `client`
+ * в памяти — phoneCodeHash и auth-key привязаны к этому live-соединению.
+ * По завершении session-string сохраняется (encrypted) и адаптер reconnect'ится.
+ */
+export type UserbotLoginErrorCode = "phone_invalid" | "code_invalid" | "code_expired" | "password_invalid" | "flood_wait" | "unknown";
+export declare class UserbotLoginError extends Error {
+    readonly code: UserbotLoginErrorCode;
+    /** Для flood_wait — сколько секунд ждать. */
+    readonly retryAfterSec?: number | undefined;
+    constructor(code: UserbotLoginErrorCode, message: string, 
+    /** Для flood_wait — сколько секунд ждать. */
+    retryAfterSec?: number | undefined);
+}
+export interface StartedUserbotLogin {
+    client: TelegramClient;
+    phoneCodeHash: string;
+}
+export interface FinishedUserbotLogin {
+    sessionString: string;
+    userId: string;
+    username: string | null;
+    phone: string | null;
+}
+/** Шаг 1: подключиться и отправить код подтверждения на номер. */
+export declare function startUserbotLogin(opts: {
+    apiId: number;
+    apiHash: string;
+    phone: string;
+}): Promise<StartedUserbotLogin>;
+/**
+ * Шаг 2: отправить код. Если у аккаунта включён 2FA — Telegram вернёт
+ * SESSION_PASSWORD_NEEDED, возвращаем { needs2fa: true } (логин не завершён).
+ * Иначе логин завершён — возвращаем session-string.
+ */
+export declare function submitUserbotCode(opts: {
+    client: TelegramClient;
+    phone: string;
+    phoneCodeHash: string;
+    code: string;
+}): Promise<{
+    needs2fa: true;
+} | ({
+    needs2fa: false;
+} & FinishedUserbotLogin)>;
+/** Шаг 3 (опционально): отправить пароль 2FA через SRP. */
+export declare function submitUserbot2fa(opts: {
+    client: TelegramClient;
+    password: string;
+}): Promise<FinishedUserbotLogin>;
+/** Сохранить session-string + получить идентификаторы аккаунта. */
+export declare function finishUserbotLogin(client: TelegramClient): Promise<FinishedUserbotLogin>;
+//# sourceMappingURL=login.d.ts.map

package/dist/userbot/login.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"login.d.ts","sourceRoot":"","sources":["../../src/userbot/login.ts"],"names":[],"mappings":"AAAA,OAAO,EAAO,cAAc,EAAE,MAAM,UAAU,CAAC;AAI/C;;;;;;;;;;;;GAYG;AAEH,MAAM,MAAM,qBAAqB,GAC7B,eAAe,GACf,cAAc,GACd,cAAc,GACd,kBAAkB,GAClB,YAAY,GACZ,SAAS,CAAC;AAEd,qBAAa,iBAAkB,SAAQ,KAAK;IAExC,QAAQ,CAAC,IAAI,EAAE,qBAAqB;IAEpC,6CAA6C;IAC7C,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM;gBAHtB,IAAI,EAAE,qBAAqB,EACpC,OAAO,EAAE,MAAM;IACf,6CAA6C;IACpC,aAAa,CAAC,EAAE,MAAM,YAAA;CAKlC;AAED,MAAM,WAAW,mBAAmB;IAClC,MAAM,EAAE,cAAc,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CACtB;AAgCD,kEAAkE;AAClE,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAe/B;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,IAAI,EAAE;IAC5C,MAAM,EAAE,cAAc,CAAC;IACvB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,IAAI,EAAE,MAAM,CAAC;CACd,GAAG,OAAO,CAAC;IAAE,QAAQ,EAAE,IAAI,CAAA;CAAE,GAAG,CAAC;IAAE,QAAQ,EAAE,KAAK,CAAA;CAAE,GAAG,oBAAoB,CAAC,CAAC,CAoB7E;AAED,2DAA2D;AAC3D,wBAAsB,gBAAgB,CAAC,IAAI,EAAE;IAC3C,MAAM,EAAE,cAAc,CAAC;IACvB,QAAQ,EAAE,MAAM,CAAC;CAClB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAShC;AAED,mEAAmE;AACnE,wBAAsB,kBAAkB,CAAC,MAAM,EAAE,cAAc,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAS9F"}

package/package.json

@@ -0,0 +1,70 @@
+{
+  "name": "@chatman-media/channel-telegram",
+  "version": "1.1.0",
+  "description": "Telegram-каналы (BotAPI + MTProto userbot) как реализация ChannelAdapter из @chatman-media/channel-core.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "bun build ./src/index.ts --outdir ./dist --target node --format esm --external @chatman-media/channel-core && tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit",
+    "check": "biome check ./src",
+    "format": "biome format --write ./src",
+    "test": "bun test",
+    "prepublishOnly": "bun run build"
+  },
+  "keywords": [
+    "lead-engine",
+    "channel",
+    "telegram",
+    "mtproto",
+    "bot-api"
+  ],
+  "author": "Alexander Kireev",
+  "license": "MIT",
+  "dependencies": {
+    "@chatman-media/channel-core": "1.0.0"
+  },
+  "peerDependencies": {
+    "telegram": ">=2.26.0"
+  },
+  "peerDependenciesMeta": {
+    "telegram": {
+      "optional": true
+    }
+  },
+  "optionalDependencies": {
+    "telegram": "^2.26.22"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.14",
+    "@types/bun": "1.3.14",
+    "typescript": "^6.0.3"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/chatman-media/lead-engine.git",
+    "directory": "packages/channel-telegram"
+  },
+  "homepage": "https://github.com/chatman-media/lead-engine/tree/main/packages/channel-telegram#readme",
+  "bugs": {
+    "url": "https://github.com/chatman-media/lead-engine/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/bot-api/adapter.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "bun:test";
+import { TelegramBotAdapter } from "./adapter.ts";
+import type { TgUpdate } from "./types.ts";
+
+interface RecordedCall {
+  url: string;
+  body: unknown;
+}
+
+function fakeFetch(): { fetch: typeof fetch; calls: RecordedCall[] } {
+  const calls: RecordedCall[] = [];
+  const fn = async (url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const body = init?.body ? JSON.parse(String(init.body)) : null;
+    calls.push({ url: String(url), body });
+    return new Response(JSON.stringify({ ok: true, result: { message_id: 1234 } }), {
+      status: 200,
+      headers: { "content-type": "application/json" },
+    });
+  };
+  return { fetch: fn as unknown as typeof fetch, calls };
+}
+
+describe("TelegramBotAdapter", () => {
+  it("маппит OutboundEnvelope c text-part в sendMessage с chat_id/text", async () => {
+    const { fetch, calls } = fakeFetch();
+    const adapter = new TelegramBotAdapter({ id: "tg1", token: "TKN", fetch });
+    const sent = await adapter.send({
+      channelId: "tg1",
+      externalUserId: "12345",
+      parts: [{ kind: "text", text: "hello" }],
+    });
+    expect(sent.externalMessageId).toBe("1234");
+    expect(calls).toHaveLength(1);
+    const [call] = calls;
+    expect(call?.url).toBe("https://api.telegram.org/botTKN/sendMessage");
+    expect(call?.body).toEqual({ chat_id: 12345, text: "hello" });
+  });
+
+  it("маппит inline-кнопки на reply_markup, и кладёт их только на последнее сообщение", async () => {
+    const { fetch, calls } = fakeFetch();
+    const adapter = new TelegramBotAdapter({ id: "tg1", token: "TKN", fetch });
+    await adapter.send({
+      channelId: "tg1",
+      externalUserId: "10",
+      parts: [
+        { kind: "text", text: "one" },
+        { kind: "text", text: "two" },
+      ],
+      replyMarkup: { inlineButtons: [[{ label: "Yes", callbackData: "y" }]] },
+    });
+    expect(calls).toHaveLength(2);
+    expect(calls[0]?.body).not.toHaveProperty("reply_markup");
+    expect(calls[1]?.body).toMatchObject({
+      reply_markup: { inline_keyboard: [[{ text: "Yes", callback_data: "y" }]] },
+    });
+  });
+
+  it("receive() возвращает Inbound из pushUpdate без race conditions", async () => {
+    const { fetch } = fakeFetch();
+    const adapter = new TelegramBotAdapter({ id: "tg1", token: "TKN", fetch });
+    const update: TgUpdate = {
+      update_id: 1,
+      message: {
+        message_id: 9,
+        chat: { id: 7, type: "private" },
+        from: { id: 7, username: "kate" },
+        date: 1700000000,
+        text: "ping",
+      },
+    };
+    // Push до начала чтения — Inbound должен лежать в inbox.
+    adapter.pushUpdate(update);
+    const iter = adapter.receive()[Symbol.asyncIterator]();
+    const next = await iter.next();
+    expect(next.done).toBe(false);
+    expect(next.value.parts).toEqual([{ kind: "text", text: "ping" }]);
+
+    // Закрываем стрим — receive завершается.
+    adapter.close();
+    const last = await iter.next();
+    expect(last.done).toBe(true);
+  });
+
+  it("receive() ждёт pushUpdate если очередь пуста (resolver-pattern)", async () => {
+    const { fetch } = fakeFetch();
+    const adapter = new TelegramBotAdapter({ id: "tg1", token: "TKN", fetch });
+    const iter = adapter.receive()[Symbol.asyncIterator]();
+    const nextPromise = iter.next();
+    // Через микротик пушим update — Promise должен разрешиться.
+    queueMicrotask(() => {
+      adapter.pushUpdate({
+        update_id: 2,
+        message: {
+          message_id: 1,
+          chat: { id: 1, type: "private" },
+          from: { id: 1 },
+          date: 0,
+          text: "async",
+        },
+      });
+    });
+    const next = await nextPromise;
+    expect(next.value.parts).toEqual([{ kind: "text", text: "async" }]);
+  });
+});

package/src/bot-api/adapter.ts

@@ -0,0 +1,242 @@
+import type {
+  ChannelAdapter,
+  ChannelCapabilities,
+  DeleteOpts,
+  EditOpts,
+  Inbound,
+  MediaRef,
+  OutboundEnvelope,
+  OutboundPart,
+  ReplyMarkup,
+  Sent,
+} from "@chatman-media/channel-core";
+import { TelegramClient, type TelegramClientOptions } from "./client.ts";
+import type { TgReplyMarkup, TgUpdate } from "./types.ts";
+import { parseUpdate } from "./update-parser.ts";
+
+export interface TelegramBotAdapterOptions extends TelegramClientOptions {
+  /** Уникальный id канала в платформе (соответствует `channels.id` в БД). */
+  id: string;
+}
+
+const TG_BOT_CAPABILITIES: ChannelCapabilities = {
+  text: true,
+  photo: true,
+  video: true,
+  // Bot API позволяет отправлять voice через файл, но в нашем пайплайне голос
+  // только входит (от кандидата), не отправляется ботом. Если понадобится —
+  // расширим OutboundPart и снимем флаг.
+  voice: false,
+  document: true,
+  edit: true,
+  delete: true,
+  callbackQuery: true,
+  typing: true,
+};
+
+function toTgReplyMarkup(rm: ReplyMarkup | undefined): TgReplyMarkup | undefined {
+  if (!rm?.inlineButtons) return undefined;
+  return {
+    inline_keyboard: rm.inlineButtons.map((row) =>
+      row.map((b) => ({ text: b.label, callback_data: b.callbackData })),
+    ),
+  };
+}
+
+function parseMode(mode: "markdown" | "html" | undefined): "MarkdownV2" | "HTML" | undefined {
+  if (mode === "markdown") return "MarkdownV2";
+  if (mode === "html") return "HTML";
+  return undefined;
+}
+
+/**
+ * Telegram Bot API адаптер. Получает входящие через `pushUpdate()` (HTTP webhook
+ * в apps/api дёргает этот метод на каждый incoming POST), отправляет исходящие
+ * через TelegramClient.
+ *
+ * Адаптер не делает rate-limiting и retry сам — это ответственность outbound-
+ * dispatcher'а в apps/worker (использует `attempts`/`sent_at` в outbound_queue).
+ */
+export class TelegramBotAdapter implements ChannelAdapter {
+  readonly kind = "telegram_bot" as const;
+  readonly id: string;
+  readonly capabilities = TG_BOT_CAPABILITIES;
+
+  private readonly client: TelegramClient;
+  private readonly inbox: Inbound[] = [];
+  private waiters: Array<(v: IteratorResult<Inbound>) => void> = [];
+  private closed = false;
+
+  constructor(opts: TelegramBotAdapterOptions) {
+    this.id = opts.id;
+    this.client = new TelegramClient(opts);
+  }
+
+  /** Доступ к raw-клиенту для admin-операций (setWebhook, getMe, и т.д.). */
+  get rawClient(): TelegramClient {
+    return this.client;
+  }
+
+  /**
+   * Пушит сырой Telegram update в очередь. Парсится в Inbound; если update
+   * нерелевантен (нет сообщения и нет callback_query) — silent drop.
+   * Вызывается из HTTP-хэндлера webhook'а.
+   */
+  pushUpdate(update: TgUpdate): void {
+    const inbound = parseUpdate(this.id, update);
+    if (!inbound) return;
+    this.enqueue(inbound);
+  }
+
+  private enqueue(inbound: Inbound): void {
+    const waiter = this.waiters.shift();
+    if (waiter) {
+      waiter({ value: inbound, done: false });
+      return;
+    }
+    this.inbox.push(inbound);
+  }
+
+  /** Закрыть стрим: receive() завершится после дренажа очереди. */
+  close(): void {
+    this.closed = true;
+    while (this.waiters.length > 0) {
+      const w = this.waiters.shift();
+      w?.({ value: undefined as unknown as Inbound, done: true });
+    }
+  }
+
+  receive(signal?: AbortSignal): AsyncIterable<Inbound> {
+    const self = this;
+    return {
+      [Symbol.asyncIterator](): AsyncIterator<Inbound> {
+        return {
+          next(): Promise<IteratorResult<Inbound>> {
+            if (signal?.aborted) {
+              return Promise.resolve({ value: undefined as unknown as Inbound, done: true });
+            }
+            const queued = self.inbox.shift();
+            if (queued) {
+              return Promise.resolve({ value: queued, done: false });
+            }
+            if (self.closed) {
+              return Promise.resolve({ value: undefined as unknown as Inbound, done: true });
+            }
+            return new Promise((resolve) => {
+              self.waiters.push(resolve);
+              if (signal) {
+                signal.addEventListener(
+                  "abort",
+                  () => {
+                    const idx = self.waiters.indexOf(resolve);
+                    if (idx >= 0) self.waiters.splice(idx, 1);
+                    resolve({ value: undefined as unknown as Inbound, done: true });
+                  },
+                  { once: true },
+                );
+              }
+            });
+          },
+        };
+      },
+    };
+  }
+
+  async send(envelope: OutboundEnvelope): Promise<Sent> {
+    if (envelope.parts.length === 0) {
+      throw new Error("OutboundEnvelope.parts must be non-empty");
+    }
+    const chatId = Number(envelope.externalUserId);
+    if (Number.isNaN(chatId)) {
+      throw new Error(`telegram-bot: invalid externalUserId "${envelope.externalUserId}"`);
+    }
+
+    // Sequential send for каждой части — Bot API не поддерживает atomic batch.
+    // Возвращаем id ПЕРВОГО отправленного — это якорь для replyTo/edit/delete.
+    let firstMessageId: number | undefined;
+    const lastIdx = envelope.parts.length - 1;
+    for (let i = 0; i < envelope.parts.length; i++) {
+      const part = envelope.parts[i] as OutboundPart;
+      // reply_markup и reply_to_message_id применяются только к последней части,
+      // чтобы кнопки висели под финальным сообщением.
+      const isLast = i === lastIdx;
+      const replyMarkup = isLast ? toTgReplyMarkup(envelope.replyMarkup) : undefined;
+      const replyToMessageId =
+        i === 0 && envelope.replyToExternalMessageId !== undefined
+          ? Number(envelope.replyToExternalMessageId)
+          : undefined;
+
+      let res: { message_id: number };
+      if (part.kind === "text") {
+        res = await this.client.sendMessage({
+          chatId,
+          text: part.text,
+          ...(parseMode(part.parseMode) ? { parseMode: parseMode(part.parseMode) } : {}),
+          ...(replyMarkup ? { replyMarkup } : {}),
+          ...(replyToMessageId !== undefined ? { replyToMessageId } : {}),
+        });
+      } else if (part.kind === "photo") {
+        res = await this.client.sendPhoto({
+          chatId,
+          photoFileId: part.mediaRef.externalRef,
+          ...(part.caption ? { caption: part.caption } : {}),
+        });
+      } else if (part.kind === "video") {
+        res = await this.client.sendVideo({
+          chatId,
+          videoFileId: part.mediaRef.externalRef,
+          ...(part.caption ? { caption: part.caption } : {}),
+        });
+      } else {
+        res = await this.client.sendDocument({
+          chatId,
+          documentFileId: part.mediaRef.externalRef,
+          ...(part.caption ? { caption: part.caption } : {}),
+        });
+      }
+      if (firstMessageId === undefined) firstMessageId = res.message_id;
+    }
+
+    return {
+      channelId: this.id,
+      externalMessageId: String(firstMessageId ?? ""),
+      sentAt: Math.floor(Date.now() / 1000),
+    };
+  }
+
+  async edit(opts: EditOpts): Promise<void> {
+    const chatId = Number(opts.externalUserId);
+    const messageId = Number(opts.externalMessageId);
+    if (Number.isNaN(chatId) || Number.isNaN(messageId)) {
+      throw new Error("telegram-bot: edit requires numeric externalUserId / externalMessageId");
+    }
+    await this.client.editMessageText({
+      chatId,
+      messageId,
+      text: opts.text,
+      ...(parseMode(opts.parseMode) ? { parseMode: parseMode(opts.parseMode) } : {}),
+      ...(toTgReplyMarkup(opts.replyMarkup)
+        ? { replyMarkup: toTgReplyMarkup(opts.replyMarkup) as TgReplyMarkup }
+        : {}),
+    });
+  }
+
+  async delete(opts: DeleteOpts): Promise<void> {
+    const chatId = Number(opts.externalUserId);
+    const messageId = Number(opts.externalMessageId);
+    if (Number.isNaN(chatId) || Number.isNaN(messageId)) {
+      throw new Error("telegram-bot: delete requires numeric externalUserId / externalMessageId");
+    }
+    await this.client.deleteMessage({ chatId, messageId });
+  }
+
+  downloadMedia(mediaRef: MediaRef): Promise<Response> {
+    return this.client.downloadFile(mediaRef.externalRef);
+  }
+
+  async signalTyping(externalUserId: string): Promise<void> {
+    const chatId = Number(externalUserId);
+    if (Number.isNaN(chatId)) return;
+    await this.client.sendChatAction({ chatId, action: "typing" });
+  }
+}