facebookdp 0.1.0

data/README.markdown

@@ -0,0 +1,76 @@
+# Overview
+
+This gem allows you to authenticate against facebook and then make Graph API calls from ruby
+
+# Authenticating a user against Facebook to obtain an access\_token
+
+The goal here is to delegate authentication to Facebook and retrieve a
+secret OAuth2 `access_token`. In other words, you want your web
+application to be able to send a user to facebook, and have facebook
+figure out whether or not they are who they say they are.
+
+Facebook uses OAuth2 to authenticate users on thirdparty application's
+behalf. This gem handles the Oauth2 "handshake" with
+facebook. Basically, here are the steps:
+
+1) Register you application with Facebook and get your API Key and API Secret
+
+2) Create Facebook::OAuth object like so: 
+
+    @oauth2 ||= Facebookdp::OAuth.new(your-api-key, you-api-secret, 'https://graph.facebook.com', facebook-callback-url)
+    
+The `facebook-callback-url` argument should be something like
+`http://yourwebapp/facebook-controller/handle-facebook-response`. If
+you don't specifiy a facebook-callback-url, it will default to
+`http://localhost:3000/facebook`. So you might want to just stick a
+controller there when doing development for easy testing.
+
+3) Next, call `@oauth2.authorize_url`. This should give you a url like
+this:
+`https://graph.facebook.com/oauth/authorize?client_id=YOUR_APP_ID&type=web_server&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Ffacebook%2Fcallback`
+
+4) Now it's time to trade the `client_id` for a Access Token (note the
+http param named `client_id` in the `authorize_url`). Your web app
+should redirect the user's browser to the `authorize_url`. Facebook
+then prompts for a username and password. The user enters a username
+and password.
+
+Tip: During development, sometimes it helps to simply copy and paste the `authorize_url` into your
+browser. 
+
+5a) If the user enters invalid credentials, they'll be redirected back
+to the `facebook-callback-url` specified above. The request will
+include a http param named `error_reason` so your application can
+handle the invalid username and password error appropriately.
+
+5b) If this is the first time the user has ever logged into your
+application, they'll be prompted by Facebook whether to allow or deny
+your web application. After they choose to allow or deny, they'll be
+redirected to the facebook-callback-url specified above. 
+
+6) Assuming the user entered correct credentials and approved your web
+application, then they'll be redirected back to the
+`facebook-callback-url` you specified above. For example, something like this
+
+http://yourwebapp/facebook-controller/handle-facebook-response?code=dd8490a3a1c82de377f45bc3-1388092492|\_6MST-8QGIQhiKP3ZkdEMou44Uo
+
+Your web appilcation should parse that access code and hang onto it!
+
+7) Next, you trade the access code for an `access_token` like so: 
+
+    @oauth2_token = @oath2.get_access_token
+    @oauth2_token ||= @oauth2.get_access_token(the-access-code-you-parsed-and-saved)
+
+# Using this Facebook Gem to make Graph API calls
+
+First, you have to do the whole OAuth2 song and dance as described above. Once you do that, you should have a OAuth2 `access_token` for the user. You can then use the token to create an instance of the Facebookdp::Base class. 
+
+    @client = Facebookdp::Base.new(@oauth2_token)
+    
+Then, simply use the `@client` instance to make Facebook Graph API
+calls on the user's behalf. For example, you can get all the users
+friends:
+
+    friends = @client.friends
+    
+

data/lib/facebookdp.rb

@@ -0,0 +1,8 @@
+gem 'oauth2', '~> 0.0.8'
+require 'oauth2'
+
+gem 'crack'
+require 'crack/json'
+
+require 'facebookdp/oauth'
+require 'facebookdp/base'

data/lib/facebookdp/base.rb

@@ -0,0 +1,56 @@
+module Facebookdp
+  class Base
+    def initialize(oauth2_access_token)
+      @access_token = oauth2_access_token
+    end
+
+    # 
+    # Return current user's account information
+    def my_account
+      @my_account ||= Crack::JSON.parse(get_request("/me"))
+    end
+
+    def my_picture_url
+      @my_picture_url ||= "http://graph.facebook.com/#{my_account['id']}/picture"
+    end
+
+    # Get list of hash's id and name keys for each of current_user's friends
+    def friend_ids_and_names
+      @friend_ids ||= Crack::JSON.parse(get_request("/me/friends?fields=id,name"))['data']
+    end
+
+    # Get all information about all your friends. Pass limit
+    def friends(limit=0, offset=0)
+      if(limit<=0)
+        @friends ||= Crack::JSON.parse(get_request("/me/friends"))['data']
+      else
+        #TODO: this isn't working, not sure why
+        @friends ||= Crack::JSON.parse(get_request("/me/friends?limit=#{limit}&offset=#{offset}"))['data']
+      end
+    end
+
+    # Retrieve full information about a friend given their facebook id
+    def friend_info(fbid)
+      Crack::JSON.parse(get_request("/#{fbid}"))
+    end
+
+    # Retrieve last 10 statuses of a friend. Pass in limit to control
+    # number of status returned
+    def friend_statuses(fbid, limit=10)
+      Crack::JSON.parse(get_request("/#{fbid}/statuses?limit=#{limit}"))['data']
+    end
+
+    # Retrieve all statuses published by a friend since the date specified.
+    # TODO: not tested yet
+    def friend_latest_statuses(unix_timestamp)
+      Crack::JSON.parse(get_request("/#{fbid}/statuses?since=#{unix_timestamp}"))
+    end
+
+    protected
+
+    def get_request(path)
+      @access_token.get(path)
+    end
+
+  end
+end

