koala 1.2.1 → 1.3.0rc1

data/.rspec

@@ -0,0 +1 @@
+--color --order rand

data/CHANGELOG

@@ -1,3 +1,21 @@
+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
+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)
+Internal improvements:
+-- FQL queries now use the Graph API behind-the-scenes
+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

data/koala.gemspec

@@ -32,17 +32,17 @@ Gem::Specification.new do |s|
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<multi_json>,      ["~> 1.0"])
       s.add_runtime_dependency(%q<faraday>,  ["~> 0.7.0"])
-      s.add_development_dependency(%q<rspec>,     ["~> 2.5"])
+      s.add_development_dependency(%q<rspec>,     ["~> 2.8.0rc1"])
       s.add_development_dependency(%q<rake>,      ["~> 0.8.7"])
     else
       s.add_dependency(%q<multi_json>,      ["~> 1.0"])
-      s.add_dependency(%q<rspec>,     ["~> 2.5"])
+      s.add_dependency(%q<rspec>,     ["~> 2.8.0rc1"])
       s.add_dependency(%q<rake>,      ["~> 0.8.7"])
       s.add_dependency(%q<faraday>,  ["~> 0.7.0"])
     end
   else
     s.add_dependency(%q<multi_json>,      ["~> 1.0"])
-    s.add_dependency(%q<rspec>,     ["~> 2.5"])
+    s.add_dependency(%q<rspec>,     ["~> 2.8.0rc1"])
     s.add_dependency(%q<rake>,      ["~> 0.8.7"])
     s.add_dependency(%q<faraday>,  ["~> 0.7.0"])
   end

data/lib/koala.rb

@@ -100,8 +100,9 @@ module Koala
     # Errors
 
     class APIError < StandardError
-      attr_accessor :fb_error_type
+      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

data/lib/koala/graph_api.rb

@@ -176,9 +176,24 @@ module Koala
       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.
+      
+      def fql_query(query, args = {}, options = {})
+        get_object("fql", args.merge(:q => query), options)
+      end
 
-      def get_page_access_token(object_id)
-        result = get_object(object_id, :fields => "access_token") do
+      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
+      
+      def get_page_access_token(object_id, args = {}, options = {})
+        result = get_object(object_id, args.merge(:fields => "access_token"), options) do
           result ? result["access_token"] : nil
         end
       end
@@ -190,6 +205,10 @@ module Koala
         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
 
       # GraphCollection support
       def get_page(params)

data/lib/koala/graph_batch_api.rb

@@ -38,7 +38,8 @@ module Koala
 
       def check_graph_batch_api_response(response)
         if response.is_a?(Hash) && response["error"] && !response["error"].is_a?(Hash)
-          APIError.new("type" => "Error #{response["error"]}", "message" => response["error_description"])
+          # old error format -- see http://developers.facebook.com/blog/post/596/
+          APIError.new({"type" => "Error #{response["error"]}", "message" => response["error_description"]}.merge(response))
         else
           check_graph_api_response(response)
         end

data/lib/koala/graph_collection.rb

@@ -41,8 +41,12 @@ module Koala
           parse_page_url(@paging[this])
         end
       end
-
+      
       def parse_page_url(url)
+        GraphCollection.parse_page_url(url)
+      end
+
+      def self.parse_page_url(url)
         match = url.match(/.com\/(.*)\?(.*)/)
         base = match[1]
         args = match[2]

data/lib/koala/http_service.rb

@@ -11,9 +11,8 @@ module Koala
   end
 
   module HTTPService
-    # common functionality for all HTTP services
-
     class << self
+
       attr_accessor :faraday_middleware, :http_options
     end
 

data/lib/koala/oauth.rb

@@ -1,5 +1,8 @@
 module Koala
   module Facebook
+    
+    DIALOG_HOST = "www.facebook.com"
+    
     class OAuth
       attr_reader :app_id, :app_secret, :oauth_callback_url
       def initialize(app_id, app_secret, oauth_callback_url = nil)
