koala 1.4.0 → 1.5.0rc1

data/CHANGELOG

@@ -1,6 +1,26 @@
+v1.5
+New methods:
+-- Added Koala::Utils.logger to enable debugging (thanks, KentonWhite!)
+-- Expose fb_error_message and fb_error_code directly in APIError
+Updated methods:
+-- GraphCollection.parse_page_url now uses the URI library and can parse any address (thanks, bnorton!)
+Internal improvements:
+-- Update MultiJson dependency to support the Oj library (thanks, zinenko!)
+-- Loosened Faraday dependency (thanks, rewritten and romanbsd!)
+-- Fixed typos (thanks, nathanbertram!)
+-- Switched uses of put_object to the more semantically accurate put_connections
+-- Cleaned up gemspec
+-- Handle invalid batch API responses better
+Documentation:
+-- Added HTTP Services description for Faraday 0.8/persistent connections (thanks, romanbsd!)
+-- Remove documentation of the old pre-1.2 HTTP Service options
+
+v.1.4.1
+-- Update MultiJson to 1.3 and change syntax to silence warnings (thanks, eckz and masterkain!)
+
 v1.4
 New methods:
--- OAuth#exchange_access_token(_info) allows you to extend access tokens you receive (thanks,   etiennebarrie!)
+-- OAuth#exchange_access_token(_info) allows you to extend access tokens you receive (thanks, etiennebarrie!)
 Updated methods:
 -- HTTPServices#encode_params sorts parameters to aid in URL comparison (thanks, sholden!)
 -- get_connections is now aliased as get_connection (use whichever makes sense to you)

data/koala.gemspec

@@ -2,47 +2,26 @@
 $LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
 require 'koala/version'
 
