chz-telegram-bot 0.3.30 → 0.5.0

package/package.json

@@ -1,44 +1,37 @@
-{
-    "name": "chz-telegram-bot",
-    "description": "Opinionated TypeScript framework that provides a structured approach to building Telegram bots.",
-    "author": {
-        "name": "Alex Halanin",
-        "url": "https://github.com/AlexSolari"
-    },
-    "license": "MIT",
-    "keywords": [
-        "telegram",
-        "telegram bot"
-    ],
-    "repository": {
-        "type": "git",
-        "url": "https://github.com/AlexSolari/botFramework.git"
-    },
-    "version": "0.3.30",
-    "type": "module",
-    "dependencies": {
-        "async-sema": "^3.1.1",
-        "moment": "^2.29.4",
-        "telegraf": "^4.16.3"
-    },
-    "main": "dist/index.js",
-    "types": "dist/index.d.ts",
-    "devDependencies": {
-        "@eslint/js": "^9.29.0",
-        "@types/markdown-escape": "^1.1.3",
-        "@types/node": "^22.5.5",
-        "eslint": "^9.29.0",
-        "globals": "^16.2.0",
-        "typescript": "^5.9.0-beta",
-        "typescript-eslint": "^8.34.1"
-    },
-    "scripts": {
-        "build": "tsc",
-        "lint": "npx eslint && tsc --noEmit"
-    },
-    "overrides": {
-        "telegraf": {
-            "node-fetch": "3.3.2"
-        }
-    }
-}
+{
+    "name": "chz-telegram-bot",
+    "description": "Opinionated TypeScript framework that provides a structured approach to building Telegram bots.",
+    "author": {
+        "name": "Alex Halanin",
+        "url": "https://github.com/AlexSolari"
+    },
+    "license": "MIT",
+    "keywords": [
+        "telegram",
+        "telegram bot"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "https://github.com/AlexSolari/botFramework.git"
+    },
+    "version": "0.5.0",
+    "type": "module",
+    "dependencies": {
+        "async-sema": "^3.1.1",
+        "moment": "^2.29.4",
+        "telegraf": "^4.16.3"
+    },
+    "main": "dist/index.js",
+    "types": "dist/index.d.ts",
+    "devDependencies": {
+        "@eslint/js": "^9.29.0",
+        "@types/node": "^22.5.5",
+        "eslint": "^9.29.0",
+        "typescript": "^5.9.0-beta",
+        "typescript-eslint": "^8.34.1"
+    },
+    "scripts": {
+        "build": "tsc",
+        "lint": "npx eslint && tsc --noEmit"
+    }
+}

package/services/actionProcessingService.ts

@@ -1,6 +1,5 @@
 import { hoursToSeconds } from '../helpers/timeConvertions';
 import { Seconds, Milliseconds, Hours } from '../types/timeValues';
-import { Telegraf } from 'telegraf';
 import { ILogger } from '../types/logger';
 import { IScheduler } from '../types/scheduler';
 import { IStorageClient } from '../types/storage';
@@ -13,6 +12,8 @@ import { buildHelpCommand } from '../builtin/helpAction';
 import { CommandActionProcessor } from './actionProcessors/commandActionProcessor';
 import { InlineQueryActionProcessor } from './actionProcessors/inlineQueryActionProcessor';
 import { ScheduledActionProcessor } from './actionProcessors/scheduledActionProcessor';
