ultra-telegram-framework 1.0.3

package/dist/core/context/reply-context.js

@@ -0,0 +1,528 @@
+import { InlineKeyboard, ReplyKeyboard } from "../keyboard";
+import { BaseContext } from "./base-context";
+export class ReplyContext extends BaseContext {
+    async reply(text, options) {
+        const { chatId, messageId } = this.getRequiredIds("reply", false);
+        return this.api.sendMessage({
+            chat_id: chatId,
+            text,
+            reply_parameters: messageId ? { message_id: messageId } : undefined,
+            ...options,
+        });
+    }
+    /**
+     * Reply to the current message with a keyboard (Inline or Reply)
+     * @param text - message text
+     * @param keyboard - keyboard
+     * @param options - parameters object
+     * @returns `Promise<Message>`
+     */
+    async replyWithKeyboard(text, keyboard, options) {
+        const reply_markup = (keyboard instanceof InlineKeyboard || keyboard instanceof ReplyKeyboard)
+            ? keyboard.build()
+            : keyboard;
+        return this.reply(text, {
+            reply_markup: reply_markup,
+            ...options,
+        });
+    }
+    /**
+   * Quick reply with an Inline keyboard
+   * @param text - message text
+   * @param buttons - keyboard
+   * @param options - parameters object
+   * @returns `Promise<Message>`
+   */
+    async replyWithInlineKeyboard(text, buttons, options) {
+        const markup = buttons instanceof InlineKeyboard
+            ? buttons.build()
+            : { inline_keyboard: buttons };
+        return this.reply(text, {
+            reply_markup: markup,
+            ...options,
+        });
+    }
+    /**
+     * Reply to the current message with a photo
+     * @param photo URL of the image or `file_id`
+     * @param options Parameters object or just the notification text
+     * @returns `Promise<Message>`
+     */
+    async replyWithPhoto(photo, options) {
+        const { chatId, messageId } = this.getRequiredIds("replyWithPhoto", false);
+        return this.api.sendPhoto({
+            chat_id: chatId,
+            photo: photo,
+            reply_parameters: messageId ? { message_id: messageId } : undefined,
+            ...options,
+        });
+    }
+    /**
+       * Reply to the current message with a video file
+       * @param video URL of the video or `file_id`
+       * @param options Parameters object or just the notification text
+       * @returns `Promise<Message>`
+       */
+    async replyWithVideo(video, options) {
+        const { chatId, messageId } = this.getRequiredIds("replyWithVideo", false);
+        return this.api.sendVideo({
+            chat_id: chatId,
+            video: video,
+            reply_parameters: messageId ? { message_id: messageId } : undefined,
+            ...options,
+        });
+    }
+    /**
+      * Reply to the current message with a document (file)
+      * @param document URL of the file or `file_id`
+      * @param options Parameters object or just the notification text
+      * @returns `Promise<Message>`
+      */
+    async replyWithDocument(document, options) {
+        const { chatId, messageId } = this.getRequiredIds("replyWithDocument", false);
+        return this.api.sendDocument({
+            chat_id: chatId,
+            document: document,
+            reply_parameters: messageId ? { message_id: messageId } : undefined,
+            ...options,
+        });
+    }
+    /**
+     * Reply to the current message with a "live photo" (Live Photo)
+     * @param photo URL of the photo or `file_id`
+     * @param livePhoto URL of the "live photo" or `file_id`
+     * @param options Parameters object or just the notification text
+     * @returns `Promise<Message>`
+     */
+    async replyWithLivePhoto(photo, livePhoto, options) {
+        const { chatId, messageId } = this.getRequiredIds("replyWithLivePhoto", false);
+        return this.api.sendLivePhoto({
+            chat_id: chatId,
+            photo,
+            live_photo: livePhoto,
+            reply_parameters: messageId ? { message_id: messageId } : undefined,
+            ...options
+        });
+    }
+    /**
+      * Send a gift (Star Gift) to the current user
+      * @param giftId Gift ID
+      * @param options Parameters object
+      * @returns `Promise<boolean>`
+      */
+    async sendGift(giftId, options) {
+        var _a;
+        const fromId = (_a = this.from) === null || _a === void 0 ? void 0 : _a.id;
+        if (!fromId)
+            throw new Error("Cannot send gift: user_id not found.");
+        return this.api.sendGift({
+            user_id: fromId,
+            gift_id: giftId,
+            ...options
+        });
+    }
+    /**
+      * Remove loading indicator from an inline button
+      * @param params Parameters object or just the notification text
+      * @returns `Promise<boolean>`
+      */
+    async answerCbQuery(params) {
+        var _a;
+        // 1. Отримуємо ID виключно з контексту, бо ми заборонили передавати його в params
+        const cbId = (_a = this.callbackQuery) === null || _a === void 0 ? void 0 : _a.id;
+        if (!cbId) {
+            throw new Error("Cannot perform answerCbQuery: callback_query_id not found.");
+        }
+        // 2. If a string is passed, it is shorthand for { text: "..." }
+        if (typeof params === "string") {
+            return this.api.answerCallbackQuery({
+                callback_query_id: cbId,
+                text: params,
+            });
+        }
+        // 3. If an object is passed, use it, adding/overriding the ID
+        return this.api.answerCallbackQuery({
+            ...params,
+            callback_query_id: cbId,
+        });
+    }
+    /**
+  * React to the current message
+  * @param reactions Array of reactions (e.g.: `[{ type: "emoji", emoji: "👍" }]`)
+  * @returns `Promise<boolean>`
+  */
+    async react(reactions) {
+        const { chatId, messageId } = this.getRequiredIds("react", true);
+        return this.api.setMessageReaction({
+            chat_id: chatId,
+            message_id: messageId,
+            reaction: reactions,
+        });
+    }
+    /**
+    * Send chat action status to the current chat (e.g., "typing", "upload_photo")
+    * @param action Action status (e.g., "typing", "upload_photo")
+    * @returns `Promise<boolean>`
+    */
+    async replyWithChatAction(action) {
+        const { chatId } = this.getRequiredIds("replyWithChatAction", false);
+        return this.api.sendChatAction({
+            chat_id: chatId,
+            action: action,
+        });
+    }
+    /**
+      * Delete the current message
+      * @returns `Promise<boolean>`
+      */
+    async deleteMessage() {
+        const { chatId, messageId } = this.getRequiredIds("deleteMessage", true);
+        return this.api.deleteMessage({
+            chat_id: chatId,
+            message_id: messageId,
+        });
+    }
+    /**
+   * Edit the text of the current message
+   * @param text Message text
+   * @param options Additional parameters
+   * @returns `Promise<Message | boolean>`
+   */
+    async editMessage(text, options) {
+        const { chatId, messageId } = this.getRequiredIds("editMessage");
+        return this.api.editMessageText({
+            chat_id: chatId,
+            message_id: messageId,
+            text,
+            ...options,
+        });
+    }
+    /**
+       * Forward the current message to another chat
+       * @param toChatId ID of the chat where the message is forwarded
+       * @returns `Promise<Message>`
+       */
+    async forwardTo(toChatId) {
+        const { chatId, messageId } = this.getRequiredIds("forwardTo", true);
+        return this.api.forwardMessage({
+            chat_id: toChatId,
+            from_chat_id: chatId,
+            message_id: messageId,
+        });
+    }
+    /**
+    * Copy the current message to another chat
+    * @param toChatId ID of the chat where the message is copied
+    * @returns `Promise<MessageId>`
+    */
+    async copyTo(toChatId) {
+        const { chatId, messageId } = this.getRequiredIds("copyTo", true);
+        return this.api.copyMessage({
+            chat_id: toChatId,
+            from_chat_id: chatId,
+            message_id: messageId,
+        });
+    }
+    /**
+     * Returns command arguments (everything that follows the command name).
+     * Example: for the message "/start ref_123", it will return "ref_123".
+     * If it is just "/start", it will return an empty string.
+     * @returns `string`
+     */
+    get payload() {
+        const txt = this.text;
+        if (!txt || !txt.startsWith('/'))
+            return '';
+        const parts = txt.split(/\s+/); // Split by spaces (one or more)
+        if (parts.length <= 1)
+            return '';
+        return parts.slice(1).join(' ').trim();
+    }
+    /**
+     * ID of the user who initiated the event
+     * @returns `number | undefined`
+     */
+    get senderId() {
+        var _a;
+        return (_a = this.from) === null || _a === void 0 ? void 0 : _a.id;
+    }
+    /**
+      * Change only the inline keyboard of the current message
+      * @param replyMarkup - keyboard
+      * @returns `Promise<Message | boolean>`
+      */
+    async editReplyMarkup(replyMarkup) {
+        const { chatId, messageId } = this.getRequiredIds("editReplyMarkup", true);
+        return this.api.editMessageReplyMarkup({
+            chat_id: chatId,
+            message_id: messageId,
+            reply_markup: replyMarkup, // If undefined is passed, the keyboard will disappear
+        });
+    }
+    /**
+   * Change the caption of the current media file (photo/video)
+   * @param caption - caption
+   * @param options - parameters object
+   * @returns `Promise<Message | boolean>`
+   */
+    async editCaption(caption, options) {
+        const { chatId, messageId } = this.getRequiredIds("editCaption", true);
+        return this.api.editMessageCaption({
+            chat_id: chatId,
+            message_id: messageId,
+            caption: caption,
+            ...options,
+        });
+    }
+    /**
+     * Get the list of administrators of the current chat
+     * @returns `Promise<ChatMember[]>`
+     */
+    async getAdministrators() {
+        const { chatId } = this.getRequiredIds("getAdministrators", false);
+        return this.api.getChatAdministrators({ chat_id: chatId });
+    }
+    /**
+     * Get information about a specific member in the current chat
+     * @param userId User ID
+     * @returns `Promise<ChatMember>`
+     */
+    async getMember(userId) {
+        const { chatId } = this.getRequiredIds("getMember", false);
+        return this.api.getChatMember({ chat_id: chatId, user_id: userId });
+    }
+    /**
+     * Leave the current chat (group/channel)
+     * @returns `Promise<boolean>`
+     */
+    async leaveChat() {
+        const { chatId } = this.getRequiredIds("leaveChat", false);
+        return this.api.leaveChat({ chat_id: chatId });
+    }
+    // --- PAYMENTS ---
+    /**
+     * Send an invoice to the current chat
+     * @param params Parameters object
+     * @returns `Promise<Message>`
+     */
+    async replyWithInvoice(params) {
+        const { chatId } = this.getRequiredIds("replyWithInvoice", false);
+        return this.api.sendInvoice({
+            chat_id: chatId,
+            ...params,
+        });
+    }
+    /**
+     * Answer a shipping query (Shipping Query)
+     * @param ok Is everything okay
+     * @param options Additional parameters
+     * @returns `Promise<boolean>`
+     */
+    async answerShippingQuery(ok, options) {
+        var _a;
+        const queryId = (_a = this.update.shipping_query) === null || _a === void 0 ? void 0 : _a.id;
+        if (!queryId)
+            throw new Error("Cannot answer Shipping Query: id not found.");
+        return this.api.answerShippingQuery({
+            shipping_query_id: queryId,
+            ok,
+            ...options,
+        });
+    }
+    /**
+     * Answer a pre-checkout query (Pre-checkout Query)
+     * @param ok Is everything okay
+     * @param errorMessage Error message
+     * @returns `Promise<boolean>`
+     */
+    async answerPreCheckoutQuery(ok, errorMessage) {
+        var _a;
+        const queryId = (_a = this.update.pre_checkout_query) === null || _a === void 0 ? void 0 : _a.id;
+        if (!queryId)
+            throw new Error("Cannot answer Pre-checkout Query: id not found.");
+        return this.api.answerPreCheckoutQuery({
+            pre_checkout_query_id: queryId,
+            ok,
+            error_message: errorMessage,
+        });
+    }
+    // --- GAMES ---
+    /**
+     * Send a game to the current chat
+     * @param gameShortName - short name of the game
+     * @param options - parameters object
+     * @returns `Promise<Message>`
+     */
+    async replyWithGame(gameShortName, options) {
+        const { chatId } = this.getRequiredIds("replyWithGame", false);
+        return this.api.sendGame({
+            chat_id: chatId,
+            game_short_name: gameShortName,
+            ...options,
+        });
+    }
+    /**
+     * Set a high score for a player in the game
+     * @param score - game score
+     * @param options - parameters object
+     * @returns `Promise<Message | boolean>`
+     */
+    async setGameScore(score, options) {
+        var _a, _b;
+        const fromId = (_a = this.from) === null || _a === void 0 ? void 0 : _a.id;
+        if (!fromId)
+            throw new Error("Cannot set game score: user_id not found.");
+        // Priority is given to inline_message_id, if it exists
+        const inlineId = (_b = this.callbackQuery) === null || _b === void 0 ? void 0 : _b.inline_message_id;
+        const { chatId, messageId } = inlineId ? { chatId: undefined, messageId: undefined } : this.getRequiredIds("setGameScore", true);
+        return this.api.setGameScore({
+            user_id: fromId,
+            score,
+            chat_id: chatId,
+            message_id: messageId,
+            inline_message_id: inlineId,
+            ...options,
+        });
+    }
+    /**
+     * Get high scores table for the game
+     * @returns `Promise<GameHighScore[]>`
+     */
+    async getGameHighScores() {
+        var _a, _b;
+        const fromId = (_a = this.from) === null || _a === void 0 ? void 0 : _a.id;
+        if (!fromId)
+            throw new Error("Cannot get game high scores: user_id not found.");
+        const inlineId = (_b = this.callbackQuery) === null || _b === void 0 ? void 0 : _b.inline_message_id;
+        const { chatId, messageId } = inlineId ? { chatId: undefined, messageId: undefined } : this.getRequiredIds("getGameHighScores", true);
+        return this.api.getGameHighScores({
+            user_id: fromId,
+            chat_id: chatId,
+            message_id: messageId,
+            inline_message_id: inlineId,
+        });
+    }
+    /**
+     * Answer a guest query (Guest Mode)
+     * @param result - query result
+     * @param options - parameters object
+     * @returns `Promise<SentGuestMessage>`
+     */
+    async answerGuest(result, options) {
+        var _a;
+        const msg = this.message;
+        const queryId = ((_a = this.update.guest_message) === null || _a === void 0 ? void 0 : _a.guest_query_id) || (msg === null || msg === void 0 ? void 0 : msg.guest_query_id);
+        if (!queryId)
+            throw new Error("Missing guest_query_id");
+        return this.api.answerGuestQuery({
+            guest_query_id: queryId,
+            result: result,
+            ...options
+        });
+    }
+    /**
+     * Delete reaction on the current message.
+     * By default, deletes the reaction of the user who initiated the event.
+     * @param options - parameters object
+     * @returns `Promise<boolean>`
+     */
+    async deleteReaction(options) {
+        var _a;
+        const { chatId, messageId } = this.getRequiredIds("deleteReaction", true);
+        // If the developer did not pass a specific user_id or actor_chat_id, 
+        // by default we substitute the ID of the current user
+        const defaultOptions = (!(options === null || options === void 0 ? void 0 : options.user_id) && !(options === null || options === void 0 ? void 0 : options.actor_chat_id))
+            ? { user_id: (_a = this.from) === null || _a === void 0 ? void 0 : _a.id }
+            : {};
+        return this.api.deleteMessageReaction({
+            chat_id: chatId,
+            message_id: messageId,
+            ...defaultOptions,
+            ...options
+        });
+    }
+    /**
+     * Delete all reactions of a specific user in the current chat (up to 10,000).
+     * By default, deletes the reactions of the user who initiated the event.
+     * @param options - parameters object
+     * @returns `Promise<boolean>`
+     */
+    async deleteAllReactions(options) {
+        var _a;
+        const { chatId } = this.getRequiredIds("deleteAllReactions", false);
+        const defaultOptions = (!(options === null || options === void 0 ? void 0 : options.user_id) && !(options === null || options === void 0 ? void 0 : options.actor_chat_id))
+            ? { user_id: (_a = this.from) === null || _a === void 0 ? void 0 : _a.id }
+            : {};
+        return this.api.deleteAllMessageReactions({
+            chat_id: chatId,
+            ...defaultOptions,
+            ...options
+        });
+    }
+    /**
+     * Send a poll or quiz (Poll / Quiz) to the current chat.
+     * Supports new API 10.0 features: media, explanation_media, 1 answer option.
+     * @param question - poll text
+     * @param pollOptions - answer options
+     * @param options - parameters object
+     * @returns `Promise<Message>`
+     */
+    async replyWithPoll(question, pollOptions, options) {
+        const { chatId, messageId } = this.getRequiredIds("replyWithPoll", false);
+        const formattedOptions = pollOptions.map(option => typeof option === "string" ? { text: option } : option);
+        return this.api.sendPoll({
+            chat_id: chatId,
+            question: question,
+            options: formattedOptions,
+            reply_parameters: messageId ? { message_id: messageId } : undefined,
+            ...options,
+        });
+    }
+    /**
+     * Streaming a temporary message (Draft) for generating responses (e.g., AI).
+     * This ephemeral message lives for 30 seconds. After completion, it is mandatory to call a regular reply().
+     * @param draftId - unique stream identifier (must be > 0). Identical IDs animate changes.
+     * @param options - parameters object
+     * @returns `Promise<boolean>`
+     */
+    async replyWithDraft(draftId, options) {
+        const { chatId } = this.getRequiredIds("replyWithDraft", false);
+        return this.api.sendMessageDraft({
+            chat_id: chatId,
+            draft_id: draftId,
+            ...options,
+        });
+    }
+    /**
+     * Send a group of media files (album).
+     * Supports photos, videos, audio, documents, and new Live Photos (API 10.0).
+     * @param media - array of media files
+     * @param options - parameters object
+     * @returns `Promise<Message[]>`
+     */
+    async replyWithMediaGroup(media, options) {
+        const { chatId, messageId } = this.getRequiredIds("replyWithMediaGroup", false);
+        return this.api.sendMediaGroup({
+            chat_id: chatId,
+            media,
+            reply_parameters: messageId ? { message_id: messageId } : undefined,
+            ...options,
+        });
+    }
+    /**
+     * Send paid media, for viewing which the user must pay with Telegram Stars.
+     * @param starCount - number of stars the user must pay
+     * @param media - array of media files
+     * @param options - parameters object
+     * @returns `Promise<Message>`
+     */
+    async replyWithPaidMedia(starCount, media, options) {
+        const { chatId } = this.getRequiredIds("replyWithPaidMedia", false);
+        return this.api.sendPaidMedia({
+            chat_id: chatId,
+            star_count: starCount,
+            media,
+            ...options,
+        });
+    }
+}

