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.
-
(required)
-
-
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-1until first API call.
-
- heelloAPI.rateLimitMax
-
<integer>: contains the number of API hits allowed in total before the API limit reset. Value is-1until 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:
-
heelloController categories:
-
heelloController checkins:
-
heelloController pings:
-
heelloController places:
-
heelloController timeline:
-
heelloController users:
<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.
