rentjuicer 0.2.1 → 0.3.0

data/README.rdoc

@@ -1,6 +1,177 @@
 = rentjuicer
 
-Description goes here.
+Rentjuicer is a ruby gem that wraps the rentjucier.com api for listings, neighborhoods and adding leads.  Rentjuicer is built on top of HTTParty.
+
+Rentjuicer requires access to rentjuice.com's api through an Rentjuice api key so make sure you have acquired a key from Rentjuice before starting with this gem.
+
+API documentation is here: http://api.rentjuice.com/documentation/RentJuice_API.pdf
+
+
+== Installation
+
+  gem install rentjuicer
+
+In a rails 2.3.x app
+
+  config.gem 'rentjuicer'
+
+
+== Usage
+
+Responses from the api come back as Hashie::Rash objects, each response will be described below
+
+For documentation on Hashie::Rash see the following:  http://github.com/tcocca/rash
+
+Basically HTTParty parses the JSON response into a hash, which is then converted into a Hashie::Rash.  This takes all hash keys and converts camelCased keys to underscored keys (eg:  'camelCase' => 'camel_case') and then makes those keys accessble as methods.
+
+So all responses create a :body method to access the data:
+
+  @results.body.neighbhoroods # => array of Hashie::Rash objects
+
+Look at the JSON being returned and all of those keys are accessible as methods on the :body method for your Rentjuicer::Response method.
+
+Rentjuicer::Response also implements some method_missing so any methods on response.body can be accessed directly on response, eg:
+
+  @results.neighborhoods == @results.body.neighborhoods
+
+In the rest of the README I will be accessing the methods off of response as I think it is cleaner to use and read.
+
+
+=== Creating a Rentjuicer Client
+
+A rentjuicer client is necessary as this is the object that makes requests, each of classes that interacts with the api requires a rentjuicer client to be passed in to the new call.
+
+  @rentjuicer = Rentjuicer::Client.new('some_api_key')
+
+
+=== Getting a list of your neighborhoods
+
+To get a list of your neighborhoods in rentjuice you can access the neighborhoods resource and call find_all
+
+  @neighborhoods = Rentjuicer::Neighborhoods.new(@rentjuicer) # where @rentjuicer is the client created above
+  @response = @neighborhoods.find_all # returns a Rentjuicer::Response object
+  
+  @response.neighborhoods contains an array of Rentjuice neighborhood objects in Hashie::Rash format
+
+if the request is invalid a Rentjuicer::Error exception will be raised
+
+
+=== Adding a lead to your account
+
+To add a lead to your Rentjuice lead management system there are two methods, create and create!
+create will not raise an error but the response will not be successful if there is an error.
+create! will raise a Rentjuicer::Error if there is an error.
+
+  @lead = Rentjuicer::Lead.new(@rentjuicer)
+  @result = @lead.create('John Smith')
+  @result.success? # => true
+
+  @result = @lead.create!('John Smith') # raises an error if the create fails
+
+create and create! take a mandatory "name" paramater and also take an optional hash of parameters as specified in the API documentation.  All optional params are passed straight through to the api so keys and values should be passed in exactly as the documentation states.
+
+
+=== Searching for listings
+
+There are 5 methods to the Rentjuicer::Listings class in two "groups"
+
+==== The first group will return Rentjuicer::Listings::SearchResponse responses
+
+  :search - searches for listings based on the params passed in, if no params are passed in it will return all properties
+  :featured - same as search above (takes a params hash) but merges in the :featured => 1 param so that it will only return featured listings
+
+Search and Featured default to 20 listings per page of the request
+
+These methods all return a Rentjuicer::Listings::SearchResults response
+
+  @listings = Rentjuicer::Listings.new(@rentjuicer)
+  @results = @listings.search(:neighborhoods => 'Boston') # => all listings in Boston
+  @results = @listings.featured(:max_rent => '2000') # => all featured listings under 2000
+  @results = @listings.find_by_id(18330) # => returns listing 18330 as the only property in @results.properties if that property is found
+
+==== Rentjuicer::Listings::SearchResponse
+
+inherits from Rentjuicer::Response so @results.body will return a Hashie::Rash of the json that is returned from the api call
+
+method_missing applies here as well so any methods on @results.body can be called on @results
+
+It also adds 2 methods
+
+  :properties - this method returns an array of Rentjuicer::Listing objects (see below)
+  :paginator - returns a WillPaginate::Collection object created from the response where the pager cycles the :properties array
+
+  @results.properties # => an array of Rentjuicer::Listing objects
+  @results.paginator.total_entries # => total number of properties
+  @results.paginator # => the @results.properties objects
+
+==== Rentjuicer::Listing
+
+Rentjuicer::Listing creates an object from a hash (or in our case our Hashie::Rash object) by converting the hash keys to instance variables who's value is the key's value from the hash, then it creates methods that return those instance variables.
+
+@results.properties is just an array of these Rentjuicer::Listing objects that are converted from @results.listings
+
+so @results.listings.first.neighborhoods == @results.properties.first.neighborhoods
+
+Where this comes in handy though is that now that it is a class, we can extend it to add more methods which is exactly what we have done
+
+a Rentjuicer::Listing object responds to the following methods:
+
+  :id - returns the rentjuice_id for convenience
+  :sorted_photos - returns the self.photos sorted by the :sort_order key passed back through the api
+  :main_pic - this is not always the first photo in the sorted list, in fact there is a specific key in the photo hash to designate the main photo, so main_pic returns the photo object that is designated
+  :thumb_pic - returns the url for the main_pic thumbnail
+  :first_pic - returns the url for the main_pic fullsize photo
+  :neighborhood_name - returns the first name in the neighborhoods hash
+  
+Also, we have added another method :similar_listings which takes a Rentjuicer::Client object and does a search call
+
+  @results.properties.first.similar_listings(@rentjuicer)
+
+This method performs a search and returns an array for Rentjuicer::Listing objects based on the following criteria
+
+  :min_rent => self.rent.to_i * 0.9,
+  :max_rent => self.rent.to_i * 1.1,
+  :min_beds => ((self.bedrooms.to_i - 1) <= 0 ? 0 : (self.bedrooms.to_i - 1)),
+  :max_beds => self.bedrooms.to_i + 1,
+  :min_baths => ((self.bathrooms.to_i - 1) <= 0 ? 0 : (self.bathrooms.to_i - 1)),
+  :max_baths => self.bathrooms.to_i + 1,
+  :neighborhoods => self.neighborhood_name
+
+You can also pass a limit to the similar_listings method, the default is 6 properties (max) returned
+
+  @results.properties.first.similar_listings(@rentjuicer, 10) # returns max 10 similar listings
+
+===== Extending Rentjuicer::Listing
+Another benefit to this Rentjuicer::Listing class is that in your app you can open the class again and add more methods if you wish.  For example create a file:  RAILS_ROOT/lib/rentjuicer_extensions.rb with the following:
+
+  module Rentjuicer
+    class Listing
+      
+      def neighborhood_list
+        self.neighborhoods.join(', ')
+      end
+    end
+  end
+
+and add require 'rentjuicer_extensions' to your config/environment.rb file.
+
+Now you can call @results.properties.first.neighborhood_list to get a nice comma separated list of neighborhood names.
+This class allows you to create any methods you want on a listing.
+
+=== The second group returns Rentjuicer::Listing responses
+
+  :find_by_id - takes a rentjuice_id for a listing and returns a Rentjuicer::Listing if the property is found or nil if it is not found
+  @property = @listings.find_by_id(18830) # returns either nil or a Rentjuicer::Listing
+
+These methods just return a Rentjuicer::Listing or an array of Rentjuicer::Listing objects.
+These methods work by making subsequent calls to go through the pagination of the results for you and compaction each request into a single array.  Use these methods only when absolutely necessary as they are expensive to use as they will make repeated api calls through the entire set of pages, so if there are 20 listings per page and 571 pages, this will make 29 api requests which is obviously quite time consuming.
+
+  :find_all - take a hash of search params (same as :search above) and returns every result on every page of the response in an array 
+  :find_all_by_ids - takes a comma separated string of rentjuice_ids and returns every listing in an array
+  
+  @results = @listings.find_all(:neighborhoods => 'Boston') # returns an array of every listing in Boston in a single array - no need for pagination
+  @results = @listings.find_all_by_ids('200306,200221,200214,200121,199646,198560,197542,197540,197538) # returns an array of all of those listings that can be found
+
 
 == Note on Patches/Pull Requests
  

data/Rakefile

@@ -11,8 +11,8 @@ begin
     gem.homepage = "http://github.com/tcocca/rentjuicer"
     gem.authors = ["tcocca"]
     gem.add_dependency "httparty", ">= 0.6.1"
-    gem.add_dependency "hashie", ">= 0.3.1"
-    gem.add_dependency "rash", ">= 0.1.1"
+    gem.add_dependency "hashie", ">= 0.4.0"
+    gem.add_dependency "rash", ">= 0.2.0"
     gem.add_dependency "will_paginate", ">= 2.3.4"
     gem.add_development_dependency "rspec", ">= 1.2.9"
     gem.add_development_dependency "webmock", ">= 1.3.4"

data/VERSION

@@ -1 +1 @@
-0.2.1
+0.3.0

data/lib/rentjuicer/listings.rb

@@ -8,10 +8,6 @@ module Rentjuicer
       self.resource = "/listings.json"
     end
     
-    def find_by_id(listing_id)
-      SearchResponse.new(self.client.class.get(resource, :query => {:rentjuice_id => listing_id}))
-    end
-    
     def search(params = {})
       limit = params[:limit] || 20
       params[:order_by] ||= "rent"
@@ -24,6 +20,11 @@ module Rentjuicer
       search(params)
     end
     
+    def find_by_id(listing_id)
+      response = SearchResponse.new(self.client.class.get(resource, :query => {:rentjuice_id => listing_id}))
+      (response.success? && response.properties.size > 0) ? response.properties.first : nil
+    end
+    
     def find_all(params = {})
       per_page = params[:limit] || 20
       all_listings = []
@@ -63,9 +64,9 @@ module Rentjuicer
       end
       
       def properties
-        return [] if @body.listings.blank?
+        return [] if self.body.listings.blank?
         props = []
-        @body.listings.each do |listing|
+        self.body.listings.each do |listing|
           props << Rentjuicer::Listing.new(listing)
         end
         props
@@ -74,9 +75,9 @@ module Rentjuicer
       def paginator
         paginator_cache if paginator_cache
         self.paginator_cache = WillPaginate::Collection.create(
-          @body.page, 
+          self.body.page, 
           @limit, 
-          (@body.total_count ? @body.total_count : properties.size)) do |pager|
+          (self.body.total_count ? self.body.total_count : properties.size)) do |pager|
           pager.replace properties
         end
       end

