koala 0.4 → 3.7.0

data/lib/koala/realtime_updates.rb

@@ -0,0 +1,151 @@
+module Koala
+  module Facebook
+    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.
+
+      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] || 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
+
+      # 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
+
+      # 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.).
+      # 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)
+      #
+      # @raise A subclass of Koala::Facebook::APIError if the subscription request failed.
+      def subscribe(object, fields, callback_url, verify_token, options = {})
+        args = {
+          :object => object,
+          :fields => fields,
+          :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)
+      end
+
+      # 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)
+      #
+      # @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)
+      end
+
+      # 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
+
+      # 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
+
+      # Public: As a security measure, all updates from facebook are signed using
+      # X-Hub-Signature: sha1=XXXX where XXX is the sha1 of the json payload
+      # using your application secret as the key.
+      #
+      # Example:
+      #   # in Rails controller
+      #   # @oauth being a previously defined Koala::Facebook::OAuth instance
+      #   def receive_update
+      #     if @oauth.validate_update(request.body, headers)
+      #       ...
+      #     end
+      #   end
+      def validate_update(body, headers)
+        unless @secret
+          raise AppSecretNotDefinedError, "You must init RealtimeUpdates with your app secret in order to validate updates"
+        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.
+      def subscription_path
+        @subscription_path ||= "#{@app_id}/subscriptions"
+      end
+    end
+  end
+end

data/lib/koala/test_users.rb

@@ -0,0 +1,189 @@
+require 'koala'
+
+module Koala
+  module Facebook
+
+    # Create and manage test users for your application.
+    # A test user is a user account associated with an app created for the purpose
+    # of testing the functionality of that app.
+    # You can use test users for manual or automated testing --
+    # Koala's live test suite uses test users to verify the library works with Facebook.
+    #
+    # @note the test user API is fairly slow compared to other interfaces
+    #       (which makes sense -- it's creating whole new user accounts!).
+    #
+    # 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
+      attr_reader :app_id, :app_access_token, :secret
+
+      # Create a new TestUsers 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] || 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
+
+        # 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
+
+        @api = API.new(@app_access_token)
+      end
+
+      # Create a new test user.
+      #
+      # @param installed whether the user has installed your app
+      # @param permissions a comma-separated string or array of permissions the user has granted (if installed)
+      # @param args any additional arguments for the create call (name, etc.)
+      # @param options (see Koala::Facebook::API#api)
+      #
+      # @return a hash of information for the new user (id, access token, login URL, etc.)
+      def create(installed, permissions = nil, args = {}, options = {})
+        # Creates and returns a test user
+        args['installed'] = installed
+        args['permissions'] = (permissions.is_a?(Array) ? permissions.join(",") : permissions) if installed
+        @api.graph_call(test_user_accounts_path, args, "post", options)
+      end
+
+      # List all test users for the app.
+      #
+      # @param options (see Koala::Facebook::API#api)
+      #
+      # @return an array of hashes of user information (id, access token, etc.)
+      def list(options = {})
+        @api.graph_call(test_user_accounts_path, {}, "get", options)
+      end
+
+      # Delete a test user.
+      #
+      # @param test_user the user to delete; can be either a Facebook ID or the hash returned by {#create}
+      # @param options (see Koala::Facebook::API#api)
+      #
+      # @return true if successful, false (or an {Koala::Facebook::APIError APIError}) if not
+      def delete(test_user, options = {})
+        test_user = test_user["id"] if test_user.is_a?(Hash)
+        @api.delete_object(test_user, options)
+      end
+
+      # Deletes all test users in batches of 50.
+      #
+      # @note if you have a lot of test users (> 20), this operation can take a long time.
+      #
+      # @param options (see Koala::Facebook::API#api)
+      #
+      # @return a list of the test users that have been deleted
+      def delete_all(options = {})
+        # ideally we'd save a call by checking next_page_params, but at the time of writing
+        # Facebook isn't consistently returning full pages after the first one
+        previous_list = nil
+        while (test_user_list = list(options)).length > 0
+          # avoid infinite loops if Facebook returns buggy users you can't delete
+          # see http://developers.facebook.com/bugs/223629371047398
+          # since the hashes may change across calls, even if the IDs don't,
+          # we just compare the IDs.
+          test_user_ids = test_user_list.map {|u| u['id']}
+          previous_user_ids = (previous_list || []).map {|u| u['id']}
+          break if (test_user_ids - previous_user_ids).empty?
+
+          test_user_list.each_slice(50) do |users|
+            self.api.batch(options) {|batch_api| users.each {|u| batch_api.delete_object(u["id"]) }}
+          end
+
+          previous_list = test_user_list
+        end
+      end
+
+      # Updates a test user's attributes.
+      #
+      # @note currently, only name and password can be changed;
+      #       see {http://developers.facebook.com/docs/test_users/ the Facebook documentation}.
+      #
+      # @param test_user the user to update; can be either a Facebook ID or the hash returned by {#create}
+      # @param args the updates to make
+      # @param options (see Koala::Facebook::API#api)
+      #
+      # @return true if successful, false (or an {Koala::Facebook::APIError APIError}) if not
+      def update(test_user, args = {}, options = {})
+        test_user = test_user["id"] if test_user.is_a?(Hash)
+        @api.graph_call(test_user, args, "post", options)
+      end
+
+      # Make two test users friends.
+      #
+      # @note there's no way to unfriend test users; you can always just create a new one.
+      #
+      # @param user1_hash one of the users to friend; the hash must contain both ID and access token (as returned by {#create})
+      # @param user2_hash the other user to friend
+      # @param options (see Koala::Facebook::API#api)
+      #
+      # @return true if successful, false (or an {Koala::Facebook::APIError APIError}) if not
+      def befriend(user1_hash, user2_hash, options = {})
+        user1_id = user1_hash["id"] || user1_hash[:id]
+        user2_id = user2_hash["id"] || user2_hash[:id]
+        user1_token = user1_hash["access_token"] || user1_hash[:access_token]
+        user2_token = user2_hash["access_token"] || user2_hash[:access_token]
+        unless user1_id && user2_id && user1_token && user2_token
+          # we explicitly raise an error here to minimize the risk of confusing output
+          # if you pass in a string (as was previously supported) no local exception would be raised
+          # but the Facebook call would fail
+          raise ArgumentError, "TestUsers#befriend requires hash arguments for both users with id and access_token"
+        end
+
+        u1_graph_api = API.new(user1_token, secret)
+        u2_graph_api = API.new(user2_token, secret)
+
+        # 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.
+      #
+      # @note this call slows down dramatically the more users you create
+      #       (test user calls are slow, and more users => more 1-on-1 connections to be made).
+      #       Use carefully.
+      #
+      # @param network_size how many users to create
+      # @param installed whether the users have installed your app (see {#create})
+      # @param permissions what permissions the users have granted (see {#create})
+      # @param options (see Koala::Facebook::API#api)
+      #
+      # @return the list of users created
+      def create_network(network_size, installed = true, permissions = '', options = {})
+        users = (0...network_size).collect { create(installed, permissions, {}, options) }
+        friends = users.clone
+        users.each do |user|
+          # Remove this user from list of friends
+          friends.delete_at(0)
+          # befriend all the others
+          friends.each do |friend|
+            befriend(user, friend, options)
+          end
+        end
+        return users
+      end
+
+      # The Facebook test users management URL for your application.
+      def test_user_accounts_path
+        @test_user_accounts_path ||= "/#{@app_id}/accounts/test-users"
+      end
+    end # TestUserMethods
+  end # Facebook
+end # Koala

