facebooker 0.9.5

data/lib/facebooker/rails/routing.rb

@@ -0,0 +1,49 @@
+module Facebooker
+  module Rails
+    module Routing
+      module RouteSetExtensions
+        def self.included(base)
+          base.alias_method_chain :extract_request_environment, :facebooker
+        end
+
+        def extract_request_environment_with_facebooker(request)
+          env = extract_request_environment_without_facebooker(request)
+          env.merge :canvas => (request.parameters[:fb_sig_in_canvas]=="1")
+        end
+      end
+      module MapperExtensions
+
+        # Generates pseudo-resource routes. Since everything is a POST, routes can't be identified
+        # using HTTP verbs. Therefore, the action is appended to the beginning of each named route,
+        # except for index.
+        #
+        # Example: 
+        #   map.facebook_resources :profiles
+        #
+        # Generates the following routes:
+        #
+        #     new_profile POST /profiles/new         {:controller=>"profiles", :action=>"new"}
+        #        profiles POST /profiles/index       {:controller=>"profiles", :action=>"index"}
+        #    show_profile POST /profiles/:id/show    {:controller=>"profiles", :action=>"show"}
+        #  create_profile POST /profiles/create      {:controller=>"profiles", :action=>"create"}
+        #    edit_profile POST /profiles/:id/edit    {:controller=>"profiles", :action=>"edit"}
+        #  update_profile POST /profiles/:id/update  {:controller=>"profiles", :action=>"update"}
+        # destroy_profile POST /profiles/:id/destroy {:controller=>"profiles", :action=>"destroy"}
+        #
+        def facebook_resources(name_sym)
+          name = name_sym.to_s
+
+          with_options :controller => name, :conditions => { :method => :post } do |map|
+            map.named_route("new_#{name.singularize}",     "#{name}/new",         :action => 'new')
+            map.named_route(name,                          "#{name}/index",       :action => 'index')
+            map.named_route("show_#{name.singularize}",    "#{name}/:id/show",    :action => 'show',    :id => /\d+/)
+            map.named_route("create_#{name.singularize}",  "#{name}/create",      :action => 'create')
+            map.named_route("edit_#{name.singularize}",    "#{name}/:id/edit",    :action => 'edit',    :id => /\d+/)
+            map.named_route("update_#{name.singularize}",  "#{name}/:id/update",  :action => 'update',  :id => /\d+/)
+            map.named_route("destroy_#{name.singularize}", "#{name}/:id/destroy", :action => 'destroy', :id => /\d+/)            
+          end
+        end
+      end
+    end
+  end      
+end

data/lib/facebooker/rails/test_helpers.rb

@@ -0,0 +1,11 @@
+module Facebooker
+  module Rails
+    module TestHelpers
+      def assert_fb_redirect_to(url)
+        assert_equal "fb:redirect", response_from_page_or_rjs.children.first.name
+        assert_equal url, response_from_page_or_rjs.children.first.attributes['url']    
+      end
+    end
+  end
+end
+        

data/lib/facebooker/rails/utilities.rb

@@ -0,0 +1,22 @@
+module Facebooker
+  module Rails
+    class Utilities
+      class << self
+        def refresh_all_images(session)
+          Dir.glob(File.join(RAILS_ROOT,"public","images","*.{png,jpg,gif}")).each do |img|
+            refresh_image(session,img)
+          end
+        end
+        
+        def refresh_image(session,full_path)
+          basename=File.basename(full_path)
+          base_path=ActionController::Base.asset_host
+          base_path += "/" unless base_path.ends_with?("/")
+          image_path=base_path+"images/#{basename}"
+          puts "refreshing: #{image_path}"
+          session.server_cache.refresh_img_src(image_path)
+        end
+      end
+    end
+  end
+end

data/lib/facebooker/server_cache.rb

