koala 1.3.0 → 1.4.0.rc1

data/.travis.yml

@@ -1,13 +1,10 @@
 rvm:
-  - 1.8.7 # (current default)
+  - 1.8.7
   - 1.9.2
   - 1.9.3
   - ruby-head
-  - rbx
-  - rbx-2.0
-  - ree
-  - jruby
-
-branches:
-  except:
-    - rdoc
+  - jruby-18mode # JRuby in 1.8 mode
+  - jruby-19mode # JRuby in 1.9 mode
+  - rbx-18mode
+  - rbx-19mode
+  - ree

data/CHANGELOG

@@ -1,3 +1,17 @@
+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 a readme typo (thanks, brycethornton!)
+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
@@ -24,7 +38,7 @@ 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 
+-- Configured tests to run in random order using RSpec 2.8.0rc1
 
 v1.2.1
 New methods:

data/Gemfile

@@ -5,11 +5,12 @@ group :development do
 end
 
 group :development, :test do
-  gem "typhoeus"
+  gem "typhoeus" unless defined? JRUBY_VERSION
 
   # Testing infrastructure
   gem 'guard'
   gem 'guard-rspec'
+  gem "parallel_tests"
 
   if RUBY_PLATFORM =~ /darwin/
     # OS X integration
@@ -18,8 +19,6 @@ group :development, :test do
   end
 end
 
-if defined? JRUBY_VERSION
-  gem "jruby-openssl"
-end
+gem "jruby-openssl" if defined? JRUBY_VERSION
 
 gemspec

data/lib/koala/api/graph_api.rb

@@ -17,7 +17,7 @@ module Koala
     # token, this will fetch the profile of the active user and the list
     # of the user's friends:
     #
-    # @example 
+    # @example
     #         graph = Koala::Facebook::API.new(access_token)
     #         user = graph.get_object("me")
     #         friends = graph.get_connections(user["id"], "friends")
@@ -25,7 +25,7 @@ module Koala
     # 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.  
+    # 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.
@@ -35,12 +35,12 @@ module Koala
       # Objects
 
       # Get information about a Facebook object.
-      # 
+      #
       # @param id the object ID (string or number)
-      # @param args any additional arguments 
+      # @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
@@ -50,11 +50,11 @@ module Koala
       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
@@ -70,14 +70,14 @@ 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. 
+      #       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)
       #
@@ -91,27 +91,28 @@ module Koala
       # 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, 
+      #
+      # @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 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 = {})
+      def get_connection(id, connection_name, args = {}, options = {})
         # Fetchs the connections for given object.
         graph_call("#{id}/#{connection_name}", args, "get", options)
       end
+      alias_method :get_connections, :get_connection
 
 
       # Write an object to the Graph for a specific user.
-      # See {http://developers.facebook.com/docs/api#publishing Facebook's documentation} 
+      # See {http://developers.facebook.com/docs/api#publishing Facebook's documentation}
       # for all the supported writeable objects.
       #
-      # @note (see #get_connections)
+      # @note (see #get_connection)
       #
       # @example
       #         graph.put_object("me", "feed", :message => "Hello, world")
@@ -123,8 +124,8 @@ module Koala
       # extended permissions.
       #
       # @param id (see #get_object)
-      # @param connection_name (see #get_connections)
-      # @param args (see #get_connections)
+      # @param connection_name (see #get_connection)
+      # @param args (see #get_connection)
       # @param options (see #get_object)
       #
       # @return a hash containing the new object's id
@@ -136,11 +137,11 @@ module Koala
 
       # Delete an object's connection (for instance, unliking the object).
       #
-      # @note (see #get_connections)
-      # 
+      # @note (see #get_connection)
+      #
       # @param id (see #get_object)
-      # @param connection_name (see #get_connections) 
-      # @args (see #get_connections)
+      # @param connection_name (see #get_connection)
+      # @args (see #get_connection)
       # @param options (see #get_object)
       #
       # @return (see #delete_object)
@@ -150,10 +151,13 @@ module Koala
         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, 
+      # Fetches a photo.
+      # (Facebook returns the src of the photo as a response header; this method parses that properly,
       # unlike using get_connections("photo").)
       #
