chz-telegram-bot 0.4.0 → 0.5.1

package/dtos/chatHistoryMessage.ts

@@ -1,11 +1,11 @@
-import { User } from 'node-telegram-bot-api';
+import { TelegramUser } from '../types/externalAliases';
 import { MessageTypeValue } from '../types/messageTypes';
 import { TraceId } from '../types/trace';
 
 export class ChatHistoryMessage {
     constructor(
         readonly id: number,
-        readonly from: User | undefined,
+        readonly from: TelegramUser | undefined,
         readonly text: string,
         readonly type: MessageTypeValue,
         readonly traceId: TraceId,

package/dtos/incomingMessage.ts

@@ -4,20 +4,20 @@ import { ChatInfo } from './chatInfo';
 import { createTrace } from '../helpers/traceFactory';
 import { TraceId } from '../types/trace';
 import { ChatHistoryMessage } from './chatHistoryMessage';
-import { Message, User } from 'node-telegram-bot-api';
+import { TelegramMessage, TelegramUser } from '../types/externalAliases';
 
 export class IncomingMessage {
     readonly messageId: number;
     readonly chatInfo: ChatInfo;
-    readonly from: User | undefined;
+    readonly from: TelegramUser | undefined;
     readonly text: string;
     readonly type: MessageTypeValue;
     readonly traceId: TraceId;
     readonly replyToMessageId: number | undefined;
 
-    readonly updateObject: Message;
+    readonly updateObject: TelegramMessage;
 
-    private detectMessageType(message: Message) {
+    private detectMessageType(message: TelegramMessage) {
         if ('forward_origin' in message) return MessageType.Forward;
         if ('text' in message) return MessageType.Text;
         if ('video' in message) return MessageType.Video;
@@ -36,7 +36,7 @@ export class IncomingMessage {
     }
 
     constructor(
-        ctxMessage: Message,
+        ctxMessage: TelegramMessage,
         botName: string,
         history: ChatHistoryMessage[]
     ) {
@@ -63,8 +63,8 @@ export class IncomingMessage {
         this.updateObject = ctxMessage;
     }
 
-    private getMessageText(ctxMessage: Message) {
-        if ('text' in ctxMessage) return ctxMessage.text ?? '';
+    private getMessageText(ctxMessage: TelegramMessage) {
+        if ('text' in ctxMessage) return ctxMessage.text;
 
         return 'caption' in ctxMessage ? ctxMessage.caption ?? '' : '';
     }

package/dtos/messageInfo.ts

@@ -1,4 +1,4 @@
-import { Message } from 'node-telegram-bot-api';
+import { TelegramMessage } from '../types/externalAliases';
 import { MessageTypeValue } from '../types/messageTypes';
 
 export class MessageInfo {
@@ -10,6 +10,6 @@ export class MessageInfo {
         /** Type of message being received */
         readonly type: MessageTypeValue,
         /** Message object recieved from Telegram */
-        readonly telegramUpdateObject: Message
+        readonly telegramUpdateObject: TelegramMessage
     ) {}
 }

package/dtos/responses/inlineQueryResponse.ts

@@ -1,5 +1,5 @@
-import { InlineQueryResult } from 'node-telegram-bot-api';
 import { InlineQueryAction } from '../../entities/actions/inlineQueryAction';
+import { TelegramInlineQueryResult } from '../../types/externalAliases';
 import { BotResponseTypes } from '../../types/response';
 import { TraceId } from '../../types/trace';
 
@@ -10,10 +10,10 @@ export class InlineQueryResponse {
     readonly queryId: string;
     readonly traceId: TraceId;
     readonly action: InlineQueryAction;
-    readonly queryResults: InlineQueryResult[];
+    readonly queryResults: TelegramInlineQueryResult[];
 
     constructor(
-        queryResult: InlineQueryResult[],
+        queryResult: TelegramInlineQueryResult[],
         queryId: string,
         traceId: TraceId,
         action: InlineQueryAction

package/dtos/responses/reaction.ts

@@ -2,7 +2,7 @@ import { BotResponseTypes, IChatResponse } from '../../types/response';
 import { IAction } from '../../types/action';
 import { ChatInfo } from '../chatInfo';
 import { TraceId } from '../../types/trace';
-import { TelegramEmoji } from 'node-telegram-bot-api';
+import { TelegramEmoji } from '../../types/externalAliases';
 
 export class Reaction implements IChatResponse {
     readonly kind = BotResponseTypes.react;

package/dtos/responses/textMessage.ts

@@ -8,6 +8,7 @@ import { ChatInfo } from '../chatInfo';
 import { TraceId } from '../../types/trace';
 import { ReplyInfo } from '../replyInfo';
 import { IReplyCapture } from '../../types/capture';
+import { TelegramInlineKeyboardButton } from '../../types/externalAliases';
 
 export class TextMessage implements IReplyResponseWithContent<string> {
     readonly kind = BotResponseTypes.text;
@@ -21,6 +22,7 @@ export class TextMessage implements IReplyResponseWithContent<string> {
     readonly disableWebPreview: boolean;
     readonly shouldPin: boolean;
     readonly action: IAction;
+    readonly keyboard?: TelegramInlineKeyboardButton[][];
 
     constructor(
         text: string,
@@ -37,5 +39,6 @@ export class TextMessage implements IReplyResponseWithContent<string> {
         this.disableWebPreview = options?.disableWebPreview ?? false;
         this.shouldPin = options?.pin ?? false;
         this.action = action;
+        this.keyboard = options?.keyboard;
     }
 }

package/entities/context/inlineQueryContext.ts

@@ -5,7 +5,7 @@ import {
     BaseContextInternal,
     BaseContextPropertiesToOmit
 } from './baseContext';
-import { InlineQueryResult } from 'node-telegram-bot-api';
+import { TelegramInlineQueryResult } from '../../types/externalAliases';
 
 export type InlineQueryContext = Omit<
     InlineQueryContextInternal,
@@ -13,7 +13,7 @@ export type InlineQueryContext = Omit<
 >;
 
 export class InlineQueryContextInternal extends BaseContextInternal<InlineQueryAction> {
-    queryResults: InlineQueryResult[] = [];
+    queryResults: TelegramInlineQueryResult[] = [];
     /**
      * Abort signal to be utilized in query handler.
      * Signal will be aborted if new query comes from the same user.
@@ -42,7 +42,7 @@ export class InlineQueryContextInternal extends BaseContextInternal<InlineQueryA
      * This result will be shown to user as a response to inline query.
      * @param queryResult Inline query result to be shown to user.
      */
-    showInlineQueryResult(queryResult: InlineQueryResult) {
+    showInlineQueryResult(queryResult: TelegramInlineQueryResult) {
         this.queryResults.push(queryResult);
     }
 }

package/entities/context/messageContext.ts

@@ -15,7 +15,7 @@ import { Seconds } from '../../types/timeValues';
 import { BaseContextPropertiesToOmit } from './baseContext';
 import { MessageInfo } from '../../dtos/messageInfo';
 import { UserInfo } from '../../dtos/userInfo';
-import { TelegramEmoji, User } from 'node-telegram-bot-api';
+import { BotInfo, TelegramEmoji } from '../../types/externalAliases';
 
 export type MessageContext<TActionState extends IActionState> = Omit<
     MessageContextInternal<TActionState>,
@@ -37,7 +37,7 @@ export class MessageContextInternal<
     /** Indicates if cooldown should be started after action is executed. Set to `true` by default. */
     startCooldown: boolean = true;
     /** Bot info from Telegram */
-    botInfo!: User;
+    botInfo!: BotInfo;
     customCooldown: Seconds | undefined;
 
     private getQuotePart(quote: boolean | string) {

package/entities/context/replyContext.ts

@@ -16,7 +16,7 @@ import {
 } from './baseContext';
 import { UserInfo } from '../../dtos/userInfo';
 import { MessageInfo } from '../../dtos/messageInfo';
-import { TelegramEmoji, User } from 'node-telegram-bot-api';
+import { TelegramUser, TelegramEmoji } from '../../types/externalAliases';
 
 export type ReplyContext<TActionState extends IActionState> = Omit<
     ReplyContextInternal<TActionState>,
@@ -38,7 +38,7 @@ export class ReplyContextInternal<
     /** Information about the message that triggered this action */
     messageInfo!: MessageInfo;
     /** Bot info from Telegram */
-    botInfo!: User;
+    botInfo!: TelegramUser;
 
     isInitialized = false;
 

package/eslint.config.js

@@ -16,6 +16,7 @@ export default tseslint.config(
             }
         },
         rules: {
+            '@typescript-eslint/switch-exhaustiveness-check': 'error',
             '@typescript-eslint/no-unused-vars': [
                 'error',
                 {

package/index.ts

@@ -7,6 +7,7 @@ export * from './entities/states/actionStateBase';
 export * from './types/messageTypes';
 export * from './helpers/timeConvertions';
 export * from './types/action';
+export * from './types/externalAliases';
 export { CommandAction } from './entities/actions/commandAction';
 export { InlineQueryAction } from './entities/actions/inlineQueryAction';
 export { ReplyCaptureAction } from './entities/actions/replyCaptureAction';

package/package.json

@@ -1,40 +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.4.0",
-    "type": "module",
-    "dependencies": {
-        "async-sema": "^3.1.1",
-        "moment": "^2.29.4",
-        "node-telegram-bot-api": "^0.66.0"
-    },
-    "main": "dist/index.js",
-    "types": "dist/index.d.ts",
-    "devDependencies": {
-        "@types/node-telegram-bot-api": "^0.64.10",
-        "@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"
-    }
-}
+{
+    "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.1",
+    "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

@@ -12,7 +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 'node-telegram-bot-api';
+import { TelegramBot } from '../types/externalAliases';
+import { Telegraf } from 'telegraf';
 
 export class ActionProcessingService {
     private readonly storage: IStorageClient;
@@ -69,10 +70,10 @@ export class ActionProcessingService {
         scheduledPeriod?: Seconds,
         verboseLoggingForIncomingMessage?: boolean
     ) {
-        this.telegramBot = new TelegramBot(token, { polling: true });
+        this.telegramBot = new Telegraf(token);
         const api = new TelegramApiService(
             this.botName,
-            this.telegramBot,
+            this.telegramBot.telegram,
             this.storage,
             this.logger,
             (capture, id, chatInfo, traceId) => {
@@ -85,15 +86,13 @@ export class ActionProcessingService {
             }
         );
 
-        const botInfo = await this.telegramBot.getMe();
+        const botInfo = await this.telegramBot.telegram.getMe();
         const commandActions =
             actions.commands.length > 0 && botInfo.username
                 ? [
                       buildHelpCommand(
                           actions.commands
-                              .map((x) =>
-                                  x.readmeFactory(botInfo.username as string)
-                              )
+                              .map((x) => x.readmeFactory(botInfo.username))
                               .filter((x) => !!x),
                           botInfo.username
                       ),
@@ -120,13 +119,15 @@ export class ActionProcessingService {
             scheduledPeriod ?? hoursToSeconds(1 as Hours)
         );
 
+        void this.telegramBot.launch();
+
         void this.storage.saveMetadata([
             ...actions.scheduled,
             ...commandActions
         ]);
     }
 
-    async stop() {
-        await this.telegramBot.stopPolling();
+    stop() {
+        this.telegramBot.stop();
     }
 }

package/services/actionProcessors/commandActionProcessor.ts

@@ -18,14 +18,14 @@ import { getOrSetIfNotExists } from '../../helpers/mapUtils';
 import { MessageInfo } from '../../dtos/messageInfo';
 import { UserInfo } from '../../dtos/userInfo';
 import { ChatHistoryMessage } from '../../dtos/chatHistoryMessage';
-import TelegramBot from 'node-telegram-bot-api';
+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!: TelegramBot.User;
+    private botInfo!: BotInfo;
 
     private commands = typeSafeObjectFromEntries(
         Object.values(MessageType).map((x) => [
@@ -39,7 +39,7 @@ export class CommandActionProcessor extends BaseActionProcessor {
         telegram: TelegramBot,
         commands: CommandAction<IActionState>[],
         verboseLoggingForIncomingMessage: boolean,
-        botInfo: TelegramBot.User
+        botInfo: BotInfo
     ) {
         this.botInfo = botInfo;
         this.initializeDependencies(api);
@@ -70,11 +70,11 @@ export class CommandActionProcessor extends BaseActionProcessor {
         }
 
         if (commands.length > 0) {
-            telegram.on('message', (msg) => {
+            telegram.on('message', ({ message }) => {
                 const internalMessage = new IncomingMessage(
-                    msg,
+                    message,
                     this.botName,
-                    getOrSetIfNotExists(this.chatHistory, msg.chat.id, [])
+                    getOrSetIfNotExists(this.chatHistory, message.chat.id, [])
                 );
 
                 const logger = this.logger.createScope(
@@ -84,7 +84,7 @@ export class CommandActionProcessor extends BaseActionProcessor {
                 );
 
                 if (verboseLoggingForIncomingMessage) {
-                    logger.logObjectWithTraceId(msg);
+                    logger.logObjectWithTraceId(message);
                 } else {
                     logger.logWithTraceId(
                         `${internalMessage.from?.first_name ?? 'Unknown'} (${

package/services/actionProcessors/inlineQueryActionProcessor.ts

@@ -1,8 +1,8 @@
-import TelegramBot from 'node-telegram-bot-api';
 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';
@@ -25,7 +25,7 @@ export class InlineQueryActionProcessor extends BaseActionProcessor {
         const queriesInProcessing = new Map<number, IncomingInlineQuery>();
 
         if (this.inlineQueries.length > 0) {
-            telegram.on('inline_query', (inlineQuery) => {
+            telegram.on('inline_query', ({ inlineQuery }) => {
                 const query = new IncomingInlineQuery(
                     inlineQuery.id,
                     inlineQuery.query,

package/services/telegramApi.ts

@@ -7,14 +7,13 @@ import { IActionWithState } from '../types/action';
 import { IActionState } from '../types/actionState';
 import { TraceId } from '../types/trace';
 import { ChatInfo } from '../dtos/chatInfo';
-import TelegramBot, { Message } from 'node-telegram-bot-api';
-import { createReadStream } from 'fs';
+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: TelegramBot;
+    private readonly telegram: TelegramApiClient;
     private readonly storage: IStorageClient;
     private readonly logger: ILogger;
     private readonly captureRegistrationCallback: (
@@ -28,7 +27,7 @@ export class TelegramApiService {
 
     constructor(
         botName: string,
-        telegram: TelegramBot,
+        telegram: TelegramApiClient,
         storage: IStorageClient,
         logger: ILogger,
         captureRegistrationCallback: (
@@ -105,7 +104,10 @@ export class TelegramApiService {
         void this.queue.flushReadyItems();
     }
 
-    private async pinIfShould(response: IReplyResponse, message: Message) {
+    private async pinIfShould(
+        response: IReplyResponse,
+        message: TelegramMessage
+    ) {
         if (response.shouldPin) {
             await this.telegram.pinChatMessage(
                 response.chatInfo.id,
@@ -124,11 +126,29 @@ export class TelegramApiService {
     }
 
     private async processResponse(response: BotResponse, ignoreQuote = false) {
-        let sentMessage: Message | null = null;
+        const sentMessage = await this.sendApiRequest(response, ignoreQuote);
+
+        if (sentMessage && 'content' in response) {
+            await this.pinIfShould(response, sentMessage);
+
+            for (const capture of response.captures) {
+                this.captureRegistrationCallback(
+                    capture,
+                    sentMessage.message_id,
+                    response.chatInfo,
+                    response.traceId
+                );
+            }
+        }
+    }
 
+    private async sendApiRequest(
+        response: BotResponse,
+        ignoreQuote: boolean
+    ): Promise<TelegramMessage | null> {
         switch (response.kind) {
             case 'text':
-                sentMessage = await this.telegram.sendMessage(
+                return await this.telegram.sendMessage(
                     response.chatInfo.id,
                     response.content,
                     {
@@ -143,51 +163,54 @@ export class TelegramApiService {
                         parse_mode: 'MarkdownV2',
                         link_preview_options: {
                             is_disabled: response.disableWebPreview
-                        }
+                        },
+                        reply_markup: response.keyboard
+                            ? {
+                                  inline_keyboard: response.keyboard
+                              }
+                            : undefined
                     }
                 );
-                break;
             case 'image':
-                sentMessage = await this.telegram.sendPhoto(
+                return await this.telegram.sendPhoto(
                     response.chatInfo.id,
-                    createReadStream(response.content.source),
+                    response.content,
+                    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
                     response.replyInfo?.id
-                        ? {
-                              reply_to_message_id: response.replyInfo.id
-                          }
+                        ? ({
+                              reply_to_message_id: response.replyInfo.id // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                          } as any)
                         : undefined
                 );
-                break;
             case 'video':
-                sentMessage = await this.telegram.sendVideo(
+                return await this.telegram.sendVideo(
                     response.chatInfo.id,
-                    createReadStream(response.content.source),
+                    response.content,
+                    // eslint-disable-next-line @typescript-eslint/no-unsafe-argument
                     response.replyInfo?.id
-                        ? {
-                              reply_to_message_id: response.replyInfo.id
-                          }
+                        ? ({
+                              reply_to_message_id: response.replyInfo.id // eslint-disable-next-line @typescript-eslint/no-explicit-any
+                          } as any)
                         : undefined
                 );
-                break;
             case 'react':
                 await this.telegram.setMessageReaction(
                     response.chatInfo.id,
                     response.messageId,
-                    {
-                        reaction: [
-                            {
-                                type: 'emoji',
-                                emoji: response.emoji
-                            }
-                        ]
-                    }
+                    [
+                        {
+                            type: 'emoji',
+                            emoji: response.emoji
+                        }
+                    ]
                 );
 
-                return;
+                return null;
             case 'unpin':
-                await this.telegram.unpinChatMessage(response.chatInfo.id, {
-                    message_id: response.messageId
-                });
+                await this.telegram.unpinChatMessage(
+                    response.chatInfo.id,
+                    response.messageId
+                );
 
                 await this.storage.updateStateFor(
                     response.action,
@@ -198,29 +221,18 @@ export class TelegramApiService {
                         );
                     }
                 );
-                break;
+
+                return null;
             case 'inlineQuery':
                 await this.telegram.answerInlineQuery(
                     response.queryId,
                     response.queryResults,
                     { cache_time: 0 }
                 );
-                break;
-            case 'delay':
-                break;
-        }
-
-        if ('content' in response && sentMessage) {
-            await this.pinIfShould(response, sentMessage);
 
-            for (const capture of response.captures) {
-                this.captureRegistrationCallback(
-                    capture,
-                    sentMessage.message_id,
-                    response.chatInfo,
-                    response.traceId
-                );
-            }
+                return null;
+            case 'delay':
+                return null;
         }
     }
 }

package/types/externalAliases.ts

@@ -0,0 +1,18 @@
+import { Telegram, Telegraf } from 'telegraf';
+import {
+    User,
+    Message,
+    InlineQueryResult,
+    UserFromGetMe,
+    TelegramEmoji as Emoji,
+    InlineKeyboardButton
+} from 'telegraf/types';
+
+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;
+export type TelegramInlineKeyboardButton = InlineKeyboardButton;

package/types/messageSendingOptions.ts

@@ -1,7 +1,10 @@
+import { TelegramInlineKeyboardButton } from './externalAliases';
+
 export interface MessageSendingOptions {
     pin?: boolean;
 }
 
 export interface TextMessageSendingOptions extends MessageSendingOptions {
     disableWebPreview?: boolean;
+    keyboard?: TelegramInlineKeyboardButton[][];
 }