koala 1.0.0 → 1.1.0

data/readme.md

@@ -1,37 +1,38 @@
 Koala
 ====
-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 (including photo uploads), the old REST API, realtime updates, and OAuth validation.  We wrote Koala with four goals:
+[Koala](http://github.com/arsduo/koala) is a new Facebook library for Ruby, supporting the Graph API (including the batch requests and photo uploads), the REST API, realtime updates, test users, 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 750 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.)
+* 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, at just over 750 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.  (In addition to vanilla Ruby, we support JRuby, Rubinius, and REE, and provide  built-in mechanism for using whichever HTTP library you prefer.)
 * 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.)
 
-1.0 
+Installation
 ---
-Version 1.0 is due out on May 1st, 2011 with a ton of great features.  
-    
-    sudo gem install koala
 
-Until then, you can install the release candidate like so:
+Easy:
+    
+    [sudo|rvm] gem install koala
+    
+Or in Bundler:
   
-    sudo gem install koala --pre
+    gem "koala"
   
 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")
-    graph.put_object("me", "feed", :message => "I am writing on my wall!")
+    @graph = Koala::Facebook::GraphAPI.new(oauth_access_token)
+    profile = @graph.get_object("me")
+    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")
+    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]
@@ -44,20 +45,29 @@ When retrieving data that returns an array of results (for example, when calling
     # 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)
+    # You can use those params to easily get the next (or previous) page
+    page = @graph.get_page(feed.next_page_params)
+
+You can make multiple calls at once using Facebook's batch API:
+
+    # Returns an array of results as if they were called non-batch
+    @graph.batch do |batch_api|
+      batch_api.get_object('me')
+      batch_api.get_object('koppel')
+    end
 
 Check out the wiki for more examples.
 
-The old-school REST API
+The 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 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:
 
-	@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
+  	@rest = Koala::Facebook::RestAPI.new(oauth_access_token)
+  	@rest.fql_query(my_fql_query) # convenience method
+  	@rest.fql_multiquery(fql_query_hash) # 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.
 
@@ -70,7 +80,7 @@ You can use the Graph and REST APIs without an OAuth access token, but the real
 
 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_cookies(cookies) # gets the user's ID
-	@oauth.get_user_info_from_cookies(cookies) # parses and returns the entire hash
+	  @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
@@ -81,20 +91,18 @@ And if you have to use the more complicated [redirect-based OAuth process](http:
 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:
+For those building apps on Facebook, parsing signed requests is simple:
     @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:
+Or, if for some horrible reason, you're still using session keys, despair not!  It's easy to turn them into shiny, modern OAuth tokens:
     @oauth.get_token_from_session_key(session_key)
     @oauth.get_tokens_from_session_keys(array_of_session_keys)
 
+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.
-
-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.
+Sometimes, reaching out to Facebook is a pain -- let it reach out to you instead.  The Graph API allows your application to subscribe to real-time updates for certain objects in the graph; check the [official Facebook documentation](http://developers.facebook.com/docs/api/realtime) for more details on what objects you can subscribe to and what limitations may apply.
 
 Koala makes it easy to interact with your applications using the RealtimeUpdates class:
 
@@ -118,6 +126,17 @@ And to top it all off, RealtimeUpdates provides a static method to respond to Fa
 
 For more information about meet_challenge and the RealtimeUpdates class, check out the Real-Time Updates page on the wiki.
 
+Test Users
+-----
+
+We also support the test users API, allowing you to conjure up fake users and command them to do your bidding using the Graph or REST API:
+    
+    @test_users = Koala::Facebook::TestUsers.new(:app_id => id, :secret => secret)
+    user = @test_users.create(is_app_installed, desired_permissions)
+    user_graph_api = Koala::Facebook::GraphAPI.new(user["access_token"])
+    # or, if you want to make a whole community:
+    @test_users.create_network(network_size, is_app_installed, common_permissions)
+
 See examples, ask questions
 -----
 Some resources to help you as you play with Koala and the Graph API:
@@ -132,12 +151,12 @@ Testing
 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:
     
     # From anywhere in the project directory:
-    rake spec
+    bundle exec rake spec
     
 
 You can also run live tests against Facebook's servers:
     
     # Again from anywhere in the project directory:
-    LIVE=true rake spec
+    LIVE=true bundle exec rake spec
 
-Important Note: to run the live tests, you have to provide some of your own data in spec/fixtures/facebook_data.yml: a valid OAuth access token with publish\_stream, read\_stream, and user\_photos permissions and an OAuth code that can be used to generate an access token.  You can get thisdata 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.)
+Important Note: to run the live tests, you have to provide some of your own data in spec/fixtures/facebook_data.yml: a valid OAuth access token with publish\_stream, read\_stream, and user\_photos permissions and an OAuth code that can be used to generate an access token.  You can get this 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/cases/api_base_spec.rb

@@ -52,21 +52,21 @@ describe "Koala::Facebook::API" do
     Koala.stub(:make_request).and_return(response)
 
     json_body = mock('JSON body')
-    JSON.stub(:parse).and_return([json_body])
+    MultiJson.stub(:decode).and_return([json_body])
 
     @service.api('anything').should == json_body
   end
 
-  it "should execute a block with the response body if passed one" do
+  it "should execute an error checking block if provided" do
     body = '{}'
     Koala.stub(:make_request).and_return(Koala::Response.new(200, body, {}))
 
     yield_test = mock('Yield Tester')
     yield_test.should_receive(:pass)
 
-    @service.api('anything') do |arg|
+    @service.api('anything', {}, "get") do |arg|
       yield_test.pass
-      arg.should == JSON.parse(body)
+      arg.should == MultiJson.decode(body)
     end
   end