koala 0.4 → 3.7.0

data/lib/koala/api/graph_collection.rb

@@ -0,0 +1,129 @@
+require 'addressable/uri'
+require 'cgi'
+
+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
+        # The raw summary information from Facebook (total counts).
+        attr_reader :summary
+        # @return [Koala::Facebook::GraphAPI] the api used to make requests.
+        attr_reader :api
+        # The entire raw response from Facebook.
+        attr_reader :raw_response
+        # The headers from the Facebook response
+        attr_reader :headers
+
+        # Initialize the array of results and store various additional paging-related information.
+        #
+        # @param [Koala::HTTPService::Response] response object wrapping the raw Facebook response
+        # @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::API::GraphCollection] an initialized GraphCollection
+        #         whose paging, summary, raw_response, and api attributes are populated.
+        def initialize(response, api)
+          super response.data["data"]
+          @paging = response.data["paging"]
+          @summary = response.data["summary"]
+          @raw_response = response.data
+          @api = api
+          @headers = response.headers
+        end
+
+        # @private
+        # Turn the response into a GraphCollection if they're pageable;
+        # if not, return the data of 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)
+          return nil if response.nil?
+
+          is_pageable?(response) ? self.new(response, api) : response.data
+        end
+
+        # response will always be an instance of Koala::HTTPService::Response
+        # since that is what we get from Koala::Facebook::API#api
+        def self.is_pageable?(response)
+          response.data.is_a?(Hash) && response.data["data"].is_a?(Array)
+        end
+
+        # Retrieve the next page of results.
+        #
+        # @param [Hash] extra_params Some optional extra parameters for paging. For supported parameters see https://developers.facebook.com/docs/reference/api/pagination/
+        #
+        # @example With optional extra params
+        #    wall = api.get_connections("me", "feed", since: 1379593891)
+        #    wall.next_page(since: 1379593891)
+        #
+        # @return a GraphCollection array of additional results (an empty array if there are no more results)
+        def next_page(extra_params = {})
+          base, args = next_page_params
+          base ? @api.get_page([base, args.merge(extra_params)]) : nil
+        end
+
+        # Retrieve the previous page of results.
+        #
+        # @param [Hash] extra_params Some optional extra parameters for paging. For supported parameters see https://developers.facebook.com/docs/reference/api/pagination/
+        #
+        # @return a GraphCollection array of additional results (an empty array if there are no earlier results)
+        def previous_page(extra_params = {})
+          base, args = previous_page_params
+          base ? @api.get_page([base, args.merge(extra_params)]) : 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)
+          uri = Addressable::URI.parse(url)
+
+          base = uri.path.sub(/^\//, '')
+          params = CGI.parse(uri.query)
+
+          new_params = {}
+          params.each_pair do |key,value|
+            new_params[key] = value.join ","
+          end
+          [base,new_params]
+        end
+      end
+    end
+  end
+end

data/lib/koala/api/graph_error_checker.rb

@@ -0,0 +1,72 @@
+module Koala
+  module Facebook
+    # This class, given a Koala::HTTPService::Response object, will check for Graph API-specific
+    # errors. This returns an error of the appropriate type which can be immediately raised
+    # (non-batch) or added to the list of batch results (batch)
+    class GraphErrorChecker
+      attr_reader :http_status, :body, :headers
+      def initialize(http_status, body, headers)
+        @http_status = http_status.to_i
+        @body = body
+        @headers = headers
+      end
+
+      # Facebook has a set of standardized error codes, some of which represent problems with the
+      # token.
+      AUTHENTICATION_ERROR_CODES = [102, 190, 450, 452, 2500]
+
+      # Facebook can return debug information in the response headers -- see
+      # https://developers.facebook.com/docs/graph-api/using-graph-api#bugdebug
+      DEBUG_HEADERS = %w[x-fb-debug x-fb-rev x-fb-trace-id x-business-use-case-usage x-ad-account-usage x-app-usage]
+
+      def error_if_appropriate
+        if http_status >= 400
+          error_class.new(http_status, body, error_info)
+        end
+      end
+
+      protected
+
+      def error_class
+        if auth_error?
+          # See: https://developers.facebook.com/docs/authentication/access-token-expiration/
+          #      https://developers.facebook.com/bugs/319643234746794?browse=search_4fa075c0bd9117b20604672
+          AuthenticationError
+        else
+          ClientError
+        end
+      end
+
+      def auth_error?
+        # tbh, I'm not sure why we restrict Facebook-reported OAuthExceptions to only those without
+        # codes or whose codes match the list above -- let's investigate changing this later.
+        error_info['type'] == 'OAuthException' &&
+          (!error_info['code'] || AUTHENTICATION_ERROR_CODES.include?(error_info['code'].to_i))
+      end
+
+      def error_info
+        # Build up the complete error info from whatever Facebook gives us plus the header
+        # information
+        @error_info ||= DEBUG_HEADERS.inject(base_error_info) do |hash, error_key|
+          hash[error_key] = headers[error_key] if headers[error_key]
+          hash
+        end
+      end
+
+      def base_error_info
+        response_hash['error'] || {}
+      end
+
+      def response_hash
+        # Normally, we start with the response body. If it isn't valid JSON, we start with an empty
+        # hash and fill it with error data.
+        @response_hash ||= begin
+          parsed_body = JSON.parse(body)
+          parsed_body.is_a?(Hash) ? parsed_body : {}
+        rescue JSON::ParserError
+          {}
+        end
+      end
+    end
+  end
+end

data/lib/koala/api.rb

@@ -0,0 +1,159 @@
+# graph_batch_api and legacy are required at the bottom, since they depend on API being defined
+require 'koala/api/graph_api_methods'
+require 'koala/api/graph_collection'
+require 'openssl'
+
+module Koala
+  module Facebook
+    class API
+      # Creates a new API client.
+      # @param [String] access_token access token
+      # @param [String] app_secret app secret, for tying your access tokens to your app secret
+      #                 If you provide an app secret, your requests will be
+      #                 signed by default, unless you pass appsecret_proof:
+      #                 false as an option to the API call. (See
+      #                 https://developers.facebook.com/docs/graph-api/securing-requests/)
+      # @param [Block]  rate_limit_hook block called with limits received in facebook response headers
+      # @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 = Koala.config.access_token, app_secret = Koala.config.app_secret, rate_limit_hook = Koala.config.rate_limit_hook)
+        @access_token = access_token
+        @app_secret = app_secret
+        @rate_limit_hook = rate_limit_hook
+      end
+
+      attr_reader :access_token, :app_secret, :rate_limit_hook
+
+      include GraphAPIMethods
+
+      # Make a call directly to the Graph API.
+      # (See any of the other methods for example invocations.)
+      #
+      # @param path the Graph API path to query (no leading / needed)
+      # @param args (see #get_object)
+      # @param verb the type of HTTP request to make (get, post, delete, etc.)
+      # @options (see #get_object)
+      #
+      # @yield response when making a batch API call, you can pass in a block
+      #        that parses the results, allowing for cleaner code.
+      #        The block's return value is returned in the batch results.
+      #        See the code for {#get_picture} for examples.
+      #        (Not needed in regular calls; you'll probably rarely use this.)
+      #
+      # @raise [Koala::Facebook::APIError] if Facebook returns an error
+      #
+      # @return the result from Facebook
+      def graph_call(path, args = {}, verb = "get", options = {}, &post_processing)
+        # enable appsecret_proof by default
+        options = {:appsecret_proof => true}.merge(options) if @app_secret
+        response = api(path, args, verb, options)
+
+        error = GraphErrorChecker.new(response.status, response.body, response.headers).error_if_appropriate
+        raise error if error
+
+        # if we want a component other than the body (e.g. redirect header for images), provide that
+        http_component = options[:http_component]
+        desired_data = if options[:http_component]
+          http_component == :response ? response : response.send(http_component)
+        else
+          # turn this into a GraphCollection if it's pageable
+          API::GraphCollection.evaluate(response, self)
+        end
+
+        if rate_limit_hook
+          limits = %w(x-business-use-case-usage x-ad-account-usage x-app-usage).each_with_object({}) do |key, hash|
+            value = response.headers.fetch(key, nil)
+            next unless value
+            hash[key] = JSON.parse(response.headers[key])
+          rescue JSON::ParserError => e
+            Koala::Utils.logger.error("#{e.class}: #{e.message} while parsing #{key} = #{value}")
+          end
+
+          rate_limit_hook.call(limits) if limits.keys.any?
+        end
+
+        # now process as appropriate for the given call (get picture header, etc.)
+        post_processing ? post_processing.call(desired_data) : desired_data
+      end
+
+
+      # Makes a request to the appropriate Facebook API.
+      # @note You'll rarely need to call this method directly.
+      #
+      # @see GraphAPIMethods#graph_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 [Symbol] :format which request format to use. Currently, :json is supported
+      # @option options [Symbol] :preserve_form_arguments preserve arrays in arguments, which are
+      #                          expected by certain FB APIs (see the ads API in particular,
+      #                          https://developers.facebook.com/docs/marketing-api/adgroup/v2.4)
+      # @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.)
+      # @raise [Koala::Facebook::ServerError] if Facebook returns an error (response status >= 500)
+      #
+      # @return a Koala::HTTPService::Response object representing the returned Facebook data
+      def api(path, args = {}, verb = "get", options = {})
+        # we make a copy of args so the modifications (added access_token & appsecret_proof)
+        # do not affect the received argument
+        args = args.dup
+
+        # If a access token is explicitly provided, use that
+        # This is explicitly needed in batch requests so GraphCollection
+        # results preserve any specific access tokens provided
+        args["access_token"] ||= @access_token || @app_access_token if @access_token || @app_access_token
+
+        if options.delete(:appsecret_proof) && args["access_token"] && @app_secret
+          args["appsecret_proof"] = OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new("sha256"), @app_secret, args["access_token"])
+        end
+
+        # Translate any arrays in the params into comma-separated strings
+        args = sanitize_request_parameters(args) unless preserve_form_arguments?(options)
+
+        # add a leading / if needed...
+        path = "/#{path}" unless path.to_s =~ /^\//
+
+        # make the request via the provided service
+        result = Koala.make_request(path, args, verb, options)
+
+        if result.status.to_i >= 500
+          raise Koala::Facebook::ServerError.new(result.status.to_i, result.body)
+        end
+
+        result
+      end
+
+      private
+
+      # Sanitizes Ruby objects into Facebook-compatible string values.
+      #
+      # @param parameters a hash of parameters.
+      #
+      # Returns a hash in which values that are arrays of non-enumerable values
+      #         (Strings, Symbols, Numbers, etc.) are turned into comma-separated strings.
+      def sanitize_request_parameters(parameters)
+        parameters.reduce({}) do |result, (key, value)|
+          # if the parameter is an array that contains non-enumerable values,
+          # turn it into a comma-separated list
+          # in Ruby 1.8.7, strings are enumerable, but we don't care
+          if value.is_a?(Array) && value.none? {|entry| entry.is_a?(Enumerable) && !entry.is_a?(String)}
+            value = value.join(",")
+          end
+          result.merge(key => value)
+        end
+      end
+
+      def preserve_form_arguments?(options)
+        options[:format] == :json || options[:preserve_form_arguments] || Koala.config.preserve_form_arguments
+      end
+
+      def check_response(http_status, body, headers)
+      end
+    end
+  end
+end

