facebooker 0.9.5

data/lib/facebooker/cookie.rb

@@ -0,0 +1,10 @@
+require 'facebooker/model'
+module Facebooker
+  
+  ##
+  # A simple representation of a cookie.
+  class Cookie
+    include Model
+    attr_accessor :uid, :name, :value, :expires, :path
+  end
+end

data/lib/facebooker/data.rb

@@ -0,0 +1,38 @@
+module Facebooker
+  class Data
+    def initialize(session)
+      @session = session
+    end
+    
+    ##
+    # ** BETA ***
+    # Sets a cookie on Facebook
+    # +user+ The user for whom this cookie needs to be set.
+    # +name+ Name of the cookie
+    # +value+ Value of the cookie
+    # Optional:
+    # +expires+ Time when the cookie should expire. If not specified, the cookie never expires. 
+    # +path+ Path relative to the application's callback URL, with which the cookie should be associated. (default value is /?
+    def set_cookie(user, name, value, expires=nil, path=nil)
+      (@session.post 'facebook.data.setCookie', 
+        :uid => User.cast_to_facebook_id(user), 
+        :name => name, 
+        :value => value, 
+        :expires => expires, 
+        :path => path) == '1'
+    end
+    
+    ##
+    # ** BETA ***
+    # Gets a cookie stored on Facebook
+    # +user+	The user from whom to get the cookies.	
+    # Optional:   
+    # +name+ The name of the cookie. If not specified, all the cookies for the given user get returned.
+    def get_cookies(user, name=nil)
+      @cookies = @session.post( 
+        'facebook.data.getCookies', :uid => User.cast_to_facebook_id(user), :name => name).map do |hash|
+        Cookie.from_hash(hash)
+      end
+    end    
+  end
+end

data/lib/facebooker/education_info.rb

@@ -0,0 +1,11 @@
+module Facebooker
+  class EducationInfo
+    class HighschoolInfo
+      include Model
+      attr_accessor :hs1_id, :hs2_id, :grad_year, :hs1_name, :hs2_name
+    end
+    
+    include Model
+    attr_accessor :concentrations, :name, :year, :degree
+  end
+end

data/lib/facebooker/event.rb

@@ -0,0 +1,26 @@
+require 'facebooker/model'
+module Facebooker
+  class Event
+    
+    ##
+    # The relationship between a Facebook user and an Event to which he or she has been
+    # invited and may or may not be attending (based on #rsvp_status)
+    class Attendance
+      include Model
+      attr_accessor :eid, :uid, :rsvp_status
+      
+      ##
+      # Get the full, populated Event object which this Attendance is associated with.
+      # First access will query the Facebook API (facebook.events.get).  Subsequent
+      # calls are retrieved from in-memory cache.
+      def event
+        @event ||= Event.from_hash(session.post('facebook.events.get', :eids => [eid]).first)
+      end
+      
+      #TODO: implement user() method
+    end
+    
+    include Model
+    attr_accessor :eid, :pic, :pic_small, :pic_big, :name, :creator, :update_time, :description, :tagline, :venue, :host, :event_type, :nid, :location, :end_time, :start_time, :event_subtype
+  end
+end

data/lib/facebooker/feed.rb

