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.

• heelloController accounts:

  • heello.accounts.update

• heelloController categories:

  • heello.categories.get
  • heello.categories.primary
  • heello.categories.secondary
  • heello.categories.show

• heelloController checkins:

  • heello.checkins.create
  • heello.checkins.show

• heelloController pings:

  • heello.pings.create
  • heello.pings.destroy
  • heello.pings.echo
  • heello.pings.summary
  • heello.pings.search
  • heello.pings.show

• heelloController places:

  • heello.places.create
  • heello.places.search
  • heello.places.show

• heelloController timeline:

  • heello.timeline.public

• heelloController users:

  • heello.users.block
    • heello.users.blocking
    • heello.users.checkins
    • heello.users.listen
    • heello.users.listeners
    • heello.users.listening
    • heello.users.lookup
    • heello.users.me
    • heello.users.notifications
    • heello.users.pings
    • heello.users.show
    • heello.users.timeline
    • heello.users.unblock
    • heello.users.unlisten

<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.