@dementevdev/maxbot-ts 1.0.0

package/dist/esm/bot/lifecycle.js

@@ -0,0 +1,163 @@
+import { BotRouting } from "./routing.js";
+/**
+ * Слой жизненного цикла и удобных методов.
+ *
+ * Отвечает за:
+ * - Запуск / остановку бота (`start` / `stop`) с Promise-мьютексом
+ * - Управление webhook (`setWebhookUrl`, `deleteWebhook`, `getWebhookInfo`)
+ * - Высокоуровневые методы отправки (`sendMessage`, `sendPrivateMessage`, `getMe`)
+ * - Конфигурацию наблюдателей (`onError`, `onSlowHandler`)
+ *
+ * Расширяет {@link BotRouting} — использует маршруты и middleware из него.
+ *
+ * Поля `api` и `transport` объявлены как `abstract` — конкретные значения
+ * предоставляет конструктор `Bot`.
+ */
+export class BotLifecycle extends BotRouting {
+    // Promise-мьютекс: не null пока бот запущен или останавливается.
+    // Использование Promise вместо boolean-флага устраняет race condition:
+    // конкурентный вызов start() во время stop() получит актуальный статус
+    // без окна между проверкой флага и его установкой.
+    startPromise = null;
+    // ==================== Управление webhook ====================
+    /**
+     * Установить URL для webhook.
+     */
+    async setWebhookUrl(url) {
+        await this.api.subscriptions.subscribe({ url });
+    }
+    /**
+     * Удалить webhook.
+     */
+    async deleteWebhook() {
+        await this.api.subscriptions.unsubscribe();
+    }
+    /**
+     * Получить информацию о текущем webhook.
+     */
+    async getWebhookInfo() {
+        return this.api.subscriptions.getSubscriptions();
+    }
+    // ==================== Наблюдатели ====================
+    /**
+     * Зарегистрировать обработчик ошибок.
+     */
+    onError(handler) {
+        this.errorHandler = handler;
+        return this;
+    }
+    /**
+     * Назначить коллбэк для медленных обработчиков.
+     *
+     * Если обработка обновления заняла больше `thresholdMs` мс,
+     * вызывается `cb` с фактическим временем выполнения и типом обновления.
+     *
+     * @example
+     * bot.onSlowHandler(500, (ms, type) => {
+     *   log.warn({ ms, type }, 'slow handler detected');
+     * });
+     */
+    onSlowHandler(thresholdMs, cb) {
+        this.slowThresholdMs = thresholdMs;
+        this.slowHandler = cb;
+        return this;
+    }
+    // ==================== Удобные методы ====================
+    /**
+     * Получить информацию о боте.
+     */
+    async getMe() {
+        return this.api.bots.getMe();
+    }
+    /**
+     * Отправить сообщение в чат.
+     */
+    async sendMessage(chatId, text, options) {
+        const body = {
+            text,
+            format: options?.format,
+            attachments: options?.attachments,
+            notify: options?.notify,
+        };
+        const response = await this.api.messages.sendMessage({ chat_id: chatId, disable_link_preview: options?.disable_link_preview }, body);
+        return response.message;
+    }
+    /**
+     * Отправить личное сообщение пользователю.
+     */
+    async sendPrivateMessage(userId, text, options) {
+        const body = {
+            text,
+            format: options?.format,
+            attachments: options?.attachments,
+            notify: options?.notify,
+        };
+        const response = await this.api.messages.sendMessage({ user_id: userId, disable_link_preview: options?.disable_link_preview }, body);
+        return response.message;
+    }
+    // ==================== Жизненный цикл ====================
+    /**
+     * Запустить бота.
+     */
+    async start() {
+        // Если уже есть активный Promise запуска/остановки — бот занят.
+        // Ждём завершения и только потом решаем, можно ли стартовать.
+        if (this.startPromise !== null) {
+            await this.startPromise;
+            throw new Error("Бот уже запущен. Вызовите stop() перед повторным запуском.");
+        }
+        // Сохраняем Promise до первого await — в JS между синхронными строками
+        // нет переключения контекста, поэтому конкурентный вызов увидит startPromise
+        // уже установленным ещё до любого await внутри _doStart().
+        const startTask = this._doStart();
+        this.startPromise = startTask;
+        try {
+            await startTask;
+        }
+        catch (error) {
+            // Сбрасываем только если это всё ещё актуальный lifecycle task.
+            if (this.startPromise === startTask) {
+                this.startPromise = null;
+            }
+            throw error;
+        }
+    }
+    /**
+     * Остановить бота.
+     */
+    async stop() {
+        if (this.startPromise === null) {
+            return; // уже остановлен — идемпотентно
+        }
+        const lifecycleTask = this.startPromise;
+        const stopTask = (async () => {
+            // Дожидаемся завершения запуска перед остановкой, чтобы transport.stop()
+            // всегда вызывался после transport.start().
+            try {
+                await lifecycleTask;
+            }
+            catch {
+                /* start упал — transport уже не запущен */
+            }
+            await this.transport.stop();
+        })();
+        // Держим mutex до полного завершения stop() — это закрывает окно гонки,
+        // в котором параллельный start() мог пройти до фактической остановки.
+        this.startPromise = stopTask;
+        try {
+            await stopTask;
+        }
+        finally {
+            if (this.startPromise === stopTask) {
+                this.startPromise = null;
+            }
+        }
+    }
+    async _doStart() {
+        // Проверка токена до запуска — fail fast.
+        // Лучше узнать о невалидном токене сразу, чем при первом обновлении.
+        await this.api.bots.getMe();
+        await this.transport.start();
+    }
+}
+//# sourceMappingURL=lifecycle.js.map

