koala 1.2.1 → 1.3.0rc2

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,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.0rc2"
 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
 -----

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

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