+      # @param options options for Facebook (see #get_object).
+      #                        To get a different size photo, pass :type => size (small, normal, large, square).
+      #
       # @note to delete photos or videos, use delete_object(id)
       #
       # @return the URL to the image
@@ -199,7 +203,7 @@ module Koala
         put_object(*args)
       end
 
-      # Write directly to the user's wall.  
+      # Write directly to the user's wall.
       # Convenience method equivalent to put_object(id, "feed").
       #
       # To get wall posts, use get_connections(user, "feed")
@@ -220,13 +224,13 @@ module Koala
       #         "picture" => "http://www.example.com/thumbnail.jpg"
       #       })
       #
-      # @see #put_connections      
+      # @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.  
+      # Comment on a given object.
       # Convenience method equivalent to put_connection(id, "comments").
       #
       # To delete comments, use delete_object(comment_id).
@@ -242,7 +246,7 @@ module Koala
         self.put_object(id, "comments", {:message => message}, options)
       end
 
-      # Like a given object.  
+      # 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").
@@ -256,7 +260,7 @@ module Koala
         self.put_object(id, "likes", {}, options)
       end
 
-      # Unlike a given object.  
+      # Unlike a given object.
       # Convenience method equivalent to delete_connection(id, "likes").
       #
       # @param id (see #get_object)
@@ -275,7 +279,7 @@ module Koala
       # @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?
@@ -286,10 +290,10 @@ module Koala
       # 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.  
+
+      # 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)
@@ -298,15 +302,15 @@ module Koala
       end
 
       # Make an FQL multiquery.
-      # This method simplifies the result returned from multiquery into a more logical format.      
-      # 
+      # 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()", 
+      #       "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, ...]}
@@ -319,15 +323,15 @@ module Koala
           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)      
+      # @param options (see #get_object)
       #
-      # @return the page's access token (discarding expiration and any other information)      
+      # @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
@@ -340,14 +344,14 @@ module Koala
       # @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
@@ -355,9 +359,9 @@ module Koala
       # 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).    
+      #       (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}.
@@ -367,10 +371,10 @@ module Koala
         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} 
+      # 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
@@ -388,7 +392,7 @@ module Koala
       #         end
       #         # => [{"id" => my_id, ...}, {"id"" => koppel_id, ...}]
       #
-      # @return an array of results from your batch calls (as if you'd made them individually), 
+      # @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)
@@ -399,7 +403,7 @@ module Koala
           batch_client
         end
       end
-      
+
       # Make a call directly to the Graph API.
       # (See any of the other methods for example invocations.)
       #
@@ -408,12 +412,12 @@ module Koala
       # @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.  
+      # @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
@@ -425,13 +429,13 @@ module Koala
 
         # 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)

data/lib/koala/http_service.rb

@@ -86,7 +86,7 @@ module Koala
     #
     # @return the appropriately-encoded string
     def self.encode_params(param_hash)
