koala 0.4 → 3.7.0

data/lib/koala.rb

@@ -1,307 +1,67 @@
-require 'cgi'
+# useful tools
 require 'digest/md5'
-
-# rubygems is required to support json, how facebook returns data
-require 'rubygems'
 require 'json'
 
-# include default http services
-require 'http_services'
+# 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'
 
-module Koala
-  # Ruby client library for the Facebook Platform.
-  # Copyright 2010 Facebook
-  # Adapted from the Python library by Alex Koppel, Rafi Jacoby, and the team at Context Optional
-  #
-  # Licensed under the Apache License, Version 2.0 (the "License"); you may
-  # not use this file except in compliance with the License. You may obtain
-  # a copy of the License at
-  #     http://www.apache.org/licenses/LICENSE-2.0
-  #
-  # Unless required by applicable law or agreed to in writing, software
-  # distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
-  # WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the
-  # License for the specific language governing permissions and limitations
-  # under the License.
-  # 
-  # This client library is designed to support the Graph API and the official
-  # Facebook JavaScript SDK, which is the canonical way to implement
-  # Facebook authentication. Read more about the Graph API at
-  # http://developers.facebook.com/docs/api. You can download the Facebook
-  # JavaScript SDK at http://github.com/facebook/connect-js/.
+# HTTP module so we can communicate with Facebook
+require 'koala/http_service'
 
-  FACEBOOK_GRAPH_SERVER = "graph.facebook.com"
+# miscellaneous
+require 'koala/configuration'
+require 'koala/utils'
+require 'koala/version'
+require 'ostruct'
 
-  class GraphAPI
-    # A client for the Facebook Graph API.
-    # 
-    # See http://developers.facebook.com/docs/api for complete documentation
-    # for the API.
-    # 
-    # The Graph API is made up of the objects in Facebook (e.g., people, pages,
-    # events, photos) and the connections between them (e.g., friends,
-    # photo tags, and event RSVPs). This client provides access to those
-    # primitive types in a generic way. For example, given an OAuth access
-    # token, this will fetch the profile of the active user and the list
-    # of the user's friends:
-    # 
-    #    graph = Facebook::GraphAPI.new(access_token)
-    #    user = graph.get_object("me")
-    #    friends = graph.get_connections(user["id"], "friends")
-    # 
-    # You can see a list of all of the objects and connections supported
-    # by the API at http://developers.facebook.com/docs/reference/api/.
-    # 
-    # You can obtain an access token via OAuth or by using the Facebook
-    # JavaScript SDK. See http://developers.facebook.com/docs/authentication/
-    # for details.
-    # 
-    # If you are using the JavaScript SDK, you can use the
-    # Facebook::get_user_from_cookie() method below to get the OAuth access token
-    # for the active user from the cookie saved by the SDK.
-            
-    # initialize with an access token 
-    def initialize(access_token = nil)
-      @access_token = access_token
-    end
-    
-    def get_object(id, args = {})
-      # Fetchs the given object from the graph.
-      request(id, args)
-    end
-    
-    def get_objects(ids, args = {})
-      # Fetchs all of the given object from the graph.
-      # We return a map from ID to object. If any of the IDs are invalid,
-      # we raise an exception.
-      request("", args.merge("ids" => ids.join(",")))
-    end
-    
-    def get_connections(id, connection_name, args = {})
-      # Fetchs the connections for given object.
-      request("#{id}/#{connection_name}", args)
-    end
-    
-    def put_object(parent_object, connection_name, args = {})
-      # Writes the given object to the graph, connected to the given parent.
-      # 
-      # For example,
-      # 
-      #     graph.put_object("me", "feed", :message => "Hello, world")
-      # 
-      # writes "Hello, world" to the active user's wall. Likewise, this
-      # will comment on a the first post of the active user's feed:
-      # 
-      #     feed = graph.get_connections("me", "feed")
-      #     post = feed["data"][0]
-      #     graph.put_object(post["id"], "comments", :message => "First!")
-      # 
-      # See http://developers.facebook.com/docs/api#publishing for all of
-      # the supported writeable objects.
-      # 
-      # Most write operations require extended permissions. For example,
-      # publishing wall posts requires the "publish_stream" permission. See
-      # http://developers.facebook.com/docs/authentication/ for details about
-      # extended permissions.
+module Koala
+  # A Ruby client library for the Facebook Platform.
+  # See http://github.com/arsduo/koala/wiki for a general introduction to Koala
+  # and the Graph API.
 
