npm install vk-api-callsvk-api-calls   
============
> Yet another VK API wrapper for Node.js & io.js.
* (Kind of) easy authentication
* Multiple API calls at once via execute
* Collecting paged data
* Automatic request rate debouncing
* Callbacks/Promises agnostic
``sh`
npm install --save vk-api-calls
#### 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 666
Default:
Delay for API calls debouncing in milliseconds. Has to be at least 333 because of API restrictions.
###### timeout
Type: number 30000
Default:
Milliseconds untill ETIMEDOUT error is thrown if there's no response from the server.
###### headers
Type: object {'user-agent': 'https://github.com/dsblv/vk-api-calls'}
Default:
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:
`js`
{
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
---
#### vk.setSession(data) → this
Saves session data.
##### data
Required
Type: object
Data returned by VK API server:
`js`
{
'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.
---
#### 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.
---
#### 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:
`js
// 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()
---
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:
`js
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);
});
`
---
#### 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`
MIT © Dmitriy Sobolev