Note

This is an incomplete conversion of https://github.com/duerig/appnet.js. Places, and App stream references are not valid (not implemented by the Pnut.io API yet).

pnut.js

A library for interacting with pnut.io written in JavaScript. Exported as both a jQuery and a Node.js module.

In jQuery, every method is invoked from the object found at $.pnut. Using Node.js, that object is the sole export. See the examples below.

Most function map one-to-one onto the HTTP endpoints of the pnut.io API. The exceptions are a few utility functions at the top level for setting and checking authorization tokens, and the all.* functions which are a convenient way to get an entire stream.

Download

When using this package with jQuery, the latest development version can be obtained at:

• Full Source

JQuery Example

$.pnut.authorize("MY_USER_TOKEN");
var promise = $.pnut.post.getGlobal({ include_raw: 1 });
promise.then(function (response) {
// On success, response is the json object returned by the pnut.io server.
// See: http://developers.pnut.io/docs/basics/responses/#response-envelope
console.dir(response.data);
console.dir(response.meta);
return $.pnut.post.getThread('1000', { count: 10 });
}).then(function (response) {
console.dir(response);
}, function (response) {
// On failure, response is the jQuery response object.
// See: http://api.jquery.com/Types/#jqXHR
console.log('Error!');
});

Node.js Example

var pnut = require('pnut');
pnut.authorize("MY_USER_TOKEN");
var promise = pnut.post.getGlobal({ include_raw: 1 });
promise.then(function (response) {
// On success, response is the json object returned by the pnut.io server.
// ~~See: http://pnut.io/docs/basics/responses/#response-envelope~~
console.dir(response.data);
console.dir(response.meta);
return pnut.post.getThread('1000', { count: 10 });
}).then(function (response) {
console.dir(response);
}, function (response) {
// On failure, response is the q-io response object.
// See: https://github.com/kriskowal/q-io#response
console.dir(response.status);
console.log('Error!');
});

Reference

Utility Functions

Method	Parameters	Description
authorize	( userToken, appToken )	Sets the user and/or app tokens. Required for various calls as noted below.
deauthorize	( )	Clears all tokens.
isLogged	( )	Returns true if either a user or an app token has been previously provided.
isApp	( )	Return true if an app token was previously provided.
isUser	( )	Returns true if a user token was previously provided.

'all' endpoints

$.pnut.all provides some convenience functions for fetching the contents of an entire stream, automatically using pagination parameters to make multiple calls to the API when necessary.

Caution These functions will keep calling and not callback until the entire stream is fetched. If the stream is big, this can be a long wait. Only use these when you are confident that the stream can be fetched with a few calls.

These functions all return a mock response envelope with a 'data' field containing an array of the entire set of objects fetched. If they fail part of the way through, your rejection method will be called with the failed response object.

Method	Parameters	Method Used
getSubscriptions	( args )	channel.getUserSubscribed
getMessages	( channel_id, args )	message.getChannel
getUserPosts	( user_id, args )	post.getUser
getFollowing	( user_id, args )	user.getFollowing
getChannelList	( channel_ids, args )	channel.getList
getUserList	( user_ids, args )	user.getList

pnut.io endpoints

These endpoints all return the result of invoking $.ajax() which is a jQuery promise. You are then free to attach your own callbacks to it etc. Typically the response you receive will be a response envelope with a 'data' field containing the results of your operation on success and a 'meta' field with the response code and any other information associated with your query.

