@adminforth/chat-surface-adapter-telegram 1.0.0

package/.woodpecker/buildRelease.sh

@@ -0,0 +1,9 @@
+#!/bin/bash
+
+pnpm run build 2>&1 | tee build.log
+build_status=${PIPESTATUS[0]}
+
+if [ $build_status -ne 0 ]; then
+  echo "Build failed. Exiting with status code $build_status"
+  exit $build_status
+fi

package/.woodpecker/buildSlackNotify.sh

@@ -0,0 +1,44 @@
+#!/bin/sh
+
+set -x
+
+COMMIT_SHORT_SHA=$(echo $CI_COMMIT_SHA | cut -c1-8)
+
+STATUS=${1}
+
+if [ "$STATUS" = "success" ]; then
+  MESSAGE="Did a build without issues on \`$CI_REPO_NAME/$CI_COMMIT_BRANCH\`. Commit: _${CI_COMMIT_MESSAGE}_ (<$CI_COMMIT_URL|$COMMIT_SHORT_SHA>)"
+
+  curl  -s -X POST -H "Content-Type: application/json" -d '{
+    "username": "'"$CI_COMMIT_AUTHOR"'",
+    "icon_url": "'"$CI_COMMIT_AUTHOR_AVATAR"'",
+    "attachments": [
+      {
+          "mrkdwn_in": ["text", "pretext"],
+          "color": "#36a64f",
+          "text": "'"$MESSAGE"'"
+      }
+    ]
+  }' "$DEVELOPERS_SLACK_WEBHOOK"
+  exit 0
+fi
+export BUILD_LOG=$(cat ./build.log)
+
+BUILD_LOG=$(echo $BUILD_LOG | sed 's/"/\\"/g')
+
+MESSAGE="Broke \`$CI_REPO_NAME/$CI_COMMIT_BRANCH\` with commit _${CI_COMMIT_MESSAGE}_ (<$CI_COMMIT_URL|$COMMIT_SHORT_SHA>)"
+CODE_BLOCK="\`\`\`$BUILD_LOG\n\`\`\`"
+
+echo "Sending slack message to developers $MESSAGE"
+curl -sS -X POST -H "Content-Type: application/json" -d '{
+  "username": "'"$CI_COMMIT_AUTHOR"'",
+  "icon_url": "'"$CI_COMMIT_AUTHOR_AVATAR"'",
+  "attachments": [
+    {
+        "mrkdwn_in": ["text", "pretext"],
+        "color": "#8A1C12",
+        "text": "'"$CODE_BLOCK"'",
+        "pretext": "'"$MESSAGE"'"
+    }
+  ]
+}' "$DEVELOPERS_SLACK_WEBHOOK" 2>&1

package/.woodpecker/release.yml

@@ -0,0 +1,56 @@
+clone:
+  git:
+    image: woodpeckerci/plugin-git
+    settings:
+      partial: false
+      depth: 5
+
+steps:
+  init-secrets:
+    when:
+      - event: push
+    image: infisical/cli
+    environment:
+      INFISICAL_TOKEN:
+        from_secret: VAULT_TOKEN
+    commands:
+      - infisical export --domain https://vault.devforth.io/api --format=dotenv-export --env="prod" > /woodpecker/deploy.vault.env
+
+  build:
+    image: devforth/node20-pnpm:latest
+    when:
+      - event: push
+    commands:
+      - . /woodpecker/deploy.vault.env
+      - pnpm install
+      - /bin/bash ./.woodpecker/buildRelease.sh
+      - npm audit signatures
+
+  release:
+    image: devforth/node20-pnpm:latest
+    when:
+      - event:
+          - push
+        branch:
+          - main
+    commands:
+      - . /woodpecker/deploy.vault.env
+      - pnpm exec semantic-release
+
+  slack-on-failure:
+    image: curlimages/curl
+    when:
+      - event: push
+        status: [failure]
+    commands:
+      - . /woodpecker/deploy.vault.env
+      - /bin/sh ./.woodpecker/buildSlackNotify.sh failure
+
+  slack-on-success:
+    image: curlimages/curl
+    when:
+      - event: push
+        status: [success]
+    commands:
+      - . /woodpecker/deploy.vault.env
+      - /bin/sh ./.woodpecker/buildSlackNotify.sh success

