palidanx-koala 0.9.0

data/lib/koala/graph_api.rb

@@ -0,0 +1,192 @@
+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
+    
+    
+
+    module GraphAPIMethods
+      # A client for the Facebook Graph API.
+      # 
+      # See http://developers.facebook.com/docs/api for complete documentation
+      # for the API.
+      # 
+      # 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)
+      #    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 http://developers.facebook.com/docs/authentication/
+      # for details.
+      # 
+      # 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 = {})
+        # Fetchs the given object from the graph.
+        graph_call(id, args)
+      end
+    
+      def get_objects(ids, args = {})
+        # 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(",")))
+      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 = {})
+        # 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.
+        # 
+        # 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")
+      end
+    
+      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.
+        # 
+        # attachment adds a structured attachment to the status message being
+        # posted to the Wall. It should be a dictionary of the form:
+        # 
+        #     {"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}))
+      end
+    
+      def put_comment(object_id, message)
+        # Writes the given comment on the given post.
+        self.put_object(object_id, "comments", {:message => message})
+      end
+    
+      def put_like(object_id)
+        # Likes the given post.
+        self.put_object(object_id, "likes")
+      end
+    
+      def delete_object(id)
+        # Deletes the object with the given ID from the graph.
+        graph_call(id, {}, "delete")
+      end
+    
+      def search(search_terms, args = {})
+        # Searches for a given term
+        result = graph_call("search", args.merge({:q => search_terms}))
+        result ? GraphCollection.new(result, self) : nil # when facebook is down nil can be returned
+      end
+    
+      def graph_call(*args)
+        response = api(*args) do |response|
+          # check for Graph API-specific errors
+          if response.is_a?(Hash) && error_details = response["error"]
+            raise APIError.new(error_details)
+          end
+        end
+      
+        response
+      end
+    end
+  end
+end

data/lib/koala/http_services.rb

@@ -0,0 +1,71 @@
+module Koala
+  class Response
+    attr_reader :status, :body, :headers
+    def initialize(status, body, headers)
+      @status = status
+      @body = body
+      @headers = headers
+    end
+  end
+
+  module NetHTTPService
+    # this service uses Net::HTTP to send requests to the graph
+    def self.included(base)
+      base.class_eval do
+        require 'net/http' unless defined?(Net::HTTP)
+        require 'net/https'
+
+        def self.make_request(path, args, verb, options = {})
+          # We translate args to a valid query string. If post is specified,
+          # we send a POST request to the given path with the given arguments.
+
+          # 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"
+
+          server = options[:rest_api] ? Facebook::REST_SERVER : Facebook::GRAPH_SERVER
+          http = Net::HTTP.new(server, 443)
+          http.use_ssl = true
+          # we turn off certificate validation to avoid the 
+          # "warning: peer certificate won't be verified in this SSL session" warning
+          # not sure if this is the right way to handle it
+          # see http://redcorundum.blogspot.com/2008/03/ssl-certificates-and-nethttps.html
+          http.verify_mode = OpenSSL::SSL::VERIFY_NONE
+
+          result = http.start { |http|
+            response, body = (verb == "post" ? http.post(path, encode_params(args)) : http.get("#{path}?#{encode_params(args)}"))
+            Koala::Response.new(response.code.to_i, body, response)
+          }
+        end
+
+        protected
+        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
+          ((param_hash || {}).collect do |key_and_value| 
+            key_and_value[1] = key_and_value[1].to_json if key_and_value[1].class != String
+            "#{key_and_value[0].to_s}=#{CGI.escape key_and_value[1]}"
+          end).join("&")
+        end
+      end
+    end
+  end
+
+  module TyphoeusService
+    # this service uses Typhoeus to send requests to the graph
+    def self.included(base)
+      base.class_eval do
+        require 'typhoeus' unless defined?(Typhoeus)
+        include Typhoeus
+
+        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"
+          server = options[:rest_api] ? Facebook::REST_SERVER : Facebook::GRAPH_SERVER
+          typhoeus_options = {:params => args}.merge(options[:typhoeus_options] || {})
+          response = self.send(verb, "https://#{server}#{path}", typhoeus_options)
+          Koala::Response.new(response.code, response.body, response.headers_hash)
+        end
+      end # class_eval
+    end
+  end
+end

data/lib/koala/realtime_updates.rb