data/lib/koala/utils.rb

@@ -0,0 +1,41 @@
+module Koala
+  module Utils
+
+    # Utility methods used by Koala.
+    require 'logger'
+    require 'forwardable'
+
+    extend Forwardable
+    extend self
+
+    def_delegators :logger, :debug, :info, :warn, :error, :fatal, :level, :level=
+
+    # The Koala logger, an instance of the standard Ruby logger, pointing to STDOUT by default.
+    # In Rails projects, you can set this to Rails.logger.
+    attr_accessor :logger
+    self.logger = Logger.new(STDOUT)
+    self.logger.level = Logger::ERROR
+
+    # @private
+    DEPRECATION_PREFIX = "KOALA: Deprecation warning: "
+
+    # Prints a deprecation message.
+    # Each individual message will only be printed once to avoid spamming.
+    def deprecate(message)
+      @posted_deprecations ||= []
+      unless @posted_deprecations.include?(message)
+        # only include each message once
+        Kernel.warn("#{DEPRECATION_PREFIX}#{message}")
+        @posted_deprecations << message
+      end
+    end
+
+    # Ensures that a hash uses symbols as opposed to strings
+    # Useful for allowing either syntax for end users
+    def symbolize_hash(hash)
+      return hash unless hash.is_a?(Hash)
+
+      hash.inject({}){ |memo,(key,value)| memo[key.to_sym] = symbolize_hash(value); memo }
+    end
+  end
+end

data/lib/koala/version.rb

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