= FbGraph

A Ruby wrapper for Facebook Graph API.
This is a work in progress.

== Installation

  gem install fb_graph

== Resources

* View Source on GitHub (http://github.com/nov/fb_graph)
* View RDoc on GitHub (http://nov.github.com/fb_graph)
* Report Issues on GitHub (http://github.com/nov/fb_graph/issues)
* Facebook fan page (http://www.facebook.com/pages/FbGraph/117513961602338)

== Examples

Now FbGraph supports all objects listed here: http://developers.facebook.com/docs/reference/api/
Almost all connections　for each object are also supported. (Private message connections are not supported yet)

=== GET

==== Basic Objects

  user = FbGraph::User.fetch('matake')
  user.name    # => 'Nov Matake'
  user.picture # => 'https://graph.facebook.com/matake/picture'

  # User.new doesn't fetch the user's profile info
  me = User.new('me', :access_token => YOUR_ACCESS_TOKEN)

  page = FbGraph::Page.fetch('smartfmteam')
  page.name     # => 'smart.fm'
  page.picture  # => 'https://graph.facebook.com/smart.fm/picture'

  :

==== Connections

  # Public connections
  user = FbGraph::User.fetch('matake')
  user.feed
  user.posts
  user.friends
  user.tagged
  :
  
  # Private connections requires "access_token"
  FbGraph::User.new('matake').friends # => raise FbGraph::Unauthorized
  user = FbGraph::User.fetch('matake', :access_token => ACCESS_TOKEN)
  user.albums
  user.events
  user.friends
  user.likes
  :
  
  # "home" connection is only available for "me"
  me = User.new('me', :access_token => ACCESS_TOKEN)
  me.home
  :

==== Pagination

  user = FbGraph::User.new('matake', :access_token => ACCESS_TOKEN)
  likes = user.likes # => Array of FbGraph::Like
  likes.next         # => {:limit => 25, :until => '...'}
  likes.previous     # => {:limit => 25, :since => '...'}
  user.likes(likes.next)     # => Array of FbGraph::Like
  user.likes(likes.previous) # => Array of FbGraph::Like

=== POST

==== Update status (wall post)

  me = FbGraph::User.me(ACCESS_TOKEN)
  me.feed!(
    :message => 'Updating via FbGraph',
    :picture => 'https://graph.facebook.com/matake/picture',
    :link => 'http://github.com/nov/fb_graph',
    :name => 'FbGraph',
    :description => 'A Ruby wrapper for Facebook Graph API'
  )

==== Post a like/comment to a post

  post = FbGraph::Page.new(117513961602338).feed.first
  bool = post.like!(
    :access_token => ACCESS_TOKEN
  )
  comment = post.comment!(
    :access_token => ACCESS_TOKEN,
    :message => 'Hey, I\'m testing you!'
  )

==== Post a note

  page = FbGraph::Page.new(117513961602338)
  note = page.note!(
    :access_token => ACCESS_TOKEN,
    :subject => 'testing',
    :message => 'Hey, I\'m testing you!'
  )

==== Post a link

  me = FbGraph::User.me(ACCESS_TOKEN)
  link = me.link!(
    :link => 'http://github.com/nov/fb_graph',
    :message => 'A Ruby wrapper for Facebook Graph API.'
  )

==== Create Event, respond to it

  me = FbGraph::User.me(ACCESS_TOKEN)
  event = me.event!(
    :name => 'FbGraph test event',
    :start_time => 1.week.from_now.to_i,
    :end_time => 2.week.from_now.to_i
  )
  bool = event.attending!(
    :access_token => ACCESS_TOKEN
  )
  bool = event.maybe!(
    :access_token => ACCESS_TOKEN
  )
  bool = event.declined!(
    :access_token => ACCESS_TOKEN
  )

==== Create an album

  me = FbGraph::User.me(ACCESS_TOKEN)
  album = me.album!(
    :name => 'FbGraph test',
    :message => 'test test test'
  ) # => now facebook Graph API returns weird response for this call

==== Upload a photo to an album

  me = FbGraph::User.me(ACCESS_TOKEN)
  album = me.albums.first
  album.photo!(
    :access_token => ACCESS_TOKEN,
    :image => File.new('/Users/nov/Desktop/nov.gif', 'rb'), # 'rb' is needed only on windows
    :message => 'Hello, where is photo?'
  )

== Note on Patches/Pull Requests
 
* Fork the project.
* Make your feature addition or bug fix.
* Add tests for it. This is important so I don't break it in a
  future version unintentionally.
* Commit, do not mess with rakefile, version, or history.
  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
* Send me a pull request. Bonus points for topic branches.

== Copyright

Copyright (c) 2010 nov matake. See LICENSE for details.