sodium-vk-api

Sodium - фреймворк для удобного создания ботов VK. В его функционал входят инструменты для контекстной обработки сообщения, создания команд, сценариев, работы с JSON и логом.

Ссылки

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

Боты, методы сообщений, клавиатура для ботов

Разработчики

sodium-vk-api, node-vk-bot-api, axios

Инициализация и события

Бот работает по принципам Longpoll, поэтому все ивенты вы будете получать независимо.

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

const { Bot } = require('sodium-vk-api/lib')
const { Data } = require('sodium-vk-api/essentials')

const token = new Data('./config').data.token
const bot = new Bot(token)

// ...

bot.start(err => {
    if (err) {
        console.log(err)
    } else {
        console.log(start)
    }
})

Есть два типа модулей: lib и essentials. В lib хранятся инструменты для работы с контекстом и API, а в essentials - внешние инструменты.

При инициализации объекта Bot в него обязательно нужно вложить токен, которого можно достать из вашего config.json файла, или используя обычную строку.

При открытии доступа к коду вашего бота убедитесь, что токена нигде в коде. Он должен быть скрыт либо в вашем конфиг файле, либо удален из кода бота заранее. Используйте .gitignore для скрытия файлов.

События

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

https://vk.com/dev/groups_events

Обработка

Чтобы обрабатывать конкретное событие, используйте метод .event.

bot.event('wall_post_new', event => {
    bot.send(db.data.userIds, 'В паблике новый пост!')
})

Сообщение

Чтобы добавить реакцию боту, приведите контекс команды через метод .on. У бота есть отдельный метод .message, позволяющий напрямую обрабатывать объекты сообщений.

// команда
bot.on('...', msg => {
    msg == {
        // ... поля ответа API,
        reply: Function, // если есть поле peer_id
        patterns: [...]
    }
})

// прямая обработка
bot.message(msg => { ... })

Ответ

Если поля ответа от API имеют поле peer_id, то в него автоматически вкладывается метод .reply. Он позволяет отправить новое сообщение в эту же беседу или диалог.

bot.message(msg => {
    // ...
    msg.reply('Текст сообщения', {
        // https://vk.com/dev/objects/message
    })
})

Методы бота

Добавление обработчиков

Команда

const { Command } = require('sodium-vk-api/lib')
// ...
bot.addCommands(...new Command('...', { ... }))

Команда события сообщения

const { MessageEventCommand } = require('sodium-vk-api/lib')
// ...
bot.addMessageEventCommands(
    ...new MessageEventCommand('...', event => { ... })
)

Сцена

const { Stage } = require('sodium-vk-api/lib')
// ...
bot.addStages(
    ...new Stage(id, [ ... msg => { ... } ])
)

Плагин

const { Plugin } = require('sodium-vk-api/lib')
// ...
bot.addPlugin(new Plugin(require('./...')))

API

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

Get

bot.get('имя_метода', { ... })

// Получить данные о пользователе
bot.getUser(id, { ... })

// Получить данные о чате
bot.getChat(id, { ... })

// Получить данные о группе
bot.getGroup(id, { ... })

Post

bot.post('имя_метода', { ... })

// Отправить сообщение
bot.send(id, { ... })

// Отправить реакцию на событие сообщения.
// Подробнее можно ознакомиться в главе
// "Клавиатура и кнопки"
bot.sendMessageEventAnswer(eventObject, { ... })

Прочее

Локальные сообщения

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

bot.localMessage({ ... }, ...msg => { ... })

Сокеты

Ответы бота можно подключить к внешним обработчикам или другим ботам.

bot.socketTo(...Bot || Function)

Команды

Простые команды

Простые команды добавляются методом .on и проверяют текст сообщения целиком. Вы также можете использовать регулярные выражения.

// Префикс "~" означает, что текст сообщения
// не проверяется на регистр букв
bot.on('~Начать|Старт', msg => {
    // Можно проверить на то, что
    // пользователь уже писал боту
    if (!db.data.chats.includes(msg.user)) {
        msg.reply('Начать уже пол дела!')
    }
})

bot.on(/^\w(?:\s[+*]\s\w)+$/g, msg => {
    let calculate = new Function(`return ${msg.content}`)
    msg.reply(calculate())
})

Контекстные команды

Контекстные команды добавляются методом .command и проверяют только начало сообщения, используя синтаксис паттернов.

