koala 0.10.0 → 1.0.0.beta2

data/CHANGELOG

@@ -1,3 +1,29 @@
+v1.0
+New methods:
+-- Photo and file upload now supported through #put_picture
+  -- Beta 2: support for Rails 3, Sinatra, File objects, and paths (see documentation)
+  -- Beta 2: Added UploadableIO class to manage file uploads
+-- Added a delete_like method (thanks to wassem)
+-- Beta 2: Added put_connection and delete_connection convenience methods
+Updated methods:
+-- Beta 2: TestUser#befriend now requires user info hashes (id and access token) due to Facebook API changes (thanks to pulsd/kbighorse)
+-- Beta 2: all methods now accept an http_options hash as their optional last parameter
+-- Beta 2: You can now pass :beta => true in the http options to use Facebook's beta tier.
+Internal improvements: 
+-- For public requests, Koala now uses http by default (instead of https) to improve speed
+  -- This can be overridden through Koala.always_use_ssl= or by passing :use_ssl => true in the options hash for an api call
+-- Read-only REST API requests now go through the faster api-read server
+-- Replaced parse_signed_request with a version from Facebook that also supports the new signed params proposal
+  -- Note: invalid requests will now raise exceptions rather than return nil, in keeping with other SDKs
+-- delete_object will now raise an error if there's no access token (like put_object and delete_like)
+-- Beta 2: photo and file uploads now accept symbols as well as strings overall
+-- Beta 2: APIError is now < StandardError, not Exception
+-- Beta 2: Added KoalaError for non-API errors
+Test improvements:
+-- Expanded HTTP service tests (added Typhoeus test suite and additional Net::HTTP test cases)
+-- Live tests now verify that the access token has the necessary permissions before starting
+-- Replaced the 50-person network test, which often took 15+ minutes to run live, with a 5-person test
+
 v0.10.0
 -- Added test user module
 -- Fixed bug when raising APIError after Facebook fails to exchange session keys
@@ -11,10 +37,10 @@ v0.9.1
 v0.9.0
 -- Added parse_signed_request to handle Facebook's new authentication scheme
   -- note: creates dependency on OpenSSL (OpenSSL::HMAC) for decryption
--- Added GraphCollection class to provide paging support for GraphAPI get_connections and search methods (thanks to jagthedrummer)    
+-- Added GraphCollection class to provide paging support for GraphAPI get_connections and search methods (thanks to jagthedrummer)
 -- Added get_page method to easily fetch pages of results from GraphCollections
 -- Exchanging sessions for tokens now works properly when provided invalid/expired session keys
--- You can now include a :typhoeus_options key in TyphoeusService#make_request's options hash to control the Typhoeus call (for example, to set :disable_ssl_peer_verification => true) 
+-- You can now include a :typhoeus_options key in TyphoeusService#make_request's options hash to control the Typhoeus call (for example, to set :disable_ssl_peer_verification => true)
 -- All paths provided to HTTP services start with leading / to improve compatibility with stubbing libraries
 -- If Facebook returns nil for search or get_connections requests, Koala now returns nil rather than throwing an exception
 
@@ -23,7 +49,7 @@ v0.8.0
   -- Removed string overloading for the methods, per 0.7.3, which caused Marshaling issues
   -- Removed ability to provide a string as the second argument to url_for_access_token, per 0.5.0
 
-v0.7.4 
+v0.7.4
 -- Fixed bug with get_user_from_cookies
 
 v0.7.3
@@ -34,18 +60,18 @@ v0.7.3
     -- Using those methods triggers a deprecation warning
     -- This will be removed by 1.0
   -- There are new info methods (get_access_token_info, get_app_access_token_info, get_token_info_from_session_keys, and get_user_info_from_cookies) that natively return hashes, for when you want the expiration date
--- Responses with HTTP status 500+ now properly throw errors under Net::HTTP 
+-- Responses with HTTP status 500+ now properly throw errors under Net::HTTP
 -- Updated changelog
 -- Added license
 
 v0.7.2
 -- Added support for exchanging session keys for OAuth access tokens (get_token_from_session_key for single keys, get_tokens_from_session_keys for multiple)
 -- Moved Koala files into a koala/ subdirectory to minimize risk of name collisions
--- Added OAuth Playground git submodule as an example 
+-- Added OAuth Playground git submodule as an example
 -- Updated tests, readme, and changelog
 
 v0.7.1
--- Updated RealtimeUpdates#list_subscriptions and GraphAPI#get_connections to now return an 
+-- Updated RealtimeUpdates#list_subscriptions and GraphAPI#get_connections to now return an
 array of results directly (rather than a hash with one key)
 -- Fixed a bug with Net::HTTP-based HTTP service in which the headers hash was improperly formatted
 -- Updated readme
