koala 1.3.0rc1 → 1.3.0rc2

data/lib/koala/realtime_updates.rb

@@ -1,36 +1,27 @@
 module Koala
   module Facebook
-    module RealtimeUpdateMethods
-      # note: to subscribe to real-time updates, you must have an application access token
+    class RealtimeUpdates
+      # Manage realtime callbacks for changes to users' information.
+      # See http://developers.facebook.com/docs/reference/api/realtime.
+      #
+      # @note: to subscribe to real-time updates, you must have an application access token
+      #        or provide the app secret when initializing your RealtimeUpdates object.
 
-      def self.included(base)
-        # make the attributes readable
-        base.class_eval do
-          attr_reader :api, :app_id, :app_access_token, :secret
-
-          # parses the challenge params and makes sure the call is legitimate
-          # returns the challenge string to be sent back to facebook if true
-          # returns false otherwise
-          # this is a class method, since you don't need to know anything about the app
-          # saves a potential trip fetching the app access token
-          def self.meet_challenge(params, verify_token = nil, &verification_block)
-            if params["hub.mode"] == "subscribe" &&
-                # you can make sure this is legitimate through two ways
-                # if your store the token across the calls, you can pass in the token value
-                # and we'll make sure it matches
-                (verify_token && params["hub.verify_token"] == verify_token) ||
-                # alternately, if you sent a specially-constructed value (such as a hash of various secret values)
-                # you can pass in a block, which we'll call with the verify_token sent by Facebook
-                # if it's legit, return anything that evaluates to true; otherwise, return nil or false
-                (verification_block && yield(params["hub.verify_token"]))
-              params["hub.challenge"]
-            else
-              false
-            end
-          end
-        end
-      end
+      # The application API interface used to communicate with Facebook. 
+      # @return [Koala::Facebook::API] 
+      attr_reader :api
+      attr_reader :app_id, :app_access_token, :secret
 
+      # Create a new RealtimeUpdates instance.  
+      # If you don't have your app's access token, provide the app's secret and 
+      # Koala will make a request to Facebook for the appropriate token.
+      # 
+      # @param options initialization options.
+      # @option options :app_id the application's ID.
+      # @option options :app_access_token an application access token, if known.
+      # @option options :secret the application's secret.  
+      #
+      # @raise ArgumentError if the application ID and one of the app access token or the secret are not provided.
       def initialize(options = {})
         @app_id = options[:app_id]
         @app_access_token = options[:app_access_token]
@@ -45,45 +36,92 @@ module Koala
           @app_access_token = oauth.get_app_access_token
         end
 
-        @graph_api = API.new(@app_access_token)
+        @api = API.new(@app_access_token)
       end
 
-      # subscribes for realtime updates
-      # your callback_url must be set up to handle the verification request or the subscription will not be set up
-      # http://developers.facebook.com/docs/api/realtime
-      def subscribe(object, fields, callback_url, verify_token)
+      # Subscribe to realtime updates for certain fields on a given object (user, page, etc.).  
+      # See {http://developers.facebook.com/docs/reference/api/realtime the realtime updates documentation}
+      # for more information on what objects and fields you can register for.
+      #
+      # @note Your callback_url must be set up to handle the verification request or the subscription will not be set up.
+      #
+      # @param object a Facebook ID (name or number)
+      # @param fields the fields you want your app to be updated about
+      # @param callback_url the URL Facebook should ping when an update is available
+      # @param verify_token a token included in the verification request, allowing you to ensure the call is genuine 
+      #                     (see the docs for more information)
+      # @param options (see Koala::HTTPService.make_request)
+      #
+      # @return true if successful, false (or an APIError) otherwise.
+      def subscribe(object, fields, callback_url, verify_token, options = {})
         args = {
           :object => object,
           :fields => fields,
           :callback_url => callback_url,
-          :verify_token => verify_token
-        }
+        }.merge(verify_token ? {:verify_token => verify_token} : {})
         # a subscription is a success if Facebook returns a 200 (after hitting your server for verification)
