fireeagle 0.0.1

data/License.txt

@@ -0,0 +1,20 @@
+Copyright (c) 2007 Jesse Newland
+
+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/Manifest.txt

@@ -0,0 +1,19 @@
+History.txt
+License.txt
+Manifest.txt
+README.txt
+Rakefile
+lib/fireeagle.rb
+lib/fireeagle/application.rb
+lib/fireeagle/apibase.rb
+lib/fireeagle/base.rb
+lib/fireeagle/location.rb
+lib/fireeagle/user.rb
+lib/fireeagle/version.rb
+scripts/txt2html
+setup.rb
+test/test_fireeagle.rb
+test/test_fireeagle_application.rb
+test/test_fireeagle_location.rb
+test/test_fireeagle_user.rb
+test/test_helper.rb

data/README.txt

@@ -0,0 +1,20 @@
+FireEagle[http://fireeagle.research.yahoo.com/] (FE) is a system providing centralized management of user location information. FE allows 3rd party developers to update and/or access user's location data.
+
+== Installation
+
+ gem install fireeagle
+ 
+== Usage
+
+ require 'fireeagle'
+ f = FireEagle.new(:token => "foo", :secret => "bar")
+ user = FireEagle::User.new(f,"token")
+ l = FireEagle::Location.new(:country => "Belize")
+ user.location = l
+ user.location
+ =>  #<FireEagle::Location:0x15ba0d0 @details={:country=>"Belize"}>
+
+ Rubyforge Project Page:: http://rubyforge.org/projects/fireeagle
+ Author::    Jesse Newland (http://soylentfoo.jnewland.com) (jnewland@gmail.com[mailto:jnewland@gmail.com])
+ Copyright:: Copyright (c) 2007 Jesse Newland
+ License::   Distributes under the same terms as Ruby

data/Rakefile

@@ -0,0 +1,123 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/contrib/rubyforgepublisher'
+require 'fileutils'
+require 'hoe'
+
+include FileUtils
+require File.join(File.dirname(__FILE__), 'lib', 'fireeagle', 'version')
+
+AUTHOR = 'Jesse Newland'  # can also be an array of Authors
+EMAIL = "jnewland@gmail.com"
+DESCRIPTION = "Fire Eagle is a site that keeps track of your current location and helps you share it with other sites and services safely. There are hundreds of potential applications. This gem exposes the FireEagle API as Ruby Classes"
+GEM_NAME = 'fireeagle' # what ppl will type to install your gem
+
+@config_file = "~/.rubyforge/user-config.yml"
+@config = nil
+def rubyforge_username
+  unless @config
+    begin
+      @config = YAML.load(File.read(File.expand_path(@config_file)))
+    rescue
+      puts <<-EOS
+ERROR: No rubyforge config file found: #{@config_file}"
+Run 'rubyforge setup' to prepare your env for access to Rubyforge
+ - See http://newgem.rubyforge.org/rubyforge.html for more details
+      EOS
+      exit
+    end
+  end
+  @rubyforge_username ||= @config["username"]
+end
+
+RUBYFORGE_PROJECT = 'fireeagle' # The unix name for your project
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+DOWNLOAD_PATH = "http://rubyforge.org/projects/#{RUBYFORGE_PROJECT}"
+
+NAME = "fireeagle"
+REV = nil 
+# UNCOMMENT IF REQUIRED: 
+# REV = `svn info`.each {|line| if line =~ /^Revision:/ then k,v = line.split(': '); break v.chomp; else next; end} rescue nil
+VERS = FireEagle::VERSION::STRING + (REV ? ".#{REV}" : "")
+CLEAN.include ['**/.*.sw?', '*.gem', '.config', '**/.DS_Store']
+RDOC_OPTS = ['--quiet', '--title', 'fireeagle documentation',
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README",
+    "--inline-source"]
+
+class Hoe
+  def extra_deps 
+    @extra_deps.reject { |x| Array(x).first == 'hoe' } 
+  end 
+end
+
+# Generate all the Rake tasks
+# Run 'rake -T' to see list of generated tasks (from gem root directory)
+hoe = Hoe.new(GEM_NAME, VERS) do |p|
+  p.author = AUTHOR 
+  p.description = DESCRIPTION
+  p.email = EMAIL
+  p.summary = DESCRIPTION
+  p.url = HOMEPATH
+  p.rubyforge_name = RUBYFORGE_PROJECT if RUBYFORGE_PROJECT
+  p.test_globs = ["test/**/test_*.rb"]
+  p.clean_globs |= CLEAN  #An array of file patterns to delete on clean.
+  
+  # == Optional
+  p.changes = p.paragraphs_of("History.txt", 0..1).join("\n\n")
+  p.extra_deps = [['hpricot', '>= 0.5.145'] ]     # An array of rubygem dependencies [name, version], e.g. [ ['active_support', '>= 1.3.1'] ]
+  #p.spec_extras = {}    # A hash of extra values to set in the gemspec.
+end
+
+CHANGES = hoe.paragraphs_of('History.txt', 0..1).join("\n\n")
+PATH    = (RUBYFORGE_PROJECT == GEM_NAME) ? RUBYFORGE_PROJECT : "#{RUBYFORGE_PROJECT}/#{GEM_NAME}"
+hoe.remote_rdoc_dir = File.join(PATH.gsub(/^#{RUBYFORGE_PROJECT}\/?/,''), 'rdoc')
+
+desc 'Generate website files'
+task :website_generate do
+  Dir['website/**/*.txt'].each do |txt|
+    sh %{ ruby scripts/txt2html #{txt} > #{txt.gsub(/txt$/,'html')} }
+  end
+end
+
+desc 'Upload website files to rubyforge'
+task :website_upload do
+  host = "#{rubyforge_username}@rubyforge.org"
+  remote_dir = "/var/www/gforge-projects/#{PATH}/"
+  local_dir = 'website'
+  sh %{rsync -aCv #{local_dir}/ #{host}:#{remote_dir}}
+end
+
+desc 'Generate and upload website files'
+task :website => [:website_generate, :website_upload, :publish_docs]
+
+desc 'Release the website and new gem version'
+task :deploy => [:check_version, :website, :release] do
+  puts "Remember to create SVN tag:"
+  puts "svn copy svn+ssh://#{rubyforge_username}@rubyforge.org/var/svn/#{PATH}/trunk " +
+    "svn+ssh://#{rubyforge_username}@rubyforge.org/var/svn/#{PATH}/tags/REL-#{VERS} "
+  puts "Suggested comment:"
+  puts "Tagging release #{CHANGES}"
+end
+
+desc 'Runs tasks website_generate and install_gem as a local deployment of the gem'
+task :local_deploy => [:website_generate, :install_gem]
+
+task :check_version do
+  unless ENV['VERSION']
+    puts 'Must pass a VERSION=x.y.z release version'
+    exit
+  end
+  unless ENV['VERSION'] == VERS
+    puts "Please update your version.rb to match the release version, currently #{VERS}"
+    exit
+  end
+end
+
+

data/lib/fireeagle.rb

@@ -0,0 +1,65 @@
+%w[ cgi digest/sha1 net/http hpricot time ].each { |f| require f }
+
+class FireEagle#:nodoc:
+  API_DOMAIN = "fireeagle.research.yahoo.com"
+  API_PATH = "/api/"
+  DEBUG = false
+  
+  class Error < RuntimeError #:nodoc:
+  end
+
+  class ArgumentError < Error #:nodoc:
+  end
+  
+  class FireEagleException < Error #:nodoc:
+  end
+end
+
+require 'fireeagle/base'
+require 'fireeagle/apibase'
+require 'fireeagle/application'
+require 'fireeagle/user'
+require 'fireeagle/location'
+require 'fireeagle/version'
+
+#FireEagle additions to the <code>Hash</code> class
+class Hash
+  #Returns <code>true</code> if the ALL or NONE of the given keys are present in <i>hsh</i>.
+  def has_all_or_none_keys?(*my_keys)
+    size = my_keys.length
+    false_count = 0
+    my_keys.each do |k|
+      false_count += 1 unless keys.include?(k)
+    end
+    false_count == 0 or false_count == size
+  end
+  
+end
+
+#FireEagle additions to the <code>Object</code> class
+class Object
+  # A Ruby-ized realization of the K combinator, courtesy of Mikael Brockman.
+  #
+  #   def foo
+  #     returning values = [] do
+  #       values << 'bar'
+  #       values << 'baz'
+  #     end
+  #   end
+  #
+  #   foo # => ['bar', 'baz']
+  #
+  #   def foo
+  #     returning [] do |values|
+  #       values << 'bar'
+  #       values << 'baz'
+  #     end
+  #   end
+  #
+  #   foo # => ['bar', 'baz']
+  #
+  def returning(value)
+   yield(value)
+   value
+  end
+end

data/lib/fireeagle/apibase.rb

@@ -0,0 +1,6 @@
+class FireEagle::APIBase < FireEagle::Base #:nodoc:
+	def initialize(fireeagle)
+	   super(:token => fireeagle.token, :secret => fireeagle.secret)
+	   @fireeagle = fireeagle
+	end
+end

data/lib/fireeagle/application.rb

@@ -0,0 +1,29 @@
+class FireEagle::Application < FireEagle::APIBase
+  #A user must authorize (or grant permissions to) an application before the application can write or read the user's location. This authorization process begins by directing a user to the authorization page, where the user logs in and chooses which permissions to grant to the requesting application. The authorization page generates a user token, specific to the requesting application, which can be returned to the requesting application in several ways:
+  # 
+  #1. User token passed back to requesting application via callback URL (if the callback parameter is supplied)
+  #2. User token displayed onscreen (this is good for testing, but will likely be phased out or modified in the future)
+  #3. User token is exchanged at a later time (good for mobile devices where a user may not want to enter their Yahoo! username/password)
+  #   
+  def authorize_url(callback_url = "")
+    "http://#{FireEagle::API_DOMAIN}/authorize.php?appid=#{@fireeagle.token}&callback=#{CGI::escape(callback_url)}"
+  end
+
+  
+  #Applications which do not maintain a user repository (for example, a lightweight mobile application) may not wish to use the callback mechanism described above. These applications still must send users to authorize.php, but do not expect an immediate response (though at the moment, the authorize page will display the user token for easy testing and debugging). After the user has authorized an application, the application can later retrieve the user token in exchange for a short code obtained by the user from the Fire Eagle site. The user would retrieve a short code from the FE site and enter the code into the application which would then use the exchangeToken.php to exchange the short code for a full user token.
+  # 
+  #To obtain a short code users visit http://fireeagle.research.yahoo.com/displayToken.php?appid=TOKEN, where app token is the application token.
+  #
+  #Returnes an instance of FireEagle::User 
+  def exchange_token(shortcode = nil)
+    raise FireEagle::ArgumentError, "Shortcode required" if shortcode.nil?
+    request("exchangeToken", :shortcode => shortcode.to_s)
+  end
+  
+private
+  
+  def parse_response(doc)
+    raise FireEagle::FireEagleException, doc.at("/resultset/errormessage").innerText unless doc.at("/resultset").nil?
+    FireEagle::User.new_from_xml(@fireeagle, doc)
+  end
+end

data/lib/fireeagle/base.rb

@@ -0,0 +1,89 @@
+#The base class for interfacing w/ FireEagle
+#
+#  @fireeagle = Fireagle::Base.new(:token => "foo", :secret => "bar")
+#
+#Fire Eagle (FE) is a system providing centralized management of user location information. FE allows 3rd party developers to update and/or access user's location data.
+#
+#There are 3 data entities at Fire Eagle's core:
+# 
+#* User: Users can grant 3rd party applications privileges to read or write the user's location data. Users identify themselves to the FE system with their Yahoo! username/password. Applications identify a user with an application-specific user token (referred to in the API as a userid) generated by FE.
+#* Application: An application is identified by system-wide application token. Applications use this token (referred to in the API as an appid) and an application-specific secret to identify themselves to FE when reading or writing user location data.
+#* Location: FE stores the most recent location supplied by each application for each user. Applications can specify location in a number of ways: e.g. a latitude/longitude pair, a postal code, a street address, a GSM cell tower identifier, or an identifier from an external system (Plazes, Upcoming.org, etc.). See the Update API section for all possible location input options.
+# 
+#Only one location per user-application pair is stored, thus FE provides access only to a user's current location, not a location history of where the user has been. When a user's location is requested FE combines location info from one or more applications into a current best guess location record which is returned in XML format -- see the Query API Response section, below for details.
+class FireEagle::Base
+  
+  attr_reader :token, :secret
+  
+  #Create a new FireEagle::Base object.
+  #
+  # @fireeagle = Fireagle::Base.new(:token => "foo", :secret => "bar")
+  def initialize(options = {})
+    options = { :token => nil, :secret => nil }.merge(options)
+    raise FireEagle::ArgumentError, "Token and Secret required" if options[:token].nil? || options[:secret].nil?
+    @token = options[:token]
+    @secret = options[:secret]
+    @fireeagle = self
+  end
+  
+  # Return an instance of FireEagle::Application
+  def application() @application ||= FireEagle::Application.new(self) end
+
+private
+
+  # do the required api signing
+  def encode_and_sign(params = {})
+
+    #check for the params
+    raise ArgumentError, "Params required" if params == {} || !params.is_a?(Hash)
+
+    #remove any provided sig
+    params.delete(:sig)
+
+    #add the app token id
+    params[:appid] = @fireeagle.token
+
+    #sort and URL encode the params
+    normalized_params = {}
+    params.each_pair { |name, value| normalized_params[name.to_s] = value.to_s }
+
+    #build the string to sign
+    sig = "#{@fireeagle.secret}"
+    normalized_params.sort.each { |name, value| sig << "#{name}#{value}" } 
+
+    #sign it
+    normalized_params['sig'] = Digest::SHA1.hexdigest(sig)
+
+    #create and return the request string
+    request_string = "?" + normalized_params.sort.collect { |name, value| "#{name}=#{CGI::escape(value)}" }.join('&')
+  end
+
+  # request method which is used by all public methods
+  def request(action = nil,params = {})
+    raise ArgumentError, "Action name required" if action.nil?
+
+    #reject crap
+    params.reject { |key, value| value.nil? or (value.is_a?(String) and value.empty?)}
+    #merge timestamp
+    params.merge!( { :timestamp => Time.now.to_i } )
+
+    path = "#{FireEagle::API_PATH}#{action}.php#{encode_and_sign(params)}"
+    
+    puts path if FireEagle::DEBUG
+
+    response = Net::HTTP.get_response(FireEagle::API_DOMAIN, path)
+    
+    parse_response(Hpricot(response.body))   
+  end
+  
+  def parse_response(doc)
+    raise FireEagleException, doc.at("/resultset/errormessage").innerText unless !doc.at("/resultset").nil? and doc.at("/resultset/error").innerText.to_i == "0"
+    doc.at("/result")
+  end
+  
+  def fireeagle
+    fireeagle
+  end
+  
+  
+end

data/lib/fireeagle/location.rb

@@ -0,0 +1,74 @@
+#Describes a location
+class FireEagle::Location
+  
+  DETAILS = :locale, :quality, :updatetime, :latitute, :longitude, :offsetlat, :offsetlon, 
+              :radius, :boundinglatnorth, :boundinglatsouth, :boundinglateast, :boundinglatwest,
+              :name, :line1, :line2, :line3, :line4, :house, :street, :xstreet, :unittype, :unit,
+              :neighborhood, :city, :county, :state, :country, :coutrycode, :statecode, :countrycode,
+              :timezone, 
+              # attributes used only on update
+              :source, :addr, :mcn, :mcc, :lac, :cellid, :loc, :name, :woeid, :plazesid, 
+              :upvenueid, :street1, :street2
+  
+  attr_reader :details
+  
+  #Create an instance of FireEagle::Location. There are some specific requirements for combinations of elements in the <code>options</code> Hash:
+  #
+  #* Requires all or none of :lat, :long
+  #* Requires all or none of :mnc, :mcc, :lac, :cellid
+  #* Requires all or none of :street1, :street2
+  #* Requires :postal or :city with :street1 and :street2
+  #* Requires :city or :postal with :addr
+  #* Requires :state, :country, or :postal with :city
+  #* Requires :country with :postal if not in US
+  def initialize(options = {}, verify_attributes = true)
+    option = options.reject { |key, value| DETAILS.include?(key) }
+    
+    if verify_attributes
+      raise FireEagle::ArgumentError, "Requires all or none of :lat, :long" unless options.has_all_or_none_keys?(:lat, :long)
+      raise FireEagle::ArgumentError, "Requires all or none of :mnc, :mcc, :lac, :cellid" unless options.has_all_or_none_keys?(:mnc, :mcc, :lac, :cellid)
+      raise FireEagle::ArgumentError, "Requires all or none of :street1, :street2" unless options.has_all_or_none_keys?(:street1, :street2)
+      raise FireEagle::ArgumentError, "Requires :postal or :city with :street1 and :street2" if (options.has_key?(:street1) and options.has_key?(:street2)) and !(options.has_key?(:city) or options.has_key?(:postal))
+      raise FireEagle::ArgumentError, "Requires :city or :postal with :addr" if options.has_key?(:addr) and !(options.has_key?(:city) or options.has_key?(:postal))
+      raise FireEagle::ArgumentError, "Requires :state, :country, or :postal with :city" if options.has_key?(:city) and !(options.has_key?(:state) or options.has_key?(:country) or options.has_key?(:postal))
+      raise FireEagle::ArgumentError, "Requires :country with :postal if not in US" if (options.has_key?(:postal) and options.has_key?(:country)) and (options[:country] != "US")
+    end
+    
+    @details = options
+  end
+  
+  class << self
+    #Create a new instance of FireEagle::Location from the XML returned from Yahoo!
+    def new_from_xml(doc)
+      #build the massive hash needed for a location
+      options = { }
+      doc = doc.at("/resultset")
+      options[:locale] = doc.at("locale").innerText unless doc.at("locale").nil?
+      # quick parse of the xml
+      puts doc if FireEagle::DEBUG
+      doc.at("result").containers.each do |attribute| 
+        options[attribute.xpath.split("/")[-1].to_sym] = attribute.inner_text unless attribute.nil?
+      end
+      #fixup types
+      options[:updatetime] = Time.parse(options[:updatetime])
+      options[:radius] = options[:radius].to_i
+      options[:quality] = options[:radius].to_i
+      %w(latitude longitude offsetlat offsetlon :boundinglatnorth boundinglatsouth boundinglateast boundinglatwest).each do |attribute|
+        options[attribute.to_sym].nil? || options[attribute.to_sym].empty? ? (options[attribute.to_sym] = '') : (options[attribute.to_sym] = options[attribute.to_sym].to_f)
+      end
+      
+      FireEagle::Location.new(options, false)
+    end
+  end
+
+private
+  
+  def verify_attribute_combination(options, *args)
+    args.each do |a|
+      return false unless options.include?(a)
+    end
+    return true
+  end
+  
+  
+end