@@ -0,0 +1,95 @@
+require 'koala'
+
+module Koala
+  module Facebook
+    module RealtimeUpdateMethods
+      # note: to subscribe to real-time updates, you must have an application access token
+      
+      def self.included(base)
+        # make the attributes readable
+        base.class_eval do
+          attr_reader :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
+      
+      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
+      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)
+        args = {
+          :object => object, 
+          :fields => fields,
+          :callback_url => callback_url,
+          :verify_token => verify_token
+        }
+        # a subscription is a success if Facebook returns a 200 (after hitting your server for verification)
+        api(subscription_path, args, 'post', :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
+        api(subscription_path, args, 'delete', :http_component => :status) == 200
+      end
+  
+      def list_subscriptions
+        api(subscription_path)["data"]
+      end
+      
+      def api(*args) # same as GraphAPI
+        response = super(*args) do |response|
+          # check for subscription errors
+          if response.is_a?(Hash) && error_details = response["error"]
+            raise APIError.new(error_details)
+          end
+        end
+      
+        response
+      end    
+      
+      protected
+      
+      def subscription_path
+        @subscription_path ||= "#{@app_id}/subscriptions"
+      end
+    end
+  end
+end

data/lib/koala/rest_api.rb

@@ -0,0 +1,23 @@
+module Koala
+  module Facebook
+    REST_SERVER = "api.facebook.com"
+    
+    module RestAPIMethods
+      def fql_query(fql)
+        rest_call('fql.query', 'query' => fql)
+      end
+      
+      def rest_call(method, args = {})
+        response = api("method/#{method}", args.merge('format' => 'json'), 'get', :rest_api => true) do |response|
+          # check for REST API-specific errors
+          if response.is_a?(Hash) && response["error_code"]
+            raise APIError.new("type" => response["error_code"], "message" => response["error_msg"])
+          end
+        end
+        
+        response
+      end
+    end
+    
+  end # module Facebook
+end # module Koala

data/readme.md

@@ -0,0 +1,129 @@
+Koala
+====
+Koala (<a href="http://github.com/arsduo/koala" target="_blank">http://github.com/arsduo/koala</a>) is a new Facebook library for Ruby, supporting the Graph API, the old REST API, realtime updates, and OAuth validation.  We wrote Koala with four goals: 
+
+* Lightweight: Koala should be as light and simple as Facebook’s own new libraries, providing API accessors and returning simple JSON.  (We clock in, with comments, just over 500 lines of code.)
+* Fast: Koala should, out of the box, be quick. In addition to supporting the vanilla Ruby networking libraries, it natively supports Typhoeus, our preferred gem for making fast HTTP requests. Of course, That brings us to our next topic:
+* Flexible: Koala should be useful to everyone, regardless of their current configuration.  (We have no dependencies beyond the JSON gem.  Koala also has a built-in mechanism for using whichever HTTP library you prefer to make requests against the graph.)
+* Tested: Koala should have complete test coverage, so you can rely on it.  (Our complete test coverage can be run against either mocked responses or the live Facebook servers.)
+
+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::GraphAPI.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 GraphAPI#get_connections or GraphAPI#search) a GraphCollection object (a sub-class of Array) will be returned, which contains added methods for getting the next and previous page of results:
+    
+    # Returns the feed items for the currently logged-in user as a GraphCollection
+    feed = graph.get_connections("me", "feed")
+    
+    # GraphCollection is a sub-class of Array, so you can use it as a usual Array
+    first_entry = feed[0]
+    last_entry = feed.last
+
+    # Returns the next page of results (also as a GraphCollection)
+    next_feed = feed.next_page
+
+    # Returns an array describing the URL for the next page: [path, arguments]
+    # This is useful for paging across multiple requests
+    next_path, next_args = feed.next_page_params
+    
+    # You can use those params to easily get the next (or prevous) page
+    page = graph.get_page(feed.next_page_params)
+
+Check out the wiki for more examples.
+
+The old-school 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.  
+
+Koala now supports the old-school REST API using OAuth access tokens; to use this, instantiate your class using the RestAPI class:
+
+	@rest = Koala::Facebook::RestAPI.new(oauth_access_token)
+	@rest.fql_query(my_fql_query) # convenience method
+	@rest.rest_call("stream.publish", arguments_hash) # generic version
+	
+We reserve the right to expand the built-in REST API coverage to additional convenience methods in the future, depending on how fast Facebook moves to fill in the gaps.  
+
+(If you want the power of both APIs in the palm of your hand, try out the GraphAndRestAPI class.)
+
+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, code, 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_cookie(cookies)
+
+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
+
+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).
+
+*Signed Requests:* Excited to try out the new signed request authentication scheme?  Good news!  Koala now supports parsing those parameters:
+    @oauth.parse_signed_request(request)
+
+*Exchanging session keys:* Stuck building tab applications on Facebook?  Wishing you had an OAuth token so you could use the Graph API?  You're in luck! Koala now allows you to exchange session keys for OAuth access tokens:
+    @oauth.get_token_from_session_key(session_key)
+    @oauth.get_tokens_from_session_keys(array_of_session_keys)
+
+Real-time Updates
+-----
+The Graph API now allows your application to subscribe to real-time updates for certain objects in the graph.
+
+Currently, Facebook only supports subscribing to users, permissions and errors.  On top of that, there are limitations on what attributes and connections for each of these objects you can subscribe to updates for.  Check the [official Facebook documentation](http://developers.facebook.com/docs/api/realtime) for more details.
+
+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.
+
+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 the spec directory
+    spec koala_spec.rb
+
+You can also run live tests against Facebook's servers:
+    # Again from the spec directory
+    spec koala_spec_without_mocks.rb
+
+Important Note: to run the live tests, you have to provide some of your own data: a valid OAuth access token with publish\_stream and read\_stream permissions and an OAuth code that can be used to generate an access token.  You can get these data at the OAuth Playground; if you want to use your own app, remember to swap out the app ID, secret, and other values.  (The file also provides valid values for other tests, which you're welcome to swap out for data specific to your own application.)