package/dist/esm/bot/metrics.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Метрики обработки одного обновления.
+ *
+ * Передаются в колбэк `BotConfig.onMetrics` после каждого обработанного update.
+ */
+export interface BotMetrics {
+    /** Тип обновления (`message_created`, `message_callback`, и т.д.) */
+    updateType: string;
+    /** Общее время обработки update в миллисекундах (middleware + handlers) */
+    totalMs: number;
+    /** Размер очереди семафора **до** захвата слота (число ожидающих updates) */
+    queueSizeAtStart: number;
+    /** Число ошибок, выброшенных handlers во время обработки этого update */
+    handlerErrors: number;
+    /** Время выполнения каждого middleware в миллисекундах (в порядке регистрации) */
+    middlewareTimes: number[];
+}
+//# sourceMappingURL=metrics.d.ts.map

package/dist/esm/bot/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../../../src/bot/metrics.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,qEAAqE;IACrE,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,gBAAgB,EAAE,MAAM,CAAC;IACzB,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC;IACtB,kFAAkF;IAClF,eAAe,EAAE,MAAM,EAAE,CAAC;CAC3B"}

package/dist/esm/bot/metrics.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=metrics.js.map

package/dist/esm/bot/routing.d.ts

@@ -0,0 +1,131 @@
+import type { Middleware } from "../middleware/types.js";
+import type { UpdateType } from "../types/update.js";
+import { BotDispatch } from "./dispatch.js";
+import type { Context } from "./Bot.js";
+import { type HearsTrigger, type CommandTrigger } from "./triggers.js";
+/**
+ * Слой маршрутизации.
+ *
+ * Отвечает за регистрацию обработчиков событий:
+ * - `on` / `onMessage` / `onCallback` / `onStart` — подписка на типы обновлений
+ * - `command` / `hears` / `action` — шорткаты с pattern matching
+ * - `use` / `filter` — middleware-цепочки и предикаты
+ *
+ * Расширяет {@link BotDispatch} — использует `handlers` и `middlewares` из него.
+ */
+export declare abstract class BotRouting<Ctx extends Context> extends BotDispatch<Ctx> {
+    /**
+     * Зарегистрировать один или несколько обработчиков для события message_created.
+     *
+     * При нескольких аргументах промежуточные middleware должны вызывать `next()`;
+     * последний аргумент — финальный обработчик (next не нужен).
+     *
+     * @example С промежуточным middleware
+     * bot.onMessage(authMw, async (ctx) => { await ctx.reply('OK'); });
+     */
+    onMessage(...fns: Middleware<Ctx>[]): this;
+    /**
+     * Зарегистрировать один или несколько обработчиков для callback-запросов.
+     *
+     * @example
+     * bot.onCallback(logMw, async (ctx) => { ... });
+     */
+    onCallback(...fns: Middleware<Ctx>[]): this;
+    /**
+     * Зарегистрировать обработчик для события `bot_started`.
+     *
+     * Срабатывает когда пользователь нажимает Start в диалоге или переходит по deep link.
+     *
+     * @example Onboarding с deep link
+     * bot.onStart(async (ctx) => {
+     *   if (isBotStartedContext(ctx) && ctx.startPayload) {
+     *     await ctx.reply(`Реферал: ${ctx.startPayload}`);
+     *   } else {
+     *     await ctx.reply('Добро пожаловать!');
+     *   }
+     * });
+     */
+    onStart(...fns: Middleware<Ctx>[]): this;
+    /**
+     * Зарегистрировать один или несколько обработчиков для любого типа обновления.
+     *
+     * @example Один обработчик
+     * bot.on('message_created', async (ctx) => { ... });
+     *
+     * @example Несколько middleware + обработчик
+     * bot.on('message_created', authMw, rateLimitMw, async (ctx) => { ... });
+     */
+    on(event: UpdateType, ...fns: Middleware<Ctx>[]): this;
+    /**
+     * Зарегистрировать обработчик команды.
+     *
+     * Срабатывает на `message_created`, если текст сообщения начинается с `/<name>`.
+     *
+     * @example Один обработчик
+     * bot.command('start', async (ctx) => { ... });
+     *
+     * @example Массив команд
+     * bot.command(['start', 'begin'], async (ctx) => { ... });
+     *
+     * @example С промежуточными middleware
+     * bot.command('pay', authMw, checkBalanceMw, async (ctx) => { ... });
+     */
+    command(name: CommandTrigger, ...fns: Middleware<Ctx>[]): this;
+    /**
+     * Зарегистрировать обработчик по regexp- или строковому фильтру текста сообщения.
+     *
+     * При совпадении RegExp устанавливает `ctx.match` с capture-группами.
+     *
+     * @example
+     * bot.hears(/(\d+)/, async (ctx) => { ... });
+     * bot.hears('привет', async (ctx) => { ... });
+     * bot.hears(['привет', /^hi/i], async (ctx) => { ... });
+     */
+    hears(pattern: HearsTrigger, ...fns: Middleware<Ctx>[]): this;
+    /**
+     * Зарегистрировать обработчик по `callback.payload`.
+     *
+     * `pattern` может быть строкой, RegExp или массивом — срабатывает на первое
+     * совпадение. При совпадении RegExp устанавливает `ctx.match` с capture-группами.
+     *
+     * @example
+     * bot.action('buy',                   handler);
+     * bot.action(/^buy:(\d+)$/,           handler);
+     * bot.action(['confirm', 'ok'],        handler); // оба payload
+     * bot.action([/^buy:/, /^sell:/],     handler); // несколько RegExp
+     */
+    action(pattern: HearsTrigger, ...fns: Middleware<Ctx>[]): this;
+    /**
+     * Добавить глобальный middleware.
+     *
+     * Middleware выполняется **внутри** семафорного слота — backpressure применяется
+     * ко всему пайплайну целиком, а не только к финальным хендлерам.
+     *
+     * @example
+     * bot.use(async (ctx, next) => {
+     *   console.log('before');
+     *   await next();
+     *   console.log('after');
+     * });
+     */
+    use(middleware: Middleware<Ctx>): this;
+    /**
+     * Подключить middleware только если предикат возвращает `true`.
+     *
+     * Если предикат не сработал — обновление прозрачно перетекает к следующим middleware.
+     *
+     * @example Только сообщения с текстом
+     * bot.filter(hasText, async (ctx) => {
+     *   console.log(ctx.text.toUpperCase()); // ctx.text: string
+     * });
+     *
+     * @example Composer + filter
+     * const privateRouter = new Composer();
+     * privateRouter.command('start', handler);
+     * bot.filter(isPrivateChat, privateRouter.middleware());
+     */
+    filter<Narrowed extends Ctx>(predicate: (ctx: Ctx) => ctx is Narrowed, ...fns: Middleware<Narrowed>[]): this;
+    /** Цепочка из middleware: возвращает единый EventHandler, вызывающий каждый fn по очереди. */
+    private pipe;
+}
+//# sourceMappingURL=routing.d.ts.map

