@dementevdev/maxbot-ts 1.0.0

package/dist/types/bot/Bot.d.ts

@@ -0,0 +1,380 @@
+import type { IBotsApi, IChatsApi, IMessagesApi, ISubscriptionsApi, IUploadsApi } from "../api/interfaces.js";
+import { type IRateLimiter } from "../core/rate-limiter/RateLimiter.js";
+import type { LongPollingConfig, WebhookConfig } from "../transport/interfaces.js";
+import type { BotInfo } from "../types/bot.js";
+import type { Message } from "../types/message.js";
+import type { SubscriptionInfo } from "../types/subscription.js";
+import type { UpdateType } from "../types/update.js";
+import { CallbackContext } from "./context/CallbackContext.js";
+import { ChatContext } from "./context/ChatContext.js";
+import { BotStartedContext } from "./context/BotStartedContext.js";
+import { MessageContext, type SendOptions } from "./context/MessageContext.js";
+import type { Middleware } from "../middleware/types.js";
+import { type HearsTrigger, type CommandTrigger } from "./triggers.js";
+import type { BotMetrics } from "./metrics.js";
+/**
+ * Конфигурация бота.
+ *
+ * Параметр `Ctx` позволяет задать расширенный тип контекста.
+ * По умолчанию используется базовый `Context`.
+ *
+ * @example Расширенный контекст
+ * interface MyCtx extends MessageContext { session: Record<string, unknown> }
+ * const bot = new Bot<MyCtx>({
+ *   token: '...',
+ *   transport: 'polling',
+ *   contextFactory: (base) => Object.assign(base as MyCtx, { session: {} }),
+ * });
+ */
+export interface BotConfig<Ctx extends Context = Context> {
+    /** Токен бота */
+    token: string;
+    /** Режим получения обновлений */
+    transport: "polling" | "webhook";
+    /** Настройки long polling */
+    polling?: LongPollingConfig;
+    /** Настройки webhook */
+    webhook?: WebhookConfig;
+    /** Кастомный rate limiter (опционально) */
+    rateLimiter?: IRateLimiter;
+    /** Базовый URL API (опционально, для тестирования) */
+    baseUrl?: string;
+    /**
+     * Максимальное число одновременно обрабатываемых обновлений (по умолчанию 10).
+     *
+     * При burst-нагрузке без этого ограничения каждое входящее обновление
+     * немедленно запускает новые промисы — их количество не ограничено.
+     * Семафор гарантирует не более `concurrency` активных обработчиков;
+     * остальные обновления встают в очередь и обрабатываются по мере освобождения.
+     *
+     * Установите `Infinity` чтобы отключить ограничение (поведение до этой версии).
+     */
+    concurrency?: number;
+    /**
+     * Фабрика контекста — позволяет расширить базовый контекст своими полями.
+     *
+     * Вызывается для каждого обновления после создания базового контекста.
+     * Возвращаемое значение передаётся во все middleware и handlers вместо базового.
+     *
+     * Если не задана — используется базовый контекст без изменений.
+     *
+     * @example Добавить поле `session` к каждому контексту
+     * contextFactory: (base) => Object.assign(base as MyCtx, { session: {} })
+     */
+    contextFactory?: (base: Context) => Ctx;
+    /**
+     * Обработчик неизвестных типов обновлений в рантайме.
+     *
+     * На практике этот колбэк нужен при работе c версией платформы, которая
+     * распознаёт update_type, ещё не описанный в текущей версии SDK.
+     *
+     * Если колбэк не задан — неизвестный update_type передаётся в `errorHandler`
+     * как `Error("Неизвестный тип обновления: <type>")`.
+     *
+     * @example Логировать неизвестные типы, не падая с ошибкой
+     * onUnknownUpdate: (raw) => console.warn("unknown update_type:", raw.update_type)
+     */
+    onUnknownUpdate?: (raw: Record<string, unknown>) => void;
+    /**
+     * Колбэк метрик производительности — вызывается после каждого обработанного update.
+     *
+     * Получает {@link BotMetrics}: суммарное время, размер очереди на момент захвата
+     * слота, число ошибок handlers и время каждого middleware по отдельности.
+     *
+     * Не влияет на производительность если не задан (нет накладных расходов на замер).
+     *
+     * @example
+     * bot.onMetrics((m) => {
+     *   if (m.totalMs > 500) console.warn('slow', m);
+     *   if (m.handlerErrors > 0) metrics.increment('bot.handler_errors');
+     * });
+     */
+    onMetrics?: (metrics: BotMetrics) => void;
+}
+/**
+ * Контекст обновления (может быть разного типа)
+ */
+export type Context = MessageContext | CallbackContext | ChatContext | BotStartedContext;
+/**
+ * Обработчик событий
+ */
+export type EventHandler<T = Context> = (ctx: T) => void | Promise<void>;
+/**
+ * Главный класс бота.
+ *
+ * Параметр `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 declare class Bot<Ctx extends Context = Context> {
+    /** Доступ к низкоуровневым API для продвинутых сценариев */
+    readonly api: {
+        readonly bots: IBotsApi;
+        readonly chats: IChatsApi;
+        readonly messages: IMessagesApi;
+        readonly subscriptions: ISubscriptionsApi;
+        readonly uploads: IUploadsApi;
+    };
+    private readonly http;
+    private readonly transport;
+    private readonly contextApi;
+    private readonly _contextFactory;
+    private readonly handlers;
+    private readonly middlewares;
+    private errorHandler;
+    private slowHandler;
+    private slowThresholdMs;
+    private unknownUpdateHandler;
+    private metricsHandler;
+    private readonly concurrency;
+    private activeCount;
+    private readonly waitQueue;
+    private startPromise;
+    constructor(config: BotConfig<Ctx>);
+    /**
+     * Установить URL для webhook.
+     */
+    setWebhookUrl(url: string): Promise<void>;
+    /**
+     * Удалить webhook.
+     */
+    deleteWebhook(): Promise<void>;
+    /**
+     * Получить информацию о текущем webhook.
+     */
+    getWebhookInfo(): Promise<SubscriptionInfo>;
+    /**
+     * Зарегистрировать один или несколько обработчиков для события message_created.
+     *
+     * При нескольких аргументах промежуточные middleware должны вызывать `next()`;
+     * последний аргумент — финальный обработчик (next не нужен).
+     *
+     * @example С промежуточным middleware
+     * bot.onMessage(authMw, async (ctx) => { await ctx.reply('OK'); });
+     */
+    onMessage(...fns: Middleware<Ctx>[]): this;
+    /**
+     * Зарегистрировать один или несколько обработчиков для callback-запросов.
+     *
+     * При нескольких аргументах промежуточные middleware должны вызывать `next()`.
+     *
+     * @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;
+    /**
+     * Зарегистрировать один или несколько обработчиков для любого типа обновления.
+     *
+     * При нескольких аргументах промежуточные middleware должны вызывать `next()`;
+     * последний аргумент — финальный обработчик.
+     *
+     * @example Один обработчик (прежнее поведение)
+     * bot.on('message_created', async (ctx) => { ... });
+     *
+     * @example Несколько middleware + обработчик
+     * bot.on('message_created', authMw, rateLimitMw, async (ctx) => { ... });
+     */
+    on(event: UpdateType, ...fns: Middleware<Ctx>[]): this;
+    /** Цепочка из middleware: возвращает единый EventHandler, вызывающий каждый fn по очереди. */
+    private pipe;
+    /**
+     * Зарегистрировать обработчик команды.
+     *
+     * Срабатывает на `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: CommandTrigger, ...fns: Middleware<Ctx>[]): this;
+    /**
+     * Зарегистрировать обработчик по 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: HearsTrigger, ...fns: Middleware<Ctx>[]): this;
+    /**
+     * Зарегистрировать обработчик по `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: HearsTrigger, ...fns: Middleware<Ctx>[]): this;
+    /**
+     * Зарегистрировать middleware, выполняемый перед обработчиками события.
+     *
+     * Middleware выполняется **внутри** семафорного слота — backpressure применяется
+     * ко всему пайплайну целиком, а не только к финальным хендлерам.
+     *
+     * @example
+     * bot.use(async (ctx, next) => {
+     *   console.log('before handlers');
+     *   await next();
+     *   console.log('after handlers');
+     * });
+     */
+    use(middleware: Middleware<Ctx>): 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<Narrowed extends Ctx>(predicate: (ctx: Ctx) => ctx is Narrowed, ...fns: Middleware<Narrowed>[]): this;
+    /**
+     * Зарегистрировать обработчик ошибок.
+     */
+    onError(handler: (error: Error) => void): 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: number, cb: (ms: number, updateType: string) => void): this;
+    /**
+     * Получить информацию о боте.
+     */
+    getMe(): Promise<BotInfo>;
+    /**
+     * Отправить сообщение в чат.
+     */
+    sendMessage(chatId: number, text: string, options?: SendOptions): Promise<Message>;
+    /**
+     * Отправить личное сообщение пользователю.
+     */
+    sendPrivateMessage(userId: number, text: string, options?: SendOptions): Promise<Message>;
+    /**
+     * Запустить бота.
+     */
+    start(): Promise<void>;
+    private _doStart;
+    /**
+     * Остановить бота.
+     */
+    stop(): Promise<void>;
+    private handleUpdate;
+    private runHandlersWithSemaphore;
+    /**
+     * Захватить слот семафора.
+     * Если свободных слотов нет — ждём в очереди.
+     */
+    private acquireSemaphore;
+    /**
+     * Освободить слот семафора и разбудить следующего в очереди.
+     */
+    private releaseSemaphore;
+    private handleError;
+    /**
+     * Создаёт типизированный контекст из сырого обновления.
+     *
+     * Возвращает `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),
+     * });
+     * ```
+     */
+    private createContext;
+}
+//# sourceMappingURL=Bot.d.ts.map

