fogli 0.1.0

data/lib/fogli/facebook_object/properties.rb

@@ -0,0 +1,81 @@
+module Fogli
+  class FacebookObject < FacebookGraph
+    # Allows for properties to be set on an object. A property is
+    # accessible instance data which is parsed from the JSON data blob
+    # which is returned by Graph API calls.
+    module Properties
+      def self.included(base)
+        base.extend(ClassMethods)
+      end
+
+      module ClassMethods
+        # Defines a property on the object. These properties map
+        # directly to keys in the returned JSON from the Facebook
+        # Graph API.
+        def property(*names)
+          options = names.last
+          options = {} if !options.kind_of?(Hash)
+
+          names.each do |name|
+            next if name.kind_of?(Hash)
+            name = name.to_s.downcase.to_sym
+            properties[name] = options
+
+            # Create a method for reading the property.
+            define_method(name) { read_property(name) }
+          end
+        end
+
+        # Returns the properties associated with this facebook
+        # object.
+        #
+        # @return [Hash]
+        def properties
+          @_properties ||= {}
+        end
+
+        # Propagates properties to another class. This is used
+        # internally for making sure that subclasses get all the
+        # properties associated with the parent classes.
+        def propagate_properties(klass)
+          properties.each { |n, o| klass.property(n, o) }
+        end
+      end
+
+      # Populates the properties with the given hash of data. This
+      # method also handles parsing non-primitive data such as other
+      # facebook objects.
+      def populate_properties(data)
+        property_values.clear
+
+        self.class.properties.keys.each do |name|
+          # Try both the string and symbol lookup to get the item
+          # associated with a key
+          item = data[name.to_s] || data [name]
+
+          if item.is_a?(Hash)
+            # For now, assume its a NamedObject. In the future, we'll be
+            # more careful.
+            item = NamedObject.new(item.merge(:_loaded => true))
+          end
+
+          property_values[name] = item
+        end
+
+        self
+      end
+
+      # Reads a property.
+      def read_property(name)
+        value = property_values[name]
+        value = value.name if value.is_a?(NamedObject)
+        value
+      end
+
+      # Stores the values of the variables properties
+      def property_values
+        @_property_values ||= {}
+      end
+    end
+  end
+end

data/lib/fogli/facebook_object/scope_methods.rb

@@ -0,0 +1,49 @@
+module Fogli
+  class FacebookObject < FacebookGraph
+    # Includable module which has the scope methods to properly
+    # instantiate a {ConnectionScope}.
+    module ScopeMethods
+      # The various scoping types. Each method takes a single value
+      # associated with it, which is used to build up a new scope.
+      [:limit, :offset, :until, :since].each do |scope|
+        define_method(scope) do |value|
+          ConnectionScope.new(*_scope_initializer_args(scope, value))
+        end
+      end
+
+      # Scope the connection by the fields you're interested in. By
+      # default, the connection will load all the possible fields for
+      # the connection, which can result in a fairly large overhead if
+      # you're only interested in the `first_name`, for example.
+      #
+      # The parameter to this method can be almost anything which can
+      # intuitively be converted down to either a string or
+      # array. Some example uses follow (admittingly some of these are
+      # a bit pathological, but they're meant to showcase the
+      # flexibility of the method):
+      #
+      #     fields("name,birthday,last_name")
+      #     fields(:name, :birthday, :last_name)
+      #     fields([:name, "birthday"], :last_name)
+      #     fields("name,birthday", ["last_name"])
+      #
+      def fields(*fields)
+        ConnectionScope.new(*_scope_initializer_args(:fields, fields.flatten.join(",")))
+      end
+
+      # Returns the proper set of arguments to send to the
+      # {ConnectionScope} initializer given the scope and value.
+      #
+      # @param [Symbol] scope The scope option.
+      # @param [Object] value The value for the scope.
+      # @return [Array]
+      def _scope_initializer_args(scope, value)
+        if self.is_a?(ConnectionScope)
+          [proxy, options.merge(scope => value)]
+        else
+          [self, {scope => value}]
+        end
+      end
+    end
+  end
+end