data/lib/rentjuicer/response.rb

@@ -4,12 +4,20 @@ module Rentjuicer
     attr_accessor :body
     
     def initialize(response, raise_error = true)
-      @body = rash_response(response)
-      raise Error.new(@body.code, @body.message) if !success? && raise_error
+      rash_response(response)
+      raise Error.new(self.body.code, self.body.message) if !success? && raise_error
     end
     
     def success?
-      @body.status == "ok"
+      self.body.status == "ok"
+    end
+    
+    def method_missing(method_name, *args)
+      if self.body.respond_to?(method_name)
+        self.body.send(method_name)
+      else
+        super
+      end
     end
     
     private

data/rentjuicer.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = %q{rentjuicer}
-  s.version = "0.2.1"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["tcocca"]
@@ -52,6 +52,7 @@ Gem::Specification.new do |s|
      "spec/responses/lead_error.json",
      "spec/responses/listings.json",
      "spec/responses/neighborhoods.json",
+     "spec/responses/no_listings.json",
      "spec/spec.opts",
      "spec/spec_helper.rb",
      "spec/support/listing_helper.rb",
@@ -81,23 +82,23 @@ Gem::Specification.new do |s|
 
     if Gem::Version.new(Gem::RubyGemsVersion) >= Gem::Version.new('1.2.0') then
       s.add_runtime_dependency(%q<httparty>, [">= 0.6.1"])