+import { TelegramBot } from '../types/externalAliases';
+import { Telegraf } from 'telegraf';
 
 export class ActionProcessingService {
     private readonly storage: IStorageClient;
@@ -24,7 +25,7 @@ export class ActionProcessingService {
 
     private readonly botName: string;
 
-    private telegraf!: Telegraf;
+    private telegramBot!: TelegramBot;
 
     constructor(
         botName: string,
@@ -69,10 +70,10 @@ export class ActionProcessingService {
         scheduledPeriod?: Seconds,
         verboseLoggingForIncomingMessage?: boolean
     ) {
-        this.telegraf = new Telegraf(token);
+        this.telegramBot = new Telegraf(token);
         const api = new TelegramApiService(
             this.botName,
-            this.telegraf.telegram,
+            this.telegramBot.telegram,
             this.storage,
             this.logger,
             (capture, id, chatInfo, traceId) => {
@@ -85,9 +86,9 @@ export class ActionProcessingService {
             }
         );
 
-        const botInfo = await this.telegraf.telegram.getMe();
+        const botInfo = await this.telegramBot.telegram.getMe();
         const commandActions =
-            actions.commands.length > 0
+            actions.commands.length > 0 && botInfo.username
                 ? [
                       buildHelpCommand(
                           actions.commands
@@ -101,14 +102,14 @@ export class ActionProcessingService {
 
         this.commandProcessor.initialize(
             api,
-            this.telegraf,
+            this.telegramBot,
             commandActions,
             verboseLoggingForIncomingMessage ?? false,
             botInfo
         );
         this.inlineQueryProcessor.initialize(
             api,
-            this.telegraf,
+            this.telegramBot,
             actions.inlineQueries,
             300 as Milliseconds
         );
@@ -118,15 +119,15 @@ export class ActionProcessingService {
             scheduledPeriod ?? hoursToSeconds(1 as Hours)
         );
 
+        void this.telegramBot.launch();
+
         void this.storage.saveMetadata([
             ...actions.scheduled,
             ...commandActions
         ]);
-
-        void this.telegraf.launch();
     }
 
-    stop(code: string) {
-        this.telegraf.stop(code);
+    stop() {
+        this.telegramBot.stop();
     }
 }

package/services/actionProcessors/commandActionProcessor.ts

@@ -1,4 +1,3 @@
-import { Telegraf } from 'telegraf';
 import { IncomingMessage } from '../../dtos/incomingMessage';
 import { CommandAction } from '../../entities/actions/commandAction';
 import { ReplyCaptureAction } from '../../entities/actions/replyCaptureAction';
@@ -15,18 +14,18 @@ import {
 } from '../../types/messageTypes';
 import { typeSafeObjectFromEntries } from '../../helpers/objectFromEntries';
 import { BaseActionProcessor } from './baseProcessor';
-import { UserFromGetMe } from 'telegraf/types';
 import { getOrSetIfNotExists } from '../../helpers/mapUtils';
 import { MessageInfo } from '../../dtos/messageInfo';
 import { UserInfo } from '../../dtos/userInfo';
 import { ChatHistoryMessage } from '../../dtos/chatHistoryMessage';
+import { BotInfo, TelegramBot } from '../../types/externalAliases';
 
 const MESSAGE_HISTORY_LENGTH_LIMIT = 100;
 
 export class CommandActionProcessor extends BaseActionProcessor {
     private readonly replyCaptures: ReplyCaptureAction<IActionState>[] = [];
     private readonly chatHistory = new Map<number, ChatHistoryMessage[]>();
-    private botInfo!: UserFromGetMe;
+    private botInfo!: BotInfo;
 
     private commands = typeSafeObjectFromEntries(
         Object.values(MessageType).map((x) => [
@@ -37,10 +36,10 @@ export class CommandActionProcessor extends BaseActionProcessor {
 
     initialize(
         api: TelegramApiService,
-        telegraf: Telegraf,
+        telegram: TelegramBot,
         commands: CommandAction<IActionState>[],
         verboseLoggingForIncomingMessage: boolean,
-        botInfo: UserFromGetMe
+        botInfo: BotInfo
     ) {
         this.botInfo = botInfo;
         this.initializeDependencies(api);
@@ -71,30 +70,30 @@ export class CommandActionProcessor extends BaseActionProcessor {
         }
 
         if (commands.length > 0) {
-            telegraf.on('message', (ctx) => {
-                const msg = new IncomingMessage(
-                    ctx.update.message,
+            telegram.on('message', ({ message }) => {
+                const internalMessage = new IncomingMessage(
+                    message,
                     this.botName,
-                    getOrSetIfNotExists(this.chatHistory, ctx.chat.id, [])
+                    getOrSetIfNotExists(this.chatHistory, message.chat.id, [])
                 );
 
                 const logger = this.logger.createScope(
                     this.botName,
-                    msg.traceId,
-                    msg.chatInfo.name
+                    internalMessage.traceId,
+                    internalMessage.chatInfo.name
                 );
 
                 if (verboseLoggingForIncomingMessage) {
-                    logger.logObjectWithTraceId(ctx.update.message);
+                    logger.logObjectWithTraceId(message);
                 } else {
                     logger.logWithTraceId(
-                        `${msg.from?.first_name ?? 'Unknown'} (${
-                            msg.from?.id ?? 'Unknown'
-                        }): ${msg.text || msg.type}`
+                        `${internalMessage.from?.first_name ?? 'Unknown'} (${
+                            internalMessage.from?.id ?? 'Unknown'
+                        }): ${internalMessage.text || internalMessage.type}`
                     );
                 }
 
-                void this.processMessage(msg);
+                void this.processMessage(internalMessage);
             });
         }
     }

package/services/actionProcessors/inlineQueryActionProcessor.ts

@@ -1,8 +1,8 @@
-import { Telegraf } from 'telegraf';
 import { IncomingInlineQuery } from '../../dtos/incomingQuery';
 import { InlineQueryAction } from '../../entities/actions/inlineQueryAction';
 import { InlineQueryContextInternal } from '../../entities/context/inlineQueryContext';
 import { createTrace } from '../../helpers/traceFactory';
+import { TelegramBot } from '../../types/externalAliases';
 import { Milliseconds } from '../../types/timeValues';
 import { TraceId } from '../../types/trace';
 import { TelegramApiService } from '../telegramApi';
@@ -13,7 +13,7 @@ export class InlineQueryActionProcessor extends BaseActionProcessor {
 
     initialize(
         api: TelegramApiService,
-        telegraf: Telegraf,
+        telegram: TelegramBot,
         inlineQueries: InlineQueryAction[],
         period: Milliseconds
     ) {
@@ -25,12 +25,12 @@ export class InlineQueryActionProcessor extends BaseActionProcessor {
         const queriesInProcessing = new Map<number, IncomingInlineQuery>();
 
         if (this.inlineQueries.length > 0) {
-            telegraf.on('inline_query', (ctx) => {
+            telegram.on('inline_query', ({ inlineQuery }) => {
                 const query = new IncomingInlineQuery(
-                    ctx.inlineQuery.id,
-                    ctx.inlineQuery.query,
-                    ctx.inlineQuery.from.id,
-                    createTrace('InlineQuery', this.botName, ctx.inlineQuery.id)
+                    inlineQuery.id,
+                    inlineQuery.query,
+                    inlineQuery.from.id,
+                    createTrace('InlineQuery', this.botName, inlineQuery.id)
                 );
 
                 const logger = this.logger.createScope(
@@ -40,9 +40,9 @@ export class InlineQueryActionProcessor extends BaseActionProcessor {
                 );
 
                 logger.logWithTraceId(
-                    `${ctx.inlineQuery.from.username ?? 'Unknown'} (${
-                        ctx.inlineQuery.from.id
-                    }): Query for ${ctx.inlineQuery.query}`
+                    `${inlineQuery.from.username ?? 'Unknown'} (${
+                        inlineQuery.from.id
+                    }): Query for ${inlineQuery.query}`
                 );
 
                 const queryBeingProcessed = queriesInProcessing.get(

package/services/jsonLogger.ts

@@ -1,39 +1,42 @@
-/* eslint-disable @typescript-eslint/no-unsafe-member-access */
-/* eslint-disable @typescript-eslint/no-explicit-any */
 import { ILogger, IScopedLogger } from '../types/logger';
 import { TraceId } from '../types/trace';
 
 export class JsonLogger implements ILogger {
-    private serializeError(error: any) {
-        const plainObject: Record<string, unknown> = {};
-        Object.getOwnPropertyNames(error).forEach(function (key) {
-            plainObject[key] = error[key];
-        });
-        return JSON.stringify(plainObject);
+    private serializeError(error: unknown): string {
+        if (error instanceof Error) {
+            const plainObject: Record<string, unknown> = {
+                name: error.name,
+                message: error.message,
+                stack: error.stack
+            };
+
+            for (const [key, value] of Object.entries(error)) {
+                plainObject[key] = value;
+            }
+
+            return JSON.stringify(plainObject);
+        }
+
+        return JSON.stringify({ error });
     }
 
     private getCircularReplacer() {
-        const ancestors: unknown[] = [];
-        return function <V>(this: V, _: unknown, value: V) {
-            if (typeof value !== 'object' || value === null) {
-                return value;
-            }
-            // `this` is the object that value is contained in,
-            // i.e., its direct parent.
-            while (ancestors.length > 0 && ancestors.at(-1) !== this) {
-                ancestors.pop();
-            }
-            if (ancestors.includes(value)) {
-                return '[Circular]';
+        const cache = new Set();
+        return <T>(_: string, value: T) => {
+            if (typeof value === 'object' && value !== null) {
+                if (cache.has(value)) {
+                    return;
+                }
+
+                cache.add(value);
             }
-            ancestors.push(value);
             return value;
         };
     }
 
     createScope(botName: string, traceId: TraceId, chatName: string) {
         return {
-            logObjectWithTraceId: (data: any) => {
+            logObjectWithTraceId: (data: unknown) => {
                 this.logObjectWithTraceId(botName, traceId, chatName, data);
             },
             logWithTraceId: (text: string) => {
@@ -55,12 +58,24 @@ export class JsonLogger implements ILogger {
         botName: string,
         traceId: TraceId,
         chatName: string,
-        data: any
+        data: unknown
     ) {
-        data.botName = botName;
-        data.traceId = traceId;
-        data.chatName = chatName;
-        console.log(data);
+        const enrichedData =
+            typeof data == 'object'
+                ? {
+                      ...data,
+                      botName,
+                      traceId,
+                      chatName
+                  }
+                : {
+                      botName,
+                      traceId,
+                      chatName,
+                      data
+                  };
+
+        console.log(enrichedData);
     }
 
     logWithTraceId(

package/services/telegramApi.ts

@@ -1,7 +1,5 @@
-import { Message } from 'telegraf/types';
 import { IStorageClient } from '../types/storage';
 import { BotResponse, IReplyResponse } from '../types/response';
-import { Telegram } from 'telegraf/typings/telegram';
 import { ILogger } from '../types/logger';
 import { QueueItem, ResponseProcessingQueue } from './responseProcessingQueue';
 import { IReplyCapture } from '../types/capture';
@@ -9,13 +7,13 @@ import { IActionWithState } from '../types/action';
 import { IActionState } from '../types/actionState';
 import { TraceId } from '../types/trace';
 import { ChatInfo } from '../dtos/chatInfo';
-import { TelegramError } from 'telegraf';
+import { TelegramApiClient, TelegramMessage } from '../types/externalAliases';
 
 export const TELEGRAM_ERROR_QUOTE_INVALID = 'QUOTE_TEXT_INVALID';
 
 export class TelegramApiService {
     private readonly queue = new ResponseProcessingQueue();
-    private readonly telegram: Telegram;
+    private readonly telegram: TelegramApiClient;
     private readonly storage: IStorageClient;
     private readonly logger: ILogger;
     private readonly captureRegistrationCallback: (
@@ -29,7 +27,7 @@ export class TelegramApiService {
 
     constructor(
         botName: string,
-        telegram: Telegram,
+        telegram: TelegramApiClient,
         storage: IStorageClient,
         logger: ILogger,
         captureRegistrationCallback: (
@@ -67,8 +65,10 @@ export class TelegramApiService {
                     try {
                         await this.processResponse(response);
                     } catch (error) {
-                        if ('message' in (error as TelegramError)) {
-                            const telegramResponse = error as TelegramError;
+                        if ('message' in (error as { message?: string })) {
+                            const telegramResponse = error as {
+                                message: string;
+                            };
 
                             if (
                                 telegramResponse.message.includes(
@@ -104,11 +104,14 @@ export class TelegramApiService {
         void this.queue.flushReadyItems();
     }
 
-    private async pinIfShould(response: IReplyResponse, sentMessage: Message) {
+    private async pinIfShould(
+        response: IReplyResponse,
+        message: TelegramMessage
+    ) {
         if (response.shouldPin) {
             await this.telegram.pinChatMessage(
                 response.chatInfo.id,
-                sentMessage.message_id,
+                message.message_id,
                 { disable_notification: true }
             );
 
@@ -116,14 +119,14 @@ export class TelegramApiService {
                 response.action as IActionWithState<IActionState>,
                 response.chatInfo.id,
                 (state) => {
-                    state.pinnedMessages.push(sentMessage.message_id);
+                    state.pinnedMessages.push(message.message_id);
                 }
             );
         }
     }
 
     private async processResponse(response: BotResponse, ignoreQuote = false) {
-        let sentMessage: Message | null = null;
+        let sentMessage: TelegramMessage | null = null;
 
         switch (response.kind) {
             case 'text':
@@ -179,8 +182,7 @@ export class TelegramApiService {
                             type: 'emoji',
                             emoji: response.emoji
                         }
-                    ],
-                    true
+                    ]
                 );
 
                 return;

package/types/externalAliases.ts

@@ -0,0 +1,17 @@
+import {
+    User,
+    Message,
+    InlineQueryResult,
+    TelegramEmoji as Emoji,
+    UserFromGetMe
+} from 'telegraf/typings/core/types/typegram';
+import { Telegraf } from 'telegraf';
+import Telegram from 'telegraf/typings/telegram';
+
+export type TelegramUser = User;
+export type TelegramMessage = Message;
+export type TelegramInlineQueryResult = InlineQueryResult;
+export type TelegramEmoji = Emoji;
+export type TelegramApiClient = Telegram;
+export type BotInfo = UserFromGetMe;
+export type TelegramBot = Telegraf;

package/types/inputFile.ts

@@ -0,0 +1,4 @@
+export interface InputFile {
+    source: string;
+    filename?: string;
+}

package/types/logger.ts

@@ -1,10 +1,7 @@
 import { TraceId } from './trace';
 
 export interface IScopedLogger {
-    logObjectWithTraceId(
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        data: any
-    ): void;
+    logObjectWithTraceId(data: unknown): void;
 
     logWithTraceId(text: string): void;
 
@@ -22,8 +19,7 @@ export interface ILogger {
         botName: string,
         traceId: TraceId,
         chatName: string,
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        data: any
+        data: unknown
     ): void;
 
     logWithTraceId(

package/types/messageTypes.ts

@@ -1,5 +1,3 @@
-import { Message, Update } from 'telegraf/types';
-
 export const INTERNAL_MESSAGE_TYPE_PREFIX = `__msg:`;
 
 export const MessageType = {
@@ -21,5 +19,3 @@ export const MessageType = {
 } as const;
 
 export type MessageTypeValue = (typeof MessageType)[keyof typeof MessageType];
-
-export type TelegrafContextMessage = Update.New & (Update.NonChannel & Message);