koala 1.0.0 → 1.2.0

data/lib/koala.rb

@@ -1,22 +1,32 @@
 require 'cgi'
 require 'digest/md5'
 
-require 'json'
+require 'multi_json'
 
 # OpenSSL and Base64 are required to support signed_request
 require 'openssl'
 require 'base64'
 
 # include koala modules
-require 'koala/http_services'
+require 'koala/oauth'
 require 'koala/graph_api'
+require 'koala/graph_batch_api'
+require 'koala/batch_operation'
+require 'koala/graph_collection'
 require 'koala/rest_api'
 require 'koala/realtime_updates'
 require 'koala/test_users'
 
+# HTTP module so we can communicate with Facebook
+require 'koala/http_service'
+
 # add KoalaIO class
 require 'koala/uploadable_io'
 
+# miscellaneous
+require 'koala/utils'
+require 'koala/version'
+
 module Koala
 
   module Facebook
@@ -25,6 +35,7 @@ module Koala
     # Contributors: Alex Koppel, Chris Baclig, Rafi Jacoby, and the team at Context Optional
     # http://github.com/arsduo/koala
 
+    # APIs
     class API
       # initialize with an access token
       def initialize(access_token = nil)
@@ -32,10 +43,13 @@ module Koala
       end
       attr_reader :access_token
 
+      include GraphAPIMethods
+      include RestAPIMethods
+
       def api(path, args = {}, verb = "get", options = {}, &error_checking_block)
         # Fetches the given path in the Graph API.
         args["access_token"] = @access_token || @app_access_token if @access_token || @app_access_token
-        
+
         # add a leading /
         path = "/#{path}" unless path =~ /^\//
 
@@ -47,45 +61,42 @@ module Koala
         # in the case of a server error
         raise APIError.new({"type" => "HTTP #{result.status.to_s}", "message" => "Response body: #{result.body}"}) if result.status >= 500
 
-        # Parse the body as JSON and check for errors if provided a mechanism to do so
+        # parse the body as JSON and run it through the error checker (if provided)
         # 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
+        # and cause MultiJson.decode to fail -- so we account for that by wrapping the result in []
+        body = MultiJson.decode("[#{result.body.to_s}]")[0]
+        yield body if error_checking_block
 
-        # now return the desired information
-        if options[:http_component]
-          result.send(options[:http_component])
-        else
-          body
-        end
+        # if we want a component other than the body (e.g. redirect header for images), return that
+        options[:http_component] ? result.send(options[:http_component]) : body
       end
     end
 
-    class GraphAPI < API
-      include GraphAPIMethods
+    # special enhanced APIs
+    class GraphBatchAPI < API
+      include GraphBatchAPIMethods
     end
 
-    class RestAPI < API
-      include RestAPIMethods
+    class RealtimeUpdates
+      include RealtimeUpdateMethods
     end
 
-    class GraphAndRestAPI < API
-      include GraphAPIMethods
-      include RestAPIMethods
+    class TestUsers
+      include TestUserMethods
     end
 
-    class RealtimeUpdates < API
-      include RealtimeUpdateMethods
+    # legacy support for old APIs
+    class OldAPI < API;
+      def initialize(*args)
+        Koala::Utils.deprecate("#{self.class.name} is deprecated and will be removed in a future version; please use the API class instead.")
+        super
+      end
     end
+    class GraphAPI < OldAPI; end
+    class RestAPI < OldAPI; end
+    class GraphAndRestAPI < OldAPI; end
 
-    class TestUsers < API
-      include TestUserMethods
-      # make the Graph API accessible in case someone wants to make other calls to interact with their users
-      attr_reader :graph_api
-    end
+    # Errors
 
     class APIError < StandardError
       attr_accessor :fb_error_type
@@ -94,201 +105,32 @@ module Koala
         super("#{fb_error_type}: #{details["message"]}")
       end
     end
+  end
 
+  class KoalaError < StandardError; end
 
