pricehubble 0.1.0

data/lib/pricehubble/entity/concern/attributes.rb

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  module EntityConcern
+    # An ActiveRecord-like attribute management feature, with the exception
+    # that the attributes are not generated through a schema file, but are
+    # defined inline the entity class.
+    #
+    module Attributes
+      extend ActiveSupport::Concern
+
+      included do
+        # Include all custom typed attribute helpers
+        include Attributes::DateArray
+        include Attributes::Enum
+        include Attributes::Range
+        include Attributes::StringInquirer
+
+        # Collect all registed attribute names as symbols
+        class_attribute :attribute_names
+
+        # Export all attributes as data hash, as requested by the ActiveModel
+        # API.
+        #
+        # @param sanitize [Boolean] whenever to sanitize the data for transport
+        # @return [Hash{String => Mixed}] the attribute data
+        #
+        # rubocop:disable Metrics/MethodLength because of the
+        #   key/value sanitization handling
+        def attributes(sanitize = false)
+          attribute_names.each_with_object({}) do |key, memo|
+            reader = key
+
+            if sanitize
+              sanitizer = "sanitize_attr_#{key}".to_sym
+              reader = methods.include?(sanitizer) ? sanitizer : key
+
+              key_sanitizer = "sanitize_attr_key_#{key}".to_sym
+              key = methods.include?(key_sanitizer) ? send(key_sanitizer) : key
+            end
+
+            result = resolve_attributes(send(reader))
+            memo[key.to_s] = result
+          end
+        end
+        # rubocop:enable Metrics/MethodLength
+
+        # A wrapper for the +ActiveModel#assign_attributes+ method with support
+        # for unmapped attributes. These attributes are put into the
+        # +_unmapped+ struct and all the known attributes are assigned like
+        # normal. This allows the client to be forward compatible with changing
+        # APIs.
+        #
+        # @param struct [Hash{Mixed => Mixed}, RecursiveOpenStruct] the data
+        #   to assign
+        # @return [Mixed] the input data which was assigned
+        def assign_attributes(struct = {})
+          # Build a RecursiveOpenStruct and a simple hash from the given data
+          struct, hash = sanitize_data(struct)
+          # Initialize associations and map them accordingly
+          struct, hash = initialize_associations(struct, hash)
+          # Initialize attributes and map unknown ones and pass back the known
+          known = initialize_attributes(struct, hash)
+          # Mass assign the known attributes via ActiveModel
+          super(known)
+        end
+
+        private
+
+        # Resolve the attributes for the given object while respecting
+        # sanitization and deep arrays.
+        #
+        # @param obj [Mixed] the object to resolve its attributes
+        # @param sanitize [Boolean] whenever to sanitize the data for transport
+        # @return [Mixed] the attribute(s) data
+        def resolve_attributes(obj, sanitize = false)
+          if obj.respond_to? :attributes
+            obj = if obj.method(:attributes).arity == 1
+                    obj.attributes(sanitize)
+                  else
+                    obj.attributes
+                  end
+          end
+
+          obj = obj.map { |elem| resolve_attributes(elem, sanitize) } \
+            if obj.is_a? Array
+
+          obj
+        end
+
+        # Explicitly convert the given struct to an +RecursiveOpenStruct+ and a
+        # deep symbolized key copy for further usage.
+        #
+        # @param data [Hash{Mixed => Mixed}, RecursiveOpenStruct] the initial
+        #   data
+        # @return [Array<RecursiveOpenStruct, Hash{Symbol => Mixed}>] the
+        #   left over data
+        def sanitize_data(data = {})
+          # Convert the given arguments to a recursive open struct,
+          # when not already done
+          data = ::RecursiveOpenStruct.new(data, recurse_over_arrays: true) \
+            unless data.is_a? ::RecursiveOpenStruct
+          # Symbolize all keys in deep (including hashes in arrays), while
+          # converting back to an ordinary hash
+          [data, data.to_h]
+        end
+
+        # Process the given data by separating the known from the unknown
+        # attributes. The unknown attributes are collected on the +_unmapped+
+        # variable for later access. This allows the entities to be
+        # forward-compatible on the application HTTP responses in case of
+        # additions.
+        #
+        # @param struct [RecursiveOpenStruct] all the data as struct
+        # @param hash [Hash{Symbol => Mixed}] all the data as hash
+        # @return [Hash{Symbol => Mixed}] the known attributes
+        def initialize_attributes(struct, hash)
+          # Substract known keys, to move them to the +_unmapped+ variable
+          attribute_names.each { |key| struct.delete_field(key) }
+          # Merge the previous unmapped struct and the given data
+          self._unmapped = \
+            ::RecursiveOpenStruct.new(_unmapped.to_h.merge(struct.to_h),
+                                      recurse_over_arrays: true)
+          # Allow mass assignment of known attributes
+          hash.slice(*attribute_names)
+        end
+      end
+
+      class_methods do
+        # Initialize the attributes structures on an inherited class.
+        #
+        # @param child_class [Class] the child class which inherits us
+        def inherited_setup_attributes(child_class)
+          child_class.attribute_names = []
+        end
+
+        # Register tracked attributes of the entity. This adds the attributes
+        # to the +Class.attribute_names+ collection, generates getters and
+        # setters as well sets up the dirty-tracking of these attributes.
+        #
+        # @param args [Array<Symbol>] the attributes to register
+        def tracked_attr(*args)
+          # Register the attribute names, for easy access
+          self.attribute_names += args
+          # Define getters/setters
+          attr_reader(*args)
+          args.each do |arg|
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def #{arg}=(value)
+                #{arg}_will_change!
+                @#{arg} = value
+              end
+            RUBY
+          end
+          # Register the attributes for ActiveModel
+          define_attribute_methods(*args)
+        end
+
+        # (Re-)Register attributes with strict type casts. This adds additional
+        # reader methods as well as a writer with casted type.
+        #
+        # @param name [Symbol, String] the name of the attribute
+        # @param type [Symbol] the type of the attribute
+        # @param args [Hash{Symbol => Mixed}] additional options for the type
+        def typed_attr(name, type, **args)
+          send("typed_attr_#{type}", name, **args)
+        end
+      end
+    end
+  end
+end

