@adminforth/chat-surface-adapter-telegram 1.1.0 → 1.1.1

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { type AdminUser, type ChatSurfaceAdapter, type ChatSurfaceEventSink, type ChatSurfaceIncomingMessage, type ChatSurfaceRequestContext, type IAdminForth } from "adminforth";
+import { type ChatSurfaceAdapter, type ChatSurfaceEventSink, type ChatSurfaceIncomingMessage, type ChatSurfaceRequestContext } from "adminforth";
 import { AdapterOptions } from "./types.js";
 export type { AdapterOptions, TelegramStreamingMode } from "./types.js";
 export { getFinalMessageStreamPreview, renderFinalMessageImages, renderHtmlBlockToPng, renderTablePng, renderVegaLitePng, type RenderedMessage, type RenderedMessageImage, type RenderTableColumn, type RenderTablePngInput, type VegaLiteSpec, } from "./renderers.js";
@@ -17,9 +17,17 @@ type TelegramUpdate = {
         };
     };
 };
+type ChatSurfaceConnectAction = {
+    type: "url";
+    label: string;
+    url: string;
+};
 export declare class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
     private options;
     name: string;
+    createConnectAction?: (input: {
+        token: string;
+    }) => ChatSurfaceConnectAction;
     constructor(options: AdapterOptions);
     validate(): void;
     parseIncomingMessage(ctx: ChatSurfaceRequestContext): Promise<{
@@ -29,14 +37,11 @@ export declare class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
         externalUserId: string;
         userTimeZone: string;
         metadata: {
+            startPayload: string | null;
             telegramUpdate: TelegramUpdate;
         };
     } | null>;
     createEventSink(ctx: ChatSurfaceRequestContext, incoming: ChatSurfaceIncomingMessage): ChatSurfaceEventSink;
-    resolveAdminUser(input: {
-        adminforth: IAdminForth;
-        incoming: ChatSurfaceIncomingMessage;
-    }): Promise<AdminUser | null>;
     private sendMessage;
     private sendFinalMessage;
     private sendPhoto;

package/dist/index.js

@@ -7,7 +7,6 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
         step((generator = generator.apply(thisArg, _arguments || [])).next());
     });
 };
-import { AdminForthFilterOperators, } from "adminforth";
 import { getFinalMessageStreamPreview, renderFinalMessageImages } from "./renderers.js";
 import { randomInt } from "node:crypto";
 export { getFinalMessageStreamPreview, renderFinalMessageImages, renderHtmlBlockToPng, renderTablePng, renderVegaLitePng, } from "./renderers.js";
@@ -17,8 +16,8 @@ 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);
 }
@@ -46,10 +45,24 @@ function splitTelegramMessage(text) {
     }
     return chunks;
 }
+function parseTelegramStartPayload(text) {
+    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 {
     constructor(options) {
         this.options = options;
         this.name = "telegram";
+        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) {
@@ -70,6 +83,7 @@ export class TelegramChatSurfaceAdapter {
             if (!text || chatId === undefined || userId === undefined) {
                 return null;
             }
+            const startPayload = parseTelegramStartPayload(text);
             return {
                 surface: this.name,
                 prompt: text,
@@ -77,6 +91,7 @@ export class TelegramChatSurfaceAdapter {
                 externalUserId: String(userId),
                 userTimeZone: "UTC",
                 metadata: {
+                    startPayload,
                     telegramUpdate: update,
                 },
             };
@@ -181,28 +196,6 @@ export class TelegramChatSurfaceAdapter {
             }),
         };
     }
-    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) {

package/dist/types.d.ts

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

package/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,6 +140,8 @@ export class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
       return null;
     }
 
+    const startPayload = parseTelegramStartPayload(text);
+
     return {
       surface: this.name,
       prompt: text,
@@ -125,6 +149,7 @@ export class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
       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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adminforth/chat-surface-adapter-telegram",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -34,7 +34,7 @@
   },
   "peerDependencies": {
     "@adminforth/agent": ">=1.0.2",
-    "adminforth": ">=2.59.0"
+    "adminforth": ">=2.60.0"
   },
   "release": {
     "plugins": [

package/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;
 };