heello v1.0.10
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 informationreturn
:<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 completeheelloAPI.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*](https://developer.heello.com/docs/1/PUT/accounts/update)
heelloController categories: [heello.categories.get](https://developer.heello.com/docs/1/GET/categories/get) heello.categories.primary [heello.categories.secondary](https://developer.heello.com/docs/1/GET/categories/secondary) heello.categories.show
heelloController checkins: [heello.checkins.create](https://developer.heello.com/docs/1/POST/checkins/checkin) heello.checkins.show
heelloController pings: [heello.pings.create](https://developer.heello.com/docs/1/POST/pings/create) heello.pings.destroy [heello.pings.echo](https://developer.heello.com/docs/1/POST/pings/echo) heello.pings.summary [heello.pings.search](https://developer.heello.com/docs/1/GET/pings/search) heello.pings.show
heelloController places: [heello.places.create](https://developer.heello.com/docs/1/POST/places/create) heello.places.search [heello.places.show*](https://developer.heello.com/docs/1/GET/places/show)
heelloController timeline: [heello.timeline.public*](https://developer.heello.com/docs/1/GET/timeline/public)
heelloController users:
- heello.users.block [heello.users.blocking](https://developer.heello.com/docs/1/GET/users/blocking) heello.users.checkins [heello.users.listen](https://developer.heello.com/docs/1/POST/users/listen) heello.users.listeners [heello.users.listening](https://developer.heello.com/docs/1/GET/users/listening) heello.users.lookup [heello.users.me](https://developer.heello.com/docs/1/GET/users/me) heello.users.notifications [heello.users.pings](https://developer.heello.com/docs/1/GET/users/pings) heello.users.show [heello.users.timeline](https://developer.heello.com/docs/1/GET/users/timeline) heello.users.unblock [heello.users.unlisten*](https://developer.heello.com/docs/1/DELETE/users/listen)
<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.