data/lib/pricehubble/entity/concern/callbacks.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  module EntityConcern
+    # Define all the base callbacks of a common entity.
+    module Callbacks
+      extend ActiveSupport::Concern
+
+      class_methods do
+        include ActiveModel::Callbacks
+      end
+
+      included do
+        # Define all the base callbacks
+        define_model_callbacks :initialize, only: :after
+      end
+    end
+  end
+end

data/lib/pricehubble/entity/concern/client.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  module EntityConcern
+    # Allow entities to define their low level HTTP client to use.
+    module Client
+      extend ActiveSupport::Concern
+
+      included do
+        # The class constant of the low level client
+        class_attribute :client_class
+
+        # Get the cached low level client instance.
+        #
+        # @return [Mixed] the client instance
+        def client
+          @client ||= client_class.new
+        end
+      end
+
+      class_methods do
+        # Allows an entity to configure the client it depends on.
+        #
+        # @param name [Symbol, String] the client name, in snake_case
+        def client(name)
+          self.client_class = PriceHubble.client(name).class
+        end
+      end
+    end
+  end
+end

data/lib/pricehubble/entity/coordinates.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  # The common PriceHubble coordinates object.
+  #
+  # @see https://docs.pricehubble.com/#types-coordinates
+  class Coordinates < BaseEntity
+    # Mapped and tracked attributes
+    tracked_attr :latitude, :longitude
+  end
+end

data/lib/pricehubble/entity/location.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  # The common PriceHubble location object.
+  #
+  # @see https://docs.pricehubble.com/#types-location
+  class Location < BaseEntity
+    # Associations
+    with_options(initialize: true, persist: true) do
+      has_one :address
+      has_one :coordinates
+    end
+  end
+end

