koala 2.4.0 → 3.5.0

data/readme.md

@@ -1,10 +1,10 @@
-Koala [![Version](https://img.shields.io/gem/v/koala.svg)](https://rubygems.org/gems/koala) [![Dependencies](https://img.shields.io/gemnasium/arsduo/koala.svg)](https://gemnasium.com/arsduo/koala) [![Build Status](https://img.shields.io/travis/arsduo/koala.svg)](http://travis-ci.org/arsduo/koala) [![Code Climate](https://img.shields.io/codeclimate/github/arsduo/koala.svg)](https://codeclimate.com/github/arsduo/koala) [![Code Coverage](https://img.shields.io/codeclimate/coverage/github/arsduo/koala.svg)](https://codeclimate.com/github/arsduo/koala)
+Koala [![Version](https://img.shields.io/gem/v/koala.svg)](https://rubygems.org/gems/koala) [![Build Status](https://img.shields.io/travis/arsduo/koala.svg)](http://travis-ci.org/arsduo/koala) [![Code Climate](https://img.shields.io/codeclimate/coverage-letter/arsduo/koala.svg)](https://codeclimate.com/github/arsduo/koala) [![Code Coverage](https://img.shields.io/codeclimate/coverage/arsduo/koala.svg)](https://codeclimate.com/github/arsduo/koala)
 ====
-[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:
+[Koala](http://github.com/arsduo/koala) is a Facebook library for Ruby, supporting the Graph API (including the batch requests and photo uploads), the Marketing API, the Atlas 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 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 (1.8.7, 1.9.2, 1.9.3, and 2.0.0), and use the Faraday library to provide complete flexibility over how HTTP requests are made.
+* Flexible: Koala should be useful to everyone, regardless of their current configuration.  We support all currently-supported Ruby versions (MRI 2.1-2.4) and Koala should work on JRuby and Rubinius.
 * 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; we're also on [Travis CI](http://travis-ci.org/arsduo/koala/).
 
 **Found a bug? Interested in contributing?** Check out the Maintenance section below!
@@ -12,9 +12,12 @@ Koala [![Version](https://img.shields.io/gem/v/koala.svg)](https://rubygems.org/
 Installation
 ------------
 
+**Koala 3.0 is out! There should be no significant changes** for most users. If you encounter any
+problems, please file an issue and I'll take a look.
+
 In Bundler:
 ```ruby
-gem "koala", "~> 2.2"
+gem "koala"
 ```
 
 Otherwise:
@@ -22,23 +25,41 @@ Otherwise:
 [sudo|rvm] gem install koala
 ```
 
-Upgrading to 2.0+
------------------
+Configuration
+-------------
+
+Most applications will only use one application configuration. Rather than having to provide that
+value every time, you can configure Koala to use global settings:
+
+```ruby
+# In Rails, you could put this in config/initializers/koala.rb
+Koala.configure do |config|
+  config.access_token = MY_TOKEN
+  config.app_access_token = MY_APP_ACCESS_TOKEN
+  config.app_id = MY_APP_ID
+  config.app_secret = MY_APP_SECRET
+  # See Koala::Configuration for more options, including details on how to send requests through
+  # your own proxy servers.
+end
+```
 
-Koala 2.0 is not a major refactor, but rather a set of small, mostly internal
-refactors, which should not require significant changes by users. See changelog.md for more
-details.
+**Note**: this is not currently threadsafe. (PRs welcome as long as they support both threaded and
+non-threaded configuration.)
 
 Graph API
 ---------
 
-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').
+The Graph API is the 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:
 
 ```ruby
-@graph = Koala::Facebook::API.new(oauth_access_token)
+require 'koala'
+
+# access_token and other values aren't required if you set the defaults as described above
+@graph = Koala::Facebook::API.new(access_token)
 
 profile = @graph.get_object("me")
 friends = @graph.get_connections("me", "friends")
@@ -54,14 +75,14 @@ friends = @graph.get_connections("me", "friends")
 # For extra security (recommended), you can provide an appsecret parameter,
 # tying your access tokens to your app secret.
 # (See https://developers.facebook.com/docs/reference/api/securing-graph-api/
-# You'll need to turn on 'Require proof on all calls' in the advanced section
+
+# You may need to turn on 'Require proof on all calls' in the advanced section
 # of your app's settings when doing this.
-@graph = Koala::Facebook::API.new(oauth_access_token, app_secret)
+@graph = Koala::Facebook::API.new(access_token, app_secret)
 
 # Facebook is now versioning their API. # If you don't specify a version, Facebook
-# will default to the oldest version your app is allowed to use. Note that apps
-# created after f8 2014 *cannot* use the v1.0 API. See
-# https://developers.facebook.com/docs/apps/versions for more information.
+# will default to the oldest version your app is allowed to use.
+# See https://developers.facebook.com/docs/apps/versions for more information.
 #
 # You can specify version either globally:
 Koala.config.api_version = "v2.0"
@@ -113,85 +134,20 @@ the results apart from a long list of array entries:
 
 Check out the wiki for more details and examples.
 
-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.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)
-fql = @api.fql_query(my_fql_query)
-@api.put_wall_post(process_result(fql))
-```
-
-Configuration
--------------
-
-You can change the host that koala makes requests to (point to a mock server, apigee, runscope etc..)
-```ruby
-# config/initializers/koala.rb
-require 'koala'
-
-Koala.configure do |config|
-  config.graph_server = 'my-graph-mock.mysite.com'
-  # other common options are `rest_server` and `dialog_host`
-  # see lib/koala/http_service.rb
-end
-```
-
-Of course the defaults are the facebook endpoints and you can additionally configure the beta
-tier and video upload matching and replacement strings.
-
-OAuth
+App Access Tokens
 -----
 
-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:
+You get your application's own access token, which can be used without a user session for subscriptions and certain other requests:
 ```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:
-```ruby
-# parses and returns a hash including the token and the user id
-# NOTE: this method can only be called once per session, as the OAuth code
-# Facebook supplies can only be redeemed once.  Your application must handle
-# cross-request storage of this information; you can no longer call this method
-# multiple times.
-@oauth.get_user_info_from_cookies(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:
-
-```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:
-```ruby
 @oauth.get_app_access_token
 ```
 For those building apps on Facebook, parsing signed requests is simple:
 ```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:
-```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).
+
+The OAuth class has additional methods that may occasionally be useful.
 
 Real-time Updates
 -----------------
@@ -200,6 +156,7 @@ Sometimes, reaching out to Facebook is a pain -- let it reach out to you instead
 
 Koala makes it easy to interact with your applications using the RealtimeUpdates class:
 ```ruby
+# This class also supports the defaults as described above
 @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:
@@ -220,17 +177,50 @@ 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.
 
+Rate limits
+-----------
+
+We support Facebook rate limit informations as defined here: [https://developers.facebook.com/docs/graph-api/overview/rate-limiting/](https://developers.facebook.com/docs/graph-api/overview/rate-limiting/)
+
+The information is available either via the `Facebook::APIError`:
+
+```ruby
+error.fb_buc_usage
+error.fb_ada_usage
+error.fb_app_usage
+```
+
+Or with the rate_limit_hook:
+
+```ruby
+# App level configuration
+
+Koala.configure do |config|
+  config.rate_limit_hook = ->(limits) { 
+    limits["x-app-usage"] # {"call_count"=>0, "total_cputime"=>0, "total_time"=>0}
+    limits["x-ad-account-usage"] # {"acc_id_util_pct"=>9.67}
+    limits["x-business-use-case-usage"] # {"123456789012345"=>[{"type"=>"messenger", "call_count"=>1, "total_cputime"=>1, "total_time"=>1, "estimated_time_to_regain_access"=>0}]}
+  }
+end
+
+# Per API configuration
+
+Koala::Facebook::API.new('', '', ->(limits) {})
+```
+
 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:
+We also support the test users API, allowing you to conjure up fake users and command them to do your bidding using the Graph API:
 ```ruby
+# This class also supports the defaults as described above
 @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
 -------------------
 
@@ -253,14 +243,6 @@ Some resources to help you as you play with Koala and the Graph API:
 * Complete Koala documentation <a href="https://github.com/arsduo/koala/wiki">on the wiki</a>
 * Facebook's <a href="http://facebook.stackoverflow.com/">Stack Overflow site</a> is a stupendous place to ask questions, filled with people who will help you figure out what's up with the Facebook API.
 * Facebook's <a href="http://developers.facebook.com/tools/explorer/">Graph API Explorer</a>, where you can play with the Graph API in your browser
-* The Koala-powered <a href="http://oauth.twoalex.com" target="_blank">OAuth Playground</a>, where you can easily generate OAuth access tokens and any other data needed to test out the APIs or OAuth
-* Follow Koala on <a href="http://www.facebook.com/pages/Koala/315368291823667">Facebook</a> and <a href="https://twitter.com/#!/koala_fb">Twitter</a> for SDK updates and occasional news about Facebook API changes.
-
-*Note*: I use the Koala issues tracker on Github to triage and address issues
-with the gem itself; if you need help using the Facebook API, the above
-resources will be far more effective. Depending on how much time I have, Github
-issues filed about how to use the Facebook API may be closed with a reference
-to the Facebook Stack Overflow page.
 
 Testing
 -------
@@ -278,26 +260,18 @@ 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.
 
 Maintenance
 -----------
 
 _Pull requests_: Koala exists as it does thanks to the amazing support and work of community members of all
-backgrounds and levels of experience. Pull requests are very welcome! If you have any questions,
-just open an issue.
+backgrounds and levels of experience. Pull requests are very welcome!
+
+_Issues_: If you have any questions about the gem, found an issue in the Ruby code or
+documentation, or have another question that isn't right for StackOverflow, just open an issue and fill out the template.
 
 Please note that this project is released with a Contributor Code of Conduct. By participating in
 this project you agree to abide by its terms. See
 [code_of_conduct.md](https://github.com/arsduo/koala/blob/master/code_of_conduct.md) for more information.
-
-_Schedule_: In order to keep Koala moving forward on a regular and predictable schedule, I will
-address issues and pull requests at least three times a year: late July/early August, late
-December/early January, and late March/early April. I may respond to issues in between maintenance
-periods, but it'll depend on other life/work goings-on.
-
-Breaking/new Facebook changes and other urgent issues obviously will get addressed much more
-quickly. (We've never had a security issue, but obviously that would be priority 0.)
-
-Have questions? Found a breaking bug or urgent issue? [Tweet at me](http://twitter.com/arsduo) --
-I'm always happy to respond.

data/spec/cases/api_spec.rb

@@ -1,9 +1,30 @@
 require 'spec_helper'
 
 describe "Koala::Facebook::API" do
-  before(:each) do
+  before :each do
     @service = Koala::Facebook::API.new
   end
+  let(:dummy_response) { double("fake response", data: {}, status: 200, body: "", headers: {}) }
+
+  it "defaults to the globally configured token if one's provided" do
+    token = "Foo"
+
+    Koala.configure do |config|
+      config.access_token = token
+    end
+
+    expect(Koala::Facebook::API.new.access_token).to eq(token)
+  end
+
+  it "defaults to the globally configured app_secret if one's provided" do
+    app_secret = "Foo"
+
+    Koala.configure do |config|
+      config.app_secret = app_secret
+    end
+
+    expect(Koala::Facebook::API.new.app_secret).to eq(app_secret)
+  end
 
   it "doesn't include an access token if none was given" do
     expect(Koala).to receive(:make_request).with(
@@ -45,36 +66,6 @@ describe "Koala::Facebook::API" do
     service.api('anything', args)
   end
 
-  it "has an attr_reader for access token" do
-    token = 'adfadf'
-    service = Koala::Facebook::API.new token
-    expect(service.access_token).to eq(token)
-  end
-
-  it "has an attr_reader for app_secret" do
-    secret = double
-    service = Koala::Facebook::API.new(@token, secret)
-    expect(service.app_secret).to eq(secret)
-  end
-
-  it "gets the attribute of a Koala::HTTPService::Response given by the http_component parameter" do
-    http_component = :method_name
-
-    response = double('Mock KoalaResponse', :body => '', :status => 200)
-    result = double("result")
-    allow(response).to receive(http_component).and_return(result)
-    allow(Koala).to receive(:make_request).and_return(response)
-
-    expect(@service.api('anything', {}, 'get', :http_component => http_component)).to eq(result)
-  end
-
-  it "returns the entire response if http_component => :response" do
-    http_component = :response
-    response = double('Mock KoalaResponse', :body => '', :status => 200)
-    allow(Koala).to receive(:make_request).and_return(response)
-    expect(@service.api('anything', {}, 'get', :http_component => http_component)).to eq(response)
-  end
-
   it "turns arrays of non-enumerables into comma-separated arguments by default" do
     args = [12345, {:foo => [1, 2, "3", :four]}]
     expected = ["/12345", {:foo => "1,2,3,four"}, "get", {}]
@@ -123,43 +114,12 @@ describe "Koala::Facebook::API" do
     @service.api(*args)
   end
 
-  it "returns the body of the request as JSON if no http_component is given" do
-    response = double('response', :body => 'body', :status => 200)
-    allow(Koala).to receive(:make_request).and_return(response)
-
-    json_body = double('JSON body')
-    allow(MultiJson).to receive(:load).and_return([json_body])
-
-    expect(@service.api('anything')).to eq(json_body)
-  end
-
-  it "executes an error checking block if provided" do
-    response = Koala::HTTPService::Response.new(200, '{}', {})
-    allow(Koala).to receive(:make_request).and_return(response)
-
-    yield_test = double('Yield Tester')
-    expect(yield_test).to receive(:pass)
-
-    @service.api('anything', {}, "get") do |arg|
-      yield_test.pass
-      expect(arg).to eq(response)
-    end
-  end
-
   it "raises an API error if the HTTP response code is greater than or equal to 500" do
     allow(Koala).to receive(:make_request).and_return(Koala::HTTPService::Response.new(500, 'response body', {}))
 
     expect { @service.api('anything') }.to raise_exception(Koala::Facebook::APIError)
   end
 
-  it "handles rogue true/false as responses" do
-    expect(Koala).to receive(:make_request).and_return(Koala::HTTPService::Response.new(200, 'true', {}))
-    expect(@service.api('anything')).to be_truthy
-
-    expect(Koala).to receive(:make_request).and_return(Koala::HTTPService::Response.new(200, 'false', {}))
-    expect(@service.api('anything')).to be_falsey
-  end
-
   describe "path manipulation" do
     context "leading /" do
       it "adds a leading / to the path if not present" do
@@ -179,11 +139,9 @@ describe "Koala::Facebook::API" do
   describe "with an access token" do
     before(:each) do
       @api = Koala::Facebook::API.new(@token)
+      @app_access_token = KoalaTest.app_access_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"
@@ -194,12 +152,10 @@ describe "Koala::Facebook::API" do
       @api = Koala::Facebook::API.new
     end
 
-    it_should_behave_like "Koala RestAPI"
-    it_should_behave_like "Koala RestAPI without an access token"
-
+    # In theory this should behave the same with a GraphCollection, but those tests currently hit
+    # an endpoint that now requires a 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
 
   context '#api' do
@@ -252,4 +208,155 @@ describe "Koala::Facebook::API" do
       end
     end
   end
+
+  describe "#graph_call" do
+    it "passes all arguments to the api method" do
+      user = KoalaTest.user1
+      args = {}
+      verb = 'get'
+      opts = {:a => :b}
+      expect(@service).to receive(:api).with(user, args, verb, opts).and_return(dummy_response)
+      @service.graph_call(user, args, verb, opts)
+    end
+
+    it "throws an APIError if the result hash has an error key" do
+      allow(Koala).to receive(:make_request).and_return(Koala::HTTPService::Response.new(500, '{"error": "An error occurred!"}', {}))
+      expect { @service.graph_call(KoalaTest.user1, {}) }.to raise_exception(Koala::Facebook::APIError)
+    end
+
+    it "passes the results through GraphCollection.evaluate" do
+      allow(@service).to receive(:api).and_return(dummy_response)
+      expect(Koala::Facebook::API::GraphCollection).to receive(:evaluate).with(dummy_response, @service)
+      @service.graph_call("/me")
+    end
+
+    it "returns the results of GraphCollection.evaluate" do
+      expected = {}
+      allow(@service).to receive(:api).and_return(dummy_response)
+      expect(Koala::Facebook::API::GraphCollection).to receive(:evaluate).and_return(expected)
+      expect(@service.graph_call("/me")).to eq(expected)
+    end
+
+    it "returns the post_processing block's results if one is supplied" do
+      other_result = [:a, 2, :three]
+      block = Proc.new {|r| other_result}
+      allow(@service).to receive(:api).and_return(dummy_response)
+      expect(@service.graph_call("/me", {}, "get", {}, &block)).to eq(other_result)
+    end
+
+    it "gets the status of a Koala::HTTPService::Response if requested" do
+      response = Koala::HTTPService::Response.new(200, '', {})
+      allow(Koala).to receive(:make_request).and_return(response)
+
+      expect(@service.graph_call('anything', {}, 'get', http_component: :status)).to eq(200)
+    end
+
+    it "gets the headers of a Koala::HTTPService::Response if requested" do
+      headers = {"a" => 2}
+      response = Koala::HTTPService::Response.new(200, '', headers)
+      allow(Koala).to receive(:make_request).and_return(response)
+
+      expect(@service.graph_call('anything', {}, 'get', :http_component => :headers)).to eq(headers)
+    end
+
+    it "returns the entire response if http_component => :response" do
+      http_component = :response
+      response = Koala::HTTPService::Response.new(200, '', {})
+      allow(Koala).to receive(:make_request).and_return(response)
+      expect(@service.graph_call('anything', {}, 'get', :http_component => http_component)).to eq(response)
+    end
+
+    it "returns the body of the request as JSON if no http_component is given" do
+      result = {"a" => 2}
+      response = Koala::HTTPService::Response.new(200, result.to_json, {})
+      allow(Koala).to receive(:make_request).and_return(response)
+
+      expect(@service.graph_call('anything')).to eq(result)
+    end
+
+    it "handles rogue true/false as responses" do
+      expect(Koala).to receive(:make_request).and_return(Koala::HTTPService::Response.new(200, 'true', {}))
+      expect(@service.graph_call('anything')).to be_truthy
+
+      expect(Koala).to receive(:make_request).and_return(Koala::HTTPService::Response.new(200, 'false', {}))
+      expect(@service.graph_call('anything')).to be_falsey
+    end
+  end
+
+  describe "Rate limit hook" do
+    it "is called when x-business-use-case-usage header is present" do
+      api = Koala::Facebook::API.new('', '', ->(limits) {
+        expect(limits["x-business-use-case-usage"]).to eq({"123456789012345"=>[{"type"=>"messenger", "call_count"=>1, "total_cputime"=>1, "total_time"=>1, "estimated_time_to_regain_access"=>0}]})
+      })
+
+      result = {"a" => 2}
+      response = Koala::HTTPService::Response.new(200, result.to_json, { "x-business-use-case-usage" => "{\"123456789012345\":[{\"type\":\"messenger\",\"call_count\":1,\"total_cputime\":1,\"total_time\":1,\"estimated_time_to_regain_access\":0}]}" })
+      allow(Koala).to receive(:make_request).and_return(response)
+
+      api.graph_call('anything')
+    end
+
+    it "is called when x-ad-account-usage header is present" do
+      api = Koala::Facebook::API.new('', '', ->(limits) {
+        expect(limits["x-ad-account-usage"]).to eq({"acc_id_util_pct"=>9.67})
+      })
+
+      result = {"a" => 2}
+      response = Koala::HTTPService::Response.new(200, result.to_json, { "x-ad-account-usage" => "{\"acc_id_util_pct\":9.67}" })
+      allow(Koala).to receive(:make_request).and_return(response)
+
+      api.graph_call('anything')
+    end
+
+    it "is called when x-app-usage header is present" do
+      api = Koala::Facebook::API.new('', '', ->(limits) {
+        expect(limits["x-app-usage"]).to eq({"call_count"=>0, "total_cputime"=>0, "total_time"=>0})
+      })
+
+      result = {"a" => 2}
+      response = Koala::HTTPService::Response.new(200, result.to_json, { "x-app-usage" => "{\"call_count\":0,\"total_cputime\":0,\"total_time\":0}" })
+      allow(Koala).to receive(:make_request).and_return(response)
+
+      api.graph_call('anything')
+    end
+
+    it "isn't called if none of the rate limit header is present" do
+      rate_limit_hook_called = false
+
+      api = Koala::Facebook::API.new('', '', ->(limits) {
+        rate_limit_hook_called = true
+      })
+
+      result = {"a" => 2}
+      response = Koala::HTTPService::Response.new(200, result.to_json, {})
+      allow(Koala).to receive(:make_request).and_return(response)
+
+      api.graph_call('anything')
+
+      expect(rate_limit_hook_called).to be(false)
+    end
+
+    it "isn't called if no rate limit hook is defined" do
+      api = Koala::Facebook::API.new('', '', ->(limits) {
+        #noop
+      })
+
+      result = {"a" => 2}
+      response = Koala::HTTPService::Response.new(200, result.to_json, { "x-ad-account-usage" => "{\"acc_id_util_pct\"9.67}"})
+      allow(Koala).to receive(:make_request).and_return(response)
+
+      expect(Koala::Utils.logger).to receive(:error).with(/JSON::ParserError:.*unexpected token at '{"acc_id_util_pct"9.67}' while parsing x-ad-account-usage = {"acc_id_util_pct"9.67}/)
+      api.graph_call('anything')
+    end
+
+    it "logs an error if the rate limit header can't be properly parsed" do
+      api = Koala::Facebook::API.new('', '', nil)
+
+      result = {"a" => 2}
+      response = Koala::HTTPService::Response.new(200, result.to_json, {})
+      allow(Koala).to receive(:make_request).and_return(response)
+
+      api.graph_call('anything')
+    end
+  end
 end

data/spec/cases/configuration_spec.rb

@@ -0,0 +1,11 @@
+require "spec_helper"
+
+RSpec.describe Koala::Configuration do
+  let(:config) { Koala::Configuration.new }
+
+  it "defaults the HTTPService's DEFAULT_SERVERS" do
+    Koala::HTTPService::DEFAULT_SERVERS.each_pair do |key, value|
+      expect(config.public_send(key)).to eq(value)
+    end
+  end
+end

data/spec/cases/error_spec.rb

@@ -1,5 +1,9 @@
 require 'spec_helper'
 
+BUC_USAGE_JSON = "{\"123456789012345\":[{\"type\":\"messenger\",\"call_count\":1,\"total_cputime\":1,\"total_time\":1,\"estimated_time_to_regain_access\":0}]}"
+ADA_USAGE_JSON = "{\"acc_id_util_pct\":9.67}"
+APP_USAGE_JSON = "{\"call_count\":0,\"total_cputime\":0,\"total_time\":0}"
+
 describe Koala::Facebook::APIError do
   it "is a Koala::KoalaError" do
     expect(Koala::Facebook::APIError.new(nil, nil)).to be_a(Koala::KoalaError)
@@ -32,7 +36,10 @@ describe Koala::Facebook::APIError do
         'error_user_title' => 'error user title',
         'x-fb-trace-id' => 'fb trace id',
         'x-fb-debug' => 'fb debug token',
-        'x-fb-rev' => 'fb revision'
+        'x-fb-rev' => 'fb revision',
+        'x-business-use-case-usage' => BUC_USAGE_JSON,
+        'x-ad-account-usage' => ADA_USAGE_JSON,
+        'x-app-usage' => APP_USAGE_JSON
       }
       Koala::Facebook::APIError.new(400, '', error_info)
     }
@@ -46,7 +53,10 @@ describe Koala::Facebook::APIError do
       :fb_error_user_title => 'error user title',
       :fb_error_trace_id => 'fb trace id',
       :fb_error_debug => 'fb debug token',
-      :fb_error_rev => 'fb revision'
+      :fb_error_rev => 'fb revision',
+      :fb_buc_usage => JSON.parse(BUC_USAGE_JSON),
+      :fb_ada_usage => JSON.parse(ADA_USAGE_JSON),
+      :fb_app_usage => JSON.parse(APP_USAGE_JSON)
     }.each_pair do |accessor, value|
       it "sets #{accessor} to #{value}" do
         expect(error.send(accessor)).to eq(value)
@@ -76,7 +86,10 @@ describe Koala::Facebook::APIError do
         :fb_error_code => 1,
         :fb_error_subcode => 'subcode',
         :fb_error_user_msg => 'error user message',
-        :fb_error_user_title => 'error user title'
+        :fb_error_user_title => 'error user title',
+        :fb_buc_usage => nil,
+        :fb_ada_usage => nil,
+        :fb_app_usage => nil
       }.each_pair do |accessor, value|
         expect(error.send(accessor)).to eq(value)
       end