vk-api-calls

vk-api-calls

Yet another VK API wrapper for Node.js & io.js.

Features

• (Kind of) easy authentication
• Multiple API calls at once via execute
• Collecting paged data
• Automatic request rate debouncing
• Callbacks/Promises agnostic

Install

npm install --save vk-api-calls

API

Constructor

var vk = new VK([app], [options], [session])

app

Type: object

Info about your app for future authentication.

clientId

Type: number or string

Your app's ID.

clientSecret

Type: string

Your app's Secure Key.

redirectUri

Type: string

Redirect URI as specified in your app's options.

scope

Type: string, array or number

List of desirable scopes for your app or calculated bit mask.

v

Type: string or number

Version of VK API you want to work with.

options

Type: object

Custom vk-api-calls settings.

interval

Type: number
Default: 666

Delay for API calls debouncing in milliseconds. Has to be at least 333 because of API restrictions.

timeout

Type: number
Default: 30000

Milliseconds untill ETIMEDOUT error is thrown if there's no response from the server.

headers

Type: object
Default: {'user-agent': 'https://github.com/dsblv/vk-api-calls'}

Headers to be sent with each request. user-agent contains a link to this repo by default. Provide some information about your app here so VK server administration will beter know what's going on.

session

Type: object

Session data: user id, access token and when it expires:

{
	userId: 'USER_ID',
	token: 'ACCESS_TOKEN',
	expires: 1440163431337
}

This will help you not to perform authentication each time user visits your page. Save this in your session storage and use until it's expired. If expires is set to 0, token is assumed to be eternal.

Note that expires value is not relative, but absolute

---

Session methods

vk.setSession(data) → this

Saves session data.

data

Required
Type: object

Data returned by VK API server:

{
	'user_id': 'USER_ID',
	'access_token': 'ACCESS_TOKEN',
	'expires_in': 3600
}

Note that this time expires_in is relative. The module will internally convert in to absolute value.

vk.getSession() → object

Returns session data prepared for storing in session storage.

vk.getToken() → string

Returns current access token or undefined if it's expired or not set.

vk.hasValidToken() → boolean

Tells if valid token is avalible.

---

Authentication methods

vk.renderAuthUrl([query]) → string

Retutns URL to direct user to for authentication.

query

Type: object

Query parameters you may want to manually override.

vk.performSiteAuth(query, [callback]) → promise/this

Alias: vk.siteAuth()

Performs Authorization Code Flow auth.

query

Required
Type: object

Query has only one required parameter — code — which is returned by VK API server when user is successfully logged in.

callback(error, data, response)

Type: function

If callback is supplied, it will be called when server responds. Otherwise, the method returns a Promise.

vk.performServerAuth([query], [callback]) → promise/this

Alias: vk.serverAuth()

Performs Client Credentials Flow auth.

query

Type: object

Query parameters you may want to manually override.

callback(error, data, response)

Type: function

If callback is supplied, it will be called when server responds. Otherwise, the method returns a Promise.

---

Request methods

vk.performApiCall(method, [query], [callback]) → promise/this

Alias: vk.apiCall()

Performs API requests.

method

Required
Type: string

One of VK API methods.

query

Type: object

Query parameters you want to pass to VK API method. Required authentication data will be attached automatically.

callback(error, data, response)

Type: function

If callback is supplied, it will be called when server responds. Otherwise, the method returns a Promise.

vk.collectStream(method, [query]) → readable stream

This metod allows you to get more data than VK restrictions allow by sending multiple requests. Every API response will emit data event with received data so you can operatively store it.

Stream emits data, error and end events.

API request rate is limited to match VK API requirements.

method

Required
Type: string

One of VK API methods.

query

Type: object

Query parameters you want to pass to VK API method. Required authentication data will be attached automatically.

Example:

// your save-to-database module
var save = require('./save');

// let's get 10000 members of a group
// when maximum per request is 1000

var stream = vk.collectStream('groups.getMembers', {
	group_id: 1,
	count: 10000
});

stream.on('data', function (data) {
	save(data.items);
});

stream.on('error', function (error) {
	console.error('wild error appears');
});

vk.collect(method, [query], [callback]) → promise/this

Wrapper around #collectStream() that collects the whole stream.

Arguments are same as in #peformApiCall()

---

Deferred execution

vk-api-calls provides a way to collect several API calls and run them all at once via execute method. This approach can speed up your application, as yo're able to retreive all data you need by one shot.

vk.execution() → execution

This method return an Execution object instance.

execution.push(method, [query]) → this

Add an API call to the set.

Arguments are same as in #peformApiCall() except callback — no callbacks needed here.

execution.code() → string

Generates code for execution by VK at any point of time.

execution.execute([callback]) → promise/vk-api-calls instance

Runs the execution via #peformApiCall() with 'execute' as first argument.

Example:

var exec = vk.execution();

exec
.push('users.get', {user_ids: 1})
.push('wall.get', {owner_id: 1})
.push('photos.get', {owner_id: 1})
.execute()
.then(function (data) {
	console.log('Name: ' + data[0].response.first_name);
	console.log('Wall posts: ' + data[1].response.count);
	console.log('Photos posts: ' + data[2].response.count);
});

---

Utility methods

vk.hasInScope(method) → boolean

Tells if application scope allows you to call particular method. vk-api-calls performs this check internally before every call, so you don't need to do it yourself.

method

Required
Type: string

License

MIT © Dmitriy Sobolev