umbot
Version:
Мультиплатформенный фреймворк для создания голосовых навыков и чат-ботов с единой бизнес-логикой. Встроенная поддержка ВКонтакте, Telegram, Viber, MAX, Яндекс Алисы, Маруси и Сбера SmartApp. Архитектура на адаптерах позволяет подключать любые другие платф
136 lines (135 loc) • 6.53 kB
TypeScript
import { TPatternRegExp } from '../../utils/standard/RegExp';
import { BotController } from '../../controller';
export interface IGroupData {
commands: string[];
regExp: RegExp | null | string;
}
/**
* Специальное имя команды для обработки неизвестных запросов.
*
* Если ни одна из зарегистрированных команд не сработала,
* и существует команда с именем `FALLBACK_COMMAND`,
* её callback будет выполнен как fallback-обработчик.
*
* @example
* ```ts
* bot.addCommand(FALLBACK_COMMAND, [], (cmd, ctrl) => {
* ctrl.text = 'Извините, я вас не понял. Скажите "помощь" для списка команд.';
* ctrl.buttons.addBtn('Помощь');
* });
* ```
*
* @remarks
* - Fallback срабатывает только если нет совпадений по слотам.
* - Не влияет на стандартные интенты (`welcome`, `help`).
* - Можно зарегистрировать только одну fallback-команду (последняя перезапишет предыдущую).
* - Можно просто передать "*"
*/
export declare const FALLBACK_COMMAND = "*";
/**
* Тип для слотов команд
*/
export type TSlots = TPatternRegExp[];
/**
* Параметры команды
*
* Определяет структуру команды, включая триггеры активации,
* флаг использования регулярных выражений и функцию-обработчик.
*
* @example
* ```ts
* const command: ICommandParam = {
* slots: ['привет', 'здравствуй'],
* isPattern: false,
* cb: (text, controller) => {
* controller.text = 'Привет! Рад вас видеть!';
* }
* };
* ```
*/
export interface ICommandParam<TBotController extends BotController = BotController> {
/**
* Триггеры активации команды
*
* Массив слов или регулярных выражений для активации команды.
*/
slots?: TSlots;
/**
* Флаг использования регулярных выражений
*
* Если true, строки в slots интерпретируются как регулярные выражения.
*/
isPattern?: boolean;
/**
* Функция-обработчик команды
*
* @param {string} userCommand - Текст команды пользователя
* @param {BotController} [botController] - Контроллер с бизнес-логикой приложения для управления ответом
* @returns {void | string} - Строка ответа или void
*
* Если функция возвращает строку, она автоматически устанавливается как ответ для платформы.
*/
cb: (userCommand: string, botController: TBotController) => void | string | Promise<void | string>;
/**
* Имя группы. Актуально для регулярок
* @private
*/
__$groupName?: string | null;
/**
* Скомпилированное регулярное выражение
*/
regExp?: RegExp;
isRegExpString: boolean;
}
/**
* Параметры конфигурации шага диалога.
*
* Используется для регистрации шагов в системе. Шаги сохраняются между сессиями
* и автоматически восстанавливаются при повторном входе пользователя в навык.
*
* @example
* ```ts
* // Обычный шаг
* const step: IStepParam = {
* stepName: 'hello',
* cb: (ctx) => {
* ctx.text = 'Привет! Рад вас видеть!';
* }
* };
*
* // Шаг с условием пропуска (возврат false)
* const stepWithFallback: IStepParam = {
* stepName: 'expired_game',
* cb: (ctx) => {
* if (ctx.messageId === 0) {
* return false; // Пропустить шаг
* }
* ctx.text = 'Продолжаем игру...';
* }
* };
* ```
*/
export interface IStepParam<TBotController extends BotController = BotController> {
/**
* Уникальное имя шага. Используется для идентификации и сохранения в сессии.
*/
stepName: string;
/**
* Функция-обработчик шага. Вызывается при активации шага.
* Если шаг обрабатывать не нужно, то можно вернуть false. В таком случае фреймворк посчитает что шаг не был найден, и продолжит выполнение своей логики с поиском команд.
*
* @param {BotController} botController - Контроллер с бизнес-логикой приложения для управления ответом
* @returns
* - `void` или `undefined` — шаг активен. Обработка останавливается на этом шаге, ожидается ввод пользователя.
* - `false` — шаг **игнорируется**. Фреймворк считает, что шаг не применим, и передаёт управление дальше.
*/
cb: (botController: TBotController) => void | Promise<void> | false;
}
/**
* Тип для функции обработки кастомного обработчика команд.
* Кастомный обработчик может быть как синхронным, так и асинхронным. В случае успешного нахождения команды, возвращается название этой команды. В противном случае возвращается null
* @param userCommand - Команда пользователя
* @param commands - Список всех зарегистрированных команд
* @return {string} - Имя команды
*/
export type TCommandResolver = (userCommand: string, commands: Map<string, ICommandParam>) => string | null | Promise<string | null>;