@@ -0,0 +1,65 @@
+module Facebooker
+  module Feed
+    METHODS = {'Action' => 'facebook.feed.publishActionOfUser', 'Story' => 'facebook.feed.publishStoryToUser',
+               'TemplatizedAction' => 'facebook.feed.publishTemplatizedAction' }
+
+    class ActionBase
+      1.upto(4) do |num|
+        attr_accessor "image_#{num}"
+        attr_accessor "image_#{num}_link"
+      end
+
+      protected
+      def image_params
+        image_hash = {}
+        1.upto(4) do |num|
+          image_attribute = "image_#{num}"
+          image_link_attribute = image_attribute + "_link"
+          self.__send__(image_attribute) ? image_hash[image_attribute] = self.__send__(image_attribute) : nil
+          self.__send__(image_link_attribute) ? image_hash[image_link_attribute] = self.__send__(image_link_attribute) : nil    
+        end
+        image_hash
+      end
+    end
+
+    ##
+    # Representation of a templatized action to be published into a user's news feed
+    # Deprecation Notice: +actor_id+ will be removed by Facebook sometime in February 2008
+    class TemplatizedAction < ActionBase
+     attr_accessor :actor_id, :page_actor_id, :title_template, :title_data, :body_template, :body_data, :body_general, :target_ids
+
+      def to_params
+       raise "Must set title_template" if self.title_template.nil?
+       { :actor_id => actor_id, :page_actor_id => page_actor_id, 
+         :title_template => title_template, :title_data => convert_json(title_data),
+         :body_template => body_template, :body_data => convert_json(body_data), :body_general => body_general,
+         :target_ids => target_ids }.merge image_params
+      end
+      
+      def convert_json(hash_or_string)    
+        (hash_or_string.is_a?(Hash) and hash_or_string.respond_to?(:to_json)) ? hash_or_string.to_json : hash_or_string
+      end
+    end
+
+    ##
+    # Representation of a story to be published into a user's news feed.
+    class Story < ActionBase
+      attr_accessor :title, :body
+
+      ##
+      # Converts Story to a Hash of its attributes for use as parameters to Facebook REST API calls
+      def to_params
+        raise "Must set title before converting" if self.title.nil?
+        { :title => title, :body => body }.merge image_params
+      end
+
+    end
+    Action = Story.dup
+    def Action.name
+      "Action"
+    end
+    ##
+    #  Representation of an action to be published into a user's news feed.  Alias for Story.
+    class Action; end
+  end
+end

data/lib/facebooker/group.rb

@@ -0,0 +1,35 @@
+require 'facebooker/model'
+module Facebooker
+  class Group
+    ##
+    # The model of a user's relationship to a group.  Users can occupy different positions within a group (e.g. 'owner')
+    class Membership
+      include Model
+      attr_accessor :position, :gid, :uid
+    end
+    include Model
+    attr_accessor :pic, :pic_small, :pic_big, :name, :creator, :recent_news, :gid, :update_time, :group_subtype, :group_type, :website, :office, :description, :venue, :nid
+    
+    
+    ##
+    # Get the full list of members as populated User objects.  First time fetches group members via Facebook API call.  
+    # Subsequent calls return cached values.
+    # This is a convenience method for getting all of the Membership instances and instantiating User instances for each Membership.
+    def members
+      @members ||= memberships.map do |membership|
+        User.new(membership.uid, session)
+      end
+    end
+    
+    ##
+    # Get a list of Membership instances associated with this Group.  First call retrieves the Membership instances via a Facebook
+    # API call.  Subsequent calls are retrieved from in-memory cache.
+    def memberships
+      @memberships ||= session.post('facebook.groups.getMembers', :gid => gid).map do |hash|
+        Membership.from_hash(hash) do |membership|
+          membership.gid = gid
+        end
+      end
+    end
+  end
+end

data/lib/facebooker/location.rb

@@ -0,0 +1,8 @@
+module Facebooker
+  ##
+  # Representation of Location used in all places where a Location is specified.
+  class Location
+    include Model
+    attr_accessor :city, :zip, :country, :state
+  end
+end

data/lib/facebooker/model.rb

