rfacebook 0.5.0

data/README

@@ -0,0 +1,76 @@
+============================== IMPORTANT NOTES ==============================
+
+
+** THIS IS ESPECIALLY IMPORTANT FOR PEOPLE WHO USED THE OLD CLIENT WHEN IT WAS CALLED "RBook" **
+
+[1] The RBook name was already taken, so now you need to change any "RBook" references to "RFacebook"
+
+[2] The desktop app login process is much simpler now:
+
+	fbsession = RFacebook::FacebookDesktopSession.new(APIKEY, APISECRET)
+	puts fbsession.get_login_url # tell the user to login at this url
+	# ...after the user logs in...
+	fbsession.activate
+
+[3] The "init_with_token" method is now "activate_with_token" (it is a little less confusing with this naming)
+
+[4] A helpful "NotActivatedException" will be raised if you forget to activate your session in one of the following ways:
+
+		Web: you must call either "activate_with_token" or "activate_with_previous_session"
+		Desktop: you must call either "activate" or "activate_with_previous_session"
+
+[5] Infinite sessions are now supported (web and desktop)...
+
+		Web:
+		
+			(a) Save the session key to a file or something
+				(i.e. "keyToSave = fbsession.session_key")
+				
+			(b) Normally, you would redirect the user to "get_login_url" and then call "activate_with_token" after the callback.
+				With an infinite session, skip these two steps and call "fbsession.activate_with_previous_session(keyToSave)" instead.
+		
+		Desktop:
+		
+			(a) Save the session key and session secret to a file or something
+				(i.e. "keyToSave = fbsession.session_key" and "secretToSave = fbsession.session_secret")
+			
+			(b) Normally, you would redirect the user to "get_login_url" and then call "activate".
+				With an infinite session, skip these two steps and call "fbsession.activate_with_previous_session(keyToSave, secretToSave)" instead.
+
+
+
+============================== LICENSE ==============================
+
+Copyright (c) 2007, Matt Pizzimenti (www.livelearncode.com)
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+Redistributions of source code must retain the above copyright notice,
+this list of conditions and the following disclaimer.
+
+Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation
+and/or other materials provided with the distribution.
+
+Neither the name of the original author nor the names of contributors
+may be used to endorse or promote products derived from this software
+without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+
+
+Some code was inspired by techniques used in Alpha Chen's old client.
+Some code was ported from the official PHP5 client.
+

data/lib/facebook_desktop_session.rb