data/lib/koala/configuration.rb

@@ -0,0 +1,56 @@
+# Global configuration for Koala.
+class Koala::Configuration
+  # The default access token to be used if none is otherwise supplied.
+  attr_accessor :access_token
+
+  # The default app secret value to be used if none is otherwise supplied.
+  attr_accessor :app_secret
+
+  # The default application ID to use if none is otherwise supplied.
+  attr_accessor :app_id
+
+  # The default app access token to be used if none is otherwise supplied.
+  attr_accessor :app_access_token
+
+  # The default API version to use if none is otherwise specified.
+  attr_accessor :api_version
+
+  # The default value to use for the oauth_callback_url if no other is provided.
+  attr_accessor :oauth_callback_url
+
+  # Whether to preserve arrays in arguments, which are expected by certain FB APIs (see the ads API
+  # in particular, https://developers.facebook.com/docs/marketing-api/adgroup/v2.4)
+  attr_accessor :preserve_form_arguments
+
+  # The server to use for Graph API requests
+  attr_accessor :graph_server
+
+  # The server to use when constructing dialog URLs.
+  attr_accessor :dialog_host
+
+  # Whether or not to mask tokens
+  attr_accessor :mask_tokens
+
+  # Called with the info for the rate limits in the response header
+  attr_accessor :rate_limit_hook
+
+  # Certain Facebook services (beta, video) require you to access different
+  # servers. If you're using your own servers, for instance, for a proxy,
+  # you can change both the matcher (what value to change when updating the URL) and the
+  # replacement values (what to add).
+  #
+  # So, for instance, to use the beta stack, we match on .facebook and change it to .beta.facebook.
+  # If you're talking to fbproxy.mycompany.com, you could set up beta.fbproxy.mycompany.com for
+  # FB's beta tier, and set the matcher to /\.fbproxy/ and the beta_replace to '.beta.fbproxy'.
+  attr_accessor :host_path_matcher
+  attr_accessor :video_replace
+  attr_accessor :beta_replace
+
+  def initialize
+    # Default to our default values.
+    Koala::HTTPService::DEFAULT_SERVERS.each_pair do |key, value|
+      self.public_send("#{key}=", value)
+    end
+    self.mask_tokens = true
+  end
+end