-    class OAuth
-      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
-        @oauth_callback_url = oauth_callback_url
-      end
-
-      def get_user_info_from_cookie(cookie_hash)
-        # Parses the cookie set by the official Facebook JavaScript SDK.
-        #
-        # cookies should be a Hash, like the one Rails provides
-        #
-        # If the user is logged in via Facebook, we return a dictionary with the
-        # keys "uid" and "access_token". The former is the user's Facebook ID,
-        # and the latter can be used to make authenticated requests to the Graph API.
-        # If the user is not logged in, we return None.
-        #
-        # Download the official Facebook JavaScript SDK at
-        # http://github.com/facebook/connect-js/. Read more about Facebook
-        # authentication at http://developers.facebook.com/docs/authentication/.
-
-        if fb_cookie = cookie_hash["fbs_" + @app_id.to_s]
-          # remove the opening/closing quote
-          fb_cookie = fb_cookie.gsub(/\"/, "")
-
-          # since we no longer get individual cookies, we have to separate out the components ourselves
-          components = {}
-          fb_cookie.split("&").map {|param| param = param.split("="); components[param[0]] = param[1]}
-
-          # generate the signature and make sure it matches what we expect
-          auth_string = components.keys.sort.collect {|a| a == "sig" ? nil : "#{a}=#{components[a]}"}.reject {|a| a.nil?}.join("")
-          sig = Digest::MD5.hexdigest(auth_string + @app_secret)
-          sig == components["sig"] && (components["expires"] == "0" || Time.now.to_i < components["expires"].to_i) ? components : nil
-        end
-      end
-      alias_method :get_user_info_from_cookies, :get_user_info_from_cookie
-
-      def get_user_from_cookie(cookies)
-        if info = get_user_info_from_cookies(cookies)
-          string = info["uid"]
-        end
-      end
-      alias_method :get_user_from_cookies, :get_user_from_cookie
-
-      # URLs
-
-      def url_for_oauth_code(options = {})
-        # for permissions, see http://developers.facebook.com/docs/authentication/permissions
-        permissions = options[:permissions]
-        scope = permissions ? "&scope=#{permissions.is_a?(Array) ? permissions.join(",") : permissions}" : ""
-        display = options.has_key?(:display) ? "&display=#{options[:display]}" : ""
-        
-        callback = options[:callback] || @oauth_callback_url
-        raise ArgumentError, "url_for_oauth_code must get a callback either from the OAuth object or in the options!" unless callback
-
-        # Creates the URL for oauth authorization for a given callback and optional set of permissions
-        "https://#{GRAPH_SERVER}/oauth/authorize?client_id=#{@app_id}&redirect_uri=#{callback}#{scope}#{display}"
-      end
-
-      def url_for_access_token(code, options = {})
-        # Creates the URL for the token corresponding to a given code generated by Facebook
-        callback = options[:callback] || @oauth_callback_url
-        raise ArgumentError, "url_for_access_token must get a callback either from the OAuth object or in the parameters!" unless callback
-        "https://#{GRAPH_SERVER}/oauth/access_token?client_id=#{@app_id}&redirect_uri=#{callback}&client_secret=#{@app_secret}&code=#{code}"
-      end
-
-      def get_access_token_info(code, options = {})
-        # 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}, false, options)
-      end
-
-      def get_access_token(code, options = {})
-        # upstream methods will throw errors if needed
-        if info = get_access_token_info(code, options)
-          string = info["access_token"]
-        end
-      end
-
-      def get_app_access_token_info(options = {})
-        # convenience method to get a the application's sessionless access token
-        get_token_from_server({:type => 'client_cred'}, true, options)
-      end
-
-      def get_app_access_token(options = {})
-        if info = get_app_access_token_info(options)
-          string = info["access_token"]
-        end
-      end
-
-      # Originally provided directly by Facebook, however this has changed
-      # as their concept of crypto changed. For historic purposes, this is their proposal:
-      # https://developers.facebook.com/docs/authentication/canvas/encryption_proposal/
-      # Currently see https://github.com/facebook/php-sdk/blob/master/src/facebook.php#L758
-      # for a more accurate reference implementation strategy.
-      def parse_signed_request(input)
-        encoded_sig, encoded_envelope = input.split('.', 2)
-        signature = base64_url_decode(encoded_sig).unpack("H*").first
-        envelope = JSON.parse(base64_url_decode(encoded_envelope))
-
-        raise "SignedRequest: Unsupported algorithm #{envelope['algorithm']}" if envelope['algorithm'] != 'HMAC-SHA256'
-
-        # now see if the signature is valid (digest, key, data)
-        hmac = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, @app_secret, encoded_envelope.tr("-_", "+/"))
-        raise 'SignedRequest: Invalid signature' if (signature != hmac)
-
-        return envelope
-      end
-
-      # from session keys
-      def get_token_info_from_session_keys(sessions, options = {})
-        # fetch the OAuth tokens from Facebook
-        response = fetch_token_string({
-          :type => 'client_cred',
-          :sessions => sessions.join(",")
-        }, true, "exchange_sessions", options)
-
-        # Facebook returns an empty body in certain error conditions
-        if response == ""
-          raise APIError.new({
-            "type" => "ArgumentError",
-            "message" => "get_token_from_session_key received an error (empty response body) for sessions #{sessions.inspect}!"
-          })
-        end
-
-        JSON.parse(response)
-      end
-
-      def get_tokens_from_session_keys(sessions, options = {})
-        # get the original hash results
-        results = get_token_info_from_session_keys(sessions, options)
-        # now recollect them as just the access tokens
-        results.collect { |r| r ? r["access_token"] : nil }
-      end
-
-      def get_token_from_session_key(session, options = {})
-        # convenience method for a single key
-        # gets the overlaoded strings automatically
-        get_tokens_from_session_keys([session], options)[0]
-      end
-
-      protected
-
-      def get_token_from_server(args, post = false, options = {})
-        # fetch the result from Facebook's servers
-        result = fetch_token_string(args, post, "access_token", options)
-
-        # 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("=")
-          hash.merge!(key => value)
-        end
-        components
-      end
-
-      def fetch_token_string(args, post = false, endpoint = "access_token", options = {})
-        Koala.make_request("/oauth/#{endpoint}", {
-          :client_id => @app_id,
-          :client_secret => @app_secret
-        }.merge!(args), post ? "post" : "get", {:use_ssl => true}.merge!(options)).body
-      end
 
