@xbibzlibrary/telebibz 0.1.19 → 0.2.1

package/dist-cjs/src/core/bot.js

@@ -27,36 +27,49 @@ class Bot {
     pollingAbort;
     offset = 0;
     me;
+    brandingEnabled;
+    /** Branding effects run only on an interactive TTY; structured logs stay untouched otherwise. */
+    brandingActive;
+    activeBanner;
+    errorHandler;
     constructor(options) {
         const config = typeof options === "string" ? { token: options } : options;
         if (!config.token || !/^\d+:[\w-]+$/.test(config.token))
             throw new Error("A valid Telegram bot token is required.");
         this.token = config.token;
-        (0, terminal_js_1.printTerminalBranding)();
+        this.brandingEnabled = config.branding ?? true;
+        this.brandingActive = this.brandingEnabled && process.stdout.isTTY === true;
         this.logger = config.logger instanceof logger_js_1.Logger ? config.logger : (0, logger_js_1.createLogger)(config.logger);
         this.router = new router_js_1.Router(config.router);
         this.session = config.session ?? new storage_js_1.MemoryStorage();
         this.services = { ...(config.services ?? {}) };
         const transport = config.transport ?? new transport_js_1.FetchTransport({ baseUrl: `${config.apiBaseUrl ?? "https://api.telegram.org"}/bot${config.token}`, ...(config.transportOptions ?? {}) });
         this.api = new client_js_1.ApiClient({
-            transport,
             hooks: {
                 onRequest: (context) => { this.logger.trace("api.request", { method: context.method, payload: context.payload }); return this.events.emit("api:request", { method: context.method, payload: context.payload }); },
                 onResponse: (context) => { this.logger.debug("api.response", { method: context.method, durationMs: context.durationMs ?? 0, ok: context.response?.ok }); return this.events.emit("api:response", { method: context.method, durationMs: context.durationMs ?? 0, response: context.response }); },
                 onError: (context) => { this.logger.error("api.error", { method: context.method, durationMs: context.durationMs ?? 0, error: context.error }); return this.events.emit("api:error", { method: context.method, durationMs: context.durationMs ?? 0, error: context.error }); },
             },
+            transport,
         });
         this.plugins = new plugin_js_1.PluginManager(this);
         this.pollingOptions = {
-            timeout: config.polling?.timeout ?? 30,
-            limit: config.polling?.limit ?? 100,
             allowedUpdates: config.polling?.allowedUpdates ?? [],
-            retryDelayMs: config.polling?.retryDelayMs ?? 500,
+            limit: config.polling?.limit ?? 100,
             maxRetryDelayMs: config.polling?.maxRetryDelayMs ?? 30_000,
+            retryDelayMs: config.polling?.retryDelayMs ?? 500,
+            timeout: config.polling?.timeout ?? 30,
         };
-        this.logger.info("bot.created", { status: this.statusValue });
+        this.startupLog("bot.created", { status: this.statusValue });
         void this.events.emit("bot:created", { bot: this });
     }
+    /** Startup info logs are demoted to debug while the branding sequence owns the terminal. */
+    startupLog(event, context) {
+        if (this.brandingActive)
+            this.logger.debug(event, context);
+        else
+            this.logger.info(event, context);
+    }
     get status() { return this.statusValue; }
     get botInfo() { return this.me; }
     use(...middleware) { this.middlewares.push(...middleware); return this; }
@@ -64,6 +77,21 @@ class Bot {
     callback(pattern, handler) { this.router.callback(pattern, handler); return this; }
     onText(text, handler) { this.router.text(text, handler); return this; }
     onRegex(expression, handler) { this.router.regex(expression, handler); return this; }
+    /** Registers a handler for update types: `bot.on("message:photo", handler)` or `bot.on(["message:text", "callback_query:data"], handler)`. */
+    on(filter, handler) { this.router.on(filter, handler); return this; }
+    /** Registers a handler for exact text or a regular expression, mirroring familiar frameworks. */
+    hears(trigger, handler) {
+        if (trigger instanceof RegExp)
+            this.router.regex(trigger, handler);
+        else
+            this.router.text(trigger, handler);
+        return this;
+    }
+    /**
+     * Sets the error boundary for update handlers. When set, handler failures are
+     * passed here instead of rejecting `handleUpdate()` (webhooks answer 200).
+     */
+    catch(handler) { this.errorHandler = handler; return this; }
     usePlugin(plugin) { this.plugins.use(plugin); return this; }
     /**
      * Routes subsequent messages to the active Wizard step for the same chat/user.
@@ -92,20 +120,29 @@ class Bot {
     async init() {
         if (this.statusValue === "initialized" || this.statusValue === "running")
             return this;
-        this.logger.info("bot.initializing");
-        const animation = (0, terminal_js_1.startTerminalAnimation)("Connecting to Telegram and initializing bot");
+        this.startupLog("bot.initializing", {});
+        const standaloneBanner = this.brandingActive && !this.activeBanner;
+        const animation = this.brandingActive ? undefined : (0, terminal_js_1.startTerminalAnimation)("Connecting to Telegram and initializing bot");
+        if (standaloneBanner)
+            (0, terminal_js_1.printTeleBibzBanner)({ subtitle: "Connecting to Telegram..." });
         try {
             this.me = await this.api.methods.getMe();
             this.statusValue = "initialized";
-            this.logger.info("bot.initialized", { botId: this.me.id, username: this.me.username });
+            this.startupLog("bot.initialized", { botId: this.me.id, username: this.me.username });
             await this.events.emit("bot:initialized", { bot: this });
             await this.plugins.setup();
             await this.plugins.start();
-            animation.stop("Bot initialized; ready to start");
+            if (standaloneBanner)
+                (0, terminal_js_1.printStatusLine)(`✓ Bot initialized as @${this.me.username ?? this.me.id}`);
+            else
+                animation?.stop("Bot initialized; ready to start");
             return this;
         }
         catch (error) {
-            animation.stop("Error: bot could not initialize");
+            if (standaloneBanner)
+                (0, terminal_js_1.printStatusLine)(`✗ Bot could not initialize: ${error instanceof Error ? error.message : String(error)}`);
+            else
+                animation?.stop("Error: bot could not initialize");
             throw error;
         }
     }
@@ -113,15 +150,35 @@ class Bot {
     async launch(options = { mode: "polling" }) {
         if (options.mode !== "polling")
             throw new Error("Use createWebhookHandler() for webhook mode.");
-        await this.init();
+        const runBrandingSequence = this.brandingActive && !this.activeBanner && (this.statusValue === "created" || this.statusValue === "stopped");
+        if (runBrandingSequence) {
+            await (0, terminal_js_1.runStartupSequence)();
+            this.activeBanner = (0, terminal_js_1.startTeleBibzBanner)({ subtitle: "Connecting to Telegram..." });
+        }
+        try {
+            await this.init();
+        }
+        catch (error) {
+            if (this.activeBanner) {
+                this.activeBanner.stop(`Connection failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+                this.activeBanner = undefined;
+            }
+            throw error;
+        }
+        if (this.activeBanner) {
+            this.activeBanner.stop(`Connected as @${this.me?.username ?? this.me?.id}`);
+            this.activeBanner = undefined;
+        }
         if (this.statusValue === "running")
             return;
         this.statusValue = "starting";
-        this.logger.info("bot.starting", { mode: options.mode });
+        this.startupLog("bot.starting", { mode: options.mode });
         await this.events.emit("bot:starting", { bot: this });
         this.pollingAbort = new AbortController();
         this.statusValue = "running";
         await this.events.emit("bot:started", { bot: this });
+        if (this.brandingActive)
+            (0, terminal_js_1.printStatusLine)("Listening for updates...");
         await this.poll(options.timeout ?? this.pollingOptions.timeout, options.allowedUpdates ?? this.pollingOptions.allowedUpdates, this.pollingAbort.signal);
     }
     async stop() {
@@ -134,7 +191,10 @@ class Bot {
         await this.plugins.stop();
         await this.plugins.dispose();
         this.statusValue = "stopped";
-        this.logger.info("bot.stopped");
+        if (this.brandingActive)
+            (0, terminal_js_1.printStatusLine)("Bot stopped.");
+        else
+            this.logger.info("bot.stopped");
         await this.events.emit("bot:stopped", { bot: this });
     }
     async restart() { await this.stop(); await this.start(); }
@@ -151,7 +211,7 @@ class Bot {
     async setCommands(commands, scope, languageCode) { return this.api.call("setMyCommands", { commands, scope, language_code: languageCode }); }
     async deleteCommands(scope, languageCode) { return this.api.call("deleteMyCommands", { scope, language_code: languageCode }); }
     async handleUpdate(update) {
-        this.logger.debug("update.received", { update: (0, logger_js_1.summarizeUpdate)(update, this.logger.includeUpdateContent) });
+        this.logger.incoming((0, logger_js_1.describeIncomingUpdate)(update));
         const message = update.message
             ?? update.edited_message
             ?? update.channel_post
@@ -166,7 +226,7 @@ class Bot {
             await this.init();
         if (!this.me)
             return;
-        const ctx = new context_js_1.Context({ update, api: this.api, session, services: this.services });
+        const ctx = new context_js_1.Context({ update, api: this.api, session, services: this.services, me: this.me });
         await this.events.emit("update", { update });
         if (message) {
             await this.events.emit("message", { message });
@@ -189,22 +249,42 @@ class Bot {
             this.logger.error("update.handler_error", { update: (0, logger_js_1.summarizeUpdate)(update, this.logger.includeUpdateContent), error });
             await this.events.emit("update:error", { update, error });
             await this.events.emit("bot:error", { bot: this, error });
+            if (this.errorHandler) {
+                // With an error boundary registered, the failure is considered handled:
+                // webhooks answer 200 and polling continues without rethrowing.
+                await this.errorHandler(error, ctx);
+                return;
+            }
             throw error;
         }
     }
     conversationKey(update) {
+        if (update.callback_query) {
+            const chat = update.callback_query.message?.chat;
+            const userId = update.callback_query.from.id;
+            if (chat?.id !== undefined)
+                return `${chat.id}:${userId}`;
+            return `user:${userId}`;
+        }
+        if (update.inline_query?.from?.id !== undefined)
+            return `user:${update.inline_query.from.id}`;
+        if (update.chosen_inline_result?.from?.id !== undefined)
+            return `user:${update.chosen_inline_result.from.id}`;
         const message = update.message
             ?? update.edited_message
             ?? update.channel_post
             ?? update.edited_channel_post
             ?? update.business_message
             ?? update.edited_business_message
-            ?? update.guest_message
-            ?? update.callback_query?.message;
+            ?? update.guest_message;
         if (message?.chat?.id !== undefined)
             return `${message.chat.id}:${message.from?.id ?? "anonymous"}`;
-        if (update.callback_query?.from?.id !== undefined)
-            return `user:${update.callback_query.from.id}`;
+        if (update.chat_member?.chat?.id !== undefined)
+            return `${update.chat_member.chat.id}:${update.chat_member.from.id}`;
+        if (update.my_chat_member?.chat?.id !== undefined)
+            return `${update.my_chat_member.chat.id}:${update.my_chat_member.from.id}`;
+        if (update.chat_join_request?.chat?.id !== undefined)
+            return `${update.chat_join_request.chat.id}:${update.chat_join_request.from.id}`;
         return `update:${update.update_id}`;
     }
     async waitForRetry(delayMs, signal) {
@@ -225,9 +305,12 @@ class Bot {
     }
     async poll(timeout, allowedUpdates, signal) {
         let delay = this.pollingOptions.retryDelayMs;
+        // Telegram holds a long-poll connection open for `timeout` seconds, so the
+        // request timeout must exceed it to avoid aborting a healthy connection.
+        const requestTimeoutMs = timeout * 1_000 + 10_000;
         while (!signal.aborted) {
             try {
-                const updates = await this.api.methods.getUpdates({ offset: this.offset, limit: this.pollingOptions.limit, timeout, allowed_updates: allowedUpdates });
+                const updates = await this.api.request("getUpdates", { offset: this.offset, limit: this.pollingOptions.limit, timeout, allowed_updates: allowedUpdates }, signal, { timeoutMs: requestTimeoutMs });
                 delay = this.pollingOptions.retryDelayMs;
                 for (const update of updates) {
                     this.offset = Math.max(this.offset, update.update_id + 1);

package/dist-cjs/src/keyboard/index.js

@@ -11,6 +11,10 @@ class InlineKeyboard {
     webApp(text, url) { return this.button({ text, web_app: { url } }); }
     pay(text = "Pay") { return this.button({ text, pay: true }); }
     copy(text, copiedText) { return this.button({ text, copy_text: { text: copiedText } }); }
+    switchInline(text, query = "") { return this.button({ text, switch_inline_query: query }); }
+    switchInlineCurrent(text, query = "") { return this.button({ text, switch_inline_query_current_chat: query }); }
+    login(text, url, options = {}) { return this.button({ text, login_url: { url, ...options } }); }
+    game(text) { return this.button({ text, callback_game: {} }); }
     button(button) { this.ensureRow().push(validateInlineButton(button)); return this; }
     row(...buttons) { this.rows.push(buttons.map(validateInlineButton)); return this; }
     conditional(condition, factory) { return condition ? factory(this) : this; }
@@ -25,17 +29,25 @@ class InlineKeyboard {
 exports.InlineKeyboard = InlineKeyboard;
 class ReplyKeyboard {
     rows = [];
+    options = {};
     text(text) { return this.button({ text }); }
     contact(text) { return this.button({ text, request_contact: true }); }
     location(text) { return this.button({ text, request_location: true }); }
     poll(text, type) { return this.button({ text, request_poll: type ? { type } : {} }); }
     webApp(text, url) { return this.button({ text, web_app: { url } }); }
+    requestUsers(text, options = {}) { return this.button({ text, request_users: options }); }
+    requestChat(text, options = {}) { return this.button({ text, request_chat: options }); }
+    resized(resize = true) { this.options.resize_keyboard = resize; return this; }
+    oneTime(oneTime = true) { this.options.one_time_keyboard = oneTime; return this; }
+    persistent(persistent = true) { this.options.is_persistent = persistent; return this; }
+    placeholder(text) { this.options.input_field_placeholder = text; return this; }
+    selective(selective = true) { this.options.selective = selective; return this; }
     button(button) { this.ensureRow().push(button); return this; }
     row(...buttons) { this.rows.push([...buttons]); return this; }
     grid(buttons, columns) { if (!Number.isInteger(columns) || columns < 1)
         throw new RangeError("columns must be a positive integer"); for (let index = 0; index < buttons.length; index += columns)
         this.rows.push(buttons.slice(index, index + columns)); return this; }
-    build(options = {}) { return { keyboard: this.rows.map((row) => [...row]), ...options }; }
+    build(options = {}) { return { keyboard: this.rows.map((row) => [...row]), ...this.options, ...options }; }
     asReplyMarkup() { return this.build(); }
     ensureRow() { const row = this.rows.at(-1); if (row)
         return row; const next = []; this.rows.push(next); return next; }

package/dist-cjs/src/observability/logger.js

@@ -1,7 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Logger = void 0;
+exports.Logger = exports.INCOMING_TEXT_LIMIT = void 0;
 exports.redact = redact;
+exports.formatLocalStamp = formatLocalStamp;
+exports.describeIncomingUpdate = describeIncomingUpdate;
 exports.summarizeUpdate = summarizeUpdate;
 exports.createLogger = createLogger;
 const priorities = { silent: 99, error: 0, warn: 1, info: 2, debug: 3, trace: 4 };
@@ -88,6 +90,84 @@ function updateType(update) {
         return "poll_answer";
     return "unknown";
 }
+exports.INCOMING_TEXT_LIMIT = 50;
+function padNumber(value) { return String(value).padStart(2, "0"); }
+/** Formats a date as `dd/mm/yyyy hh:mm:ss` in local time. */
+function formatLocalStamp(date = new Date()) {
+    return `${padNumber(date.getDate())}/${padNumber(date.getMonth() + 1)}/${date.getFullYear()} ${padNumber(date.getHours())}:${padNumber(date.getMinutes())}:${padNumber(date.getSeconds())}`;
+}
+function truncateForDisplay(value, limit = exports.INCOMING_TEXT_LIMIT) {
+    if (value.length <= limit)
+        return { text: value, truncated: false };
+    return { text: `${value.slice(0, limit)}…`, truncated: true };
+}
+function nicknameFromUser(user) {
+    if (!user)
+        return undefined;
+    const name = [user.first_name, user.last_name].filter(Boolean).join(" ").trim();
+    return name.length > 0 ? name : user.username ?? String(user.id);
+}
+function messageMediaType(message) {
+    for (const key of ["photo", "video", "video_note", "animation", "document", "audio", "voice", "sticker", "location", "venue", "contact", "dice", "poll", "story", "paid_media"]) {
+        if (message[key] !== undefined)
+            return key;
+    }
+    return undefined;
+}
+/**
+ * Builds the human-readable description of an incoming update used for the
+ * `[ => ] Message From ...` terminal lines. Text messages and commands are
+ * truncated to 50 characters; callback button data is shown in full.
+ */
+function describeIncomingUpdate(update) {
+    const callback = update.callback_query;
+    if (callback) {
+        const result = { kind: "Callback", fromId: callback.from.id, nickname: nicknameFromUser(callback.from), contentLabel: "Data", content: callback.data };
+        return result;
+    }
+    const message = (update.message ?? update.edited_message ?? update.channel_post ?? update.edited_channel_post ?? update.business_message ?? update.edited_business_message ?? update.guest_message ?? update.edited_guest_message);
+    if (message) {
+        const from = message.from;
+        const nickname = nicknameFromUser(from) ?? (message.chat.title !== undefined ? String(message.chat.title) : message.chat.id !== undefined ? String(message.chat.id) : undefined);
+        const input = { kind: "Message", fromId: from?.id ?? message.chat.id, nickname };
+        const text = message.text;
+        if (text !== undefined) {
+            const truncated = truncateForDisplay(text);
+            input.contentLabel = "Text";
+            input.content = truncated.text;
+            input.truncated = truncated.truncated;
+        }
+        else if (message.caption !== undefined) {
+            const truncated = truncateForDisplay(message.caption);
+            input.contentLabel = "Caption";
+            input.content = truncated.text;
+            input.truncated = truncated.truncated;
+        }
+        else {
+            const media = messageMediaType(message);
+            if (media !== undefined)
+                input.contentLabel = media === "photo" ? "Photo" : media.replace(/_/g, " ").replace(/^./, (character) => character.toUpperCase());
+        }
+        return input;
+    }
+    const inline = update.inline_query;
+    if (inline) {
+        const truncated = truncateForDisplay(inline.query);
+        return { kind: "Inline Query", fromId: inline.from.id, nickname: nicknameFromUser(inline.from), contentLabel: "Query", content: truncated.text, truncated: truncated.truncated };
+    }
+    const chosen = update.chosen_inline_result;
+    if (chosen)
+        return { kind: "Inline Result", fromId: chosen.from.id, nickname: nicknameFromUser(chosen.from), contentLabel: "Result", content: chosen.result_id };
+    const chatScoped = update.chat_member ?? update.my_chat_member ?? update.chat_join_request;
+    if (chatScoped) {
+        return { kind: "Update", fromId: chatScoped.from.id, nickname: nicknameFromUser(chatScoped.from), contentLabel: "Chat", content: chatScoped.chat.title ?? String(chatScoped.chat.id) };
+    }
+    const reaction = update.message_reaction;
+    const reactor = nicknameFromUser(reaction?.from);
+    if (reactor)
+        return { kind: "Reaction", fromId: reaction?.from?.id, nickname: reactor };
+    return { kind: "Update", context: { type: updateType(update) } };
+}
 function summarizeUpdate(update, includeContent = false) {
     const callback = update.callback_query;
     const message = (update.message ?? update.edited_message ?? update.channel_post ?? update.edited_channel_post ?? update.business_message ?? update.edited_business_message ?? update.guest_message ?? update.edited_guest_message ?? callback?.message);
@@ -134,6 +214,10 @@ function createDefaultSink(options, redactKeys) {
     const color = options.color ?? Boolean(stream.isTTY && !process.env.NO_COLOR);
     const format = options.format ?? "pretty";
     return (entry) => {
+        if (typeof entry.text === "string") {
+            stream.write(`${redactString(entry.text)}\n`);
+            return;
+        }
         const safeEntry = redact(entry, redactKeys);
         const line = formatEntry(safeEntry, color, format);
         stream.write(`${line}\n`);
@@ -163,6 +247,34 @@ class Logger {
     info(event, context) { this.write("info", event, context); }
     warn(event, context) { this.write("warn", event, context); }
     error(event, context) { this.write("error", event, context); }
+    /**
+     * Logs an incoming update as the human-readable terminal line:
+     * `[ => ] Message From {id} {nickname} {dd/mm/yyyy} {hh:mm:ss}` followed by
+     * an indented content line. In `json` format it emits a structured entry
+     * with the event name `update.received`.
+     */
+    incoming(input) {
+        if (priorities.info > priorities[this.level])
+            return;
+        if (this.format === "json") {
+            const context = { kind: input.kind, ...(input.fromId !== undefined ? { fromId: input.fromId } : {}), ...(input.nickname !== undefined ? { nickname: input.nickname } : {}), ...(input.content !== undefined ? { content: input.content } : {}), ...(input.truncated ? { truncated: true } : {}), ...input.context };
+            this.write("info", "update.received", context);
+            return;
+        }
+        const stamp = formatLocalStamp();
+        const identity = [input.fromId !== undefined ? String(input.fromId) : undefined, input.nickname].filter(Boolean).join(" ");
+        const arrow = this.color ? `\u001b[36m\u001b[1m[ => ]\u001b[0m` : "[ => ]";
+        const kind = this.color ? `\u001b[1m${input.kind}\u001b[0m` : input.kind;
+        const header = `${arrow} ${kind} From ${identity} ${this.color ? `\u001b[2m${stamp}\u001b[0m` : stamp}`;
+        const lines = [redactString(header)];
+        if (input.content !== undefined || input.contentLabel !== undefined) {
+            const label = input.contentLabel ?? "Content";
+            const value = input.content ?? "";
+            const contentLine = `        ↳ ${label}: ${value}`;
+            lines.push(this.color ? `\u001b[2m${redactString(contentLine)}\u001b[0m` : redactString(contentLine));
+        }
+        this.sink({ timestamp: new Date().toISOString(), level: "info", event: "update.received", text: lines.join("\n") });
+    }
     write(level, event, context = {}) {
         if (priorities[level] > priorities[this.level])
             return;

package/dist-cjs/src/plugins/plugin.js

@@ -13,6 +13,7 @@ exports.ServiceContainer = ServiceContainer;
 class PluginManager {
     plugins = [];
     api;
+    setupComplete = false;
     constructor(bot) {
         const host = bot;
         this.api = {
@@ -39,10 +40,16 @@ class PluginManager {
     }
     use(plugin) { if (this.plugins.some((existing) => existing.name === plugin.name))
         throw new Error(`Plugin already registered: ${plugin.name}`); this.plugins.push(plugin); return this; }
-    async setup() { for (const plugin of this.plugins) {
-        await plugin.install?.(this.api);
-        await plugin.setup?.(this.api);
-    } }
+    /** Installs plugins once; re-running setup after a restart must not double-register middleware. */
+    async setup() {
+        if (this.setupComplete)
+            return;
+        for (const plugin of this.plugins) {
+            await plugin.install?.(this.api);
+            await plugin.setup?.(this.api);
+        }
+        this.setupComplete = true;
+    }
     async start() { for (const plugin of this.plugins)
         await plugin.onStart?.(this.api); }
     async update(context) { for (const plugin of this.plugins)

package/dist-cjs/src/router/router.js

@@ -1,12 +1,57 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Router = void 0;
+exports.Router = exports.UPDATE_FILTER_TYPES = void 0;
 const compose_js_1 = require("../middleware/compose.js");
 function testRegExp(expression, value) {
     expression.lastIndex = 0;
     return expression.test(value);
 }
+/** Update types accepted by `on()` filters, mirroring the Telegram `Update` object. */
+exports.UPDATE_FILTER_TYPES = [
+    "message",
+    "edited_message",
+    "channel_post",
+    "edited_channel_post",
+    "business_connection",
+    "business_message",
+    "edited_business_message",
+    "deleted_business_messages",
+    "guest_message",
+    "message_reaction",
+    "message_reaction_count",
+    "inline_query",
+    "chosen_inline_result",
+    "callback_query",
+    "shipping_query",
+    "pre_checkout_query",
+    "purchased_paid_media",
+    "poll",
+    "poll_answer",
+    "my_chat_member",
+    "chat_member",
+    "chat_join_request",
+    "chat_boost",
+    "removed_chat_boost",
+];
+const updateFilterTypes = new Set(exports.UPDATE_FILTER_TYPES);
+function assertValidFilter(filter) {
+    const type = filter.split(":", 1)[0] ?? "";
+    if (!updateFilterTypes.has(type))
+        throw new TypeError(`Unknown update type in filter "${filter}". Expected one of: ${exports.UPDATE_FILTER_TYPES.join(", ")}.`);
+}
+function matchesFilter(ctx, filter) {
+    const separator = filter.indexOf(":");
+    const type = separator < 0 ? filter : filter.slice(0, separator);
+    const field = separator < 0 ? undefined : filter.slice(separator + 1);
+    const payload = ctx.update[type];
+    if (payload === undefined || payload === null)
+        return false;
+    if (field === undefined || field === "")
+        return true;
+    return typeof payload === "object" && payload[field] !== undefined;
+}
 class Router {
+    middlewares = [];
     routes = [];
     sequence = 0;
     matchMode;
@@ -16,7 +61,7 @@ class Router {
     use(...middleware) {
         if (middleware.length === 0)
             return this;
-        this.routes.push({ priority: -1_000_000 + this.sequence++, matcher: () => true, middleware });
+        this.middlewares.push(...middleware);
         return this;
     }
     route(matcher, ...middleware) {
@@ -27,29 +72,61 @@ class Router {
     }
     command(name, ...middleware) {
         return this.route(async (ctx) => {
-            const text = ctx.message?.text;
+            const text = ctx.message?.text ?? ctx.message?.caption;
             if (!text?.startsWith("/"))
                 return false;
-            const command = text.slice(1).split(/[\s@]/, 1)[0] ?? "";
-            return typeof name === "string"
+            const parts = text.slice(1).split(/\s+/);
+            const commandWithBot = parts[0] ?? "";
+            const [command, botUsername] = commandWithBot.split("@");
+            if (botUsername && ctx.me?.username && botUsername.toLowerCase() !== ctx.me.username.toLowerCase()) {
+                return false;
+            }
+            const matched = typeof name === "string"
                 ? command === name.replace(/^\//, "")
-                : testRegExp(name, command);
+                : testRegExp(name, command ?? "");
+            if (matched) {
+                ctx.args = parts.slice(1);
+            }
+            return matched;
         }, ...middleware);
     }
     text(value, ...middleware) {
-        return this.route((ctx) => ctx.message?.text === value, ...middleware);
+        return this.route((ctx) => {
+            const text = ctx.message?.text ?? ctx.message?.caption;
+            return text === value;
+        }, ...middleware);
     }
     regex(expression, ...middleware) {
-        return this.route((ctx) => testRegExp(expression, ctx.message?.text ?? ""), ...middleware);
+        return this.route((ctx) => {
+            const text = ctx.message?.text ?? ctx.message?.caption ?? "";
+            const match = text.match(expression);
+            if (match) {
+                ctx.match = match;
+                return true;
+            }
+            return false;
+        }, ...middleware);
     }
     callback(pattern, ...middleware) {
         return this.route((ctx) => {
             const data = ctx.callbackQuery?.data ?? "";
-            return typeof pattern === "string"
-                ? pattern.endsWith("*")
-                    ? data.startsWith(pattern.slice(0, -1))
-                    : data === pattern
-                : testRegExp(pattern, data);
+            if (typeof pattern === "string") {
+                if (pattern.endsWith("*")) {
+                    const prefix = pattern.slice(0, -1);
+                    if (data.startsWith(prefix)) {
+                        ctx.params = { ...ctx.params, wildcard: data.slice(prefix.length) };
+                        return true;
+                    }
+                    return false;
+                }
+                return data === pattern;
+            }
+            const match = data.match(pattern);
+            if (match) {
+                ctx.match = match;
+                return true;
+            }
+            return false;
         }, ...middleware);
     }
     chat(chatId, ...middleware) {
@@ -58,6 +135,19 @@ class Router {
             return id !== undefined && (id === chatId || String(id) === String(chatId));
         }, ...middleware);
     }
+    /**
+     * Registers handlers for update types, with optional payload narrowing:
+     * `on("message")`, `on("message:photo")`, `on("callback_query:data")`,
+     * or an array such as `["message:text", "callback_query:data"]`.
+     */
+    on(filter, ...middleware) {
+        const filters = (Array.isArray(filter) ? filter : [filter]).map((value) => String(value));
+        if (filters.length === 0)
+            throw new Error("At least one update filter is required.");
+        for (const value of filters)
+            assertValidFilter(value);
+        return this.route((ctx) => filters.some((value) => matchesFilter(ctx, value)), ...middleware);
+    }
     predicate(matcher, ...middleware) {
         return this.route(matcher, ...middleware);
     }
@@ -67,18 +157,30 @@ class Router {
         });
     }
     async handle(ctx, terminal) {
-        const ordered = [...this.routes].sort((left, right) => left.priority - right.priority);
-        let matched = false;
-        for (const route of ordered) {
-            if (!(await route.matcher(ctx)))
-                continue;
-            matched = true;
-            await (0, compose_js_1.compose)(route.middleware)(ctx);
-            if (this.matchMode === "first")
-                break;
+        const routeDispatcher = async (currentCtx, next) => {
+            const ordered = [...this.routes].sort((left, right) => left.priority - right.priority);
+            let matched = false;
+            for (const route of ordered) {
+                if (!(await route.matcher(currentCtx)))
+                    continue;
+                matched = true;
+                await (0, compose_js_1.compose)(route.middleware)(currentCtx);
+                if (this.matchMode === "first")
+                    break;
+            }
+            if (!matched) {
+                if (terminal)
+                    await terminal();
+                else
+                    await next();
+            }
+        };
+        if (this.middlewares.length === 0) {
+            await routeDispatcher(ctx, async () => { });
+        }
+        else {
+            await (0, compose_js_1.compose)([...this.middlewares, routeDispatcher])(ctx);
         }
-        if (!matched)
-            await terminal?.();
     }
 }
 exports.Router = Router;