koala 1.3.0rc1 → 1.3.0rc2

data/.gitignore

@@ -2,4 +2,6 @@ pkg
 .project
 Gemfile.lock
 .rvmrc
-*.rbc
+*.rbc
+*~
+.yardoc/

data/.travis.yml

@@ -7,3 +7,7 @@ rvm:
   - rbx-2.0
   - ree
   - jruby
+
+branches:
+  except:
+    - rdoc

data/.yardopts

@@ -0,0 +1,3 @@
+--readme          readme.md
+--title           "Koala Documentation"
+--no-private

data/CHANGELOG

@@ -3,13 +3,20 @@ 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:
 -- 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
 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

data/Gemfile

@@ -1,7 +1,21 @@
 source :rubygems
 
+group :development do
+  gem "yard"
+end
+
 group :development, :test do
   gem "typhoeus"
+
+  # Testing infrastructure
+  gem 'guard'
+  gem 'guard-rspec'
+
+  if RUBY_PLATFORM =~ /darwin/
+    # OS X integration
+    gem "ruby_gntp"
+    gem "rb-fsevent", "~> 0.4.3.1"
+  end
 end
 
 if defined? JRUBY_VERSION

data/Guardfile

@@ -0,0 +1,6 @@
+guard 'rspec', :version => 2 do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end
+

data/lib/koala.rb

@@ -1,122 +1,40 @@
-require 'cgi'
+# useful tools
 require 'digest/md5'
-
 require 'multi_json'
 
-# OpenSSL and Base64 are required to support signed_request
-require 'openssl'
-require 'base64'
-
 # include koala modules
+require 'koala/api'
 require 'koala/oauth'
-require 'koala/graph_api'
-require 'koala/graph_batch_api'
-require 'koala/batch_operation'
-require 'koala/graph_collection'
-require 'koala/rest_api'
 require 'koala/realtime_updates'
 require 'koala/test_users'
 
 # HTTP module so we can communicate with Facebook
 require 'koala/http_service'
-require 'koala/multipart_request'
-
-# add KoalaIO class
-require 'koala/uploadable_io'
 
 # miscellaneous
 require 'koala/utils'
 require 'koala/version'
 
 module Koala
-
-  module Facebook
-    # Ruby client library for the Facebook Platform.
-    # Copyright 2010-2011 Alex Koppel
-    # Contributors: Alex Koppel, Chris Baclig, Rafi Jacoby, and the team at Context Optional
-    # http://github.com/arsduo/koala
-
-    # APIs
-    class API
-      # initialize with an access token
-      def initialize(access_token = nil)
-        @access_token = access_token
-      end
-      attr_reader :access_token
-
-      include GraphAPIMethods
-      include RestAPIMethods
-
-      def api(path, args = {}, verb = "get", options = {}, &error_checking_block)
-        # Fetches the given path in the Graph API.
-        args["access_token"] = @access_token || @app_access_token if @access_token || @app_access_token
-
-        # add a leading /
-        path = "/#{path}" unless path =~ /^\//
-
-        # make the request via the provided service
-        result = Koala.make_request(path, args, verb, options)
-
-        # Check for any 500 errors before parsing the body
-        # since we're not guaranteed that the body is valid JSON
-        # in the case of a server error
-        raise APIError.new({"type" => "HTTP #{result.status.to_s}", "message" => "Response body: #{result.body}"}) if result.status >= 500
-
-        # parse the body as JSON and run it through the error checker (if provided)
-        # Note: Facebook sometimes sends results like "true" and "false", which aren't strictly objects
-        # and cause MultiJson.decode to fail -- so we account for that by wrapping the result in []
-        body = MultiJson.decode("[#{result.body.to_s}]")[0]
-        yield body if error_checking_block
-
-        # if we want a component other than the body (e.g. redirect header for images), return that
-        options[:http_component] ? result.send(options[:http_component]) : body
-      end
-    end
-
-    # special enhanced APIs
-    class GraphBatchAPI < API
-      include GraphBatchAPIMethods
-    end
-
-    class RealtimeUpdates
-      include RealtimeUpdateMethods
-    end
-
-    class TestUsers
-      include TestUserMethods
-    end
-
-    # legacy support for old APIs
-    class OldAPI < API;
-      def initialize(*args)
-        Koala::Utils.deprecate("#{self.class.name} is deprecated and will be removed in a future version; please use the API class instead.")
-        super
-      end
-    end
-    class GraphAPI < OldAPI; end
-    class RestAPI < OldAPI; end
-    class GraphAndRestAPI < OldAPI; end
-
-    # Errors
-
-    class APIError < StandardError
-      attr_accessor :fb_error_type, :raw_response
-      def initialize(details = {})
-        self.raw_response = details
-        self.fb_error_type = details["type"]
-        super("#{fb_error_type}: #{details["message"]}")
-      end
-    end
-  end
-
+  # A Ruby client library for the Facebook Platform.
+  # See http://github.com/arsduo/koala/wiki for a general introduction to Koala
+  # and the Graph API.
+  
   class KoalaError < StandardError; end
 
