koala 1.5.0 → 1.6.0.rc1

data/lib/koala/version.rb

@@ -1,3 +1,3 @@
 module Koala
-  VERSION = "1.5.0"
+  VERSION = "1.6.0.rc1"
 end

data/readme.md

@@ -13,52 +13,78 @@ Installation
 ---
 
 Easy:
-
-    [sudo|rvm] gem install koala
+```bash
+[sudo|rvm] gem install koala
+```
 
 Or in Bundler:
-
-    gem "koala"
+```ruby
+gem "koala"
+```
 
 Graph API
 ----
-The Graph API is the simple, slick new interface to Facebook's data.  Using it with Koala is quite straightforward:
+The Graph API is the simple, slick new interface to Facebook's data.  
+Using it with Koala is quite straightforward.  First, you'll need an access token, which you can get through 
+Facebook's [Graph API Explorer](https://developers.facebook.com/tools/explorer) (click on 'Get Access Token').  
+Then, go exploring:
 
-    @graph = Koala::Facebook::API.new(oauth_access_token)
-    # in 1.1 or earlier, use GraphAPI instead of API
+```ruby
+@graph = Koala::Facebook::API.new(oauth_access_token)
 
-    profile = @graph.get_object("me")
-    friends = @graph.get_connections("me", "friends")
-    @graph.put_connections("me", "feed", :message => "I am writing on my wall!")
+profile = @graph.get_object("me")
+friends = @graph.get_connections("me", "friends")
+@graph.put_connections("me", "feed", :message => "I am writing on my wall!")
 
-    # three-part queries are easy too!
-    @graph.get_connections("me", "mutualfriends/#{friend_id}")
+# three-part queries are easy too!
+@graph.get_connections("me", "mutualfriends/#{friend_id}")
 
-    # you can even use the new Timeline API
-    # see https://developers.facebook.com/docs/beta/opengraph/tutorial/
-    @graph.put_connections("me", "namespace:action", :object => object_url)
+# you can even use the new Timeline API
+# see https://developers.facebook.com/docs/beta/opengraph/tutorial/
+@graph.put_connections("me", "namespace:action", :object => object_url)
+```
 
 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 API#get_connections or API#search) a GraphCollection object will be returned, which makes it easy to page through the results:
+When retrieving data that returns an array of results (for example, when calling `API#get_connections` or `API#search`)
+a GraphCollection object will be returned, which makes it easy to page through the results:
 
-    # Returns the feed items for the currently logged-in user as a GraphCollection
-    feed = @graph.get_connections("me", "feed")
-    feed.each {|f| do_something_with_item(f) } # it's a subclass of Array
-    next_feed = feed.next_page
+```ruby
+# Returns the feed items for the currently logged-in user as a GraphCollection
+feed = @graph.get_connections("me", "feed")
+feed.each {|f| do_something_with_item(f) } # it's a subclass of Array
+next_feed = feed.next_page
 
-    # You can also get an array describing the URL for the next page: [path, arguments]
-    # This is useful for storing page state across multiple browser requests
-    next_page_params = feed.next_page_params
-    page = @graph.get_page(next_page_params)
+# You can also get an array describing the URL for the next page: [path, arguments]
+# This is useful for storing page state across multiple browser requests
+next_page_params = feed.next_page_params
+page = @graph.get_page(next_page_params)
+```
 
 You can also make multiple calls at once using Facebook's batch API:
+```ruby
+# Returns an array of results as if they were called non-batch
+@graph.batch do |batch_api|
+  batch_api.get_object('me')
+  batch_api.put_wall_post('Making a post in a batch.')
+end
+```
+
+You can pass a "post-processing" block to each of Koala's Graph API methods. This is handy for two reasons:
+
+1. You can modify the result returned by the Graph API method:
+
+        education = @graph.get_object("me") { |data| data['education'] }
+        # returned value only contains the "education" portion of the profile
 
-    # Returns an array of results as if they were called non-batch
-    @graph.batch do |batch_api|
-      batch_api.get_object('me')
-      batch_api.put_wall_post('Making a post in a batch.')
-    end
+2. You can consume the data in place which is particularly useful in the batch case, so you don't have to pull
+the results apart from a long list of array entries:
+
+        @graph.batch do |batch_api|
+          # Assuming you have database fields "about_me" and "photos"
+          batch_api.get_object('me')                {|me|     self.about_me = me }
+          batch_api.get_connections('me', 'photos') {|photos| self.photos   = photos }
+        end
 
 Check out the wiki for more details and examples.
 
@@ -67,55 +93,56 @@ 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.
 
 Fortunately, Koala supports the REST API using the very same interface; to use this, instantiate an API:
+```ruby
+@rest = Koala::Facebook::API.new(oauth_access_token)
 
-    @rest = Koala::Facebook::API.new(oauth_access_token)
-    # in 1.1 or earlier, use RestAPI instead of API
-
-  	@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
+@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
+```
 
 Of course, you can use the Graph API methods on the same object -- the power of two APIs right in the palm of your hand.
