mini_fb 0.2.5 → 1.0.0

data/README.markdown

@@ -3,13 +3,76 @@ MiniFB - the simple miniature facebook library
 
 MiniFB is a small, lightweight Ruby library for interacting with the [Facebook API](http://wiki.developers.facebook.com/index.php/API).
 
+Support
+--------
+
+Join our Discussion Group at: http://groups.google.com/group/mini_fb
+
 Installation
 -------------
 
-We're using gemcutter so be sure to have gemcutter as a source, then: 
-
     gem install mini_fb
 
+
+Facebook Graph API
+==================
+
+For an overview of what this is all about, see http://developers.facebook.com/docs/api.
+
+Authentication
+--------------
+
+Facebook now uses Oauth 2 for authentication, but don't worry, this part is easy.
+
+    # Get your oauth url
+    @oauth_url = MiniFB.oauth_url(FB_APP_ID, # your Facebook App ID (NOT API_KEY)
+                                  "http://www.yoursite.com/sessions/create", # redirect url
+                                  :scope=>MiniFB.scopes.join(",")) # This asks for all permissions
+    # Have your users click on a link to @oauth_url
+    .....
+    # Then in your /sessions/create
+    access_token_hash = MiniFB.oauth_access_token(FB_APP_ID, "http://www.yoursite.com/sessions/create", FB_SECRET, params[:code])
+    @access_token = access_token_hash["access_token"]
+    # TODO: This is where you'd want to store the token in your database
+    # but for now, we'll just keep it in the cookie so we don't need a database
+    cookies[:access_token] = @access_token
+
+That's it. You now need to hold onto this access_token. We've put it in a cookie for now, but you probably
+want to store it in your database or something.
+
+Getting Data from Facebook
+--------------------------
+
+It's very simple:
+
+    @id = {some ID of something in facebook} || "me"
+    @type = {some facebook type like feed, friends, or photos} # (optional) nil will just return the object data directly
+    @response_hash = MiniFB.get(@access_token, @id, :type=>@type)
+
+Posting Data to Facebook
+------------------------
+
+Also pretty simple:
+
+    @id = {some ID of something in facebook}
+    @type = {some type of post like comments, likes, feed} # required here
+    @response_hash = MiniFB.post(@access_token, @id, :type=>@type)
+
+
+Logging
+-------
+
+To enabled logging:
+
+    MiniFB.enable_logging
+
+
+Original Facebook API
+=====================
+
+This API will probably go away at some point, so you should use the Graph API above in most cases.
+
+
 General Usage
 -------------
 
@@ -85,10 +148,3 @@ This is as simple as calling:
     @fb.call("photos.upload", "filename"=>"<full path to file>")
 
 The file_name parameter will be used as the file data.
-
-
-Support
---------
-
-Join our Discussion Group at: http://groups.google.com/group/mini_fb
-

data/lib/mini_fb.rb

@@ -1,6 +1,8 @@
 require 'digest/md5'
 require 'erb'
 require 'json' unless defined? JSON
+require 'rest_client'
+require 'hashie'
 
 module MiniFB
 
@@ -298,6 +300,97 @@ module MiniFB
         login_url
     end
 
+    def self.graph_base
+        "https://graph.facebook.com/"
+    end
+
+    # options:
+    #   - scope: comma separated list of extends permissions. see http://developers.facebook.com/docs/authentication/permissions
+    def self.oauth_url(app_id, redirect_uri, options={})
+        oauth_url = "#{graph_base}oauth/authorize"
+        oauth_url << "?client_id=#{app_id}"
+        oauth_url << "&redirect_uri=#{URI.escape(redirect_uri)}"
+        oauth_url << "&scope=#{options[:scope]}" if options[:scope]
+    end
+
+    # returns a hash with one value being 'access_token', the other being 'expires'
+    def self.oauth_access_token(app_id, redirect_uri, secret, code)
+        oauth_url = "#{graph_base}oauth/access_token"
+        oauth_url << "?client_id=#{app_id}"
+        oauth_url << "&redirect_uri=#{URI.escape(redirect_uri)}"
+        oauth_url << "&client_secret=#{secret}"
+        oauth_url << "&code=#{URI.escape(code)}"
+        resp = RestClient.get oauth_url
+        puts 'resp=' + resp.body.to_s if @@logging
+        params = {}
+        params_array = resp.split("&")
+        params_array.each do |p|
+            ps = p.split("=")
+            params[ps[0]] = ps[1]
+        end
+        return params
+    end
+
+    # options:
+    #   - type: eg: feed, home, etc
+    #   - metadata: to include metadata in response. true/false
+    def self.get(access_token, id, options={})
+        url = "#{graph_base}#{id}"
+        url << "/#{options[:type]}" if options[:type]
+        url << "?access_token=#{URI.escape(access_token)}"
+        url << "&metadata=1" if options[:metadata]
+        puts 'url=' + url if @@logging
+        begin
+            resp = RestClient.get url
+        rescue RestClient::Exception => ex
+            puts ex.http_code.to_s
+            puts 'ex.http_body=' + ex.http_body if @@logging
+            res_hash = JSON.parse(ex.http_body) # probably should ensure it has a good response
+            raise MiniFB::FaceBookError.new(ex.http_code, "#{res_hash["error"]["type"]}: #{res_hash["error"]["message"]}")
+        end
+        puts 'resp=' + resp.body.to_s if @@logging
+        res_hash = JSON.parse(resp.body)
+        res_hash = Hashie::Mash.new(res_hash)
+        return res_hash
+    end
+
+    # options:
+    #   - type: eg: feed, home, etc
+    #   - metadata: to include metadata in response. true/false
+    def self.post(access_token, id, options={})
+        url = "#{graph_base}#{id}"
+        url << "/#{options[:type]}" if options[:type]
+        params = {}
+        params["access_token"] = "#{(access_token)}"
+        params["metadata"] = "1" if options[:metadata]
+        puts 'url=' + url if @@logging
+        begin
+            resp = RestClient.post url, params
+        rescue RestClient::Exception => ex
+            puts ex.http_code.to_s
+            puts 'ex.http_body=' + ex.http_body if @@logging
+            res_hash = JSON.parse(ex.http_body) # probably should ensure it has a good json response
+            raise MiniFB::FaceBookError.new(ex.http_code, "#{res_hash["error"]["type"]}: #{res_hash["error"]["message"]}")
+        end
+        puts 'resp=' + resp.body.to_s if @@logging
+        res_hash = JSON.parse(resp.body)
+        res_hash = Hashie::Mash.new(res_hash)
+        return res_hash
+    end
+
+    # Returns all available scopes.
+    def self.scopes
+        all_scopes = []
+        scope_names = ["about_me", "activities", "birthday", "education_history", "events", "groups",
+                       "interests", "likes",
+                       "location", "notes", "online_presence", "photo_video_tags", "photos", "relationships",
+                       "religion_politics", "status", "videos", "website", "work_history"]
+        scope_names.each { |x| all_scopes << "user_" + x; all_scopes << "friends_" + x}
+        all_scopes << "read_friendlists"
+        all_scopes << "read_stream"
+        all_scopes
+    end
+
     # This function expects arguments as a hash, so
     # it is agnostic to different POST handling variants in ruby.
     #

metadata

@@ -3,10 +3,10 @@ name: mini_fb
 version: !ruby/object:Gem::Version 
   prerelease: false
   segments: 
+  - 1
   - 0
-  - 2
-  - 5
-  version: 0.2.5
+  - 0
+  version: 1.0.0
 platform: ruby
 authors: 
 - Travis Reeder
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-04-20 00:00:00 -07:00
+date: 2010-04-29 00:00:00 -07:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency