koala 0.9.0 → 0.10.0

data/CHANGELOG

@@ -1,3 +1,13 @@
+v0.10.0
+-- Added test user module
+-- Fixed bug when raising APIError after Facebook fails to exchange session keys
+-- Made access_token accessible via the readonly access_token property on all our API classes
+
+v0.9.1
+-- Tests are now compatible with Ruby 1.9.2
+-- Added JSON to runtime dependencies
+-- Removed examples directory (referenced from github instead)
+
 v0.9.0
 -- Added parse_signed_request to handle Facebook's new authentication scheme
   -- note: creates dependency on OpenSSL (OpenSSL::HMAC) for decryption

data/Manifest

@@ -2,20 +2,6 @@ CHANGELOG
 LICENSE
 Manifest
 Rakefile
-examples/oauth_playground/Capfile
-examples/oauth_playground/LICENSE
-examples/oauth_playground/Rakefile
-examples/oauth_playground/config.ru
-examples/oauth_playground/config/deploy.rb
-examples/oauth_playground/config/facebook.yml
-examples/oauth_playground/lib/load_facebook.rb
-examples/oauth_playground/lib/oauth_playground.rb
-examples/oauth_playground/readme.md
-examples/oauth_playground/spec/oauth_playground_spec.rb
-examples/oauth_playground/spec/spec_helper.rb
-examples/oauth_playground/tmp/restart.txt
-examples/oauth_playground/views/index.erb
-examples/oauth_playground/views/layout.erb
 init.rb
 koala.gemspec
 lib/koala.rb
@@ -23,6 +9,7 @@ lib/koala/graph_api.rb
 lib/koala/http_services.rb
 lib/koala/realtime_updates.rb
 lib/koala/rest_api.rb
+lib/koala/test_users.rb
 readme.md
 spec/facebook_data.yml
 spec/koala/api_base_tests.rb
@@ -37,6 +24,7 @@ spec/koala/oauth/oauth_tests.rb
 spec/koala/realtime_updates/realtime_updates_tests.rb
 spec/koala/rest_api/rest_api_no_access_token_tests.rb
 spec/koala/rest_api/rest_api_with_access_token_tests.rb
+spec/koala/test_users/test_users_tests.rb
 spec/koala_spec.rb
 spec/koala_spec_helper.rb
 spec/koala_spec_without_mocks.rb

data/Rakefile

@@ -4,13 +4,14 @@ require 'rake'
 require 'echoe'
 
 # gem management
-Echoe.new('koala', '0.9.0') do |p|
+Echoe.new('koala', '0.10.0') do |p|
   p.summary    = "A lightweight, flexible library for Facebook with support for the Graph API, the old REST API, realtime updates, and OAuth validation."
   p.description = "Koala is a lightweight, flexible Ruby SDK for Facebook.  It allows read/write access to the social graph via the Graph API and the older REST API, as well as support for realtime updates and OAuth and Facebook Connect authentication.  Koala is fully tested and supports Net::HTTP and Typhoeus connections out of the box and can accept custom modules for other services."
   p.url            = "http://github.com/arsduo/koala"
   p.author         = ["Alex Koppel", "Chris Baclig", "Rafi Jacoby", "Context Optional"]
   p.email          = "alex@alexkoppel.com"
   p.ignore_pattern = ["tmp/*", "script/*", "pkg/*"]
+  p.runtime_dependencies = ["json >=1.0"]
   p.development_dependencies = []
   p.retain_gemspec = true
 end

data/koala.gemspec

@@ -2,15 +2,15 @@
 
 Gem::Specification.new do |s|
   s.name = %q{koala}
-  s.version = "0.9.0"
+  s.version = "0.10.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["Alex Koppel, Chris Baclig, Rafi Jacoby, Context Optional"]
-  s.date = %q{2010-09-30}
+  s.date = %q{2010-12-15}
   s.description = %q{Koala is a lightweight, flexible Ruby SDK for Facebook.  It allows read/write access to the social graph via the Graph API and the older REST API, as well as support for realtime updates and OAuth and Facebook Connect authentication.  Koala is fully tested and supports Net::HTTP and Typhoeus connections out of the box and can accept custom modules for other services.}
   s.email = %q{alex@alexkoppel.com}
-  s.extra_rdoc_files = ["CHANGELOG", "LICENSE", "lib/koala.rb", "lib/koala/graph_api.rb", "lib/koala/http_services.rb", "lib/koala/realtime_updates.rb", "lib/koala/rest_api.rb"]
-  s.files = ["CHANGELOG", "LICENSE", "Manifest", "Rakefile", "examples/oauth_playground/Capfile", "examples/oauth_playground/LICENSE", "examples/oauth_playground/Rakefile", "examples/oauth_playground/config.ru", "examples/oauth_playground/config/deploy.rb", "examples/oauth_playground/config/facebook.yml", "examples/oauth_playground/lib/load_facebook.rb", "examples/oauth_playground/lib/oauth_playground.rb", "examples/oauth_playground/readme.md", "examples/oauth_playground/spec/oauth_playground_spec.rb", "examples/oauth_playground/spec/spec_helper.rb", "examples/oauth_playground/tmp/restart.txt", "examples/oauth_playground/views/index.erb", "examples/oauth_playground/views/layout.erb", "init.rb", "koala.gemspec", "lib/koala.rb", "lib/koala/graph_api.rb", "lib/koala/http_services.rb", "lib/koala/realtime_updates.rb", "lib/koala/rest_api.rb", "readme.md", "spec/facebook_data.yml", "spec/koala/api_base_tests.rb", "spec/koala/graph_and_rest_api/graph_and_rest_api_no_token_tests.rb", "spec/koala/graph_and_rest_api/graph_and_rest_api_with_token_tests.rb", "spec/koala/graph_api/graph_api_no_access_token_tests.rb", "spec/koala/graph_api/graph_api_with_access_token_tests.rb", "spec/koala/graph_api/graph_collection_tests.rb", "spec/koala/live_testing_data_helper.rb", "spec/koala/net_http_service_tests.rb", "spec/koala/oauth/oauth_tests.rb", "spec/koala/realtime_updates/realtime_updates_tests.rb", "spec/koala/rest_api/rest_api_no_access_token_tests.rb", "spec/koala/rest_api/rest_api_with_access_token_tests.rb", "spec/koala_spec.rb", "spec/koala_spec_helper.rb", "spec/koala_spec_without_mocks.rb", "spec/mock_facebook_responses.yml", "spec/mock_http_service.rb"]
+  s.extra_rdoc_files = ["CHANGELOG", "LICENSE", "lib/koala.rb", "lib/koala/graph_api.rb", "lib/koala/http_services.rb", "lib/koala/realtime_updates.rb", "lib/koala/rest_api.rb", "lib/koala/test_users.rb"]
+  s.files = ["CHANGELOG", "LICENSE", "Manifest", "Rakefile", "init.rb", "koala.gemspec", "lib/koala.rb", "lib/koala/graph_api.rb", "lib/koala/http_services.rb", "lib/koala/realtime_updates.rb", "lib/koala/rest_api.rb", "lib/koala/test_users.rb", "readme.md", "spec/facebook_data.yml", "spec/koala/api_base_tests.rb", "spec/koala/graph_and_rest_api/graph_and_rest_api_no_token_tests.rb", "spec/koala/graph_and_rest_api/graph_and_rest_api_with_token_tests.rb", "spec/koala/graph_api/graph_api_no_access_token_tests.rb", "spec/koala/graph_api/graph_api_with_access_token_tests.rb", "spec/koala/graph_api/graph_collection_tests.rb", "spec/koala/live_testing_data_helper.rb", "spec/koala/net_http_service_tests.rb", "spec/koala/oauth/oauth_tests.rb", "spec/koala/realtime_updates/realtime_updates_tests.rb", "spec/koala/rest_api/rest_api_no_access_token_tests.rb", "spec/koala/rest_api/rest_api_with_access_token_tests.rb", "spec/koala/test_users/test_users_tests.rb", "spec/koala_spec.rb", "spec/koala_spec_helper.rb", "spec/koala_spec_without_mocks.rb", "spec/mock_facebook_responses.yml", "spec/mock_http_service.rb"]
   s.homepage = %q{http://github.com/arsduo/koala}
   s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Koala", "--main", "readme.md"]
   s.require_paths = ["lib"]
@@ -23,8 +23,11 @@ Gem::Specification.new do |s|
     s.specification_version = 3
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+      s.add_runtime_dependency(%q<json>, [">= 1.0"])
     else
+      s.add_dependency(%q<json>, [">= 1.0"])
     end
   else
+    s.add_dependency(%q<json>, [">= 1.0"])
   end
 end

data/lib/koala/test_users.rb

@@ -0,0 +1,72 @@
+require 'koala'
+
+module Koala
+  module Facebook
+    module TestUserMethods
+      
+      def initialize(options = {})
+        @app_id = options[:app_id]
+        @app_access_token = options[:app_access_token]
+        @secret = options[:secret]
+        unless @app_id && (@app_access_token || @secret) # make sure we have what we need
+          raise ArgumentError, "Initialize must receive a hash with :app_id and either :app_access_token or :secret! (received #{options.inspect})"
+        end
+
+        # fetch the access token if we're provided a secret
+        if @secret && !@app_access_token
+          oauth = Koala::Facebook::OAuth.new(@app_id, @secret)
+          @app_access_token = oauth.get_app_access_token
+        end
+        @graph_api = GraphAPI.new(@app_access_token)
+      end
+
+      def create(installed, permissions = nil)
+        # Creates and returns a test user
+        args = {'installed' => installed}
+        args['permissions'] = (permissions.is_a?(Array) ? permissions.join(",") : permissions) if installed
+        result = @graph_api.graph_call(accounts_path, args, "post")
+      end
+      
+      def list
+        @graph_api.graph_call(accounts_path)["data"]
+      end
+      
+      def delete(test_user)
+        test_user = test_user["id"] if test_user.is_a?(Hash)
+        @graph_api.delete_object(test_user)
+      end
+      
+      def delete_all
+        list.each {|u| delete u }
+      end
+      
+      def befriend(user1, user2)
+        user1 = user1["id"] if user1.is_a?(Hash)
+        user2 = user2["id"] if user2.is_a?(Hash)
+        @graph_api.graph_call("/#{user1}/friends/#{user2}") && @graph_api.graph_call("/#{user2}/friends/#{user1}")
+      end
+      
+      def create_network(network_size, installed = true, permissions = '')
+        network_size = 50 if network_size > 50 # FB's max is 50
+        users = (0...network_size).collect { create(installed, permissions) }
+        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)
+          end
+        end
+        return users
+      end
+      
+      protected
+      
+      def accounts_path
+        @accounts_path ||= "/#{@app_id}/accounts/test-users"
+      end
+
+    end # TestUserMethods
+  end # Facebook
+end # Koala

data/lib/koala.rb

@@ -17,8 +17,12 @@ require 'koala/graph_api'
 # add REST API methods
 require 'koala/rest_api'
 
+# add realtime update methods
 require 'koala/realtime_updates'
 
+# add test user methods
+require 'koala/test_users'
+
 module Koala
     
   module Facebook
@@ -48,6 +52,7 @@ module Koala
       def initialize(access_token = nil)
         @access_token = access_token
       end
+      attr_reader :access_token
       
       def api(path, args = {}, verb = "get", options = {}, &error_checking_block)
         # Fetches the given path in the Graph API.
@@ -98,6 +103,12 @@ module Koala
       include RealtimeUpdateMethods
     end
     
+    class TestUsers < API
+      include TestUserMethods
+      # make the Graph API accessible in case someone wants to make other calls to interact with their users
+      attr_reader :graph_api
+    end
+    
     class APIError < Exception
       attr_accessor :fb_error_type
       def initialize(details = {})
@@ -223,7 +234,10 @@ module Koala
         
         # Facebook returns an empty body in certain error conditions
         if response == "" 
-          raise APIError.new("ArgumentError", "get_token_from_session_key received an error (empty response body) for sessions #{sessions.inspect}!")
+          raise APIError.new({
+            "type" => "ArgumentError", 
+            "message" => "get_token_from_session_key received an error (empty response body) for sessions #{sessions.inspect}!"
+          })
         end
         
         JSON.parse(response)

data/readme.md

@@ -56,10 +56,11 @@ We reserve the right to expand the built-in REST API coverage to additional conv
 OAuth
 -----
 You can use the Graph and REST APIs without an OAuth access token, but the real magic happens when you provide Facebook an OAuth token to prove you're authenticated.  Koala provides an OAuth class to make that process easy:
-    @oauth = Koala::Facebook::OAuth.new(app_id, code, callback_url)
+    @oauth = Koala::Facebook::OAuth.new(app_id, app_secret, callback_url)
 
 If your application uses Koala and the Facebook [JavaScript SDK](http://github.com/facebook/connect-js) (formerly Facebook Connect), you can use the OAuth class to parse the cookies:
-    @oauth.get_user_from_cookie(cookies)
+    @oauth.get_user_from_cookies(cookies) # gets the user's ID
+	@oauth.get_user_info_from_cookies(cookies) # parses and returns the entire hash
 
 And if you have to use the more complicated [redirect-based OAuth process](http://developers.facebook.com/docs/authentication/), Koala helps out there, too:
 	  # generate authenticating URL

data/spec/facebook_data.yml

@@ -5,18 +5,18 @@
  
 # You must supply this value yourself to test the GraphAPI class.
 # Your OAuth token should have publish_stream and read_stream permissions.
-oauth_token: 119908831367602|2.K0IVdhrRngS7VQM4Z_s6_g__.3600.1285844400-2905623|Q3VNUb9haS3s29X4SYPk6VL1f9A 
+oauth_token: 
 
 # for testing the OAuth class    
 # baseline app
 oauth_test_data: 
   # You must supply this value yourself, since they will expire.
-  code: 2.K0IVdhrRngS7VQM4Z_s6_g__.3600.1285844400-2905623|b5PCXOhEMe2FJXPHAg_mY3Psl6M
+  code: 
   # easiest way to get session keys: use multiple test accounts with the Javascript login at http://oauth.twoalex.com
-  session_key: 2.K0IVdhrRngS7VQM4Z_s6_g__.3600.1285844400-2905623
+  session_key: 
   multiple_session_keys:
-    - 2.K0IVdhrRngS7VQM4Z_s6_g__.3600.1285844400-2905623
-    - 2.K0IVdhrRngS7VQM4Z_s6_g__.3600.1285844400-2905623
+    - 
+    - 
   
   # These values will work out of the box
   app_id: 119908831367602

data/spec/koala/api_base_tests.rb

@@ -1,4 +1,5 @@
 class ApiBaseTests < Test::Unit::TestCase
+
   describe "Koala API base class" do
     before(:each) do
       @service = Koala::Facebook::API.new  
@@ -29,6 +30,12 @@ class ApiBaseTests < Test::Unit::TestCase
       service.api('anything')
     end
     
+    it "should have an attr_reader for access token" do
+      token = 'adfadf'
+      service = Koala::Facebook::API.new token
+      service.access_token.should == token
+    end
+    
     it "should get the attribute of a Koala::Response given by the http_component parameter" do
       http_component = :method_name
       

data/spec/koala/graph_and_rest_api/graph_and_rest_api_with_token_tests.rb

@@ -1,6 +1,6 @@
 class GraphAndRestAPIWithTokenTests < Test::Unit::TestCase
   describe "Koala GraphAndRestAPI without an access token" do
-    it_should_behave_like "live testing examples"
+    include LiveTestingDataHelper
     it_should_behave_like "Koala RestAPI with an access token"
     it_should_behave_like "Koala GraphAPI with an access token"
     

data/spec/koala/graph_api/graph_api_with_access_token_tests.rb

@@ -140,7 +140,7 @@ end
 
 class FacebookWithAccessTokenTests < Test::Unit::TestCase
   describe "Koala GraphAPI with an access token" do
-    it_should_behave_like "live testing examples"
+    include LiveTestingDataHelper
     it_should_behave_like "Koala GraphAPI with an access token"
     
     before :each do

data/spec/koala/graph_api/graph_collection_tests.rb

@@ -65,7 +65,7 @@ shared_examples_for "Koala GraphAPI with GraphCollection" do
           @api.should_receive(:graph_call).with(@base, @args).and_return(@second_page)
           Koala::Facebook::GraphCollection.should_receive(:new).with(@second_page, @api).and_return(@page_of_results)
       
-          @result.previous_page(@api).should == @page_of_results
+          @result.previous_page.should == @page_of_results
         end
     
         it "should return the next page of results" do
@@ -79,7 +79,7 @@ shared_examples_for "Koala GraphAPI with GraphCollection" do
         it "should return nil it there are no other pages" do
           %w{next previous}.each do |this|
             @result.should_receive("#{this}_page_params".to_sym).and_return(nil)
-            @result.send("#{this}_page", @api).should == nil
+            @result.send("#{this}_page").should == nil
           end
         end
       end

data/spec/koala/live_testing_data_helper.rb

@@ -1,15 +1,43 @@
-shared_examples_for "live testing examples" do
-    before :each do
-      @token = $testing_data["oauth_token"]
-      raise Exception, "Must supply access token to run FacebookWithAccessTokenTests!" unless @token
-    end
-    
-    after :each do 
-      # clean up any temporary objects
-      if @temporary_object_id
-        puts "\nCleaning up temporary object #{@temporary_object_id.to_s}"
-        result = @api.delete_object(@temporary_object_id)
-        raise "Unable to clean up temporary Graph object #{@temporary_object_id}!" unless result
+module LiveTestingDataHelper
+  # in RSpec 2, included example groups no longer share any hooks or state with outside examples 
+  # even if in the same block
+  # so we have to use a module to provide setup and teardown hooks for live testing
+  
+  def self.included(base)
+    base.class_eval do
+      before :each do
+        @token = $testing_data["oauth_token"]
+        raise Exception, "Must supply access token to run FacebookWithAccessTokenTests!" unless @token
+        # track temporary objects created
+        @temporary_object_ids = []
+      end
+  
+      after :each do 
+        # clean up any temporary objects
+        @temporary_object_ids << @temporary_object_id if @temporary_object_id
+        count = @temporary_object_ids.length
+        errors = []
+        
+        if count > 0
+          print "\nCleaning up #{count} temporary #{count > 1 ? "objects" : "object"}..."
+          @temporary_object_ids.each do |id|
+            # get our API
+            api = @api || (@test_users ? @test_users.graph_api : nil)
+            raise "Unable to locate API when passed temporary object to delete!" unless api
+          
+            # delete the object
+            result = (api.delete_object(id) rescue false)
+            # if we errored out or Facebook returned false, track that
+            errors << id unless result
+          end
+          
+          if errors.length == 0
+            puts "done."
+          else 
+            puts "cleaned up #{count - errors.length} objects, but errored out on the following:\n #{errors.join(", ")}"
+          end
+        end
       end
     end
+  end
 end