package/dist/esm/bot/routing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"routing.d.ts","sourceRoot":"","sources":["../../../src/bot/routing.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,KAAK,EAAE,OAAO,EAAgB,MAAM,UAAU,CAAC;AACtD,OAAO,EAGL,KAAK,YAAY,EACjB,KAAK,cAAc,EACpB,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;GASG;AACH,8BAAsB,UAAU,CAAC,GAAG,SAAS,OAAO,CAAE,SAAQ,WAAW,CAAC,GAAG,CAAC;IAG5E;;;;;;;;OAQG;IACH,SAAS,CAAC,GAAG,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI;IAI1C;;;;;OAKG;IACH,UAAU,CAAC,GAAG,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI;IAI3C;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,GAAG,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI;IAIxC;;;;;;;;OAQG;IACH,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI;IAUtD;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,IAAI,EAAE,cAAc,EAAE,GAAG,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI;IAU9D;;;;;;;;;OASG;IACH,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI;IAY7D;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI;IAY9D;;;;;;;;;;;;OAYG;IACH,GAAG,CAAC,UAAU,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,IAAI;IAKtC;;;;;;;;;;;;;;OAcG;IACH,MAAM,CAAC,QAAQ,SAAS,GAAG,EACzB,SAAS,EAAE,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,IAAI,QAAQ,EACxC,GAAG,GAAG,EAAE,UAAU,CAAC,QAAQ,CAAC,EAAE,GAC7B,IAAI;IAWP,8FAA8F;IAC9F,OAAO,CAAC,IAAI;CAIb"}