-      raise GraphAPIError.new(nil, "Write operations require an access token") unless @access_token
-      request("#{parent_object}/#{connection_name}", args, "post")
-    end
-    
-    def put_wall_post(message, attachment = {}, profile_id = "me")
-      # Writes a wall post to the given profile's wall.
-      # 
-      # We default to writing to the authenticated user's wall if no
-      # profile_id is specified.
-      # 
-      # attachment adds a structured attachment to the status message being
-      # posted to the Wall. It should be a dictionary of the form:
-      # 
-      #     {"name": "Link name"
-      #      "link": "http://www.example.com/",
-      #      "caption": "{*actor*} posted a new review",
-      #      "description": "This is a longer description of the attachment",
-      #      "picture": "http://www.example.com/thumbnail.jpg"}
+  # Making HTTP requests
+  class << self
+    # Control which HTTP service framework Koala uses.
+    # Primarily used to switch between the mock-request framework used in testing
+    # and the live framework used in real life (and live testing).
+    # In theory, you could write your own HTTPService module if you need different functionality,
+    # but since the switch to {https://github.com/arsduo/koala/wiki/HTTP-Services Faraday} almost all such goals can be accomplished with middleware.
+    attr_accessor :http_service
 
-      self.put_object(profile_id, "feed", attachment.merge({:message => message}))
-    end
-    
-    def put_comment(object_id, message)
-      # Writes the given comment on the given post.
-      self.put_object(object_id, "comments", {:message => message})
-    end
-    
-    def put_like(object_id)
-      # Likes the given post.
-      self.put_object(object_id, "likes")
+    def configure
+      yield config
     end
-    
-    def delete_object(id)
-      # Deletes the object with the given ID from the graph.
-      request(id, {}, "delete")
-    end
-    
-    def search(search_terms, args = {})
-      # Searches for a given term
-      request("search", args.merge({:q => search_terms}))
-    end
-    
-    def request(path, args = {}, verb = "get")
-      # Fetches the given path in the Graph API.
-      args["access_token"] = @access_token if @access_token
-        
-      # make the request via the provided service
-      result = make_request(path, args, verb)
-      
-      # Facebook sometimes sends results like "true" and "false", which aren't strictly object
-      # and cause JSON.parse to fail
-      # so we account for that
-      response = JSON.parse("[#{result}]")[0]
 
-      # check for errors
-      if response.is_a?(Hash) && error = response["error"]
-        raise GraphAPIError.new(error["code"], error["message"])
-      end
-      
-      response
-    end
-    
-    # set up the http service used to make requests
-    # you can use your own (for HTTParty, etc.) by calling Koala::API.http_service = YourModule
-    def self.http_service=(service)
-      self.send(:include, service)
+    # Allows you to control various Koala configuration options.
+    # NOTE: this is not currently threadsafe.
+    # See Koala::Configuration.
+    def config
+      @config ||= Configuration.new
     end
-    
-    # by default, try requiring Typhoeus -- if that works, use it
-    begin
-      require 'typhoeus'
-      Koala::GraphAPI.http_service = TyphoeusService
-    rescue LoadError
-      Koala::GraphAPI.http_service = NetHTTPService
-    end
-  end
-  
-  class GraphAPIError < Exception
-    attr_accessor :code
-    def initialize(code, message)
-      super(message)
-      self.code = code  
+
+    # Used for testing.
+    def reset_config
+      @config = nil
     end
   end