@@ -0,0 +1,152 @@
+# Copyright (c) 2007, Matt Pizzimenti (www.livelearncode.com)
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+# 
+# Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer.
+# 
+# Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+# 
+# Neither the name of the original author nor the names of contributors
+# may be used to endorse or promote products derived from this software
+# without specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+
+#
+# Some code was inspired by techniques used in Alpha Chen's old client.
+# Some code was ported from the official PHP5 client.
+#
+
+require "facebook_session"
+
+module RFacebook
+
+class FacebookDesktopSession < FacebookSession
+  
+  # you'll need to access session_secret (in addition to the session_key) to be able to
+  # call "activate_with_previous_session" when using infinite sessions
+  attr_reader :session_secret
+  
+  # Function: get_login_url
+  #   Gets the authentication URL
+  #
+  # Parameters:
+  #   options.next          - the page to redirect to after login
+  #   options.popup         - boolean, whether or not to use the popup style (defaults to true)
+  #   options.skipcookie    - boolean, whether to force new Facebook login (defaults to false)
+  #   options.hidecheckbox  - boolean, whether to show the "infinite session" option checkbox
+  def get_login_url(options={})
+    # options
+    path_next = options[:next] ||= nil
+    popup = (options[:popup] == nil) ? true : false
+    skipcookie = (options[:skipcookie] == nil) ? false : true
+    
+    # get some extra portions of the URL
+    optionalNext = (path_next == nil) ? "" : "&next=#{CGI.escape(path_next.to_s)}"
+    optionalPopup = (popup == true) ? "&popup=true" : ""
+    optionalSkipCookie = (skipcookie == true) ? "&skipcookie=true" : ""
+    optionalHideCheckbox = (hidecheckbox == true) ? "&hide_checkbox=true" : ""
+    
+    # build and return URL
+    return "http://#{LOGIN_SERVER_BASE_URL}#{LOGIN_SERVER_PATH}?v=1.0&api_key=#{@api_key}&auth_token=#{@desktop_auth_token}#{optionalPopup}#{optionalNext}#{optionalSkipCookie}#{optionalHideCheckbox}"
+  end
+  
+  
+  # Function: initialize
+  #   Constructs a FacebookSession
+  #
+  # Parameters:
+  #   api_key                       - your API key
+  #   api_secret                    - your API secret
+  #   desktop                       - boolean, whether this is a desktop client or not (defaults to false)
+  #   options.suppress_exceptions   - boolean, set to true if you don't want exceptions to be thrown (defaults to false)
+  def initialize(api_key, api_secret, suppress_exceptions = false)
+    super(api_key, api_secret, suppress_exceptions)
+    @desktop_auth_token = get_auth_token
+  end
+  
+  def activate
+    activate_with_token(@desktop_auth_token)
+  end
+  
+  # Function: activate_with_previous_session
+  #   Sets the session key and secret directly (for example, if you have an infinite session key)
+  # 
+  # Parameters:
+  #   key    - the session key to use
+  def activate_with_previous_session(key, secret)
+    # set the session key and secret
+    @session_key = key
+    @session_secret = secret
+    
+    # determine the current user's id
+    result = call_method("users.getLoggedInUser")
+    @session_uid = result.at("users_getLoggedInUser_response").inner_html
+  end
+  
+  def is_valid?
+    return (is_activated? and !session_expired?)
+  end
+  
+  protected
+  
+  def is_activated?
+    return (@session_key != nil and @session_secret != nil)
+  end
+  
+  # Function: activate_with_token
+  #   Gets the session information available after current user logs in.
+  # 
+  # Parameters:
+  #   auth_token    - string token returned by auth.createToken (see: <get_auth_token>)
+  def activate_with_token(auth_token)
+    result = call_method("auth.getSession", {:auth_token => auth_token}, true)
+    if result != nil
+      @session_uid = result.at("uid").inner_html
+      @session_key = result.at("session_key").inner_html
+      @session_secret = result.at("secret").inner_html
+    end
+    return result
+  end
+  
+  # Function: auth_createToken
+  #   Returns a string auth_token
+  def get_auth_token
+    result = call_method("auth.createToken", {})
+    result = result.at("auth_createtoken_response").inner_html.to_s ||= result.at("auth_createToken_response").inner_html.to_s
+    return result
+  end
+  
+  # Function: get_secret
+  #   Template method, used by super::signature to generate a signature
+  def get_secret(params)
+    
+    if ( params[:method] != "facebook.auth.getSession" and params[:method] != "facebook.auth.createToken")
+      return @session_secret
+    else
+      return @api_secret
+    end
+    
+  end
+  
+end
+
+
+
+end
+    

data/lib/facebook_session.rb