data/lib/facebookdp/oauth.rb

@@ -0,0 +1,35 @@
+module Facebookdp
+  class OAuth
+    attr_accessor :apikey, :apisecret, :graph_api_url, :callback_url, :code
+
+    def initialize(apikey, apisecret, graph_api_url = "https://graph.facebook.com", callback_url = "http://localhost:3000/facebook/callback")
+      @apikey = apikey
+      @apisecret = apisecret
+      @graph_api_url = graph_api_url
+      @callback_url = callback_url
+    end
+
+    #
+    # client is an instance of an oauth object, but needs to be
+    # authenticated by having a user visit facebook and retrieve a
+    # access code
+    def client
+      @client ||= OAuth2::Client.new(@apikey, @apisecret, :site => @graph_api_url)
+    end
+
+    #
+    # Get the url needed to recieve auth token
+    # behind the scenes, oauth2 is passing id and secret
+    def authorize_url
+      client.web_server.authorize_url( :redirect_uri => callback_url )
+    end
+
+    #
+    # Create access_token, and then we're connected
+    def get_access_token(code)
+      @code = code
+      @access_token ||= client.web_server.get_access_token( @code, :redirect_uri => callback_url)
+    end
+
+  end
+end

data/test/facebookdp_test.rb

@@ -0,0 +1,94 @@
+require 'rubygems'
+require 'facebookdp'
+require 'test/unit'
+
+class FacebookdpTest < Test::Unit::TestCase
+  # copy valid code here:
+  ACCESS_CODE = '' 
+  FACEBOOK_APP_ID = '' 
+  FACEBOOK_APP_SECRET = '' 
+  class << self
+    def startup
+      unless @oauth2_token
+        @oauth2 ||= Facebookdp::OAuth.new(FACEBOOK_APP_ID, FACEBOOK_APP_SECRET , 'https://graph.facebook.com', 'http://localhost:3000/oauth2_consumers/facebook/callback')
+        expected = "https://graph.facebook.com/oauth/authorize?client_id=#{FACEBOOK_APP_ID}&type=web_server&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Ffacebook%2Fcallback"
+        begin
+          @oauth2_token ||= @oauth2.get_access_token(ACCESS_CODE)
+          @client = Facebookdp::Base.new(@oauth2_token)
+        rescue
+          #TODO: how to know if session is invalid and recover?
+          puts "Copy the following url into your browser to get a valid access token: #{@oauth2.authorize_url}"
+          raise
+        end
+      end
+    end
+
+    def shutdown
+      # puts 'this runs once at end'
+    end
+
+    def oauth2_token
+      @oauth2_token
+    end
+
+    def client
+      @client
+    end
+
+    def suite
+      mysuite = super
+      def mysuite.run(*args)
+        FacebookdpTest.startup()
+        super
+        FacebookdpTest.shutdown()
+      end
+      mysuite
+    end
+  end
+
+  def setup
+    # puts 'runs once before each test'
+  end
+
+  def teardown
+    # puts 'runs once after each test'
+  end
+
+  def test_simple
+    assert(true)
+  end
+
+  def test_get_my_account
+    result = self.class.client.my_account
+    assert_equal("Dave Paroulek", result['name'])
+  end
+
+  def test_get_friend_ids
+    result = self.class.client.friend_ids_and_names
+    assert_equal(159, result.size)
+  end
+
+  def test_get_friends
+    result = self.class.client.friends
+    assert_equal(159, result.size)
+  end
+
+  def test_get_friend_info
+    result = self.class.client.friend_info(1500782)
+    assert_equal(result['name'], "Michael Shafrir")
+    assert_equal(result['first_name'], "Michael")
+  end
+
+  def test_get_friend_statuses
+    result = self.class.client.friend_statuses(1500782, 1)
+    assert_equal(1, result.size)
+    assert_not_nil(result[0]['message'])
+  end
+
+  def test_get_my_picture
+    expected = "http://graph.facebook.com/1388092492/picture"    
+    result = self.class.client.my_picture_url
+    assert_equal(expected,result)
+  end
+
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification 
+name: facebookdp
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Dave Paroulek
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-11-02 00:00:00 -04:00
+default_executable: 
+dependencies: []
+
+description: Consumes the Facebook OAuth2 Graph Rest API
+email: dave @nospam@ daveparoulek.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.markdown
+- lib/facebookdp/base.rb
+- lib/facebookdp/oauth.rb
+- lib/facebookdp.rb
+- test/facebookdp_test.rb
+has_rdoc: true
+homepage: http://upgradingdave.com
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.7
+signing_key: 
+specification_version: 3
+summary: Exposes Facebook OAuth2 Graph Rest API and provides ability to authenticate users against Facebook
+test_files: []
+