Powncer!

Powncer is a Ruby library/wrapper to the Pownce REST API

Get It

sudo gem install powncer
Powncer requires the JSON gem to be installed. Which it will include by default

Getting Started

irb -rubygems
irb(main):001:0> require 'powncer'
=> true
irb(main):002:0> include Powncer
=> Object

Powncer provides many objects for the Pownce API, with the two main objects being User and Note. While some actions require authentication to perform, some can produce both public (non-authenticated) and private (authenticated) results.

User

Profile

You can access a users public profile:

user = User.new('jaehess')
user.profile

- or -

user = User.find('jaehess')
To retrieve authenticated results, you must create an authenticated connection prior to the call.

You can access properties of a users profile:

user.short_name
=> "Jae H."
user.gender
=> "Bloke"
user.is_pro?
=> false
See docs for full list of available methods

Friends, Fans, Fan of

You can access a users relationship data:

user.friends
=> [#<Powncer::User:0x148e670 @attributes={....]
user.fans
=> []
user.fan_of.length
=> 2
The above methods return an array of user objects that follow the same patterns as the User.profile methods
user.friends.first.short_name
=> "Andrew S."

Note

Find

Return properties on a specific note.

note = Note.find(1437687)
=> #<Powncer::Note:0x14a06b8>
note.body
=> "Powncer Ruby Gem released soon ..."
note.permalink
=> "http://pownce.com/jaehess/notes/1437687/"
If the note is not public, or viewable from the authenticated user, you will receive a PowncerError.

You also have access to the sender object / recipient list:

note.sender
=> #<Powncer::User:0x148e670>
note.sender.first_name
=> "Jae"
note.recipients
=> [#<Powncer::User:0x148e670 @attributes={....]
note.recipients.length
=> "7"
note.recipients.first.gender
=> "Bloke"
Sender / recipient object(s) follow the same patterns as the User.profile

Note Lists

Returns a list of notes for the user (users public notes by default). If authenticated, will return the users typical Pownce stream. When accessing through a friend, you will see notes friend sent to you.

Public Note List

Returns an array of note objects from the Pownce public timeline.

notes = Note.find(:public)
=> [#<Powncer::Note:0x14a06b8>....]
notes.length
=> 20 # Default
lots_of_notes = Note.find(:public, {:limit => 100})
lots_of_notes.length
=> 100 # Max you can get in a single request lots_of_notes.first.body
=> "It takes a very long time...."
You can access pagination on this method Ex. Note.find(:public, {:page => 2})

User Note Lists

Same results as the Public Note List, scoped to a user. You can also filter by types.

user
=> #<Powncer::User:0x148e670>
user.notes # all messages, events, and links
=> [#<Powncer::Note:0x14a06b8>....]
user.messages.length
=> 1
user.links.length
=> 1
user.events.length
=> 1
To retrieve authenticated results, you must create an authenticated connection prior to the call.

Authenticating

Before you can access any of the authenticated portions of the Pownce API, you must establish an authenticated connection.

Creating Basic Auth Connection

Authentication::Basic.connect!({
:secret_key=>"api_secret_key",
:username=>"username",
:application_key=>"api_application_key",
:password=>"password"
})

Environment Variables

You may specify the credentials with the following environment variables

ENV["POWNCER_APPLICATION_KEY"] = "api_application_key"
ENV["POWNCER_SECRET_KEY"] = "api_secret_key"
ENV["POWNCER_USERNAME"] = "username"
ENV["POWNCER_PASSWORD"] = "password"
You can store the above in ~/.powncer, and the library will autoload the variables
Authentication::Basic.connect! # Args loaded from ENV

Example

user
=> #<Powncer::User:0x148e670>
user.notes.length
=> 3 # public notes length
Authentication::Basic.connect!
user.notes.length
=> 20 # all notes length

Posting

All posted Note types accept a :to parameter. If this is not specified, the users default send to is used. If a recipient is not valid for that user, it will return a InvalidFriend error.

Post Message

Parameters are:

:to
options are: :all, :public or username
:body
text of the message

note = Note.new({:to => "jaehess", :body => "Foo Bar"})
note.save

- or -

note = Note.create({:to => "jaehess", :body => "Foo Bar"})
Both of these return the Note object back, allowing calls on the note object with expected results. Ex. note.body #=> "Foo Bar", etc.

Post Link

Parameters are:

:to
options are: :all, :public or username
:url
full url of the link, including http://
:body [optional]
text of the message

link = Link.new({:to => :public, :url => "http://powncer.rubyforge.org"})
link.save

- or -

link = Link.create({:url => "http://powncer.rubyforge.org"})
Both of these return the Link object back, allowing calls on the link object with expected results. Ex. link.url #=> "http://powncer.rubyforge.org", etc.

Post Event

Parameters are:

:to
options are: :all, :public or username
:name
name of event
:location
location of the event
:date
date of the event in the format YYYY-MM-DD hh:mm
:body [optional]
text of the message

event = Event.new({:to => "powncertest", :name => "Crazy Sk8 Party!", :location => "Hubba Hideout, SF", :date => "2008-03-06 18:00"})
event.save

- or -

event = Event.create({:to => "powncertest", :name => "Crazy Sk8 Party!", :location => "Hubba Hideout, SF", :date => "2008-03-06 18:00"})
Both of these return the Event object back, allowing calls on the event object with expected results. Ex. event.location #=> "Hubba Hideout, SF", etc.

Posting Errors

The following errors are specific to creating / saving new notes

InvalidFriend
raised when target recipient is not in senders send to list
RequirementMissing
raised when a required attribute has not been specified
InvalidFormat
raised when either date/url formatting on Event/Link object is incorrect, respectively

Contribute

How to submit patches

Read the 8 steps for fixing other peoples code and for section 8c. Submit patch to RubyForge Tracker, use the Powncer Tracker.

svn co http://powncer.rubyforge.org/svn/trunk/ powncer

Miscellaneous

To Do

Powncer Gem by Jae Hess
Logo inspired by AWS::S3 Logo, created by Lemon Mob.