@dementevdev/maxbot-ts 1.0.0

package/dist/esm/bot/Bot.js

@@ -0,0 +1,620 @@
+import { BotsApi, ChatsApi, MessagesApi, SubscriptionsApi, UploadsApi, } from "../api/index.js";
+import { HttpClient } from "../core/http/HttpClient.js";
+import { RateLimiter, } from "../core/rate-limiter/RateLimiter.js";
+import { LongPollingTransport } from "../transport/LongPollingTransport.js";
+import { WebhookTransport } from "../transport/WebhookTransport.js";
+import { CallbackContext } from "./context/CallbackContext.js";
+import { ChatContext } from "./context/ChatContext.js";
+import { BotStartedContext } from "./context/BotStartedContext.js";
+import { MessageContext, } from "./context/MessageContext.js";
+import { assertNever } from "../utils/assertNever.js";
+import { compose, composeWithTiming } from "../middleware/compose.js";
+import { isMessageContext, isCallbackContext } from "./context/guards.js";
+import { matchTrigger, matchCommand, } from "./triggers.js";
+const BASE_URL = "https://platform-api.max.ru";
+/**
+ * Главный класс бота.
+ *
+ * Параметр `Ctx` задаёт тип контекста, передаваемого в middleware и handlers.
+ * По умолчанию — базовый `Context = MessageContext | CallbackContext | ChatContext`.
+ * Используй `contextFactory` в конфиге чтобы расширить контекст своими полями.
+ *
+ * @example Базовое использование
+ * const bot = new Bot({ token: '...', transport: 'polling' });
+ *
+ * @example Расширенный контекст
+ * const bot = new Bot<MyCtx>({ token: '...', transport: 'polling', contextFactory: buildCtx });
+ */
+export class Bot {
+    /** Доступ к низкоуровневым API для продвинутых сценариев */
+    api;
+    http;
+    transport;
+    contextApi;
+    _contextFactory;
+    handlers = new Map();
+    middlewares = [];
+    errorHandler = null;
+    slowHandler = null;
+    slowThresholdMs = 0;
+    unknownUpdateHandler = null;
+    metricsHandler = null;
+    // Семафор для backpressure: ограничивает число параллельных обработчиков.
+    concurrency;
+    activeCount = 0;
+    waitQueue = [];
+    // Promise-мьютекс: не null пока бот запущен или останавливается.
+    // Использование Promise вместо boolean-флага устраняет race condition:
+    // конкурентный вызов start() во время stop() получит актуальный статус
+    // без окна между проверкой флага и его установкой.
+    startPromise = null;
+    constructor(config) {
+        // Собираем граф зависимостей — каждый компонент получает только то, что ему нужно
+        const rateLimiter = config.rateLimiter ?? new RateLimiter();
+        // Если contextFactory не задана — идентичная функция (Ctx = Context по умолчанию)
+        this._contextFactory = config.contextFactory ?? ((base) => base);
+        this.unknownUpdateHandler = config.onUnknownUpdate ?? null;
+        this.metricsHandler = config.onMetrics ?? null;
+        this.http = new HttpClient({
+            baseUrl: config.baseUrl ?? BASE_URL,
+            token: config.token,
+            rateLimiter,
+        });
+        // Инициализируем API-сервисы
+        const bots = new BotsApi(this.http);
+        const chats = new ChatsApi(this.http);
+        const messages = new MessagesApi(this.http);
+        const subscriptions = new SubscriptionsApi(this.http);
+        // Токен передаётся явно — UploadsApi использует его для прямых fetch-запросов
+        const uploads = new UploadsApi(this.http, config.token);
+        this.api = { bots, chats, messages, subscriptions, uploads };
+        this.contextApi = { bots, chats, messages, subscriptions, uploads };
+        // Выбираем стратегию транспорта — паттерн Strategy
+        this.transport =
+            config.transport === "webhook"
+                ? new WebhookTransport(subscriptions, config.webhook)
+                : new LongPollingTransport(subscriptions, config.polling);
+        const concurrency = config.concurrency ?? 10;
+        if (!(concurrency === Infinity ||
+            (Number.isInteger(concurrency) && concurrency > 0))) {
+            throw new Error("Параметр concurrency должен быть положительным целым числом или Infinity");
+        }
+        this.concurrency = concurrency;
+        this.transport.onUpdate(this.handleUpdate.bind(this));
+        this.transport.onError(this.handleError.bind(this));
+    }
+    // ==================== Управление 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();
+    }
+    // ==================== Регистрация обработчиков ====================
+    /**
+     * Зарегистрировать один или несколько обработчиков для события 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-запросов.
+     *
+     * При нескольких аргументах промежуточные middleware должны вызывать `next()`.
+     *
+     * @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);
+    }
+    /**
+     * Зарегистрировать один или несколько обработчиков для любого типа обновления.
+     *
+     * При нескольких аргументах промежуточные middleware должны вызывать `next()`;
+     * последний аргумент — финальный обработчик.
+     *
+     * @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;
+    }
+    /** Цепочка из middleware: возвращает единый EventHandler, вызывающий каждый fn по очереди. */
+    pipe(...fns) {
+        if (fns.length === 1)
+            return fns[0];
+        return compose(fns, async () => { });
+    }
+    // ==================== Composer sugar ====================
+    /**
+     * Зарегистрировать обработчик команды.
+     *
+     * Срабатывает на `message_created`, если текст сообщения начинается с `/<name>` (с аргументами или без).
+     * Обработчик получает полный `Ctx` — для сужения до `MessageContext` используй `isMessageContext(ctx)`.
+     *
+     * @param name - Имя команды без слеша (`start`, `help`, и т.\u0434.)
+     * @param fns - Один или несколько middleware/обработчиков. Промежуточные должны вызывать `next()`.
+     *
+     * @example Один обработчик
+     * bot.command('start', async (ctx) => {
+     *   if (isMessageContext(ctx)) await ctx.reply('Добро пожаловать!');
+     * });
+     *
+     * @example Массив команд
+     * bot.command(['start', 'begin'], async (ctx) => {
+     *   await ctx.reply('Добро пожаловать!');
+     * });
+     *
+     * @example С промежуточными middleware
+     * bot.command('pay', authMw, checkBalanceMw, async (ctx) => {
+     *   await ctx.reply('Оплата выполнена');
+     * });
+     */
+    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- или строковому фильтру текста сообщения.
+     *
+     * Срабатывает на `message_created`, если `ctx.text` совпадает с `pattern`.
+     *
+     * @param pattern - Строка (точное совпадение) или `RegExp`
+     * @param fns - Один или несколько middleware/обработчиков. Промежуточные должны вызывать `next()`.
+     *
+     * @example Один обработчик
+     * bot.hears('привет', async (ctx) => { ... });
+     * bot.hears(/^\u043fр/i, async (ctx) => { ... });
+     * bot.hears(/(\d+)/, async (ctx) => {
+     *   if (isMessageContext(ctx)) console.log(ctx.match?.[1]); // группа захвата
+     * });
+     *
+     * @example С промежуточными middleware
+     * bot.hears(/^\u043fоплата/, authMw, 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`.
+     *
+     * Срабатывает на `message_callback`, если `ctx.data` совпадает с `pattern`.
+     *
+     * @param pattern - Строка (точное совпадение) или `RegExp`
+     * @param fns - Один или несколько middleware/обработчиков. Промежуточные должны вызывать `next()`.
+     *
+     * @example Один обработчик
+     * bot.action('buy', async (ctx) => { ... });
+     * bot.action(/^action:/, async (ctx) => { ... });
+     * bot.action(/^buy:(\d+)$/, async (ctx) => {
+     *   if (isCallbackContext(ctx)) console.log(ctx.match?.[1]); // id из payload
+     * });
+     *
+     * @example С промежуточными middleware
+     * bot.action(/^buy:/, authMw, checkStockMw, async (ctx) => { ... });
+     */
+    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 handlers');
+     *   await next();
+     *   console.log('after handlers');
+     * });
+     */
+    use(middleware) {
+        this.middlewares.push(middleware);
+        return this;
+    }
+    /**
+     * Подключить middleware только если предикат возвращает `true`.
+     *
+     * Сочетается с предикатами из модуля `filters` и с `ctx.has()` для type narrowing.
+     * Если предикат не сработал — обновление прозрачно перетекает к следующим middleware.
+     *
+     * @example Только сообщения с текстом
+     * ```ts
+     * bot.filter(hasText, async (ctx) => {
+     *   console.log(ctx.text.toUpperCase()); // ctx.text: string
+     * });
+     * ```
+     *
+     * @example Комбинация с Composer
+     * ```ts
+     * 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;
+    }
+    /**
+     * Зарегистрировать обработчик ошибок.
+     */
+    onError(handler) {
+        this.errorHandler = handler;
+        return this;
+    }
+    /**
+     * Назначить коллбэк для медленных обработчиков.
+     *
+     * Если обработка обновления (включая middleware и handlers) заняла больше `thresholdMs` мс,
+     * вызывается `cb` с фактическим временем выполнения и типом обновления.
+     *
+     * Используйте для SLO-мониторинга и диагностики производительности.
+     *
+     * @param thresholdMs - Пороговое значение в миллисекундах
+     * @param cb - Коллбэк, получающий фактическое время выполнения (ms) и тип обновления
+     *
+     * @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.
+            // Если параллельно начался stop(), startPromise уже указывает на stop-task.
+            if (this.startPromise === startTask) {
+                this.startPromise = null;
+            }
+            throw error;
+        }
+    }
+    async _doStart() {
+        // Проверка токена до запуска — fail fast.
+        // Лучше узнать о невалидном токене сразу, чем при первом обновлении.
+        await this.api.bots.getMe();
+        await this.transport.start();
+    }
+    /**
+     * Остановить бота.
+     */
+    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;
+            }
+        }
+    }
+    // ==================== Внутренние методы ====================
+    handleUpdate(update) {
+        let ctx;
+        try {
+            const base = this.createContext(update);
+            // null — знак что update_type неизвестен и хук onUnknownUpdate уже вызван;
+            // пропускаем update без ошибки
+            if (base === null)
+                return;
+            ctx = this._contextFactory(base);
+        }
+        catch (error) {
+            this.handleError(error instanceof Error ? error : new Error(String(error)));
+            return;
+        }
+        const handlers = this.handlers.get(update.update_type) ?? [];
+        // Пропускаем только если нет ни middleware, ни handlers — тогда обрабатывать
+        // буквально нечего и мы не занимаем слот семафора впустую.
+        // Если есть хотя бы middleware — запускаем пайплайн: глобальные middleware
+        // (логирование, трейсинг) должны видеть ВСЕ update типы.
+        if (this.middlewares.length === 0 && handlers.length === 0)
+            return;
+        // Запускаем обработку через семафор — гарантируем не более concurrency
+        // параллельных задач. Каждое обновление обрабатывается как единица:
+        // все его хендлеры выполняются параллельно внутри одного слота семафора.
+        void this.runHandlersWithSemaphore(ctx, handlers, update.update_type);
+    }
+    async runHandlersWithSemaphore(ctx, handlers, updateType) {
+        const needMetrics = this.metricsHandler !== null;
+        const needSlow = this.slowHandler !== null;
+        // Размер очереди ДО захвата слота — показывает реальное давление
+        const queueSizeAtStart = this.waitQueue.length;
+        await this.acquireSemaphore();
+        const start = needMetrics || needSlow ? Date.now() : 0;
+        let handlerErrors = 0;
+        const middlewareTimes = [];
+        try {
+            // Финальный обработчик — запускает все зарегистрированные handlers параллельно
+            const finalHandler = async (c) => {
+                await Promise.all(handlers.map(async (handler) => {
+                    try {
+                        await handler(c);
+                    }
+                    catch (error) {
+                        handlerErrors++;
+                        this.handleError(error instanceof Error ? error : new Error(String(error)));
+                    }
+                }));
+            };
+            // Весь пайплайн [middlewares... → handlers] выполняется внутри одного
+            // семафорного слота — backpressure применяется ко всему цепочке целиком.
+            const pipeline = needMetrics
+                ? composeWithTiming(this.middlewares, finalHandler, middlewareTimes)
+                : compose(this.middlewares, finalHandler);
+            await pipeline(ctx);
+        }
+        finally {
+            const elapsed = needMetrics || needSlow ? Date.now() - start : 0;
+            if (needSlow && elapsed >= this.slowThresholdMs) {
+                try {
+                    this.slowHandler?.(elapsed, updateType);
+                }
+                catch {
+                    // Ошибки наблюдателей не должны влиять на основной поток
+                }
+            }
+            if (needMetrics) {
+                try {
+                    this.metricsHandler?.({
+                        updateType,
+                        totalMs: elapsed,
+                        queueSizeAtStart,
+                        handlerErrors,
+                        middlewareTimes,
+                    });
+                }
+                catch {
+                    // Ошибки наблюдателей не должны влиять на основной поток
+                }
+            }
+            this.releaseSemaphore();
+        }
+    }
+    /**
+     * Захватить слот семафора.
+     * Если свободных слотов нет — ждём в очереди.
+     */
+    acquireSemaphore() {
+        if (this.activeCount < this.concurrency) {
+            this.activeCount++;
+            return Promise.resolve();
+        }
+        return new Promise((resolve) => {
+            this.waitQueue.push(resolve);
+        });
+    }
+    /**
+     * Освободить слот семафора и разбудить следующего в очереди.
+     */
+    releaseSemaphore() {
+        const next = this.waitQueue.shift();
+        if (next) {
+            // Передаём слот напрямую — activeCount не меняется
+            next();
+        }
+        else {
+            this.activeCount--;
+        }
+    }
+    handleError(error) {
+        if (this.errorHandler) {
+            try {
+                this.errorHandler(error);
+            }
+            catch {
+                // Игнорируем ошибки в обработчике ошибок
+                console.error("Ошибка в обработчике ошибок:", error);
+            }
+        }
+        else {
+            // По умолчанию логируем в консоль
+            console.error("Ошибка бота:", error);
+        }
+    }
+    /**
+     * Создаёт типизированный контекст из сырого обновления.
+     *
+     * Возвращает `null` если `update_type` неизвестен SDK **и** задан хук
+     * {@link BotConfig.onUnknownUpdate} — хук уже вызван, update нужно пропустить.
+     * Если хук не задан — бросает ошибку через {@link assertNever} → `errorHandler`.
+     *
+     * ### Обработка неизвестных update_type
+     *
+     * TypeScript гарантирует exhaustiveness: если появится новый `update_type`
+     * в типах `Update`, компилятор выдаст ошибку в `default`-ветке через
+     * {@link assertNever}. Это предотвращает рантайм-краши при изменении типов.
+     *
+     * **Рантайм-сценарий**: Если платформа присылает `update_type`, которого
+     * **нет в типах SDK** (например, новая версия API), используй
+     * {@link BotConfig.onUnknownUpdate} для явного контроля:
+     *
+     * ```typescript
+     * const bot = new Bot({
+     *   token: '...',
+     *   transport: 'polling',
+     *   onUnknownUpdate: (raw) => console.warn('unknown update_type:', raw.update_type),
+     * });
+     * ```
+     */
+    createContext(update) {
+        switch (update.update_type) {
+            case "message_callback":
+                return new CallbackContext(update, this.contextApi);
+            case "message_created":
+            case "message_edited":
+            case "message_removed":
+                return new MessageContext(update, this.contextApi);
+            case "bot_added":
+            case "bot_removed":
+            case "user_added":
+            case "user_removed":
+            case "chat_title_changed":
+                return new ChatContext(update);
+            case "bot_started":
+                return new BotStartedContext(update, this.contextApi);
+            default:
+                // TypeScript проверит здесь что все варианты UpdateType обработаны выше.
+                // Если появится новый update_type — будет ошибка компиляции, а не рантайм-краш.
+                if (this.unknownUpdateHandler) {
+                    // Хук вызван, возвращаем null — handleUpdate пропустит update без ошибки
+                    this.unknownUpdateHandler(update);
+                    return null;
+                }
+                // Хук не задан — бросаем ошибку, она уйдёт в errorHandler
+                return assertNever(update);
+        }
+    }
+}
+//# sourceMappingURL=Bot.js.map