package/LICENSE

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

package/build.log

@@ -0,0 +1,4 @@
+
+> @adminforth/chat-surface-adapter-telegram@1.0.0 build /woodpecker/src/github.com/devforth/adminforth-chat-surface-adapter-telegram
+> tsc
+

package/dist/index.d.ts

@@ -0,0 +1,43 @@
+import { type AdminUser, type ChatSurfaceAdapter, type ChatSurfaceEventSink, type ChatSurfaceIncomingMessage, type ChatSurfaceRequestContext, type IAdminForth } from "adminforth";
+import { AdapterOptions } from "./types.js";
+export type { AdapterOptions, TelegramStreamingMode } from "./types.js";
+type TelegramUpdate = {
+    message?: {
+        text?: string;
+        chat?: {
+            id?: number | string;
+        };
+        from?: {
+            id?: number | string;
+            username?: string;
+            first_name?: string;
+            last_name?: string;
+            language_code?: string;
+        };
+    };
+};
+export declare class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
+    private options;
+    name: string;
+    constructor(options: AdapterOptions);
+    validate(): void;
+    parseIncomingMessage(ctx: ChatSurfaceRequestContext): Promise<{
+        surface: string;
+        prompt: string;
+        externalConversationId: string;
+        externalUserId: string;
+        userTimeZone: string;
+        metadata: {
+            telegramUpdate: TelegramUpdate;
+        };
+    } | null>;
+    createEventSink(ctx: ChatSurfaceRequestContext, incoming: ChatSurfaceIncomingMessage): ChatSurfaceEventSink;
+    resolveAdminUser(input: {
+        adminforth: IAdminForth;
+        incoming: ChatSurfaceIncomingMessage;
+    }): Promise<AdminUser | null>;
+    private sendMessage;
+    private sendChatAction;
+    private sendMessageDraft;
+}
+export default TelegramChatSurfaceAdapter;

package/dist/index.js

