@codebam/cf-workers-telegram-bot 12.6.4 → 12.6.6

package/README.md

@@ -119,8 +119,25 @@ npx wrangler deploy
 
 To automate deployments, use the [Wrangler Action](https://github.com/cloudflare/wrangler-action) or Cloudflare's built-in [GitHub integration](https://developers.cloudflare.com/workers/ci-cd/github-actions/).
 
+## Structure
+
+This is a monorepo containing:
+- Root: Core library `@codebam/cf-workers-telegram-bot`
+- `ai-workflow`: A Cloudflare Workflow for handling long-running AI tasks
+- `webapp`: A Svelte 5 web application for interacting with the bot
+- `consumer`: A minimal consumer of the library
+
 ## Development
 
+You can use the root `Makefile` to run common tasks across all projects:
+
+```sh
+make build   # Build all projects
+make test    # Run tests for all projects
+make lint    # Lint all projects
+make format  # Format all projects
+```
+
 ### Setup
 
 1. **Install dependencies**:

package/dist/ai.d.ts

@@ -0,0 +1,23 @@
+import TelegramExecutionContext from './telegram_execution_context';
+/**
+ * Robustly extract text from various AI response formats.
+ * Handles OpenAI, Cloudflare, and Google Gemini structures.
+ */
+export declare function extractText(obj: any): string;
+/**
+ * Custom runner that supports tool calls across different AI models.
+ */
+export declare function customRunWithTools(ai: any, model: string, input: {
+    messages: any[];
+    tools?: any[];
+}, config: {
+    streamFinalResponse: boolean;
+}): Promise<any>;
+/**
+ * Stream AI response to Telegram, with periodic updates to avoid rate limits.
+ */
+export declare function streamAiResponseToTelegram(bot: TelegramExecutionContext, ai: any, modelId: string, messages: any[], task: any, tools?: any[]): Promise<string>;
+/**
+ * Creates a mock TelegramExecutionContext for use in environments where the full context isn't available (e.g., Workflows).
+ */
+export declare function createMockTelegramExecutionContext(task: Record<string, unknown>): TelegramExecutionContext;

package/dist/ai.js

@@ -0,0 +1,381 @@
+import TelegramApi from './telegram_api';
+import { markdownToHtml } from './utils';
+/**
+ * Robustly extract text from various AI response formats.
+ * Handles OpenAI, Cloudflare, and Google Gemini structures.
+ */
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export function extractText(obj) {
+    if (typeof obj === 'string') {
+        return obj;
+    }
+    if (typeof obj !== 'object' || obj === null) {
+        return '';
+    }
+    // Direct fields
+    if (typeof obj.response === 'string') {
+        return obj.response;
+    }
+    if (typeof obj.text === 'string') {
+        return obj.text;
+    }
+    if (typeof obj.content === 'string') {
+        return obj.content;
+    }
+    if (typeof obj.delta === 'string') {
+        return obj.delta;
+    }
+    // Nested fields
+    if (obj.choices && Array.isArray(obj.choices) && obj.choices.length > 0) {
+        return extractText(obj.choices[0]);
+    }
+    if (obj.message) {
+        return extractText(obj.message);
+    }
+    if (obj.delta) {
+        return extractText(obj.delta);
+    }
+    if (obj.candidates && Array.isArray(obj.candidates) && obj.candidates.length > 0) {
+        return extractText(obj.candidates[0]);
+    }
+    if (obj.content) {
+        return extractText(obj.content);
+    }
+    if (obj.parts && Array.isArray(obj.parts) && obj.parts.length > 0) {
+        return extractText(obj.parts[0]);
+    }
+    return '';
+}
+/**
+ * Custom runner that supports tool calls across different AI models.
+ */
+export async function customRunWithTools(
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+ai, model, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+input, config) {
+    const messages = [...input.messages];
+    const tools = input.tools || [];
+    const isGemini = model.includes('google/gemini');
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const cfTools = tools.map((t) => ({
+        type: 'function',
+        function: {
+            name: t.name,
+            description: t.description,
+            parameters: t.parameters,
+        },
+    }));
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const runModel = async (msgs, stream) => {
+        if (isGemini) {
+            const systemMessage = msgs.find((m) => m.role === 'system');
+            const otherMessages = msgs.filter((m) => m.role !== 'system');
+            const geminiInput = {
+                contents: otherMessages.map((m) => ({
+                    role: m.role === 'assistant' ? 'model' : 'user',
+                    parts: [{ text: m.content }],
+                })),
+                stream,
+            };
+            if (systemMessage) {
+                geminiInput.system_instruction = {
+                    parts: [{ text: systemMessage.content }],
+                };
+            }
+            return await ai.run(model, geminiInput);
+        }
+        return await ai.run(model, { messages: msgs, tools: cfTools.length > 0 ? cfTools : undefined, stream });
+    };
+    if (cfTools.length === 0 || isGemini) {
+        return await runModel(messages, config.streamFinalResponse);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const response = (await runModel(messages, false));
+    // FIX: Robustly extract from BOTH Cloudflare formats (Standard and OpenAI-compatible)
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let toolCalls = [];
+    if (response?.tool_calls) {
+        toolCalls = [...response.tool_calls];
+    }
+    else if (response?.choices?.[0]?.message?.tool_calls) {
+        toolCalls = [...response.choices[0].message.tool_calls];
+    }
+    let responseText = response?.response || response?.choices?.[0]?.message?.content || '';
+    // GEMMA/LLAMA FALLBACK: Catch raw tokens if native interception fails
+    if (toolCalls.length === 0) {
+        const gemmaRegex = /<\|tool_call>\s*call:\s*([a-zA-Z0-9_]+)([\s\S]*?)<tool_call\|>/g;
+        const standardRegex = /<tool_call>\s*([\s\S]*?)\s*<\/tool_call>/g;
+        let match;
+        while ((match = gemmaRegex.exec(responseText)) !== null) {
+            let name = match[1].trim();
+            if (name === 'http_fetch' || name === 'api_fetch') {
+                name = 'fetch';
+            }
+            let argsString = match[2].trim();
+            // Sanitize malformed JSON syntax
+            argsString = argsString.replace(/([{,]\s*)([a-zA-Z0-9_]+)\s*:/g, '$1"$2":').replace(/:\s*'([^']*)'/g, ': "$1"');
+            toolCalls.push({
+                id: `call_${Math.random().toString(36).substring(2, 9)}`,
+                type: 'function',
+                function: { name, arguments: argsString },
+            });
+        }
+        while ((match = standardRegex.exec(responseText)) !== null) {
+            const content = match[1].trim();
+            try {
+                // Handle both raw JSON and name/args format
+                const parsed = JSON.parse(content.replace(/'/g, '"'));
+                const name = parsed.name || 'fetch';
+                const args = parsed.arguments || parsed;
+                toolCalls.push({
+                    id: `call_${Math.random().toString(36).substring(2, 9)}`,
+                    type: 'function',
+                    function: { name, arguments: typeof args === 'string' ? args : JSON.stringify(args) },
+                });
+            }
+            catch (e) {
+                console.error('Failed to parse tool call:', content, e);
+            }
+        }
+        // Strip the raw tokens from the visible response
+        responseText = responseText
+            .replace(/<\|tool_call>[\s\S]*?<tool_call\|>/g, '')
+            .replace(/<tool_call>[\s\S]*?<\/tool_call>/g, '')
+            .trim();
+    }
+    if (toolCalls.length > 0) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        const normalizedToolCalls = toolCalls.map((call, index) => {
+            const name = call.name || (call.function && call.function.name);
+            let args = call.arguments || (call.function && call.function.arguments);
+            if (typeof args !== 'string') {
+                try {
+                    args = JSON.stringify(args);
+                }
+                catch {
+                    args = '{}';
+                }
+            }
+            return {
+                id: call.id || `call_${Math.random().toString(36).substring(2, 9)}_${index}`,
+                type: 'function',
+                function: { name, arguments: args },
+            };
+        });
+        messages.push({
+            role: 'assistant',
+            content: responseText,
+            tool_calls: normalizedToolCalls,
+        });
+        for (const call of normalizedToolCalls) {
+            const toolName = call.function.name;
+            const toolId = call.id;
+            const toolArgsString = call.function.arguments;
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            const tool = tools.find((t) => t.name === toolName);
+            if (tool && tool.function) {
+                try {
+                    let parsedArgs;
+                    try {
+                        parsedArgs = JSON.parse(toolArgsString);
+                    }
+                    catch {
+                        parsedArgs = toolArgsString;
+                    }
+                    const result = await tool.function(parsedArgs);
+                    messages.push({ role: 'tool', tool_call_id: toolId, name: toolName, content: String(result) });
+                }
+                catch (e) {
+                    messages.push({ role: 'tool', tool_call_id: toolId, name: toolName, content: String(e) });
+                }
+            }
+            else {
+                messages.push({ role: 'tool', tool_call_id: toolId, name: toolName, content: 'Tool not found' });
+            }
+        }
+        return await runModel(messages, true);
+    }
+    return response;
+}
+/**
+ * Stream AI response to Telegram, with periodic updates to avoid rate limits.
+ */
+export async function streamAiResponseToTelegram(bot, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+ai, modelId, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+messages, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+task, 
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+tools = []) {
+    const botApi = new TelegramApi();
+    // Use updateId as a stable draftId if available, otherwise generate one
+    const draftId = task.updateId || Date.now();
+    // Skip Thinking message for guest messages and business messages as they only support one response or don't support drafts
+    if (task.updateType !== 'guest_message' && task.updateType !== 'business_message') {
+        await botApi.sendMessageDraft(`https://api.telegram.org/bot${task.telegramToken || task.token}`, {
+            chat_id: task.chatId,
+            text: 'Thinking...',
+            parse_mode: 'HTML',
+            message_thread_id: task.threadId,
+            business_connection_id: task.businessConnectionId,
+            draft_id: draftId,
+        });
+    }
+    let streamContent = '';
+    let lastUpdate = Date.now();
+    try {
+        const aiResponse = await customRunWithTools(ai, modelId, {
+            messages,
+            tools,
+        }, { streamFinalResponse: true });
+        if (typeof aiResponse === 'object' && aiResponse !== null && 'getReader' in aiResponse) {
+            const stream = aiResponse;
+            const reader = stream.getReader();
+            const decoder = new TextDecoder();
+            while (true) {
+                const { done, value } = await reader.read();
+                if (done) {
+                    break;
+                }
+                const chunk = decoder.decode(value, { stream: true });
+                const lines = chunk.split('\n');
+                for (const line of lines) {
+                    if (line.startsWith('data: ')) {
+                        const data = line.slice(6);
+                        if (data === '[DONE]') {
+                            break;
+                        }
+                        try {
+                            const parsed = JSON.parse(data);
+                            const text = extractText(parsed);
+                            streamContent += text;
+                        }
+                        catch {
+                            // Ignore malformed JSON chunks
+                        }
+                    }
+                }
+                // Update Telegram every 2 seconds to avoid rate limits
+                if (task.updateType !== 'guest_message' &&
+                    task.updateType !== 'business_message' &&
+                    Date.now() - lastUpdate > 2000 &&
+                    streamContent.trim()) {
+                    const currentContent = streamContent;
+                    bot
+                        .streamReply(await markdownToHtml(currentContent + '...'), draftId, 'HTML')
+                        .catch((e) => console.error('Streaming error:', e));
+                    lastUpdate = Date.now();
+                }
+            }
+        }
+        else {
+            // Handle static response
+            streamContent = extractText(aiResponse);
+        }
+    }
+    catch (e) {
+        console.error('Error reading AI stream:', e);
+    }
+    // Send final response (blocking)
+    if (streamContent.trim()) {
+        await bot.streamReply(await markdownToHtml(streamContent), draftId, 'HTML', {}, true);
+    }
+    return streamContent;
+}
+/**
+ * Creates a mock TelegramExecutionContext for use in environments where the full context isn't available (e.g., Workflows).
+ */
+export function createMockTelegramExecutionContext(task) {
+    return {
+        chat: { id: task.chatId },
+        from: { id: task.userId },
+        update_type: task.updateType,
+        reply: async (text, options = {}) => {
+            const api = new TelegramApi();
+            if (task.updateType === 'guest_message' && task.guestQueryId) {
+                return await api.answerGuestQuery(`https://api.telegram.org/bot${task.telegramToken || task.token}`, {
+                    guest_query_id: task.guestQueryId,
+                    result: {
+                        type: 'article',
+                        id: crypto.randomUUID(),
+                        title: 'Response',
+                        input_message_content: { message_text: text, parse_mode: (options.parse_mode || 'HTML') },
+                    },
+                });
+            }
+            return await api.sendMessage(`https://api.telegram.org/bot${task.telegramToken || task.token}`, {
+                chat_id: task.chatId,
+                text,
+                parse_mode: (options.parse_mode || 'HTML'),
+                reply_markup: options.reply_markup,
+                message_thread_id: task.threadId,
+                business_connection_id: task.businessConnectionId,
+                reply_to_message_id: task.messageId,
+            });
+        },
+        streamReply: async (text, draft_id, parse_mode = '', options = {}, finish = false) => {
+            const api = new TelegramApi();
+            if (task.updateType === 'guest_message' || task.updateType === 'business_message') {
+                if (finish) {
+                    if (task.updateType === 'guest_message' && task.guestQueryId) {
+                        return await api.answerGuestQuery(`https://api.telegram.org/bot${task.telegramToken || task.token}`, {
+                            guest_query_id: task.guestQueryId,
+                            result: {
+                                type: 'article',
+                                id: crypto.randomUUID(),
+                                title: 'Response',
+                                input_message_content: { message_text: text, parse_mode: (parse_mode || 'HTML') },
+                            },
+                        });
+                    }
+                    return await api.sendMessage(`https://api.telegram.org/bot${task.telegramToken || task.token}`, {
+                        chat_id: task.chatId,
+                        text,
+                        parse_mode: (parse_mode || 'HTML'),
+                        reply_markup: options.reply_markup,
+                        message_thread_id: task.threadId,
+                        business_connection_id: task.businessConnectionId,
+                        reply_to_message_id: task.messageId,
+                    });
+                }
+                return null;
+            }
+            if (finish) {
+                // Send a final message draft to signal the end of animation
+                await api.sendMessageDraft(`https://api.telegram.org/bot${task.telegramToken || task.token}`, {
+                    chat_id: task.chatId,
+                    text,
+                    parse_mode: (parse_mode || 'HTML'),
+                    draft_id,
+                    message_thread_id: task.threadId,
+                    business_connection_id: task.businessConnectionId,
+                    finish: true,
+                    ...options,
+                });
+                // Then send the actual final message as a reply
+                return await api.sendMessage(`https://api.telegram.org/bot${task.telegramToken || task.token}`, {
+                    chat_id: task.chatId,
+                    text,
+                    parse_mode: (parse_mode || 'HTML'),
+                    reply_markup: options.reply_markup,
+                    message_thread_id: task.threadId,
+                    business_connection_id: task.businessConnectionId,
+                    reply_to_message_id: task.messageId,
+                });
+            }
+            return await api.sendMessageDraft(`https://api.telegram.org/bot${task.telegramToken || task.token}`, {
+                chat_id: task.chatId,
+                text,
+                parse_mode: (parse_mode || 'HTML'),
+                draft_id,
+                message_thread_id: task.threadId,
+                business_connection_id: task.businessConnectionId,
+                finish: false,
+                ...options,
+            });
+        },
+    };
+}

package/dist/main.d.ts

@@ -9,5 +9,6 @@ import PartialTelegramUpdate from './types/PartialTelegramUpdate.js';
 import TelegramInlineQueryType from './types/TelegramInlineQueryType.js';
 import { markdownToHtml, fetchTool } from './utils.js';
 import { HistoryManager, getBalance } from './history_manager.js';
+export { extractText, customRunWithTools, streamAiResponseToTelegram, createMockTelegramExecutionContext } from './ai.js';
 export default TelegramBot;
 export { TelegramBot, TelegramExecutionContext, Webhook, TelegramApi, TelegramApiBaseParams, SendMessageParams, SendMessageDraftParams, SendPhotoParams, SendVideoParams, SendVoiceParams, SendChatActionParams, AnswerCallbackParams, AnswerInlineParams, AnswerGuestParams, SendInvoiceParams, AnswerPreCheckoutParams, TelegramApiParams, TelegramCommand, TelegramFrom, TelegramChat, TelegramUser, TelegramMessageEntity, TelegramPhotoSize, TelegramMessage, TelegramVoice, TelegramGuestMessage, TelegramInputMessageContent, TelegramInlineQuery, TelegramUpdate, PartialTelegramUpdate, TelegramInlineQueryType, TelegramInlineQueryResult, TelegramInlineQueryResultPhoto, TelegramInlineQueryResultArticle, TelegramInlineQueryResultVideo, TelegramInlineQueryResultVoice, ChatPermissions, TelegramBusinessMessage, TelegramCallbackQuery, TelegramPreCheckoutQuery, TelegramDocument, TelegramSuccessfulPayment, markdownToHtml, fetchTool, HistoryManager, getBalance, };

package/dist/main.js

@@ -4,5 +4,6 @@ import Webhook from './webhook.js';
 import TelegramApi from './telegram_api.js';
 import { markdownToHtml, fetchTool } from './utils.js';
 import { HistoryManager, getBalance } from './history_manager.js';
+export { extractText, customRunWithTools, streamAiResponseToTelegram, createMockTelegramExecutionContext } from './ai.js';
 export default TelegramBot;
 export { TelegramBot, TelegramExecutionContext, Webhook, TelegramApi, markdownToHtml, fetchTool, HistoryManager, getBalance, };

package/dist/telegram_execution_context.js

@@ -477,9 +477,9 @@ export default class TelegramExecutionContext {
      * @returns Promise with the API response
      */
     async streamReply(message, draft_id, parse_mode = '', options = {}, finish = false) {
-        if (this.update_type === 'guest_message') {
+        if (this.update_type === 'guest_message' || this.update_type === 'business_message') {
             if (finish) {
-                return await this.answerGuestQueryText(message, parse_mode);
+                return await this.reply(message, parse_mode, true, options);
             }
             return null;
         }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@codebam/cf-workers-telegram-bot",
-	"version": "12.6.4",
+	"version": "12.6.6",
 	"description": "serverless telegram bot on cf workers",
 	"main": "./dist/main.js",
 	"module": "./dist/main.js",
@@ -29,7 +29,7 @@
 		"test:all": "npm test && npm test --prefix ai-workflow && npm test --prefix consumer && npm test --prefix webapp",
 		"format": "prettier --write src test *.json *.js *.mjs",
 		"format:check": "prettier --check src test *.json *.js *.mjs",
-		"docs": "typedoc --options typedoc.json",
+		"docs": "typedoc --options typedoc.json && node fix-docs.js",
 		"deploy:docs": "npm run docs && wrangler pages deploy docs",
 		"ncu": "npx npm-check-updates -u --root",
 		"ncu:interactive": "npx npm-check-updates -i --root",
@@ -43,6 +43,7 @@
 	},
 	"devDependencies": {
 		"@cloudflare/vitest-pool-workers": "^0.16.6",
+		"@eslint/compat": "^2.1.0",
 		"@eslint/js": "^10.0.1",
 		"@types/node": "^25.8.0",
 		"@typescript-eslint/eslint-plugin": "^8.59.3",