package/dist/types/bot/Bot.d.ts.map

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

package/dist/types/bot/Composer.d.ts

@@ -0,0 +1,131 @@
+import type { Middleware } from "../middleware/types.js";
+import type { Context } from "./Bot.js";
+import type { UpdateType } from "../types/update.js";
+import { type HearsTrigger } from "./triggers.js";
+/**
+ * Тип предиката-фильтра, уточняющего тип контекста.
+ *
+ * @example
+ * const isAdmin: Filter<Context, MessageContext> = (ctx) =>
+ *   isMessageContext(ctx) && ctx.senderId === ADMIN_ID;
+ */
+export type Filter<Ctx, Narrowed extends Ctx> = (ctx: Ctx) => ctx is Narrowed;
+/**
+ * Composer — независимый суб-роутер, совместимый с `bot.use()`.
+ *
+ * Собирает маршруты (`command`, `hears`, `action`, `on`, `filter`) в изолированную
+ * цепочку middleware и подключается к боту через `bot.use(composer.middleware())`.
+ *
+ * Позволяет разбить логику бота на независимые модули с явными границами:
+ * - `adminRouter` — команды только для администраторов
+ * - `shopRouter` — весь шоппинг-флоу
+ * - `notificationRouter` — обработка системных событий
+ *
+ * @example Суб-роутер для администраторов
+ * ```ts
+ * const adminRouter = new Composer<Context>();
+ *
+ * adminRouter.use(onlyAdminMiddleware);
+ * adminRouter.command('stats', async (ctx) => { ... });
+ * adminRouter.hears(/^админ/i, async (ctx) => { ... });
+ *
+ * bot.use(adminRouter.middleware());
+ * ```
+ *
+ * @example bot.filter() + Composer
+ * ```ts
+ * const privateRouter = new Composer<Context>();
+ * privateRouter.command('start', async (ctx) => { ... });
+ *
+ * // Подключаем только для приватных диалогов
+ * bot.filter(isPrivateChat, privateRouter.middleware());
+ * ```
+ */
+export declare class Composer<Ctx extends Context = Context> {
+    private readonly fns;
+    /**
+     * Добавить middleware в цепочку.
+     *
+     * Middleware получает контекст и функцию `next` для перехода к следующему звену.
+     *
+     * @example
+     * composer.use(async (ctx, next) => {
+     *   console.log('before');
+     *   await next();
+     *   console.log('after');
+     * });
+     */
+    use(middleware: Middleware<Ctx>): this;
+    /**
+     * Подписаться на конкретный тип обновления.
+     *
+     * @example
+     * composer.on('bot_added', async (ctx, next) => {
+     *   await ctx.reply('Бот добавлен!');
+     * });
+     */
+    on(event: UpdateType, ...fns: Middleware<Ctx>[]): this;
+    /**
+     * Подписаться на команду (`/name`).
+     *
+     * @example
+     * composer.command('help', async (ctx) => { ... });
+     * composer.command('pay', authMw, async (ctx) => { ... });
+     */
+    command(name: string, ...fns: Middleware<Ctx>[]): this;
+    /**
+     * Подписаться на текст сообщения.
+     *
+     * `pattern` может быть строкой, RegExp или массивом — срабатывает на первое совпадение.
+     * При совпадении RegExp устанавливает `ctx.match` с capture-группами.
+     *
+     * @example
+     * composer.hears(/(\d+)\+(\d+)/, async (ctx) => {
+     *   const [, a, b] = ctx.match!;
+     * });
+     * composer.hears([/^\d+$/, 'помощь'], handler); // массив паттернов
+     */
+    hears(pattern: HearsTrigger, ...fns: Middleware<Ctx>[]): this;
+    /**
+     * Подписаться на callback payload.
+     *
+     * `pattern` может быть строкой, RegExp или массивом — срабатывает на первое совпадение.
+     * При совпадении RegExp устанавливает `ctx.match` с capture-группами.
+     *
+     * @example
+     * composer.action(/^buy:(\d+)$/, async (ctx) => {
+     *   const [, id] = ctx.match!;
+     * });
+     * composer.action(['confirm', 'ok'], handler); // несколько payload
+     */
+    action(pattern: HearsTrigger, ...fns: Middleware<Ctx>[]): this;
+    /**
+     * Фильтровать контекст по предикату с сужением типа.
+     *
+     * Если предикат возвращает `true` — выполняются handlers с суженным типом.
+     * Если `false` — вызывается `next()` (передаётся наружу).
+     *
+     * @example Только авторизованные пользователи
+     * composer.filter(isAdmin, async (ctx) => {
+     *   await ctx.reply('Привет, администратор!');
+     * });
+     *
+     * @example Только сообщения с текстом
+     * composer.filter(hasText, async (ctx) => {
+     *   console.log(ctx.text.toUpperCase()); // ctx.text: string
+     * });
+     */
+    filter<Narrowed extends Ctx>(predicate: (ctx: Ctx) => ctx is Narrowed, ...fns: Middleware<Narrowed>[]): this;
+    /**
+     * Вернуть этот Composer как один `Middleware` для подключения к боту или другому Composer.
+     *
+     * @example
+     * const router = new Composer();
+     * router.command('start', handler);
+     * bot.use(router.middleware());
+     */
+    middleware(): Middleware<Ctx>;
+    /** Сборка цепочки из нескольких fns в единый терминальный обработчик (без next). */
+    private pipe;
+}
+//# sourceMappingURL=Composer.d.ts.map

