koala 2.5.0 → 3.0.0

data/lib/koala/http_service.rb

@@ -2,6 +2,7 @@ require 'faraday'
 require 'koala/http_service/multipart_request'
 require 'koala/http_service/uploadable_io'
 require 'koala/http_service/response'
+require 'koala/http_service/request'
 
 module Koala
   module HTTPService
@@ -23,98 +24,46 @@ 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',
-      :rest_server => 'api.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'
     }
 
-    # The address of the appropriate Facebook server.
-    #
-    # @param options various flags to indicate which server to use.
-    # @option options :rest_api use the old REST API instead of the Graph API
-    # @option options :video use the server designated for video uploads
-    # @option options :beta use the beta tier
-    # @option options :use_ssl force https, even if not needed
-    #
-    # @return a complete server address with protocol
-    def self.server(options = {})
-      server = "#{options[:rest_api] ? Koala.config.rest_server : Koala.config.graph_server}"
-      server.gsub!(Koala.config.host_path_matcher, Koala.config.video_replace) if options[:video]
-      server.gsub!(Koala.config.host_path_matcher, Koala.config.beta_replace) if options[:beta]
-      "#{options[:use_ssl] ? "https" : "http"}://#{server}"
-    end
-
     # Makes a request directly to Facebook.
     # @note You'll rarely need to call this method directly.
     #
     # @see Koala::Facebook::API#api
     # @see Koala::Facebook::GraphAPIMethods#graph_call
-    # @see Koala::Facebook::RestAPIMethods#rest_call
     #
-    # @param path the server path for this request
-    # @param args (see Koala::Facebook::API#api)
-    # @param verb the HTTP method to use.
-    #             If not get or post, this will be turned into a POST request with the appropriate :method
-    #             specified in the arguments.
-    # @param options (see Koala::Facebook::API#api)
+    # @param request a Koala::HTTPService::Request object
     #
     # @raise an appropriate connection error if unable to make the request to Facebook
     #
     # @return [Koala::HTTPService::Response] a response object representing the results from Facebook
-    def self.make_request(path, args, verb, options = {})
-      # if the verb isn't get or post, send it as a post argument with a method param
-      args.merge!({:method => verb}) && verb = "post" if verb != "get" && verb != "post"
-
-      # turn all the keys to strings (Faraday has issues with symbols under 1.8.7) and resolve UploadableIOs
-      params = args.inject({}) {|hash, kv| hash[kv.first.to_s] = kv.last.is_a?(UploadableIO) ? kv.last.to_upload_io : kv.last; hash}
-
-      # figure out our options for this request
-      request_options = {:params => (verb == "get" ? params : {})}.merge(http_options || {}).merge(options)
-      request_options[:use_ssl] = true if args["access_token"] # require https if there's a token
-      if request_options[:use_ssl]
-        ssl = (request_options[:ssl] ||= {})
-        ssl[:verify] = true unless ssl.has_key?(:verify)
-      end
-
-      # if an api_version is specified and the path does not already contain
-      # one, prepend it to the path
-      api_version = request_options[:api_version] || Koala.config.api_version
-      if api_version && !path_contains_api_version?(path)
-        begins_with_slash = path[0] == "/"
-        divider = begins_with_slash ? "" : "/"
-        path = "/#{api_version}#{divider}#{path}"
-      end
-
+    def self.make_request(request)
       # set up our Faraday connection
-      # we have to manually assign params to the URL or the
-      conn = Faraday.new(server(request_options), faraday_options(request_options), &(faraday_middleware || DEFAULT_MIDDLEWARE))
+      conn = Faraday.new(request.server, faraday_options(request.options), &(faraday_middleware || DEFAULT_MIDDLEWARE))
 
-      # remember, all non-GET requests are turned into POSTs -- see the the start of this method
-      if verb == "post" && options[:format] == :json
+      if request.verb == "post" && request.json?
+        # JSON requires a bit more handling
+        # remember, all non-GET requests are turned into POSTs, so this covers everything but GETs
         response = conn.post do |req|
-          req.path = path
+          req.path = request.path
           req.headers["Content-Type"] = "application/json"
-          req.body = params.to_json
+          req.body = request.post_args.to_json
           req
         end
       else
-        response = conn.send(verb, path, (verb == "post" ? params : {}))
+        response = conn.send(request.verb, request.path, request.post_args)
       end
 
       # Log URL information
