flexmls_api 0.3.2

data/lib/flexmls_api/models/video.rb

@@ -0,0 +1,16 @@
+module FlexmlsApi
+  module Models
+    class Video < Base
+      extend Subresource
+      self.element_name = 'videos'
+
+      def branded?
+        attributes['Type'] == 'branded'
+      end
+
+      def unbranded?
+        attributes['Type'] == 'unbranded'
+      end
+    end
+  end
+end

data/lib/flexmls_api/models/virtual_tour.rb

@@ -0,0 +1,18 @@
+module FlexmlsApi
+  module Models
+    class VirtualTour < Base
+      extend Subresource
+      self.element_name="virtualtours"
+      
+
+      def branded? 
+        attributes["Type"] == "branded"
+      end
+
+      def unbranded?
+        attributes["Type"] == "unbranded"
+      end
+
+    end
+  end
+end

data/lib/flexmls_api/models.rb

@@ -0,0 +1,21 @@
+require File.expand_path('../models/base', __FILE__)
+require File.expand_path('../models/listing', __FILE__)
+require File.expand_path('../models/subresource', __FILE__)
+require File.expand_path('../models/photo', __FILE__)
+require File.expand_path('../models/system_info', __FILE__)
+require File.expand_path('../models/standard_fields', __FILE__)
+require File.expand_path('../models/custom_fields', __FILE__)
+require File.expand_path('../models/property_types', __FILE__)
+require File.expand_path('../models/connect_prefs', __FILE__)
+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/virtual_tour', __FILE__)
+require File.expand_path('../models/document', __FILE__)
+
+module FlexmlsApi
+  module Models
+
+  end
+end

data/lib/flexmls_api/paginate.rb

@@ -0,0 +1,87 @@
+require 'will_paginate/collection'
+
+# =Pagination for api resource collections
+# Will paginate adapter for the api client.  Utilizes the same interface as will paginate and returns the 
+# same WillPaginate::Collection for finder results.
+module FlexmlsApi
+  module Paginate
+    
+    DEFAULT_PAGE_SIZE = 25
+    
+    # == Replacement hook for will_paginate's class method
+    # Does a best effort to mimic the will_paginate method of same name.  All arguments are
+    # passed on to the finder method except the special keys for the options hash listed below.
+    #
+    # == Special parameters for paginating finders
+    # * <tt>:page</tt> -- REQUIRED, but defaults to 1 if false or nil
+    # * <tt>:per_page</tt> -- defaults to <tt>CurrentModel.per_page</tt> (which is 25 if not overridden)
+    # * <tt>:finder</tt> -- name of the finder used (default: "get").  This needs to be a class finder method on the class
+    def paginate(*args)
+      options = args.last.is_a?(::Hash) ? args.pop : {}
+      page = options.delete(:page) || 1
+      items_per_page = options.delete(:per_page) || self.per_page
+      finder = (options.delete(:finder) || 'get').to_s
+      page_options = {
+        "_pagination" => 1,
+        "_limit" => items_per_page,
+        "_page" => page
+      }
+      options.merge!(page_options)
+      args << options
+      collection = send(finder,*args)
+    end
+    
+    # == Instanciate class instances from array of hash representations.  
+    # Needs to be called by all finders that would like to support paging.  Takes the hash result 
+    # set from the request layer and instanciates instances of the class called for the finder.
+    #
+    # * result_array -- the results object returned from the api request layer.  An array of hashes.
+    # 
+    # :returns:
+    #   An array of class instances for the Class of the calling finder
+    def collect(result_array)
+      collection = result_array.collect { |item| new(item)}
+      result_array.replace(collection)
+      result_array
+    end
+    
+    # Default per_page limit set on all models.  Override this method in the model such ala the 
+    # will_paginate gem to change
+    def per_page
+      DEFAULT_PAGE_SIZE
+    end
+  end
+
+  # ==Paginate Api Responses
+  # Module use by the request layer to decorate the response's results array with paging support.
+  # Pagination only happens if the response includes the pagination information as specified by the 
+  # API.
+  module PaginateResponse
+    # ==Enable pagination
+    # * results -- array of hashes representing api resources
+    # * paging_hash -- the pagination response information from the api representing paging state.
+    # 
+    # :returns:
+    #   The result set decorated as a WillPaginate::Collection
+    def paginate_response(results, paging_hash)
+      pager = Pagination.new(paging_hash)
+      paged_results = WillPaginate::Collection.create(pager.current_page, pager.page_size, pager.total_rows) do |p|
+        p.replace(results)
+      end
+      paged_results
+    end
+  end
+
+  # ==Pagination
+  #   Simple class representing the API's pagination response object
+  class Pagination
+    attr_accessor :total_rows, :page_size, :total_pages, :current_page
+    def initialize(hash)
+      @total_rows     = hash["TotalRows"]
+      @page_size      = hash["PageSize"]
+      @total_pages    = hash["TotalPages"]
+      @current_page   = hash["CurrentPage"]
+    end
+  end
+  
+end

