node-vkcoinapi

Модуль для работы с API VK Coin

Особенности:

Реализованы все методы официального API
Удобная документация и хорошая тех. поддержка
Возможность получения платежей в режиме реального времени
Активные обновления
Не тянет за собой много библиотек
Есть своя беседа для обсуждения обновлений/багов

Планы:

Сделать WebHooks
Сделать гайды по установке и использованию на YouTube
Сделать папку с примерами

Установка

Windows:

Скачайте и установите последнюю версию Node.JS
Создайте в удобном месте папку, например vkcoin
Перейдите в командную строку: Win + R > cmd
Перейдите в папку: cd (путь до вашей папки)
Пропишите: npm i node-vkcoinapi

Ubuntu:

Установите Node.JS по этому гайду
Создайте в удобном месте папку, например vkcoin
Перейдите в папку: cd (путь до вашей папки)
Пропишите: npm i node-vkcoinapi

Начало работы

Для начала использования, вам нужно создать в своей папке исполняемый файл, пусть это будет index.js

Теперь его нужно открыть и импортировать библиотеку:

const VKCOINAPI = require('node-vkcoinapi');

const vkcoin = new VKCOINAPI(options);

Опция	Тип	Описание
options	Object	Опции конструктора
options.key	String	Ключ для взаимодействия с API
options.userId	Number	Ваш айди ВК
options.token	String	Ваш токен

Где взять эти значения

Получение ключа (key): описано в начале этой статьи
Получение айди вк (userId):

Откройте свою аватарку и в адресной строке вы увидите подобное: https://vk.com/fakeman.cat_fmc?z=photo236908027_456259706%2Falbum236908027_0%2Frev

Вашим айди будет являться число после слова photo. В этом случае 236908027

Получение токена (token):

Откройте эту ссылку и нажмите разрешить

После этого в адресной строке будет подобное: https://api.vk.com/blank.html#access_token=xxxxxxxxxxxx&expires_in=0&user_id=user_id&email=email

Токеном будет являться строка от access_token до &expires. В этом случае xxxxxxxxxxxx

Токен нужен для получения событий через WebSocket (Моментальное получение платежей)

API

call - Вызывает апи-метод по его названию (Нужен, если я не успел обновить модуль)

Например. Вышел новый метод у vkcoin, пусть это будет send_from_admin.

Выглядеть в виде ссылки это будет так: https://coin-without-bugs.vkforms.ru/merchant/send_from_admin. Вызывать его нужно так:

async function run() {
    const result = await vkcoin.api.call('send_from_admin', { toId: 236908027 });

    console.log(result);
}   

run().catch(console.error);

Наглядно можно показать на уже существующем методе (send - делает перевод коинов):

async function run() {
    const result = await vkcoin.api.call('send', { toId: 1, amount: 1000, markAsMerchant: true });

    console.log(result);
}

Параметр	Тип	Описание
method	String	Исполняемый метод
params	Object	Параметры метода

При вызове методов с помощью call указывать merchatId и key в параметрах не нужно

getTransactionList - Получает список ваших транзакций

async function run() {
    const result = await vkcoin.api.getTransactionList(tx);
    
    console.log(result);
}

run().catch(console.error);

Параметр	Тип	Описание
tx	Number[]	Массив айди переводов для получения ИЛИ [1] - последняя 1000 транзакций, [2] - 100

sendPayment - Делает перевод другому пользователю (в десятичных долях)

async function run() {
    const result = await vkcoin.api.sendPayment(toId, amount, fromShop); // 1 коин = 1000 ед.
    
    console.log(result);
}

run().catch(console.error);

Параметр	Тип	Описание
toId	Number	Айди получателя
amount	Number	Сумма перевода
fromShop	Boolean	Если true, то платеж отправится от имени магазина

getLink - Получает ссылку для перевода

function run() {
    const link = vkcoin.api.getLink(amount, fixation);
    
    console.log(link);
}

run().catch(console.error);

Параметр	Тип	Описание
amount	Number	Сумма перевода
fixation	Boolean	Фиксированная сумма или нет

formatCoins - Делает получаемое из API значение коинов читабельным. Например, приходит значение 1234567890. Этот метод сделает значение таким: 1 234 567,890

Это можно использовать в паре с другим методом:

async function run() {
    const trans = await vkcoin.api.getTransactionList([2]);

    const fixTrans = trans.response.map((tran) => {
        tran.amount = vkcoin.api.formatCoins(tran.amount);

        return tran;
    });

    console.log(fixTrans);
}

run().catch(console.error);

Параметр	Тип	Описание
coins	Number	Входящее значение коинов

getBalance - Получает баланс по айди пользователей

getMyBalance - Получает баланс текущего пользователя

async function run() {
    const balances = await vkcoin.api.getBalance([1, 100, 236908027]);
    const myBalance = await vkcoin.api.getMyBalance();

    console.log({ balances, myBalance });
}

run().catch(console.error);

Среди этих методов аргумент принимает только getBalance:

Параметр	Тип	Описание
userIds	Number\|Number[]	Массив айди пользователей

setShopName - Меняет название магазина

async function run() {
    const result = await vkcoin.api.setShopName(name);
    
    console.log(result);
}

run().catch(console.error);

Параметр	Тип	Описание
name	String	Новое имя для магазина

setCallback - Изменяет адрес для получения событий

async function run() {
    const result = await vkcoin.api.setCallback(callback);
    
    console.log(result);
}

run().catch(console.error);

Параметр	Тип	Описание
callback	String	Новый адрес с указанием пути

removeCallback - Удаляет адрес для получения событий

async function run() {
    const result = await vkcoin.api.removeCallback();
    
    console.log(result);
}

run().catch(console.error);

Параметров не принимает

Updates

updates - Позволяет "прослушивать" события в VK Coin. Пока что я реализовал перехват входящего платежа, но вскоре придумаю что-нибудь ещё. И да, впервые работаю с сокетами :)

Запуск

Для запуска прослушивания есть 3 способа. Longpoll, webhook и отдельный middleware для Express

startPolling - Запускает обмен запросами между клиентом и сервером в режиме реального времени (WebSocket). Является лучшим и быстрым способом получения событий:

vkcoin.updates.startPolling(callback);
    
/* Тут ваши действия со слушателем */

Параметр	Тип	Описание
callback	Function	Функция обратного вызова, принимает в себя аргумент event

Советую в аргумент callback вставлять console.log или любой другой метод для отслеживания действий сокетов, например можно дебажить методом отправки сообщения ВК:

vkcoin.updates.startPolling(async(event) => {
    await vk.api.messages.send({ // Используется vk-io в качестве примера
        user_id: vkcoin.merchantId, // Тут ваш ID
        message: `Polling: ${event}`
    });

    console.log(event);
});

/* Тут ваши действия со слушателем */

Например: Вы запустили polling и потом зашли в VK Coin. Срабатывает автопереподключение к серверу:

> Подключено
> Вы зашли в VK Coin
> Соединение разорвано, переподключение совершится через 5 сек...
> Подключено

startWebHook - Запускает сервер на 8181 порте для получения событий. Может не работать на Windows и является неоптимальным способом получения событий. В этом случае можно обойтись без асинхронной функции:

vkcoin.updates.startWebHook(options);

/* Тут ваши действия со слушателем */

Опция	Тип	Описание
options	Object	Опции вебхука
options.url	String	Адрес вашего сервера для получения событий
options.port	Number	Порт для запуска сервера (8181 - по умолчанию)
options.path	String	Путь вашего хука (/ - по умолчанию)

При использовании startWebHook, вы лишаетесь многого: получение топов, места, онлайна и информации об объёме рынка. Всё это можно получить при использовании startPolling

getExpressMiddleware - Получает функцию цепи middleware для Express.

Перед использованием этого способа, нужно указать VKCOIN'у адрес для получения событий с указанием пути:

vkcoin.api.setCallback('http://my-address.ru/vkcoin');

Дальше уже можно использовать

const express = require('express');

const app = express();

/**
 * Это действие нужно обязательно
 * Нужно для получения тела запроса
 */
app.use(express.json());

// Дальше есть два варианта развития событий

// 1: Добавление функции в цепь middleware
app.use(
    vkcoin.updates.getExpressMiddleware('/vkcoin')
);

// 2: Или определить функцию на свой роут
app.post(
    '/vkcoin',
    vkcoin.updates.getExpressMiddleware()
);

// Выбирайте на свой вкус :)

/* Тут ваши действия со слушателем */

События

updates.onTransfer - Перехватывает входящие платежи, принимает один аргумент

vkcoin.updates.startPolling();

vkcoin.updates.onTransfer((event) => {
    console.log(event);
});

Или

vkcoin.updates.startWebHook({
    url: '123.123.123.123', // Тут ваша ссылка или IP-адрес сервера
    path: '/webhook',
    port: 1337
});

vkcoin.updates.onTransfer((event) => {
    console.log(event);
});

Или

async function run() {
    await vkcoin.api.setCallback('http://my-address.ru/vkcoin');

    app.use(
        vkcoin.updates.getExpressMiddleware('/vkcoin')
    )

    vkcoin.updates.onTransfer((event) => {
        console.log(event);
    });
}

event - Объект, который хранит в себе информацию о платеже:

Параметр	Тип	Описание
event.amount	Number	Количество коинов, которые послупили на счёт
event.fromId	Number	Айди плательщика
event.id	Number	Айди платежа

Стоит отметить, что startWebHook получает только платежи по ссылке.

Я опять же советую использовать startPolling

Методы и прочее

reconnectTimeout - Значение тайм-аута для переподключения

vkcoin.updates.reconnectTimeout = 10000; // Сменил на 10 скунд

По умолчанию это значение равно 5000 (5 секунд)

reconnect - Метод переподключения сервера для Longpoll. Использоуется в самой библиотеке для автопереподключения, но в своём коде его также можно использовать.

async function run() {
    await vkcoin.updates.startPolling(console.log);

    try {
        /* Тут код, который может выдать ошибку */
    } catch(error) {
        await vkcoin.updates.reconnect(); // Выполняю переподключение

        console.error(`Ошибка: ${error}`);
    }
}

run();

Стоит сказать, что при переподключении во время работы поллинга новое подключение будет перебивать первое и потом наоброт. Так будет идти бесконечно, пока вы не остановите код. Так что reconnect стоит использовать, если вы отключились от сервера, а лучше вообще не трогать :)

Полезная информация - Если вы подкючились через startLongpoll, то в качестве бонуса вы можете узнать много полезного:

Своё место в топе
Объём рынка
Сумма переводов за 5 минут
Онлайн в данный момент
Топ пользователей
Топ сообществ

const { updates } = vkcoin;

updates.startPolling(console.log).then(async() => {
    const { place, online, digits, userTop, groupTop } = updates;

    console.log({ place, online, digits, userTop, groupTop });
});

Теперь пройдусь по каждому параметру:

Параметр	Тип	Описание
place	Number	Ваше место в топе
online	Number	Онлайн пользователей в данный момент
digits	Object[]	Информация о рынке и сумме переводов
digits.description	String	Описание дигита
digits.value	Number	Значение дигита
digits.trend	Number	На сколько изменилось значение переводов за 5 минут
userTop	Object[]	Топ пользователей
userTop.id	Number	ID Пользователя
userTop.score	Number	Баланс
userTop.first_name	String	Имя
userTop.last_name	String	Фамилия
userTop.is_closed	Boolean	Закрыт ли аккаунт
userTop.can_access_closed	Boolean	Может ли текущий пользователь видеть профиль при is_closed = true
userTop.photo_200	String	Ссылка на аватарку
userTop.link	String	Ссылка на профиль
groupTop	Object[]	Топ сообществ. Подробнее: см. ниже
groupTop.id	Number	ID сообщества
groupTop.score	Number	Баланс
groupTop.name	String	Имя сообщества
groupTop.screen_name	String	Короткий адрес
groupTop.is_closed	Number	Закрыта ли группа
groupTop.type	String	Тип сообщества (паблик, страница, группа)
groupTop.photo_200	String	Аватарка сообщества
groupTop.link	String	Ссылка на сообщество

Так же скорее всего, все значения будут равны null, потому что клиент ws не успевает подключиться. Для решения этой проблемы могу посоветовать сделать delay функцию и интегрировать в метод:

const delay = (ms) => new Promise(res => setTimeout(res, ms));

const { updates } = vkcoin;

updates.startPolling(console.log).then(async() => {
    await delay(1000);

    const { place, online, digits, userTop, groupTop } = updates;
    console.log({ place, online, digits, userTop, groupTop });
});

Для тех, кто не понял. Так как подключение не успевает за получением значений, мы его задерживаем функцией delay на 1 секунду и тогда всё успевает получиться.

fakemancat/vkcoinapi