@@ -0,0 +1,263 @@
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { AdminForthFilterOperators, } from "adminforth";
+import { randomInt } from "node:crypto";
+const TELEGRAM_API_BASE_URL = "https://api.telegram.org";
+const TELEGRAM_SECRET_HEADER = "x-telegram-bot-api-secret-token";
+const TELEGRAM_MESSAGE_MAX_LENGTH = 4096;
+const TELEGRAM_DRAFT_MAX_LENGTH = 4096;
+const DEFAULT_DRAFT_UPDATE_INTERVAL_MS = 650;
+const DEFAULT_TYPING_INTERVAL_MS = 4000;
+const DEFAULT_ADMIN_USER_RESOURCE_ID = "adminuser";
+const DEFAULT_ADMIN_USER_TELEGRAM_ID_FIELD = "telegramId";
+function createTelegramDraftId() {
+    return randomInt(1, 2147483647);
+}
+function truncateTelegramDraft(text) {
+    if (text.length <= TELEGRAM_DRAFT_MAX_LENGTH) {
+        return text;
+    }
+    return `${text.slice(0, TELEGRAM_DRAFT_MAX_LENGTH - 1)}…`;
+}
+function isPrivateChatId(chatId) {
+    const numericChatId = Number(chatId);
+    return Number.isInteger(numericChatId) && numericChatId > 0;
+}
+function getHeaderValue(headers, name) {
+    const value = headers[name.toLowerCase()];
+    if (Array.isArray(value)) {
+        return String(value[0]);
+    }
+    return typeof value === "undefined" ? undefined : String(value);
+}
+function splitTelegramMessage(text) {
+    const chunks = [];
+    for (let index = 0; index < text.length; index += TELEGRAM_MESSAGE_MAX_LENGTH) {
+        chunks.push(text.slice(index, index + TELEGRAM_MESSAGE_MAX_LENGTH));
+    }
+    return chunks;
+}
+export class TelegramChatSurfaceAdapter {
+    constructor(options) {
+        this.options = options;
+        this.name = "telegram";
+    }
+    validate() {
+        if (!this.options.botToken) {
+            throw new Error("Telegram botToken is required");
+        }
+    }
+    parseIncomingMessage(ctx) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b, _c, _d, _e;
+            if (this.options.webhookSecret
+                && getHeaderValue(ctx.headers, TELEGRAM_SECRET_HEADER) !== this.options.webhookSecret) {
+                return null;
+            }
+            const update = ctx.body;
+            const text = (_a = update.message) === null || _a === void 0 ? void 0 : _a.text;
+            const chatId = (_c = (_b = update.message) === null || _b === void 0 ? void 0 : _b.chat) === null || _c === void 0 ? void 0 : _c.id;
+            const userId = (_e = (_d = update.message) === null || _d === void 0 ? void 0 : _d.from) === null || _e === void 0 ? void 0 : _e.id;
+            if (!text || chatId === undefined || userId === undefined) {
+                return null;
+            }
+            return {
+                surface: this.name,
+                prompt: text,
+                externalConversationId: String(chatId),
+                externalUserId: String(userId),
+                userTimeZone: "UTC",
+                metadata: {
+                    telegramUpdate: update,
+                },
+            };
+        });
+    }
+    createEventSink(ctx, incoming) {
+        var _a, _b;
+        let text = "";
+        let lastDraftText = "";
+        let draftTimer;
+        let typingTimer;
+        let closed = false;
+        let done = false;
+        const chatId = incoming.externalConversationId;
+        const configuredStreamingMode = (_a = this.options.streamingMode) !== null && _a !== void 0 ? _a : "draft";
+        const streamingMode = configuredStreamingMode === "draft" && !isPrivateChatId(chatId)
+            ? "typing"
+            : configuredStreamingMode;
+        const draftUpdateIntervalMs = (_b = this.options.draftUpdateIntervalMs) !== null && _b !== void 0 ? _b : DEFAULT_DRAFT_UPDATE_INTERVAL_MS;
+        const draftId = createTelegramDraftId();
+        const stopTyping = () => {
+            if (typingTimer) {
+                clearInterval(typingTimer);
+                typingTimer = undefined;
+            }
+        };
+        const startTyping = () => {
+            if (typingTimer || streamingMode === "off") {
+                return;
+            }
+            void this.sendChatAction(chatId, "typing").catch(() => undefined);
+            typingTimer = setInterval(() => {
+                void this.sendChatAction(chatId, "typing").catch(() => undefined);
+            }, DEFAULT_TYPING_INTERVAL_MS);
+        };
+        const clearDraftTimer = () => {
+            if (draftTimer) {
+                clearTimeout(draftTimer);
+                draftTimer = undefined;
+            }
+        };
+        const flushDraft = () => __awaiter(this, void 0, void 0, function* () {
+            if (closed ||
+                done ||
+                streamingMode !== "draft" ||
+                !text) {
+                return;
+            }
+            const draftText = truncateTelegramDraft(text);
+            if (draftText === lastDraftText) {
+                return;
+            }
+            lastDraftText = draftText;
+            yield this.sendMessageDraft({
+                chatId,
+                draftId,
+                text: draftText,
+                parseMode: "Markdown",
+            });
+        });
+        const scheduleDraftFlush = () => {
+            if (streamingMode !== "draft" || draftTimer) {
+                return;
+            }
+            draftTimer = setTimeout(() => {
+                draftTimer = undefined;
+                void flushDraft().catch(() => undefined);
+            }, draftUpdateIntervalMs);
+        };
+        startTyping();
+        return {
+            emit: (event) => __awaiter(this, void 0, void 0, function* () {
+                if (closed) {
+                    return;
+                }
+                if (event.type === "text_delta") {
+                    text += event.delta;
+                    if (streamingMode === "draft") {
+                        scheduleDraftFlush();
+                    }
+                    return;
+                }
+                if (event.type === "done") {
+                    done = true;
+                    stopTyping();
+                    clearDraftTimer();
+                    yield this.sendMessage(chatId, text || event.text);
+                    return;
+                }
+                if (event.type === "error") {
+                    done = true;
+                    stopTyping();
+                    clearDraftTimer();
+                    yield this.sendMessage(chatId, event.message);
+                }
+            }),
+            close: () => __awaiter(this, void 0, void 0, function* () {
+                closed = true;
+                stopTyping();
+                clearDraftTimer();
+            }),
+        };
+    }
+    resolveAdminUser(input) {
+        return __awaiter(this, void 0, void 0, function* () {
+            var _a, _b;
+            const adminUserResourceId = (_a = this.options.adminUserResourceId) !== null && _a !== void 0 ? _a : DEFAULT_ADMIN_USER_RESOURCE_ID;
+            const telegramIdField = (_b = this.options.adminUserTelegramIdField) !== null && _b !== void 0 ? _b : DEFAULT_ADMIN_USER_TELEGRAM_ID_FIELD;
+            const adminUser = yield input.adminforth.resource(adminUserResourceId).get([
+                {
+                    field: telegramIdField,
+                    operator: AdminForthFilterOperators.EQ,
+                    value: input.incoming.externalUserId,
+                },
+            ]);
+            if (!adminUser) {
+                return null;
+            }
+            return {
+                pk: adminUser.id,
+                username: adminUser[input.adminforth.config.auth.usernameField],
+                dbUser: adminUser,
+            };
+        });
+    }
+    sendMessage(chatId, text) {
+        return __awaiter(this, void 0, void 0, function* () {
+            if (!text) {
+                return;
+            }
+            for (const chunk of splitTelegramMessage(text)) {
+                const response = yield fetch(`${TELEGRAM_API_BASE_URL}/bot${this.options.botToken}/sendMessage`, {
+                    method: "POST",
+                    headers: {
+                        "Content-Type": "application/json",
+                    },
+                    body: JSON.stringify({
+                        chat_id: chatId,
+                        text: chunk,
+                        parse_mode: "Markdown",
+                    }),
+                });
+                if (!response.ok) {
+                    throw new Error(`Telegram sendMessage failed: ${response.status} ${yield response.text()}`);
+                }
+            }
+        });
+    }
+    sendChatAction(chatId, action) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield fetch(`${TELEGRAM_API_BASE_URL}/bot${this.options.botToken}/sendChatAction`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    chat_id: chatId,
+                    action,
+                }),
+            });
+            if (!response.ok) {
+                throw new Error(`Telegram sendChatAction failed: ${response.status} ${yield response.text()}`);
+            }
+        });
+    }
+    sendMessageDraft(input) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const response = yield fetch(`${TELEGRAM_API_BASE_URL}/bot${this.options.botToken}/sendMessageDraft`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                },
+                body: JSON.stringify({
+                    chat_id: Number(input.chatId),
+                    draft_id: input.draftId,
+                    text: input.text,
+                    parse_mode: input.parseMode,
+                }),
+            });
+            if (!response.ok) {
+                throw new Error(`Telegram sendMessageDraft failed: ${response.status} ${yield response.text()}`);
+            }
+        });
+    }
+}
+export default TelegramChatSurfaceAdapter;

