justimmo_client 0.4.0

data/lib/justimmo_client/api/v1/requests/realty_request.rb

@@ -0,0 +1,209 @@
+# frozen_string_literal: true
+
+module JustimmoClient::V1
+  # @api private
+  module RealtyRequest
+    extend JustimmoRequest
+
+    # Mappings for the option parser
+    TRANSLATION_MAPPING = {
+      limit: :Limit,
+      offset: :Offset,
+      lang: :culture,
+      with_projects: :alleProjektObjekte,
+      number: :objektnummer,
+      price: :preis,
+      zip_code: :plz,
+      price_per_sqm: :preis_per_m2,
+      type: :objektart,
+      subtype: :subobjektart,
+      tag: :tagname,
+      room_count: :zimmer,
+      area: :flaeche,
+      living_area: :wohnflaeche,
+      floor_area: :nutzflaeche,
+      surface_area: :grundflaeche,
+      keyword: :stichwort,
+      country: :land,
+      federal_state: :bundesland,
+      small_undbanded: :small,
+      small2_unbranded: :s220x155,
+      small3_unbranded: :s312x208,
+      id: :objekt_id,
+      salutation: :anrede,
+      title: :titel,
+      first_name: :vorname,
+      last_name: :nachname,
+      phone: :tel,
+      location: :ort,
+      all: :alle
+    }.freeze
+
+    module_function
+
+    # @!group Realty Requests
+
+    # @param [Hash] params
+    # @return [String] The requested XML.
+    def list(**params)
+      get("objekt/list", list_option_parser.parse(params))
+    end
+
+    # @param [Integer] id
+    # @param [String, Symbol] lang
+    # @return [String] The requested XML.
+    def detail(id, lang: nil)
+      get("objekt/detail", detail_option_parser.parse(id: id, lang: lang))
+    end
+
+    # @param [Integer] id
+    # @param [Hash] params
+    # @return [String] The requested XML.
+    def inquiry(id, **params)
+      get("objekt/anfrage", inquiry_option_parser.parse(params.update(id: id)))
+    end
+
+    # @param [Hash] params
+    # @return [String] A JSON string containing an array of ids.
+    def ids(**params)
+      get("objekt/ids", ids_option_parser.parse(params))
+    end
+
+    # @todo implement this
+    # @param [Hash] params
+    # @return [File] The PDF file.
+    def expose(**params)
+      get("objekt/expose", params)
+    end
+
+    # @!group Basic Data Requests
+
+    # @param [Boolean] all (false)
+    # @return [String] The requested XML.
+    def categories(all: false)
+      get("objekt/kategorien", alle: all ? 1 : 0)
+    end
+
+    # @param [Boolean] all (false)
+    # @return [String] The requested XML.
+    def types(all: false)
+      get("objekt/objektarten", alle: all ? 1 : 0)
+    end
+
+    # @param [Boolean] all (false)
+    # @return [String] The requested XML.
+    def countries(all: false)
+      get("objekt/laender", alle: all ? 1 : 0)
+    end
+
+    # @param [Boolean] all (false)
+    # @param [Integer, String] country
+    # @return [String] The requested XML.
+    def federal_states(country:, all: false)
+      get("objekt/bundeslaender", land: country, alle: all ? 1 : 0)
+    end
+
+    # @param [Boolean] all (false)
+    # @param [Integer, String] country
+    # @param [Integer] federal_state
+    # @return [String] The requested XML.
+    def regions(country: nil, federal_state: nil, all: false)
+      get("objekt/regionen", land: country, bundesland: federal_state, alle: all ? 1 : 0)
+    end
+
+    # @param [Boolean] all (false)
+    # @param [Integer, String] country
+    # @param [Integer] federal_state
+    # @return [String] The requested XML.
+    def zip_codes_and_cities(country: nil, federal_state: nil, all: false)
+      get("objekt/plzsUndOrte", land: country, bundesland: federal_state, alle: all ? 1 : 0)
+    end
+
+    # @!group Option Parsers
+
+    # @return [Hash]
+    def list_option_parser
+      @option_parsers ||= {}
+      @option_parsers[:list] ||= JustimmoClient::OptionParser.new do |options|
+        options.mappings = TRANSLATION_MAPPING
+        options.range_suffix = %i[_von _bis]
+
+        options.add :limit
+        options.add :offset
+        options.add :lang
+        options.add :orderby, values: %w[price zip_code number created_at updated_at published_at]
+        options.add :ordertype, values: %w[asc desc]
+        options.add :picturesize, values: %w[small_unbranded small2_unbranded small3_unbranded medium_unbranded big_unbranded big2_unbranded medium big bin2]
+        options.add :with_projects, type: :bool
+        options.group :filter do |f|
+          f.add :price_min
+          f.add :price_max
+          f.add :price_per_sqm_min
+          f.add :price_per_sqm_max
+          f.add :type_id
+          f.add :subtype_id
+          f.add :tag
+          f.add :zip_code
+          f.add :zip_code_min
+          f.add :zip_code_max
+          f.add :room_count_min
+          f.add :room_count_max
+          f.add :number
+          f.add :number_min
+          f.add :number_max
+          f.add :area_min
+          f.add :area_max
+          f.add :living_area_min
+          f.add :living_area_max
+          f.add :floor_area_min
+          f.add :floor_area_max
+          f.add :surface_area_min
+          f.add :surface_area_max
+          f.add :keyword
+          f.add :country_id
+          f.add :federal_state_id
+          f.add :status_id
+          f.add :project_id
+          f.add :type
+          f.add :parent_id
+          f.add :updated_at_min, as: :aktualisiert_am_von
+          f.add :updated_at_max, as: :aktualisiert_am_bis
+        end
+      end
+    end
+
+    alias ids_option_parser list_option_parser
+
+    # @return [Hash]
+    def inquiry_option_parser
+      @option_parsers ||= {}
+      @option_parsers[:inquiry] = JustimmoClient::OptionParser.new do |options|
+        options.mappings = TRANSLATION_MAPPING
+        options.range_suffix = %i[_von _bis]
+
+        options.add :salutation_id
+        options.add :title
+        options.add :first_name
+        options.add :last_name
+        options.add :email
+        options.add :phone
+        options.add :message
+        options.add :street
+        options.add :zip_code
+        options.add :location
+        options.add :country
+      end
+    end
+
+    # @return [Hash]
+    def detail_option_parser
+      @option_parsers ||= {}
+      @option_parsers[:detail] = JustimmoClient::OptionParser.new do |options|
+        options.mappings = TRANSLATION_MAPPING
+
+        options.add :all
+        options.add :lang
+      end
+    end
+  end
+end

