koala 0.9.0 → 1.1.0

data/lib/koala/graph_api.rb

@@ -1,65 +1,12 @@
 module Koala
   module Facebook
-    GRAPH_SERVER = "graph.facebook.com"
-
-    class GraphCollection < Array
-      #This class is a light wrapper for collections returned
-      #from the Graph API.
-      #
-      #It extends Array to allow direct access to the data colleciton
-      #which should allow it to drop in seamlessly.
-      #
-      #It also allows access to paging information and the
-      #ability to get the next/previous page in the collection
-      #by calling next_page or previous_page.
-      attr_reader :paging
-      attr_reader :api
-      
-      def initialize(response, api)
-        super response["data"]
-        @paging = response["paging"]
-        @api = api
-      end
-            
-      # defines methods for NEXT and PREVIOUS pages
-      %w{next previous}.each do |this|
-        
-        # def next_page
-        # def previous_page
-        define_method "#{this.to_sym}_page" do
-          base, args = send("#{this}_page_params")
-          base ? @api.get_page([base, args]) : nil
-        end
-        
-        # def next_page_params
-        # def previous_page_params
-        define_method "#{this.to_sym}_page_params" do
-          return nil unless @paging and @paging[this]
-          parse_page_url(@paging[this])
-        end
-      end
-      
-      def parse_page_url(url)
-        match = url.match(/.com\/(.*)\?(.*)/)
-        base = match[1]
-        args = match[2]
-        params = CGI.parse(args)
-        new_params = {}
-        params.each_pair do |key,value|
-          new_params[key] = value.join ","
-        end
-        [base,new_params]
-      end
-      
-    end
-    
-    
+    GRAPH_SERVER = "graph.facebook.com"   
 
     module GraphAPIMethods
       # A client for the Facebook Graph API.
       # 
-      # See http://developers.facebook.com/docs/api for complete documentation
-      # for the API.
+      # See http://github.com/arsduo/koala for Ruby/Koala documentation
+      # and http://developers.facebook.com/docs/api for Facebook API documentation
       # 
       # The Graph API is made up of the objects in Facebook (e.g., people, pages,
       # events, photos) and the connections between them (e.g., friends,
@@ -76,117 +23,236 @@ module Koala
       # by the API at http://developers.facebook.com/docs/reference/api/.
       # 
       # You can obtain an access token via OAuth or by using the Facebook
-      # JavaScript SDK. See http://developers.facebook.com/docs/authentication/
-      # for details.
+      # JavaScript SDK. See the Koala and Facebook documentation for more information.
       # 
       # If you are using the JavaScript SDK, you can use the
       # Koala::Facebook::OAuth.get_user_from_cookie() method below to get the OAuth access token
       # for the active user from the cookie saved by the SDK.
-            
-      def get_object(id, args = {})
+
+      # Objects
+
+      def get_object(id, args = {}, options = {})
         # Fetchs the given object from the graph.
-        graph_call(id, args)
-      end
-    
-      def get_objects(ids, args = {})
-        # Fetchs all of the given object from the graph.
-        # We return a map from ID to object. If any of the IDs are invalid,
-        # we raise an exception.
-        graph_call("", args.merge("ids" => ids.join(",")))
-      end
-      
-      def get_page(params)
-        result = graph_call(*params)
-        result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
+        graph_call(id, args, "get", options)
       end
     
-      def get_connections(id, connection_name, args = {})
-        # Fetchs the connections for given object.
-        result = graph_call("#{id}/#{connection_name}", args)
-        result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
+      def get_objects(ids, args = {}, options = {})
+        # Fetchs all of the given objects from the graph.
+        # If any of the IDs are invalid, they'll raise an exception.
+        return [] if ids.empty?
+        graph_call("", args.merge("ids" => ids.respond_to?(:join) ? ids.join(",") : ids), "get", options)
       end
       
-    
-      def get_picture(object, args = {})
-        result = graph_call("#{object}/picture", args, "get", :http_component => :headers)
-        result["Location"]
-      end    
-      
-      def put_object(parent_object, connection_name, args = {})
+      def put_object(parent_object, connection_name, args = {}, options = {})
         # Writes the given object to the graph, connected to the given parent.
-        # 
-        # For example,
-        # 
-        #     graph.put_object("me", "feed", :message => "Hello, world")
-        # 
-        # writes "Hello, world" to the active user's wall. Likewise, this
-        # will comment on a the first post of the active user's feed:
-        # 
-        #     feed = graph.get_connections("me", "feed")
-        #     post = feed["data"][0]
-        #     graph.put_object(post["id"], "comments", :message => "First!")
-        # 
         # See http://developers.facebook.com/docs/api#publishing for all of
         # the supported writeable objects.
         # 
