koala 0.6.0 → 0.7.0

data/CHANGELOG

@@ -1,3 +1,13 @@
+v0.7.0
+-- Added RealtimeUpdates class, which can be used to manage subscriptions for user updates (see http://developers.facebook.com/docs/api/realtime)
+-- Added picture method to graph API, which fetches an object's picture from the redirect headers.
+-- Added _greatly_ improved testing with result mocking, which is now the default set of tests
+-- Renamed live testing spec to koala_spec_without_mocks.rb
+-- Added Koala::Response class, which encapsulates HTTP results since Facebook sometimes sends data in the status or headers
+-- Much internal refactoring
+-- Updated readme, changelog, etc.
+
+
 v0.6.0
 -- Added support for the old REST API thanks to cbaclig's great work
 -- Updated tests to conform to RSpec standards

data/Manifest

@@ -5,12 +5,23 @@ init.rb
 lib/graph_api.rb
 lib/http_services.rb
 lib/koala.rb
+lib/realtime_updates.rb
 lib/rest_api.rb
 readme.md
 spec/facebook_data.yml
-spec/koala/facebook_no_access_token_tests.rb
-spec/koala/facebook_oauth_tests.rb
-spec/koala/facebook_rest_api_no_access_token_test.rb
-spec/koala/facebook_rest_api_with_access_token_test.rb
-spec/koala/facebook_with_access_token_tests.rb
+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/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

data/Rakefile

@@ -4,7 +4,7 @@ require 'rake'
 require 'echoe'
 
 # gem management
-Echoe.new('koala', '0.6.0') do |p|
+Echoe.new('koala', '0.7.0') do |p|
   p.summary    = "A lightweight, flexible library for Facebook's new Graph API"
   p.description = "Koala is a lightweight, flexible Ruby SDK for Facebook's new Graph API.  It allows read/write access to the Facebook Graph and provides OAuth URLs and cookie validation for Facebook Connect sites; it also supports access-token based interaction with the old REST API.  Koala 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"

data/koala.gemspec

@@ -2,15 +2,15 @@
 
 Gem::Specification.new do |s|
   s.name = %q{koala}
-  s.version = "0.6.0"
+  s.version = "0.7.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-05-17}
+  s.date = %q{2010-05-26}
   s.description = %q{Koala is a lightweight, flexible Ruby SDK for Facebook's new Graph API.  It allows read/write access to the Facebook Graph and provides OAuth URLs and cookie validation for Facebook Connect sites; it also supports access-token based interaction with the old REST API.  Koala 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", "lib/graph_api.rb", "lib/http_services.rb", "lib/koala.rb", "lib/rest_api.rb"]
-  s.files = ["CHANGELOG", "Manifest", "Rakefile", "init.rb", "lib/graph_api.rb", "lib/http_services.rb", "lib/koala.rb", "lib/rest_api.rb", "readme.md", "spec/facebook_data.yml", "spec/koala/facebook_no_access_token_tests.rb", "spec/koala/facebook_oauth_tests.rb", "spec/koala/facebook_rest_api_no_access_token_test.rb", "spec/koala/facebook_rest_api_with_access_token_test.rb", "spec/koala/facebook_with_access_token_tests.rb", "spec/koala_spec.rb", "koala.gemspec"]
+  s.extra_rdoc_files = ["CHANGELOG", "lib/graph_api.rb", "lib/http_services.rb", "lib/koala.rb", "lib/realtime_updates.rb", "lib/rest_api.rb"]
+  s.files = ["CHANGELOG", "Manifest", "Rakefile", "init.rb", "lib/graph_api.rb", "lib/http_services.rb", "lib/koala.rb", "lib/realtime_updates.rb", "lib/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/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", "koala.gemspec"]
   s.homepage = %q{http://github.com/arsduo/koala}
   s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Koala", "--main", "readme.md"]
   s.require_paths = ["lib"]

data/lib/graph_api.rb

@@ -32,19 +32,24 @@ module Koala
             
       def get_object(id, args = {})
         # Fetchs the given object from the graph.
-        api(id, args)
+        graph_call(id, args)
       end
     
       def get_objects(ids, args = {})
         # Fetchs all of the given object from the graph.
         # We return a map from ID to object. If any of the IDs are invalid,
         # we raise an exception.
-        api("", args.merge("ids" => ids.join(",")))
+        graph_call("", args.merge("ids" => ids.join(",")))
       end
     
       def get_connections(id, connection_name, args = {})
         # Fetchs the connections for given object.
-        api("#{id}/#{connection_name}", args)
+        graph_call("#{id}/#{connection_name}", args)
+      end
+    
+      def get_picture(object)
+        result = graph_call("#{object}/picture", {}, "get", :http_component => :headers)
+        result["Location"]
       end
     
       def put_object(parent_object, connection_name, args = {})
@@ -70,7 +75,7 @@ module Koala
         # extended permissions.
 
         raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Write operations require an access token"}) unless @access_token
-        api("#{parent_object}/#{connection_name}", args, "post")
+        graph_call("#{parent_object}/#{connection_name}", args, "post")
       end
     
       def put_wall_post(message, attachment = {}, profile_id = "me")
@@ -103,20 +108,20 @@ module Koala
     
       def delete_object(id)
         # Deletes the object with the given ID from the graph.
-        api(id, {}, "delete")
+        graph_call(id, {}, "delete")
       end
     
       def search(search_terms, args = {})
         # Searches for a given term
-        api("search", args.merge({:q => search_terms}))
+        graph_call("search", args.merge({:q => search_terms}))
       end
     
-      def api(*args)
-        response = super
-        
-        # check for errors
-        if response.is_a?(Hash) && error_details = response["error"]
-          raise APIError.new(error_details)
+      def graph_call(*args)
+        response = api(*args) do |response|
+          # check for Graph API-specific errors
+          if response.is_a?(Hash) && error_details = response["error"]
+            raise APIError.new(error_details)
+          end
         end
       
         response

data/lib/http_services.rb

@@ -1,4 +1,13 @@
 module Koala
+  class Response
+    attr_reader :status, :body, :headers
+    def initialize(status, body, headers)
+      @status = status
+      @body = body
+      @headers = headers
+    end
+  end
+
   module NetHTTPService
     # this service uses Net::HTTP to send requests to the graph
     def self.included(base)
@@ -24,7 +33,7 @@ module Koala
 
           result = http.start { |http|
             response, body = (verb == "post" ? http.post(path, encode_params(args)) : http.get("#{path}?#{encode_params(args)}")) 
-            body
+            Koala::Response.new(response.code.to_i, body, response.to_hash)
           }
         end
 
@@ -52,7 +61,8 @@ module Koala
           # if the verb isn't get or post, send it as a post argument
           args.merge!({:method => verb}) && verb = "post" if verb != "get" && verb != "post"
           server = options[:rest_api] ? Facebook::REST_SERVER : Facebook::GRAPH_SERVER
-          self.send(verb, "https://#{server}/#{path}", :params => args).body
+          response = self.send(verb, "https://#{server}/#{path}", :params => args)
+          Koala::Response.new(response.code, response.body, response.headers_hash)
         end
       end # class_eval
     end

data/lib/koala.rb

@@ -14,6 +14,8 @@ require 'graph_api'
 # add REST API methods
 require 'rest_api'
 
+require 'realtime_updates'
+
 module Koala
     
   module Facebook
@@ -44,19 +46,26 @@ module Koala
         @access_token = access_token
       end
       
-      def api(path, args = {}, verb = "get", options = {})
+      def api(path, args = {}, verb = "get", options = {}, &error_checking_block)
         # Fetches the given path in the Graph API.
-        args["access_token"] = @access_token if @access_token
-        
+        args["access_token"] = @access_token || @app_access_token if @access_token || @app_access_token
         # make the request via the provided service
         result = Koala.make_request(path, args, verb, options)
-      
-        # Facebook sometimes sends results like "true" and "false", which aren't strictly object
-        # and cause JSON.parse to fail
-        # so we account for that
-        response = JSON.parse("[#{result}]")[0]
 
-        response
+        # Parse the body as JSON and check for errors if provided a mechanism to do so 
+        # Note: Facebook sometimes sends results like "true" and "false", which aren't strictly objects
+        # and cause JSON.parse to fail -- so we account for that by wrapping the result in []
+        body = response = JSON.parse("[#{result.body.to_s}]")[0]
+        if error_checking_block
+          yield(body)
+        end
+        
+        # now return the desired information
+        if options[:http_component]
+          result.send(options[:http_component])
+        else
+          body
+        end
       end
     end
     
@@ -73,6 +82,10 @@ module Koala
       include RestAPIMethods
     end
     
+    class RealtimeUpdates < API
+      include RealtimeUpdateMethods
+    end
+    
     class APIError < Exception
       attr_accessor :fb_error_type
       def initialize(details = {})
@@ -83,7 +96,7 @@ module Koala
     
     
     class OAuth
-      attr_accessor :app_id, :app_secret, :oauth_callback_url
+      attr_reader :app_id, :app_secret, :oauth_callback_url
       def initialize(app_id, app_secret, oauth_callback_url = nil)
         @app_id = app_id
         @app_secret = app_secret
@@ -144,6 +157,30 @@ module Koala
         "https://#{GRAPH_SERVER}/oauth/access_token?client_id=#{@app_id}&redirect_uri=#{callback}&client_secret=#{@app_secret}&code=#{code}"
       end
       
+      def get_access_token(code)
+        # convenience method to get a parsed token from Facebook for a given code
+        # should this require an OAuth callback URL?
+        get_token_from_server(:code => code, :redirect_uri => @oauth_callback_url)
+      end
+      
+      def get_app_access_token
+        # convenience method to get a the application's sessionless access token 
+        get_token_from_server({:type => 'client_cred'}, true)
+      end
+      
+      protected
+      
+      def get_token_from_server(args, post = false)
+        # fetch the result from Facebook's servers
+        result = fetch_token_string(args, post)
+        
+        # if we have an error, parse the error JSON and raise an error
+        raise APIError.new((JSON.parse(result)["error"] rescue nil) || {}) if result =~ /error/
+
+        # otherwise, parse the access token
+        parse_access_token(result)       
+      end
+      
       def parse_access_token(response_text)
         components = response_text.split("&").inject({}) do |hash, bit|
           key, value = bit.split("=")
@@ -152,22 +189,11 @@ module Koala
         components 
       end
 
-      def fetch_token_string(code)
+      def fetch_token_string(args, post = false)
         Koala.make_request("oauth/access_token", {
           :client_id => @app_id, 
-          :redirect_uri => @oauth_callback_url, 
-          :client_secret => @app_secret, 
-          :code => code
-        }, "get")
-      end
-      
-      def get_access_token(code)
-        result = fetch_token_string(code)
-        
-        # if we have an error, parse the error JSON and raise an error
-        raise APIError.new((JSON.parse(result)["error"] rescue nil) || {}) if result =~ /error/
-        # otherwise, parse the access token
-        parse_access_token(result)
+          :client_secret => @app_secret
+        }.merge!(args), post ? "post" : "get").body
       end
     end
   end

data/lib/realtime_updates.rb

@@ -0,0 +1,95 @@
+require 'koala'
+
+module Koala
+  module Facebook
+    module RealtimeUpdateMethods
+      # note: to subscribe to real-time updates, you must have an application access token
+      
+      def self.included(base)
+        # make the attributes readable
+        base.class_eval do
+          attr_reader :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
+      
+      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["access_token"]
+        end
+      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)
+        args = {
+          :object => object, 
+          :fields => fields,
+          :callback_url => callback_url,
+          :verify_token => verify_token
+        }
+        # a subscription is a success if Facebook returns a 200 (after hitting your server for verification)
+        api(subscription_path, args, 'post', :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
+        api(subscription_path, args, 'delete', :http_component => :status) == 200
+      end
+  
+      def list_subscriptions
+        api(subscription_path)
+      end
+      
+      def api(*args) # same as GraphAPI
+        response = super(*args) do |response|
+          # check for subscription errors
+          if response.is_a?(Hash) && error_details = response["error"]
+            raise APIError.new(error_details)
+          end
+        end
+      
+        response
+      end    
+      
+      protected
+      
+      def subscription_path
+        @subscription_path ||= "#{@app_id}/subscriptions"
+      end
+    end
+  end
+end

data/lib/rest_api.rb

@@ -4,20 +4,15 @@ module Koala
     
     module RestAPIMethods
       def fql_query(fql)
-        args = {
-          "query" => fql,
-          "format" => "json",
-        }
-
-        api('method/fql.query', args, 'get', :rest_api => true)
+        rest_call('fql.query', 'query' => fql)
       end
       
-      def api(*args)
-        response = super
-        
-        # check for REST API-specific errors
-        if response.is_a?(Hash) && response["error_code"]
-          raise APIError.new("type" => response["error_code"], "message" => response["error_msg"])
+      def rest_call(method, args = {})
+        response = api("method/#{method}", args.merge('format' => 'json'), 'get', :rest_api => true) do |response|
+          # check for REST API-specific errors
+          if response.is_a?(Hash) && response["error_code"]
+            raise APIError.new("type" => response["error_code"], "message" => response["error_msg"])
+          end
         end
         
         response

data/readme.md

@@ -1,53 +1,99 @@
 Koala
 ====
-Koala (<a href="http://github.com/arsduo/koala" target="_blank">http://github.com/arsduo/koala</a>) is a new Facebook Graph library for Ruby.  We wrote Koala with four goals: 
+Koala (<a href="http://github.com/arsduo/koala" target="_blank">http://github.com/arsduo/koala</a>) is a new Facebook library for Ruby, supporting the Graph API, the old REST API, realtime updates, and OAuth validation.  We wrote Koala with four goals: 
 
-* Lightweight: Koala should be as light and simple as Facebook’s own new libraries, providing API accessors and returning simple JSON.  (We clock in, with comments, just over 300 lines of code.)
+* Lightweight: Koala should be as light and simple as Facebook’s own new libraries, providing API accessors and returning simple JSON.  (We clock in, with comments, just over 500 lines of code.)
 * Fast: Koala should, out of the box, be quick. In addition to supporting the vanilla Ruby networking libraries, it natively supports Typhoeus, our preferred gem for making fast HTTP requests. Of course, That brings us to our next topic:
 * Flexible: Koala should be useful to everyone, regardless of their current configuration.  (We have no dependencies beyond the JSON gem.  Koala also has a built-in mechanism for using whichever HTTP library you prefer to make requests against the graph.)
-* Tested: Koala should have complete test coverage, so you can rely on it.  (By the time you read this the final tests are being written.)
-
-Basic usage:
+* Tested: Koala should have complete test coverage, so you can rely on it.  (Our complete test coverage can be run against either mocked responses or the live Facebook servers.)
 
+Graph API
+----
+The Graph API is the simple, slick new interface to Facebook's data.  Using it with Koala is quite straightforward: 
     graph = Koala::Facebook::GraphAPI.new(oauth_access_token)
     profile = graph.get_object("me")
-    friends = graph.get_connections("me", "friends")
+    friends = graph.get_connection("me", "friends")
     graph.put_object("me", "feed", :message => "I am writing on my wall!")
 
-If you're using Koala within a web application with the Facebook
-[JavaScript SDK](http://github.com/facebook/connect-js), you can use the Koala::Facebook::OAuth class 
-to parse the cookies set by the JavaScript SDK for logged in users.
+Check out the wiki for more examples.
 
-FQL and the old-school REST API
+The old-school REST API
 -----
 Where the Graph API and the old REST API overlap, you should choose the Graph API.  Unfortunately, that overlap is far from complete, and there are many important API calls -- including fql.query -- that can't yet be done via the Graph.  
 
-Koala now supports the old-school REST API using OAuth access tokens; to use this, instantiate your class using the GraphAndRestAPI class:
+Koala now supports the old-school REST API using OAuth access tokens; to use this, instantiate your class using the RestAPI class:
 
-	api = Koala::Facebook::GraphAndRestAPI.new(oauth_access_token)
+	@rest = Koala::Facebook::RestAPI.new(oauth_access_token)
+	@rest.fql_query(my_fql_query) # convenience method
+	@rest.rest_call("stream.publish", arguments_hash) # generic version
+	
+We reserve the right to expand the built-in REST API coverage to additional convenience methods in the future, depending on how fast Facebook moves to fill in the gaps.  
 
-The GraphAndRestAPI class provides access to all the Graph API methods, as well as an fql method that you can use to make FQL calls.  (You can pass the :rest\_api => true option to the api method to make REST API calls; check out lib/rest\_api.rb to see how it's done.)  We reserve the right to expand the built-in REST API coverage to additional methods in the future, depending on how fast Facebook moves to fill in the gaps.  
+(If you want the power of both APIs in the palm of your hand, try out the GraphAndRestAPI class.)
 
-Examples and More Details 
+OAuth
 -----
-Complete Koala documentation can now be found <a href="http://wiki.github.com/arsduo/koala/">on the wiki</a>!
+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)
 
-You can easily generate OAuth access tokens and any other data needed to play with the Graph API or OAuth at the Koala-powered <a href="http://oauth.twoalex.com" target="_blank">OAuth Playground</a>.
+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)
 
+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
+	@oauth.url_for_oauth_code
+	# fetch the access token once you have the code
+	@oauth.get_access_token(code)
 
-Testing
+You can also get your application's own access token, which can be used without a user session for subscriptions and certain other requests:
+    @oauth.get_app_access_token
+
+That's it!  It's pretty simple once you get the hang of it.  If you're new to OAuth, though, check out the wiki and the OAuth Playground example site (see below).
+
+
+Real-time Updates
 -----
+The Graph API now allows your application to subscribe to real-time updates for certain objects in the graph.
 
-Unit tests are provided for all of Koala's methods; however, because the OAuth access tokens and cookies expire, you have to provide some of your own data: a valid OAuth access token with publish_stream and read_stream permissions and an OAuth code that can be used to generate an access token.  (The file also provides valid values for other tests, which you're welcome to sub out for data specific to your own application.)
+Currently, Facebook only supports subscribing to users, permissions and errors.  On top of that, there are limitations on what attributes and connections for each of these objects you can subscribe to updates for.  Check the [official Facebook documentation](http://developers.facebook.com/docs/api/realtime) for more details.
 
-Insert the required values into the file test/facebook_data.yml, then run the test as follows:
-    spec koala_tests.rb
-    
+Koala makes it easy to interact with your applications using the RealTimeUpdates class:
+
+    @updates = Koala::Facebook::RealTimeUpdates.new(:app_id => app_id, :secret => secret)
+
+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)
+
+    # Get an array of your current subscriptions (one hash for each object you've subscribed to)
+    @updates.list_subscriptions
 
-Coming Soon
+    # Unsubscribe from updates for an object
+    @updates.unsubscribe("user")
+
+And to top it all off, RealTimeUpdates provides a static method to respond to Facebook servers' verification of your callback URLs:
+
+    # Returns the hub.challenge parameter in params if the verify token in params matches verify_token
+    Koala::Facebook::RealTimeUpdates.meet_challenge(params, your_verify_token)
+
+For more information about meet_challenge and the RealTimeUpdates class, check out the Real-Time Updates page on the wiki.
+
+See examples, ask questions
 -----
-* Support for real-time updates
+Some resources to help you as you play with Koala and the Graph API:
+
+* Complete Koala documentation <a href="http://wiki.github.com/arsduo/koala/">on the wiki</a>
+* 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
+* 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
 
-Known Issues
+Testing
 -----
-1. gem install koala produces "Could not find main page readme.md" message
+
+Unit tests are provided for all of Koala's methods.  By default, these tests run against mock responses and hence are ready out of the box: 
+    spec koala_tests.rb
+
+You can also run live tests against Facebook's servers:
+    spec koala_tests_without_mocks.rb
+
+Important Note: to run the live tests, you have to provide some of your own data: a valid OAuth access token with publish\_stream and read\_stream permissions and an OAuth code that can be used to generate an access token.  You can get these data at the OAuth Playground; if you want to use your own app, remember to swap out the app ID, secret, and other values.  (The file also provides valid values for other tests, which you're welcome to swap out for data specific to your own application.)

data/spec/facebook_data.yml

@@ -5,18 +5,19 @@
  
 # You must supply this value yourself to test the GraphAPI class.
 # Your OAuth token should have publish_stream and read_stream permissions.
-oauth_token: 
+oauth_token: 119908831367602|2.HlL6n4vuEhDKRyF_7dSipg__.3600.1274893200-2905623|NELx9TxQgEa2uL87wfg0arHIBvk.
 
 # for testing the OAuth class    
 # baseline app
 oauth_test_data: 
   # You must supply this value yourself, since they will expire.
-  code: 
+  code:  2.HlL6n4vuEhDKRyF_7dSipg__.3600.1274893200-2905623|HgKssdjuTn4tMSStxS-LsMb_p4M.
     
   # These values will work out of the box
   app_id: 119908831367602
   secret: e45e55a333eec232d4206d2703de1307
   callback_url: http://oauth.twoalex.com/
+  app_access_token: 119908831367602|o3wswWQ88LYjEC9-ukR_gjRIOMw.
   raw_token_string: "access_token=119908831367602|2.6GneoQbnEqtSiPppZzDU4Q__.3600.1273366800-2905623|3OLa3w0x1K4C1S5cOgbs07TytAk.&expires=6621"
   raw_offline_access_token_string: access_token=119908831367602|2.6GneoQbnEqtSiPppZzDU4Q__.3600.1273366800-2905623|3OLa3w0x1K4C1S5cOgbs07TytAk.
   valid_cookies: 
@@ -27,4 +28,12 @@ oauth_test_data:
     fbs_119908831367602: '"access_token=119908831367602|2.xv9mi6QSOpr474s4n2X_pw__.3600.1273287600-2905623|yVt5WH_S6J5p3gFa5_5lBzckhws.&expires=1273287600&secret=V_E79ovQnXqxGctFuC_n5A__&session_key=2.xv9mi6QSOpr474s4n2X_pw__.3600.1273287600-2905623&sig=eeef60838c0c800258d89b7e6ddddddb&uid=2905623"'
   offline_access_cookies: 
     # note: I've revoked the offline access for security reasons, so you can't make calls against this :)
-    fbs_119908831367602: '"access_token=119908831367602|08170230801eb225068e7a70-2905623|Q3LDCYYF8CX9cstxnZLsxiR0nwg.&expires=0&secret=78abaee300b392e275072a9f2727d436&session_key=08170230801eb225068e7a70-2905623&sig=423b8aa4b6fa1f9a571955f8e929d567&uid=2905623"'
+    fbs_119908831367602: '"access_token=119908831367602|08170230801eb225068e7a70-2905623|Q3LDCYYF8CX9cstxnZLsxiR0nwg.&expires=0&secret=78abaee300b392e275072a9f2727d436&session_key=08170230801eb225068e7a70-2905623&sig=423b8aa4b6fa1f9a571955f8e929d567&uid=2905623"'
+    
+subscription_test_data:
+  subscription_path: http://oauth.twoalex.com/subscriptions
+  verify_token: "myverificationtoken|1f54545d5f722733e17faae15377928f"
+  challenge_data: 
+    "hub.challenge": "1290024882"
+    "hub.verify_token": "myverificationtoken|1f54545d5f722733e17faae15377928f"
+    "hub.mode": "subscribe"

data/spec/koala/api_base_tests.rb

@@ -0,0 +1,44 @@
+class ApiBaseTests < Test::Unit::TestCase
+  describe "Koala API base class" do
+    before(:each) do
+      @service = Koala::Facebook::API.new  
+    end
+    
+    it "should not include an access token if none was given" do
+      Koala.should_receive(:make_request).with(
+        anything,
+        hash_not_including('access_token' => 1),
+        anything,
+        anything
+      ).and_return(Koala::Response.new(200, "", ""))
+      
+      @service.api('anything')
+    end
+    
+    it "should include an access token if given" do
+      token = 'adfadf'
+      service = Koala::Facebook::API.new token
+      
+      Koala.should_receive(:make_request).with(
+        anything,
+        hash_including('access_token' => token),
+        anything,
+        anything
+      ).and_return(Koala::Response.new(200, "", ""))
+      
+      service.api('anything')
+    end
+    
+    it "should properly handle the http_component parameter"
+    
+    it "should execute a block to test for errors if passed one"
+    
+    it "should handle rogue true/false as responses" do
+      Koala.should_receive(:make_request).and_return(Koala::Response.new(200, 'true', {}))
+      @service.api('anything').should be_true
+      
+      Koala.should_receive(:make_request).and_return(Koala::Response.new(200, 'false', {}))
+      @service.api('anything').should be_false
+    end
+  end
+end

data/spec/koala/graph_and_rest_api/graph_and_rest_api_no_token_tests.rb

@@ -0,0 +1,10 @@
+class GraphAndRestAPINoTokenTests < Test::Unit::TestCase
+  describe "Koala GraphAndRestAPI without an access token" do
+    before(:each) do
+      @api = Koala::Facebook::GraphAndRestAPI.new
+    end
+    
+    it_should_behave_like "Koala RestAPI without an access token"
+    it_should_behave_like "Koala GraphAPI without an access token"
+  end
+end