fix: clean up imports and enhance TelegramChatSurfaceAdapter with connect action and start payload parsing

Author: NoOne7135

index.ts

@@ -1,11 +1,8 @@
 import {
-  AdminForthFilterOperators,
-  type AdminUser,
   type ChatSurfaceAdapter,
   type ChatSurfaceEventSink,
   type ChatSurfaceIncomingMessage,
   type ChatSurfaceRequestContext,
-  type IAdminForth,
 } from "adminforth";
 import { AdapterOptions } from "./types.js";
 import { getFinalMessageStreamPreview, renderFinalMessageImages } from "./renderers.js";
@@ -40,14 +37,20 @@ type TelegramUpdate = {
   };
 };
 
+type ChatSurfaceConnectAction = {
+  type: "url";
+  label: string;
+  url: 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";
+const TELEGRAM_START_COMMAND_PREFIX = "/start";
+const TELEGRAM_COMMAND_PARTS_RE = /\s+/;
 
 function createTelegramDraftId() {
   return randomInt(1, 2147483647);
@@ -90,10 +93,29 @@ function splitTelegramMessage(text: string) {
   return chunks;
 }
 
+function parseTelegramStartPayload(text: string) {
+  const [command, ...payloadParts] = text.trim().split(TELEGRAM_COMMAND_PARTS_RE);
+
+  if (command !== TELEGRAM_START_COMMAND_PREFIX && !command.startsWith(`${TELEGRAM_START_COMMAND_PREFIX}@`)) {
+    return null;
+  }
+
+  return payloadParts.join(" ") || null;
+}
+
 export class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
   name = "telegram";
-
-  constructor(private options: AdapterOptions) {}
+  createConnectAction?: (input: { token: string }) => ChatSurfaceConnectAction;
+
+  constructor(private options: AdapterOptions) {
+    if (options.botUsername) {
+      this.createConnectAction = ({ token }) => ({
+        type: "url",
+        label: "Connect Telegram",
+        url: `https://t.me/${options.botUsername}?start=${encodeURIComponent(token)}`,
+      });
+    }
+  }
 
   validate() {
     if (!this.options.botToken) {
@@ -118,13 +140,16 @@ export class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
       return null;
     }
 
+    const startPayload = parseTelegramStartPayload(text);
+
     return {
       surface: this.name,
       prompt: text,
       externalConversationId: String(chatId),
       externalUserId: String(userId),
       userTimeZone: "UTC",
       metadata: {
+        startPayload,
         telegramUpdate: update,
       },
     };
@@ -267,31 +292,6 @@ export class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
     };
   }
 
-  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;

types.ts

@@ -6,6 +6,11 @@ export type AdapterOptions = {
    */
   botToken: string;
 
+  /**
+   * Telegram bot username used to build the AdminForth account-link URL.
+   */
+  botUsername?: string;
+
   /**
    * Optional secret token configured in Telegram setWebhook.
    */
@@ -22,16 +27,4 @@ export type AdapterOptions = {
    * 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;
 };