fireeagle 0.0.2 → 0.6.0

data/lib/fireeagle/location.rb

@@ -1,74 +1,70 @@
 #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")
+class FireEagle
+  class Location
+
+    #Initialize a Location from an XML response
+    def initialize(doc)
+      doc = Hpricot(doc) unless doc.is_a?(Hpricot::Doc || Hpricot::Elem)
+      @doc = doc
+    end
+
+    def label
+      @label ||= @doc.at("/location/label").innerText rescue nil
+    end
+
+    #Level of granularity for this Location
+    def level
+      @level ||= @doc.at("/location/level").innerText.to_i rescue nil
+    end
+
+    #Name of the level of granularity for this Location
+    def level_name
+      @level_name ||= @doc.at("/location/level-name").innerText rescue nil
+    end
+
+    #Human Name for this Location
+    def name
+      @name ||= @doc.at("/location/name").innerText rescue nil
+    end
+    alias_method :to_s, :name
+
+    #Unique identifier for this place. Pro-tip: This is the same place_id used by Flickr.
+    def place_id
+      @place_id ||= @doc.at("/location/place-id").innerText rescue nil
     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)
+    #Numeric unique identifier for this place.
+    def woeid
+      @woeid ||= @doc.at("/location/woeid").innerText rescue nil
+    end
+
+    #The Time at which the User last updated in this Location
+    def located_at
+      @located_at ||= Time.parse(@doc.at("/location/located-at").innerText) rescue nil
     end
-  end
 
-private
-  
-  def verify_attribute_combination(options, *args)
-    args.each do |a|
-      return false unless options.include?(a)
+    #The coordinates of the lower corner of a bounding box surrounding this Location
+    def lower_corner
+      @georss ||= @doc.at("/location//georss:box").innerText.split.map{ |l| l.to_f } rescue nil
+      @lower_corner ||= @georss[0..1] rescue nil
     end
-    return true
+
+    # The GeoRuby[http://georuby.rubyforge.org/] representation of this location
+    def geom
+      if @doc.at("/location//georss:box")
+        @geo ||= GeoRuby::SimpleFeatures::Geometry.from_georss(@doc.at("/location//georss:box").to_s)
+      elsif @doc.at("/location//georss:point")
+        @geo ||= GeoRuby::SimpleFeatures::Geometry.from_georss(@doc.at("/location//georss:point").to_s)
+      else
+        return nil
+      end
+    end
+    alias_method :geo, :geom
+    
+    #Is this Location FireEagle's best guess?
+    def best_guess?
+      @best_guess ||= @doc.at("/location").attributes["best-guess"] == "true" rescue false
+    end
+
   end
-  
-  
 end

data/lib/fireeagle/response.rb

@@ -0,0 +1,31 @@
+class FireEagle
+  class Response
+
+    #Parses the XML response from FireEagle
+    def initialize(doc)
+      doc = Hpricot(doc) unless doc.is_a?(Hpricot::Doc || Hpricot::Elem)
+      @doc = doc
+      raise FireEagle::FireEagleException, @doc.at("/rsp/err").attributes["msg"] if !success? 
+    end
+
+    #does the response indicate success?
+    def success?
+      @doc.at("/rsp").attributes["stat"] == "ok" rescue false
+    end
+
+    #An array of of User-specific tokens and their Location at all levels the Client can see and larger.
+    def users
+      @users ||= @doc.search("/rsp//user").map do |user|
+        FireEagle::User.new(user.to_s)
+      end
+    end
+
+    #A Location array.
+    def locations
+      @locations ||= @doc.search("/rsp/locations/location").map do |location|
+        FireEagle::Location.new(location.to_s)
+      end
+    end
+
+  end
+end

data/lib/fireeagle/user.rb