-Gem::Specification.new do |s|
-  s.name    = %q{koala}
-  s.version = Koala::VERSION
-
-  s.summary     = %q{A lightweight, flexible library for Facebook with support for the Graph API, the REST API, realtime updates, and OAuth authentication.}
-  s.description = %q{Koala is a lightweight, flexible Ruby SDK for Facebook.  It allows read/write access to the social graph via the Graph and REST APIs, as well as support for realtime updates and OAuth and Facebook Connect authentication.  Koala is fully tested and supports Net::HTTP and Typhoeus connections out of the box and can accept custom modules for other services.}
-  s.homepage    = %q{http://github.com/arsduo/koala}
-
-  s.authors = ["Alex Koppel"]
-  s.email   = %q{alex@alexkoppel.com}
-
-  s.files = `git ls-files`.split("\n")
-  s.test_files = `git ls-files -- {test,spec,features}/*`.split("\n")
-
-  s.extra_rdoc_files = ["readme.md", "CHANGELOG"]
-  s.rdoc_options     = ["--line-numbers", "--inline-source", "--title", "Koala"]
-
-  s.require_paths     = ["lib"]
-
-  s.rubygems_version  = %q{1.4.2}
-
-  s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
-
-  if s.respond_to? :specification_version then
-    s.specification_version = 3
-
-    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
-      s.add_runtime_dependency(%q<multi_json>,      ["~> 1.0"])
-      s.add_runtime_dependency(%q<faraday>,  ["~> 0.7.0"])
-      s.add_development_dependency(%q<rspec>,     ["~> 2.8.0rc1"])
-      s.add_development_dependency(%q<rake>,      ["~> 0.8.7"])
-    else
-      s.add_dependency(%q<multi_json>,      ["~> 1.0"])
-      s.add_dependency(%q<rspec>,     ["~> 2.8.0rc1"])
-      s.add_dependency(%q<rake>,      ["~> 0.8.7"])
-      s.add_dependency(%q<faraday>,  ["~> 0.7.0"])
-    end
-  else
-    s.add_dependency(%q<multi_json>,      ["~> 1.0"])
-    s.add_dependency(%q<rspec>,     ["~> 2.8.0rc1"])
-    s.add_dependency(%q<rake>,      ["~> 0.8.7"])
-    s.add_dependency(%q<faraday>,  ["~> 0.7.0"])
-  end
+Gem::Specification.new do |gem|
+  gem.name        = "koala"
+  gem.summary     = "A lightweight, flexible library for Facebook with support for the Graph API, the REST API, realtime updates, and OAuth authentication."
+  gem.description = "Koala is a lightweight, flexible Ruby SDK for Facebook.  It allows read/write access to the social graph via the Graph and REST APIs, as well as support for realtime updates and OAuth and Facebook Connect authentication.  Koala is fully tested and supports Net::HTTP and Typhoeus connections out of the box and can accept custom modules for other services."
+  gem.homepage    = "http://github.com/arsduo/koala"
+  gem.version     = Koala::VERSION
+
+  gem.authors     = ["Alex Koppel"]
+  gem.email       = "alex@alexkoppel.com"
+
+  gem.require_paths  = ["lib"]
+  gem.files          = `git ls-files`.split("\n")
+  gem.test_files     = `git ls-files -- {test,spec,features}/*`.split("\n")
+  gem.executables    = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
+
+  gem.extra_rdoc_files = ["readme.md", "CHANGELOG"]
+  gem.rdoc_options     = ["--line-numbers", "--inline-source", "--title", "Koala"]
+
+  gem.add_runtime_dependency(%q<multi_json>,    ["~> 1.3"])
+  gem.add_runtime_dependency(%q<faraday>,       ["~> 0.7"])
+  gem.add_development_dependency(%q<rspec>,     ["~> 2.8"])
+  gem.add_development_dependency(%q<rake>,      ["~> 0.8"])
 end

data/lib/koala/api/graph_api.rb

@@ -72,8 +72,7 @@ module Koala
       #       Please use put_connections; in a future version of Koala (2.0?),
       #       put_object will issue a POST directly to an individual object, not to a connection.
       def put_object(parent_object, connection_name, args = {}, options = {})
-        raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Write operations require an access token"}) unless @access_token
-        graph_call("#{parent_object}/#{connection_name}", args, "post", options)
+        put_connections(parent_object, connection_name, args, options)
       end
 
       # Delete an object from the Graph if you have appropriate permissions.
@@ -115,7 +114,7 @@ module Koala
       # @note (see #get_connection)
       #
       # @example
-      #         graph.put_object("me", "feed", :message => "Hello, world")
+      #         graph.put_connections("me", "feed", :message => "Hello, world")
       #         => writes "Hello, world" to the active user's wall
       #
       # Most write operations require extended permissions. For example,
@@ -192,7 +191,7 @@ module Koala
       #
       # @return (see #put_connections)
       def put_picture(*picture_args)
-        put_object(*parse_media_args(picture_args, "photos"))
+        put_connections(*parse_media_args(picture_args, "photos"))
       end
 
       # Upload a video.  Functions exactly the same as put_picture.
@@ -200,11 +199,11 @@ module Koala
       def put_video(*video_args)
         args = parse_media_args(video_args, "videos")
         args.last[:video] = true
-        put_object(*args)
+        put_connections(*args)
       end
 
       # Write directly to the user's wall.
-      # Convenience method equivalent to put_object(id, "feed").
+      # Convenience method equivalent to put_connections(id, "feed").
       #
       # To get wall posts, use get_connections(user, "feed")
       # To delete a wall post, use delete_object(post_id)
@@ -227,7 +226,7 @@ module Koala
       # @see #put_connections
       # @return (see #put_connections)
       def put_wall_post(message, attachment = {}, target_id = "me", options = {})
-        self.put_object(target_id, "feed", attachment.merge({:message => message}), options)
+        put_connections(target_id, "feed", attachment.merge({:message => message}), options)
       end
 
       # Comment on a given object.
@@ -243,7 +242,7 @@ module Koala
       # @return (see #put_connections)
       def put_comment(id, message, options = {})
         # Writes the given comment on the given post.
-        self.put_object(id, "comments", {:message => message}, options)
+        put_connections(id, "comments", {:message => message}, options)
       end
 
       # Like a given object.
@@ -257,7 +256,7 @@ module Koala
       # @return (see #put_connections)
       def put_like(id, options = {})
         # Likes the given post.
-        self.put_object(id, "likes", {}, options)
+        put_connections(id, "likes", {}, options)
       end
 
       # Unlike a given object.
@@ -318,7 +317,7 @@ module Koala
       #
       # @return a hash of FQL results keyed to the appropriate query
       def fql_multiquery(queries = {}, args = {}, options = {})
-        if results = get_object("fql", args.merge(:q => MultiJson.encode(queries)), options)
+        if results = get_object("fql", args.merge(:q => MultiJson.dump(queries)), options)
           # simplify the multiquery result format
           results.inject({}) {|outcome, data| outcome[data["name"]] = data["fql_result_set"]; outcome}
         end
@@ -353,7 +352,7 @@ module Koala
       end
 
       def set_app_restrictions(app_id, restrictions_hash, args = {}, options = {})
-        graph_call(app_id, args.merge(:restrictions => MultiJson.encode(restrictions_hash)), "post", options)
+        graph_call(app_id, args.merge(:restrictions => MultiJson.dump(restrictions_hash)), "post", options)
       end
 
       # Certain calls such as {#get_connections} return an array of results which you can page through
@@ -447,7 +446,7 @@ module Koala
 
       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
+        # so here, we parse the arguments into a form directly usable in put_connections
         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

data/lib/koala/api/graph_batch_api.rb

@@ -41,7 +41,7 @@ module Koala
       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  
+      # 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
 
@@ -53,12 +53,18 @@ module Koala
         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["batch"] = MultiJson.dump(batch_calls.map { |batch_op|
           args.merge!(batch_op.files) if batch_op.files
           batch_op.to_batch_params(access_token)
         })
 
         batch_result = graph_call_outside_batch('/', args, 'post', http_options) do |response|
+          unless response
+            # Facebook sometimes reportedly returns an empty body at times
+            # see https://github.com/arsduo/koala/issues/184
+            raise APIError.new({"type" => "BadFacebookResponse", "message" => "Facebook returned invalid batch response: #{response.inspect}"})
+          end
+
           # 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|
@@ -68,7 +74,7 @@ module Koala
 
             if call_result
               # (see note in regular api method about JSON parsing)
-              body = MultiJson.decode("[#{call_result['body'].to_s}]")[0]
+              body = MultiJson.load("[#{call_result['body'].to_s}]")[0]
 
               unless call_result["code"].to_i >= 500 || error = check_response(body)
                 # Get the HTTP component they want
@@ -92,7 +98,7 @@ module Koala
             end
           end
         end
-        
+
         # turn any results that are pageable into GraphCollections
         batch_result.inject([]) {|processed_results, raw| processed_results << GraphCollection.evaluate(raw, @original_api)}
       end

data/lib/koala/api/graph_collection.rb

@@ -87,10 +87,11 @@ module Koala
         #
         # @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)
+          uri = 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 ","

data/lib/koala/api/rest_api.rb

@@ -22,7 +22,7 @@ module Koala
       # @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")
+        rest_call("admin.setAppProperties", args.merge(:properties => MultiJson.dump(properties)), options, "post")
       end
 
       # Make a call to the REST API. 

data/lib/koala/api.rb

@@ -12,12 +12,12 @@ module Koala
       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.
       #
@@ -27,17 +27,17 @@ module Koala
       # @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. 
+      # @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.  
+      # @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 
+      # @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)      
+      # @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)
@@ -57,8 +57,8 @@ module Koala
 
         # 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]
+        # and cause MultiJson.load to fail -- so we account for that by wrapping the result in []
+        body = MultiJson.load("[#{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
@@ -69,11 +69,11 @@ module Koala
         end
       end
     end
-    
+
     class APIError < StandardError
-      attr_accessor :fb_error_type, :raw_response
+      attr_accessor :fb_error_type, :fb_error_code, :fb_error_message, :raw_response
 
-      # Creates a new APIError. 
+      # 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.
@@ -82,6 +82,8 @@ module Koala
       def initialize(details = {})
         self.raw_response = details
         self.fb_error_type = details["type"]
+        self.fb_error_code = details["code"]
+        self.fb_error_message = details["message"]
         super("#{fb_error_type}: #{details["message"]}")
       end
     end

data/lib/koala/http_service.rb

@@ -4,7 +4,7 @@ require 'koala/http_service/uploadable_io'
 require 'koala/http_service/response'
 
 module Koala
-  module HTTPService    
+  module HTTPService
     class << self
       # A customized stack of Faraday middleware that will be used to make each request.
       attr_accessor :faraday_middleware
@@ -13,9 +13,9 @@ module Koala
     end
 
     @http_options ||= {}
-    
-    # Koala's default middleware stack. 
-    # We encode requests in a Facebook-compatible multipart request, 
+
+    # 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::HTTPService::MultipartRequest
@@ -30,7 +30,7 @@ module Koala
     # @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}"
@@ -48,9 +48,9 @@ module Koala
     #
     # @param path the server path for this request
     # @param args (see Koala::Facebook::API#api)
-    # @param verb the HTTP method to use.  
+    # @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.           
+    #             specified in the arguments.
     # @param options (see Koala::Facebook::API#api)
     #
     # @raise an appropriate connection error if unable to make the request to Facebook
@@ -63,23 +63,30 @@ module Koala
       # turn all the keys to strings (Faraday has issues with symbols under 1.8.7) and resolve UploadableIOs
       params = args.inject({}) {|hash, kv| hash[kv.first.to_s] = kv.last.is_a?(UploadableIO) ? kv.last.to_upload_io : kv.last; hash}
 
-      # figure out our options for this request   
+      # figure out our options for this request
       request_options = {:params => (verb == "get" ? params : {})}.merge(http_options || {}).merge(process_options(options))
       request_options[:use_ssl] = true if args["access_token"] # require https if there's a token
+      if request_options[:use_ssl]
+        ssl = (request_options[:ssl] ||= {})
+        ssl[:verify] = true unless ssl.has_key?(:verify)
+      end
 
       # set up our Faraday connection
       # we have to manually assign params to the URL or the
       conn = Faraday.new(server(request_options), request_options, &(faraday_middleware || DEFAULT_MIDDLEWARE))
 
       response = conn.send(verb, path, (verb == "post" ? params : {}))
+
+      # Log URL information
+      Koala::Utils.debug "#{verb.upcase}: #{path} params: #{params.inspect}"
       Koala::HTTPService::Response.new(response.status.to_i, response.body, response.headers)
     end
 
-    # Encodes a given hash into a query string.  
+    # 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"
@@ -87,14 +94,14 @@ module Koala
     # @return the appropriately-encoded string
     def self.encode_params(param_hash)
       ((param_hash || {}).sort_by{|k, v| k.to_s}.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[1] = MultiJson.dump(key_and_value[1]) unless key_and_value[1].is_a? String
         "#{key_and_value[0].to_s}=#{CGI.escape key_and_value[1]}"
       end).join("&")
     end
-    
+
     # 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.")
@@ -106,7 +113,7 @@ module Koala
       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.")
@@ -118,7 +125,7 @@ module Koala
       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.")
@@ -130,7 +137,7 @@ module Koala
       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.")
@@ -142,7 +149,7 @@ module Koala
       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.")
@@ -154,7 +161,7 @@ module Koala
       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.")
@@ -179,14 +186,14 @@ module Koala
       (http_options[:ssl] ||= {})[:verify_mode] = value
     end
 
-    private 
-    
+    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.")
         options = options.merge(typhoeus_options)
       end
-      
+
       if ca_file = options.delete(:ca_file)
         Koala::Utils.deprecate("http_options[:ca_file] should now be passed inside (http_options[:ssl] = {}) -- that is, http_options[:ssl][:ca_file].  Support for this key will be removed in a future version.")
         (options[:ssl] ||= {})[:ca_file] = ca_file
@@ -201,11 +208,11 @@ module Koala
         Koala::Utils.deprecate("http_options[:verify_mode] should now be passed inside (http_options[:ssl] = {}) -- that is, http_options[:ssl][:verify_mode].  Support for this key will be removed in a future version.")
         (options[:ssl] ||= {})[:verify_mode] = verify_mode
       end
-      
+
       options
-    end   
+    end
   end
-  
+
   # @private
   module TyphoeusService
     def self.deprecated_interface

data/lib/koala/oauth.rb

@@ -229,7 +229,7 @@ module Koala
         raise 'SignedRequest: Invalid (incomplete) signature data' unless encoded_sig && encoded_envelope
 
         signature = base64_url_decode(encoded_sig).unpack("H*").first
-        envelope = MultiJson.decode(base64_url_decode(encoded_envelope))
+        envelope = MultiJson.load(base64_url_decode(encoded_envelope))
 
         raise "SignedRequest: Unsupported algorithm #{envelope['algorithm']}" if envelope['algorithm'] != 'HMAC-SHA256'
 
@@ -260,7 +260,7 @@ module Koala
           })
         end
 