data/lib/pricehubble/entity/property.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  # The common PriceHubble property object.
+  #
+  # @see https://docs.pricehubble.com/#types-property
+  class Property < BaseEntity
+    # All valid condition values
+    CONDITIONS = %i[renovation_needed well_maintained
+                    new_or_recently_renovated].freeze
+    # All valid quality values
+    QUALITIES = %i[simple normal high_quality luxury].freeze
+
+    # Mapped and tracked attributes
+    tracked_attr :location, :property_type, :building_year, :living_area,
+                 :land_area, :garden_area, :volume, :number_of_rooms,
+                 :number_of_bathrooms, :balcony_area,
+                 :number_of_indoor_parking_spaces,
+                 :number_of_outdoor_parking_spaces, :floor_number, :has_lift,
+                 :energy_label, :has_sauna, :has_pool,
+                 :number_of_floors_in_building, :is_furnished, :is_new,
+                 :renovation_year
+
+    # Associations
+    with_options(initialize: true, persist: true) do
+      has_one :location
+      has_one :property_type
+      has_one :condition, class_name: PropertyConditions
+      has_one :quality, class_name: PropertyQualities
+    end
+  end
+end

data/lib/pricehubble/entity/property_conditions.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  # The nested PriceHubble property condition object.
+  #
+  # @see https://docs.pricehubble.com/#types-property
+  class PropertyConditions < BaseEntity
+    # Mapped and tracked attributes
+    tracked_attr :bathrooms, :kitchen, :flooring, :windows, :masonry
+
+    # Define attribute types for casting
+    with_options(values: Property::CONDITIONS) do
+      typed_attr :bathrooms, :enum
+      typed_attr :kitchen, :enum
+      typed_attr :flooring, :enum
+      typed_attr :windows, :enum
+      typed_attr :masonry, :enum
+    end
+  end
+end

data/lib/pricehubble/entity/property_qualities.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  # The nested PriceHubble property quality object.
+  #
+  # @see https://docs.pricehubble.com/#types-property
+  class PropertyQualities < BaseEntity
+    # Mapped and tracked attributes
+    tracked_attr :bathrooms, :kitchen, :flooring, :windows, :masonry
+
+    # Define attribute types for casting
+    with_options(values: Property::QUALITIES) do
+      typed_attr :bathrooms, :enum
+      typed_attr :kitchen, :enum
+      typed_attr :flooring, :enum
+      typed_attr :windows, :enum
+      typed_attr :masonry, :enum
+    end
+  end
+end

data/lib/pricehubble/entity/property_type.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  # The common PriceHubble property type object.
+  #
+  # @see https://docs.pricehubble.com/#types-propertytype
+  class PropertyType < BaseEntity
+    # Mapped and tracked attributes
+    tracked_attr :code, :subcode
+
+    # Define attribute types for casting
+    typed_attr :code, :enum, values: %i[apartment house]
+    typed_attr :subcode, :enum, values: %i[apartment_normal
+                                           apartment_maisonette apartment_attic
+                                           apartment_penthouse
+                                           apartment_terraced apartment_studio
+                                           house_detached house_semi_detached
+                                           house_row_corner house_row_middle
+                                           house_farm]
+  end
+end

data/lib/pricehubble/entity/valuation.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  # The PriceHubble valuation result for a given property.
+  #
+  # @see https://docs.pricehubble.com/#international-valuation
+  class Valuation < BaseEntity
+    # Mapped and tracked attributes
+    tracked_attr :currency, :sale_price, :sale_price_range, :rent_gross,
+                 :rent_gross_range, :rent_net, :rent_net_range, :confidence,
+                 :scores, :status, :deal_type, :valuation_date, :country_code
+
+    # Define attribute types for casting
+    typed_attr :currency, :string_inquirer
+    typed_attr :confidence, :string_inquirer
+    typed_attr :deal_type, :string_inquirer
+    typed_attr :country_code, :string_inquirer
+    typed_attr :sale_price_range, :range
+    typed_attr :rent_gross_range, :range
+    typed_attr :rent_net_range, :range
+
+    # Associations
+    with_options(persist: true, initialize: true) do
+      has_one :property
+      has_one :scores, class_name: ValuationScores
+    end
+
+    # A streamlined helper to get the value by the deal type. (sale price
+    # if deal type is +sale+ or gross rent value if deal type is +rent+)
+    #
+    # @return [Integer, nil] the value of the property
+    def value
+      return sale_price if deal_type.sale?
+
+      rent_gross
+    end
+
+    # A streamlined helper to get the value range by the deal type. (sale price
+    # range if deal type is +sale+ or gross rent range if deal type is +rent+)
+    #
+    # @return [Range, nil] the value range of the property
+    def value_range
+      return sale_price_range if deal_type.sale?
+
+      rent_gross_range
+    end
+  end
+end

