koala 1.2.0beta1 → 1.2.1

data/CHANGELOG

@@ -1,11 +1,34 @@
+v1.2.1
+New methods:
+-- RestAPI.set_app_properties handles JSON-encoding application properties
+Updated methods:
+-- OAuth.get_user_from_cookie works with the new signed cookie format (thanks, gmccreight!)
+-- Beta server URLs are now correct
+-- OAuth.parse_signed_request now raises an informative error if the signed_request is malformed
+Internal improvements:
+-- Koala::Multipart middleware properly encoding nested parameters (hashes) in POSTs
+-- Updated readme, changelog, etc.
+Testing improvements:
+-- Live tests with test users now clean up all fake users they create
+-- Removed duplicate test cases
+-- Live tests with test users no longer delete each object they create, speeding things up
+
 v1.2
 New methods:
 -- API is now the main API class, contains both Graph and REST methods
   -- Old classes are aliased with deprecation warnings (non-breaking change)
 -- TestUsers#update lets you update the name or password of an existing test user
 -- API.get_page_access_token lets you easily fetch the access token for a page you manage (thanks, marcgg!)
+-- Added version.rb (Koala::VERSION)
 Updated methods:
+-- OAuth now parses Facebook's new signed cookie format
 -- API.put_picture now accepts URLs to images (thanks, marcgg!)
+-- Bug fixes to put_picture, parse_signed_request, and the test suite (thanks, johnbhall and Will S.!)
+-- Smarter GraphCollection use
+  -- Any pageable result will now become a GraphCollection
+  -- Non-pageable results from get_connections no longer error
+  -- GraphCollection.raw_results allows access to original result data
+-- Koala no longer enforces any limits on the number of test users you create at once
 Internal improvements:
 -- Koala now uses Faraday to make requests, replacing the HTTPServices (see wiki)
   -- Koala::HTTPService.http_options allows specification of default Faraday connection options
@@ -15,13 +38,15 @@ Internal improvements:
   -- Koala no longer automatically switches to Net::HTTP when uploading IO objects to Facebook
 -- RealTimeUpdates and TestUsers are no longer subclasses of API, but have their own .api objects
   -- The old .graph_api accessor is aliases to .api with a deprecation warning
+-- Removed deprecation warnings for pre-1.1 batch interface
 Testing improvements:
 -- Live test suites now run against test users by default
   -- Test suite can be repeatedly run live without having to update facebook_data.yml
   -- OAuth code and session key tests cannot be run against test users
--- Faraday adapter for live tests can be specified with ADAPTER=[your adapter] in the shell command
+-- Faraday adapter for live tests can be specified with ADAPTER=[your adapter] in the rspec command
+-- Live tests can be run against the beta server by specifying BETA=true in the rspec command
 -- Tests now pass against all rubies on Travis CI
--- Expanded test coverage
+-- Expanded and refactored test coverage
 -- Fixed bug with YAML parsing in Ruby 1.9
 
 v1.1

data/koala.gemspec

@@ -1,9 +1,11 @@
 # -*- encoding: utf-8 -*-
+$LOAD_PATH.unshift File.expand_path("../lib", __FILE__)
+require 'koala/version'
 
 Gem::Specification.new do |s|
   s.name    = %q{koala}
-  s.version = "1.2.0beta1"
-  s.date    = %q{2011-08-17}
+  s.version = Koala::VERSION
+  s.date    = %q{2011-10-04}
 
   s.summary     = %q{A lightweight, flexible library for Facebook with support for the Graph API, the REST API, realtime updates, and OAuth authentication.}
   s.description = %q{Koala is a lightweight, flexible Ruby SDK for Facebook.  It allows read/write access to the social graph via the Graph and REST APIs, as well as support for realtime updates and OAuth and Facebook Connect authentication.  Koala is fully tested and supports Net::HTTP and Typhoeus connections out of the box and can accept custom modules for other services.}
@@ -29,22 +31,19 @@ Gem::Specification.new do |s|
 
     if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<multi_json>,      ["~> 1.0"])
