koala 1.1.0 → 1.2.0

data/.travis.yml

@@ -1,8 +1,9 @@
 rvm:
   - 1.8.7 # (current default)
   - 1.9.2
+  - 1.9.3
+  - ruby-head
   - rbx
   - rbx-2.0
   - ree
   - jruby
-  - ruby-head

data/CHANGELOG

@@ -1,3 +1,39 @@
+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
+  -- Koala::HTTPService.faraday_middleware allows custom middleware configurations
+  -- Koala now defaults to Net::HTTP rather than Typhoeus
+  -- Koala::NetHTTPService and Koala::TyphoeusService modules no longer exist
+  -- 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 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 and refactored test coverage
+-- Fixed bug with YAML parsing in Ruby 1.9
+
 v1.1
 New methods:
 -- Added Batch API support (thanks, seejohnrun and spiegela!)

data/Gemfile

@@ -1,7 +1,11 @@
 source :rubygems
 
-gemspec
+group :development, :test do
+  gem "typhoeus"
+end
 
 if defined? JRUBY_VERSION
   gem "jruby-openssl"
-end
+end
+
+gemspec

data/Rakefile

@@ -7,7 +7,6 @@ rescue LoadError
   puts 'although not required, bundler is recommened for running the tests'
 end
 
-
 task :default => :spec
 
 require 'rspec/core/rake_task'

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.1.0"
-  s.date    = %q{2011-07-18}
+  s.version = Koala::VERSION
+  s.date    = %q{2011-09-27}
 
   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<multipart-post>,  ["~> 1.0"])
+      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"])
-      s.add_development_dependency(%q<typhoeus>,  ["~> 0.2.4"])
     else
       s.add_dependency(%q<multi_json>,      ["~> 1.0"])
-      s.add_dependency(%q<multipart-post>,  ["~> 1.0"])
       s.add_dependency(%q<rspec>,     ["~> 2.5"])
       s.add_dependency(%q<rake>,      ["~> 0.8.7"])
-      s.add_dependency(%q<typhoeus>,  ["~> 0.2.4"])
+      s.add_dependency(%q<faraday>,  ["~> 0.7.0"])
     end
   else
     s.add_dependency(%q<multi_json>,      ["~> 1.0"])
-    s.add_dependency(%q<multipart-post>,  ["~> 1.0"])
     s.add_dependency(%q<rspec>,     ["~> 2.5"])
     s.add_dependency(%q<rake>,      ["~> 0.8.7"])
-    s.add_dependency(%q<typhoeus>,  ["~> 0.2.4"])
+    s.add_dependency(%q<faraday>,  ["~> 0.7.0"])
   end
 end

data/lib/koala/batch_operation.rb

@@ -18,25 +18,25 @@ module Koala
         @url = options[:url]
         @method = options[:method].to_sym
         @post_processing = options[:post_processing]
-        
+
         process_binary_args
-        
+
         raise Koala::KoalaError, "Batch operations require an access token, none provided." unless @access_token
       end
-      
+
       def to_batch_params(main_access_token)
         # set up the arguments
         args_string = Koala.http_service.encode_params(@access_token == main_access_token ? @args : @args.merge(:access_token => @access_token))
-        
+
         response = {
-          :method => @method.to_s, 
+          :method => @method.to_s,
           :relative_url => @url,
         }
-         
+
         # handle batch-level arguments, such as name, depends_on, and attached_files
         @batch_args[:attached_files] = @files.keys.join(",") if @files
         response.merge!(@batch_args) if @batch_args
-        
+
         # for get and delete, we append args to the URL string
         # otherwise, they go in the body
         if args_string.length > 0
@@ -46,15 +46,15 @@ module Koala
             response[:body] = args_string if args_string.length > 0
           end
         end
-        
+
         response
       end
-  
+
       protected
-      
+
       def process_binary_args
         # collect binary files