+        # For example,
+        #     graph.put_object("me", "feed", :message => "Hello, world")
+        # writes "Hello, world" to the active user's wall.
+        #
         # Most write operations require extended permissions. For example,
         # publishing wall posts requires the "publish_stream" permission. See
         # http://developers.facebook.com/docs/authentication/ for details about
         # extended permissions.
+    
+        raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Write operations require an access token"}) unless @access_token
+        graph_call("#{parent_object}/#{connection_name}", args, "post", options)
+      end
 
+      def delete_object(id, options = {})
+        # Deletes the object with the given ID from the graph.
+        raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Delete requires an access token"}) unless @access_token
+        graph_call(id, {}, "delete", options)
+      end
+      
+      # Connections
+          
+      def get_connections(id, connection_name, args = {}, options = {})
+        # Fetchs the connections for given object.
+        graph_call("#{id}/#{connection_name}", args, "get", options) do |result|
+          result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
+        end
+      end
+
+      def get_comments_for_urls(urls = [], args = {}, options = {})
+        # Fetchs the comments for given URLs (array or comma-separated string)
+        # see https://developers.facebook.com/blog/post/490
+        return [] if urls.empty?
+        args.merge!(:ids => urls.respond_to?(:join) ? urls.join(",") : urls)
+        get_object("comments", args, options)
+      end
+          
+      def put_connections(id, connection_name, args = {}, options = {})
+        # Posts a certain connection
         raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Write operations require an access token"}) unless @access_token
-        graph_call("#{parent_object}/#{connection_name}", args, "post")
+        graph_call("#{id}/#{connection_name}", args, "post", options)
+      end
+
+      def delete_connections(id, connection_name, args = {}, options = {})
+        # Deletes a given connection
+        raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Delete requires an access token"}) unless @access_token
+        graph_call("#{id}/#{connection_name}", args, "delete", options)
       end
+
+      # Media (photos and videos)
+      # to delete photos or videos, use delete_object(object_id)
+      # note: you'll need the user_photos or user_videos permissions to actually access media after upload 
     
-      def put_wall_post(message, attachment = {}, profile_id = "me")
-        # Writes a wall post to the given profile's wall.
-        # 
-        # We default to writing to the authenticated user's wall if no
-        # profile_id is specified.
-        # 
-        # attachment adds a structured attachment to the status message being
-        # posted to the Wall. It should be a dictionary of the form:
+      def get_picture(object, args = {}, options = {})
+        # Gets a picture object, returning the URL (which Facebook sends as a header)
+        graph_call("#{object}/picture", args, "get", options.merge(:http_component => :headers)) do |result|
+          result["Location"]
+        end
+      end    
+      
+      # Can be called in multiple ways:
+      #
+      #   put_picture(file, [content_type], ...)
+      #   put_picture(path_to_file, [content_type], ...)
+      #
+      # You can pass in uploaded files directly from Rails or Sinatra.
+      # (See lib/koala/uploadable_io.rb for supported frameworks)
+      #
+      # Optional parameters can be added to the end of the argument list:
+      # - args:       a hash of request parameters (default: {})
+      # - target_id:  ID of the target where to post the picture (default: "me")
+      # - options:    a hash of http options passed to the HTTPService module
+      # 
+      #   put_picture(file, content_type, {:message => "Message"}, 01234560)
+      #   put_picture(params[:file], {:message => "Message"})
+      
+      def put_picture(*picture_args)
+        put_object(*parse_media_args(picture_args, "photos"))
+      end
+        
+      def put_video(*video_args)
+        args = parse_media_args(video_args, "videos")
+        args.last[:video] = true
+        put_object(*args)
+      end
+    
+      # Wall posts
+      # To get wall posts, use get_connections(user, "feed")
+      # To delete a wall post, just use delete_object(post_id)
+    
+      def put_wall_post(message, attachment = {}, profile_id = "me", options = {})
+        # attachment is a hash describing the wall post
+        # (see X for more details)
+        # For instance, 
         # 
-        #     {"name": "Link name"
-        #      "link": "http://www.example.com/",
-        #      "caption": "{*actor*} posted a new review",
-        #      "description": "This is a longer description of the attachment",
-        #      "picture": "http://www.example.com/thumbnail.jpg"}
+        #     {"name" => "Link name"
+        #      "link" => "http://www.example.com/",
+        #      "caption" => "{*actor*} posted a new review",
+        #      "description" => "This is a longer description of the attachment",
+        #      "picture" => "http://www.example.com/thumbnail.jpg"}
 