data/lib/justimmo_client/api/v1.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require "justimmo_client/autoload"
+
+module JustimmoClient
+  # Version 1 of the API
+  module V1
+    extend JustimmoClient::Utils
+
+    API_PATH = "#{__dir__}/v1"
+
+    autoload_dir "#{API_PATH}/models/*.rb"
+    autoload_dir "#{API_PATH}/representers/*.rb"
+    autoload_dir "#{API_PATH}/requests/*_request.rb"
+  end
+end

data/lib/justimmo_client/autoload.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "justimmo_client/version"
+require "justimmo_client/errors"
+require "justimmo_client/misc"
+
+module JustimmoClient
+  include JustimmoClient::Errors
+
+  autoload :Config,   "justimmo_client/core/config"
+  autoload :Logging,  "justimmo_client/core/logging"
+  autoload :Utils,    "justimmo_client/core/utils"
+  autoload :Caching,  "justimmo_client/core/caching"
+  autoload :Realty,   "justimmo_client/realty"
+  autoload :Employee, "justimmo_client/employee"
+  autoload :OptionParser, "justimmo_client/option_parser"
+end

data/lib/justimmo_client/core/caching.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+require "justimmo_client/core/config"
+require "justimmo_client/core/logging"
+
+module JustimmoClient
+  # Caching support
+  # @api private
+  module Caching
+    extend JustimmoClient::Logging
+
+    class NullCache
+      def write(_key, _data, **options); end
+      def read(_key); end
+    end
+
+    class << self
+      # Returns the current cache
+      # @!attribute [rw] cache
+      def cache
+        @cache ||= default_cache
+      end
+
+      def cache=(c)
+        @cache = c
+      end
+
+      def default_cache
+        cache = JustimmoClient::Config.cache || NullCache.new
+        log.info("Using default cache #{cache.class}")
+        cache
+      end
+    end
+
+    def cache
+      JustimmoClient::Caching.cache
+    end
+
+    # TODO: JSON serialize/deserialize the cached value
+    def with_cache(key, **options)
+      log.debug("Looking up cache key #{key}")
+      data = cache.read(key)
+
+      if data.nil?
+        log.debug("Cache miss for #{key}")
+        data = yield
+        cache.write(key, data, options)
+      else
+        log.debug("Cache hit for #{key}")
+      end
+
+      data
+    end
+  end
+end