-        MultiJson.decode(response)
+        MultiJson.load(response)
       end
 
       # @deprecated (see #get_token_info_from_session_keys)
@@ -285,7 +285,7 @@ module Koala
         result = fetch_token_string(args, post, "access_token", options)
 
         # if we have an error, parse the error JSON and raise an error
-        raise APIError.new((MultiJson.decode(result)["error"] rescue nil) || {}) if result =~ /error/
+        raise APIError.new((MultiJson.load(result)["error"] rescue nil) || {}) if result =~ /error/
 
         # otherwise, parse the access token
         parse_access_token(result)
@@ -325,6 +325,7 @@ module Koala
 
           components.merge(token_info) if token_info
         else
+          Koala::Utils.logger.warn("Signed cookie didn't contain Facebook OAuth code! Components: #{components}")
           nil
         end
       end

data/lib/koala/utils.rb

@@ -1,12 +1,27 @@
 module Koala
   module Utils
 
+    # Utility methods used by Koala.
+    require 'logger'
+    require 'forwardable'
+
+    extend Forwardable
+    extend self
+
+    def_delegators :logger, :debug, :info, :warn, :error, :fatal, :level, :level=
+
+    # The Koala logger, an instance of the standard Ruby logger, pointing to STDOUT by default.
+    # In Rails projects, you can set this to Rails.logger.
+    attr_accessor :logger
+    self.logger = Logger.new(STDOUT)
+    self.logger.level = Logger::ERROR
+
     # @private
     DEPRECATION_PREFIX = "KOALA: Deprecation warning: "
 