-      Koala::Utils.debug "#{verb.upcase}: #{path} params: #{params.inspect}"
+      Koala::Utils.debug "#{request.verb.upcase}: #{request.path} params: #{request.raw_args.inspect}"
       Koala::HTTPService::Response.new(response.status.to_i, response.body, response.headers)
     end
 
@@ -130,21 +79,14 @@ module Koala
     # @return the appropriately-encoded string
     def self.encode_params(param_hash)
       ((param_hash || {}).sort_by{|k, v| k.to_s}.collect do |key_and_value|
-        key_and_value[1] = JSON.dump(key_and_value[1]) unless key_and_value[1].is_a? String
-        "#{key_and_value[0].to_s}=#{CGI.escape key_and_value[1]}"
+        value = key_and_value[1]
+        unless value.is_a? String
+          value = value.to_json
+        end
+        "#{key_and_value[0].to_s}=#{CGI.escape value}"
       end).join("&")
     end
 
-    # Determines whether a given path already contains an API version.
-    #
-    # @param path the URL path.
-    #
-    # @return true or false accordingly.
-    def self.path_contains_api_version?(path)
-      match = /^\/?(v\d+(?:\.\d+)?)\//.match(path)
-      !!(match && match[1])
-    end
-
     private
 
     def self.faraday_options(options)

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.
@@ -134,7 +134,7 @@ module Koala
         if response == ''
           raise BadFacebookResponse.new(200, '', 'generate_client_code received an error: empty response body')
         else
-          result = JSON.load(response)
+          result = JSON.parse(response)
         end
 
         result.has_key?('code') ? result['code'] : raise(Koala::KoalaError.new("Facebook returned a valid response without the expected 'code' in the body (response = #{response})"))
@@ -240,7 +240,7 @@ module Koala
         raise OAuthSignatureError, 'Invalid (incomplete) signature data' unless encoded_sig && encoded_envelope
 
         signature = base64_url_decode(encoded_sig).unpack("H*").first
-        envelope = JSON.load(base64_url_decode(encoded_envelope))
+        envelope = JSON.parse(base64_url_decode(encoded_envelope))
 
         raise OAuthSignatureError, "Unsupported algorithm #{envelope['algorithm']}" if envelope['algorithm'] != 'HMAC-SHA256'
 
@@ -260,7 +260,7 @@ module Koala
       end
 
       def parse_access_token(response_text)
-        JSON.load(response_text)
+        JSON.parse(response_text)
       rescue JSON::ParserError
         response_text.split("&").inject({}) do |hash, bit|
           key, value = bit.split("=")

data/lib/koala/realtime_updates.rb

@@ -7,9 +7,6 @@ module Koala
       # @note: to subscribe to real-time updates, you must have an application access token
       #        or provide the app secret when initializing your RealtimeUpdates object.
 
-      # The application API interface used to communicate with Facebook.
-      # @return [Koala::Facebook::API]
-      attr_reader :api
       attr_reader :app_id, :app_access_token, :secret
 
       # Create a new RealtimeUpdates instance.
@@ -23,20 +20,27 @@ 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
+      end
 
-        # fetch the access token if we're provided a secret
-        if @secret && !@app_access_token
-          oauth = Koala::Facebook::OAuth.new(@app_id, @secret)
-          @app_access_token = oauth.get_app_access_token
-        end
+      # The app access token, either provided on initialization or fetched from Facebook using the
+      # app_id and secret.
+      def app_access_token
+        # If a token isn't provided but we need it, fetch it
+        @app_access_token ||= Koala::Facebook::OAuth.new(@app_id, @secret).get_app_access_token
+      end
 
-        @api = API.new(@app_access_token)
+      # The application API interface used to communicate with Facebook.
+      # @return [Koala::Facebook::API]
+      def api
+        # Only instantiate the API if needed. validate_update doesn't require it, so we shouldn't
+        # make an unnecessary request to get the app_access_token.
+        @api ||= API.new(app_access_token)
       end
 
       # Subscribe to realtime updates for certain fields on a given object (user, page, etc.).
@@ -60,7 +64,7 @@ module Koala
           :callback_url => callback_url,
         }.merge(verify_token ? {:verify_token => verify_token} : {})
         # a subscription is a success if Facebook returns a 200 (after hitting your server for verification)