data/lib/fogli/group.rb

@@ -0,0 +1,8 @@
+module Fogli
+  class Group < FacebookObject
+    property :owner, :name, :description, :link, :venue, :privacy
+
+    connection :feed, :class => :Post
+    connection :members, :class => :User
+  end
+end

data/lib/fogli/link.rb

@@ -0,0 +1,8 @@
+module Fogli
+  class Link < FacebookObject
+    property :from, :link, :name, :caption, :description,
+             :message
+
+    connection :comments, :class => :Comment
+  end
+end

data/lib/fogli/named_object.rb

@@ -0,0 +1,8 @@
+module Fogli
+  # A simple, named object. Many things in Facebook are associated
+  # with an ID but simply have a name. This object represents such an
+  # item.
+  class NamedObject < FacebookObject
+    property :name
+  end
+end

data/lib/fogli/note.rb

@@ -0,0 +1,7 @@
+module Fogli
+  class Note < FacebookObject
+    property :from, :subject, :message, :created_time
+
+    connection :comments, :class => :Comment
+  end
+end

data/lib/fogli/oauth.rb

@@ -0,0 +1,167 @@
+require 'cgi'
+
+module Fogli
+  # Handles OAuth authorization with Facebook to obtain an access key
+  # which can then be used to retrieve authorized data via the
+  # Facebook Open Graph API.
+  #
+  # # Requesting an Access Token
+  #
+  # Requesting an access token is a multi-step process:
+  #
+  # 1. Redirect the user to an authorization URL on the Facebook
+  #    domain.
+  # 2. After authorizing, Facebook redirects the user back to your
+  #    domain, with a verification string as the `code` GET parameter.
+  # 3. Request the access token from Facebook using the `code` GET
+  #    parameter and the client ID and secret key given by Facebook
+  #    during application creation.
+  #
+  # Fogli simplifies this into two separate API calls:
+  #
+  # 1. First call {authorize} to get the authorization URL.
+  # 2. Call {access_token} to get the access token.
+  #
+  # # Persisting an Access Token
+  #
+  # After retrieving an access token, it should be persisted into a
+  # cookie or some sort of session store. On subsequent requests, set
+  # the access token on the {Fogli} object:
+  #
+  #     Fogli.access_token = cookies[:access_token]
+  #
+  # Fogli will then automatically use the access token on all API
+  # requests to retrieve authorized data.
+  #
+  # # Examples
+  #
+  # The following is a full length example based on
+  # [Sinatra](http://www.sinatrarb.com) syntax of authorizing a
+  # user. For examples on the wide variety of options that each method
+  # takes, please view {authorize} and {access_token}.
+  #
+  #     require 'sinatra'
+  #     reqiure 'fogli'
+  #
+  #     # Set Fogli Configuration
+  #     Fogli.client_id = "..."
+  #     Fogli.client_secret = "..."
+  #     Fogli.redirect_uri = "http://localhost:4567/my_email"
+  #
+  #     get "/" do
+  #       # Redirect user to authorization URL
+  #       redirect_to Fogli::OAuth.authorize(:scope => "email")
+  #     end
+  #
+  #     get "/my_email" do
+  #       # Store away the access token. In reality, this should be
+  #       # persisted to some session storage (cookies, db, etc.)
+  #       Fogli.access_token = Fogli::OAuth.access_token(:code => params[:code])
+  #
+  #       # Output the current user's email
+  #       User[:me].email
+  #     end
+  #
+  class OAuth < FacebookGraph
+    AUTHORIZE_URI = "http://graph.facebook.com/oauth/authorize?client_id=%s&redirect_uri=%s"
+
+    extend Util::Options
+
+    # Returns the authorization URL to redirect the user to in order
+    # to get an access token. This method takes a hash as its sole
+    # argument, and has the following possible keys:
+    #
+    # * `:redirect_uri` (optional) - The URI to redirect to after
+    #   the user authorizes. This URI will be given a single parameter
+    #   `code` as a GET variable. This should be passed into
+    #   {access_token} to finally retrieve the access token.
+    # * `:client_id` (optional) - The client ID of your Facebook
+    #   application
+    # * `:scope` (optional) - Specifies additional [extended
+    # permissions](http://developers.facebook.com/docs/authentication/permissions)
+    #    to request with the authorization.
+    #
+    # # Examples
+    #
+    # ## Requesting a Basic Authorize URL
+    #
+    # With options in the arguments:
+    #
+    #     Fogli::OAuth.authorize(:client_id => "...",
+    #                            :redirect_uri => "...")
+    #
+    # With statically set options:
+    #
+    #     Fogli.client_id = "..."
+    #     Fogli.redirect_uri = "..."
+    #     redirect_to Fogli::OAuth.authorize
+    #
+    # ## Requesting Extended Permissions
+    #
+    #     Fogli::OAuth.authorize(:scope => ["user_email", "user_photos"])
+    #
+    # @param [Hash] options Described above.
+    # @return [String] The authorization URL to redirect the user to.
+    def self.authorize(options=nil)
+      defaults = {
+        :client_id => Fogli.client_id,
+        :redirect_uri => Fogli.redirect_uri,
+      }
+
+      options = verify_options(options, {
+                                 :required_keys => defaults.keys,
+                                 :valid_keys => [defaults.keys, :scope].flatten,
+                                 :default => defaults
+                               })
+      result = AUTHORIZE_URI % [options[:client_id], CGI.escape(options[:redirect_uri])]
+      if options[:scope]
+        options[:scope] = [options[:scope]] if !options.is_a?(Array)
+        result += "&scope=#{options[:scope].join(",")}"
+      end
+
+      result
+    end
+
+    # Exchanges a verfication code for an access token. After
+    # redirecting a user to the {authorize} URL, the user is
+    # redirected back with the `code` GET parameter. This parameter
+    # along with the `redirect_uri` should get passed into this
+    # method, which will then return the access token. The possible
+    # keys for the arguments hash are as follows:
+    #
+    # * `:redirect_uri` (**required**) - The URI which the user was
+    #   redirected to with the `code` param.
+    # * `:code` (**required**) - The code which was given as a GET
+    #   param by facebook.
+    # * `:client_id` (optional) - The client ID of your facebook
+    #   application. If this is not specified here, it must be set via
+    #   `Fogli.client_id=`
+    # * `:client_secret` (optional) - The client secret key of your
+    #   facebook application. If this is not specified here, it must be
+    #   set via `Fogli.client_secret=`.
+    #
+    # The return value is the access token. This token should be
+    # persisted in a cookie or some other session store, so it can be
+    # used on subsequent requests. The token can be set via
+    # `Fogli.access_token=`, which will cause all API calls to use the
+    # specified access token.
+    #
+    # @param [Hash] options Described above.
+    # @return [String] Access token
+    def self.access_token(options)
+      defaults = {
+        :client_id => Fogli.client_id,
+        :client_secret => Fogli.client_secret,
+        :redirect_uri => Fogli.redirect_uri,
+        :code => nil
+      }
+
+      options = verify_options(options, {
+                                 :required_keys => defaults.keys,
+                                 :default => defaults
+                               })
+      result = get("/oauth/access_token", options)
+      result.split(/(&|=)/)[2]
+    end
+  end
+end