data/lib/pricehubble/entity/valuation_request.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  # The PriceHubble valuation request for one or more properties.
+  #
+  # @see https://docs.pricehubble.com/#international-valuation
+  class ValuationRequest < BaseEntity
+    # Configure the client to use
+    client :valuation
+
+    # Mapped and tracked attributes
+    tracked_attr :deal_type, :valuation_dates, :properties, :return_scores,
+                 :country_code
+
+    # Define attribute types for casting
+    typed_attr :deal_type, :enum, values: %i[sale rent]
+    typed_attr :valuation_dates, :date_array
+    typed_attr :country_code, :string_inquirer
+
+    # Associations
+    has_many :properties, fallback_from: :property,
+                          persist: true,
+                          initialize: true
+
+    # Set some defaults when initialized
+    after_initialize do
+      self.deal_type ||= :sale
+      self.valuation_dates ||= [Date.current]
+      self.return_scores = false if return_scores.nil?
+      self.country_code ||= 'DE'
+    end
+
+    # For transportation the +properties+ array name must be changed to reflect
+    # the actual API specification.
+    #
+    # @return [Symbol] the sanitized name of the properties array
+    def sanitize_attr_key_properties
+      :valuation_inputs
+    end
+
+    # For transportation the +properties+ array must be sanitized
+    # to reflect the actual API specification.
+    #
+    # @return [Array<Hash{String => Mixed}>] the sanitized properties
+    def sanitize_attr_properties
+      properties.map { |prop| { property: prop.attributes(true) } }
+    end
+
+    # Perform the property valuation request.
+    #
+    # @param args [Hash{Symbol => Mixed}] additional options
+    # @return [Array<PriceHubble::Valuation>] the valuation results
+    def perform(**args)
+      client.property_value(self, **args) || []
+    end
+
+    # Generate bang method variants
+    bangers :perform
+  end
+end

data/lib/pricehubble/entity/valuation_scores.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  # The nested PriceHubble valuation scores object.
+  #
+  # @see https://docs.pricehubble.com/#international-valuation
+  class ValuationScores < BaseEntity
+    # Mapped and tracked attributes
+    tracked_attr :quality, :condition, :location
+  end
+end

data/lib/pricehubble/errors.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  # Generic entity exception class.
+  class EntityError < StandardError
+  end
+
+  # Generic request/response exception class.
+  class RequestError < StandardError
+    attr_reader :response
+
+    # Create a new instance of the error.
+    #
+    # @param message [String] the error message
+    # @param response [Faraday::Response] the response
+    def initialize(message = nil, response = nil)
+      @response = response
+      message ||= response.body.message if response.body.respond_to? :message
+
+      super(message)
+    end
+  end
+
+  # Raised when the authentication request failed.
+  class AuthenticationError < RequestError; end
+
+  # Raised when an entity was not found while searching/getting.
+  class EntityNotFound < EntityError
+    attr_reader :entity, :criteria
+
+    # Create a new instance of the error.
+    #
+    # @param message [String] the error message
+    # @param entity [PriceHubble::BaseEntity] the entity which was not found
+    # @param criteria [Hash{Symbol => Mixed}] the search/find criteria
+    def initialize(message = nil, entity = nil, criteria = {})
+      @entity = entity
+      @criteria = criteria
+      message ||= "Couldn't find #{entity} with #{criteria.inspect}"
+
+      super(message)
+    end
+  end
+
+  # Raised when the record is invalid, due to a response.
+  class EntityInvalid < EntityError
+    attr_reader :entity
+
+    # Create a new instance of the error.
+    #
+    # @param message [String] the error message
+    # @param entity [PriceHubble::BaseEntity] the entity which was invalid
+    def initialize(message = nil, entity = nil)
+      @entity = entity
+      message ||= "Invalid #{entity}"
+
+      super(message)
+    end
+  end
+end