-      s.add_runtime_dependency(%q<faraday>,  ["~> 0.7.4"])
-      s.add_runtime_dependency(%q<faraday-stack>,  ["~> 0.1.3"])
+      s.add_runtime_dependency(%q<faraday>,  ["~> 0.7.0"])
       s.add_development_dependency(%q<rspec>,     ["~> 2.5"])
       s.add_development_dependency(%q<rake>,      ["~> 0.8.7"])
     else
       s.add_dependency(%q<multi_json>,      ["~> 1.0"])
       s.add_dependency(%q<rspec>,     ["~> 2.5"])
       s.add_dependency(%q<rake>,      ["~> 0.8.7"])
-      s.add_dependency(%q<faraday>,  ["~> 0.7.4"])
-      s.add_dependency(%q<faraday-stack>,  ["~> 0.1.3"])
+      s.add_dependency(%q<faraday>,  ["~> 0.7.0"])
     end
   else
     s.add_dependency(%q<multi_json>,      ["~> 1.0"])
     s.add_dependency(%q<rspec>,     ["~> 2.5"])
     s.add_dependency(%q<rake>,      ["~> 0.8.7"])
-    s.add_dependency(%q<faraday>,  ["~> 0.7.4"])
-    s.add_dependency(%q<faraday-stack>,  ["~> 0.1.3"])
+    s.add_dependency(%q<faraday>,  ["~> 0.7.0"])
   end
 end

data/lib/koala/graph_api.rb

@@ -71,9 +71,7 @@ module Koala
 
       def get_connections(id, connection_name, args = {}, options = {})
         # Fetchs the connections for given object.
-        graph_call("#{id}/#{connection_name}", args, "get", options) do |result|
-          result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
-        end
+        graph_call("#{id}/#{connection_name}", args, "get", options)
       end
 
       def put_connections(id, connection_name, args = {}, options = {})
@@ -174,9 +172,7 @@ module Koala
 
       def search(search_terms, args = {}, options = {})
         args.merge!({:q => search_terms}) unless search_terms.nil?
-        graph_call("search", args, "get", options) do |result|
-          result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
-        end
+        graph_call("search", args, "get", options)
       end
 
       # Convenience Methods
@@ -199,14 +195,12 @@ module Koala
       def get_page(params)
         # Pages through a set of results stored in a GraphCollection
         # Used for connections and search results
-        graph_call(*params) do |result|
-          result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
-        end
+        graph_call(*params)
       end
 
       # Batch API
       def batch(http_options = {}, &block)
-        batch_client = GraphBatchAPI.new(access_token)
+        batch_client = GraphBatchAPI.new(access_token, self)
         if block
           yield batch_client
           batch_client.execute(http_options)
@@ -214,15 +208,7 @@ module Koala
           batch_client
         end
       end
-
-      def self.included(base)
-        base.class_eval do
-          def self.batch
-            raise NoMethodError, "The BatchAPI signature has changed (the original implementation was not thread-safe).  Please see https://github.com/arsduo/koala/wiki/Batch-requests.  (This message will be removed in the final 1.1 release.)"
-          end
-        end
-      end
-
+      
       # Direct access to the Facebook API
       # see any of the above methods for example invocations
       def graph_call(path, args = {}, verb = "get", options = {}, &post_processing)
@@ -231,10 +217,15 @@ module Koala
           raise error if error
         end
 
-        # now process as appropriate (get picture header, make GraphCollection, etc.)
+        # turn this into a GraphCollection if it's pageable
+        result = GraphCollection.evaluate(result, self)
+        
+        # now process as appropriate for the given call (get picture header, etc.)
         post_processing ? post_processing.call(result) : result
       end
 
+      private
+      
       def check_response(response)
         # check for Graph API-specific errors
         # this returns an error, which is immediately raised (non-batch)
@@ -244,8 +235,6 @@ module Koala
         end
       end
 
-      private
-
       def parse_media_args(media_args, method)
         # photo and video uploads can accept different types of arguments (see above)
         # so here, we parse the arguments into a form directly usable in put_object

data/lib/koala/graph_batch_api.rb

@@ -4,6 +4,13 @@ module Koala
 
       def self.included(base)
         base.class_eval do
+          attr_reader :original_api
+          
+          def initialize(access_token, api)
+            super(access_token)
+            @original_api = api
+          end
+
           alias_method :graph_call_outside_batch, :graph_call
           alias_method :graph_call, :graph_call_in_batch
 
