tyler_koala 1.2.0beta

data/lib/koala/test_users.rb

@@ -0,0 +1,102 @@
+require 'koala'
+
+module Koala
+  module Facebook
+    module TestUserMethods
+
+      def self.included(base)
+        base.class_eval do
+          # make the Graph API accessible in case someone wants to make other calls to interact with their users
+          attr_reader :api, :app_id, :app_access_token, :secret
+        end
+      end
+
+      def initialize(options = {})
+        @app_id = options[:app_id]
+        @app_access_token = options[:app_access_token]
+        @secret = options[: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
+
+      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
+        result = @api.graph_call(accounts_path, args, "post", options)
+      end
+
+      def list
+        @api.graph_call(accounts_path)["data"]
+      end
+
+      def delete(test_user)
+        test_user = test_user["id"] if test_user.is_a?(Hash)
+        @api.delete_object(test_user)
+      end
+
+      def delete_all
+        list.each {|u| delete u}
+      end
+
+      def update(test_user, args = {}, http_options = {})
+        test_user = test_user["id"] if test_user.is_a?(Hash)
+        @api.graph_call(test_user, args, "post", http_options)
+      end
+
+      def befriend(user1_hash, user2_hash)
+        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)
+        u2_graph_api = API.new(user2_token)
+
+        u1_graph_api.graph_call("#{user1_id}/friends/#{user2_id}", {}, "post") &&
+          u2_graph_api.graph_call("#{user2_id}/friends/#{user1_id}", {}, "post")
+      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|
+          # Remove this user from list of friends
+          friends.delete_at(0)
+          # befriend all the others
+          friends.each do |friend|
+            befriend(user, friend)
+          end
+        end
+        return users
+      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
+      end
+
+      protected
+
+      def accounts_path
+        @accounts_path ||= "/#{@app_id}/accounts/test-users"
+      end
+
+    end # TestUserMethods
+  end # Facebook
+end # Koala

data/lib/koala/uploadable_io.rb

@@ -0,0 +1,180 @@
+require "net/http/post/multipart"
+
+module Koala
+  class UploadableIO
+    attr_reader :io_or_path, :content_type, :filename
+
+    def initialize(io_or_path_or_mixed, content_type = nil, filename = nil)
+      # see if we got the right inputs
+      parse_init_mixed_param io_or_path_or_mixed, content_type
+
+      # filename is used in the Ads API
+      # if it's provided, take precedence over the detected filename
+      # otherwise, fall back to a dummy name
+      @filename = filename || @filename || "koala-io-file.dum"
+
+      raise KoalaError.new("Invalid arguments to initialize an UploadableIO") unless @io_or_path
+      raise KoalaError.new("Unable to determine MIME type for UploadableIO") if !@content_type
+    end
+
+    def to_upload_io
+      UploadIO.new(@io_or_path, @content_type, @filename)
+    end
+
+    def to_file
+      @io_or_path.is_a?(String) ? File.open(@io_or_path) : @io_or_path
+    end
+
+    def self.binary_content?(content)
+      content.is_a?(UploadableIO) || DETECTION_STRATEGIES.detect {|method| send(method, content)}
+    end
+
+    private
+    DETECTION_STRATEGIES = [
+      :sinatra_param?,
+      :rails_3_param?,
+      :file_param?
+    ]
+
+    PARSE_STRATEGIES = [
+      :parse_rails_3_param,
+      :parse_sinatra_param,
+      :parse_file_object,
+      :parse_string_path
+    ]
+
+    def parse_init_mixed_param(mixed, content_type = nil)
+      PARSE_STRATEGIES.each do |method|
+        send(method, mixed, content_type)
+        return if @io_or_path && @content_type
+      end
+    end
+
+    # Expects a parameter of type ActionDispatch::Http::UploadedFile
+    def self.rails_3_param?(uploaded_file)
+      uploaded_file.respond_to?(:content_type) and uploaded_file.respond_to?(:tempfile) and uploaded_file.tempfile.respond_to?(:path)
+    end
+
+    def parse_rails_3_param(uploaded_file, content_type = nil)
+      if UploadableIO.rails_3_param?(uploaded_file)
+        @io_or_path = uploaded_file.tempfile.path
+        @content_type = content_type || uploaded_file.content_type
+        @filename = uploaded_file.original_filename
+      end
+    end
+
+    # Expects a Sinatra hash of file info
+    def self.sinatra_param?(file_hash)
+      file_hash.kind_of?(Hash) and file_hash.has_key?(:type) and file_hash.has_key?(:tempfile)
+    end
+
+    def parse_sinatra_param(file_hash, content_type = nil)
+      if UploadableIO.sinatra_param?(file_hash)
+        @io_or_path = file_hash[:tempfile]
+        @content_type = content_type || file_hash[:type] || detect_mime_type(tempfile)
+        @filename = file_hash[:filename]
+      end
+    end
+
+    # takes a file object
+    def self.file_param?(file)
+      file.kind_of?(File)
+    end
+
+    def parse_file_object(file, content_type = nil)
+      if UploadableIO.file_param?(file)
+        @io_or_path = file
+        @content_type = content_type || detect_mime_type(file.path)
+        @filename = File.basename(file.path)
+      end
+    end
+
+    def parse_string_path(path, content_type = nil)
+      if path.kind_of?(String)
+        @io_or_path = path
+        @content_type = content_type || detect_mime_type(path)
+        @filename = File.basename(path)
+      end
+    end
+
+    def parse_io(io, content_type = nil)
+      if io.respond_to?(:read)
+        @io_or_path = io
+        @content_type = content_type
+      end
+    end
+
+    MIME_TYPE_STRATEGIES = [
+      :use_mime_module,
+      :use_simple_detection
+    ]
+
+    def detect_mime_type(filename)
+      if filename
+        MIME_TYPE_STRATEGIES.each do |method|
+          result = send(method, filename)
+          return result if result
+        end
+      end
+      nil # if we can't find anything
+    end
+
+    def use_mime_module(filename)
+      # if the user has installed mime/types, we can use that
+      # if not, rescue and return nil
+      begin
+        type = MIME::Types.type_for(filename).first
+        type ? type.to_s : nil
+      rescue
+        nil
+      end
+    end
+
+    def use_simple_detection(filename)
+      # very rudimentary extension analysis for images
+      # first, get the downcased extension, or an empty string if it doesn't exist
+      extension = ((filename.match(/\.([a-zA-Z0-9]+)$/) || [])[1] || "").downcase
+      case extension
+        when ""
+          nil
+        # images
+        when "jpg", "jpeg"
+          "image/jpeg"
+        when "png"
+          "image/png"
+        when "gif"
+          "image/gif"
+
+        # video
+        when "3g2"
+        	"video/3gpp2"
+        when "3gp", "3gpp"
+        	"video/3gpp"
+        when "asf"
+        	"video/x-ms-asf"
+        when "avi"
+        	"video/x-msvideo"
+        when "flv"
+        	"video/x-flv"
+        when "m4v"
+        	"video/x-m4v"
+        when "mkv"
+        	"video/x-matroska"
+        when "mod"
+        	"video/mod"
+        when "mov", "qt"
+        	"video/quicktime"
+        when "mp4", "mpeg4"
+        	"video/mp4"
+        when "mpe", "mpeg", "mpg", "tod", "vob"
+        	"video/mpeg"
+        when "nsv"
+        	"application/x-winamp"
+        when "ogm", "ogv"
+        	"video/ogg"
+        when "wmv"
+        	"video/x-ms-wmv"
+      end
+    end
+  end
+end