@@ -0,0 +1,245 @@
+# Copyright (c) 2007, Matt Pizzimenti (www.livelearncode.com)
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+# 
+# Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer.
+# 
+# Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+# 
+# Neither the name of the original author nor the names of contributors
+# may be used to endorse or promote products derived from this software
+# without specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+
+#
+# Some code was inspired by techniques used in Alpha Chen's old client.
+# Some code was ported from the official PHP5 client.
+#
+
+require "digest/md5"
+require "net/https"
+require "cgi"
+require "hpricot"
+
+module RFacebook
+
+API_SERVER_BASE_URL      = "api.facebook.com"
+LOGIN_SERVER_BASE_URL    = "www.facebook.com"
+API_SERVER_PATH          = "/restserver.php"
+LOGIN_SERVER_PATH        = "/login.php"
+
+class FacebookSession
+  
+  attr_reader :session_uid, :session_key
+  attr_reader :last_call_was_successful, :last_error
+  attr_writer :suppress_exceptions
+  
+  # SECTION: Exceptions
+    
+  class RemoteException < Exception; end
+  class ExpiredSessionException < Exception; end
+  class NotActivatedException < Exception; end
+  
+  # SECTION: Public Methods  
+  
+  # Function: initialize
+  #   Constructs a FacebookSession
+  #
+  # Parameters:
+  #   api_key                       - your API key
+  #   api_secret                    - your API secret
+  #   suppress_exceptions           - boolean, set to true if you don't want exceptions to be thrown (defaults to false)
+  def initialize(api_key, api_secret, suppress_exceptions = false)
+    
+    # required parameters
+    @api_key = api_key
+    @api_secret = api_secret
+    
+    # calculated parameters
+    @api_server_base_url = API_SERVER_BASE_URL
+    @api_server_path = API_SERVER_PATH
+        
+    # optional parameters
+    @suppress_exceptions = suppress_exceptions
+    
+    # initialize internal state
+    @last_call_was_successful = true
+    @last_error = nil
+    @session_expired = false
+    
+    # virtual members (subclasses will set these)
+    @session_uid = nil
+    @session_key = nil
+    
+  end
+  
+  def session_expired?
+    return (@session_expired == true)
+  end
+    
+  protected
+  
+  # SECTION: Protected Abstract Interface
+  
+  def get_secret(params)
+    raise Exception
+  end
+  
+  def init_with_token(auth_token)
+    raise Exception
+  end
+  
+  def session_key=(key)
+    raise Exception
+  end
+  
+  def is_activated?
+    raise Exception
+  end
+  
+  def is_valid?
+    raise Exception
+  end
+  
+  # SECTION: Protected Concrete Interface
+  
+  # Function: method_missing
+  #   This allows *any* Facebook method to be called, using the Ruby
+  #   mechanism for responding to unimplemented methods.  Basically,
+  #   this converts a call to "auth_getSession" to "auth.getSession"
+  #   and does the proper API call using the parameter hash given.  
+  def method_missing(methodSymbol, *params)
+    methodString = methodSymbol.to_s.gsub!("_", ".")
+    # TODO: check here for valid method names
+    call_method(methodString, params.first)
+  end
+
+  
+  # Function: call_method
+  #   Sets up the necessary parameters to make the POST request to the server
+  #
+  # Parameters:
+  #   method              - i.e. "users.getInfo"
+  #   params              - hash of key,value pairs for the parameters to this method
+  #   use_ssl             - set to true if the call will be made over SSL
+  def call_method(method, params={}, use_ssl=false)
+    
+    # ensure that this object has been activated somehow
+    if (!method.include?("auth") and !is_activated?)
+      raise NotActivatedException, "You must activate the session before using it."
+    end
+    
+    # set up params hash
+    params = params ||= {}
+    params[:method] = "facebook.#{method}"
+    params[:api_key] = @api_key
+    params[:v] = "1.0"
+    
+    if (method != "auth.getSession" and method != "auth.createToken")
+      params[:session_key] = @session_key
+      params[:call_id] = Time.now.to_f.to_s
+    end
+    
+    # convert arrays to comma-separated lists
+    params.each{|k,v| params[k] = v.join(",") if v.is_a?(Array)}
+    
+    # set up the param_signature value in the params
+    params[:sig] = param_signature(params)
+    
+    # prepare internal state
+    @last_call_was_successful = true
+    #@last_error = nil
+    
+    # do the request
+    xmlstring = post_request(@api_server_base_url, @api_server_path, method, params, use_ssl)
+    xml = Hpricot(xmlstring)
+
+    # error checking    
+    if xml.at("error_response")
+      @last_call_was_successful = false
+      code = xml.at("error_code").inner_html
+      msg = xml.at("error_msg").inner_html
+      @last_error = "ERROR #{code}: #{msg} (#{method}, #{params})"
+      @last_error_code = code
+      
+      # check to see if this error was an expired session error
+      if code.to_i == 102
+        @session_expired = true
+        raise ExpiredSessionException, @last_error unless @suppress_exceptions == true
+      end
+      
+      # otherwise, just throw a generic expired session
+      raise RemoteException, @last_error unless @suppress_exceptions == true
+      
+      return nil
+    end
+    
+    return xml
+  end
+  
+  
+  private
+  
+  # SECTION: Private Concrete Interface
+  
+  # Function: post_request
+  #   Does a post to the given server/path, using the params as formdata
+  #
+  # Parameters:
+  #   api_server_base_url         - i.e. "api.facebook.com"
+  #   api_server_path             - i.e. "/restserver.php"
+  #   method                      - i.e. "facebook.users.getInfo"
+  #   params                      - hash of key/value pairs that get sent as form data to the server
+  #   use_ssl                     - set to true if you want to use SSL for this request
+  def post_request(api_server_base_url, api_server_path, method, params, use_ssl)
+    
+    # get a server handle
+    port = (use_ssl == true) ? 443 : 80
+    http_server = Net::HTTP.new(@api_server_base_url, port)
+    http_server.use_ssl = use_ssl
+    
+    # build a request
+    http_request = Net::HTTP::Post.new(@api_server_path)
+    http_request.form_data = params
+    response = http_server.start{|http| http.request(http_request)}.body
+    
+    # return the text of the body
+    return response
+    
+  end
+  
+  # Function: param_signature
+  #   Generates a param_signature for a call to the API, per the spec on Facebook
+  #   see: <http://developers.facebook.com/documentation.php?v=1.0&doc=auth>
+  def param_signature(params)
+    
+    args = []
+    params.each do |k,v|
+      args << "#{k}=#{v}"
+    end
+    sorted_array = args.sort
+    request_str = sorted_array.join("")
+    param_signature = Digest::MD5.hexdigest("#{request_str}#{get_secret(params)}") # uses Template method get_secret
+    return param_signature
+    
+  end
+
+end
+
+end

