grambot 1.0.0

package/dist/telebot.d.ts

@@ -0,0 +1,142 @@
+import { Bot } from "grammy";
+import type { ActionHandler, ActionRef, LayoutBuilderInterface, MenuRef, TelebotConfig, TelebotContext } from "./types.js";
+/**
+ * # Telebot
+ *
+ * The main entry-point for building Telegram bots declaratively.
+ *
+ * ### Quick Start
+ * ```ts
+ * import { Telebot } from "@superpackages/telebot";
+ * import mainMenu from "./menus/main.js";
+ *
+ * const bot = Telebot.create({
+ *   token: process.env.BOT_TOKEN!,
+ *   menu: mainMenu,
+ * });
+ *
+ * bot.start();
+ * ```
+ */
+/**
+ * Helper to build actions or menus attached to specific triggers.
+ * Used internally by the {@link Telebot} class.
+ */
+declare class TriggerBuilder {
+    private triggers;
+    /**
+     * @internal
+     */
+    constructor(type: "command" | "word" | "regexp", value: string | RegExp);
+    /**
+     * Add a command trigger (e.g., /settings).
+     * @param name - The command name without the leading slash.
+     */
+    command(name: string): TriggerBuilder;
+    /**
+     * Add an exact word or phrase trigger.
+     * @param text - The text to trigger on.
+     */
+    word(text: string): TriggerBuilder;
+    /**
+     * Add a regular expression trigger.
+     * @param pattern - The regex pattern to match against the message text.
+     */
+    regexp(pattern: RegExp): TriggerBuilder;
+    /**
+     * Attach an action to the collected triggers.
+     * @param handler - The function to handle the action.
+     * @returns An {@link ActionRef} that can be used in menus.
+     */
+    action<P = undefined>(handler: ActionHandler<P>): ActionRef<P>;
+    /**
+     * Attach a menu to the collected triggers.
+     * @param builder - A function to build the menu layout.
+     * @param options - Optional menu settings.
+     * @returns A {@link MenuRef} that can be used or sent.
+     */
+    menu(builder: (layout: LayoutBuilderInterface, ctx: TelebotContext) => void | Promise<void>, options?: {
+        id?: string;
+    }): MenuRef;
+}
+/**
+ * The main entry-point for building Telegram bots declaratively.
+ *
+ * Provides static methods to create triggers, actions, and menus.
+ */
+export declare class Telebot {
+    /**
+     * Create a trigger based on a command (e.g., `/start`).
+     * @param name - The command name.
+     */
+    static command(name: string): TriggerBuilder;
+    /**
+     * Create a trigger based on an exact word or phrase.
+     * @param text - The text to match.
+     */
+    static word(text: string): TriggerBuilder;
+    /**
+     * Create a trigger based on a regular expression.
+     * @param pattern - The pattern to match.
+     */
+    static regexp(pattern: RegExp): TriggerBuilder;
+    /**
+     * Create a typed action with an optional payload generic.
+     * @param handler - The logic to execute when the action is triggered.
+     */
+    static action<P = undefined>(handler: ActionHandler<P>): ActionRef<P>;
+    /**
+     * Create a declarative menu.
+     * @param builder - A layout builder function.
+     * @param options - Optional configuration (e.g., fixed ID).
+     */
+    static menu(builder: (layout: LayoutBuilderInterface, ctx: TelebotContext) => void | Promise<void>, options?: {
+        id?: string;
+    }): MenuRef;
+    /**
+     * Create a fully configured bot instance.
+     * @param options - Configuration including token and root menu.
+     */
+    static create(options: TelebotConfig & {
+        menu: MenuRef;
+    }): TelebotApp;
+}
+/**
+ * A running bot instance with the menu tree installed.
+ *
+ * Created via {@link Telebot.create}.
+ */
+export declare class TelebotApp {
+    /** The underlying grammy bot instance. */
+    readonly bot: Bot<TelebotContext>;
+    private readonly config;
+    private readonly rootMenu;
+    private readonly installPromise;
+    /**
+     * @internal Use {@link Telebot.create} instead.
+     */
+    constructor(options: TelebotConfig & {
+        menu: MenuRef;
+    });
+    /**
+     * Start the bot using long-polling.
+     */
+    start(): Promise<void>;
+    /**
+     * Manually send the root menu to a specific chat.
+     * @param chatId - The recipient chat ID.
+     * @param ctx - The current context.
+     */
+    sendMenu(chatId: number, ctx: TelebotContext): Promise<void>;
+    /**
+     * Returns a callback function for webhook usage.
+     * @see grammy documentation for parameters.
+     */
+    webhookCallback(path?: string, onTimeout?: "throw" | "return" | "continue", timeoutMilliseconds?: number): (req: any, res: any, next?: any) => Promise<any>;
+    /**
+     * Manually handle an update (e.g., from a custom webhook implementation).
+     */
+    handleUpdate(update: any, webhookResponse?: any): Promise<void>;
+}
+export {};
+//# sourceMappingURL=telebot.d.ts.map

