umbot
    Preparing search index...

    Interface IPlatformAdapter<TQuery>

    Интерфейс для адаптеров платформы (Алиса, SmartApp, Telegram, VK и др.).

    Обеспечивает унификацию обработки запросов от разных платформ. Реализуется как плагин (IPlugin) и регистрируется в приложении.

    interface IPlatformAdapter<TQuery = unknown> {
        destroy: (bot: Bot) => void | Promise<void>;
        getContent: (
            controller: BotController,
            stateData?: Record<string, unknown> | null,
        ) => string | object | Promise<string | object>;
        getLocalStorage: <TStorageResult = unknown>(
            controller: BotController,
        ) => TStorageResult | Promise<TStorageResult>;
        getProcessingTime: (controller: BotController) => number;
        getQueryExample: (
            query: string,
            userId: string,
            count: number,
            state: string | Record<string, unknown>,
        ) => Record<string, unknown>;
        getRatingContext: (
            controller: BotController,
        ) => string | object | Promise<string | object>;
        init: (appContext: AppContext, bot: Bot) => void;
        isCorrectQuery: (
            query: TQuery,
            headers?: Record<string, unknown>,
        ) => boolean;
        isLocalStorage: (controller: BotController) => boolean;
        isPlatformOnQuery: (
            query: TQuery,
            headers?: Record<string, unknown>,
        ) => boolean;
        isSignatureCheckEnabled?: () => boolean;
        isVoice: boolean;
        limit: number | null;
        platformName: string;
        setLocalStorage: <TStorageData>(
            data: TStorageData,
            controller: BotController,
        ) => void | Promise<void>;
        setQueryData: (
            query: TQuery,
            controller: BotController,
        ) => boolean | Promise<boolean>;
        signatureName?: string;
        supportedEvents?: readonly TEventType[];
        updateTimeStart: (controller: BotController) => void;
        createApi?(controller: BotController): IControllerApi | null;
        send(
            userId: string | number,
            controllerOrText: string | BotController<IUserData, IPlatformData>,
        ): unknown;
    }

    Type Parameters

    • TQuery = unknown

    Hierarchy (View Summary)

    Implemented by

    Index

    Properties

    destroy getContent getLocalStorage getProcessingTime getQueryExample getRatingContext init isCorrectQuery isLocalStorage isPlatformOnQuery isSignatureCheckEnabled? isVoice limit platformName setLocalStorage setQueryData signatureName? supportedEvents? updateTimeStart

    Methods

    createApi? send

    Properties

    destroy: (bot: Bot) => void | Promise<void>

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

    Type Declaration

      • (bot: Bot): void | Promise<void>

      • Parameters

        • bot: Bot

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

        Returns void | Promise<void>

    getContent: (
        controller: BotController,
        stateData?: Record<string, unknown> | null,
    ) => string | object | Promise<string | object>

    Формирует тело ответа для отправки пользователю.

    Возвращает платформо-специфичный ответ (например, JSON для Алисы). Для платформ, которые отправляют ответ напрямую (например, Telegram через sendMessage), метод может возвращать { ok: true } или аналог.

    Type Declaration

      • (
            controller: BotController,
            stateData?: Record<string, unknown> | null,
        ): string | object | Promise<string | object>

      • Parameters

        • controller: BotController

          контроллер с готовым ответом

        • OptionalstateData: Record<string, unknown> | null

          данные для локального хранилища

        Returns string | object | Promise<string | object>

        ответ в формате, понятном платформе

    getLocalStorage: <TStorageResult = unknown>(
        controller: BotController,
    ) => TStorageResult | Promise<TStorageResult>

    Получает данные из локального хранилища платформы.

    Type Declaration

      • <TStorageResult = unknown>(
            controller: BotController,
        ): TStorageResult | Promise<TStorageResult>

      • Type Parameters

        • TStorageResult = unknown

        Parameters

        • controller: BotController

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

        Returns TStorageResult | Promise<TStorageResult>

        данные, сохранённые ранее

    getProcessingTime: (controller: BotController) => number

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

    Основано на разнице между updateTimeStart и текущим временем.

    Type Declaration

      • (controller: BotController): number

      • Parameters

        • controller: BotController

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

        Returns number

        время обработки в мс

    getQueryExample: (
        query: string,
        userId: string,
        count: number,
        state: string | Record<string, unknown>,
    ) => Record<string, unknown>

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

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

    Type Declaration

      • (
            query: string,
            userId: string,
            count: number,
            state: string | Record<string, unknown>,
        ): Record<string, unknown>

      • Parameters

        • query: string

          текст запроса

        • userId: string

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

        • count: number

          счётчик для уникальности

        • state: string | Record<string, unknown>

          состояние сессии

        Returns Record<string, unknown>

        объект, имитирующий входящий запрос платформы

    getRatingContext: (
        controller: BotController,
    ) => string | object | Promise<string | object>

    Формирует контекст для отправки рейтинга (если поддерживается платформой).

    Используется только на платформах с поддержкой рейтинга (например, Сбер SmartApp). Метод обязателен, но BasePlatform уже даёт реализацию по умолчанию (делегирует getContent), поэтому переопределять его нужно только для спец-формата рейтинга.

    Type Declaration

      • (controller: BotController): string | object | Promise<string | object>

      • Parameters

        • controller: BotController

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

        Returns string | object | Promise<string | object>

        данные для отправки рейтинга

    init: (appContext: AppContext, bot: Bot) => void

    Метод инициализации плагина. Вызывается один раз при подключении через bot.use().

    Type Declaration

      • (appContext: AppContext, bot: Bot): void

      • Parameters

        • appContext: AppContext

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

        • bot: Bot

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

        Returns void

    isCorrectQuery: (query: TQuery, headers?: Record<string, unknown>) => boolean

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

    Type Declaration

      • (query: TQuery, headers?: Record<string, unknown>): boolean

      • Parameters

        • query: TQuery

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

        • Optionalheaders: Record<string, unknown>

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

        Returns boolean

    isLocalStorage: (controller: BotController) => boolean

    Указывает, поддерживает ли платформа локальное хранилище.

    Type Declaration

      • (controller: BotController): boolean

      • Parameters

        • controller: BotController

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

        Returns boolean

        true, если локальное хранилище доступно

    isPlatformOnQuery: (query: TQuery, headers?: Record<string, unknown>) => boolean

    Определяет, принадлежит ли входящий запрос данной платформе.

    Метод проверяет заголовки или структуру тела запроса. Используется для маршрутизации входящих запросов между адаптерами.

    Type Declaration

      • (query: TQuery, headers?: Record<string, unknown>): boolean

      • Parameters

        • query: TQuery

          входящий запрос (тело или объект)

        • Optionalheaders: Record<string, unknown>

          HTTP-заголовки (если есть)

        Returns boolean

        true, если запрос относится к этой платформе, иначе false

    // Telegram проверяет наличие заголовка 'X-Telegram-Bot-API-Secret-Token'
    isPlatformOnQuery(query, headers) {
      return headers?.['x-telegram-bot-api-secret-token'] === this.secret;
    }
    isSignatureCheckEnabled?: () => boolean

    Возвращает, включена ли проверка подписи вебхука для этой платформы с текущей конфигурацией (секрет задан).

    Используется ядром в bot.start() для предупреждения о вебхуке, который принимает запросы платформы без проверки подлинности. Адаптеры платформ с подписью переопределяют метод: базовая реализация считает проверку включённой при заданных tokens[platform].token и signatureName (схема HMAC, например Viber).

    isVoice: boolean

    Флаг, указывающий, что платформа голосовая (например, Алиса, Маруся).

    limit: number | null

    Определяет лимит платформы. В значение указывается количество запросов, которое можно отправить платформе за 1 секунду. В случае, если у платформы нет ограничений, можно указать 0 или null. По умолчанию null

    platformName: string

    Уникальное имя платформы (например, 'telegram', 'alisa').

    setLocalStorage: <TStorageData>(
        data: TStorageData,
        controller: BotController,
    ) => void | Promise<void>

    Сохраняет данные в локальное хранилище платформы.

    Type Declaration

      • <TStorageData>(
            data: TStorageData,
            controller: BotController,
        ): void | Promise<void>

      • Type Parameters

        • TStorageData

        Parameters

        • data: TStorageData

          данные для сохранения

        • controller: BotController

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

        Returns void | Promise<void>

    setQueryData: (
        query: TQuery,
        controller: BotController,
    ) => boolean | Promise<boolean>

    Инициализирует данные запроса в контроллере приложения.

    Парсит входящий запрос и заполняет controller.userCommand, controller.payload и другие поля. Вызывается после подтверждения, что запрос принадлежит этой платформе.

    Type Declaration

      • (query: TQuery, controller: BotController): boolean | Promise<boolean>

      • Parameters

        • query: TQuery

          входящий запрос

        • controller: BotController

          контроллер приложения для текущего запроса

        Returns boolean | Promise<boolean>

        false, если запрос повреждён или не может быть обработан; иначе true

    signatureName?: string

    Имя http-заголовка, в котором платформа передаёт подпись/секрет вебхука.

    Заполняется адаптером для платформ с подписью в http-заголовке (Telegram, Viber, MAX). VK проверяет секрет в теле запроса и задаёт только isSignatureCheckEnabled. Отсутствие поля означает, что проверка подписи для платформы недоступна по построению (Alisa, Marusia, SmartApp). Используется ядром для предупреждения при старте о вебхуке без защиты.

    supportedEvents?: readonly TEventType[]

    Универсальные события (TEventType), которые адаптер может выставить в controller.eventType. Источник знания для валидации bot.addEvent(...): таблица принадлежит адаптеру, поэтому кастомные платформы участвуют в проверке автоматически.

    Опционально: BasePlatform уже объявляет дефолт ['message'], поэтому наследникам достаточно переопределить поле при поддержке других событий. Отсутствие поля (прямая реализация интерфейса) приравнивается к ['message'].

    updateTimeStart: (controller: BotController) => void

    Устанавливает время начала обработки запроса.

    Используется для измерения времени отклика (processingTime).

    Type Declaration

    Methods

    • Создаёт API-фасад платформы для controller.api.

      Фасад даёт бизнес-логике доступ к исходящим возможностям платформы (отправить медиа, ответить на callback-кнопку) без ручного конструирования платформенных Request-классов. Ядро вызывает этот метод само — знает о платформах только через данный контракт, поэтому добавить фасад новой платформе можно, не трогая ядро.

      Опционален: BasePlatform даёт реализацию по умолчанию (возвращает null — фасад недоступен), поэтому переопределять его нужно только платформам с исходящими API-вызовами. Голосовым платформам (Алиса, Маруся, SmartApp) фасад не нужен: их ответ формируется телом webhook.

      Parameters

      • controller: BotController

        Контроллер текущего запроса

      Returns IControllerApi | null

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

      class MyPlatformAdapter extends BasePlatform {
          // Своя платформа + свой фасад — достаточно переопределить один метод
          createApi(controller: BotController): IControllerApi | null {
              return makeMyApi(controller);
          }
      }

    • Отправка текста пользователю Этот метод используется для активных рассылок — когда навык или бот инициирует диалог первым (например, уведомление). В данном методе необходимо поддержать отправку результата пользователю. Это необходимо для того, чтобы само приложение смогло продолжить диалог.

      Если ваша платформа не поддерживает отправку сообщений без входящего запроса (как Алиса), оставьте реализацию пустой или верните заглушку.

      Parameters

      • userId: string | number

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

      • controllerOrText: string | BotController<IUserData, IPlatformData>

        Контроллер приложения или текст. Если необходимо отправить просто текст, можно передать строку, в случае, если необходимо передать картинку звук и тд, то необходимо корректно заполнить контроллер.

      Returns unknown

    Settings

    Member Visibility

    On This Page

    Properties
    Methods