@@ -46,7 +53,7 @@ module Koala
           batch_op.to_batch_params(access_token)
         })
 
-        graph_call_outside_batch('/', args, 'post', http_options) do |response|
+        batch_result = graph_call_outside_batch('/', args, 'post', http_options) do |response|
           # map the results with post-processing included
           index = 0 # keep compat with ruby 1.8 - no with_index for map
           response.map do |call_result|
@@ -80,6 +87,9 @@ module Koala
             end
           end
         end
+        
+        # turn any results that are pageable into GraphCollections
+        batch_result.inject([]) {|processed_results, raw| processed_results << GraphCollection.evaluate(raw, @original_api)}
       end
 
     end

data/lib/koala/graph_collection.rb

@@ -10,12 +10,17 @@ module Koala
       # It also allows access to paging information and the
       # ability to get the next/previous page in the collection
       # by calling next_page or previous_page.
-      attr_reader :paging
-      attr_reader :api
+      attr_reader :paging, :api, :raw_response
 
+      def self.evaluate(response, api)
+        # turn the response into a GraphCollection if it's pageable; if not, return the original response
+        response.is_a?(Hash) && response["data"].is_a?(Array) ? self.new(response, api) : response
+      end
+    
       def initialize(response, api)
         super response["data"]
         @paging = response["paging"]
+        @raw_response = response
         @api = api
       end
 

data/lib/koala/http_service.rb

@@ -1,5 +1,4 @@
 require 'faraday'
-require 'faraday_stack'
 
 module Koala
   class Response
@@ -21,7 +20,7 @@ module Koala
     @http_options ||= {}
     
     DEFAULT_MIDDLEWARE = Proc.new do |builder|
-      builder.request :multipart
+      builder.use Koala::MultipartRequest
       builder.request :url_encoded
       builder.adapter Faraday.default_adapter
     end
@@ -29,7 +28,8 @@ module Koala
     def self.server(options = {})
       server = "#{options[:rest_api] ? Facebook::REST_SERVER : Facebook::GRAPH_SERVER}"
       server.gsub!(/\.facebook/, "-video.facebook") if options[:video]
-      "#{options[:use_ssl] ? "https" : "http"}://#{options[:beta] ? "beta." : ""}#{server}"
+      server.gsub!(/\.facebook/, ".beta.facebook") if options[:beta]
+      "#{options[:use_ssl] ? "https" : "http"}://#{server}"
     end
 
     def self.make_request(path, args, verb, options = {})

data/lib/koala/multipart_request.rb

@@ -0,0 +1,35 @@
+require 'faraday'
+
+module Koala
+  class MultipartRequest < Faraday::Request::Multipart
+    # Facebook expects nested parameters to be passed in a certain way
+    # Based on our testing (https://github.com/arsduo/koala/issues/125),
+    # Faraday needs two changes to make that work:
+    # 1) [] need to be escaped (e.g. params[foo]=bar ==> params%5Bfoo%5D=bar)
+    # 2) such messages need to be multipart-encoded
+    
+    self.mime_type = 'multipart/form-data'.freeze
+    
+    def process_request?(env)
+      # if the request values contain any hashes or arrays, multipart it
+      super || !!(env[:body].respond_to?(:values) && env[:body].values.find {|v| v.is_a?(Hash) || v.is_a?(Array)})
+    end   
+    
+    
+    def process_params(params, prefix = nil, pieces = nil, &block)
+      params.inject(pieces || []) do |all, (key, value)|
+        key = "#{prefix}%5B#{key}%5D" if prefix
+
+        case value
+        when Array
+          values = value.inject([]) { |a,v| a << [nil, v] }
+          process_params(values, key, all, &block)
+        when Hash
+          process_params(value, key, all, &block)
+        else
+          all << block.call(key, value)
+        end
+      end
+    end
+  end
+end

data/lib/koala/oauth.rb

@@ -9,38 +9,26 @@ module Koala
       end
 
       def get_user_info_from_cookie(cookie_hash)
