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>;
        getDeliveryId?: (query: TQuery) => string | null;
        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>;
        getResponseTimeout?: () => number | null;
        getUpdates?: (signal: AbortSignal) => Promise<unknown[] | null>;
        init: (appContext: AppContext, bot: Bot) => void;
        isCorrectQuery: (
            query: TQuery,
            headers?: Record<string, unknown>,
            parsedQuery?: unknown,
        ) => boolean;
        isLocalStorage: (controller: BotController) => boolean;
        isPlatformOnQuery: (
            query: TQuery,
            headers?: Record<string, unknown>,
        ) => boolean;
        isSignatureCheckEnabled?: () => boolean;
        isSignatureSupported?: () => 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

    Methods

    createApi? send

    Properties

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

    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

    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>

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

    getDeliveryId?: (query: TQuery) => string | null

    Уникальный ID доставки вебхука — для дедупликации повторов.

    Мессенджеры повторяют доставку, если не получили 2xx вовремя. Ядро помнит ID принятых доставок (в памяти процесса, 1 час) и на повтор отвечает 200 ok, не запуская логику повторно. Повтор, пришедший во время обработки исходного запроса, ждёт его исхода и обрабатывается заново, если исходный упал с 500. Ключ дополняется хэшем тела запроса, поэтому поддельный запрос с угаданным ID не заблокирует настоящий апдейт.

    Реализуйте, только если ответ платформе не несёт содержимого (ответ уходит через API): повтор получит тело ok. Голосовым платформам метод не нужен.

    Type Declaration

      • (query: TQuery): string | null

      • Parameters

        • query: TQuery

          разобранное тело запроса

        Returns string | null

        ID доставки или null, если в запросе его нет

    getDeliveryId(query: IMyUpdate): string | null {
        return query.update_id === undefined ? null : String(query.update_id);
    }
    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>

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

    getResponseTimeout?: () => number | null

    Сколько платформа ждёт ответа на запрос, мс.

    Ядро выполняет запросы одного пользователя по очереди. Если платформа ждёт ответ ограниченное время (Алиса, Маруся, SmartApp), запрос ждёт предыдущий не дольше половины оставшегося времени и затем выполняется параллельно — иначе ответ опоздал бы. BasePlatform отвечает null: мессенджеры получают ответ через API, и жёсткого срока у них нет.

    Type Declaration

      • (): number | null

      • Returns number | null

        Срок ответа в мс или null, если срока нет

    class MyVoiceAdapter extends BasePlatform {
        // Платформа обрывает запрос через 3 секунды
        getResponseTimeout(): number | null {
            return 2900;
        }
    }
    getUpdates?: (signal: AbortSignal) => Promise<unknown[] | null>

    Long polling: один запрос за новыми обновлениями платформы (Telegram getUpdates, VK Bots Long Poll, MAX GET /updates). Реализуйте, если платформа умеет отдавать обновления по запросу, — тогда бота можно запустить bot.startPolling() без публичного HTTPS-адреса.

    Ядро вызывает метод в цикле и обрабатывает каждое обновление как запрос вебхука, но без проверки подписи: обновление получено от API платформы по токену бота. Позицию чтения (offset, marker, ts) хранит адаптер: следующий вызов должен вернуть обновления после уже отданных. Запрос должен завершаться по signal — так bot.stopPolling() и bot.close() не ждут окончания долгого запроса. Передавайте сигнал через Request.signal: AbortSignal.any() с этим сигналом в Node 20 копит память, ведь сигнал живёт весь сеанс polling.

    Временную ошибку (сеть, 5xx) бросайте исключением — ядро повторит вызов с растущей паузой. Если polling невозможен (неверный токен, у бота активен вебхук), запишите причину в лог и верните null: ядро остановит цикл этой платформы.

    Type Declaration

      • (signal: AbortSignal): Promise<unknown[] | null>

      • Parameters

        • signal: AbortSignal

          Сигнал остановки polling

        Returns Promise<unknown[] | null>

        Обновления в формате тела вебхука платформы, [] — новых нет, null — остановить polling

    class MyAdapter extends BasePlatform {
        #offset = 0;

        async getUpdates(signal: AbortSignal): Promise<unknown[] | null> {
            const request = new Request(this.appContext as AppContext);
            request.maxTimeQuery = 35_000; // дольше, чем платформа держит запрос (25 с)
            request.signal = signal;
            const res = await request.send<{ id: number }[]>(
                `https://api.example.com/updates?offset=${this.#offset}&timeout=25`,
            );
            if (res.httpStatus === 401) {
                this.appContext?.logError('MyAdapter: неверный токен, polling остановлен.');
                return null;
            }
            if (!res.status || !res.data) {
                throw new Error(`HTTP ${res.httpStatus ?? 'нет ответа'}`);
            }
            const updates = res.data;
            if (updates.length) {
                this.#offset = updates[updates.length - 1].id + 1;
            }
            return updates;
        }
    }
    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>,
        parsedQuery?: unknown,
    ) => boolean

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

    Type Declaration

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

      • Parameters

        • query: TQuery

          Запрос от платформы. В webhookHandle — сырое тело строкой (от него считается HMAC-подпись)

        • Optionalheaders: Record<string, unknown>

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

        • OptionalparsedQuery: unknown

          То же тело, уже разобранное из JSON фреймворком. Передаётся в webhookHandle/webhookEvent: адаптеру, которому для проверки нужен объект (секрет в теле, как у VK), не нужно разбирать JSON второй раз.

        Returns boolean

        true, если запрос прошёл проверку

    isCorrectQuery(query, headers, parsedQuery) {
      const body = (parsedQuery ?? (typeof query === 'string' ? JSON.parse(query) : query)) as { secret?: string };
      const got = Buffer.from(body.secret ?? '');
      const expected = Buffer.from(this.secret);
      // timingSafeEqual из node:crypto — сравнение секрета за постоянное время
      return got.length === expected.length && timingSafeEqual(got, expected);
    }
    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 узнаёт свой апдейт по полю update_id; секрет вебхука проверяет isCorrectQuery
    isPlatformOnQuery(query) {
      return typeof query === 'object' && query !== null && 'update_id' in query;
    }
    isSignatureCheckEnabled?: () => boolean

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

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

    isSignatureSupported?: () => boolean

    Умеет ли платформа подписывать вебхук (секрет в заголовке или в теле).

    Ядро предупреждает при старте о вебхуке без проверки подписи только для таких платформ: у Алисы, Маруси и SmartApp подписи нет, и советовать задать секрет бессмысленно. BasePlatform отвечает true, если задан signatureName или переопределён isSignatureCheckEnabled. Без метода (прямая реализация интерфейса) ядро судит по тем же признакам.

    Type Declaration

      • (): boolean

      • Returns boolean

        true, если у платформы есть механизм подписи вебхука

    class MyAdapter extends BasePlatform {
        // Подписи у платформы нет — предупреждение при старте не нужно
        isSignatureSupported(): boolean {
            return false;
        }
    }
    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

    Settings

    Member Visibility

    On This Page

    Methods
    Properties