facebook_api 0.1.0

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Tekin Suleyman
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,62 @@
+= Facebook API
+
+A simple, lightweight Ruby library for accessing the Facebook REST API. Currently used in Facebook Connect applications,
+but could easily be extended for use in canvas applications.
+
+== Usage
+
+  require 'facebook_api'
+
+  FacebookApi.configure do |config|
+    config.api_key = '55e9919b8c017abe484c9fb336dffb90'
+    config.secret_key 'fc881eb66493e0b845a3528c018cdd56'
+    config.canvas_page_name = 'crowdfm_publisher'
+    config.callback_url =  'http://crowd.fm/'
+  end
+
+  session = FacebookApi::Session.new(session_key, uid)
+   
+  # Make REST API calls
+  response = session.call('Friends.get', :uid => '12345')
+  # Make calls with file attachments
+  response = session.call('Photos.upload', {:uid => '12345', :aid => '67890', :caption => 'your caption'}, File.new('/path/to/image.jpg))
+  # Make fql calls
+  response = session.call_fql('SELECT page_id FROM page_admin WHERE uid="12345"')
+
+Both FacebookApi::Session#call and FacebookApi::Session#call_fql will generally return a hash, parsed from the JSON returned
+by Facebook. However, for some API calls Facebook returns non-valid JSON, usually either 'true', 'false' or a string literal
+(e.g. '12345'). In these cases, the return value from #call and #call_fql will be either true, false or the string literal
+respectively.
+
+=== How to use in a Rails application
+
+With a couple of simple methods, you can make Facebook sessions available to you in your controllers and views:
+
+  class ApplicationController < ActionController::Base
+    # Requiring a valid facebook connect session for your controller actions with a before_filter:
+    before_filter :require_facebook_session, :except => [:login]
+    # Make the facebook_session available in your views by making it a helper_method:
+    helper_method :facebook_session
+
+    private
+
+    def facebook_session
+      @facebook_session ||= facebook_session_from_cookies
+    end
+
+    def facebook_session_from_cookies
+      if FacebookApi.verify_connect_cookies_signature(cookies)
+        FacebookApi::Session.new(cookies["#{FacebookApi.api_key}_session_key"], cookies["#{FacebookApi.api_key}_user"])
+      end
+    end
+
+    def require_facebook_session
+      unless facebook_session
+        redirect_to facebook_connect_path
+      end
+    end
+  end
+
+== Copyright
+
+Copyright (c) 2010 Tekin Suleyman. See LICENSE for details.

data/lib/facebook_api/session.rb

@@ -0,0 +1,112 @@
+module FacebookApi
+  # FacebookApi::Session is your window to the Facebook REST API. Once you have a 
+  # valid session, you can make API calls with #call and fql calls with #call_fql.
+  #
+  # Example usage:
+  #
+  #   session = FacebookApi::Session.new(session_key, uid)
+  #   
+  #   # Make REST API calls
+  #   response = session.call('Friends.get', :uid => '12345')
+  #   # Make calls with file attachments
+  #   response = session.call('Photos.upload', {:uid => '12345', :aid => '67890', :caption => 'your caption'}, File.new('/path/to/image.jpg))
+  #   # Make fql calls
+  #   response = session.call_fql('SELECT page_id FROM page_admin WHERE uid="12345"') 
+  #
+  # The response from an API #call will usually be a hash, converted from the JSON
+  # returned by Facebook. For some API calls however, Facebook returns literal
+  # values such as 'true', 'false' or an identifier (e.g. '12334234').
+  # In these cases, #call returns either true, false or the literal respectively.
+  #
+  class Session
+    attr_reader :session_key, :uid #:nodoc:
+    
+    # Initialise a FacebookApi::Session with a valid session key and uid.
+    def initialize(session_key, uid)
+      @session_key = session_key
+      @uid = uid
+    end
+
+    # Alias for the FacebookApi.logger.
+    def logger
+      FacebookApi.logger
+    end
+
+    # Makes a Facebook API REST call.
+    # If a file is specified, this will be included in the call, e.g. when calling Photos.upload.
+    # Example usage:
+    #
+    #   response = session.call('Friends.get', :uid => '12345')
+    #   response = session.call('Photos.upload', {:uid => '12345', :aid => '67890', :caption => 'your caption'}, File.new('/path/to/image.jpg))
+    #
+    # Returns the response from Facebook as either a hash, boolean or literal, depending on what Facebook returns.
+    # Raises FacebookApi::Error if Facebook returns with an error.
+    def call(method, params = {}, file = nil)
+      params[:method] = method
+      begin
+        params = prepare_params(params)
+        logger.debug "Sending request to facebook: #{params.inspect}"
+        params[nil] = file if file
+        response = RestClient.post(FacebookApi::REST_URL, params)
+      rescue SocketError => e
+        raise IOError.new("Cannot connect to facebook: #{e}")
+      end
+      logger.debug "Receiving response from facebook: \"#{response.body}\""
+      parse_facebook_json response
+    end
+
+    # Makes a Facebook API REST FQL call.
+    # Returns the response from Facebook as either a hash, boolean or literal, depending on what Facebook returns.
+    # Example:
+    #
+    #   response = session.call('SELECT page_id FROM page_admin WHERE uid="12345"') 
+    #
+    # Raises FacebookApi::Error if Facebook returns with an error.
+    def call_fql(query)
+      call('Fql.query', :query => query)
+    end
+
+    # Prepares passed in params ready for sending to Facebook with a REST call.
+    def prepare_params(params)
+      s_params = {}
+      params.each_pair {|k,v| s_params[k.to_s] = v }
+      s_params['api_key'] = FacebookApi.api_key
+      s_params['v'] = FacebookApi::API_VERSION
+      s_params['call_id'] = Time.now.to_f.to_s
+      s_params['format'] = 'JSON'
+      s_params['sig'] = FacebookApi.calculate_signature(s_params)
+      s_params
+    end
+
+    # Because Facebook does not always return valid JSON, we need to pre-parse it and catch
+    # the special cases.
+    # If the response is valid JSON, this returns the parsed response. Otherwise it catches
+    # "true", "false" and string letirals, returning true, false or the string respectively. 
+    # Raises Facebook::APIError if the response from Facebook is an error message.
+    def parse_facebook_json(response)
+      body = response.body
+      if looks_like_json? body
+        data = JSON.parse body
+        raise FacebookApi::Error.new(data['error_msg'], data['error_code']) if data.include?('error_msg')
+      else
+        data = parse_literal body
+      end
+      data
+    end
+
+    private 
+
+    def looks_like_json?(string)
+      # If it starts with a '[' or a '{', then it looks like JSON to me.
+      string =~ /^[\[\{]/
+    end
+
+    def parse_literal(string)
+      case string
+        when 'true' then true
+        when 'false' then false
+        else string
+      end
+    end
+  end
+end

data/lib/facebook_api.rb

@@ -0,0 +1,117 @@
+require 'logger'
+require 'digest/sha2'
+require 'rest_client'
+require 'json'
+
+require 'facebook_api/session'
+
+module FacebookApi
+  
+  class Configuration #:nodoc:
+    attr_accessor :api_key, :secret_key, :canvas_page_name, :callback_url
+  end
+
+  API_VERSION = '1.0' #:nodoc:
+  REST_URL = 'http://api.facebook.com/restserver.php' #:nodoc:
+
+  @logger = nil
+  @config = Configuration.new
+
+  # Returns the logger for Facebook calls.
+  # By default, this outputs to STDOUT.
+  def self.logger
+    unless @logger
+      @logger = ::Logger.new($stdout)
+      @logger.level = Logger::INFO
+    end
+    @logger
+  end
+
+  # Returns the api key. set this with #configure.
+  def self.api_key
+    config.api_key
+  end
+
+  # Returns the secret key. set this with #configure.
+  def self.secret_key
+    config.secret_key    
+  end
+
+  # Allows you to set your Facebook configuration for accessing the REST API:
+  #
+  #   FacebookApi.configure do |config|
+  #     config.api_key = 'YOUR_API_KEY'
+  #     config.secret_key = 'YOUR_SECRET_KEY'
+  #     config.canvas_page_name = 'YOUR_CANVAS_PAGE_NAME'
+  #     config.callback_url = 'YOUR_CALLBACK_URL'
+  #   end
+  def self.configure(&block)
+    yield @config
+  end
+
+  # Returns the current Facebook configuration. This gets set with #configure.
+  def self.config
+    @config
+  end
+
+  # Verifies the signature of parmaters sent by Facebook.
+  # Returns true if the signature is valid, false otherwise
+  # See the API docs here[http://wiki.developers.facebook.com/index.php/Verifying_The_Signature] for
+  # more details on how this is calculated.
+  def self.verify_facebook_params_signature(args)
+    signature = args.delete('fb_sig')
+    return false if signature.nil?
+
+    signed_args = Hash.new
+    args.each do |k, v|
+      if k =~ /^fb_sig_(.*)/
+        signed_args[$1] = v
+      end
+    end
+
+    signature == calculate_signature(signed_args)
+  end
+
+  # Verifies the signature in the cookies set by Facebook Connect checks out.
+  # Returns true if the signature is valid, false otherwise.
+  # See the API docs here[http://wiki.developers.facebook.com/index.php/Verifying_The_Signature#Signatures_and_Facebook_Connect_Sites] for
+  # more details on how this is calculated.
+  def self.verify_connect_cookies_signature(args)
+    signature = args.delete(api_key)
+    return false if signature.nil?
+
+    signed_args = Hash.new
+    args.each do |k, v|
+      if k =~ /^#{api_key}_(.*)/
+        signed_args[$1] = v
+      end
+    end
+    
+    signature == calculate_signature(signed_args)
+  end
+
+  # Calculates a signature, as described in the API docs here[http://wiki.developers.facebook.com/index.php/Verifying_The_Signature#Generating_the_Signature].
+  def self.calculate_signature(params)
+    params_string = params.sort.inject('') { |str, pair| str << pair[0] << '=' << pair[1] }
+    Digest::MD5.hexdigest(params_string + secret_key)
+  end
+
+  # Helper to convert <tt>ActiveSupport::TimeWithZone</tt> from local time to Pacific time.
+  # Use this when sending date/times to Facebook as Facebook expects times to be 
+  # sent as Pacific time converted to a Unix timestamp.
+  def self.convert_time(time)
+    if time.is_a?(ActiveSupport::TimeWithZone)
+      pacific_zone = ActiveSupport::TimeZone["Pacific Time (US & Canada)"]
+      pacific_zone.parse(time.strftime("%Y-%m-%d %H:%M:%S"))
+    else
+      time
+    end
+  end
+
+  # Raised if a Facebook API call fails and returns an error response.
+  class Error < StandardError
+    def initialize(error_msg, error_code = 1) #:nodoc:
+      super("FacebookApi::Error #{error_code}: #{error_msg}" )
+    end
+  end
+end

metadata

@@ -0,0 +1,127 @@
+--- !ruby/object:Gem::Specification 
+name: facebook_api
+version: !ruby/object:Gem::Version 
+  prerelease: false
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Tekin Suleyman
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2010-05-07 00:00:00 +01:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: rest-client
+  prerelease: false
+  requirement: &id001 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">"
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 1
+        - 4
+        - 2
+        version: 1.4.2
+  type: :runtime
+  version_requirements: *id001
+- !ruby/object:Gem::Dependency 
+  name: test-unit
+  prerelease: false
+  requirement: &id002 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id002
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  prerelease: false
+  requirement: &id003 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id003
+- !ruby/object:Gem::Dependency 
+  name: mocha
+  prerelease: false
+  requirement: &id004 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id004
+- !ruby/object:Gem::Dependency 
+  name: webmock
+  prerelease: false
+  requirement: &id005 !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        segments: 
+        - 0
+        version: "0"
+  type: :development
+  version_requirements: *id005
+description: 
+email: tekin@tekin.co.uk
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README.rdoc
+files: 
+- LICENSE
+- README.rdoc
+- lib/facebook_api/session.rb
+- lib/facebook_api.rb
+has_rdoc: true
+homepage: http://tekin.co.uk
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --main
+- README.rdoc
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.6
+signing_key: 
+specification_version: 3
+summary: A simple, lightweight Ruby library for accessing the Facebook API
+test_files: []
+