@@ -7,7 +10,7 @@ module Koala
         @app_secret = app_secret
         @oauth_callback_url = oauth_callback_url
       end
-
+      
       def get_user_info_from_cookie(cookie_hash)
         # Parses the cookie set Facebook's JavaScript SDK.
         # You can pass Rack/Rails/Sinatra's cookie hash directly to this method.
@@ -34,27 +37,36 @@ module Koala
       alias_method :get_user_from_cookies, :get_user_from_cookie
 
       # URLs
-
+      
       def url_for_oauth_code(options = {})
         # for permissions, see http://developers.facebook.com/docs/authentication/permissions
-        permissions = options[:permissions]
-        scope = permissions ? "&scope=#{permissions.is_a?(Array) ? permissions.join(",") : permissions}" : ""
-        display = options.has_key?(:display) ? "&display=#{options[:display]}" : ""
-
-        callback = options[:callback] || @oauth_callback_url
-        raise ArgumentError, "url_for_oauth_code must get a callback either from the OAuth object or in the options!" unless callback
-
+        if permissions = options.delete(:permissions)
+          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
-        "https://#{GRAPH_SERVER}/oauth/authorize?client_id=#{@app_id}&redirect_uri=#{callback}#{scope}#{display}"
+        build_url("https://#{GRAPH_SERVER}/oauth/authorize", true, url_options)
       end
 
       def url_for_access_token(code, options = {})
         # Creates the URL for the token corresponding to a given code generated by Facebook
-        callback = options[:callback] || @oauth_callback_url
-        raise ArgumentError, "url_for_access_token must get a callback either from the OAuth object or in the parameters!" unless callback
-        "https://#{GRAPH_SERVER}/oauth/access_token?client_id=#{@app_id}&redirect_uri=#{callback}&client_secret=#{@app_secret}&code=#{code}"
+        url_options = {
+          :client_id => @app_id, 
+          :code => code,
+          :client_secret => @app_secret
+        }.merge(options)
+        build_url("https://#{GRAPH_SERVER}/oauth/access_token", true, url_options)
       end
 
+      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)        
+        build_url("http://#{DIALOG_HOST}/dialog/#{dialog_type}", true, url_options)
+      end
+      
+      # access tokens
+      
       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?
@@ -189,6 +201,14 @@ 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)          
+          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
   end
 end

data/lib/koala/rest_api.rb

@@ -2,18 +2,7 @@ module Koala
   module Facebook
     REST_SERVER = "api.facebook.com"
 
-    module RestAPIMethods
-      def fql_query(fql, args = {}, options = {})
-        rest_call('fql.query', args.merge(:query => fql), options)
-      end
-
-      def fql_multiquery(queries = {}, args = {}, options = {})
-        if results = rest_call('fql.multiquery', args.merge(:queries => MultiJson.encode(queries)), options)
-          # simplify the multiquery result format
-          results.inject({}) {|outcome, data| outcome[data["name"]] = data["fql_result_set"]; outcome}
-        end
-      end
-      
+    module RestAPIMethods      
       def set_app_properties(properties, args = {}, options = {})
         raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "setAppProperties requires an access token"}) unless @access_token
         rest_call("admin.setAppProperties", args.merge(:properties => MultiJson.encode(properties)), options, "post")

data/lib/koala/utils.rb

@@ -1,10 +1,13 @@
 module Koala
   module Utils
+
+    DEPRECATION_PREFIX = "KOALA: Deprecation warning: "
     def self.deprecate(message)
-      begin
-        send(:warn, "KOALA: Deprecation warning: #{message}")
-      rescue Exception => err
-        puts "Unable to issue Koala deprecation warning!  #{err.message}"
+      @posted_deprecations ||= []
+      unless @posted_deprecations.include?(message)
+        # only include each message once
+        Kernel.warn("#{DEPRECATION_PREFIX}#{message}")
+        @posted_deprecations << message
       end
     end
   end

data/lib/koala/version.rb

@@ -1,3 +1,3 @@
 module Koala
-  VERSION = "1.2.1"
+  VERSION = "1.3.0rc1"
 end

