node-vkcoinapi
TypeScript icon, indicating that this package has built-in type declarations

1.8.0 • Public • Published

node-vkcoinapi

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

npm package

Version Downloads

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

  • Реализованы все методы официального 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 Ваш токен

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

Откройте свою аватарку и в адресной строке вы увидите подобное: 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 секунду и тогда всё успевает получиться.

Ссылки

Package Sidebar

Install

npm i node-vkcoinapi

Weekly Downloads

1

Version

1.8.0

License

ISC

Unpacked Size

54.4 kB

Total Files

20

Last publish

Collaborators

  • fakemancat