-    # Prints a deprecation message.  
+    # Prints a deprecation message.
     # Each individual message will only be printed once to avoid spamming.
-    def self.deprecate(message)
+    def deprecate(message)
       @posted_deprecations ||= []
       unless @posted_deprecations.include?(message)
         # only include each message once

data/lib/koala/version.rb

@@ -1,3 +1,3 @@
 module Koala
-  VERSION = "1.4.0"
+  VERSION = "1.5.0rc1"
 end

data/readme.md

@@ -23,17 +23,17 @@ Or in Bundler:
 Graph API
 ----
 The Graph API is the simple, slick new interface to Facebook's data.  Using it with Koala is quite straightforward:
-  
+
     @graph = Koala::Facebook::API.new(oauth_access_token)
     # in 1.1 or earlier, use GraphAPI instead of API
-    
+
     profile = @graph.get_object("me")
     friends = @graph.get_connections("me", "friends")
-    @graph.put_object("me", "feed", :message => "I am writing on my wall!")
-   
+    @graph.put_connections("me", "feed", :message => "I am writing on my wall!")
+
     # three-part queries are easy too!
     @graph.get_connections("me", "mutualfriends/#{friend_id}")
-    
+
     # you can even use the new Timeline API
     # see https://developers.facebook.com/docs/beta/opengraph/tutorial/
     @graph.put_connections("me", "namespace:action", :object => object_url)
