koala 3.0.0.beta2 → 3.0.0.beta3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 18d5d8c95bece65d5f4bab2640d75645dc5fb343
-  data.tar.gz: 6ec125b20dea63584e6dd69fc02ecd08f0800ce2
+  metadata.gz: 2ed893e5254cc1e5b3007301dc847bd025b592c1
+  data.tar.gz: 3ad942cb33ac7e7a36304250dd3cc7c6b36712f8
 SHA512:
-  metadata.gz: 31a10322d86c4c49bd877ad5891cde67db496e506c6b8936d8cf3e67b6bc82e6faed1fe1e93f02dcd123ea8aee77026adc681a3b197006335e7d2f8aac40d968
-  data.tar.gz: f8d69365d42baf15acead1fcc5e38e334084dc49539358189aee046bf611d9c7761ec4ffeac690b07d3a647116ef81ac1e0fdfa2bc1d11010c5ae30dc239a189
+  metadata.gz: 6d4cac2752f9b72f7c1c1cf4632dfaf10b7ba9b72753699540587e3b636b35fde33ca2035b47e468d51d59c490ce9dcbc624618d5eb10e1da3b5fc4c2a11f034
+  data.tar.gz: 4728dfc6777f3e1b29d2dcab6608c9a40f24e8ee8a2136940ed2b463846ddcffa9c0f0afd96a1ab8d21b2d2c0203bdde5ddfe0c4a8ee1d250650921361343c90

data/ISSUE_TEMPLATE

@@ -0,0 +1,23 @@
+Thanks for using Koala! Sorry you've run into an issue 😓  Here are some questions to help get things figured out as quickly as possible.
+
+You don't have to fill this all out -- it's more of a guide. If in doubt, delete any sections that aren't relevant and open the issue. I want to help.
+
+[ ] This is a Koala bug/issue/documentation problem.
+
+Koala is a labor of love both from me and from the awesome community members who answer questions here. Much as we'd love to be able to help with everything, I have to focus my time on issues with the gem itself and can't help with questions on how to _use_ Facebook. (Plus, Facebook is huge!)
+
+If you have questions about using the Facebook API, [facebook.stackoverflow.com](http://facebook.stackoverflow.com) is a great resource.
+
+For code issues:
+
+[ ] What I'm doing works on the [Graph API explorer](https://developers.facebook.com/tools/explorer/)/curl/another tool.
+
+Seeing an example of what works helps diagnose what doesn't work.
+
+[ ] I'm using the newest version
+
+[ ] Here's code to replicate the issue:
+
+Obviously not all code can be shared -- feel free to put variables in place of any sensitive information and describe what should be used to replicate it.
+
+Thanks for submitting an issue! Looking forward to working with you to figure it out.

data/PULL_REQUEST_TEMPLATE

@@ -0,0 +1,9 @@
+Thanks for submitting a pull request to Koala! A huge portion of the gem has been built by awesome people (like you) from the Ruby community.
+
+Here are a few things that will help get your pull request merged in quickly. None of this is required -- you can delete anything not relevant. If in doubt, open the PR! I want to help.
+
+[ ] My PR has tests and they pass!
+[ ] The live tests pass for my changes (`LIVE=true rspec` -- unrelated failures are okay).
+[ ] The PR is based on the most recent master commit and has no merge conflicts.
+
+If you have any questions, feel free to open an issue or comment on your PR!

data/changelog.md

@@ -1,6 +1,11 @@
-v3.0.0
+v3.0.0 (not released yet)
 ======
 
+Most users should not see any difference upgrading from 2.x to 3.0. Most of the changes are
+internal to how requests go from a graph method (like `get_connections`) through the API to the
+HTTP layer and back. If you're not using API#api or HTTPService.make_request directly, upgrading
+should (in theory) require no code changes. (Let me know if you run into any issues.)
+
 **Key breaking changes:**
 
 * Koala now requires Ruby 2.1+ (or equivalent for JRuby, etc.)
@@ -13,8 +18,15 @@ v3.0.0
 * API#search now requires a "type"/:type argument, matching Facebook's behavior (improving their
   cryptic error message)
 