package/dist/types/bot/Composer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Composer.d.ts","sourceRoot":"","sources":["../../../src/bot/Composer.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACzD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AACxC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAErD,OAAO,EAAgB,KAAK,YAAY,EAAE,MAAM,eAAe,CAAC;AAEhE;;;;;;GAMG;AACH,MAAM,MAAM,MAAM,CAAC,GAAG,EAAE,QAAQ,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,GAAG,IAAI,QAAQ,CAAC;AAE9E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,qBAAa,QAAQ,CAAC,GAAG,SAAS,OAAO,GAAG,OAAO;IACjD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAyB;IAE7C;;;;;;;;;;;OAWG;IACH,GAAG,CAAC,UAAU,EAAE,UAAU,CAAC,GAAG,CAAC,GAAG,IAAI;IAKtC;;;;;;;OAOG;IACH,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI;IAatD;;;;;;OAMG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI;IAkBtD;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI;IAkB7D;;;;;;;;;;;OAWG;IACH,MAAM,CAAC,OAAO,EAAE,YAAY,EAAE,GAAG,GAAG,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,GAAG,IAAI;IAkB9D;;;;;;;;;;;;;;;OAeG;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;;;;;;;OAOG;IACH,UAAU,IAAI,UAAU,CAAC,GAAG,CAAC;IAU7B,oFAAoF;IACpF,OAAO,CAAC,IAAI;CAOb"}