@@ -1,39 +1,33 @@
-class FireEagle::User < FireEagle::APIBase
-  attr_reader :token
-  
-  #Create a new instance of FireEagle::User. Requires a FireEagle::Base object, and the users app-specific token 
-  def initialize(fireeagle, token)
-    super(fireeagle)
-    @fireeagle = fireeagle
-    @token = token.to_s
-  end
-  
-  class << self
-    #Create a new instance of FireEagle::User from the XML returned from Yahoo!
-    def new_from_xml(fireeagle, doc)
-      FireEagle::User.new(fireeagle, doc.at("/rsp/token").innerText)
+class FireEagle
+  class User
+
+    #Parses the XML response from FireEagle.
+    def initialize(doc)
+      doc = Hpricot(doc) unless doc.is_a?(Hpricot::Doc || Hpricot::Elem)
+      @doc = doc
     end
-  end
-  
-  #Returns a FireEagle::Location instance describing the User's current location
-  def location
-    request("queryLoc", :userid => self.token)
-  end
-  
-  #Sets the User's location to that described in an FireEagle::Location object
-  def location=(location)
-    raise FireEagle::ArgumentError, "FireEagle::Location required" unless location.is_a?(FireEagle::Location)
-    returning(location) do
-      request("updateLoc", location.details.merge(:userid => self.token))
+
+    #The User-specific token for this Client.
+    def token
+      @token ||= @doc.at("/user").attributes["token"] rescue nil
+    end
+
+    #FireEagle's "best guess" form this User's Location. This best guess is derived as the most accurate
+    #level of the hierarchy with a timestamp in the last half an hour <b>or</b> as the most accurate
+    #level of the hierarchy with the most recent timestamp.
+    def best_guess
+      @best_guess ||= locations.select { |location| location.best_guess? }.first rescue nil
+    end
+
+    #An Array containing all Location granularity that the Client has been allowed to
+    #see for the User. The Location elements returned are arranged in hierarchy order consisting of: 
+    #Country, State, County, Large Cities, Neighbourhoods/Local Area, Postal Code and exact location.
+    #The Application should therefore be prepared to receive a response that may consist of (1) only
+    #country, or (2) country & state or (3) country, state & county and so forth.
+    def locations
+      @locations ||= @doc.search("/user/location-hierarchy/location").map do |location|
+        FireEagle::Location.new(location.to_s)
+      end
     end
   end
-  
-private
-  
-  def parse_response(doc)
-    raise FireEagle::FireEagleException, doc.at("/resultset/errormessage").innerText if doc.at("/resultset/error").innerText.to_i != 0
-    return if doc.at("/resultset/result").nil? 
-    FireEagle::Location.new_from_xml(doc)
-  end
-  
 end

data/lib/fireeagle/version.rb

@@ -1,8 +1,8 @@
 class FireEagle #:nodoc:
   module VERSION #:nodoc:
     MAJOR = 0
-    MINOR = 0
-    TINY  = 2
+    MINOR = 6
+    TINY  = 0
 
     STRING = [MAJOR, MINOR, TINY].join('.')
   end

data/spec/fireeagle_location_spec.rb

@@ -0,0 +1,60 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe "FireEagle Location" do
+
+  before(:each) do
+    location = Hpricot.XML(XML_LOCATION_CHUNK)
+    @location = FireEagle::Location.new(location)
+  end
+
+  it "should know if this is a best guess" do
+    @location.best_guess?.should == false
+  end
+
+  it "should represent the level" do
+    @location.level.should == 3
+  end
+
+  it "should represent the level name" do
+    @location.level_name.should == 'city'
+  end
+
+  it "should represent the location name" do
+    @location.name.should == 'Davis, CA'
+  end
+
+  it "should represent the location place id" do
+    @location.place_id.should == 'u4L9ZOObApTdx1q3'
+  end
+
+  it "should represent the location's timestamp" do
+    @location.located_at.should == Time.parse("2008-01-22T14:23:11-08:00")
+  end
+  
+  it "should use the name for #to_s" do
+    @location.to_s.should == @location.name
+  end
+
+  describe "GeoRuby support" do
+
+    it "should represent a bounding box as a GeoRuby Envelope" do
+      location = Hpricot.XML(XML_LOCATION_CHUNK)
+      @location = FireEagle::Location.new(location)
+      @location.geom.class.should == GeoRuby::SimpleFeatures::Envelope
+    end
+
+    it "should represent an exact point as a GeoRuby Point" do
+      location = Hpricot.XML(XML_EXACT_LOCATION_CHUNK)
+      @location = FireEagle::Location.new(location)
+      @location.geom.class.should == GeoRuby::SimpleFeatures::Point
+    end
+
+    it "should be aliased as 'geo'" do
+      location = Hpricot.XML(XML_EXACT_LOCATION_CHUNK)
+      @location = FireEagle::Location.new(location)
+      @location.geo.class.should == GeoRuby::SimpleFeatures::Point     
+    end
+
+  end
+
+end

