koala 1.5.0 → 1.6.0.rc1

data/.gitignore

@@ -4,4 +4,5 @@ Gemfile.lock
 .rvmrc
 *.rbc
 *~
-.yardoc/
+.yardoc/
+.DS_Store

data/.travis.yml

@@ -7,4 +7,7 @@ rvm:
   - jruby-19mode # JRuby in 1.9 mode
   - rbx-18mode
   - rbx-19mode
-  - ree
+  - ree
+matrix:
+  allow_failures:
+    - rvm: ruby-head

data/Gemfile

@@ -15,7 +15,7 @@ group :development, :test do
   if RUBY_PLATFORM =~ /darwin/
     # OS X integration
     gem "ruby_gntp"
-    gem "rb-fsevent", "~> 0.4.3.1"
+    gem "rb-fsevent"
   end
 end
 

data/changelog.md

@@ -0,0 +1,293 @@
+v1.6
+New methods:
+* RealtimeUpdates#validate_update to validate the signature of a Facebook call (thanks, gaffo!)
+Updated methods:
+* Graph API methods now accepts a post processing block, see readme for examples (thanks, wolframarnold!)
+_Internal improvements:_
+* Switched URL parsing to addressable, which can handle unusual FB URLs (thanks, bnorton!)
+* Fixed Batch API bug that seems to have broken calls requiring post-processing
+* Bump Faraday requirement to 0.8 (thanks, jarthod!)
+* Picture and video URLs now support unicode characters (thanks, jayeff!)
+Testing improvements:
+* Cleaned up some test suites (thanks, bnorton!)
+Documentation:
+* Changelog is now markdown
+* Code highlighting in readme (thanks, sfate!)
+* Added Graph API explorer link in readme (thanks, jch!)
+* Added permissions example for OAuth (thanks, sebastiandeutsch!)
+
+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, eckz and 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!)
+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)
+Internal improvements:
+* Fixed typos (thanks, brycethornton and jpemberthy!)
+* RealtimeUpdates will no longer execute challenge block unnecessarily (thanks, iainbeeston!)
+Testing improvements:
+* Added parallel_tests to development gem file
+* Fixed failing live tests
+* Koala now tests against JRuby and Rubinius in 1.9 mode on Travis-CI
+
+v1.3
+New methods:
+* OAuth#url_for_dialog creates URLs for Facebook dialog pages
+* API#set_app_restrictions handles JSON-encoding app restrictions
+* GraphCollection.parse_page_url now exposes useful functionality for non-Rails apps
+* RealtimeUpdates#subscription_path and TestUsers#test_user_accounts_path are now public
+Updated methods:
+* REST API methods are now deprecated (see http://developers.facebook.com/blog/post/616/)
+* OAuth#url_for_access_token and #url_for_oauth_code now include any provided options as URL parameters
+* APIError#raw_response allows access to the raw error response received from Facebook
+* Utils.deprecate only prints each message once (no more spamming)
+* API#get_page_access_token now accepts additional arguments and HTTP options (like other calls)
+* TestUsers and RealtimeUpdates methods now take http_options arguments
+* All methods with http_options can now take :http_component => :response for the complete response
+* OAuth#get_user_info_from_cookies returns nil rather than an error if the cookies are expired (thanks, herzio)
+* TestUsers#delete_all now uses the Batch API and is much faster
+Internal improvements:
+* FQL queries now use the Graph API behind-the-scenes
+* Cleaned up file and class organization, with aliases for backward compatibility
+* Added YARD documentation throughout
+* Fixed bugs in RealtimeUpdates, TestUsers, elsewhere
+* Reorganized file and class structure non-destructively
+Testing improvements:
+* Expanded/improved test coverage
+* The test suite no longer users any hard-coded user IDs
+* KoalaTest.test_user_api allows access to the TestUsers instance
+* Configured tests to run in random order using RSpec 2.8.0rc1
+
+v1.2.1
+New methods:
+* RestAPI.set_app_properties handles JSON-encoding application properties
+Updated methods:
+* OAuth.get_user_from_cookie works with the new signed cookie format (thanks, gmccreight!)
+* Beta server URLs are now correct
+* OAuth.parse_signed_request now raises an informative error if the signed_request is malformed
+Internal improvements:
+* Koala::Multipart middleware properly encoding nested parameters (hashes) in POSTs
+* Updated readme, changelog, etc.
+Testing improvements:
+* Live tests with test users now clean up all fake users they create
+* Removed duplicate test cases
+* Live tests with test users no longer delete each object they create, speeding things up
+
+v1.2
+New methods:
+* API is now the main API class, contains both Graph and REST methods
+  * Old classes are aliased with deprecation warnings (non-breaking change)
+* TestUsers#update lets you update the name or password of an existing test user
+* API.get_page_access_token lets you easily fetch the access token for a page you manage (thanks, marcgg!)
+* Added version.rb (Koala::VERSION)
+Updated methods:
+* OAuth now parses Facebook's new signed cookie format
+* API.put_picture now accepts URLs to images (thanks, marcgg!)
+* Bug fixes to put_picture, parse_signed_request, and the test suite (thanks, johnbhall and Will S.!)
+* Smarter GraphCollection use
+  * Any pageable result will now become a GraphCollection
+  * Non-pageable results from get_connections no longer error
+  * GraphCollection.raw_results allows access to original result data
+* Koala no longer enforces any limits on the number of test users you create at once
+Internal improvements:
+* Koala now uses Faraday to make requests, replacing the HTTPServices (see wiki)
+  * Koala::HTTPService.http_options allows specification of default Faraday connection options
+  * Koala::HTTPService.faraday_middleware allows custom middleware configurations
+  * Koala now defaults to Net::HTTP rather than Typhoeus
+  * Koala::NetHTTPService and Koala::TyphoeusService modules no longer exist
+  * Koala no longer automatically switches to Net::HTTP when uploading IO objects to Facebook
+* RealTimeUpdates and TestUsers are no longer subclasses of API, but have their own .api objects
+  * The old .graph_api accessor is aliases to .api with a deprecation warning
+* Removed deprecation warnings for pre-1.1 batch interface
+Testing improvements:
+* Live test suites now run against test users by default
+  * Test suite can be repeatedly run live without having to update facebook_data.yml
+  * OAuth code and session key tests cannot be run against test users
+* Faraday adapter for live tests can be specified with ADAPTER=[your adapter] in the rspec command
+* Live tests can be run against the beta server by specifying BETA=true in the rspec command
+* Tests now pass against all rubies on Travis CI
+* Expanded and refactored test coverage
+* Fixed bug with YAML parsing in Ruby 1.9
+
+v1.1
+New methods:
+* Added Batch API support (thanks, seejohnrun and spiegela!)
+  * includes file uploads, error handling, and FQL
+* Added GraphAPI#put_video
+* Added GraphAPI#get_comments_for_urls (thanks, amrnt!)
+* Added RestAPI#fql_multiquery, which simplifies the results (thanks, amrnt!)
+* HTTP services support global proxy and timeout settings (thanks, itchy!)
+* Net::HTTP supports global ca_path, ca_file, and verify_mode settings (thanks, spiegela!)
+Updated methods:
+* RealtimeUpdates now uses a GraphAPI object instead of its own API
+* RestAPI#rest_call now has an optional last argument for method, for calls requiring POST, DELETE, etc. (thanks, sshilo!)
+* Filename can now be specified when uploading (e.g. for Ads API) (thanks, sshilo!)
+* get_objects([]) returns [] instead of a Facebook error in non-batch mode (thanks, aselder!)
+Internal improvements:
+* Koala is now more compatible with other Rubies (JRuby, Rubinius, etc.)
+* HTTP services are more modular and can be changed on the fly (thanks, chadk!)
+  * Includes support for uploading StringIOs and other non-files via Net::HTTP even when using TyphoeusService
+* Koala now uses multi_json to improve compatibility with Rubinius and other Ruby versions
+* Koala now uses the modern Typhoeus API (thanks, aselder!)
+* Koala now uses the current modern Net::HTTP interface (thanks, romanbsd!)
+* Fixed bugs and typos (thanks, waynn, mokevnin, and tikh!)
+
+v1.0
+New methods:
+* Photo and file upload now supported through #put_picture
+  * Added UploadableIO class to manage file uploads
+* Added a delete_like method (thanks to waseem)
+* Added put_connection and delete_connection convenience methods
+Updated methods:
+* Search can now search places, checkins, etc. (thanks, rickyc!)
+* You can now pass :beta => true in the http options to use Facebook's beta tier
+* TestUser#befriend now requires user info hashes (id and access token) due to Facebook API changes (thanks, pulsd and kbighorse!)
+* All methods now accept an http_options hash as their optional last parameter (thanks, spiegela!)
+* url_for_oauth_code can now take a :display option (thanks, netbe!)
+* Net::HTTP can now accept :timeout and :proxy options (thanks, gilles!)
+* Test users now supports using test accounts across multiple apps
+Internal improvements:
+* For public requests, Koala now uses http by default (instead of https) to improve speed
+  * This can be overridden through Koala.always_use_ssl= or by passing :use_ssl => true in the options hash for an api call
+* Read-only REST API requests now go through the faster api-read server
+* Replaced parse_signed_request with a version from Facebook that also supports the new signed params proposal
+  * Note: invalid requests will now raise exceptions rather than return nil, in keeping with other SDKs
+* Delete methods will now raise an error if there's no access token (like put_object and delete_like)
+* Updated parse_signed_request to match Facebook's current implementation (thanks, imajes!)
+* APIError is now < StandardError, not Exception
+* Added KoalaError for non-API errors
+* Net::HTTP's SSL verification is no longer disabled by default
+Test improvements:
+* Incorporated joshk's awesome rewrite of the entire Koala test suite (thanks, joshk!)
+* Expanded HTTP service tests (added Typhoeus test suite and additional Net::HTTP test cases)
+* Live tests now verify that the access token has the necessary permissions before starting
+* Replaced the 50-person network test, which often took 15+ minutes to run live, with a 5-person test
+
+v0.10.0
+* Added test user module
+* Fixed bug when raising APIError after Facebook fails to exchange session keys
+* Made access_token accessible via the readonly access_token property on all our API classes
+
+v0.9.1
+* Tests are now compatible with Ruby 1.9.2
+* Added JSON to runtime dependencies
+* Removed examples directory (referenced from github instead)
+
+v0.9.0
+* Added parse_signed_request to handle Facebook's new authentication scheme
+  * note: creates dependency on OpenSSL (OpenSSL::HMAC) for decryption
+* Added GraphCollection class to provide paging support for GraphAPI get_connections and search methods (thanks to jagthedrummer)
+* Added get_page method to easily fetch pages of results from GraphCollections
+* Exchanging sessions for tokens now works properly when provided invalid/expired session keys
+* You can now include a :typhoeus_options key in TyphoeusService#make_request's options hash to control the Typhoeus call (for example, to set :disable_ssl_peer_verification => true)
+* All paths provided to HTTP services start with leading / to improve compatibility with stubbing libraries
+* If Facebook returns nil for search or get_connections requests, Koala now returns nil rather than throwing an exception
+
+v0.8.0
+* Breaking interface changes
+  * Removed string overloading for the methods, per 0.7.3, which caused Marshaling issues
+  * Removed ability to provide a string as the second argument to url_for_access_token, per 0.5.0
+
+v0.7.4
+* Fixed bug with get_user_from_cookies
+
+v0.7.3
+* Added support for picture sizes -- thanks thhermansen for the patch!
+* Adjusted the return values for several methods (get_access_token, get_app_access_token, get_token_from_session_key, get_tokens_from_session_keys, get_user_from_cookies)
+  * These methods now return strings, rather than hashes, which makes more sense
+  * The strings are overloaded with an [] method for backwards compatibility (Ruby is truly amazing)
+    * Using those methods triggers a deprecation warning
+    * This will be removed by 1.0
+  * There are new info methods (get_access_token_info, get_app_access_token_info, get_token_info_from_session_keys, and get_user_info_from_cookies) that natively return hashes, for when you want the expiration date
+* Responses with HTTP status 500+ now properly throw errors under Net::HTTP
+* Updated changelog
+* Added license
+
+v0.7.2
+* Added support for exchanging session keys for OAuth access tokens (get_token_from_session_key for single keys, get_tokens_from_session_keys for multiple)
+* Moved Koala files into a koala/ subdirectory to minimize risk of name collisions
+* Added OAuth Playground git submodule as an example
+* Updated tests, readme, and changelog
+
+v0.7.1
+* Updated RealtimeUpdates#list_subscriptions and GraphAPI#get_connections to now return an
+array of results directly (rather than a hash with one key)
+* Fixed a bug with Net::HTTP-based HTTP service in which the headers hash was improperly formatted
+* Updated readme
+
+v0.7.0
+* Added RealtimeUpdates class, which can be used to manage subscriptions for user updates (see http://developers.facebook.com/docs/api/realtime)
+* Added picture method to graph API, which fetches an object's picture from the redirect headers.
+* Added _greatly_ improved testing with result mocking, which is now the default set of tests
+* Renamed live testing spec to koala_spec_without_mocks.rb
+* Added Koala::Response class, which encapsulates HTTP results since Facebook sometimes sends data in the status or headers
+* Much internal refactoring
+* Updated readme, changelog, etc.
+
+
+v0.6.0
+* Added support for the old REST API thanks to cbaclig's great work
+* Updated tests to conform to RSpec standards
+* Updated changelog, readme, etc.
+
+v0.5.1
+* Documentation is now on the wiki, updated readme accordingly.
+
+v0.5.0
+* Added several new OAuth methods for making and parsing access token requests
+* Added test suite for the OAuth class
+* Made second argument to url_for_access_token a hash (strings still work but trigger a deprecation warning)
+* Added fields to facebook_data.yml
+* Updated readme
+
+v0.4.1
+* Encapsulated GraphAPI and OAuth classes in the Koala::Facebook module for clarity (and to avoid claiming the global Facebook class)
+* Moved make_request method to Koala class from GraphAPI instance (for use by future OAuth class functionality)
+* Renamed request method to api for consistancy with Javascript library
+* Updated tests and readme
+
+v0.4.0
+* Adopted the Koala name
+* Updated readme and tests
+* Fixed cookie verification bug for non-expiring OAuth tokens
+
+v0.3.1
+* Bug fixes.
+
+v0.3
+* Renamed Graph API class from Facebook::GraphAPI to FacebookGraph::API
+* Created FacebookGraph::OAuth class for tokens and OAuth URLs
+* Updated method for including HTTP service (think we've got it this time)
+* Updated tests
+* Added CHANGELOG and gemspec
+
+v0.2
+* Gemified the project
+* Split out HTTP services into their own file, and adjusted inclusion method
+
+v0.1
+* Added modular support for Typhoeus
+* Added tests
+
+v0.0
+* Hi from F8!  Basic read/write from the graph is working

data/koala.gemspec

@@ -17,11 +17,12 @@ Gem::Specification.new do |gem|
   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.extra_rdoc_files = ["readme.md", "changelog.md"]
   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_runtime_dependency(%q<faraday>,       ["~> 0.8"])
+  gem.add_runtime_dependency(%q<addressable>,   ["~> 2.2"])
   gem.add_development_dependency(%q<rspec>,     ["~> 2.8"])
   gem.add_development_dependency(%q<rake>,      ["~> 0.8"])
 end

data/lib/koala.rb

@@ -3,6 +3,7 @@ require 'digest/md5'
 require 'multi_json'
 
 # include koala modules
+require 'koala/errors'
 require 'koala/api'
 require 'koala/oauth'
 require 'koala/realtime_updates'
@@ -20,8 +21,6 @@ module Koala
   # See http://github.com/arsduo/koala/wiki for a general introduction to Koala
   # and the Graph API.
   
-  class KoalaError < StandardError; end
-
   # Making HTTP requests
   class << self
     # Control which HTTP service framework Koala uses. 

data/lib/koala/api.rb

@@ -35,9 +35,9 @@ module Koala
       #                                    (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
+      # @yield The response for evaluation
       #
-      # @raise [Koala::Facebook::APIError] if Facebook returns an error (response status >= 500)
+      # @raise [Koala::Facebook::ServerError] 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)
@@ -50,43 +50,23 @@ module Koala
         # 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.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 result.status.to_i >= 500
+          raise Koala::Facebook::ServerError.new(result.status.to_i, result.body)
+        end
+      
+        yield result 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
+          # 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.load to fail -- so we account for that by wrapping the result in []
+          MultiJson.load("[#{result.body.to_s}]")[0]
         end
       end
     end
-
-    class APIError < StandardError
-      attr_accessor :fb_error_type, :fb_error_code, :fb_error_message, :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"]
-        self.fb_error_code = details["code"]
-        self.fb_error_message = details["message"]
-        super("#{fb_error_type}: #{details["message"]}")
-      end
-    end
   end
 end
 

data/lib/koala/api/batch_operation.rb

@@ -25,7 +25,7 @@ module Koala
 
           process_binary_args
 
-          raise Koala::KoalaError, "Batch operations require an access token, none provided." unless @access_token
+          raise AuthenticationError.new(nil, nil, "Batch operations require an access token, none provided.") unless @access_token
         end
 
         def to_batch_params(main_access_token)

data/lib/koala/api/graph_api.rb

@@ -1,3 +1,5 @@
+require 'addressable/uri'
+
 require 'koala/api/graph_collection'
 require 'koala/http_service/uploadable_io'
 
@@ -40,13 +42,20 @@ module Koala
       # @param args any additional arguments
       #         (fields, metadata, etc. -- see {http://developers.facebook.com/docs/reference/api/ Facebook's documentation})
       # @param options (see Koala::Facebook::API#api)
+      # @param block for post-processing. It receives the result data; the
+      #        return value of the method is the result of the block, if
+      #        provided.  (see Koala::Facebook::API#api)
       #
       # @raise [Koala::Facebook::APIError] if the ID is invalid or you don't have access to that object
       #
+      # @example
+      #     get_object("me")  # => {"id" => ..., "name" => ...}
+      #     get_object("me") {|data| data['education']}  # => only education section of profile
+      #
       # @return a hash of object data
-      def get_object(id, args = {}, options = {})
-        # Fetchs the given object from the graph.
-        graph_call(id, args, "get", options)
+      def get_object(id, args = {}, options = {}, &block)
+        # Fetches the given object from the graph.
+        graph_call(id, args, "get", options, &block)
       end
 
       # Get information about multiple Facebook objects in one call.
@@ -54,15 +63,16 @@ module Koala
       # @param ids an array or comma-separated string of object IDs
       # @param args (see #get_object)
       # @param options (see Koala::Facebook::API#api)
+      # @param block (see Koala::Facebook::API#api)
       #
       # @raise [Koala::Facebook::APIError] if any ID is invalid or you don't have access to that object
       #
       # @return an array of object data hashes
-      def get_objects(ids, args = {}, options = {})
-        # Fetchs all of the given objects from the graph.
+      def get_objects(ids, args = {}, options = {}, &block)
+        # Fetches all of the given objects from the graph.
         # If any of the IDs are invalid, they'll raise an exception.
         return [] if ids.empty?
-        graph_call("", args.merge("ids" => ids.respond_to?(:join) ? ids.join(",") : ids), "get", options)
+        graph_call("", args.merge("ids" => ids.respond_to?(:join) ? ids.join(",") : ids), "get", options, &block)
       end
 
       # Write an object to the Graph for a specific user.
@@ -71,20 +81,21 @@ module Koala
       # @note put_object is (for historical reasons) the same as put_connections.
       #       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 = {})
-        put_connections(parent_object, connection_name, args, options)
+      def put_object(parent_object, connection_name, args = {}, options = {}, &block)
+        put_connections(parent_object, connection_name, args, options, &block)
       end
 
       # Delete an object from the Graph if you have appropriate permissions.
       #
       # @param id (see #get_object)
       # @param options (see #get_object)
+      # @param block (see Koala::Facebook::API#api)
       #
       # @return true if successful, false (or an APIError) if not
-      def delete_object(id, options = {})
+      def delete_object(id, options = {}, &block)
         # Deletes the object with the given ID from the graph.
-        raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Delete requires an access token"}) unless @access_token
-        graph_call(id, {}, "delete", options)
+        raise AuthenticationError.new(nil, nil, "Delete requires an access token") unless @access_token
+        graph_call(id, {}, "delete", options, &block)
       end
 
       # Fetch information about a given connection (e.g. type of activity -- feed, events, photos, etc.)
@@ -98,11 +109,12 @@ module Koala
       # @param connection_name what
       # @param args any additional arguments
       # @param options (see #get_object)
+      # @param block (see Koala::Facebook::API#api)
       #
       # @return [Koala::Facebook::API::GraphCollection] an array of object hashes (in most cases)
-      def get_connection(id, connection_name, args = {}, options = {})
-        # Fetchs the connections for given object.
-        graph_call("#{id}/#{connection_name}", args, "get", options)
+      def get_connection(id, connection_name, args = {}, options = {}, &block)
+        # Fetches the connections for given object.
+        graph_call("#{id}/#{connection_name}", args, "get", options, &block)
       end
       alias_method :get_connections, :get_connection
 
@@ -126,12 +138,13 @@ module Koala
       # @param connection_name (see #get_connection)
       # @param args (see #get_connection)
       # @param options (see #get_object)
+      # @param block (see Koala::Facebook::API#api)
       #
       # @return a hash containing the new object's id
-      def put_connections(id, connection_name, args = {}, options = {})
+      def put_connections(id, connection_name, args = {}, options = {}, &block)
         # Posts a certain connection
-        raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Write operations require an access token"}) unless @access_token
-        graph_call("#{id}/#{connection_name}", args, "post", options)
+        raise AuthenticationError.new(nil, nil, "Write operations require an access token") unless @access_token
+        graph_call("#{id}/#{connection_name}", args, "post", options, &block)
       end
 
       # Delete an object's connection (for instance, unliking the object).
@@ -142,12 +155,13 @@ module Koala
       # @param connection_name (see #get_connection)
       # @args (see #get_connection)
       # @param options (see #get_object)
+      # @param block (see Koala::Facebook::API#api)
       #
       # @return (see #delete_object)
-      def delete_connections(id, connection_name, args = {}, options = {})
+      def delete_connections(id, connection_name, args = {}, options = {}, &block)
         # Deletes a given connection
-        raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Delete requires an access token"}) unless @access_token
-        graph_call("#{id}/#{connection_name}", args, "delete", options)
+        raise AuthenticationError.new(nil, nil, "Delete requires an access token") unless @access_token
+        graph_call("#{id}/#{connection_name}", args, "delete", options, &block)
       end
 
       # Fetches a photo.
@@ -156,15 +170,17 @@ module Koala
       #
       # @param options options for Facebook (see #get_object).
       #                        To get a different size photo, pass :type => size (small, normal, large, square).
+      # @param block (see Koala::Facebook::API#api)
       #
       # @note to delete photos or videos, use delete_object(id)
       #
       # @return the URL to the image
-      def get_picture(object, args = {}, options = {})
+      def get_picture(object, args = {}, options = {}, &block)
         # Gets a picture object, returning the URL (which Facebook sends as a header)
-        graph_call("#{object}/picture", args, "get", options.merge(:http_component => :headers)) do |result|
+        resolved_result = graph_call("#{object}/picture", args, "get", options.merge(:http_component => :headers)) do |result|
           result["Location"]
         end
+        block ? block.call(resolved_result) : resolved_result
       end
 
       # Upload a photo.
@@ -180,6 +196,7 @@ module Koala
       # @param args (see #get_object)
       # @param target_id the Facebook object to which to post the picture (default: "me")
       # @param options (see #get_object)
+      # @param block (see Koala::Facebook::API#api)
       #
       # @example
       #     put_picture(file, content_type, {:message => "Message"}, 01234560)
@@ -190,16 +207,16 @@ module Koala
       # @note to access the media after upload, you'll need the user_photos or user_videos permission as appropriate.
       #
       # @return (see #put_connections)
-      def put_picture(*picture_args)
-        put_connections(*parse_media_args(picture_args, "photos"))
+      def put_picture(*picture_args, &block)
+        put_connections(*parse_media_args(picture_args, "photos"), &block)
       end
 
       # Upload a video.  Functions exactly the same as put_picture.
       # @see #put_picture
-      def put_video(*video_args)
+      def put_video(*video_args, &block)
         args = parse_media_args(video_args, "videos")
         args.last[:video] = true
-        put_connections(*args)
+        put_connections(*args, &block)
       end
 
       # Write directly to the user's wall.
@@ -213,6 +230,7 @@ module Koala
       #         (see the {https://developers.facebook.com/docs/guides/attachments/ stream attachments} documentation.)
       # @param target_id the target wall
       # @param options (see #get_object)
+      # @param block (see Koala::Facebook::API#api)
       #
       # @example
       #       @api.put_wall_post("Hello there!", {
@@ -225,8 +243,8 @@ module Koala
       #
       # @see #put_connections
       # @return (see #put_connections)
-      def put_wall_post(message, attachment = {}, target_id = "me", options = {})
-        put_connections(target_id, "feed", attachment.merge({:message => message}), options)
+      def put_wall_post(message, attachment = {}, target_id = "me", options = {}, &block)
+        put_connections(target_id, "feed", attachment.merge({:message => message}), options, &block)
       end
 
       # Comment on a given object.
@@ -238,11 +256,12 @@ module Koala
       # @param id (see #get_object)
       # @param message the comment to write
       # @param options (see #get_object)
+      # @param block (see Koala::Facebook::API#api)
       #
       # @return (see #put_connections)
-      def put_comment(id, message, options = {})
+      def put_comment(id, message, options = {}, &block)
         # Writes the given comment on the given post.
-        put_connections(id, "comments", {:message => message}, options)
+        put_connections(id, "comments", {:message => message}, options, &block)
       end
 
       # Like a given object.
@@ -252,11 +271,12 @@ module Koala
       #
       # @param id (see #get_object)
       # @param options (see #get_object)
+      # @param block (see Koala::Facebook::API#api)
       #
       # @return (see #put_connections)
-      def put_like(id, options = {})
+      def put_like(id, options = {}, &block)
         # Likes the given post.
-        put_connections(id, "likes", {}, options)
+        put_connections(id, "likes", {}, options, &block)
       end
 
       # Unlike a given object.
@@ -264,12 +284,13 @@ module Koala
       #
       # @param id (see #get_object)
       # @param options (see #get_object)
+      # @param block (see Koala::Facebook::API#api)
       #
       # @return (see #delete_object)
-      def delete_like(id, options = {})
+      def delete_like(id, options = {}, &block)
         # Unlikes a given object for the logged-in user
-        raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Unliking requires an access token"}) unless @access_token
-        graph_call("#{id}/likes", {}, "delete", options)
+        raise AuthenticationError.new(nil, nil, "Unliking requires an access token") unless @access_token
+        graph_call("#{id}/likes", {}, "delete", options, &block)
       end
 
       # Search for a given query among visible Facebook objects.
@@ -278,11 +299,12 @@ module Koala
       # @param search_terms the query to search for
       # @param args additional arguments, such as type, fields, etc.
       # @param options (see #get_object)
+      # @param block (see Koala::Facebook::API#api)
       #
       # @return [Koala::Facebook::API::GraphCollection] an array of search results
-      def search(search_terms, args = {}, options = {})
+      def search(search_terms, args = {}, options = {}, &block)
         args.merge!({:q => search_terms}) unless search_terms.nil?
-        graph_call("search", args, "get", options)
+        graph_call("search", args, "get", options, &block)
       end
 
       # Convenience Methods
@@ -296,8 +318,11 @@ module Koala
       # @param query the FQL query to perform
       # @param args (see #get_object)
       # @param options (see #get_object)
-      def fql_query(query, args = {}, options = {})
-        get_object("fql", args.merge(:q => query), options)
+      # @param block (see Koala::Facebook::API#api)
+      #
+      # @return the result of the FQL query.
+      def fql_query(query, args = {}, options = {}, &block)
+        get_object("fql", args.merge(:q => query), options, &block)
       end
 
       # Make an FQL multiquery.
@@ -306,6 +331,7 @@ module Koala
       # @param queries a hash of query names => FQL queries
       # @param args (see #get_object)
       # @param options (see #get_object)
+      # @param block (see Koala::Facebook::API#api)
       #
       # @example
       #     @api.fql_multiquery({
@@ -316,11 +342,13 @@ module Koala
       #     # instead of [{"name":"query1", "fql_result_set":[]},{"name":"query2", "fql_result_set":[]}]
       #
       # @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.dump(queries)), options)
+      def fql_multiquery(queries = {}, args = {}, options = {}, &block)
+        resolved_results = 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
+
+        block ? block.call(resolved_results) : resolved_results
       end
 
       # Get a page's access token, allowing you to act as the page.
@@ -329,30 +357,34 @@ module Koala
       # @param id the page ID
       # @param args (see #get_object)
       # @param options (see #get_object)
+      # @param block (see Koala::Facebook::API#api)
       #
       # @return the page's access token (discarding expiration and any other information)
-      def get_page_access_token(id, args = {}, options = {})
-        result = get_object(id, args.merge(:fields => "access_token"), options) do
+      def get_page_access_token(id, args = {}, options = {}, &block)
+        access_token = get_object(id, args.merge(:fields => "access_token"), options) do |result|
           result ? result["access_token"] : nil
         end
+
+        block ? block.call(access_token) : access_token
       end
 
-      # Fetchs the comments from fb:comments widgets for a given set of URLs (array or comma-separated string).
+      # Fetches the comments from fb:comments widgets for a given set of URLs (array or comma-separated string).
       # See https://developers.facebook.com/blog/post/490.
       #
       # @param urls the URLs for which you want comments
       # @param args (see #get_object)
       # @param options (see #get_object)
+      # @param block (see Koala::Facebook::API#api)
       #
       # @returns a hash of urls => comment arrays
-      def get_comments_for_urls(urls = [], args = {}, options = {})
+      def get_comments_for_urls(urls = [], args = {}, options = {}, &block)
         return [] if urls.empty?
         args.merge!(:ids => urls.respond_to?(:join) ? urls.join(",") : urls)
-        get_object("comments", args, options)
+        get_object("comments", args, options, &block)
       end
 
-      def set_app_restrictions(app_id, restrictions_hash, args = {}, options = {})
-        graph_call(app_id, args.merge(:restrictions => MultiJson.dump(restrictions_hash)), "post", options)
+      def set_app_restrictions(app_id, restrictions_hash, args = {}, options = {}, &block)
+        graph_call(app_id, args.merge(:restrictions => MultiJson.dump(restrictions_hash)), "post", options, &block)
       end
 
       # Certain calls such as {#get_connections} return an array of results which you can page through
@@ -364,10 +396,11 @@ module Koala
       #
       # @param params an array of arguments to graph_call
       #               as returned by {Koala::Facebook::GraphCollection.parse_page_url}.
+      # @param block (see Koala::Facebook::API#api)
       #
       # @return Koala::Facebook::GraphCollection the appropriate page of results (an empty array if there are none)
-      def get_page(params)
-        graph_call(*params)
+      def get_page(params, &block)
+        graph_call(*params, &block)
       end
 
       # Execute a set of Graph API calls as a batch.
@@ -386,10 +419,21 @@ module Koala
       #
       # @example
       #         results = @api.batch do |batch_api|
-      #          batch_api.get_object('me')
-      #          batch_api.get_object(KoalaTest.user1)
+      #           batch_api.get_object('me')
+      #           batch_api.get_object(KoalaTest.user1)
+      #         end
+      #         # => [{'id' => my_id, ...}, {'id' => koppel_id, ...}]
+      #
+      #         # You can also provide blocks to your operations to process the
+      #         # results, which is often useful if you're constructing batch
+      #         # requests in various locations and want to keep the code
+      #         # together in logical places.
+      #         # See readme.md and the wiki for more examples.
+      #         @api.batch do |batch_api|
+      #           batch_api.get_object('me') {|data| data["id"] }
+      #           batch_api.get_object(KoalaTest.user1) {|data| data["name"] }
       #         end
-      #         # => [{"id" => my_id, ...}, {"id"" => koppel_id, ...}]
+      #         # => [my_id, "Alex Koppel"]
       #
       # @return an array of results from your batch calls (as if you'd made them individually),
       #         arranged in the same order they're made.
@@ -422,7 +466,7 @@ module Koala
       # @return the result from Facebook
       def graph_call(path, args = {}, verb = "get", options = {}, &post_processing)
         result = api(path, args, verb, options) do |response|
-          error = check_response(response)
+          error = check_response(response.status, response.body)
           raise error if error
         end
 
@@ -435,12 +479,38 @@ module Koala
 
       private
 
-      def check_response(response)
-        # check for Graph API-specific errors
-        # this returns an error, which is immediately raised (non-batch)
-        # or added to the list of batch results (batch)
-        if response.is_a?(Hash) && error_details = response["error"]
-          APIError.new(error_details)
+      def check_response(http_status, response_body)
+        # Check for Graph API-specific errors. This returns an error of the appropriate type
+        # which is immediately raised (non-batch) or added to the list of batch results (batch)
+        http_status = http_status.to_i
+
+        if http_status >= 400
+          begin
+            response_hash = MultiJson.load(response_body)
+          rescue MultiJson::DecodeError
+            response_hash = {}
+          end
+
+          if response_hash['error_code']
+            # Old batch api error format. This can be removed on July 5, 2012.
+            # See https://developers.facebook.com/roadmap/#graph-batch-api-exception-format
+            error_info = {
+              'code' => response_hash['error_code'],
+              'message' => response_hash['error_description']
+            }
+          else
+            error_info = response_hash['error'] || {}
+          end
+
+          if error_info['type'] == 'OAuthException' &&
+             ( !error_info['code'] || [102, 190, 450, 452, 2500].include?(error_info['code'].to_i))
+
+            # See: https://developers.facebook.com/docs/authentication/access-token-expiration/
+            #      https://developers.facebook.com/bugs/319643234746794?browse=search_4fa075c0bd9117b20604672
+            AuthenticationError.new(http_status, response_body, error_info)
+          else
+            ClientError.new(http_status, response_body, error_info)
+          end
         end
       end
 
@@ -468,9 +538,9 @@ module Koala
       def url?(data)
         return false unless data.is_a? String
         begin
-          uri = URI.parse(data)
+          uri = Addressable::URI.parse(data)
           %w( http https ).include?(uri.scheme)
-        rescue URI::BadURIError
+        rescue Addressable::URI::InvalidURIError
           false
         end
       end