-        self.put_object(profile_id, "feed", attachment.merge({:message => message}))
+        self.put_object(profile_id, "feed", attachment.merge({:message => message}), options)
       end
-    
-      def put_comment(object_id, message)
+      
+      # Comments
+      # to delete comments, use delete_object(comment_id)
+      # to get comments, use get_connections(object, "likes")
+      
+      def put_comment(object_id, message, options = {})
         # Writes the given comment on the given post.
-        self.put_object(object_id, "comments", {:message => message})
+        self.put_object(object_id, "comments", {:message => message}, options)
       end
-    
-      def put_like(object_id)
+        
+      # Likes
+      # to get likes, use get_connections(user, "likes")
+      
+      def put_like(object_id, options = {})
         # Likes the given post.
-        self.put_object(object_id, "likes")
+        self.put_object(object_id, "likes", {}, options)
       end
-    
-      def delete_object(id)
-        # Deletes the object with the given ID from the graph.
-        graph_call(id, {}, "delete")
+
+      def delete_like(object_id, options = {})
+        # Unlikes a given object for the logged-in user
+        raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Unliking requires an access token"}) unless @access_token
+        graph_call("#{object_id}/likes", {}, "delete", options)
       end
-    
-      def search(search_terms, args = {})
-        # Searches for a given term
-        result = graph_call("search", args.merge({:q => search_terms}))
-        result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
+
+      # Search
+            
+      def search(search_terms, args = {}, options = {})
+        args.merge!({:q => search_terms}) unless search_terms.nil?
+        graph_call("search", args, "get", options) do |result|
+          result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
+        end
+      end      
+      
+      
+      # GraphCollection support
+      def get_page(params)
+        # Pages through a set of results stored in a GraphCollection
+        # Used for connections and search results
+        graph_call(*params) do |result|
+          result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
+        end
       end
-    
-      def graph_call(*args)
-        response = api(*args) do |response|
-          # check for Graph API-specific errors
-          if response.is_a?(Hash) && error_details = response["error"]
-            raise APIError.new(error_details)
+      
+      
+      # Batch API
+      def batch(http_options = {}, &block)
+        batch_client = GraphBatchAPI.new(access_token)
+        if block
+          yield batch_client
+          batch_client.execute(http_options)
+        else
+          batch_client
+        end
+      end        
+      
+      def self.included(base)
+        base.class_eval do
+          def self.batch
+            raise NoMethodError, "The BatchAPI signature has changed (the original implementation was not thread-safe).  Please see https://github.com/arsduo/koala/wiki/Batch-requests.  (This message will be removed in the final 1.1 release.)"
           end
         end
+      end
       
-        response
+      # Direct access to the Facebook API
+      # see any of the above methods for example invocations
+      def graph_call(path, args = {}, verb = "get", options = {}, &post_processing)
+        result = api(path, args, verb, options) do |response|
+          error = check_response(response)
+          raise error if error
+        end
+
+        # now process as appropriate (get picture header, make GraphCollection, etc.)
+        post_processing ? post_processing.call(result) : result
+      end
+      
+      def check_response(response)
+        # check for Graph API-specific errors
+        # this returns an error, which is immediately raised (non-batch)
+        # or added to the list of batch results (batch)
+        if response.is_a?(Hash) && error_details = response["error"]
+          APIError.new(error_details) 
+        end
       end
+      
+      private
+      
+      def parse_media_args(media_args, method)
+        # photo and video uploads can accept different types of arguments (see above)
+        # so here, we parse the arguments into a form directly usable in put_object
+        raise KoalaError.new("Wrong number of arguments for put_#{method == "photos" ? "picture" : "video"}") unless media_args.size.between?(1, 5)
+        
+        args_offset = media_args[1].kind_of?(Hash) || media_args.size == 1 ? 0 : 1
+        
+        args      = media_args[1 + args_offset] || {}
+        target_id = media_args[2 + args_offset] || "me"
+        options   = media_args[3 + args_offset] || {} 
+        
+        args["source"] = Koala::UploadableIO.new(*media_args.slice(0, 1 + args_offset))
+
+        options[:http_service] = Koala.base_http_service if args["source"].requires_base_http_service
+
+        [target_id, method, args, options]
+      end      
     end
   end
-end
+end  

data/lib/koala/graph_batch_api.rb

