heello

node.js library for interaction with the social network Heello

npm install heello
30 downloads in the last week
60 downloads in the last month

node-heello

node.js library for interaction with the social network Heello.

license

MIT license

documentation

<Object> heelloAPI

- methods

  • heelloAPI.constructor(<Object> params)

    • <Object> params:
      • (required) <String> appId: heello API application id.
      • (required) <String> appSecret: heello API application secret.
      • (required) <String> callbackURI: callback URI, same one used when registering heello application.
      • <String> protocol: specify "https" or "http" for the protocol to to use for API contact. provided for testing purposes only
      • <String> domain: the domain to use for API contact. provided for testing purposes only.
      • <String> userAgent: the useragent to use when contacting the API.
      • <Array> fingerprints: an array of certificate fingerprints to identify the Heello API with.
      • <Boolean> pinCerts: should certificate pinning be enforced? this will discard responses and throw errors when non-SSL responses or non-whitelisted fingerprints are provided from the server.
  • heelloAPI.prototype.getAuthURI(<String> state)

    • Synchronous
    • Obtain the URI to redirect a user to in order to obtain authorization details from the heello API
    • <String> state: optional session-identifying string. reference heello oauth2 authorization documentation for more information
    • return: <String> URI to redirect user to for authentication with heello.
  • heelloAPI.prototype.getTokens(<String> code, <Callable> callback)

    • Obtain refresh, access tokens using authorization_code returned by heello
    • <String> code: authorization_code obtained from heello API authentication
    • <Callable> callback: callback to invoke once token obtainment is complete
  • heelloAPI.prototype.refreshTokens(<String> refreshToken, <Callable> callback)

    • Obtain new refresh, access tokens using previously obtained refresh_token (only necessary if access_token is now invalid)
    • <String> refreshToken: previously obtained refresh_token
    • <Callable> callback: callback to invoke once token obtainment is complete

- properties

  • heelloAPI.rateLimitRemaining
    • <integer>: contains the number of API hits we have left before the API limit reset since the last API call. Value is -1 until first API call.
  • heelloAPI.rateLimitMax
    • <integer>: contains the number of API hits allowed in total before the API limit reset. Value is -1 until first API call.
  • heelloAPI.rateLimitReset
    • <Date>: Date object representing when the API limit will be reset. Value is null until first API call.
  • heelloAPI.accessToken
    • <String>: access token currently in use
  • heelloAPI.refreshToken
    • <String>: latest obtained refresh token

- magic properties

All magic properties are instances of heelloController.

  • accounts
  • categories
  • checkins
  • pings
  • places
  • timeline
  • users

<Object> heelloController

Each heelloController is automagically instantiated based on lib/schema.json. For full specification, please check with the schema.json file.

- magic properties

All magic properties return an executable callback created by heelloAction. Reference heelloAction documentation for information on how to interact with heelloAction instances.

<Object> heelloAction

Instances of heelloAction are special; instead of receiving the instance yourself, you'll receive its product, a callable, to feed your parameters into for your API call.

You'll call a heelloAction like so:

heello.controller.action(<Object> params, <Callable> callback)

Callbacks supplied to the heelloAction can take up to three parameters:

  • <Error> err: null if no error, or Error if an error occurred during API call.
  • <Object> json: JSON-parsed response from the API if provided, or null
  • <Object> res: response object from npm module superagent. inherits from node builtin http.ClientResponse.

A full example of a heelloAction call, assuming heello is your heelloAPI instance, is as follows:

heello.pings.show({ id: 8188091 }, function(err, json, res) {
    if(err) throw err
    json.response // contains API response information
})

With this call, we're looking up details for a heello ping with the ID of 8188091.


use example

var heelloAPI = require('heello'),
    heello = new heelloAPI({
        appId: 'heello appId here',
        appSecret: 'heello appSecret here',
        callbackURI: 'http://callback.tld/',
    })

// @note; authentication needs to happen here - obtain your tokens as per heello docs

// get a user's latest pings
// (no auth)
heello.users.pings({ id: 1234567, count: 5 }, function(err, json, res) {
    if(err) throw err
    json.response.forEach(function(ping) {
        console.log('@%s: %s [%d]', ping.user.username, ping.text, ping.id)
    })
})

// echo a ping
// (needs auth)
heello.pings.echo({ id: 1234567 }, function(err) {
    // @param <Error|null>err: null if no error, or Error if an error.
    if(err) throw err
})

warning

Under active development. Heello-interaction API mostly firm.

Initial obtainment of authorization_code is up to $developer unfortunately; no solid methodology is present for obtaining an authorization_code with minimal user interaction.

If you need a refresh token for your application, however, please reference package heello-refreshtoken for a method of obtaining a refresh token fairly easily for testing.

todo

  • file upload support (media uploads!)

tests

Install mocha with npm install -g mocha.

Now, create a test.config.json file - an example of the file is as follows:

{
    "appId":"appid",
    "appSecret":"appsecret",
    "callbackURI":"http://127.0.0.1:9009/",
}

Next, execute node node_modules/heello-refreshtoken/bin/gettoken -o ./test.refreshtoken.json and enter in your appId, appSecret, callback URI, heello username, and heello password when prompted. Give it a moment to obtain the refresh token, then proceed with testing using mocha.

When creating a test application on Heello, use the redirect URI http://127.0.0.1:9009/ as well to allow tests to run correctly. The testing methodology is unforgiving, unfortunately, and must work within Heello's current API rules.


Community contributions welcome.

npm loves you