oodler 0.0.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 Mike Hagedorn
+
+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.markdown

@@ -0,0 +1,58 @@
+# Oodler
+
+Ruby wrapper for the [Oodle API](http://developer.oodle.com). Heavily inspired by [Wynn Nederlands's](http://github.com/pengwynn) [LinkedIn gem](http://github.com/pengwynn/linkedin), the Oodler gem provides an easy-to-use wrapper for Oodles's XML APIs.
+
+## Installation
+
+    sudo gem install gemcutter
+    gem tumble
+    sudo gem install oodler
+    
+## Usage
+
+### Authenticate
+
+Ooodle's API uses  a key for authentication, you can get a key at http://developer.oodle.com/request-api-key/
+
+    require 'rubygems'
+    require 'oodler'
+
+    # get your api keys at https://www.linkedin.com/secure/developer
+    client = Oodler::Client.new("YOURAPIKEY")
+
+### Listing examples
+
+    # get the profile for the authenticated user
+    result = client.listing({:region => "chicago",:category => "vehicle/car"})
+
+    puts result.listings[0].id
+    puts result.listings[0].title
+    puts result.listings[0].id
+    puts result.listings[0].body
+    puts result.listings[0].url
+    puts result.listings[0].images[0].src
+
+    ..etc
+
+
+    
+
+
+ TODO
+
+* Nothing yet
+
+## Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but
+   bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+## Copyright
+
+Copyright (c) 2010 [Mike Hagedorn](http://silverchairsolutions.com). See LICENSE for details.

data/Rakefile

@@ -0,0 +1,64 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "oodler"
+    gem.summary = %Q{Ruby wrapper for the Oodle API}
+    gem.description = %Q{Ruby wrapper for the Oodle API}
+    gem.email = "mike@silverchairsolutions.com"
+    gem.homepage = "http://github.com/mwhagedorn/oodler"
+    gem.authors = ["Mike Hagedorn"]
+    gem.files   = FileList["[A-Z]*", "{lib,test}/**/*"]
+    
+    
+    gem.add_dependency('roxml', '~> 3.1.3')
+    gem.add_dependency('crack', '~> 0.1.4')
+
+    gem.add_development_dependency('shoulda', '>= 2.10.1')
+    gem.add_development_dependency('jnunemaker-matchy', '0.4.0')
+    gem.add_development_dependency('mocha', '0.9.4')
+    gem.add_development_dependency('fakeweb', '>= 1.2.5')
+    gem.add_development_dependency("httparty", ">= 0.5.2")
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler"
+end
+
+require 'rake/testtask'
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'test'
+  test.ruby_opts << '-rubygems'
+  test.pattern = 'test/**/*_test.rb'
+  test.verbose = true
+end
+
+begin
+  require 'rcov/rcovtask'
+  Rcov::RcovTask.new do |test|
+    test.libs << 'test'
+    test.pattern = 'test/**/test_*.rb'
+    test.verbose = true
+  end
+rescue LoadError
+  task :rcov do
+    abort "RCov is not available. In order to run rcov, you must: sudo gem install spicycode-rcov"
+  end
+end
+
+task :test => :check_dependencies
+
+task :default => :test
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "oodler #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.0.1

data/examples/listings.rb

@@ -0,0 +1,18 @@
+require 'rubygems'
+require 'oodler'
+
+# get your api keys at http://developer.oodle.com/request-api-key
+client = Oodler::Client.new('your_api_key')
+
+
+
+#most generic
+
+client.listing({:region =>"chicago", :category=>"vehicle/cars"})
+
+#other formulations of same search
+client.search("chicago", {:category => "vehicle/cars"})
+client.search_by_category("chicago",  "vehicle/cars",{})
+
+#adding criteria
+

data/lib/oodler/category.rb

@@ -0,0 +1,9 @@
+module Oodler
+  class Category
+    include ROXML
+      xml_reader :id
+      xml_reader :name
+      xml_reader :abbrev
+  end
+  
+end

data/lib/oodler/client.rb

@@ -0,0 +1,78 @@
+module Oodler
+  class Client
+    include HTTParty
+    
+    attr_reader :key, :http_options
+    
+    def initialize(key=Oodle.key,options={})
+      @key, @http_options = key,options
+    end
+    
+    def web_client
+        @web_client ||= Oodler::WebClient.new(@key)
+    end
+   
+    
+    def get(path, options={})
+      path = "/listings#{path}"
+      validate_parameters(options)
+      response = web_client.get(path, options)
+      raise_errors(response)
+      response.body
+    end
+
+    #client.search("chicago", {:category =>"vehicle/cars"})
+    def search( region, options={})
+      path = ""
+
+      options= {:query =>options}
+      options[:query].merge!({:region => region}) if region
+      
+      OodleResponse.from_xml(get(path, options))
+    end
+
+    #helper method - client.search_by_category("chicago", "vehicle/car")
+    def search_by_category(region,category, options={})
+      path=""
+      options= {:query =>options}
+      options[:query].merge!({:region => region}) if region
+      options[:query].merge!({:category => category}) if category
+
+      OodleResponse.from_xml(get(path, options))
+
+    end
+    
+
+    #the generic pash a hash version
+    #example client.listing(:region=>"chicago", :category => "vehicle/car")
+    #returns an OodleResponse
+    def listing(options={})
+      path = ""
+      options= {:query =>options}
+      OodleResponse.from_xml(get(path, options))
+    end
+    
+    private
+        
+      def validate_parameters(options)
+        params = options[:query]
+        unless params[:region]
+          raise OodleArgumentError, 'Missing region paramter. Visit http://developer.oodle.com/regions-list/ for possible regions.'
+        end
+        unless params[:category] || options[:q]
+          raise OodleArgumentError, 'You must supply a category or query parameter. Visit http://developer.oodle.com/categories-list/ for possible categories.'
+        end
+      end
+
+      def raise_errors(response)
+        if response["oodle_response"]["error"]
+          data = response["oodle_response"]["error"]
+          raise OodlerError.new(data), "(fail: #{data}"
+        end
+
+      end
+
+      
+
+  end
+end

data/lib/oodler/element.rb

@@ -0,0 +1,19 @@
+module Oodler
+  class Element
+    include ROXML
+    xml_reader :id
+    xml_reader :title
+    xml_reader :body
+    xml_reader :url
+    xml_reader :category, :as => Category
+    xml_reader :source, :as => Source
+    xml_reader :location, :as => Location
+    xml_reader :images, :as => [Image], :in =>"images"
+    xml_reader :ctime
+    xml_reader :paid?
+    xml_reader :revenue_score
+    xml_reader :similar_url
+    xml_reader :properties ,:as => {:key => :name,:value => :content}, :in => "attributes"
+    
+  end
+end

data/lib/oodler/image.rb

@@ -0,0 +1,12 @@
+module Oodler
+  class Image
+    include ROXML
+    xml_name :element
+    xml_reader :src
+    xml_reader :width
+    xml_reader :height
+    xml_reader :alt
+    
+    
+  end
+end

data/lib/oodler/location.rb

@@ -0,0 +1,15 @@
+module Oodler
+  class Location
+    include ROXML
+    xml_reader :latitude
+    xml_reader :longitude
+    xml_reader :address
+    xml_reader :zip
+    xml_reader :addresscode
+    xml_reader :citycode
+    xml_reader :name
+    xml_reader :state
+    xml_reader :country
+    
+  end
+end

data/lib/oodler/oodle_response.rb

@@ -0,0 +1,17 @@
+module Oodler
+  class OodleResponse
+    include ROXML
+    xml_reader :region, :as => Region, :in => "current"
+    xml_reader :category, :as => Category, :in => "current"
+    xml_reader :elements, :as =>[Element], :in => "listings"
+    xml_reader :start, :in =>"current"
+    xml_reader :num, :in => "current"
+    xml_reader :stat, :from => :attr
+    xml_reader :error
+
+    def listings
+      elements
+    end
+  end
+
+end

data/lib/oodler/region.rb

@@ -0,0 +1,7 @@
+module Oodler
+  class Region
+    include ROXML
+    xml_reader :id
+    xml_reader :name 
+  end
+end

data/lib/oodler/source.rb

@@ -0,0 +1,9 @@
+module Oodler
+  class Source
+    include ROXML
+    xml_reader :id
+    xml_reader :name
+    
+    
+  end
+end

data/lib/oodler/web_client.rb

@@ -0,0 +1,27 @@
+module Oodler
+  class WebClient
+     include HTTParty
+     
+     attr_accessor :key
+     base_uri 'api.oodle.com/api/v2/'
+     format :xml
+     
+     def initialize(key=nil)
+       @key = key
+     end
+
+     def get(path,options)
+       options[:query].merge!({:key => @key}) if @key
+       validate_parameters(options)
+       self.class.get(path,options)
+     end
+
+  private
+    def validate_parameters(options)
+        params = options[:query]
+        unless params[:key]
+          raise OodleArgumentError, 'Missing API key parameter. Visit http://developer.oodle.com/request-api-key/ to get one'
+        end
+    end
+  end
+end

data/lib/oodler.rb

@@ -0,0 +1,66 @@
+
+require 'rubygems'
+
+gem 'roxml', '~> 3.1.3'
+require 'roxml'
+
+gem 'crack', '~> 0.1.4'
+require 'crack'
+
+gem 'httparty'
+require 'httparty'
+
+require 'cgi'
+
+module Oodler
+  class OodlerError < StandardError
+    attr_reader :data
+
+    def initialize(data)
+      @data = data
+      super
+    end
+  end
+  
+  class OodleArgumentError <OodlerError; end
+
+  
+  
+  # config/initializers/oodler.rb (for instance)
+  # 
+  # Oodler.configure do |config|
+  #   config.key = 'api_key'
+  # end
+  # 
+  # elsewhere
+  #
+  # client = Oodler::Client.new
+  def self.configure
+    yield self
+      
+    Oodler.key = key
+    true
+  end
+  
+  def self.key
+    @key
+  end
+  
+  def self.key=(key)
+    @key = key
+  end
+  
+  
+end
+
+directory = File.expand_path(File.dirname(__FILE__))
+require File.join(directory, "oodler", 'category')
+require File.join(directory, "oodler", 'region')
+require File.join(directory, 'oodler', 'web_client')
+require File.join(directory, 'oodler', 'location')
+require File.join(directory, 'oodler', 'image')
+require File.join(directory, 'oodler', 'source')
+require File.join(directory, 'oodler', 'category')
+require File.join(directory, 'oodler', 'element')
+require File.join(directory, 'oodler', 'oodle_response')
+require File.join(directory, 'oodler', 'client')

data/test/client_test.rb

@@ -0,0 +1,137 @@
+require 'test_helper'
+require 'test_helper'
+
+class ClientTest < Test::Unit::TestCase
+  context "when hitting the Oodle API" do
+    setup do
+      @oodler = Oodler::Client.new('key')
+    end
+    should "have a web client" do
+      stub_get("/listings?region=chicago&category=vehicle%2fcar&key=key", "listings.xml")
+      wc = mock('webclient')
+
+      Oodler::WebClient.expects(:new).with('keyval').returns(wc)
+      @oodler = Oodler::Client.new('keyval')
+
+      @oodler.web_client.should == wc
+
+    end
+
+   context "and a region is not provided" do
+      should "throw an error" do
+        stub_get("/v2/listings?region=chicago&category=vehicle%2Fcar&key=key", "listings.xml")
+        assert_raise(Oodler::OodleArgumentError)  do
+          @oodler.search(nil, {:category=>"vehicle/car"})
+        end
+
+      end
+   end
+
+    should "retrieve a listing" do
+     stub_get("/api/v2/listings?key=key&region=chicago&category=vehicle%2Fcars", "listings.xml")
+     p = @oodler.search("chicago", {:category => "vehicle/cars"})
+
+     p.region.id.should == "chicago"
+     p.region.name.should == "Chicago"
+     p.category.id.should == "vehicle/car"
+     p.start.should == "1"
+     p.listings.size.should == 10
+     p.listings[0].id.should == "1899168373"
+     p.listings[0].title.should == "2002 Mazda Tribute"
+     p.listings[0].category.name.should == "SUVs"
+     p.listings[0].source.name.should == "EveryCarListed.com"
+     p.listings[0].location.zip.should == "60453"
+     p.listings[0].images.size.should == 2
+     p.listings[0].images[0].src.should == "http://i.oodleimg.com/item/1899168373_1m?1271098477"
+     p.listings[0].paid?.should == true
+     p.listings[0].properties.should_not == nil
+     p.listings[0].properties["color"].should == "Grey"
+    end
+
+     should "retrieve a listing using convenience  method" do
+       stub_get("/api/v2/listings?key=key&region=chicago&category=vehicle%2Fcars", "listings.xml")
+       p = @oodler.search_by_category("chicago", "vehicle/cars")
+
+       p.region.id.should == "chicago"
+       p.region.name.should == "Chicago"
+       p.category.id.should == "vehicle/car"
+       p.start.should == "1"
+       p.listings.size.should == 10
+       p.listings[0].id.should == "1899168373"
+       p.listings[0].title.should == "2002 Mazda Tribute"
+       p.listings[0].category.name.should == "SUVs"
+       p.listings[0].source.name.should == "EveryCarListed.com"
+       p.listings[0].location.zip.should == "60453"
+       p.listings[0].images.size.should == 2
+       p.listings[0].images[0].src.should == "http://i.oodleimg.com/item/1899168373_1m?1271098477"
+       p.listings[0].paid?.should == true
+       p.listings[0].properties.should_not == nil
+       p.listings[0].properties["color"].should == "Grey"
+     end
+    context "when using the listing method " do
+      should "retrieve a listing " do
+        stub_get("/api/v2/listings?key=key&region=chicago&category=vehicle%2Fcars", "listings.xml")
+        p = @oodler.listing({:region =>"chicago", :category=>"vehicle/cars"})
+
+        p.region.id.should == "chicago"
+        p.region.name.should == "Chicago"
+        p.category.id.should == "vehicle/car"
+        p.start.should == "1"
+        p.listings.size.should == 10
+        p.listings[0].id.should == "1899168373"
+        p.listings[0].title.should == "2002 Mazda Tribute"
+        p.listings[0].category.name.should == "SUVs"
+        p.listings[0].source.name.should == "EveryCarListed.com"
+        p.listings[0].location.zip.should == "60453"
+        p.listings[0].images.size.should == 2
+        p.listings[0].images[0].src.should == "http://i.oodleimg.com/item/1899168373_1m?1271098477"
+        p.listings[0].paid?.should == true
+        p.listings[0].properties.should_not == nil
+        p.listings[0].properties["color"].should == "Grey"
+      end
+
+      should "throw an error with empty hash" do
+        stub_get("/api/v2/listings?key=key&region=chicago&category=vehicle%2Fcars", "listings.xml")
+        assert_raise(Oodler::OodleArgumentError)  do
+          @oodler.listing()
+        end
+
+
+      end
+
+      should "allow inclusion of attributes in the query" do
+         stub_get("/api/v2/listings?region=chicago&attributes=make_honda%2Cmodel_civic%2Cprice_12000_15000&key=key&category=vehicle%2Fcars", "listings.xml")
+
+        @oodler.listing({:region =>"chicago", :category=>"vehicle/cars", :attributes=>"make_honda,model_civic,price_12000_15000"})
+
+      end
+
+      should "display error details" do
+        stub_get("/api/v2/listings?region=chicago&attributes=make_honda%2Cmodel_civic%2Cprice_12000_15000&key=key&category=vehicle%2Fbogus", "fail.xml")
+        assert_raise(Oodler::OodlerError) do
+          @oodler.listing({:region =>"chicago", :category=>"vehicle/bogus", :attributes=>"make_honda,model_civic,price_12000_15000"})
+        end
+
+      end
+      
+    end
+
+
+    should "encode spaces as %20" do
+     stub_get("/api/v2/listings?key=key&region=sf&category=job&q=software%20engineer", "listings.xml")
+     p = @oodler.search("sf", {:category => "job", :q =>"software engineer"})
+
+    end
+
+    should "encode commas as %2C" do
+     stub_get("/api/v2/listings?location=San%20Mateo%2C%20CA&region=usa&key=key&category=job&", "listings.xml")
+     p = @oodler.search("usa", {:category => "job", :location =>"San Mateo, CA"})
+
+    end
+
+
+
+
+  end
+  
+end

data/test/element_test.rb

@@ -0,0 +1,85 @@
+require 'test_helper'
+
+class ElementTest < Test::Unit::TestCase
+
+  should "parse element correctly from xml" do
+    element = Oodler::Element.from_xml('<element>
+			<id>1900074984</id>
+			<title>2010 Chrysler Town &amp; Country Touring</title>
+			<body>Driver manual lumbar adjust, Active headrests, Front center console w/cupholder, Pwr adjustable pedals, Tip start, Tilt steering column, Leather-wrapped steering wheel, Steering wheel audio controls, Trip computer w/temp &amp; compass, Door ajar warning light, Sliding door alert, Low washer fluid warning signal, Dark maple/silver instrument panel bezel, Satin silver instrument panel bezel center stack, Pwr front windows w/one-touch, 2nd row pwr windows, Pwr rear quarter vent windows, Pwr door locks, Keyless entry w/immobilizer, Speed control, Universal garage door opener, Rear window defroster, Analog clock, Dual glove boxes, Lower instrument panel cubby bin, Cupholders w/overhead illumination, Front/rear 12V DC pwr outlets, 12V auxiliary pwr outlets, 115V pwr outlet, Driver door sill storage bin, Door trim panel w/dark maple accents, Illuminated front door storage, Interior observation mirror, Overhead console, Overhead storage bins, Rear overhead console, Visors w/illuminated vanity mirrors</body>
+			<url>http://cars.oodle.com/r_a2xx_/1900074984-11202p454,10-EST/www.everycarlisted.com___chKLl2fSDGxSt6l73uN6064DyBKKek7cFjfdds1IVF0TXnFPtwBGejSLLeJvnwcNbSGADeRrrSEW8TQWmq9mTnxTRMpCVoogInIUUrMi4fVYmgrW86CjxEqU3RRWlP5g</url>
+			<category>
+				<id>vehicle/car</id>
+				<name>Cars</name>
+			</category>
+			<source>
+				<id>everycarlisted-bronze</id>
+				<name>EveryCarListed.com</name>
+			</source>
+			<location>
+				<latitude>42.0657997</latitude>
+				<longitude>-87.9197998</longitude>
+				<address>77 Rand Rd</address>
+				<zip>60016</zip>
+				<addresscode>addr:usa:il:desplaines:77+rand+rd</addresscode>
+				<citycode>usa:il:desplaines</citycode>
+				<name>Des Plaines</name>
+				<state>IL</state>
+				<country>USA</country>
+			</location>
+			<images>
+				<element>
+					<src>http://i.oodleimg.com/item/1900074984_1m?1271160266</src>
+					<width>144</width>
+					<height>108</height>
+					<alt>2010 Chrysler Town &amp; Country T</alt>
+				</element>
+				<element>
+					<src>http://i.oodleimg.com/item/1900074984_1s?1271160266</src>
+					<width>112</width>
+					<height>84</height>
+					<alt>2010 Chrysler Town &amp; Country T</alt>
+				</element>
+			</images>
+			<ctime>1271160145</ctime>
+			<paid>Yes</paid>
+			<revenue_score>10</revenue_score>
+			<similar_url>http://cars.oodle.com/2009_2011-hrysler-town_and_country/chicago-area/price_27000_36000/mileage_0_20000/?inbs=1</similar_url>
+			<attributes>
+				<color>Blue</color>
+				<condition>New</condition>
+				<currency>USD</currency>
+				<dealer_id>Advantage Chrysler Jeep Dodge of Des Pla</dealer_id>
+				<delivery>Local Delivery</delivery>
+				<engine_type>4.0L V6 24V MPFI SOHC</engine_type>
+				<features>Trip Computer,Keyless Entry,Clock,Center Console,Air Conditioning,Air Bags</features>
+				<fee>No</fee>
+				<has_photo>Thumbnail</has_photo>
+				<make>Chrysler</make>
+				<mileage>2</mileage>
+				<model>Town and Country</model>
+				<price>31415</price>
+				<price_display>$31,415</price_display>
+				<seller_type>Dealer</seller_type>
+				<transmission>Automatic</transmission>
+				<trim>Touring</trim>
+				<vin>2A4RR5DX9AR201012</vin>
+				<year>2010</year>
+			</attributes>
+		</element>')
+
+    element.id.should == "1900074984"
+    element.category.name.should == "Cars"
+    element.location.latitude.should == "42.0657997"
+    element.images.size.should == 2
+    element.images.first.src.should == "http://i.oodleimg.com/item/1900074984_1m?1271160266"
+    element.paid?.should == true
+    element.properties.keys.size.should == 19
+    element.properties["color"].should == "Blue"
+    element.properties["mileage"].should == "2"
+
+
+
+
+  end
+end

data/test/fixtures/fail.xml

@@ -0,0 +1,5 @@
+<oodle_response stat="fail">
+<error>
+Invalid category ('category').  To see the complete list of valid categories, visit http://developer.oodle.com/categories-list
+</error>
+</oodle_response>