-        # Parses the cookie set by the official Facebook JavaScript SDK.
-        #
-        # cookies should be a Hash, like the one Rails provides
+        # Parses the cookie set Facebook's JavaScript SDK.
+        # You can pass Rack/Rails/Sinatra's cookie hash directly to this method.
         #
         # If the user is logged in via Facebook, we return a dictionary with the
         # keys "uid" and "access_token". The former is the user's Facebook ID,
         # and the latter can be used to make authenticated requests to the Graph API.
         # If the user is not logged in, we return None.
-        #
-        # Download the official Facebook JavaScript SDK at
-        # http://github.com/facebook/connect-js/. Read more about Facebook
-        # authentication at http://developers.facebook.com/docs/authentication/.
-
-        if fb_cookie = cookie_hash["fbs_" + @app_id.to_s]
-          # remove the opening/closing quote
-          fb_cookie = fb_cookie.gsub(/\"/, "")
-
-          # since we no longer get individual cookies, we have to separate out the components ourselves
-          components = {}
-          fb_cookie.split("&").map {|param| param = param.split("="); components[param[0]] = param[1]}
-
-          # generate the signature and make sure it matches what we expect
-          auth_string = components.keys.sort.collect {|a| a == "sig" ? nil : "#{a}=#{components[a]}"}.reject {|a| a.nil?}.join("")
-          sig = Digest::MD5.hexdigest(auth_string + @app_secret)
-          sig == components["sig"] && (components["expires"] == "0" || Time.now.to_i < components["expires"].to_i) ? components : nil
+
+        if signed_cookie = cookie_hash["fbsr_#{@app_id}"]
+          parse_signed_cookie(signed_cookie)
+        elsif unsigned_cookie = cookie_hash["fbs_#{@app_id}"]
+          parse_unsigned_cookie(unsigned_cookie)
         end
       end
       alias_method :get_user_info_from_cookies, :get_user_info_from_cookie
 
       def get_user_from_cookie(cookies)
         if info = get_user_info_from_cookies(cookies)
-          string = info["uid"]
+          # signed cookie has user_id, unsigned cookie has uid
+          string = info["user_id"] || info["uid"]
         end
       end
       alias_method :get_user_from_cookies, :get_user_from_cookie
@@ -70,7 +58,7 @@ module Koala
       def get_access_token_info(code, options = {})
         # convenience method to get a parsed token from Facebook for a given code
         # should this require an OAuth callback URL?
-        get_token_from_server({:code => code, :redirect_uri => @oauth_callback_url}, false, options)
+        get_token_from_server({:code => code, :redirect_uri => options[:redirect_uri] || @oauth_callback_url}, false, options)
       end
 
       def get_access_token(code, options = {})
@@ -98,16 +86,18 @@ module Koala
       # for a more accurate reference implementation strategy.
       def parse_signed_request(input)
         encoded_sig, encoded_envelope = input.split('.', 2)
+        raise 'SignedRequest: Invalid (incomplete) signature data' unless encoded_sig && encoded_envelope
+
         signature = base64_url_decode(encoded_sig).unpack("H*").first
         envelope = MultiJson.decode(base64_url_decode(encoded_envelope))
 
         raise "SignedRequest: Unsupported algorithm #{envelope['algorithm']}" if envelope['algorithm'] != 'HMAC-SHA256'
 
         # now see if the signature is valid (digest, key, data)
-        hmac = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, @app_secret, encoded_envelope.tr("-_", "+/"))
+        hmac = OpenSSL::HMAC.hexdigest(OpenSSL::Digest::SHA256.new, @app_secret, encoded_envelope)
         raise 'SignedRequest: Invalid signature' if (signature != hmac)
 
-        return envelope
+        envelope
       end
 
       # from session keys
@@ -162,6 +152,29 @@ module Koala
         end
         components
       end