@@ -0,0 +1,118 @@
+module Facebooker
+  ##
+  # helper methods primarily supporting the management of Ruby objects which are populatable via Hashes.  
+  # Since most Facebook API calls accept and return hashes of data (as XML), the Model module allows us to
+  # directly populate a model's attributes given a Hash with matching key names.
+  module Model
+    class UnboundSessionException < Exception; end
+    def self.included(includer)
+      includer.extend ClassMethods
+      includer.__send__(:attr_writer, :session)
+      includer.__send__(:attr_reader, :anonymous_fields)
+    end
+    module ClassMethods
+      ##
+      # Instantiate a new instance of the class into which we are included and populate that instance's
+      # attributes given the provided Hash.  Key names in the Hash should map to attribute names on the model.
+      def from_hash(hash)
+        instance = new(hash)
+        yield instance if block_given?
+        instance
+      end
+      
+      ##
+      # Create a standard attr_writer and a populating_attr_reader      
+      def populating_attr_accessor(*symbols)
+        attr_writer *symbols
+        populating_attr_reader *symbols
+      end
+
+      ## 
+      # Create a reader that will attempt to populate the model if it has not already been populated
+      def populating_attr_reader(*symbols)
+        symbols.each do |symbol|
+          define_method(symbol) do
+            populate unless populated?
+            instance_variable_get("@#{symbol}")
+          end
+        end
+      end
+      
+      def populating_hash_settable_accessor(symbol, klass)
+        populating_attr_reader symbol
+        hash_settable_writer(symbol, klass)
+      end
+        
+      def populating_hash_settable_list_accessor(symbol, klass)
+        populating_attr_reader symbol
+        hash_settable_list_writer(symbol, klass)
+      end
+      
+      #
+      # Declares an attribute named ::symbol:: which can be set with either an instance of ::klass::
+      # or a Hash which will be used to populate a new instance of ::klass::.
+      def hash_settable_accessor(symbol, klass)
+        attr_reader symbol
+        hash_settable_writer(symbol, klass)
+      end
+      
+      def hash_settable_writer(symbol, klass)
+        define_method("#{symbol}=") do |value|
+          instance_variable_set("@#{symbol}", value.kind_of?(Hash) ? klass.from_hash(value) : value)
+        end        
+      end
+      
+      #
+      # Declares an attribute named ::symbol:: which can be set with either a list of instances of ::klass::
+      # or a list of Hashes which will be used to populate a new instance of ::klass::.      
+      def hash_settable_list_accessor(symbol, klass)
+        attr_reader symbol
+        hash_settable_list_writer(symbol, klass)
+      end
+      
+      def hash_settable_list_writer(symbol, klass)
+        define_method("#{symbol}=") do |list|
+          instance_variable_set("@#{symbol}", list.map do |item|
+            item.kind_of?(Hash) ? klass.from_hash(item) : item
+          end)
+        end
+      end      
+    end
+    
+    ##
+    # Centralized, error-checked place for a model to get the session to which it is bound.
+    # Any Facebook API queries require a Session instance.
+    def session
+      @session || (raise UnboundSessionException, "Must bind this object to a Facebook session before querying")
+    end
+    
+    # 
+    # This gets populated from FQL queries.
+    def anon=(value)
+      @anonymous_fields = value
+    end
+    
+    def initialize(hash = {})
+      populate_from_hash!(hash)
+    end
+
+    def populate
+      raise NotImplementedError, "#{self.class} included me and should have overriden me"
+    end
+
+    def populated?
+      !@populated.nil?
+    end
+    
+    ##
+    # Set model's attributes via Hash.  Keys should map directly to the model's attribute names.
+    def populate_from_hash!(hash)
+      unless hash.empty?
+        hash.each do |key, value|
+          self.__send__("#{key}=", value)
+        end
+        @populated = true
+      end      
+    end    
+  end
+end

data/lib/facebooker/notifications.rb

@@ -0,0 +1,17 @@
+module Facebooker
+  class Notifications
+    include Model
+    attr_accessor :messages, :group_invites, :pokes, :friend_requests, :event_invites, :shares
+    
+    [:Messages, :Pokes, :Shares].each do |notification_type|
+      const_set(notification_type, Class.new do
+        include Model
+        attr_accessor :unread, :most_recent
+      end)
+      attribute_name = "#{notification_type.to_s.downcase}"
+      define_method("#{attribute_name}=") do |value|
+        instance_variable_set("@#{attribute_name}", value.kind_of?(Hash) ? Notifications.const_get(notification_type).from_hash(value) : value)
+      end
+    end
+  end
+end

data/lib/facebooker/parser.rb

