Updates

Базовый модуль получения событий из User Long Poll, Bots Long Poll и Callback API.

Описание типов

API Reference [EN]

Инициализация

Опции конструктора

import { API, Upload, Updates } from 'vk-io';

const api = new API({
    token: process.env.TOKEN
});

const upload = new Upload({
    api
});

const updates = new Updates({
    api,

    upload
});

Концепт

Класс является обобщением всех трёх способов получения событий в одном интерфейсе. События приходят в унифицированных контекстах, у каждого контекста есть основной тип события и его подтипы. За счёт этого вы можете указать основной тип события, и вы будете получать все его подтипы. Или можно указать только подтип.

Совет

Вы можете отдельно почитать про контексты здесь

// События по типу
updates.on('message', (context) => {
    // context.type // message
    // context.subTypes // ['message_new']
});

// События по подтипу
updates.on('message_new', (context) => {
    // context.type // message
    // context.subTypes // ['message_new']
});

Middleware

Сперва может показатся что класс является инстанцией EventEmitter, но это не так. Модуль использует цепочку middleware. Это позволяет более элегантно обрабатывать события, а именно:

• Обработка ошибок
• Фильтрация событий
• Модификация контекста
• Вызывать какие-то действия после работы главных обработчиков

Простой пример с модификацией контекста:

updates.on('message', (context, next) => {
    context.myProp = 1;

    return next();
});

updates.on('message', (context, next) => {
    console.log('My prop', context.myProp); // 1
});

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

Пример неправильной работы:

updates.use((context, next) => {
    if (!context.isOutbox) {
        return;
    }

    return next();
});

// Больше никогда не вызовется, так как у этого контекста нет свойства `isOutbox`
updates.on('like', () => {...});

Исправить это достаточно просто, можно использовать сразу метод .on() или напрямую вызывать context.is()

updates.use((context, next) => {
    if (context.is(['message']) && !context.isOutbox) {
        return;
    }

    return next();
});

// Теперь контекст дойдёт до этого middleware
updates.on('like', () => {...});

С использованием .on()

updates.on('message', (context, next) => {
    if (!context.isOutbox) {
        return;
    }

    return next();
});

// Теперь контекст дойдёт до этого middleware
updates.on('like', () => {...});

Внимание

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

Список событий

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

Webhook (Callback API)

В настройках группы нужно выставить версию Callback API выше 5.130 и включить нужные события

Предназначен для групп

Имеет полный набор данных

Запуск встроенного сервера

updates.start({
    webhook: {
        // ...
        path: '/super-secret-webhook-path'
    }
});

Использование express middleware

app.post('/super-secret-webhook-path', updates.getWebhookCallback());

Использование koa middleware

Предполагается что вы уже разобрали тело запроса например через koa-body

router.post('/super-secret-webhook-path', updates.getKoaWebhookMiddleware())

Использование нативного веб сервера

http.createServer(updates.getWebhookCallback('/super-secret-webhook-path'));

Polling (Bots Long Poll)

В настройках группы нужно выставить версию Bots Long Poll API выше 5.130 и включить нужные события

Предназначен для групп

Имеет полный набор данных

Совет

По умолчанию произойдёт автоматическое определение pollingGroupId для запуска Bots Long Poll, для избежания дополнительного запроса стоит передавать его заранее.

updates.start();

Polling (User Long Poll)

В отличие от Bots Long Poll и Callback API данные приходят частично, это стоит учитывать. Нужно перезагружать события или прикрепления для получения полного объекта, по умолчанию с них доступны только ID.

Предназначен для страниц пользователей

Имеет частичный набор данных

updates.startPolling();

Ручная передача событий

Если по каким-то причинам вам не подошли предыдущие автоматические способы получения событий, вы можете их передавать библиотеке вручную с помощью updates.handleWebhookUpdate() или updates.handlePollingUpdate()