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

package/dist/index.d.ts

@@ -1,6 +1,7 @@
-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";
 type TelegramUpdate = {
     message?: {
         text?: string;
@@ -16,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<{
@@ -28,15 +37,14 @@ 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;
     private sendChatAction;
     private sendMessageDraft;
 }

package/dist/index.js

@@ -7,16 +7,17 @@ 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";
 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);
 }
@@ -44,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) {
@@ -68,6 +83,7 @@ export class TelegramChatSurfaceAdapter {
             if (!text || chatId === undefined || userId === undefined) {
                 return null;
             }
+            const startPayload = parseTelegramStartPayload(text);
             return {
                 surface: this.name,
                 prompt: text,
@@ -75,6 +91,7 @@ export class TelegramChatSurfaceAdapter {
                 externalUserId: String(userId),
                 userTimeZone: "UTC",
                 metadata: {
+                    startPayload,
                     telegramUpdate: update,
                 },
             };
@@ -117,13 +134,14 @@ export class TelegramChatSurfaceAdapter {
             }
         };
         const flushDraft = () => __awaiter(this, void 0, void 0, function* () {
+            const draftPreviewText = getFinalMessageStreamPreview(text);
             if (closed ||
                 done ||
                 streamingMode !== "draft" ||
-                !text) {
+                !draftPreviewText) {
                 return;
             }
-            const draftText = truncateTelegramDraft(text);
+            const draftText = truncateTelegramDraft(draftPreviewText);
             if (draftText === lastDraftText) {
                 return;
             }
@@ -161,7 +179,7 @@ export class TelegramChatSurfaceAdapter {
                     done = true;
                     stopTyping();
                     clearDraftTimer();
-                    yield this.sendMessage(chatId, text || event.text);
+                    yield this.sendFinalMessage(chatId, text || event.text);
                     return;
                 }
                 if (event.type === "error") {
@@ -178,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) {
@@ -223,6 +219,32 @@ export class TelegramChatSurfaceAdapter {
             }
         });
     }
+    sendFinalMessage(chatId, text) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const renderedMessage = yield renderFinalMessageImages(text);
+            yield this.sendMessage(chatId, renderedMessage.text);
+            for (const image of renderedMessage.images) {
+                yield this.sendPhoto(chatId, image.buffer, image.filename);
+            }
+        });
+    }
+    sendPhoto(chatId, png, filename) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const photoBytes = new Uint8Array(png);
+            const formData = new FormData();
+            formData.append("chat_id", chatId);
+            formData.append("photo", new Blob([photoBytes], {
+                type: "image/png",
+            }), filename);
+            const response = yield fetch(`${TELEGRAM_API_BASE_URL}/bot${this.options.botToken}/sendPhoto`, {
+                method: "POST",
+                body: formData,
+            });
+            if (!response.ok) {
+                throw new Error(`Telegram sendPhoto 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`, {

package/dist/renderers.d.ts

@@ -0,0 +1,23 @@
+export type RenderTableColumn = string | {
+    key: string;
+    label: string;
+};
+export type RenderTablePngInput = {
+    columns: RenderTableColumn[];
+    rows: Record<string, unknown>[];
+    title?: string;
+};
+export type VegaLiteSpec = Record<string, unknown>;
+export type RenderedMessageImage = {
+    buffer: Buffer;
+    filename: string;
+};
+export type RenderedMessage = {
+    text: string;
+    images: RenderedMessageImage[];
+};
+export declare function getFinalMessageStreamPreview(text: string): string;
+export declare function renderHtmlBlockToPng(html: string, selector: string): Promise<Buffer>;
+export declare function renderTablePng(input: RenderTablePngInput): Promise<Buffer>;
+export declare function renderVegaLitePng(spec: VegaLiteSpec): Promise<Buffer>;
+export declare function renderFinalMessageImages(text: string): Promise<RenderedMessage>;

package/dist/renderers.js

@@ -0,0 +1,361 @@
+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());
+    });
+};
+const DEFAULT_VIEWPORT_WIDTH = 1200;
+const DEFAULT_VIEWPORT_HEIGHT = 800;
+const HTML_ESCAPE_RE = /[&<>"']/g;
+const VEGA_LITE_BLOCK_RE = /```vega-lite\s*([\s\S]*?)```/g;
+const MARKDOWN_TABLE_SEPARATOR_RE = /^\s*\|?\s*:?-{3,}:?\s*(?:\|\s*:?-{3,}:?\s*)+\|?\s*$/;
+const MARKDOWN_TABLE_ROW_RE = /^\s*\|.*\|\s*$/;
+const VEGA_LITE_FENCE_START = "```vega-lite";
+const HTML_ESCAPE_MAP = {
+    "&": "&amp;",
+    "<": "&lt;",
+    ">": "&gt;",
+    '"': "&quot;",
+    "'": "&#39;",
+};
+function escapeHtml(value) {
+    return String(value !== null && value !== void 0 ? value : "").replace(HTML_ESCAPE_RE, (char) => HTML_ESCAPE_MAP[char]);
+}
+function splitMarkdownTableRow(line) {
+    const trimmed = line.trim();
+    const withoutOuterPipes = trimmed.startsWith("|") && trimmed.endsWith("|")
+        ? trimmed.slice(1, -1)
+        : trimmed;
+    return withoutOuterPipes.split("|").map((cell) => cell.trim());
+}
+function parseMarkdownTable(lines) {
+    if (lines.length < 3) {
+        return null;
+    }
+    const headers = splitMarkdownTableRow(lines[0]);
+    const rows = lines.slice(2).map((line) => splitMarkdownTableRow(line));
+    const columns = headers.map((header, index) => ({
+        key: String(index),
+        label: header || `Column ${index + 1}`,
+    }));
+    return {
+        columns,
+        rows: rows.map((row) => Object.fromEntries(columns.map((column, index) => { var _a; return [column.key, (_a = row[index]) !== null && _a !== void 0 ? _a : ""]; }))),
+    };
+}
+function findVegaLiteBlocks(text) {
+    const blocks = [];
+    for (const match of text.matchAll(VEGA_LITE_BLOCK_RE)) {
+        const source = match[0];
+        const json = match[1];
+        const start = match.index;
+        if (start === undefined) {
+            continue;
+        }
+        blocks.push({
+            type: "vega-lite",
+            source,
+            spec: JSON.parse(json),
+            start,
+            end: start + source.length,
+        });
+    }
+    return blocks;
+}
+function findMarkdownTableBlocks(text, occupiedBlocks) {
+    const blocks = [];
+    const lines = text.split("\n");
+    let offset = 0;
+    for (let index = 0; index < lines.length - 1; index += 1) {
+        const headerLine = lines[index];
+        const separatorLine = lines[index + 1];
+        const tableStart = offset;
+        if (occupiedBlocks.some((block) => tableStart >= block.start && tableStart < block.end)
+            || !MARKDOWN_TABLE_ROW_RE.test(headerLine)
+            || !MARKDOWN_TABLE_SEPARATOR_RE.test(separatorLine)) {
+            offset += headerLine.length + 1;
+            continue;
+        }
+        const tableLines = [headerLine, separatorLine];
+        let endLineIndex = index + 2;
+        let tableEnd = tableStart + headerLine.length + 1 + separatorLine.length;
+        while (endLineIndex < lines.length && MARKDOWN_TABLE_ROW_RE.test(lines[endLineIndex])) {
+            tableEnd += 1 + lines[endLineIndex].length;
+            tableLines.push(lines[endLineIndex]);
+            endLineIndex += 1;
+        }
+        const table = parseMarkdownTable(tableLines);
+        if (table) {
+            blocks.push({
+                type: "table",
+                source: tableLines.join("\n"),
+                table,
+                start: tableStart,
+                end: tableEnd,
+            });
+        }
+        for (; index < endLineIndex - 1; index += 1) {
+            offset += lines[index].length + 1;
+        }
+        index -= 1;
+    }
+    return blocks;
+}
+function findFirstMarkdownTableStart(text) {
+    const lines = text.split("\n");
+    let offset = 0;
+    for (let index = 0; index < lines.length - 1; index += 1) {
+        const headerLine = lines[index];
+        const separatorLine = lines[index + 1];
+        if (MARKDOWN_TABLE_ROW_RE.test(headerLine)
+            && MARKDOWN_TABLE_SEPARATOR_RE.test(separatorLine)) {
+            return offset;
+        }
+        offset += headerLine.length + 1;
+    }
+    return -1;
+}
+function getPartialVegaLiteFenceStartLength(text) {
+    for (let length = Math.min(text.length, VEGA_LITE_FENCE_START.length - 1); length > 0; length -= 1) {
+        if (VEGA_LITE_FENCE_START.startsWith(text.slice(-length))) {
+            return length;
+        }
+    }
+    return 0;
+}
+function normalizeTextAfterBlockRemoval(text) {
+    return text
+        .split("\n")
+        .map((line) => line.trimEnd())
+        .join("\n")
+        .replace(/\n{3,}/g, "\n\n")
+        .trim();
+}
+export function getFinalMessageStreamPreview(text) {
+    const vegaLiteStart = text.indexOf(VEGA_LITE_FENCE_START);
+    const tableStart = findFirstMarkdownTableStart(text);
+    const renderableStarts = [vegaLiteStart, tableStart].filter((start) => start >= 0);
+    if (renderableStarts.length) {
+        return text.slice(0, Math.min(...renderableStarts)).trimEnd();
+    }
+    const partialVegaLiteFenceStartLength = getPartialVegaLiteFenceStartLength(text);
+    if (!partialVegaLiteFenceStartLength) {
+        return text;
+    }
+    return text.slice(0, -partialVegaLiteFenceStartLength);
+}
+function getChromium() {
+    return __awaiter(this, void 0, void 0, function* () {
+        const { chromium } = yield import("playwright");
+        return chromium;
+    });
+}
+export function renderHtmlBlockToPng(html, selector) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const chromium = yield getChromium();
+        const browser = yield chromium.launch({
+            headless: true,
+        });
+        try {
+            const page = yield browser.newPage({
+                viewport: {
+                    width: DEFAULT_VIEWPORT_WIDTH,
+                    height: DEFAULT_VIEWPORT_HEIGHT,
+                },
+            });
+            yield page.setContent(html, {
+                waitUntil: "networkidle",
+            });
+            yield page.evaluate(() => document.fonts.ready);
+            const hasRenderReady = yield page.evaluate(() => (Boolean(window.__adminforthRenderReady)));
+            if (hasRenderReady) {
+                yield page.waitForFunction(() => {
+                    const renderState = window;
+                    return renderState.__adminforthRenderDone || renderState.__adminforthRenderError;
+                });
+                const renderError = yield page.evaluate(() => (window.__adminforthRenderError));
+                if (renderError) {
+                    throw new Error(renderError);
+                }
+            }
+            const block = page.locator(selector);
+            yield block.waitFor({
+                state: "visible",
+            });
+            return yield block.screenshot({
+                type: "png",
+                animations: "disabled",
+            });
+        }
+        finally {
+            yield browser.close();
+        }
+    });
+}
+export function renderTablePng(input) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const normalizedColumns = input.columns.map((column) => (typeof column === "string"
+            ? { key: column, label: column }
+            : column));
+        const headerHtml = normalizedColumns
+            .map((column) => `<th>${escapeHtml(column.label)}</th>`)
+            .join("");
+        const rowsHtml = input.rows
+            .map((row) => (`<tr>${normalizedColumns
+            .map((column) => `<td>${escapeHtml(row[column.key])}</td>`)
+            .join("")}</tr>`))
+            .join("");
+        return renderHtmlBlockToPng(`
+    <!doctype html>
+    <html>
+      <head>
+        <meta charset="utf-8" />
+        <style>
+          body {
+            margin: 0;
+            background: #f6f8fa;
+            color: #17202a;
+            font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+          }
+
+          #adminforth-table-render {
+            display: inline-block;
+            padding: 28px;
+            background: #ffffff;
+          }
+
+          h1 {
+            margin: 0 0 18px;
+            font-size: 24px;
+            font-weight: 700;
+          }
+
+          table {
+            border-collapse: collapse;
+            min-width: 560px;
+            max-width: 1120px;
+            font-size: 15px;
+            line-height: 1.45;
+          }
+
+          th,
+          td {
+            padding: 11px 14px;
+            border: 1px solid #d8dee4;
+            text-align: left;
+            vertical-align: top;
+          }
+
+          th {
+            background: #eef2f6;
+            font-weight: 700;
+          }
+
+          tr:nth-child(even) td {
+            background: #f9fbfc;
+          }
+        </style>
+      </head>
+      <body>
+        <section id="adminforth-table-render">
+          ${input.title ? `<h1>${escapeHtml(input.title)}</h1>` : ""}
+          <table>
+            <thead>
+              <tr>${headerHtml}</tr>
+            </thead>
+            <tbody>${rowsHtml}</tbody>
+          </table>
+        </section>
+      </body>
+    </html>
+  `, "#adminforth-table-render");
+    });
+}
+export function renderVegaLitePng(spec) {
+    return __awaiter(this, void 0, void 0, function* () {
+        return renderHtmlBlockToPng(`
+    <!doctype html>
+    <html>
+      <head>
+        <meta charset="utf-8" />
+        <script src="https://cdn.jsdelivr.net/npm/vega@5"></script>
+        <script src="https://cdn.jsdelivr.net/npm/vega-lite@5"></script>
+        <script src="https://cdn.jsdelivr.net/npm/vega-embed@6"></script>
+        <style>
+          body {
+            margin: 0;
+            background: #ffffff;
+            color: #17202a;
+            font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+          }
+
+          #adminforth-vega-lite-render {
+            display: inline-block;
+            padding: 24px;
+            background: #ffffff;
+          }
+
+          #adminforth-vega-lite-render details {
+            display: none;
+          }
+        </style>
+      </head>
+      <body>
+        <section id="adminforth-vega-lite-render"></section>
+        <script>
+          window.__adminforthRenderReady = vegaEmbed(
+            "#adminforth-vega-lite-render",
+            ${JSON.stringify(spec)},
+            { actions: false, renderer: "svg" }
+          )
+            .then(function () {
+              window.__adminforthRenderDone = true;
+            })
+            .catch(function (error) {
+              window.__adminforthRenderError = String(error && error.message ? error.message : error);
+            });
+        </script>
+      </body>
+    </html>
+  `, "#adminforth-vega-lite-render");
+    });
+}
+export function renderFinalMessageImages(text) {
+    return __awaiter(this, void 0, void 0, function* () {
+        const vegaLiteBlocks = findVegaLiteBlocks(text);
+        const tableBlocks = findMarkdownTableBlocks(text, vegaLiteBlocks);
+        const blocks = [...vegaLiteBlocks, ...tableBlocks].sort((a, b) => a.start - b.start);
+        if (!blocks.length) {
+            return {
+                text,
+                images: [],
+            };
+        }
+        const remainingTextParts = [];
+        const images = [];
+        let cursor = 0;
+        for (const [index, block] of blocks.entries()) {
+            remainingTextParts.push(text.slice(cursor, block.start));
+            cursor = block.end;
+            if (block.type === "vega-lite") {
+                images.push({
+                    buffer: yield renderVegaLitePng(block.spec),
+                    filename: `chart-${index + 1}.png`,
+                });
+                continue;
+            }
+            images.push({
+                buffer: yield renderTablePng(block.table),
+                filename: `table-${index + 1}.png`,
+            });
+        }
+        remainingTextParts.push(text.slice(cursor));
+        return {
+            text: normalizeTextAfterBlockRemoval(remainingTextParts.join("")),
+            images,
+        };
+    });
+}

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,15 +1,25 @@
 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";
 import { randomInt } from "node:crypto";
 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";
 
 type TelegramUpdate = {
   message?: {
@@ -27,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);
@@ -77,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) {
@@ -105,6 +140,8 @@ export class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
       return null;
     }
 