+```ruby
+@api = Koala::Facebook::API.new(oauth_access_token)
 
-    @api = Koala::Facebook::API.new(oauth_access_token)
-    # in 1.1 or earlier, use GraphAndRestAPI instead of API
-
-    @api = Koala::Facebook::API.new(oauth_access_token)
-    fql = @api.fql_query(my_fql_query)
-    @api.put_wall_post(process_result(fql))
-
+@api = Koala::Facebook::API.new(oauth_access_token)
+fql = @api.fql_query(my_fql_query)
+@api.put_wall_post(process_result(fql))
+```
 
 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, app_secret, callback_url)
+```ruby
+@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/facebook-js-sdk) (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
-
+```ruby
+@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
-	  @oauth.url_for_oauth_code
-	  # fetch the access token once you have the code
-	  @oauth.get_access_token(code)
+```ruby
+# 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
-
+```ruby
+@oauth.get_app_access_token
+```
 For those building apps on Facebook, parsing signed requests is simple:
-
-    @oauth.parse_signed_request(signed_request_string)
-
+```ruby
+@oauth.parse_signed_request(signed_request_string)
+```
 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)
-
+```ruby
+@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
@@ -123,50 +150,50 @@ Real-time Updates
 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:
-
-    @updates = Koala::Facebook::RealtimeUpdates.new(:app_id => app_id, :secret => secret)
-
+```ruby
+@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:
+```ruby
+# 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_url, verify_token)
 
-    # 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_url, verify_token)
-
-    # Get an array of your current subscriptions (one hash for each object you've subscribed to)
-    @updates.list_subscriptions
-
-    # Unsubscribe from updates for an object
-    @updates.unsubscribe("user")
+# Get an array of your current subscriptions (one hash for each object you've subscribed to)
+@updates.list_subscriptions
 