package/dist/core/context.d.ts

@@ -0,0 +1,8 @@
+import { TelegramBotApi, Update } from "../types/telegram";
+import { ReplyContext } from "./context/reply-context";
+export declare class Context extends ReplyContext {
+    constructor(update: Update, api: TelegramBotApi);
+    get from(): import("../types/telegram").User | undefined;
+    get text(): string | undefined;
+    get payload(): string;
+}

package/dist/core/context.js

@@ -0,0 +1,34 @@
+import { ReplyContext } from "./context/reply-context";
+export class Context extends ReplyContext {
+    constructor(update, api) {
+        // Передаємо дані в BaseContext
+        super(update, api);
+    }
+    // Залишаємо специфічні геттери тут
+    get from() {
+        var _a, _b;
+        const msg = this.message;
+        if (msg && "from" in msg)
+            return msg.from;
+        return ((_a = this.callbackQuery) === null || _a === void 0 ? void 0 : _a.from) || ((_b = this.update.inline_query) === null || _b === void 0 ? void 0 : _b.from);
+    }
+    get text() {
+        const msg = this.message;
+        if (!msg)
+            return undefined;
+        if ("text" in msg)
+            return msg.text;
+        if ("caption" in msg)
+            return msg.caption;
+        return undefined;
+    }
+    get payload() {
+        const txt = this.text;
+        if (!txt || !txt.startsWith('/'))
+            return '';
+        const parts = txt.split(/\s+/);
+        if (parts.length <= 1)
+            return '';
+        return parts.slice(1).join(' ').trim();
+    }
+}