@@ -70,7 +70,7 @@ Fortunately, Koala supports the REST API using the very same interface; to use t
 
     @rest = Koala::Facebook::API.new(oauth_access_token)
     # in 1.1 or earlier, use RestAPI instead of API
-  	
+
   	@rest.fql_query(my_fql_query) # convenience method
   	@rest.fql_multiquery(fql_query_hash) # convenience method
   	@rest.rest_call("stream.publish", arguments_hash) # generic version
@@ -79,11 +79,11 @@ Of course, you can use the Graph API methods on the same object -- the power of
 
     @api = Koala::Facebook::API.new(oauth_access_token)
     # in 1.1 or earlier, use GraphAndRestAPI instead of API
-    
+
     @api = Koala::Facebook::API.new(oauth_access_token)
     fql = @api.fql_query(my_fql_query)
     @api.put_wall_post(process_result(fql))
-    
+
 
 OAuth
 -----
@@ -91,7 +91,7 @@ You can use the Graph and REST APIs without an OAuth access token, but the real
 
     @oauth = Koala::Facebook::OAuth.new(app_id, app_secret, callback_url)
 
-If your application uses Koala and the Facebook [JavaScript SDK](http://github.com/facebook/connect-js) (formerly Facebook Connect), you can use the OAuth class to parse the cookies:
+If your application uses Koala and the Facebook [JavaScript SDK](http://github.com/facebook/facebook-js-sdk) (formerly Facebook Connect), you can use the OAuth class to parse the cookies:
 
     @oauth.get_user_from_cookies(cookies) # gets the user's ID
 	  @oauth.get_user_info_from_cookies(cookies) # parses and returns the entire hash
@@ -166,7 +166,7 @@ Koala uses Faraday to make HTTP requests, which means you have complete control
     }
     # or on a per-request basis
     @api.get_object(id, args_hash, { :timeout => 10 })
-  
+
 The <a href="https://github.com/arsduo/koala/wiki/HTTP-Services">HTTP Services wiki page</a> has more information on what options are available, as well as on how to configure your own Faraday middleware stack (for instance, to implement request logging).
 
 See examples, ask questions