@@ -0,0 +1,386 @@
+require 'rexml/document'
+require 'facebooker/session'
+module Facebooker
+  class Parser
+    
+    module REXMLElementExtensions
+      def text_value
+        self.children.first.to_s.strip
+      end
+    end
+    
+    ::REXML::Element.__send__(:include, REXMLElementExtensions)
+    
+    def self.parse(method, data)
+      Errors.process(data)
+      parser = Parser::PARSERS[method]
+      parser.process(
+        data
+      )
+    end
+    
+    def self.array_of(response_element, element_name)
+      values_to_return = []
+      response_element.elements.each(element_name) do |element|
+        values_to_return << yield(element)
+      end
+      values_to_return
+    end
+    
+    def self.array_of_text_values(response_element, element_name)
+      array_of(response_element, element_name) do |element|
+        element.text_value
+      end
+    end
+
+    def self.array_of_hashes(response_element, element_name)
+      array_of(response_element, element_name) do |element|
+        hashinate(element)
+      end
+    end
+    
+    def self.element(name, data)
+      data = data.body rescue data # either data or an HTTP response
+      doc = REXML::Document.new(data)
+      doc.elements.each(name) do |element|
+        return element
+      end
+      raise "Element #{name} not found in #{data}"
+    end
+    
+    def self.hash_or_value_for(element)
+      if element.children.size == 1 && element.children.first.kind_of?(REXML::Text)
+        element.text_value
+      else
+        hashinate(element)
+      end
+    end
+    
+    def self.hashinate(response_element)
+      response_element.children.reject{|c| c.kind_of? REXML::Text}.inject({}) do |hash, child|
+        hash[child.name] = if child.children.size == 1 && child.children.first.kind_of?(REXML::Text)
+          anonymous_field_from(child, hash) || child.text_value
+        else
+          if child.attributes['list'] == 'true'
+            child.children.reject{|c| c.kind_of? REXML::Text}.map do |subchild| 
+                hash_or_value_for(subchild)
+            end     
+          else
+            child.children.reject{|c| c.kind_of? REXML::Text}.inject({}) do |subhash, subchild|
+              subhash[subchild.name] = hash_or_value_for(subchild)
+              subhash
+            end
+          end
+        end
+        hash
+      end      
+    end
+    
+    def self.anonymous_field_from(child, hash)
+      if child.name == 'anon'
+        (hash[child.name] || []) << child.text_value
+      end
+    end
+    
+  end  
+  
+  class CreateToken < Parser#:nodoc:
+    def self.process(data)
+      element('auth_createToken_response', data).text_value
+    end
+  end
+
+  class GetSession < Parser#:nodoc:
+    def self.process(data)      
+      hashinate(element('auth_getSession_response', data))
+    end
+  end
+  
+  class GetFriends < Parser#:nodoc:
+    def self.process(data)
+      array_of_text_values(element('friends_get_response', data), 'uid')
+    end
+  end
+ 
+  class UserInfo < Parser#:nodoc:
+    def self.process(data)
+      array_of_hashes(element('users_getInfo_response', data), 'user')
+    end
+  end
+  
+  class PublishStoryToUser < Parser#:nodoc:
+    def self.process(data)
+      element('feed_publishStoryToUser_response', data).text_value
+    end
+  end
+  
+  class PublishActionOfUser < Parser#:nodoc:
+    def self.process(data)
+      element('feed_publishActionOfUser_response', data).text_value
+    end
+  end
+    
+  class PublishTemplatizedAction < Parser#:nodoc:
+    def self.process(data)
+      element('feed_publishTemplatizedAction_response', data).children[1].text_value
+    end
+  end  
+  
+  class GetAppUsers < Parser#:nodoc:
+    def self.process(data)
+      array_of_text_values(element('friends_getAppUsers_response', data), 'uid')
+    end
+  end
+  
+  class NotificationsGet < Parser#:nodoc:
+    def self.process(data)
+      hashinate(element('notifications_get_response', data))
+    end
+  end
+  
+  class NotificationsSend < Parser#:nodoc:
+    def self.process(data)
+      element('notifications_send_response', data).text_value
+    end
+  end 
+
+  class NotificationsSendEmail < Parser#:nodoc:
+    def self.process(data)  
+      element('notifications_sendEmail_response', data).text_value
+    end
+  end
+
+  class GetTags < Parser#nodoc:
+    def self.process(data)
+      array_of_hashes(element('photos_getTags_response', data), 'photo_tag')
+    end
+  end
+  
+  class AddTags < Parser#nodoc:
+    def self.process(data)
+      element('photos_addTag_response', data)
+    end
+  end
+
+  class GetPhotos < Parser#nodoc:
+    def self.process(data)
+      array_of_hashes(element('photos_get_response', data), 'photo')
+    end
+  end
+  
+  class GetAlbums < Parser#nodoc:
+    def self.process(data)
+      array_of_hashes(element('photos_getAlbums_response', data), 'album')
+    end
+  end
+  
+  class CreateAlbum < Parser#:nodoc:
+    def self.process(data)
+      hashinate(element('photos_createAlbum_response', data))
+    end
+  end  
+  
+  class UploadPhoto < Parser#:nodoc:
+    def self.process(data)
+      hashinate(element('photos_upload_response', data))
+    end
+  end
+  
+  class SendRequest < Parser#:nodoc:
+    def self.process(data)
+      element('notifications_sendRequest_response', data).text_value
+    end
+  end
+  
+  class ProfileFBML < Parser#:nodoc:
+    def self.process(data)
+      element('profile_getFBML_response', data).text_value
+    end
+  end
+  
+  class ProfileFBMLSet < Parser#:nodoc:
+    def self.process(data)
+      element('profile_setFBML_response', data).text_value
+    end
+  end
+  
+  class FqlQuery < Parser#nodoc
+    def self.process(data)
+      root = element('fql_query_response', data)
+      first_child = root.children.reject{|c| c.kind_of?(REXML::Text)}.first
+      [first_child.name, array_of_hashes(root, first_child.name)]
+    end
+  end
+  
+  class SetRefHandle < Parser#:nodoc:
+    def self.process(data)
+      element('fbml_setRefHandle_response', data).text_value
+    end
+  end
+  
+  class RefreshRefURL < Parser#:nodoc:
+    def self.process(data)
+      element('fbml_refreshRefUrl_response', data).text_value
+    end
+  end
+  
+  class RefreshImgSrc < Parser#:nodoc:
+    def self.process(data)
+      element('fbml_refreshImgSrc_response', data).text_value
+    end
+  end
+  
+  class SetCookie < Parser#:nodoc:
+    def self.process(data)
+      element('data_setCookie_response', data).text_value
+    end
+  end
+  
+  class GetCookies < Parser#:nodoc:
+    def self.process(data)
+      array_of_hashes(element('data_getCookie_response', data), 'cookies')
+    end
+  end
+  
+  class EventsGet < Parser#:nodoc:
+    def self.process(data)
+      array_of_hashes(element('events_get_response', data), 'event')
+    end
+  end
+  
+  class GroupGetMembers < Parser#:nodoc:
+    def self.process(data)
+      root = element('groups_getMembers_response', data)
+      result = ['members', 'admins', 'officers', 'not_replied'].map do |position|
+        array_of(root, position) {|element| element}.map do |element|
+          array_of_text_values(element, 'uid').map do |uid|
+            {:position => position}.merge(:uid => uid)
+          end
+        end
+      end.flatten      
+    end
+  end
+  
+  class EventMembersGet < Parser#:nodoc:
+    def self.process(data)
+      root = element('events_getMembers_response', data)
+      result = ['attending', 'declined', 'unsure', 'not_replied'].map do |rsvp_status|
+        array_of(root, rsvp_status) {|element| element}.map do |element|
+          array_of_text_values(element, 'uid').map do |uid|
+            {:rsvp_status => rsvp_status}.merge(:uid => uid)
+          end
+        end
+      end.flatten
+    end
+  end
+  
+  class GroupsGet < Parser#:nodoc:
+    def self.process(data)
+      array_of_hashes(element('groups_get_response', data), 'group')
+    end
+  end
+  
+  class AreFriends < Parser#:nodoc:
+    def self.process(data)
+      array_of_hashes(element('friends_areFriends_response', data), 'friend_info').inject({}) do |memo, hash|
+        memo[[Integer(hash['uid1']), Integer(hash['uid2'])].sort] = are_friends?(hash['are_friends'])
+        memo
+      end
+    end
+    
+    private
+    def self.are_friends?(raw_value)
+      if raw_value == '1'
+        true
+      elsif raw_value == '0'
+        false
+      else
+        nil
+      end
+    end
+  end
+    
+  class Errors < Parser#:nodoc:
+    EXCEPTIONS = {
+      1 	=> Facebooker::Session::UnknownError,
+      2 	=> Facebooker::Session::ServiceUnavailable,
+      4 	=> Facebooker::Session::MaxRequestsDepleted,
+      5 	=> Facebooker::Session::HostNotAllowed,
+      100 => Facebooker::Session::MissingOrInvalidParameter,
+      101 => Facebooker::Session::InvalidAPIKey,
+      102 => Facebooker::Session::SessionExpired,
+      103 => Facebooker::Session::CallOutOfOrder,
+      104 => Facebooker::Session::IncorrectSignature,
+      120 => Facebooker::Session::InvalidAlbumId,
+      321 => Facebooker::Session::AlbumIsFull,
+      324 => Facebooker::Session::MissingOrInvalidImageFile,
+      325 => Facebooker::Session::TooManyUnapprovedPhotosPending,
+      340 => Facebooker::Session::TooManyUserCalls,
+      341 => Facebooker::Session::TooManyUserActionCalls,
+      342 => Facebooker::Session::InvalidFeedTitleLink,
+      343 => Facebooker::Session::InvalidFeedTitleLength,
+      344 => Facebooker::Session::InvalidFeedTitleName,
+      345 => Facebooker::Session::BlankFeedTitle,
+      346 => Facebooker::Session::FeedBodyLengthTooLong,
+      347 => Facebooker::Session::InvalidFeedPhotoSource,
+      348 => Facebooker::Session::InvalidFeedPhotoLink,      
+      330 => Facebooker::Session::FeedMarkupInvalid,
+      360 => Facebooker::Session::FeedTitleDataInvalid,
+      361 => Facebooker::Session::FeedTitleTemplateInvalid,
+      362 => Facebooker::Session::FeedBodyDataInvalid,
+      363 => Facebooker::Session::FeedBodyTemplateInvalid,
+      364 => Facebooker::Session::FeedPhotosNotRetrieved,
+      366 => Facebooker::Session::FeedTargetIdsInvalid,
+      601 => Facebooker::Session::FQLParseError,
+      602 => Facebooker::Session::FQLFieldDoesNotExist,
+      603 => Facebooker::Session::FQLTableDoesNotExist,
+      604 => Facebooker::Session::FQLStatementNotIndexable,
+      605 => Facebooker::Session::FQLFunctionDoesNotExist,
+      606 => Facebooker::Session::FQLWrongNumberArgumentsPassedToFunction
+    }
+    def self.process(data)
+      response_element = element('error_response', data) rescue nil
+      if response_element
+        hash = hashinate(response_element)
+        raise EXCEPTIONS[Integer(hash['error_code'])].new(hash['error_msg'])
+      end
+    end
+  end
+  
+  class Parser
+    PARSERS = {
+      'facebook.auth.createToken' => CreateToken,
+      'facebook.auth.getSession' => GetSession,
+      'facebook.users.getInfo' => UserInfo,
+      'facebook.friends.get' => GetFriends,
+      'facebook.friends.areFriends' => AreFriends,
+      'facebook.friends.getAppUsers' => GetAppUsers,
+      'facebook.feed.publishStoryToUser' => PublishStoryToUser,
+      'facebook.feed.publishActionOfUser' => PublishActionOfUser,
+      'facebook.feed.publishTemplatizedAction' => PublishTemplatizedAction,
+      'facebook.notifications.get' => NotificationsGet,
+      'facebook.notifications.send' => NotificationsSend,
+      'facebook.notifications.sendRequest' => SendRequest,
+      'facebook.profile.getFBML' => ProfileFBML,
+      'facebook.profile.setFBML' => ProfileFBMLSet,
+      'facebook.fbml.setRefHandle' => SetRefHandle,
+      'facebook.fbml.refreshRefUrl' => RefreshRefURL,
+      'facebook.fbml.refreshImgSrc' => RefreshImgSrc,
+      'facebook.data.setCookie' => SetCookie,
+      'facebook.data.getCookies' => GetCookies,
+      'facebook.fql.query' => FqlQuery,
+      'facebook.photos.get' => GetPhotos,
+      'facebook.photos.getAlbums' => GetAlbums,
+      'facebook.photos.createAlbum' => CreateAlbum,
+      'facebook.photos.getTags' => GetTags,
+      'facebook.photos.addTag' => AddTags,
+      'facebook.photos.upload' => UploadPhoto,
+      'facebook.events.get' => EventsGet,
+      'facebook.groups.get' => GroupsGet,
+      'facebook.events.getMembers' => EventMembersGet,
+      'facebook.groups.getMembers' => GroupGetMembers,
+      'facebook.notifications.sendEmail' => NotificationsSendEmail
+      
+    }
+  end
+end