@@ -0,0 +1,24 @@
+module Facebooker
+  class ServerCache
+    def initialize(session)
+      @session = session
+    end
+    
+    # 
+    # Stores an FBML reference on the server for use 
+    # across multiple users in FBML
+    def set_ref_handle(handle_name, fbml_source)
+      (@session.post 'facebook.fbml.setRefHandle', :handle => handle_name, :fbml => fbml_source) == '1'
+    end
+    
+    ##
+    # Fetches and re-caches the content stored at the given URL, for use in a fb:ref FBML tag.
+    def refresh_ref_url(url)
+      (@session.post 'facebook.fbml.refreshRefUrl', :url => url) == '1'
+    end
+    
+    def refresh_img_src(url)
+      (@session.post 'facebook.fbml.refreshImgSrc', :url => url) == '1'
+    end
+  end
+end

data/lib/facebooker/service.rb

@@ -0,0 +1,25 @@
+require 'net/http'
+require 'facebooker/parser'
+module Facebooker
+  class Service
+    def initialize(api_base, api_path, api_key)
+      @api_base = api_base
+      @api_path = api_path
+      @api_key = api_key
+    end
+    
+   # TODO: support ssl 
+   def post(params)
+      Parser.parse(params[:method], Net::HTTP.post_form(url, params))
+    end
+    
+    def post_file(params)
+      Parser.parse(params[:method], Net::HTTP.post_multipart_form(url, params))
+    end
+    
+    private
+      def url
+        URI.parse('http://'+ @api_base + @api_path)      
+      end
+  end
+end

data/lib/facebooker/session.rb

