koala 1.2.1 → 1.3.0

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

@@ -2,15 +2,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 +43,94 @@ 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 in batches of 50.
+      # 
+      # @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 = {})
+        # ideally we'd save a call by checking next_page_params, but at the time of writing
+        # Facebook isn't consistently returning full pages after the first one
+        previous_list = nil
+        while (test_user_list = list(options)).length > 0
+          # avoid infinite loops if Facebook returns buggy users you can't delete
+          # see http://developers.facebook.com/bugs/223629371047398
+          break if test_user_list == previous_list
+
+          test_user_list.each_slice(50) do |users| 
+            self.api.batch(options) {|batch_api| users.each {|u| batch_api.delete_object(u["id"]) }}
+          end
+          
+          previous_list = test_user_list
+        end
       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 +145,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,10 +1,17 @@
 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)
-      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.0"
 end

data/lib/koala.rb

@@ -1,121 +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
-      def initialize(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
@@ -128,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/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
 -----