-        @api.graph_call(subscription_path, args, 'post', options)
+        api.graph_call(subscription_path, args, 'post', options)
       end
 
       # Unsubscribe from updates for a particular object or from updates.
@@ -71,7 +75,7 @@ module Koala
       #
       # @raise A subclass of Koala::Facebook::APIError if the subscription request failed.
       def unsubscribe(object = nil, options = {})
-        @api.graph_call(subscription_path, object ? {:object => object} : {}, "delete", options)
+        api.graph_call(subscription_path, object ? {:object => object} : {}, "delete", options)
       end
 
       # List all active subscriptions for this application.
@@ -80,7 +84,7 @@ module Koala
       #
       # @return [Array] a list of active subscriptions
       def list_subscriptions(options = {})
-        @api.graph_call(subscription_path, {}, "get", options)
+        api.graph_call(subscription_path, {}, "get", options)
       end
 
       # As a security measure (to prevent DDoS attacks), Facebook sends a verification request to your server
@@ -129,12 +133,13 @@ module Koala
           raise AppSecretNotDefinedError, "You must init RealtimeUpdates with your app secret in order to validate updates"
         end
 
-        if request_signature = headers['X-Hub-Signature'] || headers['HTTP_X_HUB_SIGNATURE'] and
-           signature_parts = request_signature.split("sha1=")
-          request_signature = signature_parts[1]
-          calculated_signature = OpenSSL::HMAC.hexdigest('sha1', @secret, body)
-          calculated_signature == request_signature
-        end
+        request_signature = headers['X-Hub-Signature'] || headers['HTTP_X_HUB_SIGNATURE']
+        return unless request_signature
+
+        signature_parts = request_signature.split("sha1=")
+        request_signature = signature_parts[1]
+        calculated_signature = OpenSSL::HMAC.hexdigest('sha1', @secret, body)
+        calculated_signature == request_signature
       end
 
       # The Facebook subscription management URL for your application.

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
@@ -146,11 +146,12 @@ module Koala
           raise ArgumentError, "TestUsers#befriend requires hash arguments for both users with id and access_token"
         end
 
-        u1_graph_api = API.new(user1_token)
-        u2_graph_api = API.new(user2_token)
+        u1_graph_api = API.new(user1_token, secret)
+        u2_graph_api = API.new(user2_token, secret)
 
-        u1_graph_api.graph_call("#{user1_id}/friends/#{user2_id}", {}, "post", options) &&
-          u2_graph_api.graph_call("#{user2_id}/friends/#{user1_id}", {}, "post", options)
+        # if we have a secret token, flag that we want the appsecret_proof to be generated
+        u1_graph_api.graph_call("#{user1_id}/friends/#{user2_id}", {}, "post", options.merge(appsecret_proof: !!secret)) &&
+          u2_graph_api.graph_call("#{user2_id}/friends/#{user1_id}", {}, "post", options.merge(appsecret_proof: !!secret))
       end
 
       # Create a network of test users, all of whom are friends and have the same permissions.

data/lib/koala/version.rb

@@ -1,3 +1,3 @@
 module Koala
-  VERSION = "2.5.0"
+  VERSION = "3.0.0"
 end

data/lib/koala.rb

@@ -5,6 +5,7 @@ require 'json'
 # include koala modules
 require 'koala/errors'
 require 'koala/api'
+require 'koala/api/graph_batch_api'
 require 'koala/oauth'
 require 'koala/realtime_updates'
 require 'koala/test_users'
@@ -13,6 +14,7 @@ require 'koala/test_users'
 require 'koala/http_service'
 
 # miscellaneous
+require 'koala/configuration'
 require 'koala/utils'
 require 'koala/version'
 require 'ostruct'
@@ -36,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.
@@ -61,7 +59,7 @@ module Koala
 
   # An convenenient alias to Koala.http_service.make_request.
   def self.make_request(path, args, verb, options = {})
-    http_service.make_request(path, args, verb, options)
+    http_service.make_request(HTTPService::Request.new(path: path, args: args, verb: verb, options: options))
   end
 
   # we use Faraday as our main service, with mock as the other main one

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](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), 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,25 +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
 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 +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"
@@ -115,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
 -----------------
@@ -202,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:
@@ -225,14 +180,16 @@ For more information about meet_challenge and the RealtimeUpdates class, check o
 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
 -------------------
 
@@ -255,14 +212,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
 -------
@@ -280,26 +229,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.