package/dist/esm/bot/routing.js

@@ -0,0 +1,194 @@
+import { compose } from "../middleware/compose.js";
+import { isMessageContext, isCallbackContext } from "./context/guards.js";
+import { BotDispatch } from "./dispatch.js";
+import { matchTrigger, matchCommand, } from "./triggers.js";
+/**
+ * Слой маршрутизации.
+ *
+ * Отвечает за регистрацию обработчиков событий:
+ * - `on` / `onMessage` / `onCallback` / `onStart` — подписка на типы обновлений
+ * - `command` / `hears` / `action` — шорткаты с pattern matching
+ * - `use` / `filter` — middleware-цепочки и предикаты
+ *
+ * Расширяет {@link BotDispatch} — использует `handlers` и `middlewares` из него.
+ */
+export class BotRouting extends BotDispatch {
+    // ==================== Регистрация обработчиков ====================
+    /**
+     * Зарегистрировать один или несколько обработчиков для события message_created.
+     *
+     * При нескольких аргументах промежуточные middleware должны вызывать `next()`;
+     * последний аргумент — финальный обработчик (next не нужен).
+     *
+     * @example С промежуточным middleware
+     * bot.onMessage(authMw, async (ctx) => { await ctx.reply('OK'); });
+     */
+    onMessage(...fns) {
+        return this.on("message_created", ...fns);
+    }
+    /**
+     * Зарегистрировать один или несколько обработчиков для callback-запросов.
+     *
+     * @example
+     * bot.onCallback(logMw, async (ctx) => { ... });
+     */
+    onCallback(...fns) {
+        return this.on("message_callback", ...fns);
+    }
+    /**
+     * Зарегистрировать обработчик для события `bot_started`.
+     *
+     * Срабатывает когда пользователь нажимает Start в диалоге или переходит по deep link.
+     *
+     * @example Onboarding с deep link
+     * bot.onStart(async (ctx) => {
+     *   if (isBotStartedContext(ctx) && ctx.startPayload) {
+     *     await ctx.reply(`Реферал: ${ctx.startPayload}`);
+     *   } else {
+     *     await ctx.reply('Добро пожаловать!');
+     *   }
+     * });
+     */
+    onStart(...fns) {
+        return this.on("bot_started", ...fns);
+    }
+    /**
+     * Зарегистрировать один или несколько обработчиков для любого типа обновления.
+     *
+     * @example Один обработчик
+     * bot.on('message_created', async (ctx) => { ... });
+     *
+     * @example Несколько middleware + обработчик
+     * bot.on('message_created', authMw, rateLimitMw, async (ctx) => { ... });
+     */
+    on(event, ...fns) {
+        const composed = this.pipe(...fns);
+        const handlers = this.handlers.get(event) ?? [];
+        handlers.push(composed);
+        this.handlers.set(event, handlers);
+        return this;
+    }
+    // ==================== Composer sugar ====================
+    /**
+     * Зарегистрировать обработчик команды.
+     *
+     * Срабатывает на `message_created`, если текст сообщения начинается с `/<name>`.
+     *
+     * @example Один обработчик
+     * bot.command('start', async (ctx) => { ... });
+     *
+     * @example Массив команд
+     * bot.command(['start', 'begin'], async (ctx) => { ... });
+     *
+     * @example С промежуточными middleware
+     * bot.command('pay', authMw, checkBalanceMw, async (ctx) => { ... });
+     */
+    command(name, ...fns) {
+        const composed = this.pipe(...fns);
+        return this.on("message_created", async (ctx) => {
+            if (!isMessageContext(ctx))
+                return;
+            if (matchCommand(name, ctx.text ?? "")) {
+                await composed(ctx);
+            }
+        });
+    }
+    /**
+     * Зарегистрировать обработчик по regexp- или строковому фильтру текста сообщения.
+     *
+     * При совпадении RegExp устанавливает `ctx.match` с capture-группами.
+     *
+     * @example
+     * bot.hears(/(\d+)/, async (ctx) => { ... });
+     * bot.hears('привет', async (ctx) => { ... });
+     * bot.hears(['привет', /^hi/i], async (ctx) => { ... });
+     */
+    hears(pattern, ...fns) {
+        const composed = this.pipe(...fns);
+        return this.on("message_created", async (ctx) => {
+            if (!isMessageContext(ctx))
+                return;
+            const result = matchTrigger(pattern, ctx.text ?? "");
+            if (result !== null) {
+                if (result !== true)
+                    ctx.match = result;
+                await composed(ctx);
+            }
+        });
+    }
+    /**
+     * Зарегистрировать обработчик по `callback.payload`.
+     *
+     * `pattern` может быть строкой, RegExp или массивом — срабатывает на первое
+     * совпадение. При совпадении RegExp устанавливает `ctx.match` с capture-группами.
+     *
+     * @example
+     * bot.action('buy',                   handler);
+     * bot.action(/^buy:(\d+)$/,           handler);
+     * bot.action(['confirm', 'ok'],        handler); // оба payload
+     * bot.action([/^buy:/, /^sell:/],     handler); // несколько RegExp
+     */
+    action(pattern, ...fns) {
+        const composed = this.pipe(...fns);
+        return this.on("message_callback", async (ctx) => {
+            if (!isCallbackContext(ctx))
+                return;
+            const result = matchTrigger(pattern, ctx.data);
+            if (result !== null) {
+                if (result !== true)
+                    ctx.match = result;
+                await composed(ctx);
+            }
+        });
+    }
+    /**
+     * Добавить глобальный middleware.
+     *
+     * Middleware выполняется **внутри** семафорного слота — backpressure применяется
+     * ко всему пайплайну целиком, а не только к финальным хендлерам.
+     *
+     * @example
+     * bot.use(async (ctx, next) => {
+     *   console.log('before');
+     *   await next();
+     *   console.log('after');
+     * });
+     */
+    use(middleware) {
+        this.middlewares.push(middleware);
+        return this;
+    }
+    /**
+     * Подключить middleware только если предикат возвращает `true`.
+     *
+     * Если предикат не сработал — обновление прозрачно перетекает к следующим middleware.
+     *
+     * @example Только сообщения с текстом
+     * bot.filter(hasText, async (ctx) => {
+     *   console.log(ctx.text.toUpperCase()); // ctx.text: string
+     * });
+     *
+     * @example Composer + filter
+     * const privateRouter = new Composer();
+     * privateRouter.command('start', handler);
+     * bot.filter(isPrivateChat, privateRouter.middleware());
+     */
+    filter(predicate, ...fns) {
+        this.use(async (ctx, next) => {
+            if (predicate(ctx)) {
+                await compose(fns, async () => { })(ctx);
+            }
+            else {
+                await next();
+            }
+        });
+        return this;
+    }
+    /** Цепочка из middleware: возвращает единый EventHandler, вызывающий каждый fn по очереди. */
+    pipe(...fns) {
+        if (fns.length === 1)
+            return fns[0];
+        return compose(fns, async () => { });
+    }
+}
+//# sourceMappingURL=routing.js.map