data/lib/justimmo_client/core/config.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "base64"
+require "active_support/configurable"
+require "justimmo_client/errors"
+
+module JustimmoClient
+  # Configuration options storage
+  # @api private
+  class Config
+    include ActiveSupport::Configurable
+
+    SUPPORTED_API_VERSIONS = [1].freeze
+    REQUIRED = %i[username password].freeze
+
+    config_accessor(:base_url) { "api.justimmo.at/rest" }
+    config_accessor(:secure) { true }
+    config_accessor(:api_ver) { 1 }
+    config_accessor(:username)
+    config_accessor(:password)
+    config_accessor(:credentials)
+    config_accessor(:debug) { false }
+    config_accessor(:cache) { nil }
+    config_accessor(:request_retries) { 3 }
+
+    class << self
+      def configure
+        super
+        self.credentials = Base64.urlsafe_encode64("#{username}:#{password}")
+        validate
+      end
+
+      def validate
+        missing = REQUIRED.select { |r| @_config[r].nil? }
+        raise MissingConfiguration, missing unless missing.empty?
+
+        supported_ver = SUPPORTED_API_VERSIONS.include?(api_ver)
+        raise UnsupportedAPIVersion, api_ver unless supported_ver
+      end
+
+      def url
+        "#{secure ? 'https' : 'http'}://#{base_url}/v#{api_ver}"
+      end
+    end
+  end
+end

data/lib/justimmo_client/core/logging.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require "logger"
+require "justimmo_client/core/config"
+
+module JustimmoClient
+  # Logging support
+  # @api private
+  module Logging
+    class << self
+      # Use the Rails or default logger if none is set.
+      # @!attribute [rw] logger
+      # @return [Logger]
+      def logger
+        @logger ||= rails_logger || default_logger
+      end
+
+      attr_writer :logger
+
+      def default_logger
+        logger = Logger.new($stdout)
+        logger.level = JustimmoClient::Config.debug ? Logger::DEBUG : Logger::INFO
+        logger.datetime_format = "%Y-%m-%d %H:%M:%S"
+        logger.progname = "JustimmoClient"
+        logger.formatter = proc do |severity, datetime, progname, message|
+          "[#{format("%-5s", severity)}]  #{datetime}  #{progname}  #{message}\n"
+        end
+        logger
+      end
+
+      # The Ruby on Rails logger
+      # @return [Logger, nil] The logger object
+      def rails_logger
+        if ("true" == ENV.fetch("JUSTIMMO_USE_RAILS_LOGGER", "true")) && defined?(::Rails)
+          ::Rails&.logger
+        end
+      end
+    end
+
+    def logger
+      Logging.logger
+    end
+
+    alias log logger
+  end
+end

data/lib/justimmo_client/core/utils.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require "active_support/core_ext/string/inflections"
+
+module JustimmoClient
+  # Useful utility methods
+  # @api private
+  module Utils
+    def autoload_dir(path)
+      dirname = File.dirname(path)
+
+      Dir[path].each do |f|
+        basename = File.basename(f, ".rb")
+        send :autoload, basename.classify, File.join(dirname, basename)
+      end
+    end
+
+    def versioned_api(*name)
+      (["JustimmoClient::V#{JustimmoClient::Config.api_ver}"] + name).join("::").constantize
+    end
+
+    def api(name)
+      "JustimmoClient::#{name.to_s.classify}".constantize
+    end
+
+    def representer(name, type = :xml)
+      versioned_api(type.to_s.classify, "#{name.to_s.classify}Representer")
+    end
+
+    def model(name)
+      versioned_api(name.to_s.classify)
+    end
+
+    def request(name)
+      versioned_api("#{name.to_s.classify}Request")
+    end
+  end
+end

data/lib/justimmo_client/employee.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module JustimmoClient
+  # Public employee query interface
+  module Employee
+    extend JustimmoClient::Utils
+
+    module_function
+
+    # Retrieve a list of employee data.
+    # @return [Array<Object>]
+    def list
+      xml_response = request(:employee).list
+      model = Struct.new(:employees).new
+      representer(:employee_list).new(model).from_xml(xml_response).employees
+    rescue JustimmoClient::RetrievalFailed
+      []
+    end
+
+    # Retrieve detailed information about a single employee.
+    # @param id [Integer] The ID of the employee
+    # @return [Object]
+    def detail(id)
+      xml_response = request(:employee).detail(id)
+      model = model(:employee).new
+      representer(:employee).new(model).from_xml(xml_response)
+    rescue JustimmoClient::RetrievalFailed
+      nil
+    end
+
+    # @return [Array<Integer>] An array of employee IDs
+    def ids
+      json_response = request(:employee).ids
+      ::JSON.parse(json_response).map(&:to_i)
+    rescue JustimmoClient::RetrievalFailed
+      []
+    end
+  end
+end