data/lib/flexmls_api/request.rb

@@ -0,0 +1,172 @@
+
+module FlexmlsApi
+  # HTTP request wrapper.  Performs all the api session mumbo jumbo so that the models don't have to.
+  module Request
+    include PaginateResponse
+    # Perform an HTTP GET request
+    # 
+    # * path - Path of an api resource, excluding version and endpoint (domain) information
+    # * options - Resource request options as specified being supported via and api resource
+    # :returns:
+    #   Hash of the json results as documented in the api.
+    # :raises:
+    #   FlexmlsApi::ClientError or subclass if the request failed.
+    def get(path, options={})
+      request(:get, path, nil, options)
+    end
+
+    # Perform an HTTP POST request
+    # 
+    # * path - Path of an api resource, excluding version and endpoint (domain) information
+    # * body - Hash for post body data
+    # * options - Resource request options as specified being supported via and api resource
+    # :returns:
+    #   Hash of the json results as documented in the api.
+    # :raises:
+    #   FlexmlsApi::ClientError or subclass if the request failed.
+    def post(path, body={}, options={})
+      request(:post, path, body, options)
+    end
+
+    # Perform an HTTP PUT request
+    # 
+    # * path - Path of an api resource, excluding version and endpoint (domain) information
+    # * body - Hash for post body data
+    # * options - Resource request options as specified being supported via and api resource
+    # :returns:
+    #   Hash of the json results as documented in the api.
+    # :raises:
+    #   FlexmlsApi::ClientError or subclass if the request failed.
+    def put(path, body={}, options={})
+      request(:put, path, body, options)
+    end
+
+    # Perform an HTTP DELETE request
+    # 
+    # * path - Path of an api resource, excluding version and endpoint (domain) information
+    # * options - Resource request options as specified being supported via and api resource
+    # :returns:
+    #   Hash of the json results as documented in the api.
+    # :raises:
+    #   FlexmlsApi::ClientError or subclass if the request failed.
+    def delete(path, options={})
+      request(:delete, path, nil, options)
+    end
+    
+    private
+
+    # Perform an HTTP request (no data)
+    def request(method, path, body, options)
+      if @session.nil? || @session.expired?
+        authenticate
+      end
+      attempts = 0
+      begin
+        request_opts = {
+          "AuthToken" => @session.auth_token
+        }
+        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}")
+        start_time = Time.now
+        if post_data.nil?
+          response = connection.send(method, request_path)
+        else
+          FlexmlsApi.logger.debug("Data: #{post_data}")
+          response = connection.send(method, request_path, post_data)
+        end
+        request_time = Time.now - start_time
+        FlexmlsApi.logger.info("[#{request_time}s] Api: #{method.to_s.upcase} #{request_path}")
+      rescue PermissionDenied => e
+        if(ResponseCodes::SESSION_TOKEN_EXPIRED == e.code)
+          unless (attempts +=1) > 1
+            FlexmlsApi.logger.debug("Retrying authentication")
+            authenticate
+            retry
+          end
+        end
+        # No luck authenticating... KABOOM!
+        FlexmlsApi.logger.error("Authentication failed or server is sending us expired tokens, nothing we can do here.")
+        raise
+      end
+      results = response.body.results
+      paging = response.body.pagination
+      unless paging.nil?
+        results = paginate_response(results, paging)
+      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|
+        str << "&#{key}=#{value}"
+      end
+      str
+    end    
+  end
+  
+  # All known response codes listed in the API
+  module ResponseCodes
+    NOT_FOUND = 404
+    METHOD_NOT_ALLOWED = 405
+    INVALID_KEY = 1000
+    DISABLED_KEY = 1010
+    API_USER_REQUIRED = 1015
+    SESSION_TOKEN_EXPIRED = 1020
+    SSL_REQUIRED = 1030
+    INVALID_JSON = 1035
+    INVALID_FIELD = 1040
+    MISSING_PARAMETER = 1050
+    INVALID_PARAMETER = 1053
+    CONFLICTING_DATA = 1055
+    NOT_AVAILABLE= 1500
+    RATE_LIMIT_EXCEEDED = 1550
+  end
+  
+  # Errors built from API responses
+  class InvalidResponse < StandardError; end
+  class ClientError < StandardError
+    attr_reader :code, :status
+    def initialize (code, status)
+      @code = code
+      @status = status
+    end
+  end
+  class NotFound < ClientError; end
+  class PermissionDenied < ClientError; end
+  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
+    def initialize(d)
+      begin
+        hash = d["D"]
+        if hash.nil? || hash.empty?
+          raise InvalidResponse, "The server response could not be understood"
+        end
+        self.message  = hash["Message"]
+        self.code     = hash["Code"]
+        self.results  = hash["Results"]
+        self.success  = hash["Success"]
+        self.pagination = hash["Pagination"]
+      rescue Exception => e
+        FlexmlsApi.logger.error "Unable to understand the response! #{d}"
+        raise
+      end
+    end
+    def success?
+      @success
+    end
+  end
+
+end