data/lib/koala/errors.rb

@@ -0,0 +1,126 @@
+module Koala
+
+  class KoalaError < StandardError; end
+
+  module Facebook
+
+    # The OAuth signature is incomplete, invalid, or using an unsupported algorithm
+    class OAuthSignatureError < ::Koala::KoalaError; end
+
+    # Required for realtime updates validation
+    class AppSecretNotDefinedError < ::Koala::KoalaError; end
+
+    # Facebook responded with an error to an API request. If the exception contains a nil
+    # http_status, then the error was detected before making a call to Facebook. (e.g. missing access token)
+    class APIError < ::Koala::KoalaError
+      attr_accessor :http_status,
+                    :response_body,
+                    :fb_error_type,
+                    :fb_error_code,
+                    :fb_error_subcode,
+                    :fb_error_message,
+                    :fb_error_user_msg,
+                    :fb_error_user_title,
+                    :fb_error_trace_id,
+                    :fb_error_debug_trace_id,
+                    :fb_error_debug,
+                    :fb_error_rev,
+                    :fb_buc_usage,
+                    :fb_ada_usage,
+                    :fb_app_usage
+
+      # Create a new API Error
+      #
+      # @param http_status [Integer] The HTTP status code of the response
+      # @param response_body [String] The response body
+      # @param error_info One of the following:
+      #                   [Hash] The error information extracted from the request
+      #                          ("type", "code", "error_subcode", "message")
+      #                   [String] The error description
+      #                   If error_info is nil or not provided, the method will attempt to extract
+      #                   the error info from the response_body
+      #
+      # @return the newly created APIError
+      def initialize(http_status, response_body, error_info = nil)
+        if response_body
+          self.response_body = response_body.strip
+        else
+          self.response_body = ''
+        end
+        self.http_status = http_status
+
+        if error_info && error_info.is_a?(String)
+          message = error_info
+        else
+          unless error_info
+            begin
+              error_info = JSON.parse(response_body)['error'] if response_body
+            rescue
+            end
+            error_info ||= {}
+          end
+
+          self.fb_error_type = error_info["type"]
+          self.fb_error_code = error_info["code"]
+          self.fb_error_subcode = error_info["error_subcode"]
+          self.fb_error_message = error_info["message"]
+          self.fb_error_user_msg = error_info["error_user_msg"]
+          self.fb_error_user_title = error_info["error_user_title"]
+          self.fb_error_trace_id = error_info["fbtrace_id"]
+
+          self.fb_error_debug_trace_id = error_info["x-fb-trace-id"]
+          self.fb_error_debug = error_info["x-fb-debug"]
+          self.fb_error_rev = error_info["x-fb-rev"]
+          self.fb_buc_usage = json_parse_for(error_info, "x-business-use-case-usage")
+          self.fb_ada_usage = json_parse_for(error_info, "x-ad-account-usage")
+          self.fb_app_usage = json_parse_for(error_info, "x-app-usage")
+
+          error_array = []
+          %w(type code error_subcode message error_user_title error_user_msg fbtrace_id x-fb-trace-id x-fb-debug x-fb-rev).each do |key|
+            error_array << "#{key}: #{error_info[key]}" if error_info[key]
+          end
+
+          if error_array.empty?
+            message = self.response_body
+          else
+            message = error_array.join(', ')
+          end
+        end
+        message += " [HTTP #{http_status}]" if http_status
+
+        super(message)
+      end
+
+      private
+
+      # refs: https://developers.facebook.com/docs/graph-api/overview/rate-limiting/#headers
+      # NOTE: The header will contain a JSON-formatted string that describes current application rate limit usage.
+      def json_parse_for(error_info, key)
+        string = error_info[key]
+        return if string.nil?
+
+        JSON.parse(string)
+      rescue JSON::ParserError => e
+        Koala::Utils.logger.error("#{e.class}: #{e.message} while parsing #{key} = #{string}")
+        nil
+      end
+    end
+
+    # Facebook returned an invalid response body
+    class BadFacebookResponse < APIError; end
+
+    # Facebook responded with an error while attempting to request an access token
+    class OAuthTokenRequestError < APIError; end
+
+    # Any error with a 5xx HTTP status code
+    class ServerError < APIError; end
+
+    # Any error with a 4xx HTTP status code
+    class ClientError < APIError; end
+
+    # All graph API authentication failures.
+    class AuthenticationError < ClientError; end
+
+  end
+
+end