data/lib/fogli/page.rb

@@ -0,0 +1,15 @@
+module Fogli
+  class Page < FacebookObject
+    property :name, :category
+
+    connection :feed, :tagged, :posts, :class => :Post
+    connection :links, :class => :Link
+    connection :photos, :class => :Photo
+    connection :groups, :class => :Group
+    connection :albums, :class => :Album
+    connection :statuses, :class => :Status
+    connection :videos, :class => :Video
+    connection :notes, :class => :Note
+    connection :events, :class => :Event
+  end
+end

data/lib/fogli/photo.rb

@@ -0,0 +1,8 @@
+module Fogli
+  class Photo < FacebookObject
+    property :from, :tags, :name, :source, :height, :width,
+             :link, :created_time
+
+    connection :comments, :class => :Comment
+  end
+end

data/lib/fogli/post.rb

@@ -0,0 +1,18 @@
+module Fogli
+  class Post < FacebookObject
+    property :from, :to, :message, :link, :name, :caption, :description, :type,
+             :source, :icon, :attribution, :actions, :likes, :created_time
+
+    connection :comments, :class => :Comment
+
+    # Like a post. This method requires authorization.
+    def like!
+      post("/likes")
+    end
+
+    # Unlike a post. This method requires authorization.
+    def unlike!
+      post("/likes", :method => :delete)
+    end
+  end
+end

