fogli 0.1.0

data/.gitignore

@@ -0,0 +1,5 @@
+.bundle
+*.lock
+test.rb
+.yardoc/
+doc/

data/Gemfile

@@ -0,0 +1,14 @@
+source "http://rubygems.org"
+
+gem "rest-client", "~> 1.5.1"
+gem "json_pure", "~> 1.2.0"
+
+group :development do
+  gem "sinatra" # for examples
+
+  gem "yard"
+  gem "bluecloth"
+  gem "contest", ">= 0.1.2"
+  gem "mocha"
+  gem "jeweler", "~> 1.4.0"
+end

data/LICENSE

@@ -0,0 +1,21 @@
+The MIT License
+
+Copyright (c) 2010 Mitchell Hashimoto
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,168 @@
+# Fogli
+
+Fogli is a **F**acebook **O**pen **G**raph **Li**brary.
+
+## Why?
+
+Facebook introduced the Graph API in April, 2010. This API is intended
+to replace their existing "RESTful API" in the future. Mature Facebook
+libraries such as [Facebooker](http://github.com/mmangino/facebooker) are
+heavily tied to the RESTful API and have not started supporting the Open
+Graph.
+
+At the time of Fogli's creation, there were a handful of other libraries
+claiming to be Facebook Graph libraries, but I found them unsatisfactory
+since they did not meet any or all of the following requirements:
+
+* Minimizes query calls
+* Strong feature support
+* Intuitive object model
+* Independent library; not tied to any web framework
+
+Fogli aims to expose the objects of the Facebook Graph through an intuitive
+object oriented interface while minimizing the number of queries needed
+to access data through lazy loading and caching. Fogli is not tied to any
+web framework and can run standalone perfectly fine.
+
+## Supported Features
+
+Below is a list of supported Facebook Graph features:
+
+* Authorization via OAuth
+* Reading objects (`User`, `Page`, etc.)
+* Reading object connections
+* Deleting objects
+* Scoping top level objects by `fields`
+* Scoping connections by `limit`, `offset`, `since`, `until`, and `fields`
+* Liking/unliking posts
+
+The list below is a list of unsupported features, but development is
+planned in the near future:
+
+* More support for publishing (posting comments, attending events, etc.)
+* Search
+* Real time updates
+* Analytics
+
+Have a feature request? Submit it on the [GitHub Issues](https://github.com/mitchellh/fogli/issues)
+page, or fork and send me a patch!
+
+## Getting Started
+
+Install Fogli:
+
+    gem install fogli
+
+Next, you can do a few things:
+
+* Open an IRB session and begin playing. Fogli isn't tied to any framework,
+  so you can see it work right away:
+
+        >> require "fogli"
+        >> m = Fogli::User["mitchellh"]
+        >> m.name
+        => "Mitchell Hashimoto"
+
+* Run the examples in the `examples/` directory to see how to access basic
+  connections and also use {Fogli::OAuth OAuth} to access authorized data.
+
+* Read the documentation here! For more specific, class by class documentation,
+  please read [the source-generated documentation](http://mitchellh.github.com/fogli/).
+
+## Reading Data and Accessing Connections
+
+Reading public information is straightforward and requires no configuration:
+
+    u = Fogli::User["mitchellh"]
+    p u.first_name # "Mitchell"
+    p u.last_name  # "Hashimoto"
+
+Accessing connections (relationships to data) is also intuitive and
+easy:
+
+    u.feed.each do |item|
+      p item
+    end
+
+## Authentication, Authorization, and Accessing Private Data
+
+To access private data, Facebook requires that the you gain an `access_token`
+by asking the user to authorize your application. This is a two-step process.
+The example before uses [Sinatra](http://www.sinatrarb.com/) with Fogli to
+authorize a user and print his or her email:
+
+    # Set these configuration values. The keys are retrieved from
+    # registering an application with Facebook. These can all be
+    # set on the actual method calls later as well.
+    Fogli.client_id = "..."
+    Fogli.client_secret = "..."
+    Fogli.redirect_uri = "http://my-website.com/verify"
+
+    get "/" do
+      # Redirect the user to authorized, asking for email permissions
+      redirect Fogli::OAuth.authorize(:scope => "email")
+    end
+
+    get "/verify"
+      # Facebook redirects back to this page with a GET parameter `code`
+      # which is used to get the access token. This token should also be
+      # stored in a cookie or some session storage to be set on subsequent pages.
+      Fogli.access_token = Fogli::OAuth.access_token(:code => params[:code])
+
+      # Print authorized data to prove we're allowed!
+      Fogli::User[:me].email
+    end
+
+Checking if a user is already authenciated is easy as well:
+
+    # Set from cookies, perhaps
+    Fogli.access_token = cookies[:access_token]
+
+    # Verify its valid
+    if Fogli::User.authorized?
+      # valid!
+    else
+      # reauthenticate
+    end
+
+## Accessing Connections with Scopes
+
+Facebook data connections are typically relationships to massive amounts
+of data, most of which you're not interested in. By scoping the data, you
+can limit the data to only what you want, and optimize the queries made by
+Fogli in the process:
+
+    # Assuming we're authenticated (above)
+    u = Fogli::User[:me]
+
+    # We just want feed times since yesterday, and we're only interested
+    # in 10 of them:
+    u.feed.since("yesterday").limit(10).each do |item|
+      # Do something with the item
+    end
+
+    # Another example: We want to access all the user's friends, but only
+    # want their first and last name:
+    u.friends.fields(:first_name, :last_name).each do |friend|
+       p "Friend: #{friend.first_name} #{friend.last_name}"
+    end
+
+## Lazy Loading and Caching
+
+Everything in Fogli is lazy-loaded. This means that data is loaded on
+demand and no queries are made until you need the data. So, how many
+HTTP queries do you think `User[:me].feed.since("yesterday")` takes?
+Since no property was ever access on the user, only 1 query is used
+(to get the `feed` items since yesterday).
+
+Additionally, once the data is loaded, it is cached to minimize the
+number of queries needed:
+
+    # This is also only one query, the entire script, even though the
+    # items are accessed 4 times.
+    items = Fogli::User[:me].feed.since("yesterday")
+    items.each {}
+    items.each {}
+    items.each {}
+    items.each {}
+

data/Rakefile

@@ -0,0 +1,37 @@
+require 'rake/testtask'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "fogli"
+    gem.summary = "An efficient, simple, and intuitive Facebook Open Graph library."
+    gem.description = "An efficient, simple, and intuitive Facebook Open Graph library."
+    gem.email = "mitchell.hashimoto@gmail.com"
+    gem.homepage = "http://github.com/mitchellh/fogli"
+    gem.authors = ["Mitchell Hashimoto"]
+
+    gem.add_dependency('rest-client', "~> 1.5.1")
+    gem.add_dependency('json_pure', "~> 1.2.0")
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+task :default => :test
+
+Rake::TestTask.new do |t|
+  t.libs << "libs"
+  t.libs << "test"
+  t.pattern = 'test/**/*_test.rb'
+end
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new do |t|
+    t.options = ['--main', 'README.md', '--markup', 'markdown']
+    t.options += ['--title', 'Fogli Documentation']
+  end
+rescue LoadError
+  puts "Yard not available. Install it with: gem install yard bluecloth"
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/examples/README.md

@@ -0,0 +1,6 @@
+# Fogli Examples
+
+The examples are organized into directories by their name. Please
+view the `README` files in an example's respective directory for
+more information on that example.
+

data/examples/me/README.md

@@ -0,0 +1,18 @@
+# Fogli "Me" Example
+
+The "Me" example shows how to use Fogli to access data about the
+`me` pseudo-user on Facebook which represents the currently authorized
+user.
+
+## Highlights
+
+* OAuth authentication
+* Accessing authorized data
+
+## Running
+
+To run the example, make sure you have [Sinatra](http://www.sinatrarb.com)
+installed, then enter this directory and run the main file:
+
+    $ ruby me.rb
+

data/examples/me/me.rb

@@ -0,0 +1,30 @@
+require 'rubygems'
+require 'sinatra'
+
+# Make sure we load the most recent fogli that this is packaged with
+# if its available.
+$:.unshift(File.join(File.dirname(__FILE__), *%W[.. .. lib]))
+require 'fogli'
+
+#!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!#
+# IMPORTANT: Set your app configuration details here:
+#!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!#
+Fogli.client_id = "132862110062471"
+Fogli.client_secret = "3f2f371b6f01c449eb3bcfc841b1b9c1"
+
+# No need to edit this:
+Fogli.redirect_uri = "http://localhost:4567/verify"
+
+get "/" do
+  # Authorize the user so we can get an access token
+  redirect Fogli::OAuth.authorize(:scope => "email")
+end
+
+get "/verify" do
+  # Get and store the access token, then print out their user
+  # information to verify it worked
+  Fogli.access_token = Fogli::OAuth.access_token(:code => params[:code])
+
+  # Output authorized information to verify it worked
+  Fogli::User[:me].email
+end

data/lib/fogli.rb

@@ -0,0 +1,46 @@
+# Try to load the Rails ActiveSupport module accessors
+# But fall back to our own if it doesn't exist.
+begin
+  require 'active_support/core_ext/module/attribute_accessors'
+rescue LoadError
+  require 'fogli/util/module_attributes'
+end
+
+module Fogli
+  # The configuration options below only need to be set if you
+  # wish to retrieve authorized information via the Graph API.
+  # The configuration keys should be self explanatory.
+  mattr_accessor :client_id
+  mattr_accessor :client_secret
+  mattr_accessor :redirect_uri
+  mattr_accessor :access_token
+
+  # Logger. Set this to anything which has the same API as the Ruby
+  # standard library logger, or `nil` to disable logging (default)
+  mattr_accessor :logger
+
+  autoload :Exception, 'fogli/exception'
+  autoload :FacebookGraph, 'fogli/facebook_graph'
+  autoload :FacebookObject, 'fogli/facebook_object'
+
+  # User-friendly models
+  autoload :Album, 'fogli/album'
+  autoload :CategorizedObject, 'fogli/categorized_object'
+  autoload :Comment, 'fogli/comment'
+  autoload :Event, 'fogli/event'
+  autoload :Group, 'fogli/group'
+  autoload :Link, 'fogli/link'
+  autoload :NamedObject, 'fogli/named_object'
+  autoload :Note, 'fogli/note'
+  autoload :OAuth, 'fogli/oauth'
+  autoload :Page, 'fogli/page'
+  autoload :Photo, 'fogli/photo'
+  autoload :Post, 'fogli/post'
+  autoload :Status, 'fogli/status'
+  autoload :User, 'fogli/user'
+  autoload :Video, 'fogli/video'
+
+  module Util
+    autoload :Options, 'fogli/util/options'
+  end
+end

data/lib/fogli/album.rb

@@ -0,0 +1,8 @@
+module Fogli
+  class Album < FacebookObject
+    property :from, :name, :description, :location, :link, :count, :created_time
+
+    connection :photos, :class => :Photo
+    connection :comments, :class => :Comment
+  end
+end

data/lib/fogli/categorized_object.rb

@@ -0,0 +1,9 @@
+module Fogli
+  # A categorized object. In addition to simple objects such as
+  # {NamedObject}s, Facebook also has simple objects which only have a
+  # name and category in addition to an ID. This object represents
+  # such an object.
+  class CategorizedObject < NamedObject
+    property :category
+  end
+end

data/lib/fogli/comment.rb

@@ -0,0 +1,5 @@
+module Fogli
+  class Comment < FacebookObject
+    property :from, :message, :created_time
+  end
+end

data/lib/fogli/event.rb

@@ -0,0 +1,9 @@
+module Fogli
+  class Event < FacebookObject
+    property :owner, :name, :description, :start_time, :end_time, :location,
+             :venue, :privacy
+
+    connection :feed, :class => :Post
+    conncetion :noreply, :maybe, :invited, :attending, :declined, :class => :User
+  end
+end

data/lib/fogli/exception.rb

@@ -0,0 +1,15 @@
+module Fogli
+  # An exception from a call to the Facebook Graph API. This will
+  # always contain the exception type and the message given.
+  class Exception < ::Exception
+    attr_reader :type
+    attr_reader :message
+
+    def initialize(type, message)
+      @type = type
+      @message = "[#{type}] #{message}"
+
+      super()
+    end
+  end
+end

data/lib/fogli/facebook_graph.rb

@@ -0,0 +1,125 @@
+require 'cgi'
+require 'restclient'
+require 'json'
+
+module Fogli
+  # The most basic level access to the Facebook Graph. This class only
+  # has access to the `get`, `post`, etc. methods to query the
+  # Facebook Graph directly. This class is used by every other class
+  # to access the graph. This class also will automatically insert the
+  # Facebook `access_token` if it has been specified, and handles
+  # changing the HTTP method to HTTPS in that case.
+  #
+  # **Note:** Most users should never have to use this class
+  # directly. Instead, use one of the models, such as {User}, to
+  # access your data.
+  #
+  # # Requesting Data
+  #
+  # Getting data from the Facebook graph is simple:
+  #
+  #     Fogli::FacebookGraph.get("/mitchellh")
+  #
+  # If you have an access token, {FacebookGraph} will add it to the
+  # query string without you having to do anything:
+  #
+  #     Fogli.access_token = "..."
+  #     Fogli::FacebookGraph.get("/me")
+  #
+  class FacebookGraph
+    GRAPH_DOMAIN = "graph.facebook.com"
+
+    class << self
+      # Override default HTTParty behavior to go through our request
+      # method to make sure that the access token is properly set if
+      # needed.
+      [:get, :post, :delete, :head].each do |method|
+        # A requester, where the arguments go through the {request}
+        # method, which handles automatically adding the
+        # {Fogli.access_token} if it is specified, and also handles
+        # the URL relative to the given path.
+        define_method(method) do |*args|
+          Fogli.logger.debug("Fogli #{method}: #{args.inspect}") if Fogli.logger
+          request(method, *args)
+        end
+
+        # A raw requester, which just directly requests with the given
+        # arguments.
+        define_method("raw_#{method}".to_sym) do |*args|
+          Fogli.logger.debug("Fogli raw #{method}: #{args.inspect}") if Fogli.logger
+          error_check { RestClient.send(method, *args) }
+        end
+      end
+
+      # Issues the specified request type with the given URL and
+      # options. This method will inject the Facebook `access_token`
+      # if it is available, and will properly change the method to
+      # "https" if needed.
+      def request(type, url, params=nil)
+        params ||= {}
+
+        if Fogli.access_token
+          params ||= {}
+          params.merge!(:access_token => Fogli.access_token)
+        end
+
+        method = "http"
+        method = "https" if params[:access_token]
+
+        url = "#{method}://#{GRAPH_DOMAIN}#{url}"
+        if !params.empty? && [:get, :delete].include?(type)
+          # For GET and DELETE, we're responsible for appending any
+          # query parameters onto the end of the URL
+          params = params.inject([]) do |acc, data|
+            k, v = data
+            acc << "#{k}=#{CGI.escape(v.to_s)}"
+            acc
+          end
+
+          url += "?#{params.join("&")}"
+          params = {}
+        end
+
+        error_check { RestClient.send(type, url, params) }
+      end
+
+      # Yields a block, checking for any errors in a request. If no
+      # errors are detected, decodes JSON and returns the result.
+      def error_check
+        response = begin
+          yield
+        rescue RestClient::Exception => e
+          e.response
+        end
+
+        data = parse_response(response)
+        if data.is_a?(Hash) && data["error"]
+          data = data["error"]
+          raise Exception.new(data["type"], data["message"])
+        elsif response.code.to_i == 500
+          raise Exception.new("Unknown", "Internal server error")
+        end
+
+        data
+      rescue NoMethodError
+        data
+      end
+
+      # Parses a response depending on the content type it sent back.
+      def parse_response(response)
+        type = response.headers[:content_type]
+        return response.body if type.include?("text/plain")
+        return JSON.parse(response.body)
+      rescue JSON::ParserError
+        response.body
+      end
+    end
+
+    # Shortcut methods to access the class-level methods.
+    [:get, :post, :delete, :head].each do |method|
+      define_method(method) do |*args|
+        self.class.send(method, *args)
+      end
+    end
+  end
+end