umbot/README.md

Мультиплатформенный фреймворк для создания голосовых навыков и чат-ботов с единой бизнес-логикой. Встроенная поддержка ВКонтакте, Telegram, Viber, MAX, Яндекс Алисы, Маруси и Сбера SmartApp. Архитектура на адаптерах позволяет подключать любые другие платф

# umbot

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

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

Фреймворк следует [SemVer](https://semver.org/). Breaking changes возможны только в MAJOR-версиях.

[![npm version](https://badge.fury.io/js/umbot.svg)](https://badge.fury.io/js/umbot)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)]()
[![Security](https://img.shields.io/badge/Security-A+-green)]()
[![Supported Platforms](https://img.shields.io/badge/Platforms-7+-green)]()

---

## 💡 Почему `umbot`?

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

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

- ✅ Одна кодовая база для любой платформы. Хотите только Алису? Легко. Решите добавить Марусю или Telegram — просто
  добавьте нужный адаптер, логика остаётся.
- ⚡ В типичных сценариях (до 1 000 команд) полная обработка запроса внутри фреймворка, включая поиск и выполнение
  команд, занимает **менее 30 мс даже в самом сложном случае (fallback)**. В большинстве случаев это время составляет
  **< 10 мс**. Это оставляет разработчику более **2.5 секунд** на выполнение собственной бизнес-логики — это критически
  важно для платформ с жёсткими тайм-аутами (Алиса, Маруся, Сбер и др.).
- При первичной загрузке медиафайлов время ответа может превысить 1 секунду — поэтому `umbot` предусмотрел это, и
  рекомендует использовать предзагрузку необходимых ресурсов за счет использования класса `Preload`.
- 🔒 Безопасная обработка регулярных выражений с защитой от ReDoS из коробки
- 💾 Встроенное состояние, кэширование медиа, кнопки, карточки — «из коробки»
- 🛠 TypeScript, CLI, автодополнение, 80%+ покрытие тестами
- 🧰 Дополнительные утилиты для навигации и поиска текста, ускоряющие разработку.

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

### Единый API, адаптированный под платформу

`umbot` предоставляет унифицированный интерфейс для работы с ответами, но при этом учитывает специфику каждой платформы:

- Голосовые платформы (Алиса, Маруся, Салют) — поддерживается весь доступный функционал (кнопки, аудиосообщения,
  карточки и т.д.).
- Чат-боты (Telegram, VK, Viber и др.) — поддерживается только необходимый и востребованный набор функций (карточки,
  кнопки, аудиосообщения). Специфические элементы вроде опросов или кастомных интерфейсов мессенджеров исключены, так
  как они не имеют аналогов в голосовых платформах и редко нужны в кроссплатформенной логике.

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

### Чем `umbot` отличается от других решений?

Большинство фреймворков (например, `telegraf`, `alice-sdk` и тд) ориентированы **только на одну платформу**. Чтобы
запустить приложение и в Алисе, и в Telegram, приходится:

- писать **две (или больше) версии логики**,
- поддерживать **разные форматы ответов**,
- дублировать **обработку состояний, кнопок, медиа**
- знать API каждой платформы.

`umbot` решает эту проблему:  
**одна бизнес-логика** для всех платформ,  
**единый API** для кнопок, карточек, голоса и текста,  
**автоматическая адаптация** под формат каждой платформы "под капотом".

Это особенно ценно, если вы уже поддерживаете навык на Алисе и хотите быстро выйти в Марусю, Max или VK — без
переписывания или существенных доработок кода.

Даже если вы пока разрабатываете только под одну платформу, `umbot` избавляет от boilerplate, даёт единый API для работы
с состоянием, кнопками и медиа, а главное — не мешает, когда придёт время добавлять новые каналы.

## Для кого `umbot`?

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

Вы будете использовать `umbot`, если:

- **Вы разрабатываете под одну платформу (Алиса, Салют, Маруся, VK и др.).**
  Вы получите чистое разделение логики и транспорта, избавитесь от дублирования кода внутри проекта и заложите
  архитектуру, которая безболезненно масштабируется, когда потребуется вторая платформа. Инструмент не усложнит — он
  упорядочит.
- **Вы поддерживаете несколько платформ одновременно.**
  Вы перестанете синхронизировать изменения вручную. Новая функциональность появляется сразу везде, а поддержка разных
  API сводится к единому интерфейсу.
- **Вы проектируете систему с прицелом на будущее.**
  Вы не хотите переписывать ядро, когда бизнес попросит добавить Telegram, корпоративный портал или голосового
  ассистента. `umbot` делает расширение предсказуемым.
- **Вы работаете в корпоративной среде с внутренними мессенджерами.**
  Вы унифицируете разработку чат-ботов, упрощаете онбординг и переиспользование компонентов между командами.
- **Вы цените чистоту кода и не терпите копипасту.**
  Вы устали переносить обработчики из проекта в проект или мучительно адаптировать бизнес-логику под каждый новый API.
  `umbot` позволяет писать ядро один раз и забыть о boilerplate.

> **Ключевая мысль:**
> `umbot` — это не «надстройка для мультиплатформенности», а базовый слой, который делает разработку под любую платформу
> (даже одну) быстрее, чище и готовой к масштабированию.

---

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

| Платформа             | Идентификатор | Статус               |
| :-------------------- | :------------ | -------------------- |
| Яндекс.Алиса          | `alisa`       | ✅ Полная поддержка  |
| Маруся                | `marusia`     | ✅ Полная поддержка  |
| Сбер Салют (SmartApp) | `smart_app`   | ✅ Полная поддержка  |
| Telegram              | `telegram`    | ✅ Полная поддержка  |
| VK                    | `vk`          | ✅ Полная поддержка  |
| Max                   | `max_app`     | ✅ Полная поддержка  |
| Viber                 | `viber`       | ✅ Полная поддержка  |
| **Ваша платформа**    | `...`         | ✅ За счет адаптеров |

> 💡 **Нужна своя платформа?**  
> Просто создайте свой адаптер согласно документации для нужной платформы и подключите его к приложению.  
> Это позволяет интегрировать `umbot` в любую внутреннюю систему, корпоративный мессенджер или поддержать любую другую
> платформу, например `whatsapp`.

---

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

Установите фреймворк:

```bash
npm install umbot
```

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

```bash
npx umbot create echo
cd echo
npm i
npm run start
```

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

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

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

```ts
// 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}`;
        }
    }
}
```

Протестируйте приложение, и в случае необходимости опубликуйте его.

👉 [Подробное руководство по запуску](https://www.maxim-m.ru/bot/ts-doc/documents/umbot_v-3.0_.src_docs_getting-started.html)

## Производительность

В стресс-тестах на стандартном оборудовании (AMD Ryzen 5 5600G, Windows 10) фреймворк при 1003 командах показывает:

- **Пропускная способность (реалистичный сценарий)** — **41 000 RPS**  
  (эмуляция полного цикла: входящий запрос → нормализация → логика → ответ)
- **Пиковая пропускная способность (burst)** — **40 000 RPS**  
  (одновременная обработка тысяч параллельных вызовов)
- **Последовательная пропускная способность (ядро)** — **66 000 RPS**  
  (максимальная скорость одного потока)

**Важно:**

- Тесты проводились без сетевых вызовов и операций с базами данных, поэтому цифры показывают потенциал ядра фреймворка.
- В реальном проекте итоговый RPS будет определяться внешними факторами (сеть, БД, логика приложения).

Длительное тестирование (48 часов) не выявило утечек памяти или снижения производительности: средняя пропускная
способность в последовательном сценарии осталась на уровне **66 000 RPS**, а потребление памяти стабильно.

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

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

- [Быстрый старт](https://www.maxim-m.ru/bot/ts-doc/documents/umbot_v-3.0_.src_docs_getting-started.html) - Подробное описание, для
  быстрого старта проекта
- [Подробная инструкция по созданию приложений](https://www.maxim-m.ru/bot/ts-doc/documents/umbot_v-3.0_.src_docs_GUIDE.html)
- [API Reference](https://www.maxim-m.ru/bot/ts-doc/documents/umbot_v-3.0_.src_docs_api-reference.html) - Подробное описание всех классов,
  методов и интерфейсов
- [Поддерживаемые платформы](https://www.maxim-m.ru/bot/ts-doc/documents/umbot_v-3.0_.src_docs_platform-integration.html) - Руководство по
  интеграции с различными платформами
- [Конфигурация и безопасность](https://www.maxim-m.ru/bot/ts-doc/documents/umbot_v-3.0_.src_docs_configuration.html)
- [Кастомизация HTTP-клиента](https://www.maxim-m.ru/bot/ts-doc/documents/umbot_v-3.0_.src_docs_http-client.html)
- [Производительность и гарантии](https://www.maxim-m.ru/bot/ts-doc/documents/umbot_v-3.0_.src_docs_performance-and-guarantees.html)
- [Тестирование](https://www.maxim-m.ru/bot/ts-doc/documents/umbot_v-3.0_.src_docs_testing.html)
- [Развертывание](https://www.maxim-m.ru/bot/ts-doc/documents/umbot_v-3.0_.src_docs_deployment.html)
- [Middleware](https://www.maxim-m.ru/bot/ts-doc/documents/umbot_v-3.0_.src_docs_middleware.html)
- [FAQ](https://www.maxim-m.ru/bot/ts-doc/documents/umbot_v-3.0_.src_docs_FAQ.html)

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

- 📚 [Официальная документация](https://www.maxim-m.ru/bot/ts-doc/index.html)
- 📢 [Telegram канал](https://t.me/joinchat/AAAAAFM8AcuniLTwBLuNsw)
- 💬 [Telegram группа](https://t.me/mm_universal_bot)
- 📦 [npm package](https://www.npmjs.com/package/umbot)
- [Создание навыка "Я никогда не"](https://www.maxim-m.ru/article/sozdanie-navyika-ya-nikogda-ne)
- [Примеры проектов](https://github.com/max36895/universal_bot-ts/tree/main/examples.md)
- [Список изменений](https://github.com/max36895/universal_bot-ts/blob/main/CHANGELOG.md)
- [Что ждать в следующем релизе](https://www.maxim-m.ru/bot/ts-doc/documents/umbot_v-3.0_.src_docs_next-release.html)

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

- [CLI](https://www.maxim-m.ru/bot/ts-doc/documents/umbot_v-3.0_.cli_README.html) команды

## 📝 Лицензия

MIT License. См. [LICENSE](./LICENSE) для деталей.

## 🤝 Поддержка

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

- 📧 Email: maximco36895@yandex.ru
- 🐛 [Issues на GitHub](https://github.com/max36895/universal_bot-ts/issues)