data/lib/justimmo_client/errors.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# Exceptions for internal use
+module JustimmoClient::Errors
+  JustimmoError = Class.new(StandardError)
+  InitializationError = Class.new(JustimmoError)
+
+  # Raised when configuration validation fails.
+  ConfigurationError = Class.new(JustimmoError)
+
+  # Raised when authentication with the API fails.
+  class AuthenticationFailed < JustimmoError
+    def initialize
+      super("Authentication failed.")
+    end
+  end
+
+  # Raised when retrieval from the API fails.
+  class RetrievalFailed < JustimmoError
+    def initialize(message)
+      super("Failed to get data from the API: #{message}")
+    end
+  end
+
+  # A mapping could not be found in the mappings hash.
+  class MappingNotFound < JustimmoError
+    def initialize(map)
+      super("Could not find #{map} mapping.")
+    end
+  end
+
+  # A key could not be found in the specified mapping.
+  class KeyNotFound < JustimmoError
+    def initialize(key, map)
+      super("Key #{key} not found in #{map} mapping.")
+    end
+  end
+
+  class NotImplemented < JustimmoError
+    def initialize(meth)
+      super("Method #{meth} not implemented!")
+    end
+  end
+
+  # Raised when an unsupported API version is set.
+  class UnsupportedAPIVersion < ConfigurationError
+    def initialize(version)
+      super("API Version #{version} not supported.")
+    end
+  end
+
+  # Raised on missing required configuration options.
+  class MissingConfiguration < ConfigurationError
+    def initialize(missing)
+      super("Required configuration missing: #{missing}.")
+    end
+  end
+end

data/lib/justimmo_client/misc.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require "active_support/inflector/inflections"
+
+module JustimmoClient
+  ActiveSupport::Inflector.inflections do |inflect|
+    inflect.acronym "XML"
+    inflect.acronym "JSON"
+  end
+end

data/lib/justimmo_client/option_parser.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+module JustimmoClient
+  # @api private
+  class OptionParser
+    include JustimmoClient::Logging
+
+    attr_accessor :range_suffix
+    attr_accessor :mappings
+
+    def initialize(options = {})
+      @options = options
+      @mappings = {}
+      @range_suffix = %i[_min _max]
+      @context = nil
+
+      yield self if block_given?
+
+      parse unless options.empty?
+    end
+
+    def add(key, **options)
+      add_option(key, options)
+    end
+
+    def group(groupname)
+      @context = groupname.to_sym
+      yield self if block_given?
+    end
+
+    def parse(options = {})
+      out = {}
+
+      options.each do |key, value|
+        raise ArgumentError, "Invalid option: #{key}" unless @options.key?(key.to_sym)
+        group = group_of(key)
+
+        if group
+          out[group] ||= {}
+          out[group].update(parse_option(key.to_sym, value))
+        else
+          out.update(parse_option(key.to_sym, value))
+        end
+      end
+
+      out
+    end
+
+    private
+
+    def add_option(key, **options)
+      @options[key.to_sym] = {
+        group: @context,
+        type: options[:type],
+        as: options[:as],
+        values: options[:values]
+      }
+    end
+
+    def group_of(key)
+      @options.dig(key, :group)
+    end
+
+    def mapping(key)
+      @mappings.fetch(key, key)
+    end
+
+    def translate(key)
+      return @options[key][:as] if @options[key][:as]
+
+      suffix =
+        case key
+        when /(.*)_min/ then @range_suffix.first
+        when /(.*)_max/ then @range_suffix.last
+        when /(.*)_id/  then "_id"
+        else nil
+        end
+
+      key = ($1 || key).to_sym
+
+      "#{mapping(key)}#{suffix}".to_sym
+    end
+
+    def parse_option(key, value)
+      values = @options.dig(key, :values)
+      raise ArgumentError, "Value #{value} not supported" unless values.nil? || values.include?(value)
+
+      coerced =
+        case @options.dig(key, :type)
+        when :bool then i_to_bool(value)
+        else mapping(value)
+        end
+
+      { translate(key) => coerced }
+    end
+
+    def parse_range(key, range)
+      min, max  = @options[key][:range_suffix]
+      api_param = @options[key][:mapped]
+      { "#{api_param}#{min}": range.first, "#{api_param}#{max}": range.last }
+    end
+
+    def i_to_bool(value)
+      value ? 1 : 0
+    end
+  end
+end