ultra-telegram-framework 1.0.3

package/dist/core/keyboard.js

@@ -0,0 +1,182 @@
+/**
+ * Abstract class containing common logic for all keyboard types.
+ * T is the button type (InlineKeyboardButton or KeyboardButton).
+ */
+export class BaseKeyboard {
+    constructor() {
+        // Protected property (available in child classes)
+        this.matrix = [[]];
+    }
+    /** Starts a new row */
+    row() {
+        this.matrix.push([]);
+        return this;
+    }
+    /**
+     * Adds a custom emoji to the LAST added button.
+     * @param emojiId Unique emoji ID (available for Premium bots)
+     */
+    customEmoji(emojiId) {
+        const lastButton = this.getLastButton();
+        if (lastButton)
+            lastButton.icon_custom_emoji_id = emojiId;
+        return this;
+    }
+    /**
+     * Sets the style for the LAST added button.
+     * @param style 'danger' (red) | 'success' (green) | 'primary' (blue)
+     */
+    style(style) {
+        const lastButton = this.getLastButton();
+        if (lastButton)
+            lastButton.style = style;
+        return this;
+    }
+    // =====================================
+    // INTERNAL HELPERS
+    // =====================================
+    addButton(button) {
+        const currentRow = this.matrix[this.matrix.length - 1];
+        if (currentRow) {
+            currentRow.push(button);
+        }
+        return this;
+    }
+    getLastButton() {
+        const currentRow = this.matrix[this.matrix.length - 1];
+        if (!currentRow || currentRow.length === 0)
+            return undefined;
+        return currentRow[currentRow.length - 1];
+    }
+}
+// ============================================================================
+// INLINE KEYBOARD (Buttons under the message)
+// ============================================================================
+export class InlineKeyboard extends BaseKeyboard {
+    text(text, callback_data) {
+        return this.addButton({ text, callback_data });
+    }
+    url(text, url) {
+        return this.addButton({ text, url });
+    }
+    webApp(text, webAppUrl) {
+        return this.addButton({ text, web_app: { url: webAppUrl } });
+    }
+    loginUrl(text, login_url) {
+        return this.addButton({ text, login_url });
+    }
+    switchInlineQuery(text, query = '') {
+        return this.addButton({ text, switch_inline_query: query });
+    }
+    switchInlineCurrentChat(text, query = '') {
+        return this.addButton({ text, switch_inline_query_current_chat: query });
+    }
+    switchInlineChosenChat(text, chosen_chat) {
+        return this.addButton({ text, switch_inline_query_chosen_chat: chosen_chat });
+    }
+    copyText(text, copy_text) {
+        return this.addButton({ text, copy_text });
+    }
+    game(text, callback_game = {}) {
+        return this.addButton({ text, callback_game });
+    }
+    pay(text) {
+        return this.addButton({ text, pay: true });
+    }
+    /**
+     * 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, menuId, pageId) {
+        return this.addButton({ text, callback_data: `menu:${menuId}:${pageId}` });
+    }
+    /** Builds the final object (uses this.matrix from the base class) */
+    build() {
+        const cleanKeyboard = this.matrix.filter(row => row.length > 0);
+        return { inline_keyboard: cleanKeyboard };
+    }
+    /** Allows automatic serialization of the object to JSON */
+    toJSON() {
+        return this.build();
+    }
+}
+// ============================================================================
+// REPLY KEYBOARD (Buttons instead of the phone keyboard)
+// ============================================================================
+export class ReplyKeyboard extends BaseKeyboard {
+    constructor() {
+        super(...arguments);
+        this.options = {};
+    }
+    /** Adds a regular text button */
+    text(text) {
+        return this.addButton({ text });
+    }
+    requestContact(text) {
+        return this.addButton({ text, request_contact: true });
+    }
+    requestLocation(text) {
+        return this.addButton({ text, request_location: true });
+    }
+    requestUsers(text, request_users) {
+        return this.addButton({ text, request_users });
+    }
+    requestChat(text, request_chat) {
+        return this.addButton({ text, request_chat });
+    }
+    requestPoll(text, request_poll = {}) {
+        return this.addButton({ text, request_poll });
+    }
+    requestManagedBot(text, request_managed_bot) {
+        return this.addButton({ text, request_managed_bot });
+    }
+    webApp(text, webAppUrl) {
+        return this.addButton({ text, web_app: { url: webAppUrl } });
+    }
+    // =====================================
+    // KEYBOARD SETTINGS
+    // =====================================
+    persistent(is_persistent = true) {
+        this.options.is_persistent = is_persistent;
+        return this;
+    }
+    selective(is_selective = true) {
+        this.options.selective = is_selective;
+        return this;
+    }
+    resized(is_resized = true) {
+        this.options.resize_keyboard = is_resized;
+        return this;
+    }
+    oneTime(is_one_time = true) {
+        this.options.one_time_keyboard = is_one_time;
+        return this;
+    }
+    placeholder(text) {
+        this.options.input_field_placeholder = text;
+        return this;
+    }
+    /** Builds the final object (uses this.matrix from the base class) */
+    build() {
+        const cleanKeyboard = this.matrix.filter(row => row.length > 0);
+        return {
+            keyboard: cleanKeyboard,
+            ...this.options
+        };
+    }
+    /** Allows automatic serialization of the object to JSON */
+    toJSON() {
+        return this.build();
+    }
+    // =====================================
+    // STATIC HELPERS
+    // =====================================
+    static remove(selective) {
+        return { remove_keyboard: true, selective };
+    }
+    static forceReply(selective, placeholder) {
+        return { force_reply: true, selective, input_field_placeholder: placeholder };
+    }
+}