package/dist/telebot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"telebot.d.ts","sourceRoot":"","sources":["../src/telebot.ts"],"names":[],"mappings":"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"}

package/dist/telebot.js

@@ -0,0 +1,204 @@
+import { Bot } from "grammy";
+import { createAction } from "./action/action.js";
+import { createMenu } from "./menu/menu.js";
+import { installMenu, sendMenu } from "./engine/engine.js";
+/**
+ * # Telebot
+ *
+ * The main entry-point for building Telegram bots declaratively.
+ *
+ * ### Quick Start
+ * ```ts
+ * import { Telebot } from "@superpackages/telebot";
+ * import mainMenu from "./menus/main.js";
+ *
+ * const bot = Telebot.create({
+ *   token: process.env.BOT_TOKEN!,
+ *   menu: mainMenu,
+ * });
+ *
+ * bot.start();
+ * ```
+ */
+/**
+ * Helper to build actions or menus attached to specific triggers.
+ * Used internally by the {@link Telebot} class.
+ */
+class TriggerBuilder {
+    triggers = {};
+    /**
+     * @internal
+     */
+    constructor(type, value) {
+        if (type === "command")
+            this.triggers.commands = [value];
+        if (type === "word")
+            this.triggers.words = [value];
+        if (type === "regexp")
+            this.triggers.regexps = [value];
+    }
+    /**
+     * Add a command trigger (e.g., /settings).
+     * @param name - The command name without the leading slash.
+     */
+    command(name) {
+        this.triggers.commands = [...(this.triggers.commands || []), name];
+        return this;
+    }
+    /**
+     * Add an exact word or phrase trigger.
+     * @param text - The text to trigger on.
+     */
+    word(text) {
+        this.triggers.words = [...(this.triggers.words || []), text];
+        return this;
+    }
+    /**
+     * Add a regular expression trigger.
+     * @param pattern - The regex pattern to match against the message text.
+     */
+    regexp(pattern) {
+        this.triggers.regexps = [...(this.triggers.regexps || []), pattern];
+        return this;
+    }
+    /**
+     * Attach an action to the collected triggers.
+     * @param handler - The function to handle the action.
+     * @returns An {@link ActionRef} that can be used in menus.
+     */
+    action(handler) {
+        const ref = createAction(handler);
+        ref.triggers = { ...this.triggers };
+        return ref;
+    }
+    /**
+     * Attach a menu to the collected triggers.
+     * @param builder - A function to build the menu layout.
+     * @param options - Optional menu settings.
+     * @returns A {@link MenuRef} that can be used or sent.
+     */
+    menu(builder, options) {
+        const ref = createMenu(builder, options);
+        ref.triggers = { ...this.triggers };
+        return ref;
+    }
+}
+/**
+ * The main entry-point for building Telegram bots declaratively.
+ *
+ * Provides static methods to create triggers, actions, and menus.
+ */
+export class Telebot {
+    /**
+     * Create a trigger based on a command (e.g., `/start`).
+     * @param name - The command name.
+     */
+    static command(name) {
+        return new TriggerBuilder("command", name);
+    }
+    /**
+     * Create a trigger based on an exact word or phrase.
+     * @param text - The text to match.
+     */
+    static word(text) {
+        return new TriggerBuilder("word", text);
+    }
+    /**
+     * Create a trigger based on a regular expression.
+     * @param pattern - The pattern to match.
+     */
+    static regexp(pattern) {
+        return new TriggerBuilder("regexp", pattern);
+    }
+    /**
+     * Create a typed action with an optional payload generic.
+     * @param handler - The logic to execute when the action is triggered.
+     */
+    static action(handler) {
+        return createAction(handler);
+    }
+    /**
+     * Create a declarative menu.
+     * @param builder - A layout builder function.
+     * @param options - Optional configuration (e.g., fixed ID).
+     */
+    static menu(builder, options) {
+        return createMenu(builder, options);
+    }
+    /**
+     * Create a fully configured bot instance.
+     * @param options - Configuration including token and root menu.
+     */
+    static create(options) {
+        return new TelebotApp(options);
+    }
+}
+/**
+ * A running bot instance with the menu tree installed.
+ *
+ * Created via {@link Telebot.create}.
+ */
+export class TelebotApp {
+    /** The underlying grammy bot instance. */
+    bot;
+    config;
+    rootMenu;
+    installPromise;
+    /**
+     * @internal Use {@link Telebot.create} instead.
+     */
+    constructor(options) {
+        this.config = options;
+        this.rootMenu = options.menu;
+        this.bot = new Bot(options.token);
+        // Global error boundary — prevents crashes from Grammy/Telegram API errors
+        this.bot.catch((err) => {
+            const e = err.error;
+            if (options.onError) {
+                options.onError(e, err.ctx);
+            }
+            else {
+                console.error("[Telebot] Unhandled error:", e);
+            }
+        });
+        this.installPromise = installMenu(this.bot, this.rootMenu, this.config);
+    }
+    /**
+     * Start the bot using long-polling.
+     */
+    async start() {
+        await this.installPromise;
+        console.log("🤖 Telebot started");
+        await this.bot.start({
+            onStart: () => { },
+            drop_pending_updates: true,
+        });
+    }
+    /**
+     * Manually send the root menu to a specific chat.
+     * @param chatId - The recipient chat ID.
+     * @param ctx - The current context.
+     */
+    async sendMenu(chatId, ctx) {
+        await sendMenu(this.bot, chatId, this.rootMenu, ctx, this.config.translator);
+    }
+    /**
+     * Returns a callback function for webhook usage.
+     * @see grammy documentation for parameters.
+     */
+    webhookCallback(path, onTimeout, timeoutMilliseconds) {
+        return async (req, res, next) => {
+            await this.installPromise;
+            // @ts-ignore
+            return this.bot.webhookCallback(path, onTimeout, timeoutMilliseconds)(req, res, next);
+        };
+    }
+    /**
+     * Manually handle an update (e.g., from a custom webhook implementation).
+     */
+    async handleUpdate(update, webhookResponse) {
+        await this.installPromise;
+        await this.bot.handleUpdate(update, webhookResponse);
+    }
+}
+//# sourceMappingURL=telebot.js.map