-
-  # finally, the few things defined on the Koala module itself
+  # Making HTTP requests
   class << self
+    # Control which HTTP service framework Koala uses. 
+    # Primarily used to switch between the mock-request framework used in testing
+    # and the live framework used in real life (and live testing).
+    # In theory, you could write your own HTTPService module if you need different functionality,
+    # but since the switch to {https://github.com/arsduo/koala/wiki/HTTP-Services Faraday} almost all such goals can be accomplished with middleware.
     attr_accessor :http_service
   end
 
+  # @private
+  # For current HTTPServices, switch the service as expected.
+  # For deprecated services (Typhoeus and Net::HTTP), print a warning and set the default Faraday adapter appropriately.
   def self.http_service=(service)
     if service.respond_to?(:deprecated_interface)
       # if this is a deprecated module, support the old interface
@@ -129,6 +47,7 @@ module Koala
     end
   end
 
+  # An convenenient alias to Koala.http_service.make_request. 
   def self.make_request(path, args, verb, options = {})
     http_service.make_request(path, args, verb, options)
   end

data/lib/koala/api.rb

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

data/lib/koala/api/batch_operation.rb

@@ -0,0 +1,83 @@
+require 'koala/api'
+
+module Koala
+  module Facebook
+    class GraphBatchAPI < API
+      # @private
+      class BatchOperation
+        attr_reader :access_token, :http_options, :post_processing, :files, :batch_api, :identifier
+
+        @identifier = 0
+
+        def self.next_identifier
+          @identifier += 1
+        end
+
+        def initialize(options = {})
+          @identifier = self.class.next_identifier
+          @args = (options[:args] || {}).dup # because we modify it below
+          @access_token = options[:access_token]
+          @http_options = (options[:http_options] || {}).dup # dup because we modify it below
+          @batch_args = @http_options.delete(:batch_args) || {}
+          @url = options[:url]
+          @method = options[:method].to_sym
+          @post_processing = options[:post_processing]
+
+          process_binary_args
+
+          raise Koala::KoalaError, "Batch operations require an access token, none provided." unless @access_token
+        end
+
+        def to_batch_params(main_access_token)
+          # set up the arguments
+          args_string = Koala.http_service.encode_params(@access_token == main_access_token ? @args : @args.merge(:access_token => @access_token))
+
+          response = {
+            :method => @method.to_s,
+            :relative_url => @url,
+          }
+
+          # handle batch-level arguments, such as name, depends_on, and attached_files
+          @batch_args[:attached_files] = @files.keys.join(",") if @files
+          response.merge!(@batch_args) if @batch_args
+
+          # for get and delete, we append args to the URL string
+          # otherwise, they go in the body
+          if args_string.length > 0
+            if args_in_url?
+              response[:relative_url] += (@url =~ /\?/ ? "&" : "?") + args_string if args_string.length > 0
+            else
+              response[:body] = args_string if args_string.length > 0
+            end
+          end
+
+          response
+        end
+
+        protected
+
+        def process_binary_args
+          # collect binary files
+          @args.each_pair do |key, value|
+            if UploadableIO.binary_content?(value)
+              @files ||= {}
+              # we use a class-level counter to ensure unique file identifiers across multiple batch operations
+              # (this is thread safe, since we just care about uniqueness)
+              # so remove the file from the original hash and add it to the file store
+              id = "op#{identifier}_file#{@files.keys.length}"
+              @files[id] = @args.delete(key).is_a?(UploadableIO) ? value : UploadableIO.new(value)
+            end
+          end
+        end
+
+        def args_in_url?
+          @method == :get || @method == :delete
+        end
+      end
+    end
+
+    # @private
+    # legacy support for when BatchOperation lived directly under Koala::Facebook
+    BatchOperation = GraphBatchAPI::BatchOperation
+  end
+end

data/lib/koala/api/graph_api.rb