+      
+      def parse_unsigned_cookie(fb_cookie)
+        # remove the opening/closing quote
+        fb_cookie = fb_cookie.gsub(/\"/, "")
+
+        # since we no longer get individual cookies, we have to separate out the components ourselves
+        components = {}
+        fb_cookie.split("&").map {|param| param = param.split("="); components[param[0]] = param[1]}
+
+        # generate the signature and make sure it matches what we expect
+        auth_string = components.keys.sort.collect {|a| a == "sig" ? nil : "#{a}=#{components[a]}"}.reject {|a| a.nil?}.join("")
+        sig = Digest::MD5.hexdigest(auth_string + @app_secret)
+        sig == components["sig"] && (components["expires"] == "0" || Time.now.to_i < components["expires"].to_i) ? components : nil
+      end
+      
+      def parse_signed_cookie(fb_cookie)
+        components = parse_signed_request(fb_cookie)
+        if (code = components["code"]) && token_info = get_access_token_info(code, :redirect_uri => '')
+          components.merge(token_info)
+        else
+          nil
+        end
+      end
 
       def fetch_token_string(args, post = false, endpoint = "access_token", options = {})
         Koala.make_request("/oauth/#{endpoint}", {

data/lib/koala/realtime_updates.rb

@@ -71,7 +71,7 @@ module Koala
       end
 
       def list_subscriptions
-        @graph_api.graph_call(subscription_path)["data"]
+        @graph_api.graph_call(subscription_path)
       end
 
       def graph_api

data/lib/koala/rest_api.rb

@@ -13,6 +13,11 @@ module Koala
           results.inject({}) {|outcome, data| outcome[data["name"]] = data["fql_result_set"]; outcome}
         end
       end
+      
+      def set_app_properties(properties, args = {}, options = {})
+        raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "setAppProperties requires an access token"}) unless @access_token
+        rest_call("admin.setAppProperties", args.merge(:properties => MultiJson.encode(properties)), options, "post")
+      end
 
       def rest_call(fb_method, args = {}, options = {}, method = "get")
         options = options.merge!(:rest_api => true, :read_only => READ_ONLY_METHODS.include?(fb_method.to_s))

data/lib/koala/test_users.rb

@@ -31,11 +31,11 @@ module Koala
         # Creates and returns a test user
         args['installed'] = installed
         args['permissions'] = (permissions.is_a?(Array) ? permissions.join(",") : permissions) if installed
-        result = @api.graph_call(accounts_path, args, "post", options)
+        @api.graph_call(accounts_path, args, "post", options)
       end
 
       def list
-        @api.graph_call(accounts_path)["data"]
+        @api.graph_call(accounts_path)
       end
 
       def delete(test_user)
@@ -72,7 +72,6 @@ module Koala
       end
 
       def create_network(network_size, installed = true, permissions = '')
-        network_size = 50 if network_size > 50 # FB's max is 50
         users = (0...network_size).collect { create(installed, permissions) }
         friends = users.clone
         users.each do |user|

data/lib/koala/uploadable_io.rb

@@ -40,7 +40,8 @@ module Koala
       :parse_rails_3_param,
       :parse_sinatra_param,
       :parse_file_object,
-      :parse_string_path
+      :parse_string_path,
+      :parse_io
     ]
 
     def parse_init_mixed_param(mixed, content_type = nil)

data/lib/koala/version.rb

@@ -0,0 +1,3 @@
+module Koala
+  VERSION = "1.2.1"
+end

data/lib/koala.rb

@@ -8,7 +8,6 @@ require 'openssl'
 require 'base64'
 
 # include koala modules
-require 'koala/http_service'
 require 'koala/oauth'
 require 'koala/graph_api'
 require 'koala/graph_batch_api'
@@ -17,11 +16,18 @@ require 'koala/graph_collection'
 require 'koala/rest_api'
 require 'koala/realtime_updates'
 require 'koala/test_users'
-require 'koala/utils'
+
+# HTTP module so we can communicate with Facebook
+require 'koala/http_service'
+require 'koala/multipart_request'
 
 # add KoalaIO class
 require 'koala/uploadable_io'
 
+# miscellaneous
+require 'koala/utils'
+require 'koala/version'
+
 module Koala
 
   module Facebook

data/readme.md

@@ -9,28 +9,37 @@ Koala
 * Flexible: Koala should be useful to everyone, regardless of their current configuration.  (We support JRuby, Rubinius, and REE as well as vanilla Ruby, and use the Faraday library to provide complete flexibility over how HTTP requests are made.)
 * Tested: Koala should have complete test coverage, so you can rely on it.  (Our test coverage is complete and can be run against either mocked responses or the live Facebook servers.)
 