package/dist/telebot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telebot.js","sourceRoot":"","sources":["../src/telebot.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,GAAG,EAAiB,MAAM,QAAQ,CAAC;AAS5C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,OAAO,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAE3D;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;GAGG;AACH,MAAM,cAAc;IACV,QAAQ,GAAkE,EAAE,CAAC;IAErF;;OAEG;IACH,YAAY,IAAmC,EAAE,KAAsB;QACrE,IAAI,IAAI,KAAK,SAAS;YAAE,IAAI,CAAC,QAAQ,CAAC,QAAQ,GAAG,CAAC,KAAe,CAAC,CAAC;QACnE,IAAI,IAAI,KAAK,MAAM;YAAE,IAAI,CAAC,QAAQ,CAAC,KAAK,GAAG,CAAC,KAAe,CAAC,CAAC;QAC7D,IAAI,IAAI,KAAK,QAAQ;YAAE,IAAI,CAAC,QAAQ,CAAC,OAAO,GAAG,CAAC,KAAe,CAAC,CAAC;IACnE,CAAC;IAED;;;OAGG;IACH,OAAO,CAAC,IAAY;QAClB,IAAI,CAAC,QAAQ,CAAC,QAAQ,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;QACnE,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACH,IAAI,CAAC,IAAY;QACf,IAAI,CAAC,QAAQ,CAAC,KAAK,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,IAAI,CAAC,CAAC;QAC7D,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,OAAe;QACpB,IAAI,CAAC,QAAQ,CAAC,OAAO,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,CAAC;QACpE,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAgB,OAAyB;QAC7C,MAAM,GAAG,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;QAClC,GAAG,CAAC,QAAQ,GAAG,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;QACpC,OAAO,GAAG,CAAC;IACb,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,OAAsF,EAAE,OAAyB;QACpH,MAAM,GAAG,GAAG,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACzC,GAAG,CAAC,QAAQ,GAAG,EAAE,GAAG,IAAI,CAAC,QAAQ,EAAE,CAAC;QACpC,OAAO,GAAG,CAAC;IACb,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,OAAO;IAClB;;;OAGG;IACH,MAAM,CAAC,OAAO,CAAC,IAAY;QACzB,OAAO,IAAI,cAAc,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC7C,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,IAAI,CAAC,IAAY;QACtB,OAAO,IAAI,cAAc,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC1C,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,MAAM,CAAC,OAAe;QAC3B,OAAO,IAAI,cAAc,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAC/C,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,MAAM,CAAgB,OAAyB;QACpD,OAAO,YAAY,CAAC,OAAO,CAAC,CAAC;IAC/B,CAAC;IAED;;;;OAIG;IACH,MAAM,CAAC,IAAI,CAAC,OAAsF,EAAE,OAAyB;QAC3H,OAAO,UAAU,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IACtC,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,MAAM,CAAC,OAA0C;QACtD,OAAO,IAAI,UAAU,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,UAAU;IACrB,0CAA0C;IACjC,GAAG,CAAsB;IACjB,MAAM,CAAgB;IACtB,QAAQ,CAAU;IAElB,cAAc,CAAgB;IAE/C;;OAEG;IACH,YAAY,OAA0C;QACpD,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC;QACtB,IAAI,CAAC,QAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;QAC7B,IAAI,CAAC,GAAG,GAAG,IAAI,GAAG,CAAiB,OAAO,CAAC,KAAK,CAAC,CAAC;QAElD,2EAA2E;QAC3E,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,GAA6B,EAAE,EAAE;YAC/C,MAAM,CAAC,GAAG,GAAG,CAAC,KAAK,CAAC;YACpB,IAAI,OAAO,CAAC,OAAO,EAAE,CAAC;gBACpB,OAAO,CAAC,OAAO,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC,CAAC;YAC9B,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,KAAK,CAAC,4BAA4B,EAAE,CAAC,CAAC,CAAC;YACjD,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,cAAc,GAAG,WAAW,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;IAC1E,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,KAAK;QACT,MAAM,IAAI,CAAC,cAAc,CAAC;QAC1B,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;QAClC,MAAM,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC;YACnB,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC;YACjB,oBAAoB,EAAE,IAAI;SAC3B,CAAC,CAAC;IACL,CAAC;IAED;;;;OAIG;IACH,KAAK,CAAC,QAAQ,CAAC,MAAc,EAAE,GAAmB;QAChD,MAAM,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,QAAQ,EAAE,GAAG,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;IAC/E,CAAC;IAED;;;OAGG;IACH,eAAe,CAAC,IAAa,EAAE,SAA2C,EAAE,mBAA4B;QACtG,OAAO,KAAK,EAAE,GAAQ,EAAE,GAAQ,EAAE,IAAU,EAAE,EAAE;YAC9C,MAAM,IAAI,CAAC,cAAc,CAAC;YAC1B,aAAa;YACb,OAAO,IAAI,CAAC,GAAG,CAAC,eAAe,CAAC,IAAI,EAAE,SAAS,EAAE,mBAAmB,CAAC,CAAC,GAAG,EAAE,GAAG,EAAE,IAAI,CAAC,CAAC;QACxF,CAAC,CAAC;IACJ,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,YAAY,CAAC,MAAW,EAAE,eAAqB;QACnD,MAAM,IAAI,CAAC,cAAc,CAAC;QAC1B,MAAM,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACvD,CAAC;CACF"}