-  
-  class OAuth    
-    def initialize(app_id, app_secret, oauth_callback_url = nil)
-      @app_id = app_id
-      @app_secret = app_secret
-      @oauth_callback_url = oauth_callback_url 
-    end
-    
-    def get_user_from_cookie(cookie_hash)
-      # Parses the cookie set by the official Facebook JavaScript SDK.
-      # 
-      # cookies should be a dictionary-like object mapping cookie names to
-      # cookie values.
-      # 
-      # If the user is logged in via Facebook, we return a dictionary with the
-      # keys "uid" and "access_token". The former is the user's Facebook ID,
-      # and the latter can be used to make authenticated requests to the Graph API.
-      # If the user is not logged in, we return None.
-      # 
-      # Download the official Facebook JavaScript SDK at
-      # http://github.com/facebook/connect-js/. Read more about Facebook
-      # authentication at http://developers.facebook.com/docs/authentication/.
-
-      if fb_cookie = cookie_hash["fbs_" + @app_id.to_s]
-        # remove the opening/closing quote
-        fb_cookie = fb_cookie.gsub(/\"/, "")
-
-        # since we no longer get individual cookies, we have to separate out the components ourselves
-        components = {}
-        fb_cookie.split("&").map {|param| param = param.split("="); components[param[0]] = param[1]}
-
-        auth_string = components.keys.sort.collect {|a| a == "sig" ? nil : "#{a}=#{components[a]}"}.reject {|a| a.nil?}.join("")
-        sig = Digest::MD5.hexdigest(auth_string + @app_secret)
 
-        sig == components["sig"] && Time.now.to_i < components["expires"].to_i ? components : nil
-      end
-    end
-    
-    def url_for_oauth_code(options = {})
-      callback = options[:callback] || @oauth_callback_url
-      permissions = options[:permissions]
-      scope = permissions ? "&scope=#{permissions.is_a?(Array) ? permissions.join(",") : permissions}" : ""
+  # @private
+  # Switch the HTTP service -- mostly used for testing.
+  def self.http_service=(service)
+    # if it's a real http_service, use it
+    @http_service = service
+  end
 
-      # Creates the URL for oauth authorization for a given callback and optional set of permissions
-      "https://#{FACEBOOK_GRAPH_SERVER}/oauth/authorize?client_id=#{@app_id}&redirect_uri=#{callback}#{scope}"    
-    end
-        
-    def url_for_access_token(code, callback = @oauth_callback_url)
-      # Creates the URL for the token corresponding to a given code generated by Facebook
-      "https://#{FACEBOOK_GRAPH_SERVER}/oauth/access_token?client_id=#{@app_id}&redirect_uri=#{callback}&client_secret=#{@app_secret}&code=#{code}"
-    end
-    
-    # for more details and up to date information, see http://developers.facebook.com/docs/authentication/permissions
-    def self.all_permissions
-      USER_PERMISSIONS.concat(FRIEND_PERMISSIONS)
-    end
-    
-    USER_PERMISSIONS = [
-      # PUBLISHING
-      "publish_stream", # Enables your application to post content, comments, and likes to a user's stream and to the streams of the user's friends, without prompting the user each time.
-      "create_event", # Enables your application to create and modify events on the user's behalf
-      "rsvp_event", # Enables your application to RSVP to events on the user's behalf
-      "sms", # Enables your application to send messages to the user and respond to messages from the user via text message
-      "offline_access", # Enables your application to perform authorized requests on behalf of the user at any time (e.g. permanent access token)
-      
-      # DATA ACCESS
-      "email", # Provides access to the user's primary email address in the email  property
-      "read_stream", # Provides access to all the posts in the user's News Feed and enables your application to perform searches against the user's News Feed
-      "user_about_me", # Provides access to the "About Me" section of the profile in the about property
-      "user_activities", # Provides access to the user's list of activities as the activities connection
-      "user_birthday", # Provides access to the full birthday with year as the birthday_date property
-      "user_education_history", # Provides access to education history as the education property
-      "user_events", # Provides access to the list of events the user is attending as the events connection
-      "user_groups", # Provides access to the list of groups the user is a member of as the groups connection
-      "user_hometown", # Provides access to the user's hometown in the hometown property
-      "user_interests", # Provides access to the user's list of interests as the interests connection
-      "user_likes", # Provides access to the list of all of the pages the user has liked as the likes connection
-      "user_location", # Provides access to the user's current location as the current_location property
-      "user_notes", # Provides access to the user's notes as the notes connection
-      "user_online_presence", # Provides access to the user's online/offline presence
-      "user_photo_video_tags", # Provides access to the photos the user has been tagged in as the photos connection
-      "user_photos", # Provides access to the photos the user has uploaded
-      "user_relationships", # Provides access to the user's family and personal relationships and relationship status
-      "user_religion_politics", # Provides access to the user's religious and political affiliations
-      "user_status", # Provides access to the user's most recent status message
-      "user_videos", # Provides access to the videos the user has uploaded
-      "user_website", # Provides access to the user's web site URL
-      "user_work_history", # Provides access to work history as the work property
-      "read_friendlists", # Provides read access to the user's friend lists
-      "read_requests" # Provides read access to the user's friend requests
-    ]
-    
-    FRIEND_PERMISSIONS = [
-      # DATA ACCESS
-      "friends_about_me", # Provides access to the "About Me" section of the profile in the about property
-      "friends_activities", # Provides access to the user's list of activities as the activities connection
-      "friends_birthday", # Provides access to the full birthday with year as the birthday_date property
-      "friends_education_history", # Provides access to education history as the education property
-      "friends_events", # Provides access to the list of events the user is attending as the events connection
-      "friends_groups", # Provides access to the list of groups the user is a member of as the groups connection
-      "friends_hometown", # Provides access to the user's hometown in the hometown property
-      "friends_interests", # Provides access to the user's list of interests as the interests connection
-      "friends_likes", # Provides access to the list of all of the pages the user has liked as the likes connection
-      "friends_location", # Provides access to the user's current location as the current_location property
-      "friends_notes", # Provides access to the user's notes as the notes connection
-      "friends_online_presence", # Provides access to the user's online/offline presence
-      "friends_photo_video_tags", # Provides access to the photos the user has been tagged in as the photos connection
-      "friends_photos", # Provides access to the photos the user has uploaded
-      "friends_relationships", # Provides access to the user's family and personal relationships and relationship status
-      "friends_religion_politics", # Provides access to the user's religious and political affiliations
-      "friends_status", # Provides access to the user's most recent status message
-      "friends_videos", # Provides access to the videos the user has uploaded
-      "friends_website", # Provides access to the user's web site URL
-      "friends_work_history" # Provides access to work history as the work property
-    ]
+  # An convenenient alias to Koala.http_service.make_request.
+  def self.make_request(path, args, verb, options = {})
+    http_service.make_request(HTTPService::Request.new(path: path, args: args, verb: verb, options: options))
   end
-end
+
+  # we use Faraday as our main service, with mock as the other main one
+  self.http_service = HTTPService
+end

data/readme.md

@@ -1,29 +1,277 @@
-Facebook Graph
+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 Marketing API, the Atlas API, realtime updates, test users, and OAuth validation.  We wrote Koala with four goals:
 
-This Ruby client library is designed to support the
-[Facebook Graph API](http://developers.facebook.com/docs/api) and the official
-[Facebook JavaScript SDK](http://github.com/facebook/connect-js), which is
-the canonical way to implement Facebook authentication. You can read more
-about the Graph API at [http://developers.facebook.com/docs/api](http://developers.facebook.com/docs/api).
+* 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 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/).
 
-Basic usage:
+**Found a bug? Interested in contributing?** Check out the Maintenance section below!
 
-    graph = Facebook::GraphAPI.new(oauth_access_token)
-    profile = graph.get_object("me")
-    friends = graph.get_connections("me", "friends")
-    graph.put_object("me", "feed", :message => "I am writing on my wall!")
+Installation
+------------
 
-If you are using the module within a web application with the
-[JavaScript SDK](http://github.com/facebook/connect-js), you can also use the
-module to use Facebook for login, parsing the cookie set by the JavaScript SDK
-for logged in users.
+**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.
 
-Testing
+In Bundler:
+```ruby
+gem "koala"
+```
+
+Otherwise:
+```bash
+[sudo|rvm] gem install koala
+```
+
+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
+```
+
+**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 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'
+
+# 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")
+@graph.put_connections("me", "feed", message: "I am writing on my wall!")
+
+# Three-part queries are easy too!
+@graph.get_connections("me", "mutualfriends/#{friend_id}")
+
+# You can use the Timeline API:
+# (see https://developers.facebook.com/docs/beta/opengraph/tutorial/)
+@graph.put_connections("me", "namespace:action", object: object_url)
+
+# 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 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(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.
+# See https://developers.facebook.com/docs/apps/versions for more information.
+#
+# You can specify version either globally:
+Koala.config.api_version = "v2.0"
+# or on a per-request basis
+@graph.get_object("me", {}, api_version: "v2.0")
+```
+
+The response of most requests is the JSON data returned from the Facebook servers as a Hash.
+
+When retrieving data that returns an array of results (for example, when calling `API#get_connections` or `API#search`)
+a GraphCollection object will be returned, which makes it easy to page through the results:
+
+```ruby
+# Returns the feed items for the currently logged-in user as a GraphCollection
+feed = @graph.get_connections("me", "feed")
+feed.each {|f| do_something_with_item(f) } # it's a subclass of Array
+next_feed = feed.next_page
+
+# You can also get an array describing the URL for the next page: [path, arguments]
+# This is useful for storing page state across multiple browser requests
+next_page_params = feed.next_page_params
+page = @graph.get_page(next_page_params)
+```
+
+You can also make multiple calls at once using Facebook's batch API:
+```ruby
+# Returns an array of results as if they were called non-batch
+@graph.batch do |batch_api|
+  batch_api.get_object('me')
+  batch_api.put_wall_post('Making a post in a batch.')
+end
+```
+
+You can pass a "post-processing" block to each of Koala's Graph API methods. This is handy for two reasons:
+
+1. You can modify the result returned by the Graph API method:
+
+        education = @graph.get_object("me") { |data| data['education'] }
+        # returned value only contains the "education" portion of the profile
+
+2. You can consume the data in place which is particularly useful in the batch case, so you don't have to pull
+the results apart from a long list of array entries:
+
+        @graph.batch do |batch_api|
+          # Assuming you have database fields "about_me" and "photos"
+          batch_api.get_object('me')                {|me|     self.about_me = me }
+          batch_api.get_connections('me', 'photos') {|photos| self.photos   = photos }
+        end
+
+Check out the wiki for more details and examples.
+
+App Access Tokens
 -----
 
-Unit tests are provided for Graph API methods.  However, because the Graph API uses access tokens, which expire, you have to provide your own token with stream publishing permissions for the tests.  Insert the token value into the file test/facebook_data.yml, then run the test as follows:
-    spec facebook_tests.rb
-    
-Unit tests for cookie validation will be provided shortly.  (You'll also need to add that information into the yml.)
-    
+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)
+@oauth.get_app_access_token
+```
+For those building apps on Facebook, parsing signed requests is simple:
+```ruby
+@oauth.parse_signed_request(signed_request_string)
+```
+
+The OAuth class has additional methods that may occasionally be useful.
+
+Real-time Updates
+-----------------
+
+Sometimes, reaching out to Facebook is a pain -- let it reach out to you instead.  The Graph API allows your application to subscribe to real-time updates for certain objects in the graph; check the [official Facebook documentation](http://developers.facebook.com/docs/api/realtime) for more details on what objects you can subscribe to and what limitations may apply.
+
+Koala makes it easy to interact with your applications using the RealtimeUpdates class:
+```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:
+```ruby
+# Add/modify a subscription to updates for when the first_name or last_name fields of any of your users is changed
+@updates.subscribe("user", "first_name, last_name", callback_url, verify_token)
+
+# Get an array of your current subscriptions (one hash for each object you've subscribed to)
+@updates.list_subscriptions
+
+# Unsubscribe from updates for an object
+@updates.unsubscribe("user")
+```
+And to top it all off, RealtimeUpdates provides a static method to respond to Facebook servers' verification of your callback URLs:
+```ruby
+# Returns the hub.challenge parameter in params if the verify token in params matches verify_token
+Koala::Facebook::RealtimeUpdates.meet_challenge(params, your_verify_token)
+```
+For more information about meet_challenge and the RealtimeUpdates class, check out the Real-Time Updates page on the wiki.
+
+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 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
+-------------------
+
+Koala uses Faraday to make HTTP requests, which means you have complete control over how your app makes HTTP requests to Facebook.  You can set Faraday options globally or pass them in on a per-request (or both):
+```ruby
+# Set an SSL certificate to avoid Net::HTTP errors
+Koala.http_service.http_options = {
+  ssl: { ca_path: "/etc/ssl/certs" }
+}
+# or on a per-request basis
+@api.get_object(id, args_hash, { request: { timeout: 10 } })
+```
+The <a href="https://github.com/arsduo/koala/wiki/HTTP-Services">HTTP Services wiki page</a> has more information on what options are available, as well as on how to configure your own Faraday middleware stack (for instance, to implement request logging).
+
+See examples, ask questions
+---------------------------
+
+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
+
+Testing
+-------
+
+Unit tests are provided for all of Koala's methods.  By default, these tests run against mock responses and hence are ready out of the box:
+```bash
+# From anywhere in the project directory:
+bundle exec rake spec
+```
+
+You can also run live tests against Facebook's servers:
+```bash
+# Again from anywhere in the project directory:
+LIVE=true bundle exec rake spec
+# you can also test against Facebook's beta tier
+LIVE=true BETA=true bundle exec rake spec
+```
+
+By default, the live tests are run against test users, so you can run them as frequently as you want.  If you want to run them against a real user, however, you can fill in the OAuth token, code, and access\_token values in spec/fixtures/facebook_data.yml.  See the wiki for more details.
+
+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!
+
+_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.