flexmls_api 0.3.6 → 0.4.5

data/lib/flexmls_api/client.rb

@@ -7,13 +7,19 @@ module FlexmlsApi
     include Authentication
     include Request
     
+    attr_accessor :authenticator
     attr_accessor *Configuration::VALID_OPTION_KEYS
     
-    def initialize(options={})
+    # Constructor bootstraps the client with configuration and authorization class.
+    # options - see Configuration::VALID_OPTION_KEYS
+    # auth_klass - subclass of Authentication::BaseAuth Defaults to the original api auth system.
+    def initialize(options={}, auth_klass=ApiAuth)
       options = FlexmlsApi.options.merge(options)
       Configuration::VALID_OPTION_KEYS.each do |key|
         send("#{key}=", options[key])
       end
+      # Instanciate the authenication class passed in.
+      @authenticator = authentication_mode.send("new", self)
     end
 
   end

data/lib/flexmls_api/configuration.rb

@@ -1,8 +1,8 @@
 module FlexmlsApi
   module Configuration
     # valid configuration options
-    VALID_OPTION_KEYS = [:api_key, :api_secret, :api_user, :endpoint, :user_agent, :version, :ssl].freeze
-
+    VALID_OPTION_KEYS = [:api_key, :api_secret, :api_user, :endpoint, :user_agent, :version, :ssl, :oauth2_provider, :authentication_mode].freeze
+      
     DEFAULT_API_KEY = nil
     DEFAULT_API_SECRET = nil
     DEFAULT_API_USER = nil
@@ -10,6 +10,7 @@ module FlexmlsApi
     DEFAULT_VERSION = 'v1'
     DEFAULT_USER_AGENT = "flexmls API Ruby Gem #{VERSION}"
     DEFAULT_SSL = false
+    DEFAULT_OAUTH2 = nil
 
     attr_accessor *VALID_OPTION_KEYS
     def configure
@@ -36,6 +37,8 @@ module FlexmlsApi
       self.version     = DEFAULT_VERSION
       self.user_agent  = DEFAULT_USER_AGENT
       self.ssl         = DEFAULT_SSL
+      self.oauth2_provider = DEFAULT_OAUTH2
+      self.authentication_mode = FlexmlsApi::Authentication::ApiAuth
       self
     end
   end

data/lib/flexmls_api/faraday.rb

@@ -1,6 +1,6 @@
 module FlexmlsApi
   module FaradayExt
-    #=Flexmls API Faraday middle way
+    #=Flexmls API Faraday middleware
     # HTTP Response after filter to package api responses and bubble up basic api errors.
     class FlexmlsMiddleware < Faraday::Response::Middleware
       begin
@@ -17,7 +17,7 @@ module FlexmlsApi
       # indicate a failure will raise a FlexmlsApi::ClientError exception
       def self.validate_and_build_response(finished_env)
         body = finished_env[:body]
-        FlexmlsApi.logger.debug("Response Body: #{body}")
+        FlexmlsApi.logger.debug("Response Body: #{body.inspect}")
         unless body.is_a?(Hash) && body.key?("D")
           raise InvalidResponse, "The server response could not be understood"
         end
@@ -26,6 +26,10 @@ module FlexmlsApi
         when 400, 409
           raise BadResourceRequest.new(response.code, finished_env[:status]), response.message
         when 401
+          # Handle the WWW-Authenticate Response Header Field if present. This can be returned by 
+          # OAuth2 implementations and wouldn't hurt to log.
+          auth_header_error = finished_env[:request_headers]["WWW-Authenticate"]
+          FlexmlsApi.logger.warn("Authentication error #{auth_header_error}") unless auth_header_error.nil?
           raise PermissionDenied.new(response.code, finished_env[:status]), response.message
         when 404
           raise NotFound.new(response.code, finished_env[:status]), response.message

data/lib/flexmls_api/models.rb