-        @graph_api.graph_call(subscription_path, args, 'post', :http_component => :status) == 200
+        @api.graph_call(subscription_path, args, 'post', options.merge(:http_component => :status)) == 200
       end
 
-      # removes subscription for object
-      # if object is nil, it will remove all subscriptions
-      def unsubscribe(object = nil)
-        args = {}
-        args[:object] = object if object
-        @graph_api.graph_call(subscription_path, args, 'delete', :http_component => :status) == 200
+      # Unsubscribe from updates for a particular object or from updates. 
+      #
+      # @param object the object whose subscriptions to delete. 
+      #               If no object is provided, all subscriptions will be removed.
+      # @param options (see Koala::HTTPService.make_request)
+      #
+      # @return true if the unsubscription is successful, false (or an APIError) otherwise.
+      def unsubscribe(object = nil, options = {})
+        @api.graph_call(subscription_path, object ? {:object => object} : {}, "delete", options.merge(:http_component => :status)) == 200
       end
 
-      def list_subscriptions
-        @graph_api.graph_call(subscription_path)
+      # List all active subscriptions for this application.
+      # 
+      # @param options (see Koala::HTTPService.make_request) 
+      #
+      # @return [Array] a list of active subscriptions
+      def list_subscriptions(options = {})
+        @api.graph_call(subscription_path, {}, "get", options)
       end
 
-      def graph_api
-        Koala::Utils.deprecate("the TestUsers.graph_api accessor is deprecated and will be removed in a future version; please use .api instead.")
-        @api
+      # As a security measure (to prevent DDoS attacks), Facebook sends a verification request to your server
+      # after you request a subscription.
+      # This method parses the challenge params and makes sure the call is legitimate.
+      #
+      # @param params the request parameters sent by Facebook.  (You can pass in a Rails params hash.)
+      # @param verify_token the verify token sent in the {#subscribe subscription request}, if you provided one
+      # 
+      # @yield verify_token if you need to compute the verification token
+      #                     (for instance, if your callback URL includes a record ID, which you look up
+      #                     and use to calculate a hash), you can pass meet_challenge a block, which 
+      #                     will receive the verify_token received back from Facebook.
+      # 
+      # @return the challenge string to be sent back to Facebook, or false if the request is invalid.
+      def self.meet_challenge(params, verify_token = nil, &verification_block)
+        if params["hub.mode"] == "subscribe" &&
+            # you can make sure this is legitimate through two ways
+            # if your store the token across the calls, you can pass in the token value
+            # and we'll make sure it matches
+            (verify_token && params["hub.verify_token"] == verify_token) ||
+            # alternately, if you sent a specially-constructed value (such as a hash of various secret values)
+            # you can pass in a block, which we'll call with the verify_token sent by Facebook
+            # if it's legit, return anything that evaluates to true; otherwise, return nil or false
+            (verification_block && yield(params["hub.verify_token"]))
+          params["hub.challenge"]
+        else
+          false
+        end
       end
-
-      protected
-
+      
+      # The Facebook subscription management URL for your application.
       def subscription_path
         @subscription_path ||= "#{@app_id}/subscriptions"
       end
+      
+      # @private
+      def graph_api
+        Koala::Utils.deprecate("the TestUsers.graph_api accessor is deprecated and will be removed in a future version; please use .api instead.")
+        @api
+      end
     end
   end
 end

data/lib/koala/test_users.rb

@@ -1,16 +1,34 @@
 require 'koala'
-
 module Koala
   module Facebook