-      # base 64
-      # directly from https://github.com/facebook/crypto-request-examples/raw/master/sample.rb
-      def base64_url_decode(str)
-        str += '=' * (4 - str.length.modulo(4))
-        Base64.decode64(str.tr('-_', '+/'))
-      end
-    end
+  # finally, the few things defined on the Koala module itself
+  class << self
+    attr_accessor :http_service
   end
 
-  class KoalaError< StandardError; end
-
-  # finally, set up the http service Koala methods used to make requests
-  # you can use your own (for HTTParty, etc.) by calling Koala.http_service = YourModule
   def self.http_service=(service)
-    self.send(:include, service)
+    if service.respond_to?(:deprecated_interface)
+      # if this is a deprecated module, support the old interface
+      # by changing the default adapter so the right library is used
+      # we continue to use the single HTTPService module for everything
+      service.deprecated_interface 
+    else
+      # if it's a real http_service, use it
+      @http_service = service
+    end
   end
 
-  # by default, try requiring Typhoeus -- if that works, use it
-  # if you have Typheous and don't want to use it (or want another service),
-  # you can run Koala.http_service = NetHTTPService (or MyHTTPService)
-  begin
-    Koala.http_service = TyphoeusService
-  rescue LoadError
-    Koala.http_service = NetHTTPService
+  def self.make_request(path, args, verb, options = {})
+    http_service.make_request(path, args, verb, options)
   end
+
+  # we use Faraday as our main service, with mock as the other main one
+  self.http_service = HTTPService
 end

data/readme.md

@@ -1,67 +1,95 @@
+[![Build Status](https://secure.travis-ci.org/arsduo/koala.png)](http://travis-ci.org/arsduo/koala)
+
 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 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.)
-* 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.)
+* Lightweight: Koala should be as light and simple as Facebook’s own libraries, providing API accessors and returning simple JSON.
+* Fast: Koala should, out of the box, be quick. Out of the box, we use Facebook's faster read-only servers when possible and if available, the Typhoeus gem to make snappy Facebook requests.  Of course, that brings us to our next topic:
+* Flexible: Koala should be useful to everyone, regardless of their current configuration.  (We support JRuby, Rubinius, and REE as well as vanilla Ruby, and use the Faraday library to provide complete flexibility over how HTTP requests are made.)
+* Tested: Koala should have complete test coverage, so you can rely on it.  (Our test coverage is complete and can be run against either mocked responses or the live Facebook servers.)
 
-1.0 
+Facebook Changes on October 1, 2011
 ---