-      s.add_runtime_dependency(%q<hashie>, [">= 0.3.1"])
-      s.add_runtime_dependency(%q<rash>, [">= 0.1.1"])
+      s.add_runtime_dependency(%q<hashie>, [">= 0.4.0"])
+      s.add_runtime_dependency(%q<rash>, [">= 0.2.0"])
       s.add_runtime_dependency(%q<will_paginate>, [">= 2.3.4"])
       s.add_development_dependency(%q<rspec>, [">= 1.2.9"])
       s.add_development_dependency(%q<webmock>, [">= 1.3.4"])
     else
       s.add_dependency(%q<httparty>, [">= 0.6.1"])
-      s.add_dependency(%q<hashie>, [">= 0.3.1"])
-      s.add_dependency(%q<rash>, [">= 0.1.1"])
+      s.add_dependency(%q<hashie>, [">= 0.4.0"])
+      s.add_dependency(%q<rash>, [">= 0.2.0"])
       s.add_dependency(%q<will_paginate>, [">= 2.3.4"])
       s.add_dependency(%q<rspec>, [">= 1.2.9"])
       s.add_dependency(%q<webmock>, [">= 1.3.4"])
     end
   else
     s.add_dependency(%q<httparty>, [">= 0.6.1"])
-    s.add_dependency(%q<hashie>, [">= 0.3.1"])
-    s.add_dependency(%q<rash>, [">= 0.1.1"])
+    s.add_dependency(%q<hashie>, [">= 0.4.0"])
+    s.add_dependency(%q<rash>, [">= 0.2.0"])
     s.add_dependency(%q<will_paginate>, [">= 2.3.4"])
     s.add_dependency(%q<rspec>, [">= 1.2.9"])
     s.add_dependency(%q<webmock>, [">= 1.3.4"])

