koala 1.2.1 → 1.3.0rc2

data/lib/koala/http_service.rb

@@ -1,30 +1,37 @@
 require 'faraday'
+require 'koala/http_service/multipart_request'
+require 'koala/http_service/uploadable_io'
+require 'koala/http_service/response'
 
 module Koala
-  class Response
-    attr_reader :status, :body, :headers
-    def initialize(status, body, headers)
-      @status = status
-      @body = body
-      @headers = headers
-    end
-  end
-
-  module HTTPService
-    # common functionality for all HTTP services
-
+  module HTTPService    
     class << self
-      attr_accessor :faraday_middleware, :http_options
+      # A customized stack of Faraday middleware that will be used to make each request.
+      attr_accessor :faraday_middleware
+      # A default set of HTTP options (see https://github.com/arsduo/koala/wiki/HTTP-Services)
+      attr_accessor :http_options
     end
 
     @http_options ||= {}
     
+    # Koala's default middleware stack. 
+    # We encode requests in a Facebook-compatible multipart request, 
+    # and use whichever adapter has been configured for this application.
     DEFAULT_MIDDLEWARE = Proc.new do |builder|
-      builder.use Koala::MultipartRequest
+      builder.use Koala::HTTPService::MultipartRequest
       builder.request :url_encoded
       builder.adapter Faraday.default_adapter
     end
 
+    # 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] ? Facebook::REST_SERVER : Facebook::GRAPH_SERVER}"
       server.gsub!(/\.facebook/, "-video.facebook") if options[:video]
@@ -32,6 +39,23 @@ module Koala
       "#{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)
+    #
+    # @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
       args.merge!({:method => verb}) && verb = "post" if verb != "get" && verb != "post"
@@ -48,13 +72,20 @@ module Koala
       conn = Faraday.new(server(request_options), request_options, &(faraday_middleware || DEFAULT_MIDDLEWARE))
 
       response = conn.send(verb, path, (verb == "post" ? params : {}))
-      Koala::Response.new(response.status.to_i, response.body, response.headers)
-    end
-
+      Koala::HTTPService::Response.new(response.status.to_i, response.body, response.headers)
+    end
+
+    # Encodes a given hash into a query string.  
+    # This is used mainly by the Batch API nowadays, since Faraday handles this for regular cases.
+    # 
+    # @param params_hash a hash of values to CGI-encode and appropriately join
+    # 
+    # @example
+    #   Koala.http_service.encode_params({:a => 2, :b => "My String"})
+    #   => "a=2&b=My+String"
+    #
+    # @return the appropriately-encoded string
     def self.encode_params(param_hash)