-        @args.each_pair do |key, value| 
+        @args.each_pair do |key, value|
           if UploadableIO.binary_content?(value)
             @files ||= {}
             # we use a class-level counter to ensure unique file identifiers across multiple batch operations
@@ -63,12 +63,12 @@ module Koala
             id = "op#{identifier}_file#{@files.keys.length}"
             @files[id] = @args.delete(key).is_a?(UploadableIO) ? value : UploadableIO.new(value)
           end
-        end          
+        end
       end
-      
+
       def args_in_url?
-        @method == :get || @method == :delete 
-      end   
+        @method == :get || @method == :delete
+      end
     end
   end
 end

data/lib/koala/graph_api.rb

@@ -1,30 +1,30 @@
 module Koala
   module Facebook
-    GRAPH_SERVER = "graph.facebook.com"   
+    GRAPH_SERVER = "graph.facebook.com"
 
     module GraphAPIMethods
       # A client for the Facebook Graph API.
-      # 
+      #
       # See http://github.com/arsduo/koala for Ruby/Koala documentation
       # and http://developers.facebook.com/docs/api for Facebook API documentation
-      # 
+      #
       # The Graph API is made up of the objects in Facebook (e.g., people, pages,
       # events, photos) and the connections between them (e.g., friends,
       # photo tags, and event RSVPs). This client provides access to those
       # primitive types in a generic way. For example, given an OAuth access
       # token, this will fetch the profile of the active user and the list
       # of the user's friends:
-      # 
-      #    graph = Koala::Facebook::GraphAPI.new(access_token)
+      #
+      #    graph = Koala::Facebook::API.new(access_token)
       #    user = graph.get_object("me")
       #    friends = graph.get_connections(user["id"], "friends")
-      # 
+      #
       # You can see a list of all of the objects and connections supported
       # by the API at http://developers.facebook.com/docs/reference/api/.
-      # 
+      #
       # You can obtain an access token via OAuth or by using the Facebook
       # JavaScript SDK. See the Koala and Facebook documentation for more information.
-      # 
+      #
       # If you are using the JavaScript SDK, you can use the
       # Koala::Facebook::OAuth.get_user_from_cookie() method below to get the OAuth access token
       # for the active user from the cookie saved by the SDK.
@@ -35,19 +35,19 @@ module Koala
         # Fetchs the given object from the graph.
         graph_call(id, args, "get", options)
       end
-    
+
       def get_objects(ids, args = {}, options = {})
         # Fetchs all of the given objects from the graph.
         # If any of the IDs are invalid, they'll raise an exception.
         return [] if ids.empty?
         graph_call("", args.merge("ids" => ids.respond_to?(:join) ? ids.join(",") : ids), "get", options)
       end
-      
+
       def put_object(parent_object, connection_name, args = {}, options = {})
         # Writes the given object to the graph, connected to the given parent.
         # See http://developers.facebook.com/docs/api#publishing for all of
         # the supported writeable objects.
-        # 
+        #
         # For example,
         #     graph.put_object("me", "feed", :message => "Hello, world")
         # writes "Hello, world" to the active user's wall.
@@ -56,7 +56,7 @@ module Koala
         # publishing wall posts requires the "publish_stream" permission. See
         # http://developers.facebook.com/docs/authentication/ for details about
         # extended permissions.
-    
+
         raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Write operations require an access token"}) unless @access_token
         graph_call("#{parent_object}/#{connection_name}", args, "post", options)
       end
@@ -66,24 +66,14 @@ module Koala
         raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Delete requires an access token"}) unless @access_token
         graph_call(id, {}, "delete", options)
       end
-      
+
       # Connections
-          
+
       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 get_comments_for_urls(urls = [], args = {}, options = {})
-        # Fetchs the comments for given URLs (array or comma-separated string)
-        # see https://developers.facebook.com/blog/post/490
-        return [] if urls.empty?
-        args.merge!(:ids => urls.respond_to?(:join) ? urls.join(",") : urls)
-        get_object("comments", args, options)
-      end
-          
       def put_connections(id, connection_name, args = {}, options = {})
         # Posts a certain connection
         raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Write operations require an access token"}) unless @access_token