@@ -13,8 +13,10 @@ require File.expand_path('../models/contact', __FILE__)
 require File.expand_path('../models/idx_link', __FILE__)
 require File.expand_path('../models/market_statistics', __FILE__)
 require File.expand_path('../models/video', __FILE__)
+require File.expand_path('../models/tour_of_home', __FILE__)
 require File.expand_path('../models/virtual_tour', __FILE__)
 require File.expand_path('../models/document', __FILE__)
+require File.expand_path('../models/note', __FILE__)
 
 module FlexmlsApi
   module Models

data/lib/flexmls_api/models/base.rb

@@ -52,7 +52,11 @@ module FlexmlsApi
       end
 
       def self.first(options={})
-        get(options)[0]
+        get(options).first
+      end
+
+      def self.count(options={})
+        connection.get(path, options.merge({:_pagination=>"count"}))
       end
       
       def method_missing(method_symbol, *arguments)

data/lib/flexmls_api/models/contact.rb

@@ -1,6 +1,7 @@
 module FlexmlsApi
   module Models
     class Contact < Base
+      extend Finders
       self.element_name="contacts"
       
       def save

data/lib/flexmls_api/models/custom_fields.rb

@@ -4,8 +4,8 @@ module FlexmlsApi
       self.element_name="customfields"
 
 
-      def self.find_by_property_type(card_fmt, user)
-        collect(connection.get("#{self.path}/#{card_fmt}", :ApiUser => user))
+      def self.find_by_property_type(card_fmt, arguments={})
+        collect(connection.get("#{self.path}/#{card_fmt}", arguments))
       end
     end
   end

data/lib/flexmls_api/models/finders.rb

@@ -36,10 +36,10 @@ module FlexmlsApi
 
       def find_single(scope, options)
         resp = connection.get("/#{element_name}/#{scope}", options)
-        new(resp[0])
+        new(resp.first)
       end
             
     end
   end
 end
-    
+    

data/lib/flexmls_api/models/idx_link.rb

@@ -39,7 +39,7 @@ module FlexmlsApi
 
       def self.find_single(scope, options)
         resp = FlexmlsApi.client.get("/idxlinks/#{scope}", options)
-        new(resp[0])
+        new(resp.first)
       end
 
     end

data/lib/flexmls_api/models/listing.rb

@@ -11,7 +11,6 @@ module FlexmlsApi
         @virtual_tours = []
         @documents = []
 
-
         if attributes.has_key?('StandardFields')
           pics, vids, tours, docs = attributes['StandardFields'].values_at('Photos','Videos', 'VirtualTours', 'Documents')
         end
@@ -36,13 +35,12 @@ module FlexmlsApi
           attributes['StandardFields'].delete('Documents')
         end
         
-      
         super(attributes)
       end
 
-      def self.find_by_cart_id(cart_id, owner, options={}) 
-        options.merge!({ :ApiUser => owner, :_filter => "ListingCart Eq '#{cart_id}'" })
-        find(:all, options) 
+      def self.find_by_cart_id(cart_id, options={}) 
+        query = {:_filter => "ListingCart Eq '#{cart_id}'"}
+        find(:all, options.merge(query)) 
       end
       
       def self.my(arguments={})
@@ -56,6 +54,34 @@ module FlexmlsApi
       def self.company(arguments={})
         collect(connection.get("/company/listings", arguments))
       end
+      
+      def tour_of_homes(arguments={})
+        return @tour_of_homes unless @tour_of_homes.nil?
+        @tour_of_homes = TourOfHome.find_by_listing_key(self.Id, arguments)
+      end
+
+      def my_notes
+        Note.build_subclass.tap do |note|
+          note.prefix = "/listings/#{self.ListingKey}"
+          note.element_name = "/my/notes"
+          FlexmlsApi.logger.info("Note.path: #{note.path}")
+        end
+      end
+
+      # 'fore' is required when accessing an agent's shared
+      # notes for a specific contact. If the ApiUser /is/ the
+      # contact, then it can be inferred by the api, so it's
+      # unecessary
+      def shared_notes(fore=nil)
+        Note.build_subclass.tap do |note|
+          note.prefix = "/listings/#{self.ListingKey}"
+          if fore.nil?
+            note.element_name = "/shared/notes"
+          else
+            note.element_name = "/shared/notes/contacts/#{fore}"
+          end
+        end
+      end
 
       private
 