-      # unfortunately, we can't use to_query because that's Rails, not Ruby
-      # if no hash (e.g. no auth token) return empty string
-      # this is used mainly by the Batch API nowadays
       ((param_hash || {}).collect do |key_and_value|
         key_and_value[1] = MultiJson.encode(key_and_value[1]) unless key_and_value[1].is_a? String
         "#{key_and_value[0].to_s}=#{CGI.escape key_and_value[1]}"
@@ -64,76 +95,92 @@ module Koala
     # deprecations
     # not elegant or compact code, but temporary
     
+    # @private
     def self.always_use_ssl
       Koala::Utils.deprecate("HTTPService.always_use_ssl is now HTTPService.http_options[:use_ssl]; always_use_ssl will be removed in a future version.")
       http_options[:use_ssl]
     end
 
+    # @private
     def self.always_use_ssl=(value)
       Koala::Utils.deprecate("HTTPService.always_use_ssl is now HTTPService.http_options[:use_ssl]; always_use_ssl will be removed in a future version.")
       http_options[:use_ssl] = value
     end
     
+    # @private
     def self.timeout
       Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
       http_options[:timeout]
     end
 
+    # @private
     def self.timeout=(value)
       Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
       http_options[:timeout] = value
     end
     
+    # @private
     def self.timeout
       Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
       http_options[:timeout]
     end
 
+    # @private
     def self.timeout=(value)
       Koala::Utils.deprecate("HTTPService.timeout is now HTTPService.http_options[:timeout]; .timeout will be removed in a future version.")
       http_options[:timeout] = value
     end
     
+    # @private
     def self.proxy
       Koala::Utils.deprecate("HTTPService.proxy is now HTTPService.http_options[:proxy]; .proxy will be removed in a future version.")
       http_options[:proxy]
     end
 
+    # @private
     def self.proxy=(value)
       Koala::Utils.deprecate("HTTPService.proxy is now HTTPService.http_options[:proxy]; .proxy will be removed in a future version.")
       http_options[:proxy] = value
     end
     
+    # @private
     def self.ca_path
       Koala::Utils.deprecate("HTTPService.ca_path is now (HTTPService.http_options[:ssl] ||= {})[:ca_path]; .ca_path will be removed in a future version.")
       (http_options[:ssl] || {})[:ca_path]
     end
 
+    # @private
     def self.ca_path=(value)
       Koala::Utils.deprecate("HTTPService.ca_path is now (HTTPService.http_options[:ssl] ||= {})[:ca_path]; .ca_path will be removed in a future version.")
       (http_options[:ssl] ||= {})[:ca_path] = value
     end
     
+    # @private
     def self.ca_file
       Koala::Utils.deprecate("HTTPService.ca_file is now (HTTPService.http_options[:ssl] ||= {})[:ca_file]; .ca_file will be removed in a future version.")
       (http_options[:ssl] || {})[:ca_file]
     end
 
+    # @private
     def self.ca_file=(value)
       Koala::Utils.deprecate("HTTPService.ca_file is now (HTTPService.http_options[:ssl] ||= {})[:ca_file]; .ca_file will be removed in a future version.")
       (http_options[:ssl] ||= {})[:ca_file] = value
     end
 
+    # @private
     def self.verify_mode
       Koala::Utils.deprecate("HTTPService.verify_mode is now (HTTPService.http_options[:ssl] ||= {})[:verify_mode]; .verify_mode will be removed in a future version.")
       (http_options[:ssl] || {})[:verify_mode]
     end
 
+    # @private
     def self.verify_mode=(value)
       Koala::Utils.deprecate("HTTPService.verify_mode is now (HTTPService.http_options[:ssl] ||= {})[:verify_mode]; .verify_mode will be removed in a future version.")
       (http_options[:ssl] ||= {})[:verify_mode] = value
     end
 
+    private 
+    
     def self.process_options(options)
       if typhoeus_options = options.delete(:typhoeus_options)
         Koala::Utils.deprecate("typhoeus_options should now be included directly in the http_options hash.  Support for this key will be removed in a future version.")
@@ -159,6 +206,7 @@ module Koala
     end   
   end
   
+  # @private
   module TyphoeusService
     def self.deprecated_interface
       # support old-style interface with a warning
@@ -167,6 +215,7 @@ module Koala
     end
   end
 
+  # @private
   module NetHTTPService
     def self.deprecated_interface
       # support old-style interface with a warning

data/lib/koala/oauth.rb

@@ -1,22 +1,37 @@
+# OpenSSL and Base64 are required to support signed_request
+require 'openssl'
+require 'base64'
+
 module Koala
   module Facebook
+    
+    DIALOG_HOST = "www.facebook.com"
+    
     class OAuth
       attr_reader :app_id, :app_secret, :oauth_callback_url
+      
+      # Creates a new OAuth client.
+      #
+      # @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
       end
-
+      
+      # Parses the cookie set Facebook's JavaScript SDK.
+      #
+      # @note in parsing Facebook's new signed cookie format this method has to make a request to Facebook.
+      #       We recommend storing authenticated user info in your Rails session (or equivalent) and only
+      #       calling this when needed.
+      #
+      # @param cookie_hash a set of cookies that includes the Facebook cookie.  
+      #                     You can pass Rack/Rails/Sinatra's cookie hash directly to this method.
+      #
+      # @return the authenticated user's information as a hash, or nil.
       def get_user_info_from_cookie(cookie_hash)
-        # 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.
-
         if signed_cookie = cookie_hash["fbsr_#{@app_id}"]
           parse_signed_cookie(signed_cookie)
         elsif unsigned_cookie = cookie_hash["fbs_#{@app_id}"]
@@ -25,6 +40,13 @@ module Koala
       end
       alias_method :get_user_info_from_cookies, :get_user_info_from_cookie
 
+      # Parses the cookie set Facebook's JavaScript SDK and returns only the user ID.
+      #
+      # @note (see #get_user_info_from_cookie)
+      #
+      # @param (see #get_user_info_from_cookie)
+      #
+      # @return the authenticated user's Facebook ID, or nil.
       def get_user_from_cookie(cookies)
         if info = get_user_info_from_cookies(cookies)
           # signed cookie has user_id, unsigned cookie has uid
@@ -34,33 +56,106 @@ module Koala
       alias_method :get_user_from_cookies, :get_user_from_cookie
 
       # URLs
-
+      
+      # Builds an OAuth URL, where users will be prompted to log in and for any desired permissions.
+      # When the users log in, you receive a callback with their   
+      # See http://developers.facebook.com/docs/authentication/.
+      #
+      # @see #url_for_access_token
+      #
+      # @note The server-side authentication and dialog methods should only be used 
+      #       if your application can't use the Facebook Javascript SDK,
+      #       which provides a much better user experience.
+      #       See http://developers.facebook.com/docs/reference/javascript/.
+      #
+      # @param options any query values to add to the URL, as well as any special/required values listed below.
+      # @option options permissions an array or comma-separated string of desired permissions
+      # 
+      # @raise ArgumentError if no OAuth callback was specified in OAuth#new or in options as :redirect_uri
+      #
+      # @return an OAuth URL you can send your users to
       def url_for_oauth_code(options = {})
         # for permissions, see http://developers.facebook.com/docs/authentication/permissions
-        permissions = options[:permissions]
-        scope = permissions ? "&scope=#{permissions.is_a?(Array) ? permissions.join(",") : permissions}" : ""
-        display = options.has_key?(:display) ? "&display=#{options[:display]}" : ""
-
-        callback = options[:callback] || @oauth_callback_url
-        raise ArgumentError, "url_for_oauth_code must get a callback either from the OAuth object or in the options!" unless callback
-
+        if permissions = options.delete(:permissions)
+          options[:scope] = permissions.is_a?(Array) ? permissions.join(",") : permissions
+        end
+        url_options = {:client_id => @app_id}.merge(options)
+        
         # Creates the URL for oauth authorization for a given callback and optional set of permissions
-        "https://#{GRAPH_SERVER}/oauth/authorize?client_id=#{@app_id}&redirect_uri=#{callback}#{scope}#{display}"
+        build_url("https://#{GRAPH_SERVER}/oauth/authorize", true, url_options)
       end
 
+      # Once you receive an OAuth code, you need to redeem it from Facebook using an appropriate URL.
+      # (This is done by your server behind the scenes.)
+      # See http://developers.facebook.com/docs/authentication/.
+      # 
+      # @see #url_for_oauth_code
+      # 
+      # @note (see #url_for_oauth_code)
+      #
+      # @param code an OAuth code received from Facebook
+      # @param options any additional query parameters to add to the URL
+      #
+      # @raise (see #url_for_oauth_code)
+      #
+      # @return an URL your server can query for the user's access token
       def url_for_access_token(code, options = {})
         # Creates the URL for the token corresponding to a given code generated by Facebook
-        callback = options[:callback] || @oauth_callback_url
-        raise ArgumentError, "url_for_access_token must get a callback either from the OAuth object or in the parameters!" unless callback
-        "https://#{GRAPH_SERVER}/oauth/access_token?client_id=#{@app_id}&redirect_uri=#{callback}&client_secret=#{@app_secret}&code=#{code}"
+        url_options = {
+          :client_id => @app_id, 
+          :code => code,
+          :client_secret => @app_secret
+        }.merge(options)
+        build_url("https://#{GRAPH_SERVER}/oauth/access_token", true, url_options)
       end
 
+      # Builds a URL for a given dialog (feed, friends, OAuth, pay, send, etc.)
+      # See http://developers.facebook.com/docs/reference/dialogs/.
+      # 
+      # @note (see #url_for_oauth_code)
+      #
+      # @param dialog_type the kind of Facebook dialog you want to show
+      # @param options any additional query parameters to add to the URL
+      #
+      # @return an URL your server can query for the user's access token
+      def url_for_dialog(dialog_type, options = {})
+        # some endpoints require app_id, some client_id, supply both doesn't seem to hurt
+        url_options = {:app_id => @app_id, :client_id => @app_id}.merge(options)        
+        build_url("http://#{DIALOG_HOST}/dialog/#{dialog_type}", true, url_options)
+      end
+      
+      # access tokens
+      
+      # Fetches an access token, token expiration, and other info from Facebook.
+      # Useful when you've received an OAuth code using the server-side authentication process.
+      # @see url_for_oauth_code
+      #
+      # @note (see #url_for_oauth_code)
+      # 
+      # @param code (see #url_for_access_token)
+      # @param options any additional parameters to send to Facebook when redeeming the token
+      # 
+      # @raise Koala::Facebook::APIError if Facebook returns an error response 
+      # 
+      # @return a hash of the access token info returned by Facebook (token, expiration, etc.) 
       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 => options[:redirect_uri] || @oauth_callback_url}, false, options)
       end
 
