umbot
    Preparing search index...

    Class MarusiaAdapter

    Адаптер, обеспечивающий полную поддержку платформы Маруси от ВК. Позволяет разрабатывать навыки для Маруси на TypeScript с использованием всего функционала платформы: от обработки голосовых запросов до работы с карточками и кнопками.

    Этот адаптер автоматически обрабатывает входящие вебхуки от Маруси, преобразует их в унифицированный формат фреймворка и формирует ответ, совместимый с требованиями платформы. Подключается одной строкой и не мешает работе других адаптеров (например, для Telegram или VK).

    Поддерживает:

    • голосовые и текстовые запросы;
    • сохранение состояния (user/session);
    • карточки и кнопки; TTS без эффектов <speaker effect> (только стандартные звуки);
    • health-check (ping → pong);

    Подключается как любой другой адаптер: bot.use(new MarusiaAdapter(token)). Несколько адаптеров могут работать одновременно — система сама выберет подходящий на основе заголовков и структуры входящего запроса.

    // Простейший навык, который отвечает на приветствие
    import { Bot } from 'umbot';
    import { MarusiaAdapter } from 'umbot/plugins';

    const bot = new Bot()
        .use(new MarusiaAdapter('YOUR_MARUSIA_TOKEN'))
        .addCommand('start', ['привет'], (_text, ctx) => {
            ctx.text = 'Привет! Я твой первый навык для Маруси';
        });

    bot.start('localhost', 3000);
    • Bot
    • BotController
    • BasePlatform

    Hierarchy (View Summary)

    Index

    Constructors

    constructor

    Properties

    _platformOptions? _token? appContext? isVoice limit MAX_TIME_REQUEST platformName signatureName? supportedEvents WARNING_TIME_REQUEST

    Methods

    _getResponse _initTTS _timeLimitLog createApi destroy getContent getLocalStorage getProcessingTime getQueryExample getRatingContext init isCorrectQuery isLocalStorage isPlatformOnQuery isSignatureCheckEnabled send setLocalStorage setQueryData soundProcessing updateTimeStart isVoice

    Constructors

    Properties

    Protected Optional_platformOptions

    _platformOptions?: IAdapterOptions

    Protected Optional_token

    _token?: string
    appContext?: AppContext<unknown, string | IMarusiaWebhookRequest>

    Контекст приложения

    isVoice: boolean = true

    Голосовая ли платформа (TTS-ответ в теле HTTP). Чат-платформы переопределяют на false.

    limit: number | null = null

    Лимит запросов/сек для входящего rateLimiter; null — не ограничивать. Переопределяется адаптером платформы.

    MAX_TIME_REQUEST: number = 2900

    Максимальное время обработки запроса в миллисекундах: при его превышении в лог записывается ошибка (ответ платформе при этом не модифицируется)

    platformName: string = T_MARUSIA

    Идентификатор платформы Маруся.

    signatureName?: string

    Имя поля в заголовке запроса, по которому можно проверить корректность полученного запроса от платформы.

    supportedEvents: readonly TEventType[] = ...

    Универсальные события Маруси: текстовые сообщения и привязка аккаунта (auth).

    WARNING_TIME_REQUEST: number = 2000

    Порог предупреждения в миллисекундах: при его превышении в лог записывается warning

    Methods

    Protected_getResponse

    Protected_initTTS

    Protected_timeLimitLog

    • _timeLimitLog(controller: BotController): void

      При превышении допустимого времени обработки запроса логирует информацию. Вызывается вручную в конце getContent() голосовых адаптеров (Alisa, Marusia, SmartApp); адаптеры чат-платформ его не вызывают.

      • >= WARNING_TIME_REQUEST (по умолчанию 2000 мс) — warning в лог.
      • >= MAX_TIME_REQUEST (по умолчанию 2900 мс) — текст ошибки пишется в controller.platformOptions.error (не в лог).

      Пороги вынесены в protected поля — при необходимости переопределите в потомке.

      Parameters

      Returns void

    • Создаёт API-фасад платформы для controller.api — унифицированный доступ к исходящим возможностям платформы (sendPhoto, answerCallback и т.д.).

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

      Для кастомных платформ: если платформа умеет исходящие API-вызовы (отправка медиа, ответ на callback-кнопку), переопределите метод и верните свой фасад IControllerApi. Удобно завернуть готовую фабрику и дополнить её, либо собрать фасад с нуля. Для голосовых платформ (ответ формируется телом webhook) переопределять не нужно.

      Parameters

      • _controller: BotController

        Контроллер текущего запроса (не используется базовой реализацией; доступен переопределяющим методам)

      Returns IControllerApi | null

      Фасад либо null, если для платформы он недоступен

      class MyPlatformAdapter extends BasePlatform {
          createApi(controller: BotController): IControllerApi | null {
              return makeMyApi(controller); // своя фабрика фасада
          }
      }

    • Метод, который вызывается при уничтожении плагина. В данном методе можно добавить отписку, либо выполнить другие действия.

      Parameters

      • _bot: Bot

        Основной класс приложения

      Returns void | Promise<void>

    • Формирует итоговый webhook-ответ Маруси: версию протокола, response, данные сессии и выбранное state-хранилище (с проверкой лимита байт).

      Parameters

      • controller: BotController

        Контроллер приложения

      • OptionalstateData: Record<string, unknown> | null

        Состояние для сохранения (user/session)

      Returns Promise<IMarusiaWebhookResponse>

      Готовый ответ для webhook Маруси

    • Формирует пример webhook-запроса Маруси для локального тестирования (BotTest).

      Parameters

      • query: string

        Текст команды пользователя

      • userId: string

        Идентификатор пользователя

      • count: number

        Номер сообщения в сессии (0 — новая сессия)

      • state: string | IMarusiaRequestState

        Состояние (session/user) для подстановки в запрос

      Returns Record<string, unknown>

      Заготовка запроса в формате webhook Маруси

    • Инициализирует адаптер: вызывает базовую инициализацию и пробрасывает переданный в конструкторе токен в конфигурацию платформы.

      Parameters

      • appContext: AppContext

        Контекст приложения (конфиги, токены, логгер)

      Returns void

    • Проверяет полученный запрос от платформы на корректность. Из коробки проверка идет по sha256-hmac и включается только если одновременно заданы:

      • appConfig.tokens[<platformName>].token — секретный ключ
      • this.signatureName — имя http-заголовка с подписью

      Если хотя бы один из этих параметров не задан, метод вернёт true без проверки — это opt-in механизм.

      ⚠️ Важно: не все платформы используют HMAC-SHA256 от тела. Переопределите этот метод в адаптере платформы, если её формат подписи отличается:

      • Telegram — переопределён (использует plain x-telegram-bot-api-secret-token).
      • Viber — умолчание корректно (Viber шлёт x-viber-content-signature как HMAC-SHA256(auth_token, body)).
      • VK — переопределён: сверяет поле secret из тела запроса с secret_key из конфигурации (plain-сравнение через timingSafeEqual, без HMAC).
      • Max — переопределён: сверяет заголовок x-max-bot-api-secret со значением webhook-secret (options.secret / tokens.max_app.webhookSecret).
      • Для платформ без подписи (Alisa, Marusia, SmartApp) проверка пропускается из-за отсутствия signatureName.

      Parameters

      • query: string | IMarusiaWebhookRequest

        Объект запроса от платформы

      • Optionalheaders: Record<string, unknown>

        HTTP-заголовки запроса

      Returns boolean

      true — запрос валиден / проверка не включена, false — подпись не сошлась или отсутствует.

    • Проверяет, что входящий webhook-запрос принадлежит Марусе. Отличает Марусю от Алисы по заголовку подписи, meta.client_id и виду session.application.application_id.

      Parameters

      • query: IMarusiaWebhookRequest

        Входящий webhook-запрос

      • Optionalheaders: Record<string, unknown>

        Заголовки HTTP-запроса (проверяется подпись x-marusia-signature)

      Returns boolean

      true, если запрос относится к платформе Маруся

    • Проверка подписи включена, когда выполнены оба условия базовой HMAC-схемы: задан секрет платформы и имя заголовка подписи. Платформы, переопределившие isCorrectQuery (Telegram, VK, MAX), переопределяют и этот метод — источник секрета у них другой (webhookSecret / secret_key).

      Используется ядром при старте для предупреждения о вебхуке без защиты.

      Returns boolean

    Settings

    Member Visibility

    On This Page

    Constructors
    Properties
    Methods