data/lib/koala/http_service/request.rb

@@ -0,0 +1,133 @@
+module Koala
+  module HTTPService
+    class Request
+      attr_reader :raw_path, :raw_args, :raw_verb, :raw_options
+
+      # @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 various flags to indicate which server to use. (see Koala::Facebook::API#api)
+      # @param options
+      # @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
+      # @option options :json whether or not to send JSON to Facebook
+      def initialize(path:, verb:, args: {}, options: {})
+        @raw_path = path
+        @raw_args = args
+        @raw_verb = verb
+        @raw_options = options
+      end
+
+      # Determines which type of request to send to Facebook. Facebook natively accepts GETs and POSTs, for others we have to include the method in the post body.
+      #
+      # @return one of get or post
+      def verb
+        ["get", "post"].include?(raw_verb) ? raw_verb : "post"
+      end
+
+      # Determines the path to be requested on Facebook, incorporating an API version if specified.
+      #
+      # @return the original path, with API version if appropriate.
+      def path
+        # if an api_version is specified and the path does not already contain
+        # one, prepend it to the path
+        api_version = raw_options[:api_version] || Koala.config.api_version
+        if api_version && !path_contains_api_version?
+          begins_with_slash = raw_path[0] == "/"
+          divider = begins_with_slash ? "" : "/"
+          "/#{api_version}#{divider}#{raw_path}"
+        else
+          raw_path
+        end
+      end
+
+      # Determines any arguments to be sent in a POST body.
+      #
+      # @return {} for GET; the provided args for POST; those args with the method parameter for
+      # other values
+      def post_args
+        if raw_verb == "get"
+          {}
+        elsif raw_verb == "post"
+          args
+        else
+          args.merge(method: raw_verb)
+        end
+      end
+
+      def get_args
+        raw_verb == "get" ? args : {}
+      end
+
+      # Calculates a set of request options to pass to Faraday.
+      #
+      # @return a hash combining GET parameters (if appropriate), default options, and
+      # any specified for the request.
+      def options
+        # figure out our options for this request
+        add_ssl_options(
+          # for GETs, we pass the params to Faraday to encode
+          {params: get_args}.merge(HTTPService.http_options).merge(raw_options)
+        )
+      end
+
+      # Whether or not this request should use JSON.
+      #
+      # @return true or false
+      def json?
+        raw_options[:format] == :json
+      end
+
+      # The address of the appropriate Facebook server.
+      #
+      # @return a complete server address with protocol
+      def server
+        uri = "#{options[:use_ssl] ? "https" : "http"}://#{Koala.config.graph_server}"
+        # if we want to use the beta tier or the video server, make those substitutions as
+        # appropriate
+        replace_server_component(
+          replace_server_component(uri, options[:video], Koala.config.video_replace),
+          options[:beta],
+          Koala.config.beta_replace
+        )
+      end
+
+      protected
+
+      # The arguments to include in the request.
+      def args
+        raw_args.inject({}) do |hash, (key, value)|
+          # Resolve UploadableIOs into data Facebook can work with
+          hash.merge(key => value.is_a?(UploadableIO) ? value.to_upload_io : value)
+        end
+      end
+
+      def add_ssl_options(opts)
+        # require https by default (can be overriden by explicitly setting other SSL options)
+        {
+          use_ssl: true,
+          ssl: {verify: true}.merge(opts[:ssl] || {})
+        }.merge(opts)
+      end
+
+      # Determines whether a given path already contains an API version.
+      #
+      # @param path the URL path.
+      #
+      # @return true or false accordingly.
+      def path_contains_api_version?
+        # looks for "/$MAJOR[.$MINOR]/" in the path
+        match = /^\/?(v\d+(?:\.\d+)?)\//.match(raw_path)
+        !!(match && match[1])
+      end
+
+      def replace_server_component(host, condition_met, replacement)
+        return host unless condition_met
+        host.gsub(Koala.config.host_path_matcher, replacement)
+      end
+    end
+  end
+end