+New features:
+
+* Koala now supports global configuration for tokens, secrets, etc! See the readme.
+* GraphCollection now exposes #headers, allowing access to etag/rate limiting/etc. info (thanks,
+  pawandubey and jessieay!) (#589)
+
 Updated features:
 
+* Koala.config now uses a dedicated Koala::Configuration object
 * TestUser#befriend will provide the appsecret_proof if a secret is set (thanks, kwasimensah!)
 * API#search now requires an object type parameter to be included, matching Facebook's API (#575)
 
@@ -40,7 +52,11 @@ Testing improvements:
 
 * Fixed a bunch of failing mocked specs
 
-v2.5.0
+Others:
+
+* Added an issue and pull request template
+
+v2.5.0 (2017-02-17)
 ======
 
 New features:
@@ -55,7 +71,7 @@ Internal improvements:
 
 * Remove MultiJson dependency (thanks, sakuro!)
 
-v2.4.0
+v2.4.0 (2016-07-08)
 ======
 
 **Note:** Koala is no longer officially supported on Ruby 1.9.3 (which was [end-of-lifed back in
@@ -78,7 +94,7 @@ Testing improvements:
 * Test Koala against Ruby 2.3.0 (thanks, thedrow!)
 
 
-v2.3.0
+v2.3.0 (2016-04-10)
 ======
 
 Updated features:
@@ -99,7 +115,7 @@ Testing improvements:
 * Removed pended specs that were no longer relevant
 * Improved https regex in test suite (thanks, lucaskds!)
 
-v2.2.0
+v2.2.0 (2015-08-11)
 ======
 
 Updated features:

data/lib/koala.rb

@@ -14,6 +14,7 @@ require 'koala/test_users'
 require 'koala/http_service'
 
 # miscellaneous
+require 'koala/configuration'
 require 'koala/utils'
 require 'koala/version'
 require 'ostruct'
@@ -37,14 +38,10 @@ module Koala
     end
 
     # Allows you to control various Koala configuration options.
-    # Notable options:
-    #   * server endpoints: you can override any or all the server endpoints
-    #   (see HTTPService::DEFAULT_SERVERS) if you want to run requests through
-    #   other servers.
-    #   * api_version: controls which Facebook API version to use (v1.0, v2.0,
-    #   etc)
+    # NOTE: this is not currently threadsafe.
+    # See Koala::Configuration.
     def config
-      @config ||= OpenStruct.new(HTTPService::DEFAULT_SERVERS)
+      @config ||= Configuration.new
     end
 
     # Used for testing.

data/lib/koala/api.rb

@@ -15,7 +15,7 @@ module Koala
       #                 https://developers.facebook.com/docs/graph-api/securing-requests/)
       # @note If no access token is provided, you can only access some public information.
       # @return [Koala::Facebook::API] the API client
-      def initialize(access_token = nil, app_secret = nil)
+      def initialize(access_token = Koala.config.access_token, app_secret = Koala.config.app_secret)
         @access_token = access_token
         @app_secret = app_secret
       end
@@ -55,7 +55,7 @@ module Koala
           http_component == :response ? response : response.send(http_component)
         else
           # turn this into a GraphCollection if it's pageable
-          API::GraphCollection.evaluate(response.data, self)
+          API::GraphCollection.evaluate(response, self)
         end
 
         # now process as appropriate for the given call (get picture header, etc.)

data/lib/koala/api/graph_batch_api.rb

@@ -1,5 +1,5 @@
-require 'koala/api'
-require 'koala/api/batch_operation'
+require "koala/api"
+require "koala/api/batch_operation"
 
 module Koala
   module Facebook
@@ -19,7 +19,7 @@ module Koala
 
       # Enqueue a call into the batch for later processing.
       # See API#graph_call
-      def graph_call(path, args = {}, verb = 'get', options = {}, &post_processing)
+      def graph_call(path, args = {}, verb = "get", options = {}, &post_processing)
         # normalize options for consistency
         options = Koala::Utils.symbolize_hash(options)
 
@@ -40,32 +40,26 @@ module Koala
         return [] if batch_calls.empty?
 
         # Turn the call args collected into what facebook expects
-        args = { 'batch' => batch_args }
+        args = {"batch" => batch_args}
         batch_calls.each do |call|
           args.merge! call.files || {}
         end
 
-        original_api.graph_call('/', args, 'post', http_options, &handle_response)
-      end
-
-      def handle_response
-        lambda do |response|
+        original_api.graph_call("/", args, "post", http_options) do |response|
           raise bad_response if response.nil?
-          response.map(&generate_results)
+          generate_results(response)
         end
       end
 
-      def generate_results
+      def generate_results(response)
         index = 0
-        lambda do |call_result|
-          batch_op     = batch_calls[index]; index += 1
+        response.map do |call_result|
+          batch_op = batch_calls[index]
+          index += 1
           post_process = batch_op.post_processing
 
           # turn any results that are pageable into GraphCollections
-          result = GraphCollection.evaluate(
-            result_from_response(call_result, batch_op),
-            original_api
-          )
+          result = result_from_response(call_result, batch_op)
 
           # and pass to post-processing callback if given
           if post_process
@@ -78,34 +72,34 @@ module Koala
 
       def bad_response
         # Facebook sometimes reportedly returns an empty body at times
-        BadFacebookResponse.new(200, '', 'Facebook returned an empty body')
+        BadFacebookResponse.new(200, "", "Facebook returned an empty body")
       end
 
       def result_from_response(response, options)
         return nil if response.nil?
 
-        headers   = coerced_headers_from_response(response)
+        headers   = headers_from_response(response)
         error     = error_from_response(response, headers)
         component = options.http_options[:http_component]
 
-        error || result_from_component({
-          :component => component,
-          :response  => response,
-          :headers   => headers
-        })
+        error || desired_component(
+          component: component,
+          response: response,
+          headers: headers
+        )
       end
 
-      def coerced_headers_from_response(response)
-        headers = response.fetch('headers', [])
+      def headers_from_response(response)
+        headers = response.fetch("headers", [])
 
-        headers.each_with_object({}) do |h, memo|
-          memo.merge! h.fetch('name') => h.fetch('value')
+        headers.inject({}) do |compiled_headers, header|
+          compiled_headers.merge(header.fetch("name") => header.fetch("value"))
         end
       end
 
       def error_from_response(response, headers)
-        code = response['code']
-        body = response['body'].to_s
+        code = response["code"]
+        body = response["body"].to_s
 
         GraphErrorChecker.new(code, body, headers).error_if_appropriate
       end
@@ -121,21 +115,19 @@ module Koala
       def json_body(response)
         # quirks_mode is needed because Facebook sometimes returns a raw true or false value --
         # in Ruby 2.4 we can drop that.
-        JSON.parse(response.fetch('body'), quirks_mode: true)
+        JSON.parse(response.fetch("body"), quirks_mode: true)
       end
 
-      def result_from_component(options)
-        component = options.fetch(:component)
-        response  = options.fetch(:response)
-        headers   = options.fetch(:headers)
+      def desired_component(component:, response:, headers:)
+        result = Koala::HTTPService::Response.new(response['status'], response['body'], headers)
 
         # Get the HTTP component they want
         case component
-        when :status  then response['code'].to_i
+        when :status  then response["code"].to_i
         # facebook returns the headers as an array of k/v pairs, but we want a regular hash
         when :headers then headers
         # (see note in regular api method about JSON parsing)
-        else json_body(response)
+        else GraphCollection.evaluate(result, original_api)
         end
       end
 

data/lib/koala/api/graph_collection.rb

@@ -16,30 +16,41 @@ module Koala
         attr_reader :api
         # The entire raw response from Facebook.
         attr_reader :raw_response
+        # The headers from the Facebook response
+        attr_reader :headers
 
         # Initialize the array of results and store various additional paging-related information.
         #
-        # @param response the response from Facebook (a hash whose "data" key is an array)
+        # @param [Koala::HTTPService::Response] response object wrapping the raw Facebook response
         # @param api the Graph {Koala::Facebook::API API} instance to use to make calls
         #            (usually the API that made the original call).
         #
         # @return [Koala::Facebook::API::GraphCollection] an initialized GraphCollection
         #         whose paging, summary, raw_response, and api attributes are populated.
         def initialize(response, api)
-          super response["data"]
-          @paging = response["paging"]
-          @summary = response["summary"]
-          @raw_response = response
+          super response.data["data"]
+          @paging = response.data["paging"]
+          @summary = response.data["summary"]
+          @raw_response = response.data
           @api = api
+          @headers = response.headers
         end
 
         # @private
         # Turn the response into a GraphCollection if they're pageable;
-        # if not, return the original response.
+        # if not, return the data of the original response.
         # The Ads API (uniquely so far) returns a hash rather than an array when queried
         # with get_connections.
         def self.evaluate(response, api)
-          response.is_a?(Hash) && response["data"].is_a?(Array) ? self.new(response, api) : response
+          return nil if response.nil?
+
+          is_pageable?(response) ? self.new(response, api) : response.data
+        end
+
+        # response will always be an instance of Koala::HTTPService::Response
+        # since that is what we get from Koala::Facebook::API#api
+        def self.is_pageable?(response)
+          response.data.is_a?(Hash) && response.data["data"].is_a?(Array)
         end
 
         # Retrieve the next page of results.

data/lib/koala/configuration.rb

@@ -0,0 +1,49 @@
+# Global configuration for Koala.
+class Koala::Configuration
+  # The default access token to be used if none is otherwise supplied.
+  attr_accessor :access_token
+
+  # The default app secret value to be used if none is otherwise supplied.
+  attr_accessor :app_secret
+
+  # The default application ID to use if none is otherwise supplied.
+  attr_accessor :app_id
+
+  # The default app access token to be used if none is otherwise supplied.
+  attr_accessor :app_access_token
+
+  # The default API version to use if none is otherwise specified.
+  attr_accessor :api_version
+
+  # The default value to use for the oauth_callback_url if no other is provided.
+  attr_accessor :oauth_callback_url
+
+  # Whether to preserve arrays in arguments, which are expected by certain FB APIs (see the ads API
+  # in particular, https://developers.facebook.com/docs/marketing-api/adgroup/v2.4)
+  attr_accessor :preserve_form_arguments
+
+  # The server to use for Graph API requests
+  attr_accessor :graph_server
+
+  # The server to use when constructing dialog URLs.
+  attr_accessor :dialog_host
+
+  # Certain Facebook services (beta, video) require you to access different
+  # servers. If you're using your own servers, for instance, for a proxy,
+  # you can change both the matcher (what value to change when updating the URL) and the
+  # replacement values (what to add).
+  #
+  # So, for instance, to use the beta stack, we match on .facebook and change it to .beta.facebook.
+  # If you're talking to fbproxy.mycompany.com, you could set up beta.fbproxy.mycompany.com for
+  # FB's beta tier, and set the matcher to /\.fbproxy/ and the beta_replace to '.beta.fbproxy'.
+  attr_accessor :host_path_matcher
+  attr_accessor :video_replace
+  attr_accessor :beta_replace
+
+  def initialize
+    # Default to our default values.
+    Koala::HTTPService::DEFAULT_SERVERS.each_pair do |key, value|
+      self.public_send("#{key}=", value)
+    end
+  end
+end

data/lib/koala/http_service.rb

@@ -24,17 +24,11 @@ module Koala
       builder.adapter Faraday.default_adapter
     end
 
-    # Default servers for Facebook. These are read into the config OpenStruct,
-    # and can be overridden via Koala.config.
+    # Default server information for Facebook. These can be overridden by setting config values.
+    # See Koala.config.
     DEFAULT_SERVERS = {
       :graph_server => 'graph.facebook.com',
       :dialog_host => 'www.facebook.com',
-      # certain Facebook services (beta, video) require you to access different
-      # servers. If you're using your own servers, for instance, for a proxy,
-      # you can change both the matcher and the replacement values.
-      # So for instance, if you're talking to fbproxy.mycompany.com, you could
-      # set up beta.fbproxy.mycompany.com for FB's beta tier, and set the
-      # matcher to /\.fbproxy/ and the beta_replace to '.beta.fbproxy'.
       :host_path_matcher => /\.facebook/,
       :video_replace => '-video.facebook',
       :beta_replace => '.beta.facebook'

data/lib/koala/oauth.rb

@@ -12,10 +12,10 @@ module Koala
       # @param app_id [String, Integer] a Facebook application ID
       # @param app_secret a Facebook application secret
       # @param oauth_callback_url the URL in your app to which users authenticating with OAuth will be sent
-      def initialize(app_id, app_secret, oauth_callback_url = nil)
-        @app_id = app_id
-        @app_secret = app_secret
-        @oauth_callback_url = oauth_callback_url
+      def initialize(app_id = nil, app_secret = nil, oauth_callback_url = nil)
+        @app_id = app_id || Koala.config.app_id
+        @app_secret = app_secret || Koala.config.app_secret
+        @oauth_callback_url = oauth_callback_url || Koala.config.oauth_callback_url
       end
 
       # Parses the cookie set Facebook's JavaScript SDK.

data/lib/koala/realtime_updates.rb

@@ -23,9 +23,9 @@ module Koala
       #
       # @raise ArgumentError if the application ID and one of the app access token or the secret are not provided.
       def initialize(options = {})
-        @app_id = options[:app_id]
-        @app_access_token = options[:app_access_token]
-        @secret = options[:secret]
+        @app_id = options[:app_id] || Koala.config.app_id
+        @app_access_token = options[:app_access_token] || Koala.config.app_access_token
+        @secret = options[:secret] || Koala.config.app_secret
         unless @app_id && (@app_access_token || @secret) # make sure we have what we need
           raise ArgumentError, "Initialize must receive a hash with :app_id and either :app_access_token or :secret! (received #{options.inspect})"
         end

data/lib/koala/test_users.rb

@@ -14,7 +14,6 @@ module Koala
     #
     # See http://developers.facebook.com/docs/test_users/.
     class TestUsers
-
       # The application API interface used to communicate with Facebook.
       # @return [Koala::Facebook::API]
       attr_reader :api
@@ -31,9 +30,10 @@ module Koala
       #
       # @raise ArgumentError if the application ID and one of the app access token or the secret are not provided.
       def initialize(options = {})
-        @app_id = options[:app_id]
-        @app_access_token = options[:app_access_token]
-        @secret = options[:secret]
+        @app_id = options[:app_id] || Koala.config.app_id
+        @app_access_token = options[:app_access_token] || Koala.config.app_access_token
+        @secret = options[:secret] || Koala.config.app_secret
+
         unless @app_id && (@app_access_token || @secret) # make sure we have what we need
           raise ArgumentError, "Initialize must receive a hash with :app_id and either :app_access_token or :secret! (received #{options.inspect})"
         end

data/lib/koala/version.rb

@@ -1,3 +1,3 @@
 module Koala
-  VERSION = "3.0.0.beta2"
+  VERSION = "3.0.0.beta3"
 end

data/readme.md

@@ -4,7 +4,7 @@ Koala [![Version](https://img.shields.io/gem/v/koala.svg)](https://rubygems.org/
 
 * 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,35 +12,58 @@ Koala [![Version](https://img.shields.io/gem/v/koala.svg)](https://rubygems.org/
 Installation
 ------------
 
+**Koala 3.0 is in beta! There should be no significant changes** for most users -- please check it
+out!
+
 In Bundler:
 ```ruby
-gem "koala", "~> 2.2"
+gem "koala", "~> 3.0.0.beta2"
+# if you need the previous release
+gem "koala", "~> 2.4"
 ```
 
 Otherwise:
 ```bash
+[sudo|rvm] gem install koala --pre
+# if you need the previous release
 [sudo|rvm] gem install koala
 ```
 
-Upgrading to 2.0+
------------------
+Configuration
+-------------
 
-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.
+Most applications will only use one application configuration. Rather than having toprovide 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
+```
+
+**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
 require 'koala'
 
-@graph = Koala::Facebook::API.new(oauth_access_token)
+# 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")
@@ -56,14 +79,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"
@@ -115,64 +138,20 @@ the results apart from a long list of array entries:
 
 Check out the wiki for more details and examples.
 
-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'
-  # another common option: `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 API 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
 -----------------
@@ -181,6 +160,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:
@@ -206,12 +186,14 @@ 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 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
 -------------------
 
@@ -234,14 +216,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
 -------
@@ -259,26 +233,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

@@ -6,6 +6,26 @@ describe "Koala::Facebook::API" do
   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(
       anything,
@@ -46,18 +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 "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", {}]
@@ -218,7 +226,7 @@ describe "Koala::Facebook::API" do
 
     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.data, @service)
+      expect(Koala::Facebook::API::GraphCollection).to receive(:evaluate).with(dummy_response, @service)
       @service.graph_call("/me")
     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/graph_collection_spec.rb

@@ -1,14 +1,16 @@
 require 'spec_helper'
 
 describe Koala::Facebook::API::GraphCollection do
-  let(:paging){ {:paging => true} }
+  let(:paging){ {"paging" => true} }
 
   before(:each) do
-    @result = {
-      "data" => [1, 2, :three],
+    @headers = {'Content-Type' => 'application/json'}
+    @data = {
+      "data" => [1, 2, 'three'],
       "paging" => paging,
       "summary" => [3]
     }
+    @result = Koala::HTTPService::Response.new(200, @data.to_json, @headers)
     @api = Koala::Facebook::API.new("123")
     @collection = Koala::Facebook::API::GraphCollection.new(@result, @api)
   end
@@ -22,7 +24,7 @@ describe Koala::Facebook::API::GraphCollection do
   end
 
   it "contains the result data" do
-    @result["data"].each_with_index {|r, i| expect(@collection[i]).to eq(r)}
+    @data["data"].each_with_index {|r, i| expect(@collection[i]).to eq(r)}
   end
 
   it "has a read-only paging attribute" do
@@ -31,21 +33,25 @@ describe Koala::Facebook::API::GraphCollection do
   end
 
   it "sets paging to results['paging']" do
-    expect(@collection.paging).to eq(@result["paging"])
+    expect(@collection.paging).to eq(@data["paging"])
   end
 
   it "sets summary to results['summary']" do
-    expect(@collection.summary).to eq(@result["summary"])
+    expect(@collection.summary).to eq(@data["summary"])
   end
 
   it "sets raw_response to the original results" do
-    expect(@collection.raw_response).to eq(@result)
+    expect(@collection.raw_response).to eq(@result.data)
   end
 
   it "sets the API to the provided API" do
     expect(@collection.api).to eq(@api)
   end
 
+  it "sets the headers correctly" do
+    expect(@collection.headers).to eq(@headers)
+  end
+
   describe "when getting a whole page" do
     before(:each) do
       @second_page = {
@@ -55,19 +61,21 @@ describe Koala::Facebook::API::GraphCollection do
       @base = double("base")
       @args = {"a" => 1}
       @page_of_results = double("page of results")
+      @result = Koala::HTTPService::Response.new(200, @second_page.to_json, {})
+      @result.data
     end
 
     it "should return the previous page of results" do
       expect(@collection).to receive(:previous_page_params).and_return([@base, @args])
-      expect(@api).to receive(:api).with(@base, @args, anything, anything).and_return(Koala::HTTPService::Response.new(200, @second_page.to_json, {}))
-      expect(Koala::Facebook::API::GraphCollection).to receive(:new).with(@second_page, @api).and_return(@page_of_results)
+      expect(@api).to receive(:api).with(@base, @args, anything, anything).and_return(@result)
+      expect(Koala::Facebook::API::GraphCollection).to receive(:new).with(@result, @api).and_return(@page_of_results)
       expect(@collection.previous_page).to eq(@page_of_results)
     end
 
     it "should return the next page of results" do
       expect(@collection).to receive(:next_page_params).and_return([@base, @args])
-      expect(@api).to receive(:api).with(@base, @args, anything, anything).and_return(Koala::HTTPService::Response.new(200, @second_page.to_json, {}))
-      expect(Koala::Facebook::API::GraphCollection).to receive(:new).with(@second_page, @api).and_return(@page_of_results)
+      expect(@api).to receive(:api).with(@base, @args, anything, anything).and_return(@result)
+      expect(Koala::Facebook::API::GraphCollection).to receive(:new).with(@result, @api).and_return(@page_of_results)
 
       expect(@collection.next_page).to eq(@page_of_results)
     end
@@ -121,9 +129,11 @@ describe Koala::Facebook::API::GraphCollection do
   end
 
   describe ".evaluate" do
-    it "returns the original result if it's provided a non-hash result" do
-      result = []
-      expect(Koala::Facebook::API::GraphCollection.evaluate(result, @api)).to eq(result)
+    it "returns the body of the original response if it's provided a Response with a non-hash data key" do
+      result = double('fake response')
+      allow(result).to receive(:is_a?).with(Hash).and_return(false)
+      allow(result).to receive(:data).and_return([])
+      expect(Koala::Facebook::API::GraphCollection.evaluate(result, @api)).to eq([])
     end
 
     it "returns the original result if it's provided a nil result" do
@@ -131,18 +141,21 @@ describe Koala::Facebook::API::GraphCollection do
       expect(Koala::Facebook::API::GraphCollection.evaluate(result, @api)).to eq(result)
     end
 
-    it "returns the original result if the result doesn't have a data key" do
-      result = {"paging" => {}}
-      expect(Koala::Facebook::API::GraphCollection.evaluate(result, @api)).to eq(result)
+    it "returns the original result body if the result doesn't have a data key" do
+      paging = {"paging" => {}}
+      result = Koala::HTTPService::Response.new(200, paging.to_json, {})
+      expect(Koala::Facebook::API::GraphCollection.evaluate(result, @api)).to eq(paging)
     end
 
     it "returns the original result if the result's data key isn't an array" do
-      result = {"data" => {}, "paging" => {}}
-      expect(Koala::Facebook::API::GraphCollection.evaluate(result, @api)).to eq(result)
+      body = {"data" => {}, "paging" => {}}
+      result = Koala::HTTPService::Response.new(200, body.to_json, {})
+      expect(Koala::Facebook::API::GraphCollection.evaluate(result, @api)).to eq(body)
     end
 
     it "returns a new GraphCollection of the result if it has an array data key and a paging key" do
-      result = {"data" => [], "paging" => {}}
+      body = {"data" => [], "paging" => {}}
+      result = Koala::HTTPService::Response.new(200, body.to_json, {})
       expected = :foo
       expect(Koala::Facebook::API::GraphCollection).to receive(:new).with(result, @api).and_return(expected)
       expect(Koala::Facebook::API::GraphCollection.evaluate(result, @api)).to eq(expected)

data/spec/cases/http_service/request_spec.rb

@@ -66,17 +66,19 @@ module Koala
           end
 
           context "set by Koala.config" do
-            let(:version) { "v2.1" }
+            let(:version) { "v2.7" }
 
             before :each do
-              allow(Koala.config).to receive(:api_version).and_return(version)
+              Koala.configure do |config|
+                config.api_version = version
+              end
             end
 
             it_should_behave_like :including_the_version
           end
 
           context "set in options" do
-            let(:version) { "v2.1" }
+            let(:version) { "v2.8" }
 
             let(:options) { {api_version: version} }
 

data/spec/cases/koala_spec.rb

@@ -31,9 +31,7 @@ describe Koala do
 
   describe ".configure" do
     it "yields a configurable object" do
-      expect {
-        Koala.configure {|c| c.foo = "bar"}
-      }.not_to raise_exception
+      Koala.configure {|c| expect(c).to be_a(Koala::Configuration)}
     end
 
     it "caches the config (singleton)" do
@@ -56,5 +54,4 @@ describe Koala do
       expect(Koala.config.graph_server).to eq("some-new.graph_server.com")
     end
   end
-
 end

data/spec/cases/oauth_spec.rb

@@ -53,6 +53,45 @@ describe "Koala::Facebook::OAuth" do
              @oauth.app_secret == @secret &&
              @oauth.oauth_callback_url == nil).to be_truthy
     end
+
+    context "with global defaults" do
+      let(:app_id) { :app_id }
+      let(:app_secret) { :app_secret }
+      let(:oauth_callback_url) { :oauth_callback_url }
+
+      before :each do
+        Koala.configure do |config|
+          config.app_id = app_id
+          config.app_secret = app_secret
+          config.oauth_callback_url = oauth_callback_url
+        end
+      end
+
+      it "defaults to the configured data if not otherwise provided" do
+        oauth = Koala::Facebook::OAuth.new
+        expect(oauth.app_id).to eq(app_id)
+        expect(oauth.app_secret).to eq(app_secret)
+        expect(oauth.oauth_callback_url).to eq(oauth_callback_url)
+      end
+
+      it "lets you override app_id" do
+        other_value = :another_id
+        oauth = Koala::Facebook::OAuth.new(other_value)
+        expect(oauth.app_id).to eq(other_value)
+      end
+
+      it "lets you override secret" do
+        other_value = :another_secret
+        oauth = Koala::Facebook::OAuth.new(nil, other_value)
+        expect(oauth.app_secret).to eq(other_value)
+      end
+
+      it "lets you override app_id" do
+        other_value = :another_token
+        oauth = Koala::Facebook::OAuth.new(nil, nil, other_value)
+        expect(oauth.oauth_callback_url).to eq(other_value)
+      end
+    end
   end
 
   describe "for cookie parsing" do

data/spec/cases/realtime_updates_spec.rb

@@ -36,6 +36,45 @@ describe "Koala::Facebook::RealtimeUpdates" do
       expect(updates).to be_a(Koala::Facebook::RealtimeUpdates)
     end
 
+    context "with global defaults" do
+      let(:app_id) { :app_id }
+      let(:app_secret) { :app_secret }
+      let(:app_access_token) { :app_access_token }
+
+      before :each do
+        Koala.configure do |config|
+          config.app_id = app_id
+          config.app_secret = app_secret
+          config.app_access_token = app_access_token
+        end
+      end
+
+      it "defaults to the configured data if not otherwise provided" do
+        rtu = Koala::Facebook::RealtimeUpdates.new
+        expect(rtu.app_id).to eq(app_id)
+        expect(rtu.secret).to eq(app_secret)
+        expect(rtu.app_access_token).to eq(app_access_token)
+      end
+
+      it "lets you override app_id" do
+        other_value = :another_id
+        rtu = Koala::Facebook::RealtimeUpdates.new(app_id: other_value)
+        expect(rtu.app_id).to eq(other_value)
+      end
+
+      it "lets you override secret" do
+        other_value = :another_secret
+        rtu = Koala::Facebook::RealtimeUpdates.new(secret: other_value)
+        expect(rtu.secret).to eq(other_value)
+      end
+
+      it "lets you override app_id" do
+        other_value = :another_token
+        rtu = Koala::Facebook::RealtimeUpdates.new(app_access_token: other_value)
+        expect(rtu.app_access_token).to eq(other_value)
+      end
+    end
+
     # attributes
     it "allows read access to app_id" do
       # in Ruby 1.9, .method returns symbols

data/spec/cases/test_users_spec.rb

@@ -40,12 +40,52 @@ describe "Koala::Facebook::TestUsers" do
       expect(test_users).to be_a(Koala::Facebook::TestUsers)
     end
 
+    context "with global defaults" do
+      let(:app_id) { :app_id }
+      let(:app_secret) { :app_secret }
+      let(:app_access_token) { :app_access_token }
+
+      before :each do
+        Koala.configure do |config|
+          config.app_id = app_id
+          config.app_secret = app_secret
+          config.app_access_token = app_access_token
+        end
+      end
+
+      it "defaults to the configured data if not otherwise provided" do
+        test_users = Koala::Facebook::TestUsers.new
+        expect(test_users.app_id).to eq(app_id)
+        expect(test_users.secret).to eq(app_secret)
+        expect(test_users.app_access_token).to eq(app_access_token)
+      end
+
+      it "lets you override app_id" do
+        other_value = :another_id
+        test_users = Koala::Facebook::TestUsers.new(app_id: other_value)
+        expect(test_users.app_id).to eq(other_value)
+      end
+
+      it "lets you override secret" do
+        other_value = :another_secret
+        test_users = Koala::Facebook::TestUsers.new(secret: other_value)
+        expect(test_users.secret).to eq(other_value)
+      end
+
+      it "lets you override app_id" do
+        other_value = :another_token
+        test_users = Koala::Facebook::TestUsers.new(app_access_token: other_value)
+        expect(test_users.app_access_token).to eq(other_value)
+      end
+    end
+
+
     it "uses the OAuth class to fetch a token when provided an app_id and a secret" do
       oauth = Koala::Facebook::OAuth.new(@app_id, @secret)
       token = oauth.get_app_access_token
       expect(oauth).to receive(:get_app_access_token).and_return(token)
       expect(Koala::Facebook::OAuth).to receive(:new).with(@app_id, @secret).and_return(oauth)
-      test_users = Koala::Facebook::TestUsers.new(:app_id => @app_id, :secret => @secret)
+      Koala::Facebook::TestUsers.new(:app_id => @app_id, :secret => @secret)
     end
 
     # attributes

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: koala
 version: !ruby/object:Gem::Version
-  version: 3.0.0.beta2
+  version: 3.0.0.beta3
 platform: ruby
 authors:
 - Alex Koppel
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2017-02-22 00:00:00.000000000 Z
+date: 2017-03-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -71,8 +71,10 @@ files:
 - ".yardopts"
 - Gemfile
 - Guardfile
+- ISSUE_TEMPLATE
 - LICENSE
 - Manifest
+- PULL_REQUEST_TEMPLATE
 - Rakefile
 - autotest/discover.rb
 - changelog.md
@@ -85,6 +87,7 @@ files:
 - lib/koala/api/graph_batch_api.rb
 - lib/koala/api/graph_collection.rb
 - lib/koala/api/graph_error_checker.rb
+- lib/koala/configuration.rb
 - lib/koala/errors.rb
 - lib/koala/http_service.rb
 - lib/koala/http_service/multipart_request.rb
@@ -98,6 +101,7 @@ files:
 - lib/koala/version.rb
 - readme.md
 - spec/cases/api_spec.rb
+- spec/cases/configuration_spec.rb
 - spec/cases/error_spec.rb
 - spec/cases/graph_api_batch_spec.rb
 - spec/cases/graph_api_spec.rb
@@ -158,6 +162,7 @@ summary: A lightweight, flexible library for Facebook with support for the Graph
   the REST API, realtime updates, and OAuth authentication.
 test_files:
 - spec/cases/api_spec.rb
+- spec/cases/configuration_spec.rb
 - spec/cases/error_spec.rb
 - spec/cases/graph_api_batch_spec.rb
 - spec/cases/graph_api_spec.rb