-    module TestUserMethods
-
-      def self.included(base)
-        base.class_eval do
-          # make the Graph API accessible in case someone wants to make other calls to interact with their users
-          attr_reader :api, :app_id, :app_access_token, :secret
-        end
-      end
-
+    
+    # Create and manage test users for your application.  
+    # A test user is a user account associated with an app created for the purpose 
+    # of testing the functionality of that app. 
+    # You can use test users for manual or automated testing -- 
+    # Koala's live test suite uses test users to verify the library works with Facebook.
+    #
+    # @note the test user API is fairly slow compared to other interfaces
+    #       (which makes sense -- it's creating whole new user accounts!).
+    #
+    # See http://developers.facebook.com/docs/test_users/.
+    class TestUsers
+
+      # The application API interface used to communicate with Facebook. 
+      # @return [Koala::Facebook::API] 
+      attr_reader :api
+      attr_reader :app_id, :app_access_token, :secret
+      
+      # Create a new TestUsers instance.  
+      # If you don't have your app's access token, provide the app's secret and 
+      # Koala will make a request to Facebook for the appropriate token.
+      # 
+      # @param options initialization options.
+      # @option options :app_id the application's ID.
+      # @option options :app_access_token an application access token, if known.
+      # @option options :secret the application's secret.  
+      #
+      # @raise ArgumentError if the application ID and one of the app access token or the secret are not provided.
       def initialize(options = {})
         @app_id = options[:app_id]
         @app_access_token = options[:app_access_token]
@@ -24,35 +42,81 @@ module Koala
           oauth = Koala::Facebook::OAuth.new(@app_id, @secret)
           @app_access_token = oauth.get_app_access_token
         end
+        
         @api = API.new(@app_access_token)
       end
 
+      # Create a new test user.  
+      #
+      # @param installed whether the user has installed your app
+      # @param permissions a comma-separated string or array of permissions the user has granted (if installed)
+      # @param args any additional arguments for the create call (name, etc.)
+      # @param options (see Koala::Facebook::API#api)
+      #
+      # @return a hash of information for the new user (id, access token, login URL, etc.)
       def create(installed, permissions = nil, args = {}, options = {})
         # Creates and returns a test user
         args['installed'] = installed
         args['permissions'] = (permissions.is_a?(Array) ? permissions.join(",") : permissions) if installed
-        @api.graph_call(accounts_path, args, "post", options)
+        @api.graph_call(test_user_accounts_path, args, "post", options)
       end
 
-      def list
-        @api.graph_call(accounts_path)
+      # List all test users for the app.
+      #
+      # @param options (see Koala::Facebook::API#api)
+      #
+      # @return an array of hashes of user information (id, access token, etc.)
+      def list(options = {})
+        @api.graph_call(test_user_accounts_path, {}, "get", options)
       end
 
-      def delete(test_user)
+      # Delete a test user.
+      #
+      # @param test_user the user to delete; can be either a Facebook ID or the hash returned by {#create}
+      # @param options (see Koala::Facebook::API#api)
+      #
+      # @return true if successful, false (or an {Koala::Facebook::APIError APIError}) if not
+      def delete(test_user, options = {})
         test_user = test_user["id"] if test_user.is_a?(Hash)
-        @api.delete_object(test_user)
+        @api.delete_object(test_user, options)
       end
 
-      def delete_all
-        list.each {|u| delete u}
+      # Deletes all test users.
+      # 
+      # @note if you have a lot of test users (> 20), this operation can take a long time.
+      #
+      # @param options (see Koala::Facebook::API#api)
+      # 
+      # @return a list of the test users that have been deleted
+      def delete_all(options = {})
+        list(options).each {|u| delete(u, options)}
       end
 
-      def update(test_user, args = {}, http_options = {})
+      # Updates a test user's attributes.
+      #
+      # @note currently, only name and password can be changed; 
+      #       see {http://developers.facebook.com/docs/test_users/ the Facebook documentation}.
+      #
+      # @param test_user the user to update; can be either a Facebook ID or the hash returned by {#create}
+      # @param args the updates to make
+      # @param options (see Koala::Facebook::API#api)
+      #
+      # @return true if successful, false (or an {Koala::Facebook::APIError APIError}) if not
+      def update(test_user, args = {}, options = {})
         test_user = test_user["id"] if test_user.is_a?(Hash)