data/lib/facebook_web_session.rb

@@ -0,0 +1,114 @@
+# Copyright (c) 2007, Matt Pizzimenti (www.livelearncode.com)
+# All rights reserved.
+# 
+# Redistribution and use in source and binary forms, with or without modification,
+# are permitted provided that the following conditions are met:
+# 
+# Redistributions of source code must retain the above copyright notice,
+# this list of conditions and the following disclaimer.
+# 
+# Redistributions in binary form must reproduce the above copyright notice,
+# this list of conditions and the following disclaimer in the documentation
+# and/or other materials provided with the distribution.
+# 
+# Neither the name of the original author nor the names of contributors
+# may be used to endorse or promote products derived from this software
+# without specific prior written permission.
+# 
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+# DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+# SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+# CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+# OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+#
+
+#
+# Some code was inspired by techniques used in Alpha Chen's old client.
+# Some code was ported from the official PHP5 client.
+#
+
+require "facebook_session"
+
+module RFacebook
+
+class FacebookWebSession < FacebookSession
+  
+  # Function: get_login_url
+  #   Gets the authentication URL
+  #
+  # Parameters:
+  #   options.next          - the page to redirect to after login
+  #   options.popup         - boolean, whether or not to use the popup style (defaults to true)
+  #   options.skipcookie    - boolean, whether to force new Facebook login (defaults to false)
+  #   options.hidecheckbox  - boolean, whether to show the "infinite session" option checkbox
+  def get_login_url(options={})
+    # options
+    path_next = options[:next] ||= nil
+    popup = (options[:popup] == nil) ? true : false
+    skipcookie = (options[:skipcookie] == nil) ? false : true
+    
+    # get some extra portions of the URL
+    optionalNext = (path_next == nil) ? "" : "&next=#{CGI.escape(path_next.to_s)}"
+    optionalPopup = (popup == true) ? "&popup=true" : ""
+    optionalSkipCookie = (skipcookie == true) ? "&skipcookie=true" : ""
+    optionalHideCheckbox = (hidecheckbox == true) ? "&hide_checkbox=true" : ""
+    
+    # build and return URL
+    return "http://#{LOGIN_SERVER_BASE_URL}#{LOGIN_SERVER_PATH}?v=1.0&api_key=#{@api_key}#{optionalPopup}#{optionalNext}#{optionalSkipCookie}#{optionalHideCheckbox}"
+  end
+  
+  # Function: activate_with_token
+  #   Gets the session information available after current user logs in.
+  # 
+  # Parameters:
+  #   auth_token    - string token passed back by the callback URL
+  def activate_with_token(auth_token)
+    result = call_method("auth.getSession", {:auth_token => auth_token})
+    if result != nil
+      @session_uid = result.at("uid").inner_html
+      @session_key = result.at("session_key").inner_html
+    end
+  end
+  
+  # Function: activate_with_previous_session
+  #   Sets the session key directly (for example, if you have an infinite session key)
+  # 
+  # Parameters:
+  #   key    - the session key to use
+  def activate_with_previous_session(key)
+    # set the session key
+    @session_key = key
+    
+    # determine the current user's id
+    result = call_method("users.getLoggedInUser")
+    @session_uid = result.at("users_getLoggedInUser_response").inner_html
+  end
+  
+  def is_valid?
+    return (is_activated? and !session_expired?)
+  end
+
+  protected
+  
+  def is_activated?
+    return (@session_key != nil)
+  end
+  
+  # Function: get_secret
+  #   Template method, used by super::signature to generate a signature
+  def get_secret(params)
+    
+    return @api_secret
+    
+  end
+  
+end
+
+
+
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.9.0
+specification_version: 1
+name: rfacebook
+version: !ruby/object:Gem::Version 
+  version: 0.5.0
+date: 2007-05-08 00:00:00 -04:00
+summary: A Ruby interface to the Facebook API v1.0+
+require_paths: 
+- lib
+email: matt@livelearncode.com
+homepage: http://livelearncode.com/
+rubyforge_project: 
+description: 
+autorequire: rfacebook
+default_executable: 
+bindir: bin
+has_rdoc: false
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+post_install_message: 
+authors: 
+- Matt Pizzimenti
+files: 
+- lib/facebook_desktop_session.rb
+- lib/facebook_session.rb
+- lib/facebook_web_session.rb
+- README
+test_files: []
+
+rdoc_options: []
+
+extra_rdoc_files: 
+- README
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: hpricot
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Version::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: 0.4.0
+    version: