koala 0.8.0 → 0.9.0

data/readme.md

@@ -10,16 +10,38 @@ Koala (<a href="http://github.com/arsduo/koala" target="_blank">http://github.co
 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_connection("me", "friends")
+    friends = graph.get_connections("me", "friends")
     graph.put_object("me", "feed", :message => "I am writing on my wall!")
 
+The response of most requests is the JSON data returned from the Facebook servers as a Hash.  
+
+When retrieving data that returns an array of results (for example, when calling GraphAPI#get_connections or GraphAPI#search) a GraphCollection object (a sub-class of Array) will be returned, which contains added methods for getting the next and previous page of results:
+    
+    # Returns the feed items for the currently logged-in user as a GraphCollection
+    feed = graph.get_connections("me", "feed")
+    
+    # GraphCollection is a sub-class of Array, so you can use it as a usual Array
+    first_entry = feed[0]
+    last_entry = feed.last
+
+    # Returns the next page of results (also as a GraphCollection)
+    next_feed = feed.next_page
+
+    # Returns an array describing the URL for the next page: [path, arguments]
+    # This is useful for paging across multiple requests
+    next_path, next_args = feed.next_page_params
+    
+    # You can use those params to easily get the next (or prevous) page
+    page = graph.get_page(feed.next_page_params)
+
 Check out the wiki for more examples.
 
 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.  
+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 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 RestAPI class:
 
@@ -40,16 +62,19 @@ If your application uses Koala and the Facebook [JavaScript SDK](http://github.c
     @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)
+	  # generate authenticating URL
+	  @oauth.url_for_oauth_code
+	  # fetch the access token once you have the code
+	  @oauth.get_access_token(code)
 
 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).
 
+*Signed Requests:* Excited to try out the new signed request authentication scheme?  Good news!  Koala now supports parsing those parameters:
+    @oauth.parse_signed_request(request)
+
 *Exchanging session keys:* Stuck building tab applications on Facebook?  Wishing you had an OAuth token so you could use the Graph API?  You're in luck! Koala now allows you to exchange session keys for OAuth access tokens:
     @oauth.get_token_from_session_key(session_key)
     @oauth.get_tokens_from_session_keys(array_of_session_keys)
@@ -60,11 +85,11 @@ The Graph API now allows your application to subscribe to real-time updates for
 
 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.
 
-Koala makes it easy to interact with your applications using the RealTimeUpdates class:
+Koala makes it easy to interact with your applications using the RealtimeUpdates class:
 
-    @updates = Koala::Facebook::RealTimeUpdates.new(:app_id => app_id, :secret => secret)
+    @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:
+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)
@@ -75,12 +100,12 @@ You can do just about anything with your real-time update subscriptions using th
     # 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:
+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)
+    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.
+For more information about meet_challenge and the RealtimeUpdates class, check out the Real-Time Updates page on the wiki.
 
 See examples, ask questions
 -----

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: 
+oauth_token: 119908831367602|2.K0IVdhrRngS7VQM4Z_s6_g__.3600.1285844400-2905623|Q3VNUb9haS3s29X4SYPk6VL1f9A 
 
 # for testing the OAuth class    
 # baseline app
 oauth_test_data: 
   # You must supply this value yourself, since they will expire.
-  code: 
+  code: 2.K0IVdhrRngS7VQM4Z_s6_g__.3600.1285844400-2905623|b5PCXOhEMe2FJXPHAg_mY3Psl6M
   # easiest way to get session keys: use multiple test accounts with the Javascript login at http://oauth.twoalex.com
-  session_key: 
+  session_key: 2.K0IVdhrRngS7VQM4Z_s6_g__.3600.1285844400-2905623
   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
@@ -34,7 +34,19 @@ oauth_test_data:
   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"'
+
+  # These values will work out of the box
+  # They're from Facebook's example at http://developers.facebook.com/docs/authentication/canvas
+  # You can update this to live data if desired
+  # request_secret is optional and will fall back to the secret above if absent
+  request_secret: "secret"
+  signed_request: "vlXgu64BQGFSQrY0ZcJBZASMvYvTHu9GQ0YM9rjPSso.eyJhbGdvcml0aG0iOiJITUFDLVNIQTI1NiIsIjAiOiJwYXlsb2FkIn0"
+  signed_request_result:
+      "0": payload
+      algorithm: HMAC-SHA256
     
+  
+
 subscription_test_data:
   subscription_path: http://oauth.twoalex.com/subscriptions
   verify_token: "myverificationtoken|1f54545d5f722733e17faae15377928f"

data/spec/koala/api_base_tests.rb

@@ -76,5 +76,20 @@ class ApiBaseTests < Test::Unit::TestCase
       Koala.should_receive(:make_request).and_return(Koala::Response.new(200, 'false', {}))
       @service.api('anything').should be_false
     end
+    
+    describe "with regard to leading slashes" do 
+      it "should add 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', {}))
+        @service.api(path)      
+      end
+    
+      it "shouldn'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', {}))
+        @service.api(path)              
+      end
+    end
+    
   end
 end

data/spec/koala/graph_api/graph_api_no_access_token_tests.rb

@@ -39,9 +39,17 @@ shared_examples_for "Koala GraphAPI without an access token" do
   end
 
   it "should be able to access connections from public Pages" do
-    result = @api.get_connections("contextoptional", "likes")
+    result = @api.get_connections("contextoptional", "photos")
     result.should be_a(Array)
   end
+  
+  # paging
+  # see also graph_collection_tests
+  it "should make a request for a page when provided a specific set of page params" do
+    query = [1, 2]
+    @api.should_receive(:graph_call).with(*query)
+    @api.get_page(query)
+  end
 
   it "should not be able to put an object" do
     lambda { @result = @api.put_object("lukeshepard", "feed", :message => "Hello, world") }.should raise_error(Koala::Facebook::APIError)
@@ -66,8 +74,7 @@ shared_examples_for "Koala GraphAPI without an access token" do
   it "should not be able to like an object" do
     lambda { @api.put_like("7204941866_119776748033392") }.should raise_error(Koala::Facebook::APIError)
   end
-
-
+  
   # DELETE
   it "should not be able to delete posts" do 
     # test post on the Ruby SDK Test application
@@ -77,9 +84,11 @@ shared_examples_for "Koala GraphAPI without an access token" do
   # SEARCH
   it "should be able to search" do
     result = @api.search("facebook")
-    result["data"].should be_an(Array)
+    result.length.should be_an(Integer)
   end
 