@@ -0,0 +1,385 @@
+require 'digest/md5'
+require 'cgi'
+
+module Facebooker
+  #
+  # Raised when trying to perform an operation on a user
+  # other than the logged in user (if that's unallowed)
+  class NonSessionUser < StandardError;  end
+  class Session
+    class SessionExpired < StandardError; end
+    class UnknownError < StandardError; end
+    class ServiceUnavailable < StandardError; end
+    class MaxRequestsDepleted < StandardError; end
+    class HostNotAllowed < StandardError; end
+    class MissingOrInvalidParameter < StandardError; end
+    class InvalidAPIKey < StandardError; end
+    class SessionExpired < StandardError; end
+    class CallOutOfOrder < StandardError; end
+    class IncorrectSignature     < StandardError; end
+    class SignatureTooOld     < StandardError; end
+    class TooManyUserCalls < StandardError; end
+    class TooManyUserActionCalls < StandardError; end
+    class InvalidFeedTitleLink < StandardError; end
+    class InvalidFeedTitleLength < StandardError; end
+    class InvalidFeedTitleName < StandardError; end
+    class BlankFeedTitle < StandardError; end
+    class FeedBodyLengthTooLong < StandardError; end
+    class InvalidFeedPhotoSource < StandardError; end
+    class InvalidFeedPhotoLink < StandardError; end    
+    class FeedMarkupInvalid < StandardError; end
+    class FeedTitleDataInvalid < StandardError; end
+    class FeedTitleTemplateInvalid < StandardError; end
+    class FeedBodyDataInvalid < StandardError; end
+    class FeedBodyTemplateInvalid < StandardError; end
+    class FeedPhotosNotRetrieved < StandardError; end
+    class FeedTargetIdsInvalid < StandardError; end
+    class ConfigurationMissing < StandardError; end
+    class FQLParseError < StandardError; end
+    class FQLFieldDoesNotExist < StandardError; end
+    class FQLTableDoesNotExist < StandardError; end
+    class FQLStatementNotIndexable < StandardError; end
+    class FQLFunctionDoesNotExist < StandardError; end
+    class FQLWrongNumberArgumentsPassedToFunction < StandardError; end
+    class InvalidAlbumId < StandardError; end
+    class AlbumIsFull < StandardError; end
+    class MissingOrInvalidImageFile < StandardError; end
+    class TooManyUnapprovedPhotosPending < StandardError; end
+  
+    API_SERVER_BASE_URL       = "api.facebook.com"
+    API_PATH_REST             = "/restserver.php"
+    WWW_SERVER_BASE_URL       = "www.facebook.com"
+    WWW_PATH_LOGIN            = "/login.php"
+    WWW_PATH_ADD              = "/add.php"
+    WWW_PATH_INSTALL          = "/install.php"
+    
+    attr_writer :auth_token
+    attr_reader :session_key
+          
+    def self.create(api_key=nil, secret_key=nil)
+      api_key ||= self.api_key
+      secret_key ||= self.secret_key
+      raise ArgumentError unless !api_key.nil? && !secret_key.nil?
+      new(api_key, secret_key)
+    end
+    
+    def self.api_key
+      extract_key_from_environment(:api) || extract_key_from_configuration_file(:api) rescue report_inability_to_find_key(:api)
+    end
+    
+    def self.secret_key
+      extract_key_from_environment(:secret) || extract_key_from_configuration_file(:secret) rescue report_inability_to_find_key(:secret)
+    end
+    
+    def self.current
+      @current_session
+    end
+    
+    def self.current=(session)
+      @current_session=session
+    end
+    
+    def login_url(options={})
+      options = default_login_url_options.merge(options)
+      "http://www.facebook.com/login.php?api_key=#{@api_key}&v=1.0#{login_url_optional_parameters(options)}"
+    end
+
+    def install_url(options={})
+      "http://www.facebook.com/install.php?api_key=#{@api_key}&v=1.0#{install_url_optional_parameters(options)}"
+    end
+
+    def install_url_optional_parameters(options)
+      optional_parameters = []
+      optional_parameters << "&next=#{CGI.escape(options[:next])}" if options[:next]
+      optional_parameters.join
+    end
+
+    def login_url_optional_parameters(options)
+      # It is important that unused options are omitted as stuff like &canvas=false will still display the canvas. 
+      optional_parameters = []
+      optional_parameters << "&next=#{CGI.escape(options[:next])}" if options[:next]
+      optional_parameters << "&skipcookie=true" if options[:skip_cookie]
+      optional_parameters << "&hide_checkbox=true" if options[:hide_checkbox]
+      optional_parameters << "&canvas=true" if options[:canvas]
+      optional_parameters.join
+    end
+  
+    def default_login_url_options
+      {}
+    end
+    
+    def initialize(api_key, secret_key)
+      @api_key = api_key
+      @secret_key = secret_key
+    end
+    
+    def secret_for_method(method_name)
+      @secret_key
+    end
+      
+    def auth_token
+      @auth_token ||= post 'facebook.auth.createToken'
+    end
+    
+    def infinite?
+      @expires == 0
+    end
+    
+    def expired?
+      @expires.nil? || (!infinite? && Time.at(@expires) <= Time.now)
+    end
+    
+    def secured?
+      !@session_key.nil? && !expired?
+    end
+    
+    def secure!
+      response = post 'facebook.auth.getSession', :auth_token => auth_token
+      secure_with!(response['session_key'], response['uid'], response['expires'], response['secret'])
+    end    
+    
+    def secure_with!(session_key, uid, expires, secret_from_session = nil)
+      @session_key = session_key
+      @uid = Integer(uid)
+      @expires = Integer(expires)
+      @secret_from_session = secret_from_session
+    end
+    
+    def fql_query(query, format = 'XML')
+      response = post('facebook.fql.query', :query => query, :format => format)
+      type = response.shift
+      response.shift.map do |hash|
+        case type
+        when 'user'
+          user = User.new
+          user.session = self
+          user.populate_from_hash!(hash)
+          user
+        when 'photo'
+          Photo.from_hash(hash)
+        when 'event_member'
+          Event::Attendance.from_hash(hash)
+        end
+      end        
+    end
+    
+    def user
+      @user ||= User.new(uid, self)
+    end
+    
+    #
+    # This one has so many parameters, a Hash seemed cleaner than a long param list.  Options can be:
+    # :uid => Filter by events associated with a user with this uid
+    # :eids => Filter by this list of event ids. This is a comma-separated list of eids.
+    # :start_time => Filter with this UTC as lower bound. A missing or zero parameter indicates no lower bound. (Time or Integer)
+    # :end_time => Filter with this UTC as upper bound. A missing or zero parameter indicates no upper bound. (Time or Integer)
+    # :rsvp_status => Filter by this RSVP status.
+    def events(options = {})
+      @events ||= post('facebook.events.get', options).map do |hash|
+        Event.from_hash(hash)
+      end
+    end
+    
+    def event_members(eid)
+      @members ||= post('facebook.events.getMembers', :eid => eid).map do |attendee_hash|
+        Event::Attendance.from_hash(attendee_hash)
+      end
+    end
+    
+    
+    #
+    # Returns a proxy object for handling calls to Facebook cached items
+    # such as images and FBML ref handles
+    def server_cache
+      Facebooker::ServerCache.new(self)
+    end
+    
+    #
+    # Returns a proxy object for handling calls to the Facebook Data API
+    def data
+      Facebooker::Data.new(self)
+    end
+    
+    #
+    # Given an array like:
+    # [[userid, otheruserid], [yetanotherid, andanotherid]]
+    # returns a Hash indicating friendship of those pairs:
+    # {[userid, otheruserid] => true, [yetanotherid, andanotherid] => false}
+    # if one of the Hash values is nil, it means the facebook platform's answer is "I don't know"
+    def check_friendship(array_of_pairs_of_users)
+      uids1 = []
+      uids2 = []
+      array_of_pairs_of_users.each do |pair|
+        uids1 = pair.first
+        uids2 = pair.last
+      end
+      post('facebook.friends.areFriends', :uids1 => uids1, :uids2 => uids2)
+    end
+    
+    def get_photos(pids = nil, subj_id = nil,  aid = nil)
+      if [subj_id, pids, aid].all? {|arg| arg.nil?}
+        raise ArgumentError, "Can't get a photo without a picture, album or subject ID" 
+      end
+      @photos = post('facebook.photos.get', :subj_id => subj_id, :pids => pids, :aid => aid ).map do |hash|
+        Photo.from_hash(hash)
+      end
+    end
+    
+    def get_albums(aids)
+      @albums = post('facebook.photos.getAlbums', :aids => aids).map do |hash|        
+        Album.from_hash(hash)
+      end
+    end
+    
+    def get_tags(pids)
+      @tags = post('facebook.photos.getTags', :pids => pids).map do |hash|
+        Tag.from_hash(hash)
+      end
+    end
+    
+    def add_tags(pid, x, y, tag_uid = nil, tag_text = nil )
+      if [tag_uid, tag_text].all? {|arg| arg.nil?}
+        raise ArgumentError, "Must enter a name or string for this tag"        
+      end
+      @tags = post('facebook.photos.addTag', :pid => pid, :tag_uid => tag_uid, :tag_text => tag_text, :x => x, :y => y )
+    end
+    
+    def send_notification(user_ids, fbml, email_fbml = nil)
+      params = {:notification => fbml, :to_ids => user_ids.map{ |id| User.cast_to_facebook_id(id)}.join(',')}
+      if email_fbml
+        params[:email] = email_fbml
+      end
+      post 'facebook.notifications.send', params
+    end 
+
+    ##
+    # Send email to as many as 100 users at a time
+	  def send_email(user_ids, subject, text, fbml = nil) 			
+		  user_ids = Array(user_ids)
+      params = {:fbml => fbml, :recipients => user_ids.map{ |id| User.cast_to_facebook_id(id)}.join(','), :text => text, :subject => subject} 
+      post 'facebook.notifications.sendEmail', params
+    end
+
+    # Only serialize the bare minimum to recreate the session.
+    def marshal_load(variables)#:nodoc:
+      fields_to_serialize.each_with_index{|field, index| instance_variable_set_value(field, variables[index])}
+    end
+    
+    # Only serialize the bare minimum to recreate the session.    
+    def marshal_dump#:nodoc:
+      fields_to_serialize.map{|field| instance_variable_value(field)}
+    end
+    
+    # Only serialize the bare minimum to recreate the session. 
+    def to_yaml( opts = {} )
+      YAML::quick_emit(self.object_id, opts) do |out|
+        out.map(taguri) do |map|
+          fields_to_serialize.each do |field|
+            map.add(field, instance_variable_value(field))
+          end
+        end
+      end
+    end
+    
+    def instance_variable_set_value(field, value)
+      self.instance_variable_set("@#{field}", value)
+    end
+    
+    def instance_variable_value(field)
+      self.instance_variable_get("@#{field}")
+    end
+    
+    def fields_to_serialize
+      %w(session_key uid expires secret_from_session auth_token api_key secret_key)
+    end
+    
+    class Desktop < Session
+      def login_url
+        super + "&auth_token=#{auth_token}"
+      end
+
+      def secret_for_method(method_name)
+        secret = auth_request_methods.include?(method_name) ? super : @secret_from_session
+        secret
+      end
+      
+      def post(method, params = {})
+        if method == 'facebook.profile.getFBML' || method == 'facebook.profile.setFBML'
+          raise NonSessionUser.new("User #{@uid} is not the logged in user.") unless @uid == params[:uid]
+        end
+        super
+      end
+      private
+        def auth_request_methods
+          ['facebook.auth.getSession', 'facebook.auth.createToken']
+        end
+    end
+    
+    def post(method, params = {})
+      add_facebook_params(params, method)
+      @session_key && params[:session_key] ||= @session_key
+      service.post(params.merge(:sig => signature_for(params)))      
+    end
+    
+    def post_file(method, params = {})
+      add_facebook_params(params, method)
+      @session_key && params[:session_key] ||= @session_key
+      service.post_file(params.merge(:sig => signature_for(params.reject{|key, value| key.nil?})))
+    end
+    
+    
+    def self.configuration_file_path
+      @configuration_file_path || File.expand_path("~/.facebookerrc")
+    end
+    
+    def self.configuration_file_path=(path)
+      @configuration_file_path = path
+    end
+    
+    private
+      def add_facebook_params(hash, method)
+        hash[:method] = method
+        hash[:api_key] = @api_key
+        hash[:call_id] = Time.now.to_f.to_s unless method == 'facebook.auth.getSession'
+        hash[:v] = "1.0"
+      end
+    
+      def self.extract_key_from_environment(key_name)
+        val = ENV["FACEBOOK_" + key_name.to_s.upcase + "_KEY"]
+      end
+    
+      def self.extract_key_from_configuration_file(key_name)
+        read_configuration_file[key_name]
+      end
+    
+      def self.report_inability_to_find_key(key_name)
+        raise ConfigurationMissing, "Could not find configuration information for #{key_name}"
+      end
+    
+      def self.read_configuration_file
+        eval(File.read(configuration_file_path))
+      end
+    
+      def service
+        @service ||= Service.new(API_SERVER_BASE_URL, API_PATH_REST, @api_key)      
+      end
+    
+      def uid
+        @uid || (secure!; @uid)
+      end
+      
+      def signature_for(params)
+        raw_string = params.inject([]) do |collection, pair|
+          collection << pair.join("=")
+          collection
+        end.sort.join
+        Digest::MD5.hexdigest([raw_string, secret_for_method(params[:method])].join)
+      end        
+  end
+  
+  class CanvasSession < Session
+    def default_login_url_options
+      {:canvas => true}
+    end
+  end
+end