VK-IO
Включает в себя авторизацию, загрузку файлов, longpoll, stream и утилиты
Мощный инструмент для работы с VK API.
Инициализация / Начало работы
Установка модуля
npm install vk-io --save
Инициализация одного экземпляра
'use strict'; const vk = new ;
В конструктор так можно сразу передать настройки
const VK = ; const group = token: 'token-group';const user = id: 1 token: 'token-user';
Конфигурация модуля
Сниппет простой установки токена
vk;
Настройки которые можно передать в объект
vk;
Описание возможных параметров настроек
id
Тип: number
Идентификатор пользователя ВКонтакте (временно не используется)
app
Тип: number
или string
Идентификатор приложения standalone
key
Тип: string
Секретный ключ приложения
pass
Тип: string
Пароль пользователя
login
Тип: string
Логин пользователя, может содержать email
или номер телефона
phone
Тип: string
или number
Номер телефона, необходим для валидации авторизации если запросится телефон
Пример записи: 79241111111
, в начале так же может присутствовать +
Может использоваться вместо login
debug
Тип: boolean
По умолчанию: true
Позволяет логировать действия модуля
proxy
Тип: string
По умолчанию: null
Прокси, формат записи http://example.com/
restartError
Тип: number
По умолчанию: true
Перезапускать метод при ошибках соединения
restartCount
Тип: boolean
По умолчанию: 3
Количество попыток перезапуска
timeout
Тип: number
По умолчанию: 6
Время ожидания для сброса соединения в секундах
limit
Тип: number
По умолчанию: 3
Лимит запросов в секунду
Авторизация через standalone
Для авторизации standalone
нужно установить app
, pass
, login
или phone
Пример авторизации, по умолчанию scope содержит все разрешения
Авторизация не заменяет токен в настройках модуля, учтите это
vk; const auth = vk; auth;
Список разрешений можно установить двумя способами
vk; /* Или */ auth;
Также есть возможность установить свой CookieJar
auth
Из объектов auth можно извлечь дополнительные данные
auth; // -> CookieJar - Хранилище cookieauth; // -> array - Список разрешений
Серверная авторизация
Токен получается для использования в серверных метода, пример
const server = new ; server; server;
Авторизация через официальные приложения
Для авторизации необходимо установить только pass
, login
или phone
Получение объекта Auth официальных приложений
Android
const auth = vk;
Windows
const auth = vk;
Windows Phone
const auth = vk;
iPhone
const auth = vk;
iPad
const auth = vk;
Пример дальнейших действий
auth;
Выполнение методов VK API
Необходимо скопировать название из списка методов
На примере получение записей со стены через wall.get
,
vkapiwall;
Работа с установленными процедурами приложения
vk; // -> promise
Если необходимо вызвать много одних и тех же методов рекомендуется использовать .chain()
или .executes()
Для множественного вызова одного метода с разными параметрами есть снипет работающий на.chain()
vk; /* Пример */vk;
Цепочки методов
Цепочки методов помогают получить много данных с разных методов или просто вызвать их
Можно передать неограниченное количество методов в цепочку
Цепочка будет делится по 25 методов в один execute и возвращать результат
Учтите если был вызван .execute()
и вызвать .append()
выбросится синхронное исключение
Пример работы с простой цепочкой
const chain = vk; chain; chain; chain;
Данные можно получить двумя способами, первый способ просто поставить .then()
на возвращаемый promise
chain
Или же можно получить данные со всех результатов, они будут возвращены в порядке в котором вызваны
chain;
Если цепочка методов будет пуста, в результат вернётся пустой массив
vk
Присутствует простой сниппет для быстрого получение promise
без обращения к .execute()
Простое сокращение .execute().then(fn)
или .execute().catch(fn)
chain; /* Или же */ chain;
Работа с потоками
Потоки только для методов в которых есть параметр offset
Позволяет получить все данные или только указанное кол-во в count
Например получить все записи со стены пользователя
vkstreamwall;
Загрузка файлов
file
Тип: Stream
, string
или array
в некоторых случаях
Обязательный параметр для загрузки
В array
может содержать только Stream
или string
В string
может быть путь к файлу или url на файл
В метод так же можно передавать парметры которые должны быть после загрузки для сохранения
timeout
Тип: number
По умолчанию: 15
Необязательный параметр, время ожидания для сброса соединения в секундах
Методы для загрузки с описанием
album
Загрузка фотографий в альбом
Обязательный параметр album_id
В file
может быть передан массив, не более 5 файлов
wall
Загрузка изображения на стену
owner
Загрузка фотографии на главную профиля или сообщества
Дополнительный параметр crop
указываете x,y,w
квадратной миниатюры, подробнее
message
Загрузка изображения в личное сообщение
chat
Загрузка фотографии для чата
Дополнительный параметр crop
указываете объект квадратной миниатюры
width
- Ширина фотографии после обрезки в px.
x
- Координата x для обрезки фотографии (верхний правый угол)
y
- Координата y для обрезки фотографии (верхний правый угол).
product
Загрузка фотографии для товара
Дополнительный параметр crop
указываете объект квадратной миниатюры
width
- Ширина фотографии после обрезки в px.
x
- Координата x для обрезки фотографии (верхний правый угол)
y
- Координата y для обрезки фотографии (верхний правый угол).
selection
Загрузка фотографии для подборки товаров
audio
Загрузка аудиозаписей
video
Загрузка видеозаписи
doc
Загрузка документа
graffiti
Загрузка граффити, доступные расширения png
,svg
Наследует doc
voice
Загрузка аудиосообщения, доступные расширения mp3
,ogg
Наследует doc
Пример загрузки файлов в doc
Загрузка в документы
/* Request */vkupload; /* URL */vkupload; /* Stream */vkupload; /* Путь к файлу */vkupload;
Работа с longpoll
Открытие соединения
vk;
Закрытие соединения
vk;
Подпись на события происходит через EventEmitter
Пример прослушивания новых сообщений
vk;
Список событий longpoll
События действий чата, наследуют message
chat.create
Был создан чат
title
- название чата
chat.rename
Чат был переименован
title
- новое название чата
rename(title)
- метод для переименование чата, в качестве аргумента новое название чата
message;
chat.invite
В чат был добавлен новый участник или вернулся который вышел
invite
- идентификатор пользователя которого пригласили
kick()
- метод для исключения пользователя,
Работает если пользователь пригласил или пользователь администратор чата
Необязательный параметр позволяет указать идентификатор другого пользователя
message; // -> promise message;
chat.kick
В чате исключили пользователя или он вышел
kick
- идентификатор пользователя которого исключили
invite()
- метод для приглашения пользователя,
Работает если только пользователя исключили
Необязательный параметр позволяет указать идентификатор другого пользователя
message // -> promise message;
chat.photo.update
В чате обновили изображение
photo
- информация о изображение
remove()
- метод для удаления изображения чата
message // -> promise
chat.photo.remove
В чате удалили изображение
Основные события
message
Пришло новое сообщение
Не игнорирует сообщение или события отправленные самим пользователем
id
- идентификатор сообщения
date
- когда пришло сообщение в timestamp
peer
- peer_id, отрицательное для сообщества
user
- пользователь отправивший сообщение, для сообщества null
chat
- идентификатор чата
text
- текст сообщения в случае отсутствия null
flags
- флаги сообщения, подробнее
hasEmoji
- присутствуют ли emoji в тексте
title
- название чата, по умолчанию null
send()
- метод отправки сообщения в текущий диалог (обёртка для messages.send), примеры
message; message; message;
hasFlag()
- проверяет на наличие флага сообщения, пример
if message console; else console;
hasAttachments()
- проверяет наличие любых прикриплений
hasAttachment(name)
- проверяет наличие указанного прикрипления
hasFwd()
- проверяет наличие пересылаемых сообщений
getFwd()
- возвращает пересылаемые сообщений
message;
isDialog()
- сообщение написано в личку
isChat()
- сообщение написано в чате
isGroup()
- сообщения написано в сообществе
attachments
- прикрипления, подробнее ниже
======
geo
- карта, содержит:
id
- идентификатор картыprovider
- идентификатор сервиса карты
photo
- содержит массив с прикриплениями изображений
video
- содержит массив с прикриплениями видео
audio
- содержит массив с прикриплениями аудиозаписями
doc
- содержит массив с прикриплениями документов
type
- тип прикрипления (graffiti,audiomsg)
wall
- содержит массив с прикриплениями постов
link
- содержит массив с прикриплениями ссылок
url
- URL ссылкиtitle
- название ссылкиdescription
- описание ссылкиphoto
- объект{id: 1234, owner: 5678}
или null
sticker
- стикер
id
- идентификатор стикераproduct
- идентификатор набора
gift
- подарок
id
- идентификатор подарка
message.flags.set
Установка флагов сообщения
id
- идентификатор сообщения
flags
- список флагов
message.flags.remove
Сброс флагов сообщения
id
- идентификатор сообщения
flags
- список флагов
message.read.inbox
Прочтение всех входящих сообщений
peer
- идентификатор начала непрочитанных сообщений
local
- идентификатор остановки чтения
message.read.outbox
Прочтение всех исходящих сообщений
peer
- идентификатор начала непрочитанных сообщений
local
- идентификатор остановки чтения
user.online
Друг стал онлайн
user
- идентификатор пользователя
platform
- платформа с которой пользователь стал онлайн, список платформ ниже
standalone
- веб сайт или другое standalone приложениеmobile
- мобильная версия ВКонтактеipad
- офицальное приложение iPadiphone
- офицальное приложение iPhoneandroid
- офицальное приложение Androidwindows
- офицальное приложение Windowswphone
- офицальное приложение Windows Phone
user.offline
Друг стал оффлайн
user
- идентификатор пользователя
exit
- вышел ли пользователь используя кнопку выхода или таймаут
group.flags.remove
Удаления флагов для сообщения сообщества
peer
- идентификатор чата/собеседника
flags
- флаги сообщения
group.flags.set
Установка флагов для сообщения сообщества
peer
- идентификатор чата/собеседника
flags
- флаги сообщения
chat.action
Один из параметров беседы был изменён
chat
- идентификатор чата
self
- вызваны ли изменения самим пользователем
typing.user
Пользователь начал набирать текст в диалоге
user
- идентификатор пользователя
typing.chat
Пользователь начал набирать текст в чате
user
- идентификатор пользователя
chat
- идентификатор чата
unread.count
Новый счетчик непрочитанных в левом меню меню
count
- счётчик непрочитанных диалогов
notify.set
Изменились настройки оповещений
peer
- идентификатор чата/диалога
sound
- включены или выключены звуковые оповещения
until
- выключение оповещений на необходимый срок, (-1: навсегда, 0: включены, other: timestamp, когда нужно включить)
Обработка исключений
Captcha / Капча
Установка обработчика капчи, возвращает функция для повтора запроса.
1 аргумент
- ссылка на капчу
2 аргумент
- обработчик для повторной отправки с полученой капчей
3 аргумент
- идентификатор капчи
Пример обработки капчи
vk;
Исключения в методах VK API
Бывает ввели неверный параметр или сервер дал ошибку, например выдаст ошибку ApiError и как её обработать
vkapimessages;
Так же возможна проблема при отправке или получение овтета
vkapimessages;
Есть возможность проверить является ли ошибка класса VkIo
vk; // -> boolean
А благодаря bluebird promise можно организовать нужные обработчики
vkapimessages;
Исключения в авторизации
Проверить является ли ошибка класса авторизации
vk; // -> boolean
А так же catch
auth;
Логгер
В модуле присутствует простой логер, для его замены нужно
Логгер должен поддерживать методы
log
- Стандартный логerror
- Сообщения об ошибкахwarn
- Предупреждения модуляinfo
- Информация модуляdebug
- Данные для дебага
vk;
Сниппеты
Парсинг ссылок вк
Принимает один параметр string
или number
Возможные значения type
user
- Пользовательgroup
- Группаapplication
- Приложение
С остальными типами присутствует свойство peer
photo
- Фотографияvideo
- Видеоdoc
- Документalbum
- Альбомtopic
- Топикwall
- Стенаpage
- Страница
vk;
Получение ссылок на фотографию объекта photo
Есть 3 метода для получение ссылки с объекта photo
Если метод не находит ссылку на фотографию он будет искать более меньшего размера пока не найдёт существующие разрешение
getLargePhoto
- Возвращает фотографии разрешения 2560
или 1280
getMediumPhoto
- Возвращает фотографии разрешения 807
или 604
getSmallPhoto
- Возвращает фотографии разрешения 130
или 75
Пример работы с методами
vkapiphotos;
Получение прикриплений с объектов
Список доступных объектов objects медиаконтент
Метод getAttachment
1 аргумент
- Тип нужно прикрипления
Тип: string
2 аргумент
- Объекты или массив объектов
Тип: string
или array
Пример работы с методом
vkupload
Геттеры
Получение кол-во заданий в очереди
vk; // -> integer
Получение токена
vk; // -> null или string
Константы
Текущая версия API
vkAPI_VERSION;
События
Отсутствуют
Утилиты
Проверяет наличие метода
vk; // -> boolean
TODO
Если вам есть что предложить прошу написать мне VK или сделать pull request