data/lib/fogli/status.rb

@@ -0,0 +1,7 @@
+module Fogli
+  class Status < FacebookObject
+    property :from, :message
+
+    connection :comments, :class => :Comment
+  end
+end

data/lib/fogli/user.rb

@@ -0,0 +1,36 @@
+module Fogli
+  class User < FacebookObject
+    property :first_name, :last_name, :name, :link, :about,
+             :birthday, :work, :education, :email, :website,
+             :hometown, :location, :gender, :interested_in,
+             :meeting_for, :relationship_status, :religion,
+             :political, :verified, :significant_other, :timezone
+
+    connection :friends, :class => :User
+    connection :home, :feed, :tagged, :posts, :class => :Post
+    connection :activities, :interests, :music, :books, :movies,
+               :television, :class => :CategorizedObject
+    connection :likes, :class => :Page
+    connection :photos, :class => :Photo
+    connection :albums, :class => :Album
+    connection :videos, :class => :Video
+    connection :groups, :class => :Group
+    connection :statuses, :class => :Status
+    connection :links, :class => :Link
+    connection :notes, :class => :Note
+    connection :events, :class => :Event
+
+    # Checks if a user is authorized. This returns a true or false
+    # depending if we're allowed to make authorized calls yet. If this
+    # returns false, the user must be authorized using the {OAuth}
+    # class via a simple two step process.
+    #
+    # @return [Boolean]
+    def self.authorized?
+      User.find(:me, :fields => :id).load!
+      true
+    rescue Fogli::Exception
+      false
+    end
+  end
+end

data/lib/fogli/util/module_attributes.rb

@@ -0,0 +1,61 @@
+# Taken directly from Rails 3 core. I claim no authorship of this
+# code. Fogli first attempts to load the actual ActiveSupport code
+# if it exists, but falls back to this implementation. This way,
+# running Fogli with rails shouldn't conflict in any way.
+
+#
+# Extends the module object with module and instance accessors for class attributes,
+# just like the native attr* accessors for instance attributes.
+#
+#  module AppConfiguration
+#    mattr_accessor :google_api_key
+#    self.google_api_key = "123456789"
+#
+#    mattr_accessor :paypal_url
+#    self.paypal_url = "www.sandbox.paypal.com"
+#  end
+#
+#  AppConfiguration.google_api_key = "overriding the api key!"
+class Module
+  def mattr_reader(*syms)
+    syms.each do |sym|
+      next if sym.is_a?(Hash)
+      class_eval(<<-EOS, __FILE__, __LINE__)
+        unless defined? @@#{sym}
+          @@#{sym} = nil
+        end
+
+        def self.#{sym}
+          @@#{sym}
+        end
+
+        def #{sym}
+          @@#{sym}
+        end
+      EOS
+    end
+  end
+
+  def mattr_writer(*syms)
+    syms.each do |sym|
+      class_eval(<<-EOS, __FILE__, __LINE__)
+        unless defined? @@#{sym}
+          @@#{sym} = nil
+        end
+
+        def self.#{sym}=(obj)
+          @@#{sym} = obj
+        end
+
+        def #{sym}=(obj)
+          @@#{sym} = obj
+        end
+      EOS
+    end
+  end
+
+  def mattr_accessor(*syms)
+    mattr_reader(*syms)
+    mattr_writer(*syms)
+  end
+end