data/lib/pricehubble/faraday.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# Register our custom faraday middlewares
+Faraday::Request.register_middleware \
+  ph_data_sanitization: PriceHubble::Client::Request::DataSanitization
+Faraday::Request.register_middleware \
+  ph_default_headers: PriceHubble::Client::Request::DefaultHeaders
+
+Faraday::Response.register_middleware \
+  ph_data_sanitization: PriceHubble::Client::Response::DataSanitization
+Faraday::Response.register_middleware \
+  ph_recursive_open_struct: PriceHubble::Client::Response::RecursiveOpenStruct

data/lib/pricehubble/identity.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  # Handles all the identity retrival high-level logic.
+  #
+  # rubocop:disable Style/ClassVars because we split module code
+  module Identity
+    extend ActiveSupport::Concern
+    class_methods do
+      # Reset the current identity.
+      def reset_identity!
+        @@identity = nil
+      end
+
+      # Get the current identity we use for all requests.  We try to
+      # authenticate against the PriceHubble Authentication API with the
+      # configured credentials from the Gem configuration.
+      # (+PriceHubble.configuration+) In case this went well, we cache the
+      # result. Otherwise we raise an +AuthenticationError+.
+      #
+      # @return [PriceHubble::Authentication] the authentication instance
+      # @raise [AuthenticationError] in case of a failed login
+      def identity
+        # Fetch a new identity with the configured identity settings from the
+        # Gem configuration
+        @@identity ||= auth_by_config
+        # Take care of an expired identity
+        @@identity = auth_by_config if @@identity.expired?
+        # Pass back the actual identity instance
+        @@identity
+      end
+
+      private
+
+      # Perform the authentication via the configured identity credentials.
+      #
+      # @return [Hausgold::Jwt] the new JWT instance
+      # @raise [AuthenticationError] in case of a failed login
+      def auth_by_config
+        args = identity_params.dup
+        client(:authentication).login!(**args)
+      end
+    end
+  end
+  # rubocop:enable Style/ClassVars
+end

data/lib/pricehubble/railtie.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  # Rails-specific initializations.
+  class Railtie < Rails::Railtie
+    # Run before all Rails initializers, but after the application is defined
+    config.before_initialize do
+      # Nothing to do here at the moment.
+    end
+
+    # Run after all configuration is set via Rails initializers
+    config.after_initialize do
+      # Nothing to do here at the moment.
+    end
+  end
+end

data/lib/pricehubble/utils/bangers.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  module Utils
+    # Generate bang variants of methods which use the +Decision+ flow control.
+    module Bangers
+      extend ActiveSupport::Concern
+
+      class_methods do
+        # Generate bang variants for the given methods.
+        # Be sure to use the +bangers+ class method AFTER all method
+        # definitions, otherwise it will raise errors about missing methods.
+        #
+        # @param methods [Array<Symbol>] the source method names
+        # @raise [NoMethodError] when a source method is not defined
+        # @raise [ArgumentError] when a source method does not accept arguments
+        #
+        # rubocop:disable Metrics/MethodLength because the method template
+        #   is better inlined
+        def bangers(*methods)
+          methods.each do |meth|
+            raise NoMethodError, "#{self}##{meth} does not exit" \
+              unless instance_methods(false).include? meth
+
+            raise ArgumentError, "#{self}##{meth} does not accept arguments" \
+              if instance_method(meth).arity.zero?
+
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def #{meth}!(*args)
+                if args.last.is_a? Hash
+                  args.last.merge!(bang: true)
+                else
+                  args.push({ bang: true })
+                end
+                #{meth}(*args)
+              end
+            RUBY
+          end
+        end
+        # rubocop:enable Metrics/MethodLength
+      end
+    end
+  end
+end