+# 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)
-
+```ruby
+# 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.
 
 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::API.new(user["access_token"])
-    # or, if you want to make a whole community:
-    @test_users.create_network(network_size, is_app_installed, common_permissions)
-
+```ruby
+@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::API.new(user["access_token"])
+# or, if you want to make a whole community:
+@test_users.create_network(network_size, is_app_installed, common_permissions)
+```
 Talking to Facebook
 -----
 
 Koala uses Faraday to make HTTP requests, which means you have complete control over how your app makes HTTP requests to Facebook.  You can set Faraday options globally or pass them in on a per-request (or both):
-
-    # Set an SSL certificate to avoid Net::HTTP errors
-    Koala.http_service.http_options = {
-      :ssl => { :ca_path => "/etc/ssl/certs" }
-    }
-    # or on a per-request basis
-    @api.get_object(id, args_hash, { :timeout => 10 })
-
+```ruby
+# Set an SSL certificate to avoid Net::HTTP errors
+Koala.http_service.http_options = {
+  :ssl => { :ca_path => "/etc/ssl/certs" }
+}
+# or on a per-request basis
+@api.get_object(id, args_hash, { :timeout => 10 })
+```
 The <a href="https://github.com/arsduo/koala/wiki/HTTP-Services">HTTP Services wiki page</a> has more information on what options are available, as well as on how to configure your own Faraday middleware stack (for instance, to implement request logging).
 
 See examples, ask questions
@@ -184,16 +211,16 @@ 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:
-    bundle exec rake spec
-
+```bash
+# From anywhere in the project directory:
+bundle exec rake spec
+```
 
 You can also run live tests against Facebook's servers:
-
-    # Again from anywhere in the project directory:
-    LIVE=true bundle exec rake spec
-    # you can also test against Facebook's beta tier
-    LIVE=true BETA=true bundle exec rake spec
-
+```bash
+# Again from anywhere in the project directory:
+LIVE=true bundle exec rake spec
+# you can also test against Facebook's beta tier
+LIVE=true BETA=true bundle exec rake spec
+```
 By default, the live tests are run against test users, so you can run them as frequently as you want.  If you want to run them against a real user, however, you can fill in the OAuth token, code, and access\_token values in spec/fixtures/facebook_data.yml.  See the wiki for more details.

data/spec/cases/api_spec.rb

@@ -65,15 +65,15 @@ describe "Koala::Facebook::API" do
   end
 
   it "executes an error checking block if provided" do
-    body = '{}'
-    Koala.stub(:make_request).and_return(Koala::HTTPService::Response.new(200, body, {}))
+    response = Koala::HTTPService::Response.new(200, '{}', {})
+    Koala.stub(:make_request).and_return(response)
 
     yield_test = mock('Yield Tester')
     yield_test.should_receive(:pass)
 
     @service.api('anything', {}, "get") do |arg|
       yield_test.pass
-      arg.should == MultiJson.load(body)
+      arg.should == response
     end
   end
 

data/spec/cases/error_spec.rb

@@ -1,40 +1,76 @@
 require 'spec_helper'
 
 describe Koala::Facebook::APIError do
-  it "is a StandardError" do
-    Koala::Facebook::APIError.new.should be_a(StandardError)
+  it "is a Koala::KoalaError" do
+    Koala::Facebook::APIError.new(nil, nil).should be_a(Koala::KoalaError)
   end
 
-  [:fb_error_type, :fb_error_code, :fb_error_message, :raw_response].each do |accessor|
+  [:fb_error_type, :fb_error_code, :fb_error_subcode, :fb_error_message, :http_status, :response_body].each do |accessor|
     it "has an accessor for #{accessor}" do
       Koala::Facebook::APIError.instance_methods.map(&:to_sym).should include(accessor)
       Koala::Facebook::APIError.instance_methods.map(&:to_sym).should include(:"#{accessor}=")
     end
   end
 
-  it "sets raw_response to the provided error details" do
-    error_response = {"type" => "foo", "other_details" => "bar"}
-    Koala::Facebook::APIError.new(error_response).raw_response.should == error_response
+  it "sets http_status to the provided status" do
+    error_response = '{ "error": {"type": "foo", "other_details": "bar"} }'
+    Koala::Facebook::APIError.new(400, error_response).response_body.should == error_response
+  end
+
+  it "sets response_body to the provided response body" do
+    Koala::Facebook::APIError.new(400, '').http_status.should == 400
+  end
+
+  context "with an error_info hash" do
+    let(:error) { 
+      error_info = {
+        'type' => 'type',
+        'message' => 'message',
+        'code' => 1,
+        'error_subcode' => 'subcode'
+      }
+      Koala::Facebook::APIError.new(400, '', error_info)
+    }
+
+    {
+      :fb_error_type => 'type',
+      :fb_error_message => 'message',
+      :fb_error_code => 1,
+      :fb_error_subcode => 'subcode'
+    }.each_pair do |accessor, value|
+      it "sets #{accessor} to #{value}" do
+        error.send(accessor).should == value
+      end
+    end
+
+    it "sets the error message \"type: error_info['type'], code: error_info['code'], error_subcode: error_info['error_subcode'], message: error_info['message'] [HTTP http_status]\"" do
+      error.message.should == "type: type, code: 1, error_subcode: subcode, message: message [HTTP 400]"
+    end
   end
 
-  {
-    :fb_error_type => 'type',
-    :fb_error_message => 'message',
-    :fb_error_code => 'code'
-  }.each_pair do |accessor, key|
-    it "sets #{accessor} to details['#{key}']" do
-      value = "foo"
-      Koala::Facebook::APIError.new(key => value).send(accessor).should == value
+  context "with an error_info string" do
+    it "sets the error message \"error_info [HTTP http_status]\"" do
+      error_info = "Facebook is down."
+      error = Koala::Facebook::APIError.new(400, '', error_info)
+      error.message.should == "Facebook is down. [HTTP 400]"
     end
   end
 
-  it "sets the error message details['type']: details['message']" do
-    type = "foo"
-    message = "bar"
-    error = Koala::Facebook::APIError.new("type" => type, "message" => message)
-    error.message.should =~ /#{type}/
-    error.message.should =~ /#{message}/
+  context "with no error_info and a response_body containing error JSON" do
+    it "should extract the error info from the response body" do
+      response_body = '{ "error": { "type": "type", "message": "message", "code": 1, "error_subcode": "subcode" } }'
+      error = Koala::Facebook::APIError.new(400, response_body)
+      {
+        :fb_error_type => 'type',
+        :fb_error_message => 'message',
+        :fb_error_code => 1,
+        :fb_error_subcode => 'subcode'
+      }.each_pair do |accessor, value|
+        error.send(accessor).should == value
+      end
+    end
   end
+
 end
 
 describe Koala::KoalaError do
@@ -43,3 +79,38 @@ describe Koala::KoalaError do
   end
 end
 
+describe Koala::Facebook::OAuthSignatureError do
+  it "is a Koala::KoalaError" do
+     Koala::KoalaError.new.should be_a(Koala::KoalaError)
+  end
+end
+
+describe Koala::Facebook::BadFacebookResponse do
+  it "is a Koala::Facebook::APIError" do
+     Koala::Facebook::BadFacebookResponse.new(nil, nil).should be_a(Koala::Facebook::APIError)
+  end
+end
+
+describe Koala::Facebook::OAuthTokenRequestError do
+  it "is a Koala::Facebook::APIError" do
+     Koala::Facebook::OAuthTokenRequestError.new(nil, nil).should be_a(Koala::Facebook::APIError)
+  end
+end
+
+describe Koala::Facebook::ServerError do
+  it "is a Koala::Facebook::APIError" do
+     Koala::Facebook::ServerError.new(nil, nil).should be_a(Koala::Facebook::APIError)
+  end
+end
+
+describe Koala::Facebook::ClientError do
+  it "is a Koala::Facebook::APIError" do
+     Koala::Facebook::ClientError.new(nil, nil).should be_a(Koala::Facebook::APIError)
+  end
+end
+
+describe Koala::Facebook::AuthenticationError do
+  it "is a Koala::Facebook::ClientError" do
+     Koala::Facebook::AuthenticationError.new(nil, nil).should be_a(Koala::Facebook::ClientError)
+  end
+end