koala 1.2.1 → 1.3.0

data/lib/koala/{graph_batch_api.rb → api/graph_batch_api.rb}

@@ -1,22 +1,17 @@
+require 'koala/api'
+require 'koala/api/batch_operation'
+
 module Koala
   module Facebook
-      module GraphBatchAPIMethods
-
-      def self.included(base)
-        base.class_eval do
-          attr_reader :original_api
-          
-          def initialize(access_token, api)
-            super(access_token)
-            @original_api = api
-          end
-
-          alias_method :graph_call_outside_batch, :graph_call
-          alias_method :graph_call, :graph_call_in_batch
+    # @private
+    class GraphBatchAPI < API
+      # inside a batch call we can do anything a regular Graph API can do
+      include GraphAPIMethods
 
-          alias_method :check_graph_api_response, :check_response
-          alias_method :check_response, :check_graph_batch_api_response
-        end
+      attr_reader :original_api
+      def initialize(access_token, api)
+        super(access_token)
+        @original_api = api
       end
 
       def batch_calls
@@ -38,12 +33,22 @@ module Koala
 
       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"])
+          # old error format -- see http://developers.facebook.com/blog/post/596/
+          APIError.new({"type" => "Error #{response["error"]}", "message" => response["error_description"]}.merge(response))
         else
           check_graph_api_response(response)
         end
       end
 
+      # redefine the graph_call and check_response methods
+      # so we can use this API inside the batch block just like any regular Graph API  
+      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
+
+      # execute the queued batch calls
       def execute(http_options = {})
         return [] unless batch_calls.length > 0
         # Turn the call args collected into what facebook expects

data/lib/koala/api/graph_collection.rb

@@ -0,0 +1,107 @@
+module Koala
+  module Facebook
+    class API
+      # A light wrapper for collections returned from the Graph API.
+      # It extends Array to allow you to page backward and forward through
+      # result sets, and providing easy access to paging information.
+      class GraphCollection < Array        
+        
+        # The raw paging information from Facebook (next/previous URLs).
+        attr_reader :paging
+        # @return [Koala::Facebook::GraphAPI] the api used to make requests.
+        attr_reader :api
+        # The entire raw response from Facebook.
+        attr_reader :raw_response
+    
+        # Initialize the array of results and store various additional paging-related information.
+        # 
+        # @param response the response from Facebook (a hash whose "data" key is an array)
+        # @param api the Graph {Koala::Facebook::API API} instance to use to make calls
+        #            (usually the API that made the original call).
+        #
+        # @return [Koala::Facebook::GraphCollection] an initialized GraphCollection 
+        #         whose paging, raw_response, and api attributes are populated.
+        def initialize(response, api)
+          super response["data"]
+          @paging = response["paging"]
+          @raw_response = response
+          @api = api
+        end
+
+        # @private
+        # Turn the response into a GraphCollection if they're pageable; 
+        # if not, return the original response.
+        # The Ads API (uniquely so far) returns a hash rather than an array when queried
+        # with get_connections. 
+        def self.evaluate(response, api)
+          response.is_a?(Hash) && response["data"].is_a?(Array) ? self.new(response, api) : response
+        end
+        
+        # Retrieve the next page of results.
+        # 
+        # @return a GraphCollection array of additional results (an empty array if there are no more results)
+        def next_page
+          base, args = next_page_params
+          base ? @api.get_page([base, args]) : nil
+        end
+        
+        # Retrieve the previous page of results.
+        # 
+        # @return a GraphCollection array of additional results (an empty array if there are no earlier results)
+        def previous_page
+          base, args = previous_page_params
+          base ? @api.get_page([base, args]) : nil
+        end
+        
+        # Arguments that can be sent to {Koala::Facebook::API#graph_call} to retrieve the next page of results. 
+        # 
+        # @example
+        #           @api.graph_call(*collection.next_page_params)
+        #
+        # @return an array of arguments, or nil if there are no more pages
+        def next_page_params
+          @paging && @paging["next"] ? parse_page_url(@paging["next"]) : nil
+        end
+        
+        # Arguments that can be sent to {Koala::Facebook::API#graph_call} to retrieve the previous page of results. 
+        # 
+        # @example
+        #           @api.graph_call(*collection.previous_page_params)
+        #
+        # @return an array of arguments, or nil if there are no previous pages
+        def previous_page_params
+          @paging && @paging["previous"] ? parse_page_url(@paging["previous"]) : nil
+        end
+        
+        # @private
+        def parse_page_url(url)
+          GraphCollection.parse_page_url(url)
+        end
+
+        # Parse the previous and next page URLs Facebook provides in pageable results.
+        # You'll mainly need to use this when using a non-Rails framework (one without url_for);
+        # to store paging information between page loads, pass the URL (from GraphCollection#paging)
+        # and use parse_page_url to turn it into parameters useful for {Koala::Facebook::API#get_page}.
+        #
+        # @param url the paging URL to turn into graph_call parameters
+        #
+        # @return an array of parameters that can be provided via graph_call(*parsed_params)
+        def self.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
+    
+    # @private
+    # legacy support for when GraphCollection lived directly under Koala::Facebook    
+    GraphCollection = API::GraphCollection
+  end
+end

data/lib/koala/api/legacy.rb

@@ -0,0 +1,26 @@
+require 'koala/api'
+module Koala
+  module Facebook
+    # Legacy support for old pre-1.2 APIs
+    
+    # A wrapper for the old APIs deprecated in 1.2.0, which triggers a deprecation warning when used.
+    # Otherwise, this class functions identically to API.
+    # @see API 
+    # @private
+    class OldAPI < API
+      def initialize(*args)
+        Koala::Utils.deprecate("#{self.class.name} is deprecated and will be removed in a future version; please use the API class instead.")
+        super
+      end
+    end
+    
+    # @private
+    class GraphAPI < OldAPI; end
+    
+    # @private
+    class RestAPI < OldAPI; end
+    
+    # @private
+    class GraphAndRestAPI < OldAPI; end
+  end
+end

data/lib/koala/{rest_api.rb → api/rest_api.rb}

@@ -2,27 +2,47 @@ module Koala
   module Facebook
     REST_SERVER = "api.facebook.com"
 
+    # Methods used to interact with Facebook's legacy REST API.  
+    # Where possible, you should use the newer, faster Graph API to interact with Facebook;
+    # in the future, the REST API will be deprecated.
+    # For now, though, there are a few methods that can't be done through the Graph API.
+    #
+    # When using the REST API, Koala will use Facebook's faster read-only servers 
+    # whenever the call allows.  
+    #
+    # See https://github.com/arsduo/koala/wiki/REST-API for a general introduction to Koala
+    # and the Rest API.
     module RestAPIMethods
-      def fql_query(fql, args = {}, options = {})
-        rest_call('fql.query', args.merge(:query => fql), options)
-      end
-
-      def fql_multiquery(queries = {}, args = {}, options = {})
-        if results = rest_call('fql.multiquery', args.merge(:queries => MultiJson.encode(queries)), options)
-          # simplify the multiquery result format
-          results.inject({}) {|outcome, data| outcome[data["name"]] = data["fql_result_set"]; outcome}
-        end
-      end
-      
+      # Set a Facebook application's properties.
+      # 
+      # @param properties a hash of properties you want to update with their new values.
+      # @param (see #rest_call)
+      # @param options (see #rest_call)
+      #
+      # @return true if successful, false if not.  (This call currently doesn't give useful feedback on failure.)
       def set_app_properties(properties, args = {}, options = {})
         raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "setAppProperties requires an access token"}) unless @access_token
         rest_call("admin.setAppProperties", args.merge(:properties => MultiJson.encode(properties)), options, "post")
       end
 
-      def rest_call(fb_method, args = {}, options = {}, method = "get")
+      # Make a call to the REST API. 
+      #
+      # @note The order of the last two arguments is non-standard (for historical reasons).  Sorry.
+      # 
+      # @param fb_method the API call you want to make
+      # @param args (see Koala::Facebook::GraphAPIMethods#graph_call)
+      # @param options (see Koala::Facebook::GraphAPIMethods#graph_call)
+      # @param verb (see Koala::Facebook::GraphAPIMethods#graph_call)
+      # 
+      # @raise [Koala::Facebook::APIError] if Facebook returns an error
+      # 
+      # @return the result from Facebook
+      def rest_call(fb_method, args = {}, options = {}, verb = "get")
+        Koala::Utils.deprecate("The REST API is now deprecated; please use the equivalent Graph API methods instead.  See http://developers.facebook.com/blog/post/616/.")
+
         options = options.merge!(:rest_api => true, :read_only => READ_ONLY_METHODS.include?(fb_method.to_s))
 
-        api("method/#{fb_method}", args.merge('format' => 'json'), method, options) do |response|
+        api("method/#{fb_method}", args.merge('format' => 'json'), verb, options) do |response|
           # check for REST API-specific errors
           if response.is_a?(Hash) && response["error_code"]
             raise APIError.new("type" => response["error_code"], "message" => response["error_msg"])
@@ -30,6 +50,7 @@ module Koala
         end
       end
 
+      # @private
       # read-only methods for which we can use API-read
       # taken directly from the FB PHP library (https://github.com/facebook/php-sdk/blob/master/src/facebook.php)
       READ_ONLY_METHODS = [

data/lib/koala/api.rb

@@ -0,0 +1,93 @@
+# graph_batch_api and legacy are required at the bottom, since they depend on API being defined
+require 'koala/api/graph_api'
+require 'koala/api/rest_api'
+
+module Koala
+  module Facebook
+    class API
+      # Creates a new API client.
+      # @param [String] access_token access token
+      # @note If no access token is provided, you can only access some public information.
+      # @return [Koala::Facebook::API] the API client
+      def initialize(access_token = nil)
+        @access_token = access_token
+      end
+      
+      attr_reader :access_token
+
+      include GraphAPIMethods
+      include RestAPIMethods
+      
+      # Makes a request to the appropriate Facebook API.
+      # @note You'll rarely need to call this method directly.
+      #
+      # @see GraphAPIMethods#graph_call
+      # @see RestAPIMethods#rest_call
+      #
+      # @param path the server path for this request (leading / is prepended if not present)
+      # @param args arguments to be sent to Facebook
+      # @param verb the HTTP method to use
+      # @param options request-related options for Koala and Faraday. 
+      #                See https://github.com/arsduo/koala/wiki/HTTP-Services for additional options.
+      # @option options [Symbol] :http_component which part of the response (headers, body, or status) to return
+      # @option options [Boolean] :beta use Facebook's beta tier
+      # @option options [Boolean] :use_ssl force SSL for this request, even if it's tokenless.  
+      #                                    (All API requests with access tokens use SSL.)
+      # @param error_checking_block a block to evaluate the response status for additional JSON-encoded errors 
+      #
+      # @yield The response body for evaluation
+      #
+      # @raise [Koala::Facebook::APIError] if Facebook returns an error (response status >= 500)      
+      #
+      # @return the body of the response from Facebook (unless another http_component is requested)
+      def api(path, args = {}, verb = "get", options = {}, &error_checking_block)
+        # Fetches the given path in the Graph API.
+        args["access_token"] = @access_token || @app_access_token if @access_token || @app_access_token
+
+        # add a leading /
+        path = "/#{path}" unless path =~ /^\//
+
+        # make the request via the provided service
+        result = Koala.make_request(path, args, verb, options)
+
+        # Check for any 500 errors before parsing the body
+        # since we're not guaranteed that the body is valid JSON
+        # in the case of a server error
+        raise APIError.new({"type" => "HTTP #{result.status.to_s}", "message" => "Response body: #{result.body}"}) if result.status >= 500
+
+        # parse the body as JSON and run it through the error checker (if provided)
+        # Note: Facebook sometimes sends results like "true" and "false", which aren't strictly objects
+        # and cause MultiJson.decode to fail -- so we account for that by wrapping the result in []
+        body = MultiJson.decode("[#{result.body.to_s}]")[0]
+        yield body if error_checking_block
+
+        # if we want a component other than the body (e.g. redirect header for images), return that
+        if component = options[:http_component]
+          component == :response ? result : result.send(options[:http_component])
+        else
+          body
+        end
+      end
+    end
+    
+    class APIError < StandardError
+      attr_accessor :fb_error_type, :raw_response
+
+      # Creates a new APIError. 
+      #
+      # Assigns the error type (as reported by Facebook) to #fb_error_type
+      # and the raw error response available to #raw_response.
+      #
+      # @param details error details containing "type" and "message" keys.
+      def initialize(details = {})
+        self.raw_response = details
+        self.fb_error_type = details["type"]
+        super("#{fb_error_type}: #{details["message"]}")
+      end
+    end
+  end
+end
+
+require 'koala/api/graph_batch_api'
+# legacy support for old pre-1.2 API interfaces
+require 'koala/api/legacy'

data/lib/koala/http_service/multipart_request.rb

@@ -0,0 +1,41 @@
+require 'faraday'
+
+module Koala  
+  module HTTPService
+    class MultipartRequest < Faraday::Request::Multipart
+      # Facebook expects nested parameters to be passed in a certain way
+      # Based on our testing (https://github.com/arsduo/koala/issues/125),
+      # Faraday needs two changes to make that work:
+      # 1) [] need to be escaped (e.g. params[foo]=bar ==> params%5Bfoo%5D=bar)
+      # 2) such messages need to be multipart-encoded
+    
+      self.mime_type = 'multipart/form-data'.freeze
+    
+      def process_request?(env)
+        # if the request values contain any hashes or arrays, multipart it
+        super || !!(env[:body].respond_to?(:values) && env[:body].values.find {|v| v.is_a?(Hash) || v.is_a?(Array)})
+      end   
+    
+    
+      def process_params(params, prefix = nil, pieces = nil, &block)
+        params.inject(pieces || []) do |all, (key, value)|
+          key = "#{prefix}%5B#{key}%5D" if prefix
+
+          case value
+          when Array
+            values = value.inject([]) { |a,v| a << [nil, v] }
+            process_params(values, key, all, &block)
+          when Hash
+            process_params(value, key, all, &block)
+          else
+            all << block.call(key, value)
+          end
+        end
+      end
+    end
+  end
+  
+  # @private
+  # legacy support for when MultipartRequest lived directly under Koala
+  MultipartRequest = HTTPService::MultipartRequest  
+end

data/lib/koala/http_service/response.rb

@@ -0,0 +1,18 @@
+module Koala
+  module HTTPService
+    class Response
+      attr_reader :status, :body, :headers
+
+      # Creates a new Response object, which standardizes the response received by Facebook for use within Koala.
+      def initialize(status, body, headers)
+        @status = status
+        @body = body
+        @headers = headers
+      end
+    end
+  end
+  
+  # @private
+  # legacy support for when Response lived directly under Koala
+  Response = HTTPService::Response
+end

data/lib/koala/http_service/uploadable_io.rb

@@ -0,0 +1,187 @@
+require "net/http/post/multipart"
+
+module Koala
+  module HTTPService
+    class UploadableIO
+      attr_reader :io_or_path, :content_type, :filename
+
+      def initialize(io_or_path_or_mixed, content_type = nil, filename = nil)
+        # see if we got the right inputs
+        parse_init_mixed_param io_or_path_or_mixed, content_type
+
+        # filename is used in the Ads API
+        # if it's provided, take precedence over the detected filename
+        # otherwise, fall back to a dummy name
+        @filename = filename || @filename || "koala-io-file.dum"
+
+        raise KoalaError.new("Invalid arguments to initialize an UploadableIO") unless @io_or_path
+        raise KoalaError.new("Unable to determine MIME type for UploadableIO") if !@content_type
+      end
+
+      def to_upload_io
+        UploadIO.new(@io_or_path, @content_type, @filename)
+      end
+
+      def to_file
+        @io_or_path.is_a?(String) ? File.open(@io_or_path) : @io_or_path
+      end
+
+      def self.binary_content?(content)
+        content.is_a?(UploadableIO) || DETECTION_STRATEGIES.detect {|method| send(method, content)}
+      end
+
+      private
+      DETECTION_STRATEGIES = [
+        :sinatra_param?,
+        :rails_3_param?,
+        :file_param?
+      ]
+
+      PARSE_STRATEGIES = [
+        :parse_rails_3_param,
+        :parse_sinatra_param,
+        :parse_file_object,
+        :parse_string_path,
+        :parse_io
+      ]
+
+      def parse_init_mixed_param(mixed, content_type = nil)
+        PARSE_STRATEGIES.each do |method|
+          send(method, mixed, content_type)
+          return if @io_or_path && @content_type
+        end
+      end
+
+      # Expects a parameter of type ActionDispatch::Http::UploadedFile
+      def self.rails_3_param?(uploaded_file)
+        uploaded_file.respond_to?(:content_type) and uploaded_file.respond_to?(:tempfile) and uploaded_file.tempfile.respond_to?(:path)
+      end
+
+      def parse_rails_3_param(uploaded_file, content_type = nil)
+        if UploadableIO.rails_3_param?(uploaded_file)
+          @io_or_path = uploaded_file.tempfile.path
+          @content_type = content_type || uploaded_file.content_type
+          @filename = uploaded_file.original_filename
+        end
+      end
+
+      # Expects a Sinatra hash of file info
+      def self.sinatra_param?(file_hash)
+        file_hash.kind_of?(Hash) and file_hash.has_key?(:type) and file_hash.has_key?(:tempfile)
+      end
+
+      def parse_sinatra_param(file_hash, content_type = nil)
+        if UploadableIO.sinatra_param?(file_hash)
+          @io_or_path = file_hash[:tempfile]
+          @content_type = content_type || file_hash[:type] || detect_mime_type(tempfile)
+          @filename = file_hash[:filename]
+        end
+      end
+
+      # takes a file object
+      def self.file_param?(file)
+        file.kind_of?(File)
+      end
+
+      def parse_file_object(file, content_type = nil)
+        if UploadableIO.file_param?(file)
+          @io_or_path = file
+          @content_type = content_type || detect_mime_type(file.path)
+          @filename = File.basename(file.path)
+        end
+      end
+
+      def parse_string_path(path, content_type = nil)
+        if path.kind_of?(String)
+          @io_or_path = path
+          @content_type = content_type || detect_mime_type(path)
+          @filename = File.basename(path)
+        end
+      end
+
+      def parse_io(io, content_type = nil)
+        if io.respond_to?(:read)
+          @io_or_path = io
+          @content_type = content_type
+        end
+      end
+
+      MIME_TYPE_STRATEGIES = [
+        :use_mime_module,
+        :use_simple_detection
+      ]
+
+      def detect_mime_type(filename)
+        if filename
+          MIME_TYPE_STRATEGIES.each do |method|
+            result = send(method, filename)
+            return result if result
+          end
+        end
+        nil # if we can't find anything
+      end
+
+      def use_mime_module(filename)
+        # if the user has installed mime/types, we can use that
+        # if not, rescue and return nil
+        begin
+          type = MIME::Types.type_for(filename).first
+          type ? type.to_s : nil
+        rescue
+          nil
+        end
+      end
+
+      def use_simple_detection(filename)
+        # very rudimentary extension analysis for images
+        # first, get the downcased extension, or an empty string if it doesn't exist
+        extension = ((filename.match(/\.([a-zA-Z0-9]+)$/) || [])[1] || "").downcase
+        case extension
+          when ""
+            nil
+          # images
+          when "jpg", "jpeg"
+            "image/jpeg"
+          when "png"
+            "image/png"
+          when "gif"
+            "image/gif"
+
+          # video
+          when "3g2"
+          	"video/3gpp2"
+          when "3gp", "3gpp"
+          	"video/3gpp"
+          when "asf"
+          	"video/x-ms-asf"
+          when "avi"
+          	"video/x-msvideo"
+          when "flv"
+          	"video/x-flv"
+          when "m4v"
+          	"video/x-m4v"
+          when "mkv"
+          	"video/x-matroska"
+          when "mod"
+          	"video/mod"
+          when "mov", "qt"
+          	"video/quicktime"
+          when "mp4", "mpeg4"
+          	"video/mp4"
+          when "mpe", "mpeg", "mpg", "tod", "vob"
+          	"video/mpeg"
+          when "nsv"
+          	"application/x-winamp"
+          when "ogm", "ogv"
+          	"video/ogg"
+          when "wmv"
+          	"video/x-ms-wmv"
+        end
+      end
+    end
+  end
+  
+  # @private
+  # legacy support for when UploadableIO lived directly under Koala
+  UploadableIO = HTTPService::UploadableIO
+end