umbot

umbot — это первая в своём роде TypeScript-библиотека для разработки чат-ботов и голосовых навыков с единой бизнес-логикой под все ведущие российские платформы: Яндекс.Алиса, Маруся, Сбер SmartApp, а также Telegram, VK, MAX и Viber.

В отличие от большинства решений, требующих отдельной реализации под каждую платформу, umbot абстрагирует различия в форматах запросов и ответов, предоставляя разработчику единый, предсказуемый интерфейс. Это позволяет писать логику один раз — и запускать её везде.

Библиотека следует SemVer . Breaking changes возможны только в MAJOR-версиях.

---

💡 Почему umbot?

Больше не нужно писать три версии одного навыка.
Больше не нужно разбираться в JSON-форматах Алисы, Сбера и Маруси.
Ваша логика — одна. Платформы — любые.

Ключевые преимущества:

• ✅ Алиса + Маруся + Сбер SmartApp + ... — одновременно, без костылей
• ⚡ Гарантированное время обработки ≤1 сек (оставляет минимум 2 сек на вашу логику)
• 🔒 Безопасная обработка регулярных выражений с защитой от ReDoS
• 💾 Встроенное состояние, кэширование медиа, кнопки, карточки — «из коробки»
• 🛠 TypeScript, CLI, автодополнение, 80%+ покрытие тестами

umbot — пишешь один раз, запускаешь везде.

🎯 Для кого umbot?

• Команды, поддерживающие навыки на Алисе, Сбере и Марусе одновременно
• Корпорации с внутренними мессенджерами
• Разработчики, уставшие от дублирования кода

---

🧩 Поддерживаемые платформы

Платформа	Идентификатор	Статус
Яндекс.Алиса	alisa	✅ Полная поддержка
Маруся	marusia	✅ Полная поддержка
Сбер SmartApp	smart_app	✅ Полная поддержка
Telegram	telegram	✅ Полная поддержка
VK	vk	✅ Полная поддержка
Max	max_app	✅ Полная поддержка
Viber	viber	✅ Полная поддержка
Ваша платформа	user_application	✅ Базовая поддержка

💡 Нужна своя платформа?
Просто укажите user_application в appType и реализуйте обработку входящих/исходящих сообщений под ваш формат.
Это позволяет интегрировать umbot в любую внутреннюю систему или корпоративный мессенджер.

---

🚀 Быстрый старт

Установите библиотеку:

npm install umbot

Создайте и запустите проект за четыре команды:

npx umbot create echo
cd echo
npm i
npm run start

Поправьте файлы нужным вам образом. Например:

// index.ts
import { Bot } from 'umbot';
import { EchoController } from './EchoController';

const bot = new Bot()
    .setAppConfig({ json: './data', isLocalStorage: true })
    .initBotController(new EchoController())
    .start('localhost', 3000);

// EchoController.ts
import { BotController, WELCOME_INTENT_NAME } from 'umbot';

export class EchoController extends BotController {
    public action(intentName: string): void {
        if (intentName === WELCOME_INTENT_NAME) {
            this.text = 'Привет! Я повторяю за вами.';
        } else {
            this.text = `Вы сказали: ${this.userCommand}`;
        }
    }
}

👉 Подробное руководство по запуску

📚 Документация

Подробная документация доступна в следующих разделах:

• Быстрый старт - Подробное описание, для быстрого старта проекта
• API Reference - Подробное описание всех классов, методов и интерфейсов
• Поддерживаемые платформы - Руководство по интеграции с различными платформами
• Конфигурация и безопасность
• Кастомизация HTTP-клиента
• Производительность и гарантии
• Тестирование
• Развертывание
• Middleware
• FAQ

Полезные ссылки

• 📚 Официальная документация
• 📢 Telegram канал
• 💬 Telegram группа
• 📦 npm package
• Создание навыка "Я никогда не"
• Примеры проектов
• Список изменений
• Что ждать в следующем релизе

🛠 Инструменты разработчика

• CLI команды

Рекомендации

re2

Библиотека поддерживает работу с re2. За счет использования данной библиотеки, можно добиться существенного ускорения обработки регулярных выражений, а также добиться сокращения по потреблению памяти. По памяти потребление уменьшается примерно в 3-7 раз, а время выполнения увеличивается в среднем в 2-15 раз. Для корректной установки на window нужно следовать инструкции, установив python3.13, а также инструменты visual studio. Установка на linux или mac происходит без лишних действий. Также стоит учитывать что последние версия re2(1.21 и выше) не поддерживает работу nodejs 18, поэтому необходимо установить версию 1.20.12. Если вы используете nodejs 20 и выше, то лучше установить актуальную версию. Установка:

npm install --save re2@latest

Дальше библиотека сама определит установлен re2 или нет, и в случае если он установлен, все регулярные выражения будут обрабатываться через него.

Хранение данных пользователей

Не рекомендуется использовать в релизной версии приложения файловую базу данных, так как данный подход может привести к падению приложения, при большом количестве записей. Связано это с тем, что в файловой базе данных, данные в основном хранятся в оперативной памяти. Для сохранения данных в БД укажите:

1. поле db в настройке приложения bot.setAppConfig({db:{...}})
2. укажите свое подключение к БД через bot.setUserDbController(new DbConnect());

📝 Лицензия

MIT License. См. LICENSE для деталей.

🤝 Поддержка

Если у вас есть вопросы или предложения:

• 📧 Email: [email protected]
• 🐛 Issues на GitHub