package/dist/types/bot/context/BotStartedContext.d.ts

@@ -0,0 +1,83 @@
+import type { ContextApi, SendOptions } from "./MessageContext.js";
+import type { Message } from "../../types/message.js";
+import type { User } from "../../types/common.js";
+import type { BotStartedUpdate } from "../../types/update.js";
+import type { Context } from "../Bot.js";
+/**
+ * Контекст события bot_started.
+ *
+ * Возникает когда пользователь нажимает кнопку Start в диалоге с ботом
+ * или переходит по deep link вида `https://max.ru/...?start=<payload>`.
+ *
+ * Используйте `ctx.startPayload` для чтения payload из deep link:
+ * реферальные программы, onboarding-флоу, контекстный запуск бота.
+ *
+ * @example Реферальная ссылка
+ * bot.onStart(async (ctx) => {
+ *   if (ctx.startPayload) {
+ *     await ctx.reply(`Вы пришли по ссылке: ref=${ctx.startPayload}`);
+ *   } else {
+ *     await ctx.reply("Добро пожаловать!");
+ *   }
+ * });
+ */
+export declare class BotStartedContext {
+    private readonly update;
+    private readonly api;
+    constructor(update: BotStartedUpdate, api: ContextApi);
+    /** Исходное обновление */
+    get raw(): BotStartedUpdate;
+    /** ID чата (диалога), в котором произошло событие */
+    get chatId(): number;
+    /** Пользователь, нажавший Start */
+    get user(): User;
+    /** ID пользователя */
+    get userId(): number;
+    /**
+     * Payload из deep link.
+     *
+     * `null` или `undefined` если Start нажат без параметра (обычный запуск).
+     * Непустая строка — значение параметра `start` из ссылки.
+     *
+     * @example
+     * // Ссылка: https://max.ru/...?start=ref_123
+     * bot.onStart(async (ctx) => {
+     *   const ref = ctx.startPayload; // "ref_123" | null | undefined
+     * });
+     */
+    get startPayload(): string | null | undefined;
+    /**
+     * Отправить сообщение в диалог пользователю.
+     *
+     * @example
+     * bot.onStart(async (ctx) => {
+     *   if (isBotStartedContext(ctx)) await ctx.reply('Добро пожаловать!');
+     * });
+     */
+    reply(text: string, options?: SendOptions): Promise<Message>;
+    /**
+     * Отправить произвольное действие в чат (диалог пользователя).
+     *
+     * Распространённые значения: `"typing_on"`, `"sending_photo"`,
+     * `"sending_video"`, `"sending_audio"`, `"sending_file"`, `"mark_seen"`.
+     *
+     * @example
+     * bot.onStart(async (ctx) => {
+     *   await ctx.sendAction('typing_on');
+     *   await ctx.reply('Добро пожаловать!');
+     * });
+     */
+    sendAction(action: string): Promise<void>;
+    /**
+     * Проверить тип контекста с сужением типа (type narrowing).
+     *
+     * @example
+     * ```ts
+     * bot.onStart(async (ctx) => {
+     *   if (ctx.has(isPrivateChat)) { ... }
+     * });
+     * ```
+     */
+    has<R extends Context>(filter: (ctx: Context) => ctx is R): this is R;
+}
+//# sourceMappingURL=BotStartedContext.d.ts.map