data/readme.md

@@ -6,13 +6,8 @@ Koala
 
 * Lightweight: Koala should be as light and simple as Facebook’s own libraries, providing API accessors and returning simple JSON.
 * Fast: Koala should, out of the box, be quick. Out of the box, we use Facebook's faster read-only servers when possible and if available, the Typhoeus gem to make snappy Facebook requests.  Of course, that brings us to our next topic:
-* Flexible: Koala should be useful to everyone, regardless of their current configuration.  (We support JRuby, Rubinius, and REE as well as vanilla Ruby, and use the Faraday library to provide complete flexibility over how HTTP requests are made.)
-* Tested: Koala should have complete test coverage, so you can rely on it.  (Our test coverage is complete and can be run against either mocked responses or the live Facebook servers.)
-
-Facebook Changes on October 1, 2011
----
-
-Koala 1.2 supports all of Facebook's new authentication schemes, which were introduced on October 1, 2011.  If you have the appropriate calls to get_user_info_from_cookies (apps using the Javascript SDK) and/or parse_signed_params (for Canvas and tab apps), your application should work without a hitch.  For more information, see Facebook's [OAuth 2.0 and HTTPS Migration](https://developers.facebook.com/docs/oauth2-https-migration/) guide.  
+* Flexible: Koala should be useful to everyone, regardless of their current configuration.  We support JRuby, Rubinius, and REE as well as vanilla Ruby (1.8.7, 1.9.2, and 1.9.3), and use the Faraday library to provide complete flexibility over how HTTP requests are made.
+* Tested: Koala should have complete test coverage, so you can rely on it.  Our test coverage is complete and can be run against either mocked responses or the live Facebook servers; we're also on [Travis CI](travis-ci.org/arsduo/koala/).
 
 Installation
 ---
@@ -35,7 +30,10 @@ The Graph API is the simple, slick new interface to Facebook's data.  Using it w
     profile = @graph.get_object("me")
     friends = @graph.get_connections("me", "friends")
     @graph.put_object("me", "feed", :message => "I am writing on my wall!")
-
+   
+    # three-part queries are easy too!
+    @graph.get_connection("me", "mutualfriends/#{friend_id}")
+    
     # you can even use the new Timeline API
     # see https://developers.facebook.com/docs/beta/opengraph/tutorial/
     @graph.put_connections("me", "namespace:action", :object => object_url)
@@ -131,7 +129,7 @@ Koala makes it easy to interact with your applications using the RealtimeUpdates
 You can do just about anything with your real-time update subscriptions using the RealtimeUpdates class:
 
     # Add/modify a subscription to updates for when the first_name or last_name fields of any of your users is changed
-    @updates.subscribe("user", "first_name, last_name", callback_token, verify_token)
+    @updates.subscribe("user", "first_name, last_name", callback_url, verify_token)
 
     # Get an array of your current subscriptions (one hash for each object you've subscribed to)
     @updates.list_subscriptions
@@ -179,6 +177,8 @@ Some resources to help you as you play with Koala and the Graph API:
 * The <a href="http://groups.google.com/group/koala-users">Koala users group</a> on Google Groups, the place for your Koala and API questions
 * Facebook's <a href="http://developers.facebook.com/tools/explorer/">Graph API Explorer</a>, where you can play with the Graph API in your browser
 * The Koala-powered <a href="http://oauth.twoalex.com" target="_blank">OAuth Playground</a>, where you can easily generate OAuth access tokens and any other data needed to test out the APIs or OAuth
+* Follow Koala on <a href="http://www.facebook.com/pages/Koala/315368291823667">Facebook</a> and <a href="https://twitter.com/#!/koala_fb">Twitter</a> for SDK updates and occasional news about Facebook API changes.
+
 
 Testing
 -----

data/spec/cases/error_spec.rb

@@ -10,6 +10,16 @@ describe Koala::Facebook::APIError do
     Koala::Facebook::APIError.instance_methods.map(&:to_sym).should include(:fb_error_type=)
   end
 
+  it "has an accessor for raw_response" do
+    Koala::Facebook::APIError.instance_methods.map(&:to_sym).should include(:raw_response)
+    Koala::Facebook::APIError.instance_methods.map(&:to_sym).should include(:raw_response=)
+  end
+
+  it "sets raw_response to the provided error details" do
+    error_response = {"type" => "foo", "other_details" => "bar"}
+    Koala::Facebook::APIError.new(error_response).raw_response.should == error_response
+  end
+  
   it "sets fb_error_type to details['type']" do
     type = "foo"
     Koala::Facebook::APIError.new("type" => type).fb_error_type.should == type

data/spec/cases/graph_api_batch_spec.rb

@@ -22,7 +22,7 @@ describe "Koala::Facebook::GraphAPI in batch mode" do
       }
     end
 