+      
+      # Fetches the access token (ignoring expiration and other info) from Facebook.
+      # Useful when you've received an OAuth code using the server-side authentication process.
+      # @see get_access_token_info
+      # 
+      # @note (see #url_for_oauth_code)
+      # 
+      # @param (see #get_access_token_info)
+      #
+      # @raise (see #get_access_token_info)
+      #
+      # @return the access token
       def get_access_token(code, options = {})
         # upstream methods will throw errors if needed
         if info = get_access_token_info(code, options)
@@ -68,22 +163,36 @@ module Koala
         end
       end
 
+      # Fetches the application's access token, along with any other information provided by Facebook.
+      # See http://developers.facebook.com/docs/authentication/ (search for App Login).
+      # 
+      # @param options any additional parameters to send to Facebook when redeeming the token
+      #
+      # @return the application access token and other information (expiration, etc.)
       def get_app_access_token_info(options = {})
         # convenience method to get a the application's sessionless access token
         get_token_from_server({:type => 'client_cred'}, true, options)
       end
 
+      # Fetches the application's access token (ignoring expiration and other info).
+      # @see get_app_access_token_info
+      # 
+      # @param (see #get_app_access_token_info)
+      #
+      # @return the application access token
       def get_app_access_token(options = {})
         if info = get_app_access_token_info(options)
           string = info["access_token"]
         end
       end
 