package/dist/types/bot/context/BotStartedContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"BotStartedContext.d.ts","sourceRoot":"","sources":["../../../../src/bot/context/BotStartedContext.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,qBAAqB,CAAC;AACnE,OAAO,KAAK,EAAE,OAAO,EAAkB,MAAM,wBAAwB,CAAC;AACtE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAC9D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAEzC;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,iBAAiB;IAG1B,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,GAAG;gBADH,MAAM,EAAE,gBAAgB,EACxB,GAAG,EAAE,UAAU;IAGlC,0BAA0B;IAC1B,IAAI,GAAG,IAAI,gBAAgB,CAE1B;IAED,qDAAqD;IACrD,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,mCAAmC;IACnC,IAAI,IAAI,IAAI,IAAI,CAEf;IAED,sBAAsB;IACtB,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED;;;;;;;;;;;OAWG;IACH,IAAI,YAAY,IAAI,MAAM,GAAG,IAAI,GAAG,SAAS,CAE5C;IAED;;;;;;;OAOG;IACG,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,OAAO,CAAC;IAiBlE;;;;;;;;;;;OAWG;IACG,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI/C;;;;;;;;;OASG;IACH,GAAG,CAAC,CAAC,SAAS,OAAO,EAAE,MAAM,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,GAAG,IAAI,CAAC,GAAG,IAAI,IAAI,CAAC;CAGtE"}