umbot
Version:
Мультиплатформенный фреймворк для создания голосовых навыков и чат-ботов с единой бизнес-логикой. Встроенная поддержка ВКонтакте, Telegram, Viber, MAX, Яндекс Алисы, Маруси и Сбера SmartApp. Архитектура на адаптерах позволяет подключать любые другие платф
243 lines (242 loc) • 9.65 kB
TypeScript
/**
* Основной класс приложения для создания мультиплатформенных приложений, которое будет работать с голосовыми навыками и чат-ботами одновременно.
*
* Предоставляет функциональность для:
* - Управления конфигурацией приложения
* - Работы с базой данных
* - Обработки команд и интентов
* - Логирования и сохранения данных
*
* Основные возможности:
* - Поддержка множества платформ (Алиса, Маруся, Telegram, Viber, VK)
* - Гибкая система конфигурации
* - Управление командами и интентами
* - Работа с базой данных
* - Логирование и отладка
*
* @example
* ```ts
* import { AppContext } from 'umbot';
* const appContext = new AppContext();
* // Настройка конфигурации
* appContext.setAppConfig({
* error_log: './logs',
* json: './data',
* isLocalStorage: true,
* // База данных опциональна
* db: {
* host: 'localhost',
* database: 'bot_db',
* user: 'admin',
* pass: 'password'
* }
* });
*
* // Настройка параметров
* appContext.setPlatformParams({
* welcome_text: 'Привет! Чем могу помочь?',
* help_text: 'Список доступных команд: ...',
* intents: [
* {
* name: 'greeting',
* slots: ['привет', 'здравствуй'],
* is_pattern: false
* },
* {
* name: 'numbers',
* slots: ['\\b\\d{3}\\b'],
* is_pattern: true // Явно указываем, что используем регулярное выражение
* }
* ]
* });
* ```
*/
import { IDatabaseAdapter, IDatabaseInfo, IPlatform } from './interfaces/IBot';
import { ILogger } from './interfaces/ILogger';
import { IAppConfig, IAppParam, TAppMode, THttpClient, TAppPlugin } from './interfaces/IAppContext';
import { CommandReg, ICommandParam, IGroupData, IStepParam } from './utils/CommandReg';
/**
* Тип платформы: Автоопределение
*/
export declare const T_AUTO = "auto";
/**
* Идентификатор интента приветствия
*/
export declare const WELCOME_INTENT_NAME = "welcome";
/**
* Идентификатор интента помощи
*/
export declare const HELP_INTENT_NAME = "help";
/**
* Внутренний класс для хранения состояния и конфигурации приложения.
* Используется внутри Bot для хранения состояния и конфигурации
*
* @remarks
* Разработчикам обычно НЕ нужно создавать экземпляры этого класса напрямую.
* Вместо этого используйте методы класса {@link Bot}:
* - `bot.getAppContext()` - получить доступ к контексту
* - `bot.setAppConfig()` - настроить конфигурацию
* - `bot.setPlatformParams()` - настроить параметры платформ
*
* Этот класс содержит:
* - Конфигурацию приложения (IAppConfig)
* - Параметры платформ (IAppParam)
* - Регистрацию команд и интентов
* - Логирование и метрики
* - Подключение к БД
*
* @example
* ```ts
* // НЕ ТАК:
* const appContext = new AppContext();
*
* // ТАК (правильно):
* const bot = new Bot();
* const appContext = bot.getAppContext(); // если нужен прямой доступ
* ```
*/
export declare class AppContext<TDbInfo = IDatabaseInfo, TQuery = unknown> {
#private;
/**
* Список подключенных платформ
*/
platforms: IPlatform<TQuery>;
/**
* Список подключенных плагинов
*/
plugins: TAppPlugin;
/**
* Информация по подключению к базе данных.
*/
database: {
/**
* Адаптер для работы с базой данных
*/
adapter?: IDatabaseAdapter;
/**
* Данные, необходимые адаптеру для работы
*/
databaseInfo?: TDbInfo;
/**
* Флаг, определяющий вызывался метод для подключения к базе данных или нет
*/
isSendConnect?: boolean;
};
/**
* Все зарегистрированные команды и шаги
*/
command: CommandReg;
/**
* Получение всех зарегистрированных команд
*/
get commands(): Map<string, ICommandParam>;
/**
* Получение всех зарегистрированных шагов
*/
get steps(): Map<string, IStepParam>;
/**
* Получение всех зарегистрированных команд, которые распределены по группам.
* В группу добавляются только команды с регулярными выражениями.
* Группы используются для оптимизации поиска нужной команды
*/
get regexpGroup(): Map<string, IGroupData>;
/**
* Конфигурация приложения
*/
appConfig: Required<IAppConfig>;
/**
* Параметры приложения
*/
platformParams: IAppParam;
/**
* Кастомный HTTP-клиент для выполнения всех исходящих запросов фреймворка.
* По умолчанию используется глобальный `fetch`.
* Вы можете заменить его на любой совместимый клиент (например, axios, undici, got),
* реализующий интерфейс:
* ```ts
* (input: RequestInfo, init?: RequestInit) => Promise<Response>
* ```
* * Это позволяет:
* - добавлять retry-логику, таймауты, circuit breaker;
* - внедрять tracing, метрики или логирование всех запросов;
* - мокать сетевые вызовы в тестах;
* - использовать альтернативные HTTP-библиотеки.
* @example
* ```ts
* const bot = new Bot();
* const ctx = bot.getAppContext();
* ctx.httpClient = async (url, options) => {
* // добавляем таймаут 5 сек
* const controller = new AbortController();
* const id = setTimeout(() => controller.abort(), 5000);
* try {
* const res = await fetch(url, { ...options, signal: controller.signal });
* clearTimeout(id);
* return res;
* } catch (e) {
* clearTimeout(id);
* throw e;
* }
* };
*```
*/
httpClient: THttpClient;
/**
* Определяет режим работы приложения
*/
appMode: TAppMode;
/**
* Закрывает все подключения, для корректного завершения работы приложения
*/
close(): Promise<void>;
/**
* Устанавливает конфигурацию приложения
* @param {IAppConfig} config - Пользовательская конфигурация
*/
setAppConfig(config: Partial<IAppConfig>): void;
/**
* Устанавливает параметры приложения
* @param {IAppParam} params - Пользовательские параметры
*/
setPlatformParams(params: IAppParam): void;
/**
* Позволяет установить свою реализацию для логирования
* @param logger
*/
setLogger(logger: ILogger | null): void;
/**
* Логирование информации
* @param args
*/
log(...args: unknown[]): void;
/**
* Логирование ошибки
* @param str
* @param meta
*/
logError(str: string, meta?: Record<string, unknown>): void;
/**
* Возвращает флаг, который говорит о том необходимо собирать метрики или нет
*/
get usedMetric(): boolean;
/**
* Логирование метрики
* @param name - имя метрики
* @param value - значение
* @param label - Дополнительные метаданные
*/
logMetric(name: string, value: unknown, label: Record<string, unknown>): void;
/**
* Логирование предупреждения
* @param str
* @param meta
*/
logWarn(str: string, meta?: Record<string, unknown>): void;
/**
* Сохраняет данные в JSON файл
* @param fileName - Имя файла
* @param data - Данные для сохранения
* @returns true в случае успешного сохранения
*/
saveFileData(fileName: string, data: unknown): Promise<boolean>;
}