-        @api.graph_call(test_user, args, "post", http_options)
+        @api.graph_call(test_user, args, "post", options)
       end
 
-      def befriend(user1_hash, user2_hash)
+      # Make two test users friends.
+      #
+      # @note there's no way to unfriend test users; you can always just create a new one.
+      #
+      # @param user1_hash one of the users to friend; the hash must contain both ID and access token (as returned by {#create})
+      # @param user2_hash the other user to friend
+      # @param options (see Koala::Facebook::API#api)
+      #
+      # @return true if successful, false (or an {Koala::Facebook::APIError APIError}) if not
+      def befriend(user1_hash, user2_hash, options = {})
         user1_id = user1_hash["id"] || user1_hash[:id]
         user2_id = user2_hash["id"] || user2_hash[:id]
         user1_token = user1_hash["access_token"] || user1_hash[:access_token]
@@ -67,35 +131,47 @@ module Koala
         u1_graph_api = API.new(user1_token)
         u2_graph_api = API.new(user2_token)
 
-        u1_graph_api.graph_call("#{user1_id}/friends/#{user2_id}", {}, "post") &&
-          u2_graph_api.graph_call("#{user2_id}/friends/#{user1_id}", {}, "post")
+        u1_graph_api.graph_call("#{user1_id}/friends/#{user2_id}", {}, "post", options) &&
+          u2_graph_api.graph_call("#{user2_id}/friends/#{user1_id}", {}, "post", options)
       end
 
-      def create_network(network_size, installed = true, permissions = '')
-        users = (0...network_size).collect { create(installed, permissions) }
+      # Create a network of test users, all of whom are friends and have the same permissions.
+      #
+      # @note this call slows down dramatically the more users you create 
+      #       (test user calls are slow, and more users => more 1-on-1 connections to be made).
+      #       Use carefully.
+      #
+      # @param network_size how many users to create
+      # @param installed whether the users have installed your app (see {#create})
+      # @param permissions what permissions the users have granted (see {#create})
+      # @param options (see Koala::Facebook::API#api)
+      #
+      # @return the list of users created
+      def create_network(network_size, installed = true, permissions = '', options = {})
+        users = (0...network_size).collect { create(installed, permissions, options) }
         friends = users.clone
         users.each do |user|
           # Remove this user from list of friends
           friends.delete_at(0)
           # befriend all the others
           friends.each do |friend|
-            befriend(user, friend)
+            befriend(user, friend, options)
           end
         end
         return users
       end
-
+      
+      # The Facebook test users management URL for your application.
+      def test_user_accounts_path
+        @test_user_accounts_path ||= "/#{@app_id}/accounts/test-users"
+      end      
+
+      # @private
+      # Legacy accessor for before GraphAPI was unified into API
       def graph_api
         Koala::Utils.deprecate("the TestUsers.graph_api accessor is deprecated and will be removed in a future version; please use .api instead.")
         @api
       end
-
-      protected
-
-      def accounts_path
-        @accounts_path ||= "/#{@app_id}/accounts/test-users"
-      end
-
     end # TestUserMethods
   end # Facebook
 end # Koala

data/lib/koala/utils.rb

@@ -1,7 +1,11 @@
 module Koala
   module Utils
 
+    # @private
     DEPRECATION_PREFIX = "KOALA: Deprecation warning: "
+
+    # Prints a deprecation message.  
+    # Each individual message will only be printed once to avoid spamming.
     def self.deprecate(message)
       @posted_deprecations ||= []
       unless @posted_deprecations.include?(message)

data/lib/koala/version.rb

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

data/spec/cases/api_spec.rb

@@ -11,7 +11,7 @@ describe "Koala::Facebook::API" do
       hash_not_including('access_token' => 1),
       anything,
       anything