+Facebook Changes on October 1, 2011
+---
+
+Koala 1.2 supports all of Facebook's new authentication schemes, which were introduced on October 1, 2011.  If you have the appropriate calls to get_user_info_from_cookies (apps using the Javascript SDK) and/or parse_signed_params (for Canvas and tab apps), your application should work without a hitch.  For more information, see Facebook's [OAuth 2.0 and HTTPS Migration](https://developers.facebook.com/docs/oauth2-https-migration/) guide.  
+
 Installation
 ---
 
 Easy:
 
-    [sudo|rvm] gem install koala --pre # for 1.2 beta
-    [sudo|rvm] gem install koala # for 1.1
+    [sudo|rvm] gem install koala
 
 Or in Bundler:
 
-    gem "koala", "~> 1.2.0beta" 
-    gem "koala" # for 1.1 
+    gem "koala"
 
 Graph API
 ----
 The Graph API is the simple, slick new interface to Facebook's data.  Using it with Koala is quite straightforward:
-
+  
     @graph = Koala::Facebook::API.new(oauth_access_token)
+    # in 1.1 or earlier, use GraphAPI instead of API
+    
     profile = @graph.get_object("me")
     friends = @graph.get_connections("me", "friends")
     @graph.put_object("me", "feed", :message => "I am writing on my wall!")
 
+    # you can even use the new Timeline API
+    # see https://developers.facebook.com/docs/beta/opengraph/tutorial/
+    @graph.put_connections("me", "namespace:action", :object => object_url)
+
 The response of most requests is the JSON data returned from the Facebook servers as a Hash.
 
 When retrieving data that returns an array of results (for example, when calling API#get_connections or API#search) a GraphCollection object will be returned, which makes it easy to page through the results:
@@ -61,13 +70,18 @@ Where the Graph API and the old REST API overlap, you should choose the Graph AP
 
 Fortunately, Koala supports the REST API using the very same interface; to use this, instantiate an API:
 
-  	@rest = Koala::Facebook::API.new(oauth_access_token)
+    @rest = Koala::Facebook::API.new(oauth_access_token)
+    # in 1.1 or earlier, use RestAPI instead of API
+  	
   	@rest.fql_query(my_fql_query) # convenience method
   	@rest.fql_multiquery(fql_query_hash) # convenience method
   	@rest.rest_call("stream.publish", arguments_hash) # generic version
 
 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.
 
+    @api = Koala::Facebook::API.new(oauth_access_token)
+    # in 1.1 or earlier, use GraphAndRestAPI instead of API
+    
     @api = Koala::Facebook::API.new(oauth_access_token)
     fql = @api.fql_query(my_fql_query)
     @api.put_wall_post(process_result(fql))
@@ -76,25 +90,31 @@ Of course, you can use the Graph API methods on the same object -- the power of
 OAuth
 -----
 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:
+
     @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/connect-js) (formerly Facebook Connect), you can use the OAuth class to parse the cookies:
+
     @oauth.get_user_from_cookies(cookies) # gets the user's ID
 	  @oauth.get_user_info_from_cookies(cookies) # parses and returns the entire hash
 
 And if you have to use the more complicated [redirect-based OAuth process](http://developers.facebook.com/docs/authentication/), Koala helps out there, too:
+
 	  # generate authenticating URL
 	  @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:
+
     @oauth.get_app_access_token
 
 For those building apps on Facebook, parsing signed requests is simple:
-    @oauth.parse_signed_request(request)
+
+    @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:
+
     @oauth.get_token_from_session_key(session_key)
     @oauth.get_tokens_from_session_keys(array_of_session_keys)
 
@@ -137,12 +157,27 @@ We also support the test users API, allowing you to conjure up fake users and co
     # 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):
+
+    # 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, { :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="http://wiki.github.com/arsduo/koala/">on the wiki</a>
 * The <a href="http://groups.google.com/group/koala-users">Koala users group</a> on Google Groups, the place for your Koala and API questions
+* 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
 
 Testing
@@ -158,5 +193,7 @@ You can also run live tests against Facebook's servers:
 
     # 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.