data/lib/flexmls_api/models/market_statistics.rb

@@ -25,7 +25,7 @@ module FlexmlsApi
       private 
       def self.stat(stat_name, parameters={})
         resp = connection.get("#{path}/#{stat_name}", parameters)
-        new(resp[0])
+        new(resp.first)
       end
       
     end

data/lib/flexmls_api/models/note.rb

@@ -0,0 +1,43 @@
+module FlexmlsApi
+  module Models
+    class Note < Base
+      extend Subresource 
+      self.element_name = "notes" # not sure this is really of any use...
+      
+      def self.get(options={})
+        ret = super(options)
+        if ret.empty?
+          return nil
+        else
+          return ret.first
+        end
+      end
+
+
+      def save(arguments={})
+        begin
+          return save!(arguments)
+        rescue BadResourceRequest => e
+        rescue NotFound => e
+          # log and leave
+          FlexmlsApi.logger.error("Failed to save note #{self} (path: #{self.class.path}): #{e.message}")
+        end 
+        false
+      end 
+
+      def save!(args={})
+        args.merge(:Notes => attributes['Note'])
+        results = connection.put(self.class.path, {:Note => attributes['Note']}, args)
+        result = results.first
+        attributes['ResourceUri'] = result['ResourceUri']
+        true
+      end 
+
+      def delete(args={})
+        connection.delete(self.class.path, args)
+      end
+
+
+    end
+  end
+end

data/lib/flexmls_api/models/standard_fields.rb

@@ -1,7 +1,50 @@
 module FlexmlsApi
   module Models
     class StandardFields < Base
+      extend Finders
       self.element_name="standardfields"
+      
+      # expand all fields passed in
+      def self.find_and_expand_all(fields, arguments={}, max_list_size=1000)
+        returns = {}
+        
+        # find all standard fields, but expand only the location fields
+        # TODO: when _expand support is added to StandardFields API, use the following
+        # standard_fields = find(:all, {:ApiUser => owner, :_expand => fields.join(",")}) 
+        standard_fields = find(:all, arguments)
+      
+        # filter through the list and return only the location fields found
+        fields.each do |field|
+          # search for field in the payload
+          if standard_fields.first.attributes.has_key?(field)
+            returns[field] = standard_fields.first.attributes[field]
+              
+            # lookup fully _expand field, if the field has a list
+            if returns[field]['HasList'] && returns[field]['MaxListSize'].to_i <= max_list_size
+              returns[field] = connection.get("/standardfields/#{field}", arguments).first[field]
+            end
+              
+          end
+        end
+        
+        returns
+      end
+      
+      
+      # find_nearby: find fields nearby via lat/lon
+      def self.find_nearby(prop_types = ["A"], arguments={})
+        return_json = {"D" => {"Success" => true, "Results" => []} }
+        
+        # add _expand=1 so the fields are returned
+        arguments.merge!({:_expand => 1})
+        
+        # find and return
+        return_json["D"]["Results"] = connection.get("/standardfields/nearby/#{prop_types.join(',')}", arguments)
+        
+        # return
+        return_json
+      end
+      
     end
   end
 end

data/lib/flexmls_api/models/subresource.rb

@@ -2,11 +2,14 @@ module FlexmlsApi
   module Models
     module Subresource 
     
-      def find_by_listing_key(key, user)
-        collect(connection.get("/listings/#{key}#{self.path}", :ApiUser => user))
+      def build_subclass
+        Class.new(self)
       end
 
 
+      def find_by_listing_key(key, arguments={})
+        collect(connection.get("/listings/#{key}#{self.path}", arguments))
+      end
 
     end
   end

data/lib/flexmls_api/models/system_info.rb

