= FbGraph

A full-stack Facebook Graph API wrapper in Ruby.

{<img src="https://secure.travis-ci.org/nov/fb_graph.png" />}[http://travis-ci.org/nov/fb_graph]

== This gem is deprecated

FbGraph is basically developed for Graph API v1.0, and could be buggy with v2.+.

Since Graph API v1.0 is shut down on 2014/04/30, this gem is also deprecated.

Please use fb_graph2 gem instead.
https://github.com/nov/fb_graph2

== Installation

  gem install fb_graph

== Resources

* View Source on GitHub (https://github.com/nov/fb_graph)
* Report Issues on GitHub (https://github.com/nov/fb_graph/issues)
* Subscribe Update Info (https://www.facebook.com/FbGraph)
* Q&A on Google Groups (http://groups.google.com/group/fb_graph)

== Examples

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

You can also play with a Rails sample app here. http://fbgraphsample.heroku.com/

See GitHub wiki for more examples.
https://github.com/nov/fb_graph/wiki

=== GET

==== Basic Objects

  user = FbGraph::User.me(ACCESS_TOKEN)

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

  # fb_graph doesn't access to Graph API until you call "fetch"
  user = FbGraph::User.new('matake', :access_token => YOUR_ACCESS_TOKEN)
  user.identifier # => "matake"
  user.name # => nil
  user.link # => nil
  user = user.fetch
  user.name # => "Nov Matake"
  user.description # => "http://www.facebook.com/matake"

  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
  user.family
  :

  # 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
  :

By default, FbGraph will only return the default fields. In order to
get a non-default field, you have to supply the connect with an optional hash
specifying the field. An example for events:

  user.events({:fields => "owner,name,description,picture"}) # { and } optional

An overview of which fields you can include in the graph API can be found at
https://developers.facebook.com/docs/reference/api/, which has a description
of the specific objects fields in the sidebar under "Objects".

==== Search

  # all objects
  FbGraph::Searchable.search("FbGraph") # => Array of Hash

  # specify type
  FbGraph::Page.search("FbGraph") # => Array of FbGraph::Page
  FbGraph::User.search("matake", :access_token => ACCESS_TOKEN) # => Array of FbGraph::User

==== Pagination

  # collection
  user = FbGraph::User.new('matake', :access_token => ACCESS_TOKEN)
  likes = user.likes # => Array of FbGraph::Like
  likes.next         # => Array of FbGraph::Like (next page)
  likes.previous     # => Array of FbGraph::Like (previous page)
  likes.collection.next     # => Hash for pagination options (ex. {"limit"=>"25", "until"=>"2010-08-08T03:17:21+0000"})
  likes.collection.previous # => Hash for pagination options (ex. {"limit"=>"25", "since"=>"2010-08-08T06:28:20+0000"})
  user.likes(likes.collection.next)     # => same with likes.next
  user.likes(likes.collection.previous) # => same with likes.previous

  # search results
  results = FbGraph::Page.search("FbGraph") # => Array of FbGraph::Page
  results.next     # => Array of FbGraph::Page (next page)
  results.previous # => Array of FbGraph::Page (next page)
  results.klass    # => FbGraph::Page
  results.collection.next     # => Hash for pagination options (ex. {"limit"=>"25", "until"=>"2010-08-08T03:17:21+0000"})
  results.collection.previous # => Hash for pagination options (ex. {"limit"=>"25", "since"=>"2010-08-08T06:28:20+0000"})
  results.klass.search(results.query, results.collection.next)     # => same with results.next
  results.klass.search(results.query, results.collection.previous) # => same with results.previous

=== 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 => 'https://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 => 'https://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,
    :end_time => 2.week.from_now
  )
  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,
    :source => File.new('/Users/nov/Desktop/nov.gif', 'rb'), # 'rb' is needed only on windows
    :message => 'Hello, where is photo?'
  )

=== DELETE

==== Delete an object

  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!'
  )
  comment.destroy(:access_token => ACCESS_TOKEN)
  post.unlike!(:access_token => ACCESS_TOKEN)
  post.destroy(:access_token => ACCESS_TOKEN)

=== Authentication

Both Facebook JavaScript SDK and normal OAuth2 flow are supported.
Below I show simple sample code.
You can also see https://github.com/nov/fb_graph_sample for more details Rails3 sample application.

In addition, if you are migrating an application that uses old-style session keys you can exchange
the keys for access tokens.
See more here: http://developers.facebook.com/docs/authentication/fb_sig/

==== JavaScript SDK

  fb_auth = FbGraph::Auth.new(YOUR_APP_ID, YOUR_APPLICATION_SECRET)
  fb_auth.client # => Rack::OAuth2::Client

  # get Facebook's auth cookie in advance using their JS SDK
  fb_auth.from_cookie(cookies)
  fb_auth.access_token # => Rack::OAuth2::AccessToken
  fb_auth.user         # => FbGraph::User (only basic attributes)
  fb_auth.user.fetch   # => fetch more details

==== Normal OAuth2 Flow

  # setup client
  client = fb_auth.client
  client.redirect_uri = "http://your.client.com/facebook/callback"

  # redirect user to facebook
  redirect_to client.authorization_uri(
    :scope => [:email, :read_stream, :offline_access]
  )

  # in callback
  client.authorization_code = params[:code]
  access_token = client.access_token! :client_auth_body # => Rack::OAuth2::AccessToken
  FbGraph::User.me(access_token).fetch # => FbGraph::User

==== Extend Access Token Lifetime

  # setup client
  fb_auth = FbGraph::Auth.new(YOUR_APP_ID, YOUR_APPLICATION_SECRET)
  fb_auth.exchange_token! 'short-life-access-token'
  fb_auth.access_token # => Rack::OAuth2::AccessToken


=== Analytics

  app = FbGraph::Application.new(YOUR_APP_ID, :secret => YOUR_APPLICATION_SECRET)
  app.insights # => Array of FbGraph::Insight

=== Test User

Not tested well yet.
Sample is here.
https://gist.github.com/752974

=== FQL

Not tested well yet.
Sample is here.
https://gist.github.com/752914

=== More Examples?

See GitHub wiki for more examples.
https://github.com/nov/fb_graph/wiki

== 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.