+  it_should_behave_like "Koala GraphAPI with GraphCollection"
+  
   # API
   it "should never use the rest api server" do
     Koala.should_receive(:make_request).with(

data/spec/koala/graph_api/graph_api_with_access_token_tests.rb

@@ -1,5 +1,5 @@
 shared_examples_for "Koala GraphAPI with an access token" do
-it "should get public data about a user" do
+  it "should get public data about a user" do
       result = @api.get_object("koppel")
       # the results should have an ID and a name, among other things
       (result["id"] && result["name"]).should_not be_nil
@@ -41,10 +41,19 @@ it "should get public data about a user" do
     end
 
     it "should be able to access connections from public Pages" do
-      result = @api.get_connections("contextoptional", "likes")
+      result = @api.get_connections("contextoptional", "photos")
       result.should be_a(Array)
     end
     
+    # paging
+    # see also graph_collection_tests
+    it "should make a request for a page when provided a specific set of page params" do
+      query = [1, 2]
+      @api.should_receive(:graph_call).with(*query)
+      @api.get_page(query)
+    end
+    
+    
     # PUT
     it "should be able to write an object to the graph" do
       result = @api.put_wall_post("Hello, world, from the test suite!")
@@ -120,11 +129,13 @@ it "should get public data about a user" do
     # SEARCH
     it "should be able to search" do
       result = @api.search("facebook")
-      result["data"].should be_an(Array)
+      result.length.should be_an(Integer)
     end
 
     # API
     # the above tests test this already, but we should consider additional api tests
+
+    it_should_behave_like "Koala GraphAPI with GraphCollection"
 end
 
 class FacebookWithAccessTokenTests < Test::Unit::TestCase

data/spec/koala/graph_api/graph_collection_tests.rb

@@ -0,0 +1,104 @@
+# GraphCollection
+shared_examples_for "Koala GraphAPI with GraphCollection" do
+  
+  it "should create an array-like object" do
+    call = @api.graph_call("contextoptional/photos")
+    Koala::Facebook::GraphCollection.new(call, @api).should be_an(Array)
+  end
+  
+  describe "when getting a collection" do
+    # GraphCollection methods    
+    it "should get a GraphCollection when getting connections" do
+      @result = @api.get_connections("contextoptional", "photos")
+      @result.should be_a(Koala::Facebook::GraphCollection)
+    end
+    
+    it "should return nil if the get_collections call fails with nil" do
+      # this happens sometimes
+      @api.should_receive(:graph_call).and_return(nil)
+      @api.get_connections("contextoptional", "photos").should be_nil
+    end
+
+    it "should get a GraphCollection when searching" do
+      result = @api.search("facebook")
+      result.should be_a(Koala::Facebook::GraphCollection)
+    end
+
+    it "should return nil if the search call fails with nil" do
+      # this happens sometimes
+      @api.should_receive(:graph_call).and_return(nil)
+      @api.search("facebook").should be_nil
+    end
+    
+    it "should get a GraphCollection when paging through results" do
+      @results = @api.get_page(["search", {"q"=>"facebook", "limit"=>"25", "until"=>"2010-09-23T21:17:33+0000"}])
+      @results.should be_a(Koala::Facebook::GraphCollection)
+    end
+    
+    it "should return nil if the page call fails with nil" do
+      # this happens sometimes
+      @api.should_receive(:graph_call).and_return(nil)
+      @api.get_page(["search", {"q"=>"facebook", "limit"=>"25", "until"=>"2010-09-23T21:17:33+0000"}]).should be_nil
+    end
+    
+    # GraphCollection attributes
+    describe "the GraphCollection" do
+      before(:each) do
+        @result = @api.get_connections("contextoptional", "photos")
+      end
+          
+      it "should have a read-only paging attribute" do
+        lambda { @result.paging }.should_not raise_error
+        lambda { @result.paging = "paging" }.should raise_error(NoMethodError)
+      end
+  
+      describe "when getting a whole page" do
+        before(:each) do
+          @second_page = stub("page of Fb graph results")
+          @base = stub("base")
+          @args = stub("args")
+          @page_of_results = stub("page of results")
+        end
+    
+        it "should return the previous page of results" do
+          @result.should_receive(:previous_page_params).and_return([@base, @args])
+          @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
+        end
+    
+        it "should return the next page of results" do
+          @result.should_receive(:next_page_params).and_return([@base, @args])
+          @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.next_page.should == @page_of_results        
+        end
+    
+        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
+          end
+        end
+      end
+  
+      describe "when parsing page paramters" do
+        before(:each) do
+          @graph_collection = Koala::Facebook::GraphCollection.new({"data" => []}, Koala::Facebook::GraphAPI.new)
+        end
+    
+        it "should return the base as the first array entry" do
+          base = "url_path"
+          @graph_collection.parse_page_url("anything.com/#{base}?anything").first.should == base 
+        end
+    
+        it "should return the arguments as a hash as the last array entry" do
+          args_hash = {"one" => "val_one", "two" => "val_two"}
+          @graph_collection.parse_page_url("anything.com/anything?#{args_hash.map {|k,v| "#{k}=#{v}" }.join("&")}").last.should == args_hash
+        end
+      end
+    end
+  end
+end

data/spec/koala/net_http_service_tests.rb

@@ -74,7 +74,7 @@ class NetHTTPServiceTests < Test::Unit::TestCase
         Bear.make_request('anything', {}, 'post')
       end
       
-      it "should go to the specified path" do
+      it "should go to the specified path adding a / if it doesn't exist" do
         path = mock('Path')
         @http_yield_mock.should_receive(:post).with(path, anything).and_return(@http_request_result)
         

data/spec/koala/oauth/oauth_tests.rb

@@ -10,7 +10,7 @@ class Time
 end
 
 class FacebookOAuthTests < Test::Unit::TestCase
-  describe "Koala GraphAPI without an access token" do
+  describe "Koala OAuth tests" do
     before :each do
       # make the relevant test data easily accessible
       @oauth_data = $testing_data["oauth_test_data"]
@@ -21,6 +21,13 @@ class FacebookOAuthTests < Test::Unit::TestCase
       @raw_token_string = @oauth_data["raw_token_string"]
       @raw_offline_access_token_string = @oauth_data["raw_offline_access_token_string"]
       
+      # per Facebook's example:
+      # http://developers.facebook.com/docs/authentication/canvas
+      # this allows us to use Facebook's example data while running the other live data
+      @request_secret = @oauth_data["request_secret"] || @secret 
+      @signed_request = @oauth_data["signed_request"]
+      @signed_request_result = @oauth_data["signed_request_result"]
+      
       # this should expanded to cover all variables
       raise Exception, "Must supply app data to run FacebookOAuthTests!" unless @app_id && @secret && @callback_url && 
                                                                                 @code && @raw_token_string && 
@@ -51,7 +58,7 @@ class FacebookOAuthTests < Test::Unit::TestCase
         @oauth.oauth_callback_url == nil).should be_true
     end
     
-    describe "cookie parsing" do
+    describe "for cookie parsing" do
       describe "get_user_info_from_cookies" do
         it "should properly parse valid cookies" do
           result = @oauth.get_user_info_from_cookies(@oauth_data["valid_cookies"])
@@ -113,113 +120,155 @@ class FacebookOAuthTests < Test::Unit::TestCase
     
     # OAuth URLs
     
-    # url_for_oauth_code
-    it "should generate a properly formatted OAuth code URL with the default values" do 
-      url = @oauth.url_for_oauth_code
-      url.should == "https://#{Koala::Facebook::GRAPH_SERVER}/oauth/authorize?client_id=#{@app_id}&redirect_uri=#{@callback_url}"
-    end
-
-    it "should generate a properly formatted OAuth code URL when a callback is given" do 
-      callback = "foo.com"
-      url = @oauth.url_for_oauth_code(:callback => callback)
-      url.should == "https://#{Koala::Facebook::GRAPH_SERVER}/oauth/authorize?client_id=#{@app_id}&redirect_uri=#{callback}"
-    end
+    describe "for URL generation" do
 
-    it "should generate a properly formatted OAuth code URL when permissions are requested as a string" do 
-      permissions = "publish_stream,read_stream"
-      url = @oauth.url_for_oauth_code(:permissions => permissions)
-      url.should == "https://#{Koala::Facebook::GRAPH_SERVER}/oauth/authorize?client_id=#{@app_id}&redirect_uri=#{@callback_url}&scope=#{permissions}"
-    end
+      describe "for OAuth codes" do 
+        # url_for_oauth_code
+        it "should generate a properly formatted OAuth code URL with the default values" do 
+          url = @oauth.url_for_oauth_code
+          url.should == "https://#{Koala::Facebook::GRAPH_SERVER}/oauth/authorize?client_id=#{@app_id}&redirect_uri=#{@callback_url}"
+        end
 
-    it "should generate a properly formatted OAuth code URL when permissions are requested as a string" do 
-      permissions = ["publish_stream", "read_stream"]
-      url = @oauth.url_for_oauth_code(:permissions => permissions)
-      url.should == "https://#{Koala::Facebook::GRAPH_SERVER}/oauth/authorize?client_id=#{@app_id}&redirect_uri=#{@callback_url}&scope=#{permissions.join(",")}"
-    end
+        it "should generate a properly formatted OAuth code URL when a callback is given" do 
+          callback = "foo.com"
+          url = @oauth.url_for_oauth_code(:callback => callback)
+          url.should == "https://#{Koala::Facebook::GRAPH_SERVER}/oauth/authorize?client_id=#{@app_id}&redirect_uri=#{callback}"
+        end
 
-    it "should generate a properly formatted OAuth code URL when both permissions and callback are provided" do 
-      permissions = "publish_stream,read_stream"
-      callback = "foo.com"
-      url = @oauth.url_for_oauth_code(:callback => callback, :permissions => permissions)
-      url.should == "https://#{Koala::Facebook::GRAPH_SERVER}/oauth/authorize?client_id=#{@app_id}&redirect_uri=#{callback}&scope=#{permissions}"
-    end
+        it "should generate a properly formatted OAuth code URL when permissions are requested as a string" do 
+          permissions = "publish_stream,read_stream"
+          url = @oauth.url_for_oauth_code(:permissions => permissions)
+          url.should == "https://#{Koala::Facebook::GRAPH_SERVER}/oauth/authorize?client_id=#{@app_id}&redirect_uri=#{@callback_url}&scope=#{permissions}"
+        end
 
-    it "should raise an exception if no callback is given in initialization or the call" do 
-      oauth2 = Koala::Facebook::OAuth.new(@app_id, @secret)
-      lambda { oauth2.url_for_oauth_code }.should raise_error(ArgumentError)
-    end
+        it "should generate a properly formatted OAuth code URL when permissions are requested as a string" do 
+          permissions = ["publish_stream", "read_stream"]
+          url = @oauth.url_for_oauth_code(:permissions => permissions)
+          url.should == "https://#{Koala::Facebook::GRAPH_SERVER}/oauth/authorize?client_id=#{@app_id}&redirect_uri=#{@callback_url}&scope=#{permissions.join(",")}"
+        end
 
-    # url_for_access_token
-    it "should generate a properly formatted OAuth token URL when provided a code" do 
-      url = @oauth.url_for_access_token(@code)
-      url.should == "https://#{Koala::Facebook::GRAPH_SERVER}/oauth/access_token?client_id=#{@app_id}&redirect_uri=#{@callback_url}&client_secret=#{@secret}&code=#{@code}"
-    end
+        it "should generate a properly formatted OAuth code URL when both permissions and callback are provided" do 
+          permissions = "publish_stream,read_stream"
+          callback = "foo.com"
+          url = @oauth.url_for_oauth_code(:callback => callback, :permissions => permissions)
+          url.should == "https://#{Koala::Facebook::GRAPH_SERVER}/oauth/authorize?client_id=#{@app_id}&redirect_uri=#{callback}&scope=#{permissions}"
+        end
 
-    it "should generate a properly formatted OAuth token URL when provided a callback" do 
-      callback = "foo.com"
-      url = @oauth.url_for_access_token(@code, :callback => callback)
-      url.should == "https://#{Koala::Facebook::GRAPH_SERVER}/oauth/access_token?client_id=#{@app_id}&redirect_uri=#{callback}&client_secret=#{@secret}&code=#{@code}"
-    end
-    
-    describe "get_access_token_info" do
-      it "should properly get and parse an access token token results into a hash" do
-        result = @oauth.get_access_token_info(@code)
-        result.should be_a(Hash)
+        it "should raise an exception if no callback is given in initialization or the call" do 
+          oauth2 = Koala::Facebook::OAuth.new(@app_id, @secret)
+          lambda { oauth2.url_for_oauth_code }.should raise_error(ArgumentError)
+        end
       end
+    
+      describe "for access token URLs" do
 
-      it "should properly include the access token results" do
-        result = @oauth.get_access_token_info(@code)
-        result["access_token"].should
-      end
+        # url_for_access_token
+        it "should generate a properly formatted OAuth token URL when provided a code" do 
+          url = @oauth.url_for_access_token(@code)
+          url.should == "https://#{Koala::Facebook::GRAPH_SERVER}/oauth/access_token?client_id=#{@app_id}&redirect_uri=#{@callback_url}&client_secret=#{@secret}&code=#{@code}"
+        end
 
-      it "should raise an error when get_access_token is called with a bad code" do
-        lambda { @oauth.get_access_token_info("foo") }.should raise_error(Koala::Facebook::APIError) 
+        it "should generate a properly formatted OAuth token URL when provided a callback" do 
+          callback = "foo.com"
+          url = @oauth.url_for_access_token(@code, :callback => callback)
+          url.should == "https://#{Koala::Facebook::GRAPH_SERVER}/oauth/access_token?client_id=#{@app_id}&redirect_uri=#{callback}&client_secret=#{@secret}&code=#{@code}"
+        end
       end
     end
+  
+    describe "for fetching access tokens" do 
+      describe "get_access_token_info" do
+        it "should properly get and parse an access token token results into a hash" do
+          result = @oauth.get_access_token_info(@code)
+          result.should be_a(Hash)
+        end
 
-    describe "get_access_token" do
-      it "should use get_access_token_info to get and parse an access token token results" do
-        result = @oauth.get_access_token(@code)
-        result.should be_a(String)
-      end
+        it "should properly include the access token results" do
+          result = @oauth.get_access_token_info(@code)
+          result["access_token"].should
+        end
 
-      it "should return the access token as a string" do
-        result = @oauth.get_access_token(@code)
-        original = @oauth.get_access_token_info(@code)
-        result.should == original["access_token"]
-      end
-      
-      it "should raise an error when get_access_token is called with a bad code" do
-        lambda { @oauth.get_access_token("foo") }.should raise_error(Koala::Facebook::APIError) 
+        it "should raise an error when get_access_token is called with a bad code" do
+          lambda { @oauth.get_access_token_info("foo") }.should raise_error(Koala::Facebook::APIError) 
+        end
       end
-    end
 
-    describe "get_app_access_token_info" do
-      it "should properly get and parse an app's access token as a hash" do
-        result = @oauth.get_app_access_token_info
-        result.should be_a(Hash)
+      describe "get_access_token" do
+        it "should use get_access_token_info to get and parse an access token token results" do
+          result = @oauth.get_access_token(@code)
+          result.should be_a(String)
+        end
+
+        it "should return the access token as a string" do
+          result = @oauth.get_access_token(@code)
+          original = @oauth.get_access_token_info(@code)
+          result.should == original["access_token"]
+        end
+
+        it "should raise an error when get_access_token is called with a bad code" do
+          lambda { @oauth.get_access_token("foo") }.should raise_error(Koala::Facebook::APIError) 
+        end
       end
+
+      describe "get_app_access_token_info" do
+        it "should properly get and parse an app's access token as a hash" do
+          result = @oauth.get_app_access_token_info
+          result.should be_a(Hash)
+        end
     
-      it "should include the access token" do
-        result = @oauth.get_app_access_token_info
-        result["access_token"].should
+        it "should include the access token" do
+          result = @oauth.get_app_access_token_info
+          result["access_token"].should
+        end
       end
-    end
     
-    describe "get_app_acess_token" do
-      it "should use get_access_token_info to get and parse an access token token results" do
-        result = @oauth.get_app_access_token
-        result.should be_a(String)
+      describe "get_app_acess_token" do
+        it "should use get_access_token_info to get and parse an access token token results" do
+          result = @oauth.get_app_access_token
+          result.should be_a(String)
+        end
+
+        it "should return the access token as a string" do
+          result = @oauth.get_app_access_token
+          original = @oauth.get_app_access_token_info
+          result.should == original["access_token"]
+        end
       end
+      
+      describe "protected methods" do
+      
+        # protected methods
+        # since these are pretty fundamental and pretty testable, we want to test them
+
+        # parse_access_token
+        it "should properly parse access token results" do
+          result = @oauth.send(:parse_access_token, @raw_token_string)
+          has_both_parts = result["access_token"] && result["expires"]
+          has_both_parts.should
+        end
 
-      it "should return the access token as a string" do
-        result = @oauth.get_app_access_token
-        original = @oauth.get_app_access_token_info
-        result.should == original["access_token"]
+        it "should properly parse offline access token results" do
+          result = @oauth.send(:parse_access_token, @raw_offline_access_token_string)
+          has_both_parts = result["access_token"] && !result["expires"]
+          has_both_parts.should
+        end
+
+        # fetch_token_string
+        # somewhat duplicative with the tests for get_access_token and get_app_access_token
+        # but no harm in thoroughness
+        it "should fetch a proper token string from Facebook when given a code" do
+          result = @oauth.send(:fetch_token_string, :code => @code, :redirect_uri => @callback_url)
+          result.should =~ /^access_token/
+        end
+
+        it "should fetch a proper token string from Facebook when asked for the app token" do
+          result = @oauth.send(:fetch_token_string, {:type => 'client_cred'}, true)
+          result.should =~ /^access_token/
+        end
       end
     end
 
-    describe "exchanging session keys" do
+    describe "for exchanging session keys" do
       describe "with get_token_info_from_session_keys" do
         it "should get an array of session keys from Facebook when passed a single key" do
           result = @oauth.get_tokens_from_session_keys([@oauth_data["session_key"]])
@@ -237,6 +286,18 @@ class FacebookOAuthTests < Test::Unit::TestCase
           result = @oauth.get_token_info_from_session_keys(@oauth_data["multiple_session_keys"])
           result[0].should be_a(Hash)
         end
+        
+        it "should properly handle invalid session keys" do
+          result = @oauth.get_token_info_from_session_keys(["foo", "bar"])
+          #it should return nil for each of the invalid ones
+          result.each {|r| r.should be_nil}
+        end
+        
+        it "should properly handle a mix of valid and invalid session keys" do
+          result = @oauth.get_token_info_from_session_keys(["foo"].concat(@oauth_data["multiple_session_keys"]))
+          # it should return nil for each of the invalid ones
+          result.each_with_index {|r, index| index > 0 ? r.should(be_a(Hash)) : r.should(be_nil)}
+        end
       end
       
       describe "with get_tokens_from_session_keys" do
@@ -251,6 +312,18 @@ class FacebookOAuthTests < Test::Unit::TestCase
           result = @oauth.get_tokens_from_session_keys(args)
           result.each {|r| r.should be_a(String) }
         end
+        
+        it "should properly handle invalid session keys" do
+          result = @oauth.get_tokens_from_session_keys(["foo", "bar"])
+          # it should return nil for each of the invalid ones
+          result.each {|r| r.should be_nil}
+        end
+        
+        it "should properly handle a mix of valid and invalid session keys" do
+          result = @oauth.get_tokens_from_session_keys(["foo"].concat(@oauth_data["multiple_session_keys"]))
+          # it should return nil for each of the invalid ones
+          result.each_with_index {|r, index| index > 0 ? r.should(be_a(String)) : r.should(be_nil)}
+        end
       end
 
       describe "get_token_from_session_key" do
@@ -270,39 +343,98 @@ class FacebookOAuthTests < Test::Unit::TestCase
           array = @oauth.get_tokens_from_session_keys([@oauth_data["session_key"]])
           result.should == array[0]
         end
+        
+        it "should properly handle an invalid session key" do
+          result = @oauth.get_token_from_session_key("foo")
+          result.should be_nil
+        end
       end    
     end
     
-    # protected methods
-    # since these are pretty fundamental and pretty testable, we want to test them
-    
-    # parse_access_token
-    it "should properly parse access token results" do
-      result = @oauth.send(:parse_access_token, @raw_token_string)
-      has_both_parts = result["access_token"] && result["expires"]
-      has_both_parts.should
-    end
-    
-    it "should properly parse offline access token results" do
-      result = @oauth.send(:parse_access_token, @raw_offline_access_token_string)
-      has_both_parts = result["access_token"] && !result["expires"]
-      has_both_parts.should
-    end
-    
-    # fetch_token_string
-    # somewhat duplicative with the tests for get_access_token and get_app_access_token
-    # but no harm in thoroughness
-    it "should fetch a proper token string from Facebook when given a code" do
-      result = @oauth.send(:fetch_token_string, :code => @code, :redirect_uri => @callback_url)
-      result.should =~ /^access_token/
-    end
+    describe "for parsing signed requests" do
+      before :each do 
+        # you can test against live data by updating the YML, or you can use the default data
+        # which tests against Facebook's example on http://developers.facebook.com/docs/authentication/canvas
+        @oauth = Koala::Facebook::OAuth.new(@app_id, @request_secret || @app_secret)
+      end
 
-    it "should fetch a proper token string from Facebook when asked for the app token" do
-      result = @oauth.send(:fetch_token_string, {:type => 'client_cred'}, true)
-      result.should =~ /^access_token/
+      it "should break the request into the encoded signature and the payload" do
+        @signed_request.should_receive(:split).with(".").and_return(["", ""])
+        @oauth.parse_signed_request(@signed_request)
+      end
+      
+      it "should base64 URL decode the signed request" do
+        sig = ""
+        @signed_request.should_receive(:split).with(".").and_return([sig, "1"])
+        @oauth.should_receive(:base64_url_decode).with(sig).and_return("4")
+        @oauth.parse_signed_request(@signed_request)
+      end
+
+      it "should base64 URL decode the signed request" do
+        sig = @signed_request.split(".")[0]
+        @oauth.should_receive(:base64_url_decode).with(sig).and_return(nil)
+        @oauth.parse_signed_request(@signed_request)        
+      end
+      
+      it "should get the sha64 encoded payload using proper arguments from OpenSSL::HMAC" do
+        payload = ""
+        @signed_request.should_receive(:split).with(".").and_return(["1", payload])
+        OpenSSL::HMAC.should_receive(:digest).with("sha256", @request_secret, payload)
+        @oauth.parse_signed_request(@signed_request)        
+      end
+      
+      it "should compare the encoded payload with the signature" do
+        sig = "2"
+        @oauth.should_receive(:base64_url_decode).and_return(sig)
+        encoded_payload = "1"
+        OpenSSL::HMAC.should_receive(:digest).with(anything, anything, anything).and_return(encoded_payload)
+        encoded_payload.should_receive(:==).with(sig)
+        @oauth.parse_signed_request(@signed_request)                
+      end
+        
+      describe "if the encoded payload matches the signature" do
+        before :each do
+          # set it up so the sig will match the encoded payload
+          raw_sig = ""
+          @sig = "2"
+          @payload = "1"
+          @signed_request.should_receive(:split).and_return([raw_sig, @payload])
+          @oauth.should_receive(:base64_url_decode).with(raw_sig).and_return(@sig)
+          OpenSSL::HMAC.should_receive(:digest).with(anything, anything, anything).and_return(@sig.dup)
+        end
+        
+        it "should base64_url_decode the payload" do
+          @oauth.should_receive(:base64_url_decode).with(@payload).ordered.and_return("{}")
+          @oauth.parse_signed_request(@signed_request)        
+        end
+        
+        it "should JSON decode the payload" do
+          result = "{}"
+          @oauth.should_receive(:base64_url_decode).with(@payload).and_return(result)
+          JSON.should_receive(:parse).with(result)
+          @oauth.parse_signed_request(@signed_request)        
+        end
+      end
+
+      describe "if the encoded payload does not match the signature" do
+        before :each do
+          sig = ""
+          @signed_request.should_receive(:split).and_return([sig, ""])
+          OpenSSL::HMAC.should_receive(:digest).with(anything, anything, anything).and_return("hi")
+        end
+        
+        it "should return nil" do
+          @oauth.parse_signed_request(@signed_request).should be_nil
+        end
+      end
+      
+      describe "run against data" do
+        it "should work" do
+          @oauth.parse_signed_request(@signed_request).should == @signed_request_result
+        end
+      end
     end
-    
-    # END CODE THAT NEEDS MOCKING
+
   end # describe
 
 end #class