package/dist/esm/bot/triggers.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Тип паттерна для `hears()` и `action()`.
+ *
+ * Принимает:
+ * - строку — точное совпадение
+ * - RegExp — совпадение по регулярке, устанавливает `ctx.match`
+ * - массив строк/RegExp — срабатывает на **первое** совпадение из списка
+ *
+ * @example
+ * bot.hears('привет',            handler);  // строка
+ * bot.hears(/(\d+)\+(\d+)/,      handler);  // RegExp
+ * bot.hears([/^\d+$/, 'помощь'], handler);  // массив: число ИЛИ "помощь"
+ *
+ * bot.action(['confirm', 'ok'],    handler);  // несколько строк
+ * bot.action([/^buy:/, /^sell:/],  handler);  // несколько RegExp
+ */
+export type HearsTrigger = string | RegExp | ReadonlyArray<string | RegExp>;
+/**
+ * Тип паттерна для `command()`.
+ *
+ * Принимает одну команду или массив команд (без учёта ведущего `/`).
+ *
+ * @example
+ * bot.command('start',             handler);  // /start
+ * bot.command(['start', 'begin'],  handler);  // /start или /begin
+ * bot.command(['/help', 'info'],   handler);  // ведущий / необязателен
+ */
+export type CommandTrigger = string | ReadonlyArray<string>;
+/**
+ * Проверяет `HearsTrigger` против строки, перебирая все паттерны.
+ *
+ * Возвращает результат **первого** совпавшего паттерна:
+ * - `RegExpExecArray` — если совпал RegExp (для установки `ctx.match`)
+ * - `true` — если совпала строка
+ * - `null` — ни один паттерн не совпал
+ *
+ * @example
+ * const result = matchTrigger([/^(\d+)$/, 'да'], '42');
+ * // result: RegExpExecArray — ['42', '42'], совпал первый паттерн
+ *
+ * const result2 = matchTrigger([/^\d+$/, 'да'], 'да');
+ * // result2: true — совпала строка
+ */
+export declare function matchTrigger(trigger: HearsTrigger, text: string): RegExpExecArray | true | null;
+/**
+ * Проверяет `CommandTrigger` против текста сообщения.
+ *
+ * Совпадение: текст равен `/<name>` или начинается с `/<name> ` (команда с аргументами).
+ * Сравнение регистронезависимо (`/Start` === `/start`).
+ *
+ * @returns `true` если хотя бы одна команда совпала, иначе `false`
+ *
+ * @example
+ * matchCommand('start', '/start')              // true
+ * matchCommand('start', '/start arg1')         // true
+ * matchCommand(['start', 'help'], '/help')     // true
+ * matchCommand('start', '/stop')               // false
+ * matchCommand('start', '/starter')            // false — нет пробела после имени
+ */
+export declare function matchCommand(trigger: CommandTrigger, text: string): boolean;
+//# sourceMappingURL=triggers.d.ts.map

