vk-call

Simple API wrapper for VK.com social network. Inspired by node-vk-sdk.

Installation

npm install vk-call

Usage

VK object

var vk = require('vk-call').vk;

constructor(config: Object)

config options:

token — OAuth token for authorized requests
timeout — request timeout in milliseconds
version — API version
api_url — base url for api calls

vk.call(method: String, params: Object) : Promise

Single api call, returns promise.

method — method name, i.e. 'users.get'
params — method parameters, i.e. { id: 1 }

Example:

var vk = require('vk-call').vk;

var api = new vk({
  token: "YOUR TOKEN HERE",
  version: "5.50",
  timeout: 10000
});

api.call("users.get", { user_ids: 1 })
  .then(users => console.log(users));

vk.chain() : Chain

Intitializes and returns Chain object

Chain object

This object is responsible for chaining api calls and batching them with the help of execute method. It allows you to legally get around some of request rate limits. However, remember that you can't chain more than 25 api calls.

It's better to create Chain object via vk.chain method.

constructor(api: vk)

api — initialized instance of vk

append(method: String, params: Object) : Promise

This method is very similar to vk.call, but used for chaining. Returned promise will be resolved after successfull execute call. Promise will return value as if it is a single api call. It means, that only data returned single for this request will be supplied.

You can't call Chain.append after you called Chain.done, you have to create new Chain.

done() : Promise

You must call this method, when you appended enough requests.

This method will return an array of results for chained methods in the same order in which you appended calls.

Empty chain will return Promise([]).

Exmaple:

var vk = require('vk-call');

var api = new vk({
  token: "YOUR TOKEN",
  version: "5.50"
});

var chain = api.chain();

chain.append("users.get", { user_ids: 1 })
  .then((users) => console.log(users));
  
chain.append("groups.getById", { group_ids: 1 })
  .then(groups => console.log(groups));
  
chain.done()
  .then((result) => {
    var users = result[0];
    var groups = result[1];
    console.log(users, groups);
  });
  
chain.append("users.get", { user_ids: 2 });

// Throws error, because chain ended after done

Errors

All errors are wrapped with VKError object wich you can request as:

var VKError = require('vk-call').errors.VKError;

There are two type of errors:

domain errors — all errors, that returned by VK API
failures (not domain errors) — all other errors (timeouts, no internet, code issues etc.)

Most of error codes that can be returned by VK API are represented by constants:

var errors = require('vk-call').errors;
assert(errors.NOT_DOMAIN_ERROR === -1);
assert(errors.UKNOWN_ERROR === 1);
assert(errors.UNKNOWN_METHOD === 3);

This codes are stored in type property of VKError instance. You can find the whole list of constants here.

There is also name property, it can have two values:

var errors = require('vk-call').errors;
errors.NOT_DOMAIN_NAME
errors.DOMAIN_NAME

This property is handy for distinguishing API errors from any other failures.

Also there is an originalError property were you can get the original error (json or Error object).

Tests

This library is mostly covered with tests. To run test, use npm test command. For developing, use npm test-watch command.

We use mocha for testing. All test files are stored in test/**/*.

License

Distributed under MIT LICENSE

VasyaITOne/node-vk-call