package/dist/types.d.ts

@@ -0,0 +1,31 @@
+export type TelegramStreamingMode = "draft" | "typing" | "off";
+export type AdapterOptions = {
+    /**
+     * Telegram bot token from BotFather.
+     */
+    botToken: string;
+    /**
+     * Optional secret token configured in Telegram setWebhook.
+     */
+    webhookSecret?: string;
+    /**
+     * Streaming behavior for Telegram responses.
+     * Default is `draft`.
+     */
+    streamingMode?: TelegramStreamingMode;
+    /**
+     * Draft preview update throttle interval.
+     * Default is 650ms.
+     */
+    draftUpdateIntervalMs?: number;
+    /**
+     * AdminForth admin user field that stores Telegram user id.
+     * Default is `telegramId`.
+     */
+    adminUserTelegramIdField?: string;
+    /**
+     * AdminForth admin users resource id.
+     * Default is `adminuser`.
+     */
+    adminUserResourceId?: string;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/index.ts

@@ -0,0 +1,346 @@
+import {
+  AdminForthFilterOperators,
+  type AdminUser,
+  type ChatSurfaceAdapter,
+  type ChatSurfaceEventSink,
+  type ChatSurfaceIncomingMessage,
+  type ChatSurfaceRequestContext,
+  type IAdminForth,
+} from "adminforth";
+import { AdapterOptions } from "./types.js";
+import { randomInt } from "node:crypto";
+export type { AdapterOptions, TelegramStreamingMode } from "./types.js";
+
+type TelegramUpdate = {
+  message?: {
+    text?: string;
+    chat?: {
+      id?: number | string;
+    };
+    from?: {
+      id?: number | string;
+      username?: string;
+      first_name?: string;
+      last_name?: string;
+      language_code?: string;
+    };
+  };
+};
+
+const TELEGRAM_API_BASE_URL = "https://api.telegram.org";
+const TELEGRAM_SECRET_HEADER = "x-telegram-bot-api-secret-token";
+const TELEGRAM_MESSAGE_MAX_LENGTH = 4096;
+const TELEGRAM_DRAFT_MAX_LENGTH = 4096;
+const DEFAULT_DRAFT_UPDATE_INTERVAL_MS = 650;
+const DEFAULT_TYPING_INTERVAL_MS = 4000;
+const DEFAULT_ADMIN_USER_RESOURCE_ID = "adminuser";
+const DEFAULT_ADMIN_USER_TELEGRAM_ID_FIELD = "telegramId";
+
+function createTelegramDraftId() {
+  return randomInt(1, 2147483647);
+}
+
+function truncateTelegramDraft(text: string) {
+  if (text.length <= TELEGRAM_DRAFT_MAX_LENGTH) {
+    return text;
+  }
+
+  return `${text.slice(0, TELEGRAM_DRAFT_MAX_LENGTH - 1)}…`;
+}
+
+function isPrivateChatId(chatId: string) {
+  const numericChatId = Number(chatId);
+
+  return Number.isInteger(numericChatId) && numericChatId > 0;
+}
+
+function getHeaderValue(
+  headers: ChatSurfaceRequestContext["headers"],
+  name: string,
+) {
+  const value = headers[name.toLowerCase()];
+
+  if (Array.isArray(value)) {
+    return String(value[0]);
+  }
+
+  return typeof value === "undefined" ? undefined : String(value);
+}
+
+function splitTelegramMessage(text: string) {
+  const chunks: string[] = [];
+
+  for (let index = 0; index < text.length; index += TELEGRAM_MESSAGE_MAX_LENGTH) {
+    chunks.push(text.slice(index, index + TELEGRAM_MESSAGE_MAX_LENGTH));
+  }
+
+  return chunks;
+}
+
+export class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
+  name = "telegram";
+
+  constructor(private options: AdapterOptions) {}
+
+  validate() {
+    if (!this.options.botToken) {
+      throw new Error("Telegram botToken is required");
+    }
+  }
+
+  async parseIncomingMessage(ctx: ChatSurfaceRequestContext) {
+    if (
+      this.options.webhookSecret
+      && getHeaderValue(ctx.headers, TELEGRAM_SECRET_HEADER) !== this.options.webhookSecret
+    ) {
+      return null;
+    }
+
+    const update = ctx.body as TelegramUpdate;
+    const text = update.message?.text;
+    const chatId = update.message?.chat?.id;
+    const userId = update.message?.from?.id;
+
+    if (!text || chatId === undefined || userId === undefined) {
+      return null;
+    }
+
+    return {
+      surface: this.name,
+      prompt: text,
+      externalConversationId: String(chatId),
+      externalUserId: String(userId),
+      userTimeZone: "UTC",
+      metadata: {
+        telegramUpdate: update,
+      },
+    };
+  }
+
+  createEventSink(
+    ctx: ChatSurfaceRequestContext,
+    incoming: ChatSurfaceIncomingMessage,
+  ): ChatSurfaceEventSink {
+    let text = "";
+    let lastDraftText = "";
+    let draftTimer: ReturnType<typeof setTimeout> | undefined;
+    let typingTimer: ReturnType<typeof setInterval> | undefined;
+    let closed = false;
+    let done = false;
+
+    const chatId = incoming.externalConversationId;
+    const configuredStreamingMode = this.options.streamingMode ?? "draft";
+    const streamingMode =
+      configuredStreamingMode === "draft" && !isPrivateChatId(chatId)
+        ? "typing"
+        : configuredStreamingMode;
+    const draftUpdateIntervalMs =
+      this.options.draftUpdateIntervalMs ?? DEFAULT_DRAFT_UPDATE_INTERVAL_MS;
+    const draftId = createTelegramDraftId();
+
+    const stopTyping = () => {
+      if (typingTimer) {
+        clearInterval(typingTimer);
+        typingTimer = undefined;
+      }
+    };
+
+    const startTyping = () => {
+      if (typingTimer || streamingMode === "off") {
+        return;
+      }
+
+      void this.sendChatAction(chatId, "typing").catch(() => undefined);
+
+      typingTimer = setInterval(() => {
+        void this.sendChatAction(chatId, "typing").catch(() => undefined);
+      }, DEFAULT_TYPING_INTERVAL_MS);
+    };
+
+    const clearDraftTimer = () => {
+      if (draftTimer) {
+        clearTimeout(draftTimer);
+        draftTimer = undefined;
+      }
+    };
+
+    const flushDraft = async () => {
+      if (
+        closed ||
+        done ||
+        streamingMode !== "draft" ||
+        !text
+      ) {
+        return;
+      }
+
+      const draftText = truncateTelegramDraft(text);
+
+      if (draftText === lastDraftText) {
+        return;
+      }
+
+      lastDraftText = draftText;
+
+      await this.sendMessageDraft({
+        chatId,
+        draftId,
+        text: draftText,
+        parseMode: "Markdown",
+      });
+    };
+
+    const scheduleDraftFlush = () => {
+      if (streamingMode !== "draft" || draftTimer) {
+        return;
+      }
+
+      draftTimer = setTimeout(() => {
+        draftTimer = undefined;
+
+        void flushDraft().catch(() => undefined);
+      }, draftUpdateIntervalMs);
+    };
+
+    startTyping();
+
+    return {
+      emit: async (event) => {
+        if (closed) {
+          return;
+        }
+
+        if (event.type === "text_delta") {
+          text += event.delta;
+
+          if (streamingMode === "draft") {
+            scheduleDraftFlush();
+          }
+
+          return;
+        }
+
+        if (event.type === "done") {
+          done = true;
+          stopTyping();
+          clearDraftTimer();
+
+          await this.sendMessage(
+            chatId,
+            text || event.text,
+          );
+          return;
+        }
+
+        if (event.type === "error") {
+          done = true;
+          stopTyping();
+          clearDraftTimer();
+
+          await this.sendMessage(
+            chatId,
+            event.message,
+          );
+        }
+      },
+
+      close: async () => {
+        closed = true;
+        stopTyping();
+        clearDraftTimer();
+      },
+    };
+  }
+
+  async resolveAdminUser(input: {
+    adminforth: IAdminForth;
+    incoming: ChatSurfaceIncomingMessage;
+  }): Promise<AdminUser | null> {
+    const adminUserResourceId = this.options.adminUserResourceId ?? DEFAULT_ADMIN_USER_RESOURCE_ID;
+    const telegramIdField = this.options.adminUserTelegramIdField ?? DEFAULT_ADMIN_USER_TELEGRAM_ID_FIELD;
+    const adminUser = await input.adminforth.resource(adminUserResourceId).get([
+      {
+        field: telegramIdField,
+        operator: AdminForthFilterOperators.EQ,
+        value: input.incoming.externalUserId,
+      },
+    ]);
+
+    if (!adminUser) {
+      return null;
+    }
+
+    return {
+      pk: adminUser.id,
+      username: adminUser[input.adminforth.config.auth!.usernameField],
+      dbUser: adminUser,
+    };
+  }
+
+  private async sendMessage(chatId: string, text: string) {
+    if (!text) {
+      return;
+    }
+
+    for (const chunk of splitTelegramMessage(text)) {
+      const response = await fetch(`${TELEGRAM_API_BASE_URL}/bot${this.options.botToken}/sendMessage`, {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({
+          chat_id: chatId,
+          text: chunk,
+          parse_mode: "Markdown",
+        }),
+      });
+
+      if (!response.ok) {
+        throw new Error(`Telegram sendMessage failed: ${response.status} ${await response.text()}`);
+      }
+    }
+  }
+
+  private async sendChatAction(chatId: string, action: "typing") {
+    const response = await fetch(`${TELEGRAM_API_BASE_URL}/bot${this.options.botToken}/sendChatAction`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        chat_id: chatId,
+        action,
+      }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Telegram sendChatAction failed: ${response.status} ${await response.text()}`);
+    }
+  }
+
+  private async sendMessageDraft(input: {
+    chatId: string;
+    draftId: number;
+    text: string;
+    parseMode?: "Markdown" | "MarkdownV2" | "HTML";
+  }) {
+    const response = await fetch(`${TELEGRAM_API_BASE_URL}/bot${this.options.botToken}/sendMessageDraft`, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        chat_id: Number(input.chatId),
+        draft_id: input.draftId,
+        text: input.text,
+        parse_mode: input.parseMode,
+      }),
+    });
+
+    if (!response.ok) {
+      throw new Error(`Telegram sendMessageDraft failed: ${response.status} ${await response.text()}`);
+    }
+  }
+}
+
+export default TelegramChatSurfaceAdapter;

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@adminforth/chat-surface-adapter-telegram",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "type": "module",
+  "homepage": "https://adminforth.dev/docs/tutorial/Adapters/chat-surface-adapter-telegram/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/devforth/adminforth-chat-surface-adapter-telegram.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc"
+  },
+  "keywords": [
+    "adminforth",
+    "telegram",
+    "chat-surface",
+    "ai-agent"
+  ],
+  "author": "DevForth (https://devforth.io)",
+  "license": "MIT",
+  "description": "AdminForth Agent chat surface adapter for Telegram bots.",
+  "devDependencies": {
+    "semantic-release": "^24.2.9",
+    "semantic-release-slack-bot": "^4.0.2",
+    "typescript": "^5.9.3"
+  },
+  "peerDependencies": {
+    "@adminforth/agent": ">=1.0.2",
+    "adminforth": ">=2.59.0"
+  },
+  "release": {
+    "plugins": [
+      "@semantic-release/commit-analyzer",
+      "@semantic-release/release-notes-generator",
+      "@semantic-release/npm",
+      "@semantic-release/github",
+      [
+        "semantic-release-slack-bot",
+        {
+          "packageName": "@adminforth/chat-surface-adapter-telegram",
+          "notifyOnSuccess": true,
+          "notifyOnFail": true,
+          "slackIcon": ":package:",
+          "markdownReleaseNotes": true
+        }
+      ]
+    ],
+    "branches": [
+      "main",
+      {
+        "name": "next",
+        "prerelease": true
+      }
+    ]
+  }
+}

package/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "compilerOptions": {
+    "target": "es2016",
+    "module": "node16",
+    "outDir": "./dist",
+    "declaration": true,
+    "esModuleInterop": true,
+    "forceConsistentCasingInFileNames": true,
+    "strict": false,
+    "skipLibCheck": true,
+    "strictNullChecks": true
+  },
+  "exclude": ["node_modules", "dist", "custom"]
+}

package/types.ts

@@ -0,0 +1,37 @@
+export type TelegramStreamingMode = "draft" | "typing" | "off";
+
+export type AdapterOptions = {
+  /**
+   * Telegram bot token from BotFather.
+   */
+  botToken: string;
+
+  /**
+   * Optional secret token configured in Telegram setWebhook.
+   */
+  webhookSecret?: string;
+
+  /**
+   * Streaming behavior for Telegram responses.
+   * Default is `draft`.
+   */
+  streamingMode?: TelegramStreamingMode;
+
+  /**
+   * Draft preview update throttle interval.
+   * Default is 650ms.
+   */
+  draftUpdateIntervalMs?: number;
+
+  /**
+   * AdminForth admin user field that stores Telegram user id.
+   * Default is `telegramId`.
+   */
+  adminUserTelegramIdField?: string;
+
+  /**
+   * AdminForth admin users resource id.
+   * Default is `adminuser`.
+   */
+  adminUserResourceId?: string;
+};