data/lib/koala/utils.rb

@@ -0,0 +1,7 @@
+module Koala
+  module Utils
+    def self.deprecate(message)
+      send(:warn, "KOALA: Deprecation warning: #{message}")
+    end
+  end
+end

data/readme.md

@@ -0,0 +1,160 @@
+Koala
+====
+[Koala](http://github.com/arsduo/koala) is a Facebook library for Ruby, supporting the Graph API (including the batch requests and photo uploads), the REST API, realtime updates, test users, and OAuth validation.  We wrote Koala with four goals:
+
+* Lightweight: Koala should be as light and simple as Facebook’s own libraries, providing API accessors and returning simple JSON.
+* Fast: Koala should, out of the box, be quick. Out of the box, we use Facebook's faster read-only servers when possible and if available, the Typhoeus gem to make snappy Facebook requests.  Of course, that brings us to our next topic:
+* Flexible: Koala should be useful to everyone, regardless of their current configuration.  (We support JRuby, Rubinius, and REE as well as vanilla Ruby, 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.)
+
+Installation
+---
+
+Easy:
+
+    [sudo|rvm] gem install koala --pre # for 1.2 beta
+    [sudo|rvm] gem install koala # for 1.1
+
+Or in Bundler:
+
+    gem "koala", "~> 1.2.0beta" 
+    gem "koala" # for 1.1 
+
+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)
+    profile = @graph.get_object("me")
+    friends = @graph.get_connections("me", "friends")
+    @graph.put_object("me", "feed", :message => "I am writing on my wall!")
+
+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:
+
+    # 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:
+
+    # 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
+
+Check out the wiki for more details and examples.
+
+The REST API
+-----
+Where the Graph API and the old REST API overlap, you should choose the Graph API.  Unfortunately, that overlap is far from complete, and there are many important API calls that can't yet be done via the Graph.
+
+Fortunately, Koala supports the REST API using the very same interface; to use this, instantiate an API:
+
+  	@rest = Koala::Facebook::API.new(oauth_access_token)
+  	@rest.fql_query(my_fql_query) # convenience method
+  	@rest.fql_multiquery(fql_query_hash) # convenience method
+  	@rest.rest_call("stream.publish", arguments_hash) # generic version
+
+Of course, you can use the Graph API methods on the same object -- the power of two APIs right in the palm of your hand.
+
+    @api = Koala::Facebook::API.new(oauth_access_token)
+    fql = @api.fql_query(my_fql_query)
+    @api.put_wall_post(process_result(fql))
+    
+
+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)
+
+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)
+
+That's it!  It's pretty simple once you get the hang of it.  If you're new to OAuth, though, check out the wiki and the OAuth Playground example site (see below).
+
+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:
+
+    @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:
+
+    # 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_token, 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:
+
+    # 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.
+
+Test Users
+-----
+
+We also support the test users API, allowing you to conjure up fake users and command them to do your bidding using the Graph or REST API:
+
+    @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)
+
+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
+* 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
+-----
+
+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:
+
+    # From anywhere in the project directory:
+    bundle exec rake spec
+
+
+You can also run live tests against Facebook's servers:
+
+    # Again from anywhere in the project directory:
+    LIVE=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.