@@ -0,0 +1,476 @@
+require 'koala/api/graph_collection'
+require 'koala/http_service/uploadable_io'
+
+module Koala
+  module Facebook
+    GRAPH_SERVER = "graph.facebook.com"
+
+    # Methods used to interact with the Facebook Graph API.
+    #
+    # See https://github.com/arsduo/koala/wiki/Graph-API for a general introduction to Koala
+    # and the Graph API.
+    #
+    # The Graph API is made up of the objects in Facebook (e.g., people, pages,
+    # events, photos, etc.) and the connections between them (e.g., friends,
+    # photo tags, event RSVPs, etc.). Koala provides access to those
+    # objects types in a generic way. For example, given an OAuth access
+    # token, this will fetch the profile of the active user and the list
+    # of the user's friends:
+    #
+    # @example 
+    #         graph = Koala::Facebook::API.new(access_token)
+    #         user = graph.get_object("me")
+    #         friends = graph.get_connections(user["id"], "friends")
+    #
+    # You can see a list of all of the objects and connections supported
+    # by the API at http://developers.facebook.com/docs/reference/api/.
+    #
+    # You can obtain an access token via OAuth or by using the Facebook JavaScript SDK.  
+    # If you're using the JavaScript SDK, you can use the
+    # {Koala::Facebook::OAuth#get_user_from_cookie} method to get the OAuth access token
+    # for the active user from the cookie provided by Facebook.
+    # See the Koala and Facebook documentation for more information.
+    module GraphAPIMethods
+
+      # Objects
+
+      # Get information about a Facebook object.
+      # 
+      # @param id the object ID (string or number)
+      # @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)
+      # 
+      # @raise [Koala::Facebook::APIError] if the ID is invalid or you don't have access to that object
+      #
+      # @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)
+      end
+
+      # Get information about multiple Facebook objects in one call.
+      # 
+      # @param ids an array or comma-separated string of object IDs
+      # @param args (see #get_object)
+      # @param options (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.
+        # 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)
+      end
+
+      # Write an object to the Graph for a specific user.
+      # @see #put_connections
+      #
+      # @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 = {})
+        raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Write operations require an access token"}) unless @access_token
+        graph_call("#{parent_object}/#{connection_name}", args, "post", options)
+      end
+
+      # Delete an object from the Graph if you have appropriate permissions.
+      # 
+      # @param id (see #get_object)
+      # @param options (see #get_object)
+      #
+      # @return true if successful, false (or an APIError) if not
+      def delete_object(id, options = {})
+        # 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)
+      end
+
+      # Fetch information about a given connection (e.g. type of activity -- feed, events, photos, etc.)
+      # for a specific user.
+      # See {http://developers.facebook.com/docs/api Facebook's documentation} for a complete list of connections.
+      # 
+      # @note to access connections like /user_id/CONNECTION/other_user_id, 
+      #       simply pass "CONNECTION/other_user_id" as the connection_name
+      #
+      # @param id (see #get_object)
+      # @param connection_name what 
+      # @param args any additional arguments
+      # @param options (see #get_object)
+      # 
+      # @return [Koala::Facebook::API::GraphCollection] an array of object hashes (in most cases)
+      def get_connections(id, connection_name, args = {}, options = {})
+        # Fetchs the connections for given object.
+        graph_call("#{id}/#{connection_name}", args, "get", options)
+      end
+
+
+      # Write an object to the Graph for a specific user.
+      # See {http://developers.facebook.com/docs/api#publishing Facebook's documentation} 
+      # for all the supported writeable objects.
+      #
+      # @note (see #get_connections)
+      #
+      # @example
+      #         graph.put_object("me", "feed", :message => "Hello, world")
+      #         => writes "Hello, world" to the active user's wall
+      #
+      # Most write operations require extended permissions. For example,
+      # publishing wall posts requires the "publish_stream" permission. See
+      # http://developers.facebook.com/docs/authentication/ for details about
+      # extended permissions.
+      #
+      # @param id (see #get_object)
+      # @param connection_name (see #get_connections)
+      # @param args (see #get_connections)
+      # @param options (see #get_object)
+      #
+      # @return a hash containing the new object's id
+      def put_connections(id, connection_name, args = {}, options = {})
+        # 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)
+      end
+
+      # Delete an object's connection (for instance, unliking the object).
+      #
+      # @note (see #get_connections)
+      # 
+      # @param id (see #get_object)
+      # @param connection_name (see #get_connections) 
+      # @args (see #get_connections)
+      # @param options (see #get_object)
+      #
+      # @return (see #delete_object)
+      def delete_connections(id, connection_name, args = {}, options = {})
+        # 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)
+      end
+
+      # Fetches a photo.  
+      # (Facebook returns the src of the photo as a response header; this method parses that properly, 
+      # unlike using get_connections("photo").)
+      #
+      # @note to delete photos or videos, use delete_object(id)
+      #
+      # @return the URL to the image
+      def get_picture(object, args = {}, options = {})
+        # 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|
+          result["Location"]
+        end
+      end
+
+      # Upload a photo.
+      #
+      # This can be called in multiple ways:
+      #   put_picture(file, [content_type], ...)
+      #   put_picture(path_to_file, [content_type], ...)
+      #   put_picture(picture_url, ...)
+      #
+      # You can also pass in uploaded files directly from Rails or Sinatra.
+      # See {https://github.com/arsduo/koala/wiki/Uploading-Photos-and-Videos the Koala wiki} for more information.
+      #
+      # @param args (see #get_object)
+      # @param target_id the Facebook object to which to post the picture (default: "me")
+      # @param options (see #get_object)
+      #
+      # @example
+      #     put_picture(file, content_type, {:message => "Message"}, 01234560)
+      #     put_picture(params[:file], {:message => "Message"})
+      #     # with URLs, there's no optional content type field
+      #     put_picture(picture_url, {:message => "Message"}, my_page_id)
+      #
+      # @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_object(*parse_media_args(picture_args, "photos"))
+      end
+
+      # Upload a video.  Functions exactly the same as put_picture.
+      # @see #put_picture
+      def put_video(*video_args)
+        args = parse_media_args(video_args, "videos")
+        args.last[:video] = true
+        put_object(*args)
+      end
+
+      # Write directly to the user's wall.  
+      # Convenience method equivalent to put_object(id, "feed").
+      #
+      # To get wall posts, use get_connections(user, "feed")
+      # To delete a wall post, use delete_object(post_id)
+      #
+      # @param message the message to write for the wall
+      # @param attachment a hash describing the wall post
+      #         (see the {https://developers.facebook.com/docs/guides/attachments/ stream attachments} documentation.)
+      # @param target_id the target wall
+      # @param options (see #get_object)
+      #
+      # @example
+      #       @api.put_wall_post("Hello there!", {
+      #         "name" => "Link name"
+      #         "link" => "http://www.example.com/",
+      #         "caption" => "{*actor*} posted a new review",
+      #         "description" => "This is a longer description of the attachment",
+      #         "picture" => "http://www.example.com/thumbnail.jpg"
+      #       })
+      #
+      # @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)
+      end
+
+      # Comment on a given object.  
+      # Convenience method equivalent to put_connection(id, "comments").
+      #
+      # To delete comments, use delete_object(comment_id).
+      # To get comments, use get_connections(object, "likes").
+      #
+      # @param id (see #get_object)
+      # @param message the comment to write
+      # @param options (see #get_object)
+      #
+      # @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)
+      end
+
+      # Like a given object.  
+      # Convenience method equivalent to put_connections(id, "likes").
+      #
+      # To get a list of a user's or object's likes, use get_connections(id, "likes").
+      #
+      # @param id (see #get_object)
+      # @param options (see #get_object)
+      #
+      # @return (see #put_connections)
+      def put_like(id, options = {})
+        # Likes the given post.
+        self.put_object(id, "likes", {}, options)
+      end
+
+      # Unlike a given object.  
+      # Convenience method equivalent to delete_connection(id, "likes").
+      #
+      # @param id (see #get_object)
+      # @param options (see #get_object)
+      #
+      # @return (see #delete_object)
+      def delete_like(id, options = {})
+        # 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)
+      end
+
+      # Search for a given query among visible Facebook objects.
+      # See {http://developers.facebook.com/docs/reference/api/#searching Facebook documentation} for more information.
+      #
+      # @param search_terms the query to search for
+      # @param args additional arguments, such as type, fields, etc.
+      # @param options (see #get_object)
+      # 
+      # @return [Koala::Facebook::API::GraphCollection] an array of search results
+      def search(search_terms, args = {}, options = {})
+        args.merge!({:q => search_terms}) unless search_terms.nil?
+        graph_call("search", args, "get", options)
+      end
+
+      # Convenience Methods
+      # In general, we're trying to avoid adding convenience methods to Koala
+      # except to support cases where the Facebook API requires non-standard input
+      # such as JSON-encoding arguments, posts directly to objects, etc.
+      
+      # Make an FQL query.  
+      # Convenience method equivalent to get_object("fql", :q => query).
+      # 
+      # @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)
+      end
+
+      # Make an FQL multiquery.
+      # This method simplifies the result returned from multiquery into a more logical format.      
+      # 
+      # @param queries a hash of query names => FQL queries
+      # @param args (see #get_object)
+      # @param options (see #get_object)
+      #
+      # @example
+      #     @api.fql_multiquery({
+      #       "query1" => "select post_id from stream where source_id = me()", 
+      #       "query2" => "select fromid from comment where post_id in (select post_id from #query1)"
+      #     })
+      #     # returns {"query1" => [obj1, obj2, ...], "query2" => [obj3, ...]}
+      #     # 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.encode(queries)), options)
+          # simplify the multiquery result format
+          results.inject({}) {|outcome, data| outcome[data["name"]] = data["fql_result_set"]; outcome}
+        end
+      end
+      
+      # Get a page's access token, allowing you to act as the page.
+      # Convenience method for @api.get_object(page_id, :fields => "access_token").
+      #
+      # @param id the page ID
+      # @param args (see #get_object)
+      # @param options (see #get_object)      
+      #
+      # @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
+          result ? result["access_token"] : nil
+        end
+      end
+
+      # Fetchs 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)
+      # 
+      # @returns a hash of urls => comment arrays
+      def get_comments_for_urls(urls = [], args = {}, options = {})
+        return [] if urls.empty?
+        args.merge!(:ids => urls.respond_to?(:join) ? urls.join(",") : urls)
+        get_object("comments", args, options)
+      end
+      
+      def set_app_restrictions(app_id, restrictions_hash, args = {}, options = {})
+        graph_call(app_id, args.merge(:restrictions => MultiJson.encode(restrictions_hash)), "post", options)
+      end
+
+      # Certain calls such as {#get_connections} return an array of results which you can page through
+      # forwards and backwards (to see more feed stories, search results, etc.).
+      # Those methods use get_page to request another set of results from Facebook.
+      # 
+      # @note You'll rarely need to use this method unless you're using Sinatra or another non-Rails framework
+      #       (see {Koala::Facebook::GraphCollection GraphCollection} for more information).    
+      #
+      # @param params an array of arguments to graph_call
+      #               as returned by {Koala::Facebook::GraphCollection.parse_page_url}.
+      #
+      # @return Koala::Facebook::GraphCollection the appropriate page of results (an empty array if there are none)
+      def get_page(params)
+        graph_call(*params)
+      end
+
+      # Execute a set of Graph API calls as a batch. 
+      # See {https://github.com/arsduo/koala/wiki/Batch-requests batch request documentation} 
+      # for more information and examples.
+      # 
+      # @param http_options HTTP options for the entire request.
+      #
+      # @yield batch_api [Koala::Facebook::GraphBatchAPI] an API subclass
+      #                  whose requests will be queued and executed together at the end of the block
+      #
+      # @raise [Koala::Facebook::APIError] only if there is a problem with the overall batch request
+      #                                    (e.g. connectivity failure, an operation with a missing dependency).
+      #                                    Individual calls that error out will be represented as an unraised
+      #                                    APIError in the appropriate spot in the results array.
+      #
+      # @example
+      #         results = @api.batch do |batch_api|
+      #          batch_api.get_object('me')
+      #          batch_api.get_object(KoalaTest.user1)
+      #         end
+      #         # => [{"id" => my_id, ...}, {"id"" => koppel_id, ...}]
+      #
+      # @return an array of results from your batch calls (as if you'd made them individually), 
+      #         arranged in the same order they're made.
+      def batch(http_options = {}, &block)
+        batch_client = GraphBatchAPI.new(access_token, self)
+        if block
+          yield batch_client
+          batch_client.execute(http_options)
+        else
+          batch_client
+        end
+      end
+      
+      # 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} or {#fql_multiquery} 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)
+        result = api(path, args, verb, options) do |response|
+          error = check_response(response)
+          raise error if error
+        end
+
+        # turn this into a GraphCollection if it's pageable
+        result = GraphCollection.evaluate(result, self)
+        
+        # now process as appropriate for the given call (get picture header, etc.)
+        post_processing ? post_processing.call(result) : result
+      end
+
+      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)
+        end
+      end
+
+      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
+        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
+
+        args      = media_args[1 + args_offset] || {}
+        target_id = media_args[2 + args_offset] || "me"
+        options   = media_args[3 + args_offset] || {}
+
+        if url?(media_args.first)
+          # If media_args is a URL, we can upload without UploadableIO
+          args.merge!(:url => media_args.first)
+        else
+          args["source"] = Koala::UploadableIO.new(*media_args.slice(0, 1 + args_offset))
+        end
+
+        [target_id, method, args, options]
+      end
+
+      def url?(data)
+        return false unless data.is_a? String
+        begin
+          uri = URI.parse(data)
+          %w( http https ).include?(uri.scheme)
+        rescue URI::BadURIError
+          false
+        end
+      end
+    end
+  end
+end