-    describe "#new" do
+    describe ".new" do
       it "makes http_options accessible" do
         Koala::Facebook::BatchOperation.new(@args).http_options.should == @args[:http_options]
       end
@@ -108,7 +108,7 @@ describe "Koala::Facebook::GraphAPI in batch mode" do
 
     end
 
-    describe ".to_batch_params" do
+    describe "#to_batch_params" do
       describe "handling arguments and URLs" do
         shared_examples_for "request with no body" do
           it "adds the args to the URL string, with ? if no args previously present" do
@@ -263,7 +263,6 @@ describe "Koala::Facebook::GraphAPI in batch mode" do
   end
 
   describe "GraphAPI batch interface" do
-
     it "returns nothing for a batch operation" do
       Koala.stub(:make_request).and_return(Koala::Response.new(200, "[]", {}))
       @api.batch do |batch_api|
@@ -366,18 +365,69 @@ describe "Koala::Facebook::GraphAPI in batch mode" do
       end
 
       describe "processing the request" do
-        it "throws an error if the response is not 200" do
-          Koala.stub(:make_request).and_return(Koala::Response.new(500, "[]", {}))
-          expect { Koala::Facebook::API.new("foo").batch do |batch_api|
-            batch_api.get_object('me')
-          end }.to raise_exception(Koala::Facebook::APIError)
+        it "returns the result headers as a hash if http_component is headers" do
+          Koala.stub(:make_request).and_return(Koala::Response.new(200, '[{"code":203,"headers":[{"name":"Content-Type","value":"text/javascript; charset=UTF-8"}],"body":"{\"id\":\"1234\"}"}]', {}))
+          result = @api.batch do |batch_api|
+            batch_api.get_object(KoalaTest.user1, {}, :http_component => :headers)
+          end
+          result[0].should == {"Content-Type" => "text/javascript; charset=UTF-8"}
         end
+        
+        describe "if it errors" do
+          it "raises an APIError if the response is not 200" do
+            Koala.stub(:make_request).and_return(Koala::Response.new(500, "[]", {}))
+            expect { 
+              Koala::Facebook::API.new("foo").batch {|batch_api| batch_api.get_object('me') }
+            }.to raise_exception(Koala::Facebook::APIError)
+          end
 
