koala 1.3.0rc1 → 1.3.0rc2

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
@@ -45,6 +40,15 @@ module Koala
         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,16 +2,45 @@ module Koala
   module Facebook
     REST_SERVER = "api.facebook.com"
 
-    module RestAPIMethods      
+    # 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
+      # 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")
         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"])
@@ -19,6 +48,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/http_service.rb

@@ -1,29 +1,37 @@
 require 'faraday'
+require 'koala/http_service/multipart_request'
+require 'koala/http_service/uploadable_io'
+require 'koala/http_service/response'
 
 module Koala
-  class Response
-    attr_reader :status, :body, :headers
-    def initialize(status, body, headers)
-      @status = status
-      @body = body
-      @headers = headers
-    end
-  end
-
-  module HTTPService
+  module HTTPService    
     class << self
-
-      attr_accessor :faraday_middleware, :http_options
+      # A customized stack of Faraday middleware that will be used to make each request.
+      attr_accessor :faraday_middleware
+      # A default set of HTTP options (see https://github.com/arsduo/koala/wiki/HTTP-Services)
+      attr_accessor :http_options
     end
 
     @http_options ||= {}
     
+    # Koala's default middleware stack. 
+    # We encode requests in a Facebook-compatible multipart request, 
+    # and use whichever adapter has been configured for this application.
     DEFAULT_MIDDLEWARE = Proc.new do |builder|
-      builder.use Koala::MultipartRequest
+      builder.use Koala::HTTPService::MultipartRequest
       builder.request :url_encoded
       builder.adapter Faraday.default_adapter
     end
 
+    # The address of the appropriate Facebook server.
+    #
+    # @param options various flags to indicate which server to use.
+    # @option options :rest_api use the old REST API instead of the Graph API
+    # @option options :video use the server designated for video uploads
+    # @option options :beta use the beta tier
+    # @option options :use_ssl force https, even if not needed
+    # 
+    # @return a complete server address with protocol
     def self.server(options = {})
       server = "#{options[:rest_api] ? Facebook::REST_SERVER : Facebook::GRAPH_SERVER}"
       server.gsub!(/\.facebook/, "-video.facebook") if options[:video]
@@ -31,6 +39,23 @@ module Koala
       "#{options[:use_ssl] ? "https" : "http"}://#{server}"
     end
 
+    # Makes a request directly to Facebook.
+    # @note You'll rarely need to call this method directly.
+    #
+    # @see Koala::Facebook::API#api
+    # @see Koala::Facebook::GraphAPIMethods#graph_call
+    # @see Koala::Facebook::RestAPIMethods#rest_call
+    #
+    # @param path the server path for this request
+    # @param args (see Koala::Facebook::API#api)
+    # @param verb the HTTP method to use.  
+    #             If not get or post, this will be turned into a POST request with the appropriate :method
+    #             specified in the arguments.           
+    # @param options (see Koala::Facebook::API#api)
+    #
+    # @raise an appropriate connection error if unable to make the request to Facebook
+    #
+    # @return [Koala::HTTPService::Response] a response object representing the results from Facebook
     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"
@@ -47,13 +72,20 @@ module Koala
       conn = Faraday.new(server(request_options), request_options, &(faraday_middleware || DEFAULT_MIDDLEWARE))
 
       response = conn.send(verb, path, (verb == "post" ? params : {}))
-      Koala::Response.new(response.status.to_i, response.body, response.headers)
-    end
-
+      Koala::HTTPService::Response.new(response.status.to_i, response.body, response.headers)
+    end
+
+    # Encodes a given hash into a query string.  
+    # This is used mainly by the Batch API nowadays, since Faraday handles this for regular cases.
+    # 
+    # @param params_hash a hash of values to CGI-encode and appropriately join
+    # 
+    # @example
+    #   Koala.http_service.encode_params({:a => 2, :b => "My String"})
+    #   => "a=2&b=My+String"
+    #
+    # @return the appropriately-encoded string
     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