package/dist/core/keyboard.d.ts

@@ -0,0 +1,76 @@
+import { KeyboardButton, ReplyKeyboardMarkup, ReplyKeyboardRemove, ForceReply, InlineKeyboardButton, InlineKeyboardMarkup, LoginUrl, SwitchInlineQueryChosenChat, CopyTextButton, CallbackGame, KeyboardButtonRequestUsers, KeyboardButtonRequestChat, KeyboardButtonPollType, KeyboardButtonRequestManagedBot } from '../types/telegram';
+/**
+ * Base interface for any button (so TypeScript knows about common fields)
+ */
+export interface CommonButton {
+    text: string;
+    icon_custom_emoji_id?: string;
+    style?: string;
+}
+/**
+ * Abstract class containing common logic for all keyboard types.
+ * T is the button type (InlineKeyboardButton or KeyboardButton).
+ */
+export declare abstract class BaseKeyboard<T extends CommonButton> {
+    protected matrix: T[][];
+    /** Starts a new row */
+    row(): this;
+    /**
+     * Adds a custom emoji to the LAST added button.
+     * @param emojiId Unique emoji ID (available for Premium bots)
+     */
+    customEmoji(emojiId: string): this;
+    /**
+     * Sets the style for the LAST added button.
+     * @param style 'danger' (red) | 'success' (green) | 'primary' (blue)
+     */
+    style(style: 'danger' | 'success' | 'primary'): this;
+    protected addButton(button: T): this;
+    protected getLastButton(): T | undefined;
+}
+export declare class InlineKeyboard extends BaseKeyboard<InlineKeyboardButton> {
+    text(text: string, callback_data: string): this;
+    url(text: string, url: string): this;
+    webApp(text: string, webAppUrl: string): this;
+    loginUrl(text: string, login_url: LoginUrl): this;
+    switchInlineQuery(text: string, query?: string): this;
+    switchInlineCurrentChat(text: string, query?: string): this;
+    switchInlineChosenChat(text: string, chosen_chat: SwitchInlineQueryChosenChat): this;
+    copyText(text: string, copy_text: CopyTextButton): this;
+    game(text: string, callback_game?: CallbackGame): this;
+    pay(text: string): this;
+    /**
+     * Special button for switching between InlineMenu pages
+     * @param text Button text
+     * @param menuId Menu ID
+     * @param pageId ID of the page to navigate to
+     */
+    menu(text: string, menuId: string, pageId: string): this;
+    /** Builds the final object (uses this.matrix from the base class) */
+    build(): InlineKeyboardMarkup;
+    /** Allows automatic serialization of the object to JSON */
+    toJSON(): InlineKeyboardMarkup;
+}
+export declare class ReplyKeyboard extends BaseKeyboard<KeyboardButton> {
+    private options;
+    /** Adds a regular text button */
+    text(text: string): this;
+    requestContact(text: string): this;
+    requestLocation(text: string): this;
+    requestUsers(text: string, request_users: KeyboardButtonRequestUsers): this;
+    requestChat(text: string, request_chat: KeyboardButtonRequestChat): this;
+    requestPoll(text: string, request_poll?: KeyboardButtonPollType): this;
+    requestManagedBot(text: string, request_managed_bot: KeyboardButtonRequestManagedBot): this;
+    webApp(text: string, webAppUrl: string): this;
+    persistent(is_persistent?: boolean): this;
+    selective(is_selective?: boolean): this;
+    resized(is_resized?: boolean): this;
+    oneTime(is_one_time?: boolean): this;
+    placeholder(text: string): this;
+    /** Builds the final object (uses this.matrix from the base class) */
+    build(): ReplyKeyboardMarkup;
+    /** Allows automatic serialization of the object to JSON */
+    toJSON(): ReplyKeyboardMarkup;
+    static remove(selective?: boolean): ReplyKeyboardRemove;
+    static forceReply(selective?: boolean, placeholder?: string): ForceReply;
+}