+    const startPayload = parseTelegramStartPayload(text);
+
     return {
       surface: this.name,
       prompt: text,
@@ -112,6 +149,7 @@ export class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
       externalUserId: String(userId),
       userTimeZone: "UTC",
       metadata: {
+        startPayload,
         telegramUpdate: update,
       },
     };
@@ -165,16 +203,18 @@ export class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
     };
 
     const flushDraft = async () => {
+      const draftPreviewText = getFinalMessageStreamPreview(text);
+
       if (
         closed ||
         done ||
         streamingMode !== "draft" ||
-        !text
+        !draftPreviewText
       ) {
         return;
       }
 
-      const draftText = truncateTelegramDraft(text);
+      const draftText = truncateTelegramDraft(draftPreviewText);
 
       if (draftText === lastDraftText) {
         return;
@@ -225,7 +265,7 @@ export class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
           stopTyping();
           clearDraftTimer();
 
-          await this.sendMessage(
+          await this.sendFinalMessage(
             chatId,
             text || event.text,
           );
@@ -252,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;
@@ -301,6 +316,34 @@ export class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
     }
   }
 
+  private async sendFinalMessage(chatId: string, text: string) {
+    const renderedMessage = await renderFinalMessageImages(text);
+
+    await this.sendMessage(chatId, renderedMessage.text);
+
+    for (const image of renderedMessage.images) {
+      await this.sendPhoto(chatId, image.buffer, image.filename);
+    }
+  }
+
+  private async sendPhoto(chatId: string, png: Buffer, filename: string) {
+    const photoBytes = new Uint8Array(png);
+    const formData = new FormData();
+    formData.append("chat_id", chatId);
+    formData.append("photo", new Blob([photoBytes], {
+      type: "image/png",
+    }), filename);
+
+    const response = await fetch(`${TELEGRAM_API_BASE_URL}/bot${this.options.botToken}/sendPhoto`, {
+      method: "POST",
+      body: formData,
+    });
+
+    if (!response.ok) {
+      throw new Error(`Telegram sendPhoto 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",
@@ -343,4 +386,4 @@ export class TelegramChatSurfaceAdapter implements ChatSurfaceAdapter {
   }
 }
 
-export default TelegramChatSurfaceAdapter;
+export default TelegramChatSurfaceAdapter;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adminforth/chat-surface-adapter-telegram",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "type": "module",
@@ -29,9 +29,12 @@
     "semantic-release-slack-bot": "^4.0.2",
     "typescript": "^5.9.3"
   },
+  "dependencies": {
+    "playwright": "^1.57.0"
+  },
   "peerDependencies": {
     "@adminforth/agent": ">=1.0.2",
-    "adminforth": ">=2.59.0"
+    "adminforth": ">=2.60.0"
   },
   "release": {
     "plugins": [

package/renderers.ts

@@ -0,0 +1,463 @@
+type PlaywrightChromium = typeof import("playwright").chromium;
+
+export type RenderTableColumn =
+  | string
+  | {
+      key: string;
+      label: string;
+    };
+
+export type RenderTablePngInput = {
+  columns: RenderTableColumn[];
+  rows: Record<string, unknown>[];
+  title?: string;
+};
+
+export type VegaLiteSpec = Record<string, unknown>;
+
+export type RenderedMessageImage = {
+  buffer: Buffer;
+  filename: string;
+};
+
+export type RenderedMessage = {
+  text: string;
+  images: RenderedMessageImage[];
+};
+
+type RenderableBlock =
+  | {
+      type: "vega-lite";
+      source: string;
+      spec: VegaLiteSpec;
+      start: number;
+      end: number;
+    }
+  | {
+      type: "table";
+      source: string;
+      table: RenderTablePngInput;
+      start: number;
+      end: number;
+    };
+
+const DEFAULT_VIEWPORT_WIDTH = 1200;
+const DEFAULT_VIEWPORT_HEIGHT = 800;
+const HTML_ESCAPE_RE = /[&<>"']/g;
+const VEGA_LITE_BLOCK_RE = /```vega-lite\s*([\s\S]*?)```/g;
+const MARKDOWN_TABLE_SEPARATOR_RE = /^\s*\|?\s*:?-{3,}:?\s*(?:\|\s*:?-{3,}:?\s*)+\|?\s*$/;
+const MARKDOWN_TABLE_ROW_RE = /^\s*\|.*\|\s*$/;
+const VEGA_LITE_FENCE_START = "```vega-lite";
+const HTML_ESCAPE_MAP: Record<string, string> = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;",
+};
+
+function escapeHtml(value: unknown) {
+  return String(value ?? "").replace(HTML_ESCAPE_RE, (char) => HTML_ESCAPE_MAP[char]);
+}
+
+function splitMarkdownTableRow(line: string) {
+  const trimmed = line.trim();
+  const withoutOuterPipes = trimmed.startsWith("|") && trimmed.endsWith("|")
+    ? trimmed.slice(1, -1)
+    : trimmed;
+
+  return withoutOuterPipes.split("|").map((cell) => cell.trim());
+}
+
+function parseMarkdownTable(lines: string[]): RenderTablePngInput | null {
+  if (lines.length < 3) {
+    return null;
+  }
+
+  const headers = splitMarkdownTableRow(lines[0]);
+  const rows = lines.slice(2).map((line) => splitMarkdownTableRow(line));
+  const columns = headers.map((header, index) => ({
+    key: String(index),
+    label: header || `Column ${index + 1}`,
+  }));
+
+  return {
+    columns,
+    rows: rows.map((row) => Object.fromEntries(
+      columns.map((column, index) => [column.key, row[index] ?? ""]),
+    )),
+  };
+}
+
+function findVegaLiteBlocks(text: string): RenderableBlock[] {
+  const blocks: RenderableBlock[] = [];
+
+  for (const match of text.matchAll(VEGA_LITE_BLOCK_RE)) {
+    const source = match[0];
+    const json = match[1];
+    const start = match.index;
+
+    if (start === undefined) {
+      continue;
+    }
+
+    blocks.push({
+      type: "vega-lite",
+      source,
+      spec: JSON.parse(json),
+      start,
+      end: start + source.length,
+    });
+  }
+
+  return blocks;
+}
+
+function findMarkdownTableBlocks(text: string, occupiedBlocks: RenderableBlock[]): RenderableBlock[] {
+  const blocks: RenderableBlock[] = [];
+  const lines = text.split("\n");
+  let offset = 0;
+
+  for (let index = 0; index < lines.length - 1; index += 1) {
+    const headerLine = lines[index];
+    const separatorLine = lines[index + 1];
+    const tableStart = offset;
+
+    if (
+      occupiedBlocks.some((block) => tableStart >= block.start && tableStart < block.end)
+      || !MARKDOWN_TABLE_ROW_RE.test(headerLine)
+      || !MARKDOWN_TABLE_SEPARATOR_RE.test(separatorLine)
+    ) {
+      offset += headerLine.length + 1;
+      continue;
+    }
+
+    const tableLines = [headerLine, separatorLine];
+    let endLineIndex = index + 2;
+    let tableEnd = tableStart + headerLine.length + 1 + separatorLine.length;
+
+    while (endLineIndex < lines.length && MARKDOWN_TABLE_ROW_RE.test(lines[endLineIndex])) {
+      tableEnd += 1 + lines[endLineIndex].length;
+      tableLines.push(lines[endLineIndex]);
+      endLineIndex += 1;
+    }
+
+    const table = parseMarkdownTable(tableLines);
+
+    if (table) {
+      blocks.push({
+        type: "table",
+        source: tableLines.join("\n"),
+        table,
+        start: tableStart,
+        end: tableEnd,
+      });
+    }
+
+    for (; index < endLineIndex - 1; index += 1) {
+      offset += lines[index].length + 1;
+    }
+    index -= 1;
+  }
+
+  return blocks;
+}
+
+function findFirstMarkdownTableStart(text: string) {
+  const lines = text.split("\n");
+  let offset = 0;
+
+  for (let index = 0; index < lines.length - 1; index += 1) {
+    const headerLine = lines[index];
+    const separatorLine = lines[index + 1];
+
+    if (
+      MARKDOWN_TABLE_ROW_RE.test(headerLine)
+      && MARKDOWN_TABLE_SEPARATOR_RE.test(separatorLine)
+    ) {
+      return offset;
+    }
+
+    offset += headerLine.length + 1;
+  }
+
+  return -1;
+}
+
+function getPartialVegaLiteFenceStartLength(text: string) {
+  for (let length = Math.min(text.length, VEGA_LITE_FENCE_START.length - 1); length > 0; length -= 1) {
+    if (VEGA_LITE_FENCE_START.startsWith(text.slice(-length))) {
+      return length;
+    }
+  }
+
+  return 0;
+}
+
+function normalizeTextAfterBlockRemoval(text: string) {
+  return text
+    .split("\n")
+    .map((line) => line.trimEnd())
+    .join("\n")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
+}
+
+export function getFinalMessageStreamPreview(text: string) {
+  const vegaLiteStart = text.indexOf(VEGA_LITE_FENCE_START);
+  const tableStart = findFirstMarkdownTableStart(text);
+  const renderableStarts = [vegaLiteStart, tableStart].filter((start) => start >= 0);
+
+  if (renderableStarts.length) {
+    return text.slice(0, Math.min(...renderableStarts)).trimEnd();
+  }
+
+  const partialVegaLiteFenceStartLength = getPartialVegaLiteFenceStartLength(text);
+
+  if (!partialVegaLiteFenceStartLength) {
+    return text;
+  }
+
+  return text.slice(0, -partialVegaLiteFenceStartLength);
+}
+
+async function getChromium(): Promise<PlaywrightChromium> {
+  const { chromium } = await import("playwright");
+
+  return chromium;
+}
+
+export async function renderHtmlBlockToPng(html: string, selector: string): Promise<Buffer> {
+  const chromium = await getChromium();
+  const browser = await chromium.launch({
+    headless: true,
+  });
+
+  try {
+    const page = await browser.newPage({
+      viewport: {
+        width: DEFAULT_VIEWPORT_WIDTH,
+        height: DEFAULT_VIEWPORT_HEIGHT,
+      },
+    });
+
+    await page.setContent(html, {
+      waitUntil: "networkidle",
+    });
+    await page.evaluate(() => document.fonts.ready);
+    const hasRenderReady = await page.evaluate(() => (
+      Boolean((window as typeof window & {
+        __adminforthRenderReady?: Promise<void>;
+      }).__adminforthRenderReady)
+    ));
+
+    if (hasRenderReady) {
+      await page.waitForFunction(() => {
+        const renderState = window as typeof window & {
+          __adminforthRenderDone?: boolean;
+          __adminforthRenderError?: string;
+        };
+
+        return renderState.__adminforthRenderDone || renderState.__adminforthRenderError;
+      });
+
+      const renderError = await page.evaluate(() => (
+        (window as typeof window & {
+          __adminforthRenderError?: string;
+        }).__adminforthRenderError
+      ));
+
+      if (renderError) {
+        throw new Error(renderError);
+      }
+    }
+
+    const block = page.locator(selector);
+    await block.waitFor({
+      state: "visible",
+    });
+
+    return await block.screenshot({
+      type: "png",
+      animations: "disabled",
+    });
+  } finally {
+    await browser.close();
+  }
+}
+
+export async function renderTablePng(input: RenderTablePngInput): Promise<Buffer> {
+  const normalizedColumns = input.columns.map((column) => (
+    typeof column === "string"
+      ? { key: column, label: column }
+      : column
+  ));
+
+  const headerHtml = normalizedColumns
+    .map((column) => `<th>${escapeHtml(column.label)}</th>`)
+    .join("");
+  const rowsHtml = input.rows
+    .map((row) => (
+      `<tr>${
+        normalizedColumns
+          .map((column) => `<td>${escapeHtml(row[column.key])}</td>`)
+          .join("")
+      }</tr>`
+    ))
+    .join("");
+
+  return renderHtmlBlockToPng(`
+    <!doctype html>
+    <html>
+      <head>
+        <meta charset="utf-8" />
+        <style>
+          body {
+            margin: 0;
+            background: #f6f8fa;
+            color: #17202a;
+            font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+          }
+
+          #adminforth-table-render {
+            display: inline-block;
+            padding: 28px;
+            background: #ffffff;
+          }
+
+          h1 {
+            margin: 0 0 18px;
+            font-size: 24px;
+            font-weight: 700;
+          }
+
+          table {
+            border-collapse: collapse;
+            min-width: 560px;
+            max-width: 1120px;
+            font-size: 15px;
+            line-height: 1.45;
+          }
+
+          th,
+          td {
+            padding: 11px 14px;
+            border: 1px solid #d8dee4;
+            text-align: left;
+            vertical-align: top;
+          }
+
+          th {
+            background: #eef2f6;
+            font-weight: 700;
+          }
+
+          tr:nth-child(even) td {
+            background: #f9fbfc;
+          }
+        </style>
+      </head>
+      <body>
+        <section id="adminforth-table-render">
+          ${input.title ? `<h1>${escapeHtml(input.title)}</h1>` : ""}
+          <table>
+            <thead>
+              <tr>${headerHtml}</tr>
+            </thead>
+            <tbody>${rowsHtml}</tbody>
+          </table>
+        </section>
+      </body>
+    </html>
+  `, "#adminforth-table-render");
+}
+
+export async function renderVegaLitePng(spec: VegaLiteSpec): Promise<Buffer> {
+  return renderHtmlBlockToPng(`
+    <!doctype html>
+    <html>
+      <head>
+        <meta charset="utf-8" />
+        <script src="https://cdn.jsdelivr.net/npm/vega@5"></script>
+        <script src="https://cdn.jsdelivr.net/npm/vega-lite@5"></script>
+        <script src="https://cdn.jsdelivr.net/npm/vega-embed@6"></script>
+        <style>
+          body {
+            margin: 0;
+            background: #ffffff;
+            color: #17202a;
+            font-family: Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+          }
+
+          #adminforth-vega-lite-render {
+            display: inline-block;
+            padding: 24px;
+            background: #ffffff;
+          }
+
+          #adminforth-vega-lite-render details {
+            display: none;
+          }
+        </style>
+      </head>
+      <body>
+        <section id="adminforth-vega-lite-render"></section>
+        <script>
+          window.__adminforthRenderReady = vegaEmbed(
+            "#adminforth-vega-lite-render",
+            ${JSON.stringify(spec)},
+            { actions: false, renderer: "svg" }
+          )
+            .then(function () {
+              window.__adminforthRenderDone = true;
+            })
+            .catch(function (error) {
+              window.__adminforthRenderError = String(error && error.message ? error.message : error);
+            });
+        </script>
+      </body>
+    </html>
+  `, "#adminforth-vega-lite-render");
+}
+
+export async function renderFinalMessageImages(text: string): Promise<RenderedMessage> {
+  const vegaLiteBlocks = findVegaLiteBlocks(text);
+  const tableBlocks = findMarkdownTableBlocks(text, vegaLiteBlocks);
+  const blocks = [...vegaLiteBlocks, ...tableBlocks].sort((a, b) => a.start - b.start);
+
+  if (!blocks.length) {
+    return {
+      text,
+      images: [],
+    };
+  }
+
+  const remainingTextParts: string[] = [];
+  const images: RenderedMessageImage[] = [];
+  let cursor = 0;
+
+  for (const [index, block] of blocks.entries()) {
+    remainingTextParts.push(text.slice(cursor, block.start));
+    cursor = block.end;
+
+    if (block.type === "vega-lite") {
+      images.push({
+        buffer: await renderVegaLitePng(block.spec),
+        filename: `chart-${index + 1}.png`,
+      });
+      continue;
+    }
+
+    images.push({
+      buffer: await renderTablePng(block.table),
+      filename: `table-${index + 1}.png`,
+    });
+  }
+
+  remainingTextParts.push(text.slice(cursor));
+
+  return {
+    text: normalizeTextAfterBlockRemoval(remainingTextParts.join("")),
+    images,
+  };
+}

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