Синтаксис

// в данном случае первый паттерн проверяется на
// два слова, так что пользователь может написать
// и то, и то.
bot.command('~привет|салют', msg => {
    msg.reply('Привет-привет!')
    console.log(msg.patterns.list)
    // > ["привет", остальной текст]
})

// в данном случае паттерн "бот, " не обязателен
// для указания, тоесть пользователь может написать
// "повтори ..." и бот все равно получит сообщение.
bot.command(
    "~(бот, )повтори",
    msg => {
        let patterns = msg.patterns
        if (patterns.arguments) {
            msg.reply(patterns.arguments[0])
        }
    }
)

// в данном случае текст после слова "сложи" или "сумма"
// будет разделен запятой или пробелом
bot.command(
    "~(бот, )сложи|сумма [,| ]",
    msg => {
        let patterns = msg.patterns
        let args = patterns.args
        if (args) {
            if (args.every(v => Number(v)) {
                args = args.map(v => Number(v))
                msg.reply(args.reduce(a, b => a + b))
            }
        }
    }
) 

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

Продвинутые команды

Чтобы добавить продвинутую команду в бота, нужно инициализировать новый объект команды и добавить его при помощи метода .addCommand.

bot.addCommand(new Command("(выражение)", {
    caseSensitive?: true || false,
    // проверка на регистр букв
    argumentsCount?: true || int,
    // кол-во нужных аргументов
    access?: Function(responseObject),
    // функция проверки на доступ к команде
    patterns?: Array<Object>,
    // список готовых объектов паттернов
    callback: Function(responseObject)
    // код команды
})

Клавиатура и кнопки

const { Keyboard } = require('sodium-vk-api/lib')

Чтобы отправить клавиатуру, вам нужно включить в метод .reply сообщения объект клавиатуры.

https://vk.com/dev/bots_docs_3

Классы

Карсас

let mainKeyboard = new Keyboard.Layout(buttons, options)

bot.on('...', msg => {
    // ...
    msg.reply('...', {
        keyboard: mainKeyboard
    })
})

Кнопка

Кнопки вкладываются в каркас сообщения. ****Чтобы создать новый ряд кнопок, добавьте их массив, или добавьте новую кнопку после массива или в начале списка кнопок.

new Button(label, color, action)

// Коды цветов:
// %primary, %secondary,
// %negative, %positive

let mk = new Keyboard.Layout(
    ['%primaryПодтвердить', '%negativeОтменить'],
    'Пересоздать'
, { inline: true })

let mk = new Keyboard.Layout(
    new Keyboard.Button('Заказать', 'primary', {
        type: 'callback',
        payload: '"command": {"order"}'
    })
, { inline: true })

Колбек кнопки

Этот тип кнопок работает только на мобильных устройствах и уникален тем, что эти кнопки работают независимо, тоесть бот и пользователь могут не обмениваться сообщениями.

https://vk.com/dev/bots_docs_5

let panel = new Keyboard.Layout(
    new Keyboard.Button('boot', false, {
        type: 'callback',
        payload: '"command": {"boot"}'
    },
    new Keyboard.Button('shutdown', false, {
        type: 'callback',
        payload: '"command": {"shutdown"}'
    },
    new Keyboard.Button('scan', false, {
        type: 'callback',
        payload: '"command": {"scan"}'
    },
    new Keyboard.Button('deploy', false, {
        type: 'callback',
        payload: '"command": {"deploy"}'
    }
)

При нажатии на кнопку бот получает событие message_event, его можно обработать при помощи метода .event.

bot.event('message_event', event => {
    console.log('Что-то было нажато!')
})

Но когда вам нужно обрабатывать поле payload - в дело вступают команды событий сообщения.

const { MessageEventCommand } = require('sodium-vk-api')
// ...
bot.addMessageEventCommands(
    new MessageEventCommand(
        p => p.command == 'команда',
        // или
        'команда',
        // или
        [...'команда'],
    actionObject)
    // actionObject - действие после нажатия на кнопку.
    // см. документацию
)

Сцены

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

const { Stage } = require('sodium-vk-api/lib')

Давайте рассмотрим один пример использования сцены и попробуем его разобрать.

const { Stage, Keyboard } = require('sodium-vk-api/lib')
// ...
bot.on('~начать|создать', msg => {
    if (!db.data.userIds.includes(msg.from_id)) {
        let form = { name: false, age: false }
        let cancel = {
            keyboard: new Keyboard.Layout('Отмена')
        }
        msg.reply('Как вас зовут?', cancel)
        bot.addScene(new Stage(msg.from_id, [
            (msg, frames) => {
                if (!msg.text) {
                    msg.reply('Как вас зовут?', cancel)
                    frames.back()
                } else if (msg.text == 'Отмена') {
                    msg.reply('Создание анкеты отменено.')
                    frames.close()
                } else {
                    form.name = msg.text
                    msg.reply('Сколько вам лет?', cancel)
                    frames.next()
                }
            },
            (msg, frames) => {
                if (!msg.text || !Number(msg.text)) {
                    msg.reply('Как вас зовут?', cancel)
                    frames.back()
                } else if (msg.text == 'Отмена') {
                    msg.reply('Создание анкеты отменено.')
                    frames.close()
                } else {
                    form.age = Number(msg.text)
                    frames.close()
                }
            }
        ]))
        if (form.name && form.age) {
            db.edit('forms', forms => forms.push(form))
            msg.reply('Анкета создана!')
        }
    }
})

Чтобы добавить сцену в бота, мы воспользуемся методом .addScene.

bot.addScene(new Stage(id, ...))

При создании новой сцены мы указываем айди пользователя и список фреймов. Если пользователь отправляет сообщения после инициализации сцены, то помимо команд сообщение передается в первый фрейм. Давайте рассмотрим, что можно делать во фрейме.

new Stage(id, [
    // ... фреймы
    (msg, frames) => {
        // ...
        frames.next() // сдвигаемся к следующему
        frames.back() // сдвигаемся к предыдущему
        frames.skip(2) // пропускаем два
        frames.slideTo(0) // перемещаемся к первому
        frames.move(2) // сдвигаемся на два вперед
        frames.close() // закрываем сцену
    }
    // ... фреймы
])

При завершении сцены она удаляется из бота и больше не получает сообщения.

Инструменты

В Sodium есть полезные инструменты, облегчающие работу с ботом.

Работа с JSON

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

const { Data } = require('sodium-vk-api/essentials')

Теперь укажем путь файлу и дефолтный каркас. Учтите, что нужно указывать только .json файлы.

let db = new Data('./data.json', { users: {}, chats: {} })

Чтение-запись

Чтобы получить любое поле из json файла, просто используйте поле .data и стандартный путь JS объекта.

let name = db.data.users['bifot'].name

Чтобы изменить данные всего файла, используйте то же поле .data и присвойте ему объект.

db.data = { users: {}, chats: {} } // wipe

// Можно избежать этой строки методом .wipe
db.wipe()

Если хотите отредактировать какое-то поле, используйте метод .edit.

db.edit('users.soiran.name', name => 'Марк')

Если хотите проверить, существует ли какое-то поле, попробуйте метод .exists.

db.exists('users.romiro27') // true || false

Модели

Модели используются для добавления похожих по структуре объектов в json файл.

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

// db.addModel(id, schema, options)
db.addModel('user', {
    nickname: v => v instanceof String,
    name: v => v instanceof String, // проверка на значение
    id: v => Number(v),
    messages: 0 // необязательное поле
})

Добавление

// Добавление в массив:
// db.spawn(id, path, keyField, struct)
db.new('user', 'users', false, {
    nickname: 'shirosakino',
    name: 'Сергей',
    id: 410685632
})

// Добавление в объект:
// db.spawn(id, path, keyField, struct)
db.new('user', 'users', '$id', {
    nickname: 'shirosakino',
    name: 'Сергей',
    id: 410685632
})

Логгер

Красивый логгер для вашего кода. Просто инициализуйте новый объект с алиасом и используйте методы сообщений.

const { Logger } = require('sodium-vk-api/essentials')

Создавая новый логгер - мы указываем алиас и цвет(дефолтный синий).

var log = new Logger('Bot')

Типы логов

Как говориться - на любой вкус и цвет.

log.msg('Обычное сообщение')
log.info('Важная информация')
log.result('Результат процесса')
log.error('Ошибка')
log.warn('Предупреждение')
log.debug('Дебаг сообщение')
log.loading('Загрузка')
log.trace('Потоковая информация')