data/spec/rentjuicer/listings_spec.rb

@@ -43,15 +43,21 @@ describe Rentjuicer::Listing do
       mock_get('/listings.json', 'find_by_id.json', {
         :rentjuice_id => "200306"
       })
-      @result = @listings.find_by_id(200306)
+      @listing = @listings.find_by_id(200306)
     end
     
-    it { @result.should be_kind_of(Rentjuicer::Listings::SearchResponse) }
-    it { @result.success?.should be_true }
-    
-    it "should return no more than 1 response" do
-      @result.properties.should have_at_most(1).listings
+    it { @listing.should be_kind_of(Rentjuicer::Listing) }
+  end
+  
+  context "find_by_id missing" do
+    before do
+      mock_get('/listings.json', 'no_listings.json', {
+        :rentjuice_id => "1"
+      })
+      @listing = @listings.find_by_id(1)
     end
+    
+    it { @listing.should be_nil }
   end
   
   context "featured" do

data/spec/rentjuicer/response_spec.rb

@@ -48,4 +48,27 @@ describe Rentjuicer::Response do
     end
   end
   
+  context "method missing" do
+    before do
+      @rentjuicer = new_rentjuicer
+      @listings = Rentjuicer::Listings.new(@rentjuicer)
+      mock_get('/listings.json', 'listings.json', {
+        :neighborhoods => "South Boston",
+        :order_by => "rent",
+        :order_direction => "asc"
+      })
+      @results = @listings.search(:neighborhoods => "South Boston")
+    end
+    
+    it "should allow response.body methods to be called on response" do
+      body = stub(:total_count => 25)
+      @results.body = body
+      @results.total_count.should == 25
+    end
+
+    it "should call super if body does not response to the method" do
+      lambda { @results.bad_method }.should raise_error(NoMethodError, /undefined method `bad_method'/)
+    end
+  end
+  
 end

data/spec/responses/no_listings.json

@@ -0,0 +1,8 @@
+{
+    "status": "ok",
+    "page": 1,
+    "count": 0,
+    "total_count": 0,
+    "listings": null,
+    "runtime": 0.056
+}

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: rentjuicer
 version: !ruby/object:Gem::Version 
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors: 
 - tcocca
@@ -30,7 +30,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 0.3.1
+        version: 0.4.0
     version: 
 - !ruby/object:Gem::Dependency 
   name: rash
@@ -40,7 +40,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 0.1.1
+        version: 0.2.0
     version: 
 - !ruby/object:Gem::Dependency 
   name: will_paginate
@@ -117,6 +117,7 @@ files:
 - spec/responses/lead_error.json
 - spec/responses/listings.json
 - spec/responses/neighborhoods.json
+- spec/responses/no_listings.json
 - spec/spec.opts
 - spec/spec_helper.rb
 - spec/support/listing_helper.rb