@@ -0,0 +1,87 @@
+module Koala
+  module Facebook
+      module GraphBatchAPIMethods
+        
+      def self.included(base)
+        base.class_eval do
+          alias_method :graph_call_outside_batch, :graph_call
+          alias_method :graph_call, :graph_call_in_batch
+          
+          alias_method :check_graph_api_response, :check_response
+          alias_method :check_response, :check_graph_batch_api_response
+        end
+      end
+      
+      def batch_calls
+        @batch_calls ||= []
+      end
+            
+      def graph_call_in_batch(path, args = {}, verb = "get", options = {}, &post_processing)
+          # for batch APIs, we queue up the call details (incl. post-processing)
+          batch_calls << BatchOperation.new(
+            :url => path,
+            :args => args,
+            :method => verb,
+            :access_token => options['access_token'] || access_token,
+            :http_options => options,
+            :post_processing => post_processing
+          )
+          nil # batch operations return nothing immediately 
+      end
+
+      def check_graph_batch_api_response(response)
+        if response.is_a?(Hash) && response["error"] && !response["error"].is_a?(Hash)
+          APIError.new("type" => "Error #{response["error"]}", "message" => response["error_description"])
+        else
+          check_graph_api_response(response)
+        end
+      end
+
+      def execute(http_options = {})
+        return [] unless batch_calls.length > 0
+        # Turn the call args collected into what facebook expects
+        args = {}
+        args["batch"] = MultiJson.encode(batch_calls.map { |batch_op|
+          args.merge!(batch_op.files) if batch_op.files
+          batch_op.to_batch_params(access_token)
+        })
+        
+        graph_call_outside_batch('/', args, 'post', http_options) do |response|
+          # map the results with post-processing included
+          index = 0 # keep compat with ruby 1.8 - no with_index for map
+          response.map do |call_result|
+            # Get the options hash
+            batch_op = batch_calls[index]
+            index += 1
+
+            if call_result
+              # (see note in regular api method about JSON parsing)
+              body = MultiJson.decode("[#{call_result['body'].to_s}]")[0]
+              
+              unless call_result["code"].to_i >= 500 || error = check_response(body)
+                # Get the HTTP component they want
+                data = case batch_op.http_options[:http_component] 
+                when :status
+                  call_result["code"].to_i
+                when :headers
+                  # facebook returns the headers as an array of k/v pairs, but we want a regular hash
+                  call_result['headers'].inject({}) { |headers, h| headers[h['name']] = h['value']; headers}
+                else
+                  body
+                end
+
+                # process it if we are given a block to process with
+                batch_op.post_processing ? batch_op.post_processing.call(data) : data
+              else
+                error || APIError.new({"type" => "HTTP #{call_result["code"].to_s}", "message" => "Response body: #{body}"})
+              end
+            else
+              nil
+            end
+          end          
+        end
+      end
+      
+    end
+  end
+end

data/lib/koala/graph_collection.rb

@@ -0,0 +1,54 @@
+module Koala
+  module Facebook
+    class GraphCollection < Array
+      # This class is a light wrapper for collections returned
+      # from the Graph API.
+      #
+      # It extends Array to allow direct access to the data colleciton
+      # which should allow it to drop in seamlessly.
+      #
+      # It also allows access to paging information and the
+      # ability to get the next/previous page in the collection
+      # by calling next_page or previous_page.
+      attr_reader :paging
+      attr_reader :api
+      
+      def initialize(response, api)
+        super response["data"]
+        @paging = response["paging"]
+        @api = api
+      end
+            
+      # defines methods for NEXT and PREVIOUS pages
+      %w{next previous}.each do |this|
+        
+        # def next_page
+        # def previous_page
+        define_method "#{this.to_sym}_page" do
+          base, args = send("#{this}_page_params")
+          base ? @api.get_page([base, args]) : nil
+        end
+        
+        # def next_page_params
+        # def previous_page_params
+        define_method "#{this.to_sym}_page_params" do
+          return nil unless @paging and @paging[this]
+          parse_page_url(@paging[this])
+        end
+      end
+      
+      def parse_page_url(url)
+        match = url.match(/.com\/(.*)\?(.*)/)
+        base = match[1]
+        args = match[2]
+        params = CGI.parse(args)
+        new_params = {}
+        params.each_pair do |key,value|
+          new_params[key] = value.join ","
+        end
+        [base,new_params]
+      end
+      
+    end
+  end
+end

data/lib/koala/http_services/net_http_service.rb

