facebookrb 0.1.0 → 0.1.1

data/README.rdoc

@@ -1,47 +1,82 @@
-= facebookrb 
+= facebookrb
 
-Facebookrb is currently a work in progress.
-It aims to be a lightweight yet fully featured client for the [Facebook API](http://wiki.developers.facebook.com/index.php/API).
-It is mostly based on MiniFB (http://github.com/appoxy/mini_fb) and includes some features inspired by rack-facebook (http://github.com/carlosparamio/rack-facebook).
-In other instances, it emulates the official Facebook PHP library.
+Facebookrb aims to be a lightweight yet fully featured client for the 
+{Facebook API}[http://wiki.developers.facebook.com/index.php/API], drawing
+on the best features from existing Ruby Facebook libraries.
+The functions and features are intentionally kept simple, so you can spend
+your time reading the official Facebook documentation rather than learning
+how the code works.
 
 == Installation
 
     gem install facebookrb
 
 == General Usage
-	
-	require 'facebookrb'
 
-You will want to create a client to make calls to Facebook
+The easiest way is to use the middleware.  Put this in your config.ru, Sinatra application, or wherever you declare middleware:
 
-    fb_client = FacebookRb::Client.new("API_KEY", "SECRET")
+    require 'facebookrb'
 
-If you are using the middleware, there will be one created for you already,
-available in `env['facebook.client']`.
+    use FacebookRb::Middleware, :api_key => "APIKEY", :secret => "SECRET"
 
-    user_hash = fb_client.call("Users.getInfo", "session_key"=>@session_key, "uids"=>@uid, "fields"=>User.all_fields)
+This will create a Facebook API client, populate it with any parameters from Facebook, and store it in the Rack env for you.
 
-Which simply returns the parsed json response from Facebook.
-The client will ask for results in JSON by default.
+    fb = env['facebook.client']
 
-== Middleware
+Make a call using short or long format (thanks tmm1/sinbook for the short version)
 
-The middleware checks the signature of Facebook params, and stores them in env.
+    user = fb.users.getInfo('uids' => '123235345', 'fields' => ['name', 'sex', 'religion'])
+    user = fb.call('users.getInfo', 'uids' => '123235345', 'fields' => ['name', 'sex', 'religion'])
 
-    require 'facebookrb'
+This call parses the JSON from Facebook and returns the resulting objects (a Hash, Array, String, or Integer depending on how complex the JSON is).
+The raw text of the response is also available:
+
+	fb.call(...)
+	fb.last_response
+
+If you received params from Facebook, and they are {valid}[http://wiki.developers.facebook.com/index.php/Verifying_The_Signature], then you can access them:
+
+    fb.params['user']
+    fb['user']  # Also works
+
+The 'session_key' param will automatically be passed forward to any API calls if available.
+
+== Options
+
+The options for the middleware and the client are identical, and are values you get from Facebook:
+
+    :api_key, :secret, :canvas_url
+
+== Features
+
+=== Facebook Connect
+
+The library supports reading parameters from cookies, so Connect support should be there (not thoroughly tested ATM).
+
+=== {Batching}[http://wiki.developers.facebook.com/index.php/Using_Batching_API]
+
+	results = fb.batch do 
+	 fb.application.getPublicInfo(...)
+	 fb.users.getInfo(...)
+	end
+
+	results[0]  # => result for first call
+	results[1]  # => result for second call
 
-    use Rack::Facebook, :api_key => "APIKEY", :secret => "SECRET"
+== Potential Features
 
-The Facebook parameters in the request are stored in `env['facebook.params']` and `env['facebook.client'].fb_params` if the request is valid (http://wiki.developers.facebook.com/index.php/Verifying_The_Signature)
+These would all be easy to add if anyone needs support for them.
 
-== Planned Features
+* {Base domain}[http://wiki.developers.facebook.com/index.php/Base_Domain]
+* {Preload FQL}[http://wiki.developers.facebook.com/index.php/Preload_FQL]
+* {Permissions API}[http://wiki.developers.facebook.com/index.php/Permissions_API]
+* {Session Secret}[http://wiki.developers.facebook.com/index.php/Session_Secret]
+* Converting the request method from the Facebook POST to the original HTTP method used by the client. (http://wiki.developers.facebook.com/index.php/Fb_sig_request_method)
 
-  * Facebook Connect
-  * Batching (http://wiki.developers.facebook.com/index.php/Using_Batching_API)
-  * Base domain (http://wiki.developers.facebook.com/index.php/Base_Domain)
-  * Preload FQL (http://wiki.developers.facebook.com/index.php/Preload_FQL)
-  * Permissions API (http://wiki.developers.facebook.com/index.php/Permissions_API)
-  * Session Secret (http://wiki.developers.facebook.com/index.php/Session_Secret)
-  * Converting the request method from the Facebook POST to the original HTTP method used by the client. (http://wiki.developers.facebook.com/index.php/Fb_sig_request_method)
+== Acknowledgements
 
+The code for this project was initially derived from:
+* {sinbook}[http://github.com/tmm1/sinbook]
+* {MiniFB}[http://github.com/appoxy/mini_fb]
+* {rack-facebook}[http://github.com/carlosparamio/rack-facebook]
+* The official Facebook PHP library

data/Rakefile

@@ -21,7 +21,7 @@ spec = Gem::Specification.new do |s|
 
   # Change these as appropriate
   s.name              = "facebookrb"
-  s.version           = "0.1.0"
+  s.version           = "0.1.1"
   s.summary           = "Simple Facebook API client and middleware"
   s.author            = "John Mendonca"
   s.email             = "joaosinho@gmail.com"
@@ -40,7 +40,7 @@ spec = Gem::Specification.new do |s|
    s.add_dependency("yajl-ruby")
 
   # If your tests use any gems, include them here
-  s.add_development_dependency("rspec")
+  #s.add_development_dependency("rspec")
 
   # If you want to publish automatically to rubyforge, you'll may need
   # to tweak this, and the publishing task below too.

data/lib/facebookrb.rb

@@ -1,3 +1,4 @@
+require 'rack/request' unless defined?(Rack::Request)
 require 'uri'
 require 'net/http'
 require 'digest/md5'
@@ -29,28 +30,41 @@ module FacebookRb
     USER_FIELDS_STANDARD = [:uid, :first_name, :last_name, :name, :timezone, 
       :birthday, :sex, :affiliations, :locale, :profile_url, :proxied_email]
 
-    attr_accessor :api_key, :secret, :session_key, :fb_params
-    attr_accessor :last_response
+    attr_accessor :api_key, :secret, :canvas_url, :format
+    attr_accessor :pending_batch, :batch_queue, :last_response
 
-    def initialize(api_key, secret, session_key=nil)
-      @api_key = api_key
-      @secret = secret
-      @session_key = session_key
+    def initialize(options = {})
+      self.api_key = options[:api_key] || options['api_key']
+      self.secret = options[:secret] || options['secret']
+      self.canvas_url = options[:canvas_url] || options['canvas_url']
+      self.format = options[:format] || options['format'] || 'JSON'
     end
 
-    def fb_params=(params)
-      @fb_params = params
-      @session_key = params['session_key'] if params 
+    def params
+      @params ||= {}
+    end
+
+    def [](key)
+      params[key]
+    end
+
+    def valid?
+      !params.empty?
+    end
+
+    def url(path = nil)
+      path ? "#{canvas_url}#{path}" : canvas_url
+    end
+
+    def addurl
+      "http://apps.facebook.com/add.php?api_key=#{self.api_key}"
     end
 
     #
     # Call facebook server with a method request. Most keyword arguments
     # are passed directly to the server with a few exceptions.
     #
-    # The default return is a parsed json object.
-    # Unless the 'format' and/or 'callback' arguments are given,
-    # in which case the raw text of the reply is returned. The string
-    # will always be returned, even during errors.
+    # Returns a parsed json object.
     #
     # If an error occurs, a FacebookError exception will be raised
     # with the proper code and message.
@@ -60,42 +74,177 @@ module FacebookRb
 
       # Prepare standard arguments for call
       api_params['method']      ||= method
-      api_params['api_key']     ||= api_key
-      api_params['session_key'] ||= session_key
-      api_params['call_id']     ||= Time.now.to_s
+      api_params['api_key']     ||= self.api_key
+      api_params['format']      ||= self.format
+      api_params['session_key'] ||= self.params['session_key']
+      api_params['call_id']     ||= Time.now.to_f.to_s
       api_params['v']           ||= FB_API_VERSION
-      api_params['format']      ||= 'JSON'
 
-      # Encode any Array or Hash arguments into JSON
-      json_encoder = Yajl::Encoder.new
-      api_params.each do |key, value|
-        if value.is_a?(Array) || value.is_a?(Hash)
-          api_params[key] = json_encoder.encode(value)
-        end
-      end
+      convert_outgoing_params(api_params)
 
       api_params['sig'] = generate_signature(api_params, self.secret)
 
-      # Call website with POST request
+      #If in a batch, stash the params in the queue and bail
+      if pending_batch
+        batch_queue << api_params.map { |k,v| "#{k}=#{v}" }.join('&')
+        return
+      end
+
+      # Call Facebook with POST request
       response = Net::HTTP.post_form( URI.parse(FB_URL), api_params )
 
       # Handle response
       self.last_response = response.body
       data = Yajl::Parser.parse(response.body)
 
-      if data.include?('error_msg')
+      if data.is_a?(Hash) && data['error_msg']
         raise FacebookError.new(data['error_code'], data['error_msg'])
       end
 
       return data
     end
 
+    #
+    # Performs a batch API operation (batch.run)
+    #
+    # Example:
+    #   results = fb.batch do 
+    #     fb.application.getPublicInfo(...)
+    #     fb.users.getInfo(...)
+    #   end
+    #
+    # Options:
+    #   * :raise_errors (default true) - since a batch returns results for
+    #     multiple calls, some may return errors while others do not, by default
+    #     an exception will be raised if any errors are found.  Set to 
+    #     false to disable this and handle errors yourself
+    def batch(options = {})
+      return unless block_given?
+      #TODO: real error code/message
+      raise FacebookError.new('error_code', 'error_msg') if pending_batch 
+
+      self.batch_queue = []
+      self.pending_batch = true
+      options[:raise_errors] = true if options[:raise_errors].nil?
+
+      yield self
+
+      self.pending_batch = false
+      results = call('batch.run', 
+                     :method_feed => self.batch_queue, 
+                     :serial_only => true)
+      self.batch_queue = nil
+
+      #Batch results are an array of JSON strings, parse each
+      results.map! { |json| Yajl::Parser.parse(json) }
+
+      results.each do |data|
+        if data.is_a?(Hash) && data['error_msg']
+          raise FacebookError.new(data['error_code'], data['error_msg'])
+        end
+      end if options[:raise_errors]
+
+      results
+    end
+
     def add_special_params(method, params)
       #call_as_apikey for Permissions API
       #ss Session secret
       #use_ssl_resources
     end
 
+    #
+    # Extracts and validates any Facebook parameters from the request, and
+    # stores them in the client.
+    # We look for parameters from POST, GET, then cookies, in that order. 
+    # POST and GET are always more up-to-date than cookies, so we prefer 
+    # those if they are available.
+    #
+    # Parameters:
+    #   env   the Rack environment, or a Rack request
+    #
+    def extract_params(env)
+      #Accept a Request object or the env
+      if env.is_a?(Rack::Request)
+        request = env
+      else
+        request = Rack::Request.new(env)
+      end
+
+      #Fetch from POST
+      fb_params = get_params_from(request.POST, 'fb_sig')
+
+      #Fetch from GET
+      unless fb_params
+        # note that with preload FQL, it's possible to receive POST params in
+        # addition to GET, and a different prefix is used for each
+        fb_get_params = get_params_from(request.GET, 'fb_sig') || {}
+        fb_post_params = get_params_from(request.POST, 'fb_post_sig') || {}
+        fb_get_params.merge!(fb_post_params) 
+        fb_params = fb_get_params unless fb_get_params.empty?
+      end
+
+      #Fetch from cookies
+      unless fb_params
+        fb_params = get_params_from(request.cookies, self.api_key)
+      end
+      
+      @params = convert_incoming_params(fb_params)
+    end
+
+    #
+    # Converts some parameter values into more useful forms: 
+    #   * 0 or 1 into true/false
+    #   * Time values into Time objects
+    #   * Comma separated lists into arrays
+    #
+    def convert_incoming_params(params)
+      return nil unless params
+
+      params.each do |key, value|
+        case key
+        when 'friends', 'linked_account_ids'
+          params[key] = value.split(',')
+        when /(time|expires)$/
+          if value == '0'
+            params[key] = nil
+          else
+            params[key] = Time.at(value.to_f)
+          end
+        when /^(logged_out|position_|in_|is_)/, /added$/
+          params[key] = (value == '1')
+        else
+          params[key] = value
+        end
+      end
+
+      params
+    end
+
+    #
+    # Converts parameters being sent to Facebook from ruby objects to the
+    # appropriate text representation
+    #
+    def convert_outgoing_params(params)
+      json_encoder = Yajl::Encoder.new
+      params.each do |key, value|
+        params.delete(key) if value.nil?
+
+        case value
+        when Array, Hash
+          params[key] = json_encoder.encode(value)
+        when Time
+          params[key] = value.to_i.to_s
+        when TrueClass
+          params[key] = '1'
+        when FalseClass
+          params[key] = '0'
+        end
+      end
+
+      params
+    end
+
     # Get the signed parameters that were sent from Facebook. Validates the set
     # of parameters against the included signature.
     #
@@ -115,7 +264,7 @@ module FacebookRb
     #   the subset of parameters containing the given prefix, and also matching
     #   the signature associated with them, or nil if the params do not validate
     #
-    def get_valid_fb_params(params,  namespace='fb_sig')
+    def get_params_from(params,  namespace='fb_sig')
       prefix = "#{namespace}_"
       fb_params = Hash.new
       params.each do |key, value|
@@ -124,23 +273,12 @@ module FacebookRb
         end
       end
       
-      signature = params[namespace]
-      return fb_params if signature && valid_signature?(fb_params, signature)
+      param_sig = params[namespace]
+      gen_sig = generate_signature(fb_params, self.secret)
+      return fb_params if param_sig == gen_sig
       nil
     end
 
-    # Validates that a given set of parameters match their signature.
-    # Parameters all match a given input prefix, such as "fb_sig".
-    #
-    # Parameters:
-    #   fb_params     an array of all Facebook-sent parameters, not 
-    #                 including the signature itself
-    #   expected_sig  the expected result to check against
-    #
-    def valid_signature?(fb_params, expected_sig)
-      expected_sig == generate_signature(fb_params, self.secret)
-    end
-    
     # Generate a signature using the application secret key.
     #
     # The only two entities that know your secret key are you and Facebook,
@@ -157,17 +295,38 @@ module FacebookRb
     #   a md5 hash to be checked against the signature provided by Facebook
     #
     def generate_signature(fb_params, secret)
-      #Convert any symbol keys to strings
-      #otherwise sort() bombs
-      fb_params.each_key do |key|
-        fb_params[key.to_s] = fb_params.delete(key) if key.is_a?(Symbol)
+      str = fb_params.map { |k,v| "#{k}=#{v}" }.sort.join 
+      Digest::MD5.hexdigest("#{str}#{secret}")
+    end
+
+    #
+    # Allows making calls like `client.users.getInfo`
+    #
+    class APIProxy
+      TYPES = %w[ admin application auth comments connect data events
+        fbml feed fql friends groups links liveMessage notes notifications
+        pages photos profile sms status stream users video ]
+
+      alias :__class__ :class
+      alias :__inspect__ :inspect
+      instance_methods.each { |m| undef_method m unless m =~ /^(__|object_id)/ }
+      alias :inspect :__inspect__
+
+      def initialize name, obj
+        @name, @obj = name, obj
       end
 
-      str = String.new
-      fb_params.sort.each do |key, value|
-        str << "#{key.to_s}=#{value}"
+      def method_missing method, opts = {}
+        @obj.call "#{@name}.#{method}", opts
       end
-      Digest::MD5.hexdigest("#{str}#{secret}")
+    end
+
+    APIProxy::TYPES.each do |n|
+      class_eval %[
+        def #{n}
+          (@proxies||={})[:#{n}] ||= APIProxy.new(:#{n}, self)
+        end
+      ]
     end
   end
 
@@ -189,19 +348,13 @@ module FacebookRb
     end
     
     def call(env)
-      request = Rack::Request.new(env)
-      
-      client = Client.new(@options[:api_key], @options[:secret])
+      fb = Client.new(@options)
+      fb.extract_params(env)
 
-      if fb_params = client.get_valid_fb_params(request.params, 'fb_sig')
-        #env["facebook.original_method"] = env["REQUEST_METHOD"]
-        #env["REQUEST_METHOD"] = fb_params['request_method']
-      else
-        fb_params = client.get_valid_fb_params(request.cookies, @options[:api_key])
-      end
-      client.fb_params = fb_params
-      env['facebook.params'] = fb_params
-      env['facebook.client'] = client
+      env['facebook.client'] = fb
+
+      #env["facebook.original_method"] = env["REQUEST_METHOD"]
+      #env["REQUEST_METHOD"] = fb_params['request_method']
 
       return @app.call(env)
     end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: facebookrb
 version: !ruby/object:Gem::Version 
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors: 
 - John Mendonca
@@ -9,7 +9,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-01-18 00:00:00 -08:00
+date: 2010-02-05 00:00:00 -08:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -22,16 +22,6 @@ dependencies:
       - !ruby/object:Gem::Version 
         version: "0"
     version: 
-- !ruby/object:Gem::Dependency 
-  name: rspec
-  type: :development
-  version_requirement: 
-  version_requirements: !ruby/object:Gem::Requirement 
-    requirements: 
-    - - ">="
-      - !ruby/object:Gem::Version 
-        version: "0"
-    version: 
 description: 
 email: joaosinho@gmail.com
 executables: []