-      # this is used mainly by the Batch API nowadays
       ((param_hash || {}).collect do |key_and_value|
         key_and_value[1] = MultiJson.encode(key_and_value[1]) unless key_and_value[1].is_a? String
         "#{key_and_value[0].to_s}=#{CGI.escape key_and_value[1]}"
@@ -63,76 +95,92 @@ module Koala
     # deprecations
     # not elegant or compact code, but temporary
     
+    # @private
     def self.always_use_ssl
       Koala::Utils.deprecate("HTTPService.always_use_ssl is now HTTPService.http_options[:use_ssl]; always_use_ssl will be removed in a future version.")
       http_options[:use_ssl]
     end
 
+    # @private
     def self.always_use_ssl=(value)
       Koala::Utils.deprecate("HTTPService.always_use_ssl is now HTTPService.http_options[:use_ssl]; always_use_ssl will be removed in a future version.")
       http_options[:use_ssl] = value
     end
     
+    # @private
     def self.timeout
       Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
       http_options[:timeout]
     end
 
+    # @private
     def self.timeout=(value)
       Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
       http_options[:timeout] = value
     end
     
+    # @private
     def self.timeout
       Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
       http_options[:timeout]
     end
 
+    # @private
     def self.timeout=(value)
       Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
       http_options[:timeout] = value
     end
     
+    # @private
     def self.proxy
       Koala::Utils.deprecate("HTTPService.proxy is now HTTPService.http_options[:proxy]; .proxy will be removed in a future version.")
       http_options[:proxy]
     end
 
+    # @private
     def self.proxy=(value)
       Koala::Utils.deprecate("HTTPService.proxy is now HTTPService.http_options[:proxy]; .proxy will be removed in a future version.")
       http_options[:proxy] = value
     end
     
+    # @private
     def self.ca_path
       Koala::Utils.deprecate("HTTPService.ca_path is now (HTTPService.http_options[:ssl] ||= {})[:ca_path]; .ca_path will be removed in a future version.")
       (http_options[:ssl] || {})[:ca_path]
     end
 
+    # @private
     def self.ca_path=(value)
       Koala::Utils.deprecate("HTTPService.ca_path is now (HTTPService.http_options[:ssl] ||= {})[:ca_path]; .ca_path will be removed in a future version.")
       (http_options[:ssl] ||= {})[:ca_path] = value
     end
     
+    # @private
     def self.ca_file
       Koala::Utils.deprecate("HTTPService.ca_file is now (HTTPService.http_options[:ssl] ||= {})[:ca_file]; .ca_file will be removed in a future version.")
       (http_options[:ssl] || {})[:ca_file]
     end
 
+    # @private
     def self.ca_file=(value)
       Koala::Utils.deprecate("HTTPService.ca_file is now (HTTPService.http_options[:ssl] ||= {})[:ca_file]; .ca_file will be removed in a future version.")
       (http_options[:ssl] ||= {})[:ca_file] = value
     end
 
+    # @private
     def self.verify_mode
       Koala::Utils.deprecate("HTTPService.verify_mode is now (HTTPService.http_options[:ssl] ||= {})[:verify_mode]; .verify_mode will be removed in a future version.")
       (http_options[:ssl] || {})[:verify_mode]
     end
 
+    # @private
     def self.verify_mode=(value)
       Koala::Utils.deprecate("HTTPService.verify_mode is now (HTTPService.http_options[:ssl] ||= {})[:verify_mode]; .verify_mode will be removed in a future version.")
       (http_options[:ssl] ||= {})[:verify_mode] = value
     end
 
+    private 
+    
     def self.process_options(options)
       if typhoeus_options = options.delete(:typhoeus_options)
         Koala::Utils.deprecate("typhoeus_options should now be included directly in the http_options hash.  Support for this key will be removed in a future version.")
@@ -158,6 +206,7 @@ module Koala
     end   
   end
   
+  # @private
   module TyphoeusService
     def self.deprecated_interface
       # support old-style interface with a warning
@@ -166,6 +215,7 @@ module Koala
     end
   end
 
+  # @private
   module NetHTTPService
     def self.deprecated_interface
       # support old-style interface with a warning