@@ -0,0 +1,92 @@
+require "net/http" unless defined?(Net::HTTP)
+require "net/https"
+require "net/http/post/multipart"
+
+module Koala
+  module NetHTTPService
+    # this service uses Net::HTTP to send requests to the graph
+    include Koala::HTTPService
+
+    # Net::HTTP-specific values
+    class << self
+      attr_accessor :ca_file, :ca_path, :verify_mode
+    end
+    
+    def self.make_request(path, args, verb, options = {})
+      # We translate args to a valid query string. If post is specified,
+      # we send a POST request to the given path with the given arguments.
+
+      # by default, we use SSL only for private requests
+      # this makes public requests faster
+      private_request = args["access_token"] || @always_use_ssl || options[:use_ssl]
+
+      # if the verb isn't get or post, send it as a post argument
+      args.merge!({:method => verb}) && verb = "post" if verb != "get" && verb != "post"
+
+      http = create_http(server(options), private_request, options)
+
+      response = http.start do |http|
+        if verb == "post"
+          if params_require_multipart? args
+            http.request Net::HTTP::Post::Multipart.new path, encode_multipart_params(args)
+          else
+            http.post(path, encode_params(args))
+          end
+        else
+          http.get("#{path}?#{encode_params(args)}")
+        end
+      end
+
+      Koala::Response.new(response.code.to_i, response.body, response)
+    end
+
+    protected
+    def self.encode_params(param_hash)
+      # unfortunately, we can't use to_query because that's Rails, not Ruby
+      # if no hash (e.g. no auth token) return empty string
+      ((param_hash || {}).collect do |key_and_value|
+        key_and_value[1] = MultiJson.encode(key_and_value[1]) if key_and_value[1].class != String
+        "#{key_and_value[0].to_s}=#{CGI.escape key_and_value[1]}"
+      end).join("&")
+    end
+
+    def self.encode_multipart_params(param_hash)
+      Hash[*param_hash.collect do |key, value|
+        [key, value.kind_of?(Koala::UploadableIO) ? value.to_upload_io : value]
+      end.flatten]
+    end
+
+    def self.create_http(server, private_request, options)
+      if proxy_server = options[:proxy] || proxy
+        proxy = URI.parse(proxy_server)
+        http  = Net::HTTP.new(server, private_request ? 443 : nil,
+                              proxy.host, proxy.port, proxy.user, proxy.password)
+      else
+        http  = Net::HTTP.new(server, private_request ? 443 : nil)
+      end
+
+      if timeout_value = options[:timeout] || timeout
+        http.open_timeout = timeout_value
+        http.read_timeout = timeout_value
+      end
+
+      # For HTTPS requests, set the proper CA certificates
+      if private_request
+        http.use_ssl = true  
+        http.verify_mode = options[:verify_mode] || verify_mode || OpenSSL::SSL::VERIFY_PEER
+        
+        if cert_file = options[:ca_file] || ca_file
+          raise Errno::ENOENT, "Certificate file #{cert_file.inspect} does not exist!" unless File.exists?(cert_file)
+          http.ca_file = cert_file 
+        end
+        
+        if cert_path = options[:ca_path] || ca_path
+          raise Errno::ENOENT, "Certificate path #{cert_path.inspect} does not exist!" unless File.directory?(cert_path)
+          http.ca_path = cert_path
+        end
+      end
+
+      http
+    end
+  end
+end

data/lib/koala/http_services/typhoeus_service.rb

@@ -0,0 +1,37 @@
+require "typhoeus" unless defined?(Typhoeus)
+
+module Koala
+  module TyphoeusService
+    # this service uses Typhoeus to send requests to the graph
+    include Typhoeus
+    include Koala::HTTPService
+
+    def self.make_request(path, args, verb, options = {})
+      # if the verb isn't get or post, send it as a post argument
+      args.merge!({:method => verb}) && verb = "post" if verb != "get" && verb != "post"
+
+      # switch any UploadableIOs to the files Typhoeus expects
+      args.each_pair {|key, value| args[key] = value.to_file if value.is_a?(UploadableIO)}
+
+      # you can pass arguments directly to Typhoeus using the :typhoeus_options key
+      typhoeus_options = {:params => args}.merge(options[:typhoeus_options] || {})
+
+      # if proxy/timeout options aren't passed, check if defaults are set
+      typhoeus_options[:proxy] ||= proxy
+      typhoeus_options[:timeout] ||= timeout
+
+      # by default, we use SSL only for private requests (e.g. with access token)
+      # this makes public requests faster
+      prefix = (args["access_token"] || @always_use_ssl || options[:use_ssl]) ? "https" : "http"
+
+      response = Typhoeus::Request.send(verb, "#{prefix}://#{server(options)}#{path}", typhoeus_options)
+      Koala::Response.new(response.code, response.body, response.headers_hash)
+    end
+
+    protected
+
+    def self.multipart_requires_content_type?
+      false # Typhoeus handles multipart file types, we don't have to require it
+    end
+  end
+end