Method	Parameters	Description	Token
user.get	( user_id, args )	Retrieve a User	None
user.update	( user, args )	Update a User	User
user.partialUpdate	( user, args )	Partially Update a User	User
user.getAvatar	( user_id, args )	Retrieve a User's avatar image	None
user.updateAvatar	( avatar, args )	Update a User's avatar image	User
user.getCover	( user_id, args )	Retrieve a User's cover image	None
user.updateCover	( cover, args )	Update a User's cover image	User
user.follow	( user_id, args )	Follow a User	User
user.unfollow	( user_id, args )	Unfollow a User	User
user.mute	( user_id, args )	Mute a User	User
user.unmute	( user_id, args )	Unmute a User	User
user.block	( user_id, args )	Block a User	User
user.unblock	( user_id, args )	Unblock a User	User
user.getList	( user_ids, args )	Retrieve multiple Users	Any
user.search	( args )	Search for Users	Any
user.getFollowing	( user_id, args )	Retrieve Users a User is following	Any
user.getFollowers	( user_id, args )	Retrieve Users following a User	Any
user.getFollowingIds	( user_id, args )	Retrieve IDs of Users a User is following	Any
user.getFollowerIds	( user_id, args )	Retrieve IDs of Users following a User	Any
user.getMuted	( user_id, args )	Retrieve muted Users	Any
user.getMutedList	( user_ids, args )	Retrieve muted User IDs for multiple Users	App
user.getBlocked	( user_id, args )	Retrieve blocked Users	Any
user.getBlockedList	( user_ids, args )	Retrieve blocked User IDs for multiple Users	App
user.getReposters	( post_id, args )	Retrieve Users who reposted a Post	Any
user.getStars	( post_id, args )	Retrieve Users who starred a Post	Any
post.create	( post, args )	Create a Post	User
post.get	( post_id, args )	Retrieve a Post	None
post.destroy	( post_id, args )	Delete a Post	User
post.repost	( post_id, args )	Repost a Post	User
post.unrepost	( post_id, args )	Unrepost a Post	User
post.bookmark	( post_id, args )	Star a Post	User
post.unbookmark	( post_id, args )	Unstar a Post	User
post.getList	( post_ids, args )	Retrieve multiple Posts	Any
post.getUser	( user_id, args )	Retrieve a User's posts	None
post.getUserBookmarked	( user_id, args )	Retrieve a User's starred posts	None
post.getUserMentions	( user_id, args )	Retrieve Posts mentioning a User	Any
post.getHashtag	( hashtag, args )	Retrieve Posts containing a hashtag	None
post.getThread	( post_id, args )	Retrieve replies to a Post	Any
post.getUserStream	( args )	Retrieve a User's personalized stream	User
post.getUnifiedStream	( args )	Retrieve a User's unified stream	User
post.getGlobal	( args )	Retrieve the Global stream	User
post.report	( post_id, args )	Report a Post	User
post.search	( args )	Search for Posts	Any
channel.getUserSubscribed	( args )	Get current user's subscribed channels	User
channel.create	( channel, args )	Create a Channel	User
channel.get	( channel_id, args )	Retrieve a Channel	Varies
channel.getList	( channel_ids, args )	Retrieve multiple Channels	Varies
channel.getCreated	( args )	Retrieve my Channels	User
channel.getUnreadCount	( args )	Retrieve number of unread PM Channels	User
channel.getUnreadBroadcastCount	( args )	Retrieve number of unread Broadcast Channels	User
channel.markBroadcastChannelsRead	( args )	Mark all Broadcast Channels as read	User
channel.update	( channel_id, channel, args )	Update a Channel	User
channel.deactivate	( channel_id, channel, args )	Deactivate a Channel	User
channel.subscribe	( channel_id, args )	Subscribe to a Channel	User
channel.unsubscribe	( channel_id, args )	Unsubscribe from a Channel	User
channel.getSubscribers	( channel_id, args )	Retrieve users subscribed to a Channel	None
channel.getSubscriberIds	( channel_id, args )	Retrieve user ids subscribed to a Channel	None
channel.getSubscriberIdList	( channel_ids, args )	Retrieve user ids subscribed to multiple Channels	Any
channel.mute	( channel_id, args )	Mute a Channel	User
channel.unmute	( channel_id, args )	Unmute a Channel	User
channel.getMuted	( args )	Get current user's muted Channels	User
channel.search	( args )	Search for Channels	User
message.getChannel	( channel_id, args )	Retrieve the Messages in a Channel	None
message.create	( channel_id, message, args )	Create a Message	User
message.get	( channel_id, message_id, args )	Retrieve a Message	None
message.getList	( message_ids, args )	Retrieve multiple Messages	None
message.getUser	( args )	Retrieve my Messages	User
message.destroy	( channel_id, message_id, args )	Delete a Message	User
file.create	( file, args )	Create a File	User
file.createPlaceholder	( file, args )	Create a File Placeholder	User
file.get	( file_id, args )	Retrieve a File	User
file.getList	( file_ids, args )	Retrieve multiple Files	User
file.destroy	( file_id, args )	Delete a File	User
file.getUser	( args )	Retrieve my Files	User
file.update	( file_id, file, args )	Update a File	User
file.getContent	( file_id, args )	Get File content	User
file.setContent	( file_id, content, args )	Set File content	User
AppStream.create	( stream, args )	Create a Stream	App
AppStream.get	( stream_id, args )	Retrieve a Stream	App
AppStream.update	( stream_id, stream, args )	Update a Stream	App
AppStream.destroy	( stream_id, args )	Delete a Stream	App
AppStream.getAll	( args )	Retrieve all Streams for the current Token	App
AppStream.destroyAll	( args )	Delete all Streams for the current Token	App
UserStream.destroy	( connection_id, args )	Delete a User Stream	user
UserStream.destroySubscription	( connection_id, subscription_id, args )	Delete a User Stream Subscription	user
filter.create	( filter, args )	Create a Filter	User
filter.get	( filter_id, args )	Retrieve a Filter	User
filter.update	( filter_id, filter, args )	Update a Filter	User
filter.destroy	( filter_id, args )	Delete a Filter	User
filter.getUser	( args )	Get the current User's Filters	User
filter.destroyUser	( args )	Delete the current User's Filters	User
interaction.get	( args )	Retrieve Interactions with the current User	User
marker.update	( marker, args )	Update a Stream Marker	User
text.process	( post_or_message, args )	Process text	Any
token.get	( args )	Retrieve the current token	Any
token.getAuthorizedIds	( args )	Retrieve authorized User IDs for an app	App
token.getAuthorized	( args )	Retrieve authorized User tokens for an app	App
place.get	( factual_id, args )	Retrieve a Place	Any
place.search	( args )	Search for Places	User
explore.show	( args )	Retrieve all Explore Streams	None
explore.get	( slug, args )	Retrieve an Explore Stream	None
config.get	( args )	Retrieve the Configuration Object	None