data/spec/fireeagle_response_spec.rb

@@ -0,0 +1,65 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe "FireEagle Response" do
+
+  describe "user / location parsing" do
+
+    before(:each) do
+      @response = FireEagle::Response.new(XML_LOCATION_RESPONSE)
+    end
+    
+    it "should indicate success" do
+      @response.success?.should == true
+    end
+
+    it "should have an array of users" do
+      @response.users.size.should == 1
+    end
+    
+    it "should have each users' token" do
+      @response.users.first.token.should == "16w3z6ysudxt"
+    end
+    
+    it "should flag the best guess" do
+      @response.users.first.best_guess.name.should == "Yolo County, California"
+    end
+    
+    it "should have users' loactions" do
+      @response.users.first.locations.size.should == 4
+    end
+
+  end
+  
+  describe "location parsing" do
+
+    before(:each) do
+      @response = FireEagle::Response.new(XML_LOOKUP_RESPONSE)
+    end
+
+    it "should indicate success" do
+      @response.success?.should == true
+    end
+
+    it "should have an array of locations" do
+      @response.locations.size.should == 9
+    end
+
+    it "should have each location's place_id" do
+      @response.locations.first.place_id.should == "IrhZMHuYA5s1fFi4Qw"
+    end
+
+    it "should have each location's name" do
+      @response.locations.first.name.should == "Alpharetta, GA 30022"
+    end
+
+  end
+
+  describe "error handling" do
+
+    it "should raise an exception when returned xml with a status of fail" do
+      lambda { FireEagle::Response.new(XML_ERROR_RESPONSE) }.should raise_error(FireEagle::FireEagleException)
+    end
+
+  end
+
+end

data/spec/fireeagle_spec.rb