-      ((param_hash || {}).collect do |key_and_value|
+      ((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[0].to_s}=#{CGI.escape key_and_value[1]}"
       end).join("&")

data/lib/koala/oauth.rb

@@ -4,12 +4,12 @@ require 'base64'
 
 module Koala
   module Facebook
-    
+
     DIALOG_HOST = "www.facebook.com"
-    
+
     class OAuth
       attr_reader :app_id, :app_secret, :oauth_callback_url
-      
+
       # Creates a new OAuth client.
       #
       # @param app_id [String, Integer] a Facebook application ID
@@ -20,14 +20,14 @@ module Koala
         @app_secret = app_secret
         @oauth_callback_url = oauth_callback_url
       end
-      
+
       # Parses the cookie set Facebook's JavaScript SDK.
       #
       # @note in parsing Facebook's new signed cookie format this method has to make a request to Facebook.
       #       We recommend storing authenticated user info in your Rails session (or equivalent) and only
       #       calling this when needed.
       #
-      # @param cookie_hash a set of cookies that includes the Facebook cookie.  
+      # @param cookie_hash a set of cookies that includes the Facebook cookie.
       #                     You can pass Rack/Rails/Sinatra's cookie hash directly to this method.
       #
       # @return the authenticated user's information as a hash, or nil.
@@ -60,21 +60,21 @@ module Koala
       alias_method :get_user_from_cookie, :get_user_from_cookies
 
       # URLs
-      
+
       # Builds an OAuth URL, where users will be prompted to log in and for any desired permissions.
-      # When the users log in, you receive a callback with their   
+      # When the users log in, you receive a callback with their
       # See http://developers.facebook.com/docs/authentication/.
       #
       # @see #url_for_access_token
       #
-      # @note The server-side authentication and dialog methods should only be used 
+      # @note The server-side authentication and dialog methods should only be used
       #       if your application can't use the Facebook Javascript SDK,
       #       which provides a much better user experience.
       #       See http://developers.facebook.com/docs/reference/javascript/.
       #
       # @param options any query values to add to the URL, as well as any special/required values listed below.
       # @option options permissions an array or comma-separated string of desired permissions
-      # 
+      #
       # @raise ArgumentError if no OAuth callback was specified in OAuth#new or in options as :redirect_uri
       #
       # @return an OAuth URL you can send your users to
@@ -84,7 +84,7 @@ module Koala
           options[:scope] = permissions.is_a?(Array) ? permissions.join(",") : permissions
         end
         url_options = {:client_id => @app_id}.merge(options)
-        
+
         # Creates the URL for oauth authorization for a given callback and optional set of permissions
         build_url("https://#{GRAPH_SERVER}/oauth/authorize", true, url_options)
       end
@@ -92,9 +92,9 @@ module Koala
       # Once you receive an OAuth code, you need to redeem it from Facebook using an appropriate URL.
       # (This is done by your server behind the scenes.)
       # See http://developers.facebook.com/docs/authentication/.
-      # 
+      #
       # @see #url_for_oauth_code
-      # 
+      #
       # @note (see #url_for_oauth_code)
       #
       # @param code an OAuth code received from Facebook
@@ -106,7 +106,7 @@ module Koala
       def url_for_access_token(code, options = {})
         # Creates the URL for the token corresponding to a given code generated by Facebook
         url_options = {
-          :client_id => @app_id, 
+          :client_id => @app_id,
           :code => code,
           :client_secret => @app_secret
         }.merge(options)
@@ -115,7 +115,7 @@ module Koala
 
       # Builds a URL for a given dialog (feed, friends, OAuth, pay, send, etc.)
       # See http://developers.facebook.com/docs/reference/dialogs/.
-      # 
+      #
       # @note (see #url_for_oauth_code)
       #
       # @param dialog_type the kind of Facebook dialog you want to show
@@ -124,37 +124,37 @@ module Koala
       # @return an URL your server can query for the user's access token
       def url_for_dialog(dialog_type, options = {})
         # some endpoints require app_id, some client_id, supply both doesn't seem to hurt
-        url_options = {:app_id => @app_id, :client_id => @app_id}.merge(options)        
+        url_options = {:app_id => @app_id, :client_id => @app_id}.merge(options)
         build_url("http://#{DIALOG_HOST}/dialog/#{dialog_type}", true, url_options)
       end
-      
+
       # access tokens
-      
+
       # Fetches an access token, token expiration, and other info from Facebook.
       # Useful when you've received an OAuth code using the server-side authentication process.
       # @see url_for_oauth_code
       #
       # @note (see #url_for_oauth_code)
-      # 
+      #
       # @param code (see #url_for_access_token)
       # @param options any additional parameters to send to Facebook when redeeming the token
-      # 
-      # @raise Koala::Facebook::APIError if Facebook returns an error response 
-      # 
-      # @return a hash of the access token info returned by Facebook (token, expiration, etc.) 
+      #
+      # @raise Koala::Facebook::APIError if Facebook returns an error response
+      #
+      # @return a hash of the access token info returned by Facebook (token, expiration, etc.)
       def get_access_token_info(code, options = {})
         # convenience method to get a parsed token from Facebook for a given code
         # should this require an OAuth callback URL?
         get_token_from_server({:code => code, :redirect_uri => options[:redirect_uri] || @oauth_callback_url}, false, options)
       end
 
-      
+
       # Fetches the access token (ignoring expiration and other info) from Facebook.
       # Useful when you've received an OAuth code using the server-side authentication process.
       # @see get_access_token_info
-      # 
+      #
       # @note (see #url_for_oauth_code)
-      # 
+      #
       # @param (see #get_access_token_info)
       #
       # @raise (see #get_access_token_info)
@@ -169,7 +169,7 @@ module Koala
 
       # Fetches the application's access token, along with any other information provided by Facebook.
       # See http://developers.facebook.com/docs/authentication/ (search for App Login).
-      # 
+      #
       # @param options any additional parameters to send to Facebook when redeeming the token
       #
       # @return the application access token and other information (expiration, etc.)
@@ -180,7 +180,7 @@ module Koala
 
       # Fetches the application's access token (ignoring expiration and other info).
       # @see get_app_access_token_info
-      # 
+      #
       # @param (see #get_app_access_token_info)
       #
       # @return the application access token
@@ -190,13 +190,40 @@ module Koala
         end
       end
 
+      # Fetches an access_token with extended expiration time, along with any other information provided by Facebook.
+      # See https://developers.facebook.com/docs/offline-access-deprecation/#extend_token (search for fb_exchange_token).
+      #
+      # @param access_token the access token to exchange
+      # @param options any additional parameters to send to Facebook when exchanging tokens.
+      #
+      # @return the access token with extended expiration time and other information (expiration, etc.)
+      def exchange_access_token_info(access_token, options = {})
+        get_token_from_server({
+          :grant_type => 'fb_exchange_token',
+          :fb_exchange_token => access_token
+        }, true, options)
+      end
+
+      # Fetches an access token with extended expiration time (ignoring expiration and other info).
+
+      # @see exchange_access_token_info
+      #
+      # @param (see #exchange_access_token_info)
+      #
+      # @return A new access token or the existing one, set to expire in 60 days.
+      def exchange_access_token(access_token, options = {})
+        if info = exchange_access_token_info(access_token, options)
+          info["access_token"]
+        end
+      end
+
       # Parses a signed request string provided by Facebook to canvas apps or in a secure cookie.
       #
       # @param input the signed request from Facebook
-      # 
+      #
       # @raise RuntimeError if the signature is incomplete, invalid, or using an unsupported algorithm
-      # 
-      # @return a hash of the validated request information 
+      #
+      # @return a hash of the validated request information
       def parse_signed_request(input)
         encoded_sig, encoded_envelope = input.split('.', 2)
         raise 'SignedRequest: Invalid (incomplete) signature data' unless encoded_sig && encoded_envelope
@@ -214,7 +241,7 @@ module Koala
       end
 
       # Old session key code
-      
+
       # @deprecated Facebook no longer provides session keys.
       def get_token_info_from_session_keys(sessions, options = {})
         Koala::Utils.deprecate("Facebook no longer provides session keys. The relevant OAuth methods will be removed in the next release.")
@@ -271,7 +298,7 @@ module Koala
         end
         components
       end
-      
+
       def parse_unsigned_cookie(fb_cookie)
         # remove the opening/closing quote
         fb_cookie = fb_cookie.gsub(/\"/, "")
@@ -285,7 +312,7 @@ module Koala
         sig = Digest::MD5.hexdigest(auth_string + @app_secret)
         sig == components["sig"] && (components["expires"] == "0" || Time.now.to_i < components["expires"].to_i) ? components : nil
       end
-      
+
       def parse_signed_cookie(fb_cookie)
         components = parse_signed_request(fb_cookie)
         if code = components["code"]
@@ -315,12 +342,12 @@ module Koala
         str += '=' * (4 - str.length.modulo(4))
         Base64.decode64(str.tr('-_', '+/'))
       end
-      
+
       def build_url(base, require_redirect_uri = false, url_options = {})
-        if require_redirect_uri && !(url_options[:redirect_uri] ||= url_options.delete(:callback) || @oauth_callback_url)          
+        if require_redirect_uri && !(url_options[:redirect_uri] ||= url_options.delete(:callback) || @oauth_callback_url)
           raise ArgumentError, "url_for_dialog must get a callback either from the OAuth object or in the parameters!"
         end
-        
+
         "#{base}?#{Koala::HTTPService.encode_params(url_options)}"
       end
     end