-    ).and_return(Koala::Response.new(200, "", ""))
+    ).and_return(Koala::HTTPService::Response.new(200, "", ""))
 
     @service.api('anything')
   end
@@ -25,7 +25,7 @@ describe "Koala::Facebook::API" do
       hash_including('access_token' => token),
       anything,
       anything
-    ).and_return(Koala::Response.new(200, "", ""))
+    ).and_return(Koala::HTTPService::Response.new(200, "", ""))
 
     service.api('anything')
   end
@@ -36,15 +36,22 @@ describe "Koala::Facebook::API" do
     service.access_token.should == token
   end
 
-  it "gets the attribute of a Koala::Response given by the http_component parameter" do
+  it "gets the attribute of a Koala::HTTPService::Response given by the http_component parameter" do
     http_component = :method_name
 
     response = mock('Mock KoalaResponse', :body => '', :status => 200)
-    response.should_receive(http_component).and_return('')
-
+    result = stub("result")
+    response.stub(http_component).and_return(result)
     Koala.stub(:make_request).and_return(response)
 
-    @service.api('anything', {}, 'get', :http_component => http_component)
+    @service.api('anything', {}, 'get', :http_component => http_component).should == result
+  end
+
+  it "returns the entire response if http_component => :response" do
+    http_component = :response
+    response = mock('Mock KoalaResponse', :body => '', :status => 200)
+    Koala.stub(:make_request).and_return(response)    
+    @service.api('anything', {}, 'get', :http_component => http_component).should == response
   end
 
   it "returns the body of the request as JSON if no http_component is given" do
@@ -59,7 +66,7 @@ describe "Koala::Facebook::API" do
 
   it "executes an error checking block if provided" do
     body = '{}'
-    Koala.stub(:make_request).and_return(Koala::Response.new(200, body, {}))
+    Koala.stub(:make_request).and_return(Koala::HTTPService::Response.new(200, body, {}))
 
     yield_test = mock('Yield Tester')
     yield_test.should_receive(:pass)
@@ -71,29 +78,29 @@ describe "Koala::Facebook::API" do
   end
 
   it "raises an API error if the HTTP response code is greater than or equal to 500" do
-    Koala.stub(:make_request).and_return(Koala::Response.new(500, 'response body', {}))
+    Koala.stub(:make_request).and_return(Koala::HTTPService::Response.new(500, 'response body', {}))
 
     lambda { @service.api('anything') }.should raise_exception(Koala::Facebook::APIError)
   end
 
   it "handles rogue true/false as responses" do
-    Koala.should_receive(:make_request).and_return(Koala::Response.new(200, 'true', {}))
+    Koala.should_receive(:make_request).and_return(Koala::HTTPService::Response.new(200, 'true', {}))
     @service.api('anything').should be_true
 
-    Koala.should_receive(:make_request).and_return(Koala::Response.new(200, 'false', {}))
+    Koala.should_receive(:make_request).and_return(Koala::HTTPService::Response.new(200, 'false', {}))
     @service.api('anything').should be_false
   end
 
   describe "with regard to leading slashes" do
     it "adds a leading / to the path if not present" do
       path = "anything"
-      Koala.should_receive(:make_request).with("/#{path}", anything, anything, anything).and_return(Koala::Response.new(200, 'true', {}))
+      Koala.should_receive(:make_request).with("/#{path}", anything, anything, anything).and_return(Koala::HTTPService::Response.new(200, 'true', {}))
       @service.api(path)
     end
 
     it "doesn't change the path if a leading / is present" do
       path = "/anything"
-      Koala.should_receive(:make_request).with(path, anything, anything, anything).and_return(Koala::Response.new(200, 'true', {}))
+      Koala.should_receive(:make_request).with(path, anything, anything, anything).and_return(Koala::HTTPService::Response.new(200, 'true', {}))
       @service.api(path)
     end
   end