package/dist/types.d.ts

@@ -0,0 +1,322 @@
+import type { Context, CallbackQueryContext, StorageAdapter } from "grammy";
+export type { StorageAdapter };
+import type { Conversation, ConversationFlavor } from "@grammyjs/conversations";
+/**
+ * Extend this interface via declaration merging to type `ctx.user`:
+ *
+ * ```ts
+ * declare module "Grambot" {
+ *   interface GrambotUser { isAdmin: boolean; balance: number; }
+ * }
+ * ```
+ */
+export interface GrambotUser {
+    [key: string]: any;
+}
+import type { SessionFlavor } from "grammy";
+/**
+ * Internal session structure used by Grambot.
+ */
+export interface GrambotSession {
+    /** Data for @grammyjs/conversations */
+    conversation: object;
+    /** Tracks the origin menu to handle "back" navigation and updates */
+    originMenuId?: string;
+}
+/**
+ * The context object used throughout the framework.
+ * Extends Grammy's Context with a typed `user` property.
+ * Includes SessionFlavor for conversation support.
+ */
+export type GrambotContext = ConversationFlavor<Context & SessionFlavor<GrambotSession> & {
+    /** The current user, resolved via `resolveUser` config or defaults */
+    user: GrambotUser;
+}>;
+/**
+ * Context for callback query updates (button clicks).
+ */
+export type GrambotCallbackContext = CallbackQueryContext<GrambotContext>;
+/**
+ * Type for conversation handlers.
+ */
+export type GrambotConversation = Conversation<GrambotContext, GrambotContext>;
+/** Message parse modes supported by Telegram */
+export type ParseMode = "HTML" | "Markdown" | "MarkdownV2";
+/** Button color styles supported by Telegram Bot API 9.4+ */
+export type ButtonStyle = "danger" | "success" | "primary";
+/** Types of input that can be requested from the user */
+export type AskFieldType = "text" | "number" | "photo";
+export interface AskOptions<T = string> {
+    /** Expected input type */
+    type?: AskFieldType;
+    /** Custom validation function (can be async) */
+    validate?: (value: T) => boolean | Promise<boolean>;
+    /** Message to send if validation fails */
+    errorMessage?: string;
+    /** Translation interpolation data */
+    replace?: Record<string, any>;
+    /** Message parse mode */
+    parseMode?: ParseMode;
+}
+/** Options for the `say` helper in conversations */
+export interface SayOptions {
+    /** Translation interpolation data */
+    replace?: Record<string, any>;
+    /** Message parse mode */
+    parseMode?: ParseMode;
+}
+/** Configuration for a button in an `ask` keyboard */
+export interface AskKeyboardButton {
+    /** Button label */
+    text: string;
+    /** Optional button ID */
+    _id?: string;
+    /** Set the button ID */
+    id(value: string): AskKeyboardButton;
+    /** Set a URL (makes it a URL button) */
+    url(value: string): AskKeyboardButton;
+    /** Set an action handler */
+    action(handler: ButtonActionHandler): AskKeyboardButton;
+    /** Set a submenu to open */
+    menu(ref: MenuRef): AskKeyboardButton;
+    /** Navigate to a submenu (shorthand for .menu()) */
+    navigate(ref: MenuRef): AskKeyboardButton;
+    /** Set custom payload for the action */
+    payload(data: Record<string, unknown>): AskKeyboardButton;
+    /** Force this button to be on a new row */
+    row(): AskKeyboardButton;
+}
+/** Function to build an inline keyboard for the `ask` helper */
+export type AskKeyboardBuilder = (keyboard: AskKeyboard) => void;
+/** Keyboard builder interface for conversations */
+export interface AskKeyboard {
+    /** Add a button to the keyboard */
+    button(text: string): AskKeyboardButton;
+    /** Set maximum number of buttons per row */
+    maxPerRow(count: number): void;
+}
+/** Definition for a form field in a multi-step conversation */
+export interface FormFieldDefinition<K extends string = string> {
+    /** Field name in the resulting object */
+    name: K;
+    /** Question to ask the user */
+    question: string;
+    /** Expected data type */
+    type: AskFieldType;
+}
+/** Helper provided to actions to manage conversations */
+export interface ConversationHelper {
+    /**
+     * @returns The user input or `undefined` if cancelled/navigated away.
+     */
+    ask<T = string>(question: string, options?: AskOptions<T>): Promise<T | undefined>;
+    /** Ask for a choice from a keyboard */
+    ask(question: string, builder: AskKeyboardBuilder): Promise<string | undefined>;
+    /** Ask for a choice from a keyboard with options */
+    ask(question: string, options: AskOptions<any>, builder: AskKeyboardBuilder): Promise<string | undefined>;
+    /**
+     * Update the current prompt with new text/buttons WITHOUT waiting for input.
+     * Useful for showing results or intermediate states.
+     */
+    say(text: string, options?: SayOptions | AskKeyboardBuilder): Promise<void>;
+    /** Say with both options and a keyboard builder */
+    say(text: string, options: SayOptions, builder: AskKeyboardBuilder): Promise<void>;
+    /**
+     * Manually delete the current conversation prompt.
+     */
+    delete(): Promise<void>;
+    /** Run a multi-step form collection */
+    form<T extends Record<string, unknown>>(fields: FormFieldDefinition<Extract<keyof T, string>>[]): Promise<T | undefined>;
+    /** Navigate to a specific menu or the root menu */
+    navigate(menu?: MenuRef): Promise<void>;
+}
+/** Helper for simple UI interactions */
+export interface UIHelper {
+    /** Show a temporary toast message (answerCallbackQuery) */
+    toast(text: string): Promise<void>;
+    /** Show an alert dialog */
+    alert(text: string): Promise<void>;
+}
+/** Context passed to action handlers */
+export interface ActionContext<P = undefined> {
+    /** Grammy context */
+    ctx: GrambotContext;
+    /** Custom data passed to this action */
+    payload: P;
+    /** Conversation manager */
+    conversation: ConversationHelper;
+    /** UI interaction helpers */
+    ui: UIHelper;
+    /** Layout builder for response */
+    layout: LayoutBuilderInterface;
+    /** The value of the button ID or 'id' field from payload */
+    id: string;
+    /** Navigate to a specific menu or the root menu */
+    navigate(menu?: MenuRef): Promise<void>;
+}
+/** A function that handles a specific bot action */
+export type ActionHandler<P = undefined> = (context: ActionContext<P>) => Promise<void> | void;
+/** A function used to conditionally show or hide elements */
+export type GuardFn = (ctx: GrambotContext) => boolean | Promise<boolean>;
+/** A string or a function that returns a string based on context */
+export type DynamicLabel = string | ((ctx: GrambotContext) => string);
+/** Action handler for a button click */
+export type ButtonActionHandler = ActionHandler<any> | ActionRef<any>;
+/** A reference to a registered action */
+export interface ActionRef<P = undefined> {
+    __Grambot_action: true;
+    /** Unique action ID */
+    id: string;
+    /** The actual handler function */
+    handler: ActionHandler<P>;
+    /** Triggers that can invoke this action globally */
+    triggers?: {
+        commands?: string[];
+        words?: string[];
+        regexps?: RegExp[];
+    };
+    /** Add command trigger */
+    command(name: string): ActionRef<P>;
+    /** Add text trigger */
+    word(text: string): ActionRef<P>;
+    /** Add regex trigger */
+    regexp(pattern: RegExp): ActionRef<P>;
+}
+/** Configuration for a menu button */
+export interface ButtonConfig {
+    /** Display text or label builder */
+    label: DynamicLabel;
+    /** Custom button ID */
+    buttonId?: string;
+    /** URL for the button */
+    url?: string;
+    /** If true, this button will always start a new row */
+    forceRow: boolean;
+    /** Condition for showing this button */
+    guard?: GuardFn;
+    /** Action to execute on click */
+    action?: ButtonActionHandler;
+    /** @internal */
+    inlineHandler?: ActionHandler<any>;
+    /** Submenu to open when clicked */
+    submenu?: MenuRef;
+    /** Custom data to pass to the action */
+    payload?: Record<string, unknown>;
+    /** If true, this action is triggered if no other buttons match (for text/regex) */
+    isDefault?: boolean;
+    /** Button color style (danger=red, success=green, primary=blue). Requires Bot API 9.4+ */
+    style?: ButtonStyle;
+    /** Custom emoji icon ID displayed before the button text. Requires Bot API 9.4+ */
+    iconCustomEmojiId?: string;
+}
+/** A reference to a registered menu */
+export interface MenuRef {
+    __Grambot_menu: true;
+    /** Unique menu ID */
+    id: string;
+    /** Function that defines the menu layout */
+    builder: (layout: LayoutBuilderInterface, ctx: GrambotContext) => void | Promise<void>;
+    /** Triggers that can open this menu globally */
+    triggers?: {
+        commands?: string[];
+        words?: string[];
+        regexps?: RegExp[];
+    };
+    /** Add command trigger */
+    command(name: string): MenuRef;
+    /** Add text trigger */
+    word(text: string): MenuRef;
+    /** Add regex trigger */
+    regexp(pattern: RegExp): MenuRef;
+}
+/** Configuration for a paginated list of items */
+export interface ListConfig<T> {
+    /** Data items to display */
+    items: T[];
+    /** Number of items per page */
+    itemsPerPage: number;
+    /** Number of grid columns */
+    columns: number;
+    /** Function to render each item as a button */
+    renderFn?: (item: T) => ButtonBuilderInterface;
+    /** Default action for all items in the list */
+    action?: ButtonActionHandler;
+}
+/** Interface for building menu layouts */
+export interface LayoutBuilderInterface {
+    /** Set the menu body text */
+    text(content: string): TextBuilderInterface;
+    /** Set the menu header image */
+    image(url: string): void;
+    /** Add a button to the menu */
+    button(label: DynamicLabel): ButtonBuilderInterface;
+    /** Add a paginated grid of items */
+    list<T>(items: T[], action?: ButtonActionHandler): ListBuilderInterface<T>;
+    /** Set maximum number of buttons per row */
+    maxPerRow(count: number): void;
+    /** Add a button that refreshes the current menu */
+    refreshButton(label: string): void;
+}
+/** Interface for building menu text */
+export interface TextBuilderInterface {
+    /** Set the parse mode for the text */
+    parseAs(mode: ParseMode): TextBuilderInterface;
+    /** Set interpolation variables for the text */
+    replace(data: Record<string, any>): TextBuilderInterface;
+}
+/** Interface for configuring a menu button */
+export interface ButtonBuilderInterface {
+    /** Set a custom button ID */
+    id(value: string): ButtonBuilderInterface;
+    /** Set a URL (makes it a URL button) */
+    url(value: string): ButtonBuilderInterface;
+    /** Force this button to be on a new row */
+    row(): ButtonBuilderInterface;
+    /** Set a visibility guard */
+    guard(fn: GuardFn): ButtonBuilderInterface;
+    /** Set an action handler */
+    action(handler: ButtonActionHandler): ButtonBuilderInterface;
+    /** Set a submenu to open */
+    menu(ref: MenuRef): ButtonBuilderInterface;
+    /** Set custom payload for the action */
+    payload<P extends Record<string, unknown>>(data: P): ButtonBuilderInterface;
+    /** Mark as the default action for this menu */
+    default(): ButtonBuilderInterface;
+    /** Set a button color style (danger=red, success=green, primary=blue) */
+    style(value: ButtonStyle): ButtonBuilderInterface;
+    /** Shorthand for .style("danger") — red button */
+    danger(): ButtonBuilderInterface;
+    /** Shorthand for .style("success") — green button */
+    success(): ButtonBuilderInterface;
+    /** Shorthand for .style("primary") — blue button */
+    primary(): ButtonBuilderInterface;
+    /** Set a custom emoji icon displayed before the button text */
+    icon(customEmojiId: string): ButtonBuilderInterface;
+}
+/** Interface for configuring a paginated list */
+export interface ListBuilderInterface<T> {
+    /** Set items per page */
+    perPage(count: number): ListBuilderInterface<T>;
+    /** Set grid columns */
+    columns(count: number): ListBuilderInterface<T>;
+    /** Define how to render each item */
+    render(fn: (item: T) => ButtonBuilderInterface): void;
+    /** Set the default action for items in this list */
+    action(handler: ButtonActionHandler): ListBuilderInterface<T>;
+}
+/** Function for localizing strings */
+export type Translator = (key: string, ctx: GrambotContext, options?: Record<string, any>) => string;
+/** Main configuration for GrambotApp */
+export interface GrambotConfig {
+    /** Bot token from @BotFather */
+    token: string;
+    /** Optional: resolve the GrambotUser from ctx (e.g., DB lookup) */
+    resolveUser?: (ctx: Context) => GrambotUser | Promise<GrambotUser>;
+    /** Optional: translator function for internal strings */
+    translator?: Translator;
+    /** Optional: custom storage for bot sessions */
+    sessionStorage?: StorageAdapter<GrambotSession>;
+    /** Optional: custom error handler. If not set, errors are logged to console without crashing. */
+    onError?: (error: unknown, ctx: GrambotContext) => void;
+}
+//# sourceMappingURL=types.d.ts.map