-        it "throws an error if the response is a Batch API-style error" do
-          Koala.stub(:make_request).and_return(Koala::Response.new(200, '{"error":190,"error_description":"Error validating access token."}', {}))
-          expect { Koala::Facebook::API.new("foo").batch do |batch_api|
-            batch_api.get_object('me')
-          end }.to raise_exception(Koala::Facebook::APIError)
+          context "with the old style" do
+            before :each do
+              Koala.stub(:make_request).and_return(Koala::Response.new(200, '{"error":190,"error_description":"Error validating access token."}', {}))
+            end
+            
+            it "throws an error if the response is an old Batch API-style error" do
+              expect { 
+                Koala::Facebook::API.new("foo").batch {|batch_api| batch_api.get_object('me') }
+              }.to raise_exception(Koala::Facebook::APIError)
+            end   
+            
+            it "provides a type for the error if the response is an old Batch API-style error" do
+              begin
+                Koala::Facebook::API.new("foo").batch {|batch_api| batch_api.get_object('me') }
+              rescue Koala::Facebook::APIError => err
+              end
+              err.fb_error_type.should
+            end         
+            
+            it "passes all the error details if an old Batch API-style error is raised" do
+              begin
+                Koala::Facebook::API.new("foo").batch {|batch_api| batch_api.get_object('me') }
+              rescue Koala::Facebook::APIError => err
+              end
+              err.raw_response["error"].should == 190
+            end
+          end
+          
+          context "with the new style" do          
+            before :each do
+              Koala.stub(:make_request).and_return(Koala::Response.new(200, '{"error":{"message":"Request 0 cannot depend on an  unresolved request with  name f. Requests can only depend on preceding requests","type":"GraphBatchException"}}', {}))
+            end
+
+            it "throws an error if the response is a new Graph API-style error" do
+              expect { 
+                Koala::Facebook::API.new("foo").batch {|batch_api| batch_api.get_object('me') }
+              }.to raise_exception(Koala::Facebook::APIError)
+            end
+            
+            it "passes all the error details if an old Batch API-style error is raised" do
+              begin
+                Koala::Facebook::API.new("foo").batch {|batch_api| batch_api.get_object('me') }
+              rescue Koala::Facebook::APIError => err
+              end
+              err.raw_response["message"].should
+            end
+          end
         end
 
         it "returns the result status if http_component is status" do
@@ -387,14 +437,6 @@ describe "Koala::Facebook::GraphAPI in batch mode" do
           end
           result[0].should == 203
         end
-
-        it "returns the result headers as a hash if http_component is headers" do
-          Koala.stub(:make_request).and_return(Koala::Response.new(200, '[{"code":203,"headers":[{"name":"Content-Type","value":"text/javascript; charset=UTF-8"}],"body":"{\"id\":\"1234\"}"}]', {}))
-          result = @api.batch do |batch_api|
-            batch_api.get_object(KoalaTest.user1, {}, :http_component => :headers)
-          end
-          result[0].should == {"Content-Type" => "text/javascript; charset=UTF-8"}
-        end
       end
 
       it "is thread safe" do

data/spec/cases/graph_collection_spec.rb

@@ -74,18 +74,34 @@ describe Koala::Facebook::GraphCollection do
   end
 
   describe "when parsing page paramters" do
-    it "should return the base as the first array entry" do
-      base = "url_path"
-      @collection.parse_page_url("anything.com/#{base}?anything").first.should == base
+    describe "#parse_page_url" do
+      it "should pass the url to the class method" do
+        url = stub("url")
+        Koala::Facebook::GraphCollection.should_receive(:parse_page_url).with(url)
+        @collection.parse_page_url(url)
+      end
+
+      it "should return the result of the class method" do
+        parsed_content = stub("parsed_content")
+        Koala::Facebook::GraphCollection.stub(:parse_page_url).and_return(parsed_content)
+        @collection.parse_page_url(stub("url")).should == parsed_content
+      end
     end
+    
+    describe ".parse_page_url" do    
+      it "should return the base as the first array entry" do
+        base = "url_path"
+        Koala::Facebook::GraphCollection.parse_page_url("anything.com/#{base}?anything").first.should == base
+      end
 
-    it "should return the arguments as a hash as the last array entry" do
-      args_hash = {"one" => "val_one", "two" => "val_two"}
-      @collection.parse_page_url("anything.com/anything?#{args_hash.map {|k,v| "#{k}=#{v}" }.join("&")}").last.should == args_hash
+      it "should return the arguments as a hash as the last array entry" do
+        args_hash = {"one" => "val_one", "two" => "val_two"}
+        Koala::Facebook::GraphCollection.parse_page_url("anything.com/anything?#{args_hash.map {|k,v| "#{k}=#{v}" }.join("&")}").last.should == args_hash
+      end
     end
   end
 
-  describe "#evaluate" do
+  describe ".evaluate" do
     it "returns the original result if it's provided a non-hash result" do
       result = []
       Koala::Facebook::GraphCollection.evaluate(result, @api).should == result