package/dist/esm/bot/triggers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"triggers.d.ts","sourceRoot":"","sources":["../../../src/bot/triggers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,aAAa,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;AAE5E;;;;;;;;;GASG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;AAyB5D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,MAAM,GACX,eAAe,GAAG,IAAI,GAAG,IAAI,CAU/B;AAWD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAW3E"}

package/dist/esm/bot/triggers.js

@@ -0,0 +1,80 @@
+/**
+ * Проверяет один паттерн против строки.
+ *
+ * Для RegExp с флагами `g`/`y` создаёт новый объект при каждом вызове,
+ * чтобы избежать сдвига `lastIndex` между вызовами.
+ *
+ * @returns Массив совпадения (RegExp), `true` (строка) или `null` (нет совпадения)
+ */
+function matchOne(pattern, text) {
+    if (pattern instanceof RegExp) {
+        // Создаём новый RegExp для stateful-флагов чтобы lastIndex не сохранялся
+        const re = pattern.flags.includes("g") || pattern.flags.includes("y")
+            ? new RegExp(pattern.source, pattern.flags)
+            : pattern;
+        return re.exec(text) ?? null;
+    }
+    return text === pattern ? true : null;
+}
+/**
+ * Проверяет `HearsTrigger` против строки, перебирая все паттерны.
+ *
+ * Возвращает результат **первого** совпавшего паттерна:
+ * - `RegExpExecArray` — если совпал RegExp (для установки `ctx.match`)
+ * - `true` — если совпала строка
+ * - `null` — ни один паттерн не совпал
+ *
+ * @example
+ * const result = matchTrigger([/^(\d+)$/, 'да'], '42');
+ * // result: RegExpExecArray — ['42', '42'], совпал первый паттерн
+ *
+ * const result2 = matchTrigger([/^\d+$/, 'да'], 'да');
+ * // result2: true — совпала строка
+ */
+export function matchTrigger(trigger, text) {
+    const patterns = Array.isArray(trigger)
+        ? trigger
+        : [trigger];
+    for (const p of patterns) {
+        const result = matchOne(p, text);
+        if (result !== null)
+            return result;
+    }
+    return null;
+}
+/**
+ * Нормализует имя команды: убирает ведущий `/`, приводит к нижнему регистру.
+ *
+ * @internal
+ */
+function normalizeCommandName(name) {
+    return (name.startsWith("/") ? name.slice(1) : name).toLowerCase();
+}
+/**
+ * Проверяет `CommandTrigger` против текста сообщения.
+ *
+ * Совпадение: текст равен `/<name>` или начинается с `/<name> ` (команда с аргументами).
+ * Сравнение регистронезависимо (`/Start` === `/start`).
+ *
+ * @returns `true` если хотя бы одна команда совпала, иначе `false`
+ *
+ * @example
+ * matchCommand('start', '/start')              // true
+ * matchCommand('start', '/start arg1')         // true
+ * matchCommand(['start', 'help'], '/help')     // true
+ * matchCommand('start', '/stop')               // false
+ * matchCommand('start', '/starter')            // false — нет пробела после имени
+ */
+export function matchCommand(trigger, text) {
+    const names = Array.isArray(trigger)
+        ? trigger
+        : [trigger];
+    const lower = text.toLowerCase();
+    for (const raw of names) {
+        const cmd = `/${normalizeCommandName(raw)}`;
+        if (lower === cmd || lower.startsWith(`${cmd} `))
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=triggers.js.map