package/dist/core/menu.d.ts

@@ -0,0 +1,58 @@
+import { Context } from './context';
+import { Composer, Middleware } from './composer';
+import { InlineKeyboard } from './keyboard';
+declare module './context' {
+    interface Context {
+        menu?: InlineMenuManager<any>;
+    }
+}
+export type MenuPageOptions = {
+    /** ID of the page the "Back" button leads to. If not specified, the button will not be shown. */
+    back?: string;
+    /** Text for the "Back" button (default is "⬅️ Back") */
+    backText?: string;
+};
+export type MenuPageRender<C extends Context> = (ctx: C) => Promise<{
+    text: string;
+    keyboard: InlineKeyboard;
+}> | {
+    text: string;
+    keyboard: InlineKeyboard;
+};
+export type PageEntry<C extends Context> = {
+    render: MenuPageRender<C>;
+    options?: MenuPageOptions;
+};
+/**
+ * Class for creating interactive Inline menus.
+ */
+export declare class InlineMenu<C extends Context = Context> extends Composer<C> {
+    private pages;
+    private id;
+    constructor(id?: string);
+    /**
+     * Add a page to the menu
+     * @param id Unique page ID
+     * @param renderer Function that returns text and keyboard
+     * @param options Page settings (e.g., Back button)
+     */
+    page(id: string, renderer: MenuPageRender<C>, options?: MenuPageOptions): this;
+    /**
+     * Main menu middleware
+     */
+    middleware(): Middleware<C>;
+}
+/**
+ * Manager for controlling menus inside handlers
+ */
+export declare class InlineMenuManager<C extends Context = Context> {
+    private ctx;
+    private pages;
+    private menuId;
+    constructor(ctx: C, pages: Map<string, PageEntry<C>>, menuId: string);
+    /**
+     * Go to the specified menu page
+     */
+    setPage(pageId: string): Promise<void>;
+    url(pageId: string): string;
+}

package/dist/core/menu.js