@@ -2,6 +2,13 @@ module FlexmlsApi
   module Models
     class SystemInfo < Base
       self.element_name="system"
+
+      def primary_logo
+        logo = nil
+        mls_logos = attributes['Configuration'].first['MlsLogos']
+        logo = mls_logos.first if !mls_logos.nil? and !mls_logos.empty?
+        logo
+      end
     end
   end
 end

data/lib/flexmls_api/models/tour_of_home.rb

@@ -0,0 +1,24 @@
+require 'date'
+require 'time'
+
+module FlexmlsApi
+  module Models
+    class TourOfHome < Base
+      extend Subresource
+
+      self.element_name = "tourofhomes"
+      
+      def initialize(attributes={})
+        # Transform the date strings
+        unless attributes['Date'].nil?
+          date = Date.parse(attributes['Date'])
+          attributes['Date'] = date
+          attributes['StartTime'] = Time.parse("#{date}T#{attributes['StartTime']}") unless attributes['StartTime'].nil?
+          attributes['EndTime'] = Time.parse("#{date}T#{attributes['EndTime']}") unless attributes['EndTime'].nil?
+        end
+        super(attributes)
+      end
+      
+    end
+  end
+end

data/lib/flexmls_api/request.rb

@@ -58,28 +58,22 @@ module FlexmlsApi
 
     # Perform an HTTP request (no data)
     def request(method, path, body, options)
-      if @session.nil? || @session.expired?
+      unless authenticated?
         authenticate
       end
       attempts = 0
       begin
-        request_opts = {
-          "AuthToken" => @session.auth_token
-        }
-        unless self.api_user.nil?
-          request_opts.merge!(:ApiUser => "#{api_user}")
-        end
+        request_opts = {}
         request_opts.merge!(options)
         post_data = body.nil? ? nil : {"D" => body }.to_json
-        sig = sign_token(path, request_opts, post_data)
-        request_path = "/#{version}#{path}?ApiSig=#{sig}#{build_url_parameters(request_opts)}"
-        FlexmlsApi.logger.debug("Request: #{request_path}")
+        request_path = "/#{version}#{path}"
         start_time = Time.now
+        FlexmlsApi.logger.debug("#{method.to_s.upcase} Request:  #{request_path}")
         if post_data.nil?
-          response = connection.send(method, request_path)
+          response = authenticator.request(method, request_path, nil, request_opts)
         else
-          FlexmlsApi.logger.debug("Data: #{post_data}")
-          response = connection.send(method, request_path, post_data)
+          FlexmlsApi.logger.debug("#{method.to_s.upcase} Data:   #{post_data}")
+          response = authenticator.request(method, request_path, post_data, request_opts)
         end
         request_time = Time.now - start_time
         FlexmlsApi.logger.info("[#{(request_time * 1000).to_i}ms] Api: #{method.to_s.upcase} #{request_path}")
@@ -98,25 +92,17 @@ module FlexmlsApi
       results = response.body.results
       paging = response.body.pagination
       unless paging.nil?
-        results = paginate_response(results, paging)
+        if request_opts[:_pagination] == "count"
+          results = paging['TotalRows']
+        else
+          results = paginate_response(results, paging)
+        end
       end
       results
     end
     
-    # Format a hash as request parameters
-    # 
-    # :returns:
-    #   Stringized form of the parameters as needed for the http request
-    def build_url_parameters(parameters={})
-      str = ""
-      parameters.map do |key,value|
-        escaped_value = CGI.escape("#{value}")
-        str << "&#{key}=#{escaped_value}"
-      end
-      str
-    end    
   end
-  
+ 
   # All known response codes listed in the API
   module ResponseCodes
     NOT_FOUND = 404
@@ -149,7 +135,6 @@ module FlexmlsApi
   class NotAllowed < ClientError; end
   class BadResourceRequest < ClientError; end
   
-  
   # Nice and handy class wrapper for the api response hash
   class ApiResponse
     attr_accessor :code, :message, :results, :success, :pagination