-      # Originally provided directly by Facebook, however this has changed
-      # as their concept of crypto changed. For historic purposes, this is their proposal:
-      # https://developers.facebook.com/docs/authentication/canvas/encryption_proposal/
-      # Currently see https://github.com/facebook/php-sdk/blob/master/src/facebook.php#L758
-      # for a more accurate reference implementation strategy.
+      # Parses a signed request string provided by Facebook to canvas apps or in a secure cookie.
+      #
+      # @param input the signed request from Facebook
+      # 
+      # @raise RuntimeError if the signature is incomplete, invalid, or using an unsupported algorithm
+      # 
+      # @return a hash of the validated request information 
       def parse_signed_request(input)
         encoded_sig, encoded_envelope = input.split('.', 2)
         raise 'SignedRequest: Invalid (incomplete) signature data' unless encoded_sig && encoded_envelope
@@ -100,8 +209,12 @@ module Koala
         envelope
       end
 
-      # from session keys
+      # Old session key code
+      
+      # @deprecated Facebook no longer provides session keys.
       def get_token_info_from_session_keys(sessions, options = {})
+        Koala::Utils.deprecate("Facebook no longer provides session keys. The relevant OAuth methods will be removed in the next release.")
+
         # fetch the OAuth tokens from Facebook
         response = fetch_token_string({
           :type => 'client_cred',
@@ -119,6 +232,7 @@ module Koala
         MultiJson.decode(response)
       end
 
+      # @deprecated (see #get_token_info_from_session_keys)
       def get_tokens_from_session_keys(sessions, options = {})
         # get the original hash results
         results = get_token_info_from_session_keys(sessions, options)
@@ -126,6 +240,7 @@ module Koala
         results.collect { |r| r ? r["access_token"] : nil }
       end
 
+      # @deprecated (see #get_token_info_from_session_keys)
       def get_token_from_session_key(session, options = {})
         # convenience method for a single key
         # gets the overlaoded strings automatically
@@ -189,6 +304,14 @@ module Koala
         str += '=' * (4 - str.length.modulo(4))
         Base64.decode64(str.tr('-_', '+/'))
       end
+      
+      def build_url(base, require_redirect_uri = false, url_options = {})
+        if require_redirect_uri && !(url_options[:redirect_uri] ||= url_options.delete(:callback) || @oauth_callback_url)          
+          raise ArgumentError, "url_for_dialog must get a callback either from the OAuth object or in the parameters!"
+        end
+        
+        "#{base}?#{Koala::HTTPService.encode_params(url_options)}"
+      end
     end
   end
 end

data/lib/koala/realtime_updates.rb

@@ -1,36 +1,27 @@
 module Koala
   module Facebook
-    module RealtimeUpdateMethods
-      # note: to subscribe to real-time updates, you must have an application access token
+    class RealtimeUpdates
+      # Manage realtime callbacks for changes to users' information.
+      # See http://developers.facebook.com/docs/reference/api/realtime.
+      #
+      # @note: to subscribe to real-time updates, you must have an application access token
+      #        or provide the app secret when initializing your RealtimeUpdates object.
 
-      def self.included(base)
-        # make the attributes readable
-        base.class_eval do
-          attr_reader :api, :app_id, :app_access_token, :secret
-
-          # parses the challenge params and makes sure the call is legitimate
-          # returns the challenge string to be sent back to facebook if true
-          # returns false otherwise
-          # this is a class method, since you don't need to know anything about the app
-          # saves a potential trip fetching the app access token
-          def self.meet_challenge(params, verify_token = nil, &verification_block)
-            if params["hub.mode"] == "subscribe" &&
-                # you can make sure this is legitimate through two ways
-                # if your store the token across the calls, you can pass in the token value
-                # and we'll make sure it matches
-                (verify_token && params["hub.verify_token"] == verify_token) ||
-                # alternately, if you sent a specially-constructed value (such as a hash of various secret values)
-                # you can pass in a block, which we'll call with the verify_token sent by Facebook
-                # if it's legit, return anything that evaluates to true; otherwise, return nil or false
-                (verification_block && yield(params["hub.verify_token"]))
-              params["hub.challenge"]
-            else
-              false
-            end
-          end
-        end
-      end
+      # 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.  
+      # If you don't have your app's access token, provide the app's secret and 
+      # Koala will make a request to Facebook for the appropriate token.
+      # 
+      # @param options initialization options.
+      # @option options :app_id the application's ID.
+      # @option options :app_access_token an application access token, if known.
+      # @option options :secret the application's secret.  
+      #
+      # @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]
@@ -45,45 +36,92 @@ module Koala
           @app_access_token = oauth.get_app_access_token
         end
 
-        @graph_api = API.new(@app_access_token)
+        @api = API.new(@app_access_token)
       end
 
-      # subscribes for realtime updates
-      # your callback_url must be set up to handle the verification request or the subscription will not be set up
-      # http://developers.facebook.com/docs/api/realtime
-      def subscribe(object, fields, callback_url, verify_token)
+      # Subscribe to realtime updates for certain fields on a given object (user, page, etc.).  
+      # See {http://developers.facebook.com/docs/reference/api/realtime the realtime updates documentation}
+      # for more information on what objects and fields you can register for.
+      #
+      # @note Your callback_url must be set up to handle the verification request or the subscription will not be set up.
+      #
+      # @param object a Facebook ID (name or number)
+      # @param fields the fields you want your app to be updated about
+      # @param callback_url the URL Facebook should ping when an update is available
+      # @param verify_token a token included in the verification request, allowing you to ensure the call is genuine 
+      #                     (see the docs for more information)
+      # @param options (see Koala::HTTPService.make_request)
+      #
+      # @return true if successful, false (or an APIError) otherwise.
+      def subscribe(object, fields, callback_url, verify_token, options = {})
         args = {
           :object => object,
           :fields => fields,
           :callback_url => callback_url,
-          :verify_token => verify_token
-        }
+        }.merge(verify_token ? {:verify_token => verify_token} : {})
         # a subscription is a success if Facebook returns a 200 (after hitting your server for verification)
-        @graph_api.graph_call(subscription_path, args, 'post', :http_component => :status) == 200
+        @api.graph_call(subscription_path, args, 'post', options.merge(:http_component => :status)) == 200
       end
 
-      # removes subscription for object
-      # if object is nil, it will remove all subscriptions
-      def unsubscribe(object = nil)
-        args = {}
-        args[:object] = object if object
-        @graph_api.graph_call(subscription_path, args, 'delete', :http_component => :status) == 200
+      # Unsubscribe from updates for a particular object or from updates. 
+      #
+      # @param object the object whose subscriptions to delete. 
+      #               If no object is provided, all subscriptions will be removed.
+      # @param options (see Koala::HTTPService.make_request)
+      #
+      # @return true if the unsubscription is successful, false (or an APIError) otherwise.
+      def unsubscribe(object = nil, options = {})
+        @api.graph_call(subscription_path, object ? {:object => object} : {}, "delete", options.merge(:http_component => :status)) == 200
       end
 
-      def list_subscriptions
-        @graph_api.graph_call(subscription_path)
+      # List all active subscriptions for this application.
+      # 
+      # @param options (see Koala::HTTPService.make_request) 
+      #
+      # @return [Array] a list of active subscriptions
+      def list_subscriptions(options = {})
+        @api.graph_call(subscription_path, {}, "get", options)
       end
 
-      def graph_api
-        Koala::Utils.deprecate("the TestUsers.graph_api accessor is deprecated and will be removed in a future version; please use .api instead.")
-        @api
+      # As a security measure (to prevent DDoS attacks), Facebook sends a verification request to your server
+      # after you request a subscription.
+      # This method parses the challenge params and makes sure the call is legitimate.
+      #
+      # @param params the request parameters sent by Facebook.  (You can pass in a Rails params hash.)
+      # @param verify_token the verify token sent in the {#subscribe subscription request}, if you provided one
+      # 
+      # @yield verify_token if you need to compute the verification token
+      #                     (for instance, if your callback URL includes a record ID, which you look up
+      #                     and use to calculate a hash), you can pass meet_challenge a block, which 
+      #                     will receive the verify_token received back from Facebook.
+      # 
+      # @return the challenge string to be sent back to Facebook, or false if the request is invalid.
+      def self.meet_challenge(params, verify_token = nil, &verification_block)
+        if params["hub.mode"] == "subscribe" &&
+            # you can make sure this is legitimate through two ways
+            # if your store the token across the calls, you can pass in the token value
+            # and we'll make sure it matches
+            (verify_token && params["hub.verify_token"] == verify_token) ||
+            # alternately, if you sent a specially-constructed value (such as a hash of various secret values)
+            # you can pass in a block, which we'll call with the verify_token sent by Facebook
+            # if it's legit, return anything that evaluates to true; otherwise, return nil or false
+            (verification_block && yield(params["hub.verify_token"]))
+          params["hub.challenge"]
+        else
+          false
+        end
       end
-
-      protected
-
+      
+      # The Facebook subscription management URL for your application.
       def subscription_path
         @subscription_path ||= "#{@app_id}/subscriptions"
       end
+      
+      # @private
+      def graph_api
+        Koala::Utils.deprecate("the TestUsers.graph_api accessor is deprecated and will be removed in a future version; please use .api instead.")
+        @api
+      end
     end
   end
 end