@@ -0,0 +1,87 @@
+import { Composer } from './composer';
+/**
+ * Class for creating interactive Inline menus.
+ */
+export class InlineMenu extends Composer {
+    constructor(id = 'main') {
+        super();
+        this.pages = new Map();
+        this.id = id;
+    }
+    /**
+     * Add a page to the menu
+     * @param id Unique page ID
+     * @param renderer Function that returns text and keyboard
+     * @param options Page settings (e.g., Back button)
+     */
+    page(id, renderer, options) {
+        this.pages.set(id, { render: renderer, options });
+        return this;
+    }
+    /**
+     * Main menu middleware
+     */
+    middleware() {
+        const composerHandler = super.middleware();
+        return async (ctx, next) => {
+            var _a, _b;
+            // 1. Hydrate context with the menu manager
+            ctx.menu = new InlineMenuManager(ctx, this.pages, this.id);
+            // 2. First pass through Composer handlers (.action(), etc.)
+            let handledByComposer = false;
+            await composerHandler(ctx, async () => {
+                handledByComposer = true;
+            });
+            // If Composer caught the event - do not proceed further
+            if (!handledByComposer)
+                return;
+            // 3. If no handler found - check page navigation
+            if ((_b = (_a = ctx.callbackQuery) === null || _a === void 0 ? void 0 : _a.data) === null || _b === void 0 ? void 0 : _b.startsWith(`menu:${this.id}:`)) {
+                const pageId = ctx.callbackQuery.data.split(':')[2];
+                if (pageId) {
+                    await ctx.menu.setPage(pageId);
+                    return;
+                }
+            }
+            await next();
+        };
+    }
+}
+/**
+ * Manager for controlling menus inside handlers
+ */
+export class InlineMenuManager {
+    constructor(ctx, pages, menuId) {
+        this.ctx = ctx;
+        this.pages = pages;
+        this.menuId = menuId;
+    }
+    /**
+     * Go to the specified menu page
+     */
+    async setPage(pageId) {
+        var _a;
+        const entry = this.pages.get(pageId);
+        if (!entry)
+            throw new Error(`Menu page "${pageId}" not found.`);
+        const { text, keyboard } = await Promise.resolve(entry.render(this.ctx));
+        // If a "parent" page is specified in the page settings, add a Back button
+        if ((_a = entry.options) === null || _a === void 0 ? void 0 : _a.back) {
+            keyboard.row().menu(entry.options.backText || '⬅️ Back', this.menuId, entry.options.back);
+        }
+        const rawKeyboard = keyboard.toJSON();
+        if (this.ctx.callbackQuery) {
+            // answerCbQuery is executed together with editMessage to guarantee removing the loading indicator
+            await Promise.all([
+                this.ctx.editMessage(text, { reply_markup: rawKeyboard }),
+                this.ctx.answerCbQuery()
+            ]);
+        }
+        else {
+            await this.ctx.reply(text, { reply_markup: rawKeyboard });
+        }
+    }
+    url(pageId) {
+        return `menu:${this.menuId}:${pageId}`;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @link https://volodymyrdzola.github.io/tg-framework/
+ */
+export * from './core/bot';
+export * from './core/composer';
+export * from './core/context';
+export * from './core/base-api';
+export * from './core/keyboard';
+export * from './core/menu';
+export * from './adapters/gas';
+export * from './adapters/node';
+export * from './adapters/web';
+export * from './session/index';
+export * from './scenes/stage';
+export * from './scenes/wizard';
+export * from './scenes/scene-manager';
+export * from './types/telegram';
+export * from './core/bot';

package/dist/index.js

@@ -0,0 +1,24 @@
+/**
+ * @link https://volodymyrdzola.github.io/tg-framework/
+ */
+// CORE
+export * from './core/bot';
+export * from './core/composer';
+export * from './core/context';
+export * from './core/base-api';
+export * from './core/keyboard';
+export * from './core/menu';
+// ADAPTERS
+export * from './adapters/gas';
+export * from './adapters/node';
+export * from './adapters/web';
+// SESSIONS & STORAGE
+export * from './session/index';
+// SCENES
+export * from './scenes/stage';
+export * from './scenes/wizard';
+export * from './scenes/scene-manager';
+// TYPES
+export * from './types/telegram';
+// ALIASES
+export * from './core/bot';

package/dist/scenes/scene-manager.d.ts

@@ -0,0 +1,39 @@
+export interface SceneSessionData {
+    name?: string;
+    step?: number;
+    state?: Record<string, any>;
+}
+export declare class SceneManager {
+    private ctx;
+    constructor(ctx: {
+        session?: Record<string, any>;
+    });
+    /**
+     * Protected access to the system scene session object.
+     */
+    get session(): SceneSessionData;
+    /**
+     * Storage for temporary data of a specific scene.
+     * Cleared when leaving the scene.
+     */
+    get state(): Record<string, any>;
+    set state(value: Record<string, any>);
+    /**
+     * Enter a new scene
+     * @param name Scene name
+     * @param initialState Initial state (optional)
+     */
+    enter(name: string, initialState?: Record<string, any>): void;
+    /**
+     * Leave the current scene (resets FSM)
+     */
+    leave(): void;
+    /**
+     * Go to the next step in the Wizard scene
+     */
+    next(): void;
+    /**
+     * Go to a specific step by its index
+     */
+    selectStep(index: number): void;
+}

package/dist/scenes/scene-manager.js

@@ -0,0 +1,65 @@
+// src/scenes/scene-manager.ts
+export class SceneManager {
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    /**
+     * Protected access to the system scene session object.
+     */
+    get session() {
+        var _a, _b;
+        var _c, _d;
+        (_a = (_c = this.ctx).session) !== null && _a !== void 0 ? _a : (_c.session = {});
+        (_b = (_d = this.ctx.session).__scene) !== null && _b !== void 0 ? _b : (_d.__scene = {});
+        return this.ctx.session.__scene;
+    }
+    /**
+     * Storage for temporary data of a specific scene.
+     * Cleared when leaving the scene.
+     */
+    get state() {
+        var _a;
+        var _b;
+        (_a = (_b = this.session).state) !== null && _a !== void 0 ? _a : (_b.state = {});
+        return this.session.state;
+    }
+    set state(value) {
+        this.session.state = value;
+    }
+    /**
+     * Enter a new scene
+     * @param name Scene name
+     * @param initialState Initial state (optional)
+     */
+    enter(name, initialState = {}) {
+        var _a;
+        var _b;
+        (_a = (_b = this.ctx).session) !== null && _a !== void 0 ? _a : (_b.session = {});
+        this.ctx.session.__scene = {
+            name,
+            step: 0,
+            state: initialState,
+        };
+    }
+    /**
+     * Leave the current scene (resets FSM)
+     */
+    leave() {
+        if (this.ctx.session && this.ctx.session.__scene) {
+            delete this.ctx.session.__scene;
+        }
+    }
+    /**
+     * Go to the next step in the Wizard scene
+     */
+    next() {
+        var _a;
+        this.session.step = ((_a = this.session.step) !== null && _a !== void 0 ? _a : 0) + 1;
+    }
+    /**
+     * Go to a specific step by its index
+     */
+    selectStep(index) {
+        this.session.step = index;
+    }
+}

package/dist/scenes/stage.d.ts

@@ -0,0 +1,8 @@
+import { Composer, Middleware } from '../core/composer';
+import { SceneContext, WizardScene } from './wizard';
+export declare class Stage<C extends SceneContext> extends Composer<C> {
+    private scenes;
+    constructor(scenes?: WizardScene<C>[]);
+    register(scene: WizardScene<C>): void;
+    middleware(): Middleware<C>;
+}

package/dist/scenes/stage.js

@@ -0,0 +1,34 @@
+// src/scenes/stage.ts
+import { Composer } from '../core/composer';
+import { SceneManager } from './scene-manager';
+export class Stage extends Composer {
+    constructor(scenes = []) {
+        super();
+        this.scenes = new Map();
+        scenes.forEach(scene => this.register(scene));
+    }
+    register(scene) {
+        this.scenes.set(scene.name, scene);
+    }
+    middleware() {
+        const globalHandler = super.middleware();
+        return async (ctx, next) => {
+            // 1. Hydrate context with scene manager
+            ctx.scene = new SceneManager(ctx);
+            const activeSceneName = ctx.scene.session.name;
+            // 2. If the user is NOT in a scene, pass the event to global bot handlers
+            if (!activeSceneName) {
+                return globalHandler(ctx, next);
+            }
+            // 3. If the scene is active, find it
+            const scene = this.scenes.get(activeSceneName);
+            if (!scene) {
+                // Protection against broken sessions: if the scene has been deleted from the code, exit
+                ctx.scene.leave();
+                return globalHandler(ctx, next);
+            }
+            // 4. Pass control to the active scene
+            await scene.middleware()(ctx, next);
+        };
+    }
+}

package/dist/scenes/wizard.d.ts

@@ -0,0 +1,18 @@
+import { Composer, Middleware } from '../core/composer';
+import { Context } from '../core/context';
+import { SceneManager } from './scene-manager';
+import { SessionData } from '../session';
+export interface SceneContext extends Context {
+    session: SessionData;
+    scene: SceneManager;
+}
+export declare class WizardScene<C extends SceneContext> extends Composer<C> {
+    readonly name: string;
+    private steps;
+    /**
+     * @param name Unique name of the scene
+     * @param steps Handler functions for each step (Step 0, Step 1, ...)
+     */
+    constructor(name: string, ...steps: Middleware<C>[]);
+    middleware(): Middleware<C>;
+}

package/dist/scenes/wizard.js

@@ -0,0 +1,32 @@
+// src/scenes/wizard.ts
+import { Composer } from '../core/composer';
+export class WizardScene extends Composer {
+    /**
+     * @param name Unique name of the scene
+     * @param steps Handler functions for each step (Step 0, Step 1, ...)
+     */
+    constructor(name, ...steps) {
+        super();
+        this.name = name;
+        this.steps = steps;
+    }
+    middleware() {
+        const globalHandler = super.middleware();
+        return async (ctx, next) => {
+            var _a;
+            let handledGlobally = false;
+            await globalHandler(ctx, async () => {
+                handledGlobally = true;
+            });
+            if (!handledGlobally)
+                return;
+            const currentStepIndex = (_a = ctx.scene.session.step) !== null && _a !== void 0 ? _a : 0;
+            const stepHandler = this.steps[currentStepIndex];
+            if (!stepHandler) {
+                ctx.scene.leave();
+                return next();
+            }
+            await stepHandler(ctx, next);
+        };
+    }
+}

package/dist/session/gas-cache-storage.d.ts

@@ -0,0 +1,34 @@
+import { Storage } from './storage';
+/**
+ * Session storage for Google Apps Script based on CacheService.
+ * Fast, but data lives for a maximum of 6 hours (21600 seconds).
+ */
+export declare class CacheStorage<T> implements Storage<T> {
+    private cache;
+    private prefix;
+    private ttl;
+    /**
+     * Fast session storage for Google Apps Script based on CacheService.
+     * Data lives for a maximum of 6 hours (21600 seconds).
+     * @param cache Which cache service to use (ScriptCache by default)
+     * @param ttl Time to live in seconds (21600 - 6 hours by default)
+     * @param prefix Prefix for keys
+     */
+    constructor(cache?: GoogleAppsScript.Cache.Cache, ttl?: number, prefix?: string);
+    /**
+     * Gets the session.
+     * @param key Session key
+     */
+    get(key: string): T | undefined;
+    /**
+     * Saves the session.
+     * @param key Session key
+     * @param value Session value
+     */
+    set(key: string, value: T): void;
+    /**
+     * Deletes the session.
+     * @param key Session key
+     */
+    delete(key: string): void;
+}

package/dist/session/gas-cache-storage.js

@@ -0,0 +1,49 @@
+/**
+ * Session storage for Google Apps Script based on CacheService.
+ * Fast, but data lives for a maximum of 6 hours (21600 seconds).
+ */
+export class CacheStorage {
+    /**
+     * Fast session storage for Google Apps Script based on CacheService.
+     * Data lives for a maximum of 6 hours (21600 seconds).
+     * @param cache Which cache service to use (ScriptCache by default)
+     * @param ttl Time to live in seconds (21600 - 6 hours by default)
+     * @param prefix Prefix for keys
+     */
+    constructor(cache = CacheService.getScriptCache(), ttl = 21600, prefix = 'session:') {
+        this.cache = cache;
+        this.ttl = ttl;
+        this.prefix = prefix;
+    }
+    /**
+     * Gets the session.
+     * @param key Session key
+     */
+    get(key) {
+        const raw = this.cache.get(this.prefix + key);
+        if (!raw)
+            return undefined;
+        try {
+            return JSON.parse(raw);
+        }
+        catch (e) {
+            return undefined;
+        }
+    }
+    /**
+     * Saves the session.
+     * @param key Session key
+     * @param value Session value
+     */
+    set(key, value) {
+        const raw = JSON.stringify(value);
+        this.cache.put(this.prefix + key, raw, this.ttl);
+    }
+    /**
+     * Deletes the session.
+     * @param key Session key
+     */
+    delete(key) {
+        this.cache.remove(this.prefix + key);
+    }
+}

package/dist/session/gas-hybrid-storage.d.ts

@@ -0,0 +1,27 @@
+import { Storage } from './storage';
+/**
+ * Hybrid storage for Google Apps Script (CacheService + PropertiesService).
+ * Combines cache speed and properties reliability.
+ */
+export declare class GasHybridStorage<T> implements Storage<T> {
+    private cache;
+    private properties;
+    /**
+     * Hybrid storage for Google Apps Script (CacheService + PropertiesService).
+     * Combines cache speed and properties reliability.
+     * @param options Configuration options
+     * @param options.cache Which cache service to use (ScriptCache by default)
+     * @param options.properties Which properties service to use (ScriptProperties by default)
+     * @param options.ttl Time to live in seconds (21600 - 6 hours by default)
+     * @param options.prefix Prefix for keys
+     */
+    constructor(options?: {
+        cache?: GoogleAppsScript.Cache.Cache;
+        properties?: GoogleAppsScript.Properties.Properties;
+        ttl?: number;
+        prefix?: string;
+    });
+    get(key: string): Promise<T | undefined>;
+    set(key: string, value: T): Promise<void>;
+    delete(key: string): Promise<void>;
+}