@@ -98,19 +88,20 @@ module Koala
 
       # Media (photos and videos)
       # to delete photos or videos, use delete_object(object_id)
-      # note: you'll need the user_photos or user_videos permissions to actually access media after upload 
-    
+      # note: you'll need the user_photos or user_videos permissions to actually access media after upload
+
       def get_picture(object, args = {}, options = {})
         # Gets a picture object, returning the URL (which Facebook sends as a header)
         graph_call("#{object}/picture", args, "get", options.merge(:http_component => :headers)) do |result|
           result["Location"]
         end
-      end    
-      
+      end
+
       # Can be called in multiple ways:
       #
       #   put_picture(file, [content_type], ...)
       #   put_picture(path_to_file, [content_type], ...)
+      #   put_picture(picture_url, ...)
       #
       # You can pass in uploaded files directly from Rails or Sinatra.
       # (See lib/koala/uploadable_io.rb for supported frameworks)
@@ -119,29 +110,32 @@ module Koala
       # - args:       a hash of request parameters (default: {})
       # - target_id:  ID of the target where to post the picture (default: "me")
       # - options:    a hash of http options passed to the HTTPService module
-      # 
+      #
       #   put_picture(file, content_type, {:message => "Message"}, 01234560)
       #   put_picture(params[:file], {:message => "Message"})
-      
+      #
+      #   (Note that with URLs, there's no optional content type field)
+      #   put_picture(picture_url, {:message => "Message"}, my_page_id)
+
       def put_picture(*picture_args)
         put_object(*parse_media_args(picture_args, "photos"))
       end
-        
+
       def put_video(*video_args)
         args = parse_media_args(video_args, "videos")
         args.last[:video] = true
         put_object(*args)
       end
-    
+
       # Wall posts
       # To get wall posts, use get_connections(user, "feed")
       # To delete a wall post, just use delete_object(post_id)
-    
+
       def put_wall_post(message, attachment = {}, profile_id = "me", options = {})
         # attachment is a hash describing the wall post
         # (see X for more details)
-        # For instance, 
-        # 
+        # For instance,
+        #
         #     {"name" => "Link name"
         #      "link" => "http://www.example.com/",
         #      "caption" => "{*actor*} posted a new review",
@@ -150,19 +144,19 @@ module Koala
 
         self.put_object(profile_id, "feed", attachment.merge({:message => message}), options)
       end
-      
+
       # Comments
       # to delete comments, use delete_object(comment_id)
       # to get comments, use get_connections(object, "likes")
-      
+
       def put_comment(object_id, message, options = {})
         # Writes the given comment on the given post.
         self.put_object(object_id, "comments", {:message => message}, options)
       end
-        
+
       # Likes
       # to get likes, use get_connections(user, "likes")
-      
+
       def put_like(object_id, options = {})
         # Likes the given post.
         self.put_object(object_id, "likes", {}, options)
@@ -175,42 +169,44 @@ module Koala
       end
 
       # Search
-            
+
       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
+        graph_call("search", args, "get", options)
+      end
+
+      # Convenience Methods
+
+      def get_page_access_token(object_id)
+        result = get_object(object_id, :fields => "access_token") do
+          result ? result["access_token"] : nil
         end
-      end      
-      
-      
+      end
+
+      def get_comments_for_urls(urls = [], args = {}, options = {})
+        # Fetchs the comments for given URLs (array or comma-separated string)
+        # see https://developers.facebook.com/blog/post/490
+        return [] if urls.empty?
+        args.merge!(:ids => urls.respond_to?(:join) ? urls.join(",") : urls)
+        get_object("comments", args, options)
+      end
+
       # GraphCollection support
       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)
         else
           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