data/lib/flexmls_api/version.rb

@@ -0,0 +1,4 @@
+# Gem version information
+module FlexmlsApi
+  VERSION = File.read(File.dirname(__FILE__) + "/../../VERSION").chomp
+end

data/lib/flexmls_api.rb

@@ -0,0 +1,41 @@
+# Flexmlsapi
+require 'rubygems'
+require 'curb'
+require 'json'
+require 'logger'
+
+require File.expand_path('../flexmls_api/version', __FILE__)
+require File.expand_path('../flexmls_api/configuration', __FILE__)
+require File.expand_path('../flexmls_api/authentication', __FILE__)
+require File.expand_path('../flexmls_api/paginate', __FILE__)
+require File.expand_path('../flexmls_api/request', __FILE__)
+require File.expand_path('../flexmls_api/client', __FILE__)
+require File.expand_path('../flexmls_api/faraday', __FILE__)
+require File.expand_path('../flexmls_api/models', __FILE__)
+
+module FlexmlsApi
+  extend Configuration
+ 
+  def self.logger
+    if @logger.nil?
+      @logger = Logger.new(STDOUT)
+      @logger.level = Logger::INFO
+    end
+    @logger
+  end
+
+  def self.client(opts={})
+    Thread.current[:flexmls_api_client] ||= FlexmlsApi::Client.new(opts)
+  end
+
+  def self.method_missing(method, *args, &block)
+    return super unless (client.respond_to?(method))
+    client.send(method, *args, &block)
+  end
+  
+  def self.reset
+    reset_configuration
+    Thread.current[:flexmls_api_client] = nil
+  end
+
+end

data/spec/fixtures/contacts.json

@@ -0,0 +1,25 @@
+{
+  "D": {
+    "Success": true, 
+    "Results": [
+      {
+        "ResourceUri":"/v1/contacts/20101230223226074201000000",
+        "DisplayName":"Contact One",
+        "Id":"20101230223226074201000000",
+        "PrimaryEmail":"contact1@fbsdata.com"
+      },
+      {
+        "ResourceUri":"/v1/contacts/20101230223226074202000000",
+        "DisplayName":"Contact Two",
+        "Id":"20101230223226074202000000",
+        "PrimaryEmail":"contact2fbsdata.com"
+      },
+      {
+        "ResourceUri":"/v1/contacts/20101230223226074203000000",
+        "DisplayName":"Contact Three",
+        "Id":"20101230223226074203000000",
+        "PrimaryEmail":"contact3@fbsdata.com"
+      }
+    ]
+  }
+}

data/spec/fixtures/listing_document_index.json

@@ -0,0 +1,19 @@
+{
+    "D": {
+        "Results": [
+            {
+                "Uri": "http://images.dev.fbsdata.com/documents/cda/20060725224801143085000000.pdf",
+                "ResourceUri": "/v1/listings/20060725224713296297000000/documents/20060725224801143085000000",
+                "Name": "Disclosure",
+                "Id": "20060725224801143085000000"
+            },
+            {
+                "Uri": "http://images.dev.fbsdata.com/documents/cda/20060725224818080340000000.pdf",
+                "ResourceUri": "/v1/listings/20060725224713296297000000/documents/20060725224818080340000000",
+                "Name": "Plat Map",
+                "Id": "20060725224818080340000000"
+            }
+        ],
+        "Success": true
+    }
+}

data/spec/fixtures/listing_no_subresources.json

@@ -0,0 +1,38 @@
+{
+    "D": {
+        "Results": [
+            {
+                "ResourceUri": "/v1/listings/20060725224713296297000000",
+                "StandardFields": {
+                    "StreetNumber": "7298",
+                    "Longitude": "-116.3237",
+                    "City": "Bonners Ferry",
+                    "ListingId": "06-9395",
+                    "PublicRemarks": "Afforadable home in town close to hospital,yet quiet country like setting. Good views. Must see",
+                    "BuildingAreaTotal": "924.0",
+                    "YearBuilt": 1977,
+                    "StreetName": "BIRCH",
+                    "ListPrice": "50000.0",
+                    "PostalCode": "83805",
+                    "Latitude": "48.7001",
+                    "BathsThreeQuarter": null,
+                    "BathsFull": null,
+                    "BathsTotal": "1.0",
+                    "StateOrProvince": "ID",
+                    "PropertyType": "A",
+                    "StreetAdditionalInfo": null,
+                    "StreetDirPrefix": null,
+                    "BedsTotal": 3,
+                    "StreetDirSuffix": null,
+                    "ListingKey": "20060725224713296297000000",
+                    "ListOfficeName": "Century 21 On The Lake",
+                    "BathsHalf": null,
+                    "ModificationTimestamp": "2010-11-22T20:47:21Z",
+                    "CountyOrParish": "Boundary"
+                },
+                "Id": "20060725224713296297000000"
+            }
+        ],
+        "Success": true
+    }
+}