Wondering what’s next for npm?Check out our public roadmap! »

    vk-api-calls

    1.1.4 • Public • Published

    vk-api-calls Build Status Coverage Status Dependency Status

    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

    Install

    npm i vk-api-calls

    DownloadsWeekly Downloads

    4

    Version

    1.1.4

    License

    MIT

    Last publish

    Collaborators

    • avatar