@@ -0,0 +1,150 @@
+require File.dirname(__FILE__) + '/spec_helper.rb'
+
+describe "FireEagle" do
+
+  describe "being initialized" do
+
+    it "should require OAuth Consumer Key and Secret" do
+      lambda do
+        client = FireEagle::Client.new({})
+      end.should raise_error(FireEagle::ArgumentError)
+    end
+
+    it "should initialize an OAuth::Consumer" do
+      @consumer = mock(OAuth::Consumer)
+      OAuth::Consumer.should_receive(:new).and_return(@consumer)
+      client = FireEagle::Client.new(:consumer_key => 'key', :consumer_secret => 'sekret')
+    end
+
+  end
+
+  describe "web app authentication scenario" do
+
+    it "should initialize a OAuth::Token if given it's token and secret" do
+      @access_token = mock(OAuth::Token)
+      OAuth::Token.stub!(:new).and_return(@access_token)
+      client = FireEagle::Client.new(:consumer_key => 'key', :consumer_secret => 'sekret', :access_token => 'toke', :access_token_secret => 'sekret')
+      client.access_token.should == @access_token
+    end
+
+    it "should initialize a request token if given one" do
+      @request_token = mock(OAuth::Token)
+      OAuth::Token.stub!(:new).and_return(@request_token)
+      client = FireEagle::Client.new(:consumer_key => 'key', :consumer_secret => 'sekret', :request_token => 'toke', :request_token_secret => 'sekret')
+      client.request_token.should == @request_token
+    end
+  end
+
+  describe "request token scenario" do
+    it "shouldn't initialize with a access_token" do
+      client = FireEagle::Client.new(:consumer_key => 'key', :consumer_secret => 'sekret')
+      client.access_token.should == nil
+    end
+
+    it "should require token exchange before calling any API methods" do
+      client = FireEagle::Client.new(:consumer_key => 'key', :consumer_secret => 'sekret')
+      lambda do
+        client.user
+      end.should raise_error(FireEagle::ArgumentError)
+    end
+
+    it "should generate a Request Token URL" do
+      client = FireEagle::Client.new(:consumer_key => 'key', :consumer_secret => 'sekret')
+      @token = mock("token", :token => 'foo')
+      client.stub!(:get).and_return('')
+      client.stub!(:create_token).and_return(@token)
+      client.get_request_token
+      client.authorization_url.should =~ /\?oauth_token=foo/
+    end
+
+    it "should require #get_request_token be called before #convert_to_access_token" do
+      lambda do
+        client = FireEagle::Client.new(:consumer_key => 'key', :consumer_secret => 'sekret')
+        client.convert_to_access_token
+      end.should raise_error(FireEagle::ArgumentError)
+    end
+
+    it "should require #get_request_token be called before #authorization_url" do
+      lambda do
+        client = FireEagle::Client.new(:consumer_key => 'key', :consumer_secret => 'sekret')
+        client.authorization_url
+      end.should raise_error(FireEagle::ArgumentError)
+    end
+
+    it "should generate a Request Token URL" do
+      client = FireEagle::Client.new(:consumer_key => 'key', :consumer_secret => 'sekret')
+      @token = mock("token", :token => 'foo')
+      client.stub!(:get).and_return('')
+      client.stub!(:create_token).and_return(@token)
+      client.get_request_token
+      client.convert_to_access_token
+      client.access_token.should == @token
+    end
+
+  end
+
+  describe "update method" do
+
+    before(:each) do
+      @client = FireEagle::Client.new(:consumer_key => 'key', :consumer_secret => 'sekret', :access_token => 'toke', :access_token_secret => 'sekret')
+      @response = mock('response', :body => XML_SUCCESS_RESPONSE)
+      @client.stub!(:request).and_return(@response)
+    end
+
+    it "requires all or none of :lat, :lon" do
+      lambda { @client.update(:lat => 1) }.should raise_error(FireEagle::ArgumentError)
+      lambda { @client.update(:lat => 1, :lon => 2) }.should_not raise_error(FireEagle::ArgumentError)
+    end
+
+    it "requires all or none of :mnc, :mcc, :lac, :cid" do
+      lambda { @client.update(:mcc => 123, :lac => "whatever", :cid => true) }.should raise_error(FireEagle::ArgumentError)
+      lambda { @client.update(:mcc => 123, :mnc => 123123, :lac => "whatever", :cid => true) }.should_not raise_error(FireEagle::ArgumentError)
+    end
+
+    it "should wrap the result" do
+      @client.update(:mcc => 123, :mnc => 123123, :lac => "whatever", :cid => true).users.first.token.should == "16w3z6ysudxt"
+    end
+
+  end
+
+  describe "user method" do
+
+    before(:each) do
+      @client = FireEagle::Client.new(:consumer_key => 'key', :consumer_secret => 'sekret', :access_token => 'toke', :access_token_secret => 'sekret')
+      @response = mock('response', :body => XML_LOCATION_RESPONSE)
+      @client.stub!(:request).and_return(@response)
+    end
+
+    it "should return a best guess" do
+      @client.user.best_guess.name.should == "Yolo County, California"
+    end
+
+    it "should return several locations" do
+      @client.user.locations.size.should == 4
+    end
+
+  end
+  
+  describe "lookup method" do
+
+    before(:each) do
+      @client = FireEagle::Client.new(:consumer_key => 'key', :consumer_secret => 'sekret', :access_token => 'toke', :access_token_secret => 'sekret')
+      @response = mock('response', :body => XML_LOOKUP_RESPONSE)
+      @client.stub!(:request).and_return(@response)
+    end
+
+    it "should return an array of Locations" do
+      @client.lookup(:q => "30022").size.should == 9
+    end
+
+    it "should return a place id for each" do
+      @client.lookup(:q => "30022").first.place_id.should == "IrhZMHuYA5s1fFi4Qw"
+    end
+
+    it "should return a name for each" do
+      @client.lookup(:q => "30022").first.name.should == "Alpharetta, GA 30022"
+    end
+
+  end
+
+end