@@ -92,7 +118,7 @@ v0.3.1
 v0.3
 -- Renamed Graph API class from Facebook::GraphAPI to FacebookGraph::API
 -- Created FacebookGraph::OAuth class for tokens and OAuth URLs
--- Updated method for including HTTP service (think we've got it this time) 
+-- Updated method for including HTTP service (think we've got it this time)
 -- Updated tests
 -- Added CHANGELOG and gemspec
 

data/Manifest

@@ -10,21 +10,28 @@ lib/koala/http_services.rb
 lib/koala/realtime_updates.rb
 lib/koala/rest_api.rb
 lib/koala/test_users.rb
+lib/koala/uploadable_io.rb
 readme.md
 spec/facebook_data.yml
 spec/koala/api_base_tests.rb
+spec/koala/assets/beach.jpg
 spec/koala/graph_and_rest_api/graph_and_rest_api_no_token_tests.rb
 spec/koala/graph_and_rest_api/graph_and_rest_api_with_token_tests.rb
 spec/koala/graph_api/graph_api_no_access_token_tests.rb
+spec/koala/graph_api/graph_api_tests.rb
 spec/koala/graph_api/graph_api_with_access_token_tests.rb
 spec/koala/graph_api/graph_collection_tests.rb
+spec/koala/http_services/http_service_tests.rb
+spec/koala/http_services/net_http_service_tests.rb
+spec/koala/http_services/typhoeus_service_tests.rb
 spec/koala/live_testing_data_helper.rb
-spec/koala/net_http_service_tests.rb
 spec/koala/oauth/oauth_tests.rb
 spec/koala/realtime_updates/realtime_updates_tests.rb
 spec/koala/rest_api/rest_api_no_access_token_tests.rb
+spec/koala/rest_api/rest_api_tests.rb
 spec/koala/rest_api/rest_api_with_access_token_tests.rb
 spec/koala/test_users/test_users_tests.rb
+spec/koala/uploadable_io/uploadable_io_tests.rb
 spec/koala_spec.rb
 spec/koala_spec_helper.rb
 spec/koala_spec_without_mocks.rb

data/Rakefile

@@ -4,14 +4,14 @@ require 'rake'
 require 'echoe'
 
 # gem management
-Echoe.new('koala', '0.10.0') do |p|
-  p.summary    = "A lightweight, flexible library for Facebook with support for the Graph API, the old REST API, realtime updates, and OAuth validation."
-  p.description = "Koala is a lightweight, flexible Ruby SDK for Facebook.  It allows read/write access to the social graph via the Graph API and the older REST API, 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."
+Echoe.new('koala', '1.0.0.beta2') do |p|
+  p.summary        = "A lightweight, flexible library for Facebook with support for the Graph API, the old REST API, realtime updates, and OAuth validation."
+  p.description    = "Koala is a lightweight, flexible Ruby SDK for Facebook.  It allows read/write access to the social graph via the Graph API and the older REST API, 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."
   p.url            = "http://github.com/arsduo/koala"
   p.author         = ["Alex Koppel", "Chris Baclig", "Rafi Jacoby", "Context Optional"]
   p.email          = "alex@alexkoppel.com"
   p.ignore_pattern = ["tmp/*", "script/*", "pkg/*"]
-  p.runtime_dependencies = ["json >=1.0"]
+  p.runtime_dependencies = ["json >=1.0", "multipart-post >=1.0"]
   p.development_dependencies = []
   p.retain_gemspec = true
 end

data/koala.gemspec

@@ -2,32 +2,34 @@
 
 Gem::Specification.new do |s|
   s.name = %q{koala}
-  s.version = "0.10.0"
+  s.version = "1.0.0.beta2"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 1.2") if s.respond_to? :required_rubygems_version=
   s.authors = ["Alex Koppel, Chris Baclig, Rafi Jacoby, Context Optional"]
-  s.date = %q{2010-12-15}
+  s.date = %q{2011-03-10}
   s.description = %q{Koala is a lightweight, flexible Ruby SDK for Facebook.  It allows read/write access to the social graph via the Graph API and the older REST API, 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.}
   s.email = %q{alex@alexkoppel.com}
-  s.extra_rdoc_files = ["CHANGELOG", "LICENSE", "lib/koala.rb", "lib/koala/graph_api.rb", "lib/koala/http_services.rb", "lib/koala/realtime_updates.rb", "lib/koala/rest_api.rb", "lib/koala/test_users.rb"]
-  s.files = ["CHANGELOG", "LICENSE", "Manifest", "Rakefile", "init.rb", "koala.gemspec", "lib/koala.rb", "lib/koala/graph_api.rb", "lib/koala/http_services.rb", "lib/koala/realtime_updates.rb", "lib/koala/rest_api.rb", "lib/koala/test_users.rb", "readme.md", "spec/facebook_data.yml", "spec/koala/api_base_tests.rb", "spec/koala/graph_and_rest_api/graph_and_rest_api_no_token_tests.rb", "spec/koala/graph_and_rest_api/graph_and_rest_api_with_token_tests.rb", "spec/koala/graph_api/graph_api_no_access_token_tests.rb", "spec/koala/graph_api/graph_api_with_access_token_tests.rb", "spec/koala/graph_api/graph_collection_tests.rb", "spec/koala/live_testing_data_helper.rb", "spec/koala/net_http_service_tests.rb", "spec/koala/oauth/oauth_tests.rb", "spec/koala/realtime_updates/realtime_updates_tests.rb", "spec/koala/rest_api/rest_api_no_access_token_tests.rb", "spec/koala/rest_api/rest_api_with_access_token_tests.rb", "spec/koala/test_users/test_users_tests.rb", "spec/koala_spec.rb", "spec/koala_spec_helper.rb", "spec/koala_spec_without_mocks.rb", "spec/mock_facebook_responses.yml", "spec/mock_http_service.rb"]
+  s.extra_rdoc_files = ["CHANGELOG", "LICENSE", "lib/koala.rb", "lib/koala/graph_api.rb", "lib/koala/http_services.rb", "lib/koala/realtime_updates.rb", "lib/koala/rest_api.rb", "lib/koala/test_users.rb", "lib/koala/uploadable_io.rb"]
+  s.files = ["CHANGELOG", "LICENSE", "Manifest", "Rakefile", "init.rb", "koala.gemspec", "lib/koala.rb", "lib/koala/graph_api.rb", "lib/koala/http_services.rb", "lib/koala/realtime_updates.rb", "lib/koala/rest_api.rb", "lib/koala/test_users.rb", "lib/koala/uploadable_io.rb", "readme.md", "spec/facebook_data.yml", "spec/koala/api_base_tests.rb", "spec/koala/assets/beach.jpg", "spec/koala/graph_and_rest_api/graph_and_rest_api_no_token_tests.rb", "spec/koala/graph_and_rest_api/graph_and_rest_api_with_token_tests.rb", "spec/koala/graph_api/graph_api_no_access_token_tests.rb", "spec/koala/graph_api/graph_api_tests.rb", "spec/koala/graph_api/graph_api_with_access_token_tests.rb", "spec/koala/graph_api/graph_collection_tests.rb", "spec/koala/http_services/http_service_tests.rb", "spec/koala/http_services/net_http_service_tests.rb", "spec/koala/http_services/typhoeus_service_tests.rb", "spec/koala/live_testing_data_helper.rb", "spec/koala/oauth/oauth_tests.rb", "spec/koala/realtime_updates/realtime_updates_tests.rb", "spec/koala/rest_api/rest_api_no_access_token_tests.rb", "spec/koala/rest_api/rest_api_tests.rb", "spec/koala/rest_api/rest_api_with_access_token_tests.rb", "spec/koala/test_users/test_users_tests.rb", "spec/koala/uploadable_io/uploadable_io_tests.rb", "spec/koala_spec.rb", "spec/koala_spec_helper.rb", "spec/koala_spec_without_mocks.rb", "spec/mock_facebook_responses.yml", "spec/mock_http_service.rb"]
   s.homepage = %q{http://github.com/arsduo/koala}
-  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Koala", "--main", "readme.md"]
+  s.rdoc_options = ["--line-numbers", "--inline-source", "--title", "Koala"]
   s.require_paths = ["lib"]
   s.rubyforge_project = %q{koala}
-  s.rubygems_version = %q{1.3.6}
+  s.rubygems_version = %q{1.4.2}
   s.summary = %q{A lightweight, flexible library for Facebook with support for the Graph API, the old REST API, realtime updates, and OAuth validation.}
 
   if s.respond_to? :specification_version then
-    current_version = Gem::Specification::CURRENT_SPECIFICATION_VERSION
     s.specification_version = 3
 
-    if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
+    if Gem::Version.new(Gem::VERSION) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<json>, [">= 1.0"])
+      s.add_runtime_dependency(%q<multipart-post>, [">= 1.0"])
     else
       s.add_dependency(%q<json>, [">= 1.0"])
+      s.add_dependency(%q<multipart-post>, [">= 1.0"])
     end
   else
     s.add_dependency(%q<json>, [">= 1.0"])
+    s.add_dependency(%q<multipart-post>, [">= 1.0"])
   end
 end

data/lib/koala/graph_api.rb

@@ -1,65 +1,12 @@
 module Koala
   module Facebook
-    GRAPH_SERVER = "graph.facebook.com"
-
-    class GraphCollection < Array
-      #This class is a light wrapper for collections returned
-      #from the Graph API.
-      #
-      #It extends Array to allow direct access to the data colleciton
-      #which should allow it to drop in seamlessly.
-      #
-      #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
-      
-      def initialize(response, api)
-        super response["data"]
-        @paging = response["paging"]
-        @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
-          return nil unless @paging and @paging[this]
-          parse_page_url(@paging[this])
-        end
-      end
-      
-      def parse_page_url(url)
-        match = url.match(/.com\/(.*)\?(.*)/)
-        base = match[1]
-        args = match[2]
-        params = CGI.parse(args)
-        new_params = {}
-        params.each_pair do |key,value|
-          new_params[key] = value.join ","
-        end
-        [base,new_params]
-      end
-      
-    end
-    
-    
+    GRAPH_SERVER = "graph.facebook.com"   
 
     module GraphAPIMethods
       # A client for the Facebook Graph API.
       # 
-      # See http://developers.facebook.com/docs/api for complete documentation
-      # for the 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,
@@ -76,108 +23,164 @@ module Koala
       # 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 http://developers.facebook.com/docs/authentication/
-      # for details.
+      # 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.
-            
-      def get_object(id, args = {})
+         
+      # Objects
+
+      def get_object(id, args = {}, options = {})
         # Fetchs the given object from the graph.
-        graph_call(id, args)
+        graph_call(id, args, "get", options)
       end
     
-      def get_objects(ids, args = {})
+      def get_objects(ids, args = {}, options = {})
         # Fetchs all of the given object from the graph.
         # We return a map from ID to object. If any of the IDs are invalid,
         # we raise an exception.
-        graph_call("", args.merge("ids" => ids.join(",")))
+        graph_call("", args.merge("ids" => ids.join(",")), "get", options)
       end
       
-      def get_page(params)
-        result = graph_call(*params)
-        result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
-      end
-    
-      def get_connections(id, connection_name, args = {})
-        # Fetchs the connections for given object.
-        result = graph_call("#{id}/#{connection_name}", args)
-        result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
-      end
-      
-    
-      def get_picture(object, args = {})
-        result = graph_call("#{object}/picture", args, "get", :http_component => :headers)
-        result["Location"]
-      end    
-      
-      def put_object(parent_object, connection_name, args = {})
+      def put_object(parent_object, connection_name, args = {}, options = {})
         # Writes the given object to the graph, connected to the given parent.
-        # 
-        # For example,
-        # 
-        #     graph.put_object("me", "feed", :message => "Hello, world")
-        # 
-        # writes "Hello, world" to the active user's wall. Likewise, this
-        # will comment on a the first post of the active user's feed:
-        # 
-        #     feed = graph.get_connections("me", "feed")
-        #     post = feed["data"][0]
-        #     graph.put_object(post["id"], "comments", :message => "First!")
-        # 
         # 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.
+        #
         # Most write operations require extended permissions. For example,
         # 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
+
+      def delete_object(id, options = {})
+        # Deletes the object with the given ID from the graph.
+        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.
+        result = graph_call("#{id}/#{connection_name}", args, "get", options)
+        result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
+      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
-        graph_call("#{parent_object}/#{connection_name}", args, "post")
+        graph_call("#{id}/#{connection_name}", args, "post", options)
       end
+
+      def delete_connections(id, connection_name, args = {}, options = {})
+        # Deletes a given connection
+        raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Delete requires an access token"}) unless @access_token
+        graph_call("#{id}/#{connection_name}", args, "delete", options)
+      end
+
+      # Pictures
+      # to delete pictures, use delete_object(photo_id)
+      # note: you'll need the user_photos permission to actually access photos after uploading them 
     
-      def put_wall_post(message, attachment = {}, profile_id = "me")
-        # Writes a wall post to the given profile's wall.
-        # 
-        # We default to writing to the authenticated user's wall if no
-        # profile_id is specified.
+      def get_picture(object, args = {}, options = {})
+        # Gets a picture object, returning the URL (which Facebook sends as a header)
+        result = graph_call("#{object}/picture", args, "get", options.merge(:http_component => :headers))
+        result["Location"]
+      end    
+      
+      def put_picture(*picture_args)
+        # Can be called in multiple ways:
+        #
+        #   put_picture(file, [content_type], ...)
+        #   put_picture(path_to_file, [content_type], ...)
+        #
+        # You can pass in uploaded files directly from Rails or Sinatra.
+        # (See lib/koala/uploadable_io.rb for supported frameworks)
+        #
+        # Optional parameters can be added to the end of the argument list:
+        # - 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
         # 
-        # attachment adds a structured attachment to the status message being
-        # posted to the Wall. It should be a dictionary of the form:
+        #   put_picture(file, content_type, {:message => "Message"}, 01234560)
+        #   put_picture(params[:file], {:message => "Message"})
+        
+        raise KoalaError.new("Wrong number of arguments for put_picture") unless picture_args.size.between?(1, 5)
+        
+        args_offset = picture_args[1].kind_of?(Hash) || picture_args.size == 1 ? 0 : 1
+        
+        args      = picture_args[1 + args_offset] || {}
+        target_id = picture_args[2 + args_offset] || "me"
+        options   = picture_args[3 + args_offset] || {} 
+        
+        args["source"] = Koala::UploadableIO.new(*picture_args.slice(0, 1 + args_offset))
+        
+        self.put_object(target_id, "photos", args, options)
+      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, 
         # 
-        #     {"name": "Link name"
-        #      "link": "http://www.example.com/",
-        #      "caption": "{*actor*} posted a new review",
-        #      "description": "This is a longer description of the attachment",
-        #      "picture": "http://www.example.com/thumbnail.jpg"}
+        #     {"name" => "Link name"
+        #      "link" => "http://www.example.com/",
+        #      "caption" => "{*actor*} posted a new review",
+        #      "description" => "This is a longer description of the attachment",
+        #      "picture" => "http://www.example.com/thumbnail.jpg"}
 
-        self.put_object(profile_id, "feed", attachment.merge({:message => message}))
+        self.put_object(profile_id, "feed", attachment.merge({:message => message}), options)
       end
-    
-      def put_comment(object_id, message)
+      
+      # 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})
+        self.put_object(object_id, "comments", {:message => message}, options)
       end
-    
-      def put_like(object_id)
+        
+      # 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")
+        self.put_object(object_id, "likes", {}, options)
       end
-    
-      def delete_object(id)
-        # Deletes the object with the given ID from the graph.
-        graph_call(id, {}, "delete")
+
+      def delete_like(object_id, options = {})
+        # Unlikes a given object for the logged-in user
+        raise APIError.new({"type" => "KoalaMissingAccessToken", "message" => "Unliking requires an access token"}) unless @access_token
+        graph_call("#{object_id}/likes", {}, "delete", options)
       end
-    
-      def search(search_terms, args = {})
-        # Searches for a given term
-        result = graph_call("search", args.merge({:q => search_terms}))
+
+      # Search
+            
+      def search(search_terms, args = {}, options = {})
+        # Searches for a given term among posts visible to the current user (or public posts if no token)
+        result = graph_call("search", args.merge(:q => search_terms), "get", options)
         result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
-      end
+      end      
+      
+      # API access
     
       def graph_call(*args)
+        # Direct access to the Facebook API
+        # see any of the above methods for example invocations
         response = api(*args) do |response|
           # check for Graph API-specific errors
           if response.is_a?(Hash) && error_details = response["error"]
@@ -186,7 +189,69 @@ module Koala
         end
       
         response
+      end 
+      
+      # GraphCollection support
+      
+      def get_page(params)
+        # Pages through a set of results stored in a GraphCollection
+        # Used for connections and search results
+        result = graph_call(*params)
+        result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
       end
+      
+    end
+    
+    
+    class GraphCollection < Array
+      #This class is a light wrapper for collections returned
+      #from the Graph API.
+      #
+      #It extends Array to allow direct access to the data colleciton
+      #which should allow it to drop in seamlessly.
+      #
+      #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
+      
+      def initialize(response, api)
+        super response["data"]
+        @paging = response["paging"]
+        @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
+          return nil unless @paging and @paging[this]
+          parse_page_url(@paging[this])
+        end
+      end
+      
+      def parse_page_url(url)
+        match = url.match(/.com\/(.*)\?(.*)/)
+        base = match[1]
+        args = match[2]
+        params = CGI.parse(args)
+        new_params = {}
+        params.each_pair do |key,value|
+          new_params[key] = value.join ","
+        end
+        [base,new_params]
+      end
+      
     end
   end
-end
+end