-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:
-  
-    sudo gem install koala --pre
-  
+**Koala 1.2 supports all of Facebook's new authentication schemes**, which will be introduced on October 1, 2011; the old Javascript library and older authentication schemes will be deprecated at the same time. 
+
+To test your application, upgrade to the latest version of Koala (see below) and configure your application according to Facebook's [OAuth 2.0 and HTTPS Migration](https://developers.facebook.com/docs/oauth2-https-migration/) guide.  If you have the appropriate calls to get_user_info_from_cookies (apps using the Javascript SDK) and/or parse_signed_params (for Canvas and tab apps), your application should work without a hitch.
+
+_Note_: in their new secure cookie format, Facebook provides an OAuth code, which Koala automatically exchanges for an access token.  Because this involves a call to Facebook's servers, you should consider storing the user's access token in their session and only calling get_user_info_from_cookies when necessary (access_token not present, you discover it's expired, etc.).  Otherwise, you'll be calling out to Facebook each time the user loads a page, slowing down your site.  (As we figure out best practices for this, we'll update the wiki.)
+
+Installation
+---
+
+Easy:
+
+    [sudo|rvm] gem install koala
+
+Or in Bundler:
+
+    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::API.new(oauth_access_token)
+    # in 1.1 or earlier, use GraphAPI instead of API
+    
+    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!")
+    # 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 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:
+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")
-
-    # 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)
+    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
 
-    # 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 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:
 
-    # You can use those params to easily get the next (or prevous) page
-    page = graph.get_page(feed.next_page_params)
+    # 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
 
-Check out the wiki for more examples.
+Check out the wiki for more details and 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:
+Fortunately, Koala supports the REST API using the very same interface; to use this, instantiate an API:
 
-	@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::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
 
-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.
+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.
 
-(If you want the power of both APIs in the palm of your hand, try out the GraphAndRestAPI class.)
+    @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))
+    
 
 OAuth
 -----
@@ -70,7 +98,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 +109,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).
+For those building apps on Facebook, parsing signed requests is simple:
+    @oauth.parse_signed_request(signed_request_string)
 
-*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:
+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 +144,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::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)
+
 See examples, ask questions
 -----
 Some resources to help you as you play with Koala and the Graph API:
@@ -130,14 +167,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:
-    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
+    # you can also test against Facebook's beta tier
+    LIVE=true BETA=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.)
+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_base_spec.rb → api_spec.rb}

@@ -44,7 +44,7 @@ describe "Koala::Facebook::API" do
 
     Koala.stub(:make_request).and_return(response)
 
-    @service.api('anything', 'get', {}, :http_component => http_component)
+    @service.api('anything', {}, 'get', :http_component => http_component)
   end
 
   it "should return the body of the request as JSON if no http_component is given" do
@@ -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
 
@@ -98,4 +98,29 @@ describe "Koala::Facebook::API" do
     end
   end
 
-end
+  describe "with an access token" do
+    before(:each) do
+      @api = Koala::Facebook::API.new(@token)
+    end
+
+    it_should_behave_like "Koala RestAPI"
+    it_should_behave_like "Koala RestAPI with an access token"
+
+    it_should_behave_like "Koala GraphAPI"
+    it_should_behave_like "Koala GraphAPI with an access token"
+    it_should_behave_like "Koala GraphAPI with GraphCollection"
+  end
+
+  describe "without an access token" do
+    before(:each) do
+      @api = Koala::Facebook::API.new
+    end
+
+    it_should_behave_like "Koala RestAPI"
+    it_should_behave_like "Koala RestAPI without an access token"
+
+    it_should_behave_like "Koala GraphAPI"
+    it_should_behave_like "Koala GraphAPI without an access token"
+    it_should_behave_like "Koala GraphAPI with GraphCollection"
+  end
+end

data/spec/cases/error_spec.rb

@@ -0,0 +1,32 @@
+require 'spec_helper'
+
+describe Koala::Facebook::APIError do
+  it "is a StandardError" do
+    Koala::Facebook::APIError.new.should be_a(StandardError)
+  end
+
+  it "has an accessor for fb_error_type" do
+    Koala::Facebook::APIError.instance_methods.map(&:to_sym).should include(:fb_error_type)
+    Koala::Facebook::APIError.instance_methods.map(&:to_sym).should include(:fb_error_type=)
+  end
+
+  it "sets fb_error_type to details['type']" do
+    type = "foo"
+    Koala::Facebook::APIError.new("type" => type).fb_error_type.should == type
+  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}/
+  end
+end
+
+describe Koala::KoalaError do
+  it "is a StandardError" do
+     Koala::KoalaError.new.should be_a(StandardError)
+  end
+end
+