@@ -221,38 +217,54 @@ 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)
         # or added to the list of batch results (batch)
         if response.is_a?(Hash) && error_details = response["error"]
-          APIError.new(error_details) 
+          APIError.new(error_details)
         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
         raise KoalaError.new("Wrong number of arguments for put_#{method == "photos" ? "picture" : "video"}") unless media_args.size.between?(1, 5)
-        
+
         args_offset = media_args[1].kind_of?(Hash) || media_args.size == 1 ? 0 : 1
-        
+
         args      = media_args[1 + args_offset] || {}
         target_id = media_args[2 + args_offset] || "me"
-        options   = media_args[3 + args_offset] || {} 
-        
-        args["source"] = Koala::UploadableIO.new(*media_args.slice(0, 1 + args_offset))
+        options   = media_args[3 + args_offset] || {}
 
-        options[:http_service] = Koala.base_http_service if args["source"].requires_base_http_service
+        if url?(media_args.first)
+          # If media_args is a URL, we can upload without UploadableIO
+          args.merge!(:url => media_args.first)
+        else
+          args["source"] = Koala::UploadableIO.new(*media_args.slice(0, 1 + args_offset))
+        end
 
         [target_id, method, args, options]
-      end      
+      end
+
+      def url?(data)
+        return false unless data.is_a? String
+        begin
+          uri = URI.parse(data)
+          %w( http https ).include?(uri.scheme)
+        rescue URI::BadURIError
+          false
+        end
+      end
     end
   end
-end  
+end

data/lib/koala/graph_batch_api.rb

@@ -1,21 +1,28 @@
 module Koala
   module Facebook
       module GraphBatchAPIMethods
-        
+
       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
-          
+
           alias_method :check_graph_api_response, :check_response
           alias_method :check_response, :check_graph_batch_api_response
         end
       end
-      
+
       def batch_calls
         @batch_calls ||= []
       end
-            
+
       def graph_call_in_batch(path, args = {}, verb = "get", options = {}, &post_processing)
           # for batch APIs, we queue up the call details (incl. post-processing)
           batch_calls << BatchOperation.new(
@@ -26,7 +33,7 @@ module Koala
             :http_options => options,
             :post_processing => post_processing
           )
-          nil # batch operations return nothing immediately 
+          nil # batch operations return nothing immediately
       end
 
       def check_graph_batch_api_response(response)
@@ -45,8 +52,8 @@ module Koala
           args.merge!(batch_op.files) if batch_op.files
           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|
@@ -57,10 +64,10 @@ module Koala
             if call_result
               # (see note in regular api method about JSON parsing)
               body = MultiJson.decode("[#{call_result['body'].to_s}]")[0]
-              
+
               unless call_result["code"].to_i >= 500 || error = check_response(body)
                 # Get the HTTP component they want
-                data = case batch_op.http_options[:http_component] 
+                data = case batch_op.http_options[:http_component]
                 when :status
                   call_result["code"].to_i
                 when :headers
@@ -78,10 +85,13 @@ module Koala
             else
               nil
             end
-          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
   end
 end

data/lib/koala/graph_collection.rb

@@ -10,25 +10,30 @@ 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
-            
+
       # defines methods for NEXT and PREVIOUS pages
       %w{next previous}.each do |this|
-        
+
         # def next_page
         # def previous_page
         define_method "#{this.to_sym}_page" do
           base, args = send("#{this}_page_params")
           base ? @api.get_page([base, args]) : nil
         end
-        
+
         # def next_page_params
         # def previous_page_params
         define_method "#{this.to_sym}_page_params" do
@@ -36,7 +41,7 @@ module Koala
           parse_page_url(@paging[this])
         end
       end
-      
+
       def parse_page_url(url)
         match = url.match(/.com\/(.*)\?(.*)/)
         base = match[1]
@@ -48,7 +53,7 @@ module Koala
         end
         [base,new_params]
       end
-      
+
     end
   end
 end