pricehubble 0.1.0

data/doc/examples/complex_property_valuations.rb

@@ -0,0 +1,91 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative './config'
+
+# Build a property with all relevant information for the valuation. This
+# example reflects not the full list of supported fields, [see the API
+# specification](https://docs.pricehubble.com/#types-property) for the full
+# details.
+apartment = PriceHubble::Property.new(
+  location: {
+    address: {
+      post_code: '22769',
+      city: 'Hamburg',
+      street: 'Stresemannstr.',
+      house_number: '29'
+    }
+  },
+  property_type: { code: :apartment },
+  building_year: 1990,
+  living_area: 200,
+  balcony_Area: 30,
+  floor_number: 5,
+  has_lift: true,
+  is_furnished: false,
+  is_new: false,
+  renovation_year: 2014,
+  condition: {
+    bathrooms: :well_maintained,
+    kitchen: :well_maintained,
+    flooring: :well_maintained,
+    windows: :well_maintained,
+    masonry: :well_maintained
+  },
+  quality: {
+    bathrooms: :normal,
+    kitchen: :normal,
+    flooring: :normal,
+    windows: :normal,
+    masonry: :normal
+  }
+)
+
+house = PriceHubble::Property.new(
+  location: {
+    address: {
+      post_code: '22769',
+      city: 'Hamburg',
+      street: 'Stresemannstr.',
+      house_number: '29'
+    }
+  },
+  property_type: { code: :house },
+  building_year: 1990,
+  land_area: 100,
+  living_area: 500,
+  number_of_floors_in_building: 5
+)
+
+# Fetch the property valuations for multiple properties, on multiple dates
+request = PriceHubble::ValuationRequest.new(
+  deal_type: :sale,
+  properties: [apartment, house],
+  # The dates order is reflected on the valuations list
+  valuation_dates: [
+    1.year.ago,
+    Date.current,
+    1.year.from_now
+  ]
+)
+valuations = request.perform!
+
+# Print the valuations in a simple ASCII table. This is just a
+# demonstration of how to use the valuations for a simple usecase.
+require 'terminal-table'
+table = Terminal::Table.new do |tab|
+  tab << ['Deal Type', 'Property Type', *request.valuation_dates.map(&:year)]
+  tab << :separator
+  # Group the valuations by the property they represent
+  valuations.group_by(&:property).each do |property, valuations|
+    tab << [request.deal_type, property.property_type.code,
+            *valuations.map { |val| "#{val.value} #{val.currency}" }]
+  end
+end
+puts table
+# => +-----------+---------------+-------------+-------------+-------------+
+# => | Deal Type | Property Type | 2018        | 2019        | 2020        |
+# => +-----------+---------------+-------------+-------------+-------------+
+# => | sale      | apartment     | 1282100 EUR | 1373100 EUR | 1420100 EUR |
+# => | sale      | house         | 1824800 EUR | 1950900 EUR | 2016000 EUR |
+# => +-----------+---------------+-------------+-------------+-------------+

data/doc/examples/config.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'pricehubble'
+
+PriceHubble.reset_configuration!
+PriceHubble.configure do |conf|
+  # conf.request_logging = true
+end
+
+errors = false
+
+if ENV['PRICEHUBBLE_USERNAME'].blank?
+  errors = true
+  puts '> [ERR] Environment variable `PRICEHUBBLE_USERNAME` is missing.'
+end
+
+if ENV['PRICEHUBBLE_PASSWORD'].blank?
+  errors = true
+  puts '> [ERR] Environment variable `PRICEHUBBLE_PASSWORD` is missing.'
+end
+
+if errors
+  puts
+  puts '> Usage:'
+  puts ">   $ export PRICEHUBBLE_USERNAME='your-username'"
+  puts ">   $ export PRICEHUBBLE_PASSWORD='your-password'"
+  puts ">   $ #{$PROGRAM_NAME} #{ARGV.join(' ')}"
+  exit
+end

data/doc/examples/property_valuations_errors.rb

@@ -0,0 +1,30 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative './config'
+
+begin
+  # Fetch the valuations for a single property (sale) for today (defaults).
+  # This is the bare minimum variant, as a starting point.
+  PriceHubble::ValuationRequest.new(
+    property: {
+      location: {
+        address: {
+          post_code: '22769',
+          city: 'Hamburg',
+          street: 'Stresemannstr.',
+          house_number: '29'
+        }
+      },
+      property_type: { code: :apartment },
+      building_year: 2999,
+      living_area: 200
+    }
+  ).perform!
+rescue PriceHubble::EntityInvalid => e
+  # => #<PriceHubble::EntityInvalid: buildingYear: ...>
+
+  # The error message includes the detailed problem.
+  pp e.message
+  # => "buildingYear: Must be between 1850 and 2022."
+end

data/doc/examples/simple_property_valuations.rb

@@ -0,0 +1,69 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative './config'
+
+# Fetch the valuations for a single property (sale) for today (defaults).
+# This is the bare minimum variant, as a starting point.
+valuations = PriceHubble::ValuationRequest.new(
+  property: {
+    location: {
+      address: {
+        post_code: '22769',
+        city: 'Hamburg',
+        street: 'Stresemannstr.',
+        house_number: '29'
+      }
+    },
+    property_type: { code: :apartment },
+    building_year: 1990,
+    living_area: 200
+  }
+).perform!
+# => [#<PriceHubble::Valuation ...>]
+
+# Print all relevant valuation attributes
+pp valuations.first.attributes.deep_compact
+# => {"currency"=>"EUR",
+# =>  "sale_price"=>1283400,
+# =>  "sale_price_range"=>1180800..1386100,
+# =>  "confidence"=>"good",
+# =>  "deal_type"=>"sale",
+# =>  "valuation_date"=>Thu, 17 Oct 2019,
+# =>  "country_code"=>"DE",
+# =>  "property"=>
+# =>   {"location"=>
+# =>     {"address"=>
+# =>       {"post_code"=>"22769",
+# =>        "city"=>"Hamburg",
+# =>        "street"=>"Stresemannstr.",
+# =>        "house_number"=>"29"}},
+# =>    "property_type"=>{"code"=>:apartment},
+# =>    "building_year"=>1990,
+# =>    "living_area"=>200}}
+
+# We just want to work on the first valuation
+valuation = valuations.first
+
+# Get the deal type dependent value of the property in a generic way.
+# (sale price if deal type is sale, and rent gross if deal type is rent)
+pp valuation.value
+# => 1283400
+
+# Get the upper and lower value range of the property in a generic
+# way. The deal type logic is equal to the
+# +PriceHubble::Valuation#value+ method.
+pp valuation.value_range
+# => 1180800..1386100
+
+# Query the valuation confidence in an elegant way
+pp valuation.confidence.good?
+# => true
+
+# The +PriceHubble::Valuation+ entity is a self contained
+# representation of the request and response. This means it includes
+# the property, deal type, valuation date, country code, etc it was
+# requested for. This makes it easy to process the data because
+# everything related is in one place.
+pp valuation.property.property_type.apartment?
+# => true

data/docker-compose.yml

@@ -0,0 +1,9 @@
+version: "3"
+services:
+  test:
+    build: .
+    env_file: Envfile
+    network_mode: bridge
+    working_dir: /app
+    volumes:
+      - .:/app

data/gemfiles/rails_4.2.gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'activemodel', '~> 4.2.11'
+gem 'activesupport', '~> 4.2.11'
+gem 'railties', '~> 4.2.11'
+
+gemspec path: '../'

data/gemfiles/rails_5.0.gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'activemodel', '~> 5.0.7'
+gem 'activesupport', '~> 5.0.7'
+gem 'railties', '~> 5.0.7'
+
+gemspec path: '../'

data/gemfiles/rails_5.1.gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'activemodel', '~> 5.1.6'
+gem 'activesupport', '~> 5.1.6'
+gem 'railties', '~> 5.1.6'
+
+gemspec path: '../'

data/gemfiles/rails_5.2.gemfile

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# This file was generated by Appraisal
+
+source 'https://rubygems.org'
+
+gem 'activemodel', '~> 5.2.2'
+gem 'activesupport', '~> 5.2.2'
+gem 'railties', '~> 5.2.2'
+
+gemspec path: '../'

data/lib/price_hubble.rb

@@ -0,0 +1,3 @@
+# frozen_string_literal: true
+
+require 'pricehubble'

data/lib/pricehubble/client/authentication.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  module Client
+    # A high level client library for the PriceHubble Authentication API.
+    class Authentication < Base
+      # Perform a login request while sending the passed credentials.
+      #
+      # @param args [Hash{Symbol => Mixed}] the authentication credentials
+      # @return [PriceHubble::Authentication, nil] the authentication entity,
+      #   or +nil+ on error
+      def login(**args)
+        res = connection.post do |req|
+          req.path = '/auth/login/credentials'
+          req.body = args.except(:bang)
+          use_default_context(req, :login)
+        end
+        decision(bang: args.fetch(:bang, false)) do |result|
+          result.bang { PriceHubble::AuthenticationError.new(nil, res) }
+          result.good { PriceHubble::Authentication.new(res.body) }
+          successful?(res)
+        end
+      end
+
+      # Generate bang method variants
+      bangers :login
+    end
+  end
+end

data/lib/pricehubble/client/base.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  module Client
+    # The base API client class definition. It bundles all the separated
+    # application logic on a low level.
+    class Base
+      include PriceHubble::Client::Utils::Request
+      include PriceHubble::Client::Utils::Response
+      include PriceHubble::Utils::Decision
+      include PriceHubble::Utils::Bangers
+
+      # Configure the connection instance in a generic manner. Each client can
+      # modify the connection in a specific way, when the application requires
+      # special handling. Just overwrite the +configure+ method, and call
+      # +super(con)+. Here is a full example:
+      #
+      #   def configure(con)
+      #     super(con)
+      #     con.request :url_encoded
+      #     con.response :logger
+      #     con.adapter Faraday.default_adapter
+      #   end
+      #
+      # @param con [Faraday::Connection] the connection object
+      #
+      # rubocop:disable Metrics/MethodLength because of the middleware list
+      def configure(con)
+        con.use :instrumentation
+
+        # The definition order is execution order
+        con.request :ph_data_sanitization
+        con.request :ph_default_headers
+        con.request :json
+        con.request :multipart
+        con.request :url_encoded
+
+        # The definition order is reverse to the execution order
+        con.response :ph_recursive_open_struct
+        con.response :ph_data_sanitization
+        con.response :dates
+        con.response :json, content_type: /\bjson$/
+        con.response :follow_redirects
+
+        con.adapter Faraday.default_adapter
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Create a new Faraday connection on the first shot, and pass the cached
+      # connection object on subsequent calls.
+      #
+      # @return [Faraday::Connection] the connection object
+      def connection
+        @connection ||= Faraday.new(url: PriceHubble.configuration.base_url,
+                                    &method(:configure))
+      end
+    end
+  end
+end

data/lib/pricehubble/client/request/data_sanitization.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  module Client
+    module Request
+      # We like snake cased attributes here, but the API requires camel cased
+      # hash keys, so we take care of it in a generic way here. Furthermore, we
+      # perform a deep compaction of the given body hash, to strip +nil+ values
+      # and empty hashes from the request. There is no need to send null-data
+      # on a round trip.
+      class DataSanitization < Faraday::Middleware
+        # Serve the Faraday middleware API.
+        #
+        # @param env [Hash{Symbol => Mixed}] the request
+        def call(env)
+          body = env[:body]
+
+          # Perform the data compaction and the hash key transformation,
+          # when the body is available and a hash
+          env[:body] = body.deep_compact.deep_camelize_keys \
+            if body&.is_a?(Hash)
+
+          @app.call(env)
+        end
+      end
+    end
+  end
+end

data/lib/pricehubble/client/request/default_headers.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  module Client
+    module Request
+      # Add some default headers to every request.
+      class DefaultHeaders < Faraday::Middleware
+        # Serve the Faraday middleware API.
+        #
+        # @param env [Hash{Symbol => Mixed}] the request
+        def call(env)
+          env[:request_headers].merge! \
+            'User-Agent' => user_agent,
+            'Accept' => 'application/json'
+
+          # Set request content type to JSON as fallback
+          env[:request_headers]['Content-Type'] = 'application/json' \
+            if env[:request_headers]['Content-Type'].blank?
+
+          @app.call(env)
+        end
+
+        # Build an useful user agent string to pass. We identify ourself as
+        # +PriceHubbleGem+ with the current gem version.
+        #
+        # @return [String] the user agent string
+        def user_agent
+          "PriceHubbleGem/#{PriceHubble::VERSION}"
+        end
+      end
+    end
+  end
+end

data/lib/pricehubble/client/response/data_sanitization.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  module Client
+    module Response
+      # We like snake cased attributes here, but the API sends camel cased
+      # hash keys on responses, so we take care of it in a generic way here.
+      class DataSanitization < Faraday::Middleware
+        # Serve the Faraday middleware API.
+        #
+        # @param env [Hash{Symbol => Mixed}] the request
+        def call(env)
+          @app.call(env).on_complete do |res|
+            body = res[:body]
+
+            # Skip string bodies, they are unparsed or contain binary data
+            next if body.is_a? String
+
+            # Skip non-hash bodies, we cannot handle them here
+            next unless body.is_a? Hash
+
+            # Perform the key transformation
+            res[:body] = body.deep_underscore_keys
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pricehubble/client/response/recursive_open_struct.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  module Client
+    module Response
+      # Convert every response body to an +RecursiveOpenStruct+ for an easy
+      # access.
+      class RecursiveOpenStruct < Faraday::Middleware
+        # Serve the Faraday middleware API.
+        #
+        # @param env [Hash{Symbol => Mixed}] the request
+        def call(env)
+          @app.call(env).on_complete do |res|
+            body = res[:body]
+
+            # Skip string bodies, they are unparsed or contain binary data
+            next if body.is_a? String
+
+            # By definition empty responses (HTTP status 204)
+            # or actual empty bodies should be an empty hash
+            body = {} if res[:status] == 204 || res[:body].empty?
+
+            # Looks like we have some actual data we can wrap
+            res[:body] = \
+              ::RecursiveOpenStruct.new(body, recurse_over_arrays: true)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pricehubble/client/utils/request.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  module Client
+    module Utils
+      # Some helpers to prepare requests in a general way.
+      #
+      module Request
+        extend ActiveSupport::Concern
+
+        included do
+          # A common HTTP content type to symbol
+          # mapping for correct header settings.
+          CONTENT_TYPE = {
+            json: 'application/json',
+            multipart: 'multipart/form-data',
+            url_encoded: 'application/x-www-form-urlencoded'
+          }.freeze
+
+          # Use the configured identity to authenticate the given request.
+          #
+          # @param req [Faraday::Request] the request to manipulate
+          def use_authentication(req)
+            req.params.merge!(access_token: PriceHubble.identity.access_token)
+          end
+
+          # Use the default request context to identificate the request.
+          #
+          # @param action [String, Symbol] the used client action
+          # @param req [Faraday::Request] the request to manipulate
+          def use_default_context(req, action)
+            req.options.context ||= {}
+            req.options.context.merge!(client: self.class,
+                                       action: action,
+                                       request_id: SecureRandom.hex(3))
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pricehubble/client/utils/response.rb

@@ -0,0 +1,60 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  module Client
+    module Utils
+      # Some helpers to work with responses in a general way.
+      module Response
+        extend ActiveSupport::Concern
+
+        included do
+          # Simple helper to query the response status.
+          #
+          # @param res [Faraday::response] the response object
+          # @param code [Range, Array, Integer] the range of good
+          #   response codes
+          # @return [Boolean] whenever the request got an allowed status
+          def status?(res, code: 0..399)
+            code = [code] unless code.is_a? Range
+            code = code.flatten if code.is_a? Array
+            code.include? res.status
+          end
+          alias_method :successful?, :status?
+
+          # A simple syntactic sugar helper to query the response status.
+          #
+          # @param res [Faraday::response] the response object
+          # @param code [Range] the range of failed response codes
+          # @return [Boolean] whenever the request failed
+          def failed?(res, code: 400..600)
+            status?(res, code: code)
+          end
+
+          # Perform a common error handling for entity responses. This allows a
+          # clean usage of the decision flow control. Here comes an example:
+          #
+          #   decision do |result|
+          #     result.bang(&bang_entity(entity, res, id: entity.id))
+          #   end
+          #
+          # @param entity [PriceHubble::BaseEntity, Class] the result entity
+          # @param res [Faraday::Response] the response object
+          # @param data [Hash{Mixed => Mixed}] the request data
+          # @return [Proc] the proc which performs the error handling
+          def bang_entity(entity, res, data)
+            class_name = entity
+            class_name = entity.class unless entity.is_a? Class
+            lambda do
+              next PriceHubble::EntityNotFound.new(nil, class_name, data) \
+                if res.status == 404
+              next PriceHubble::EntityInvalid.new(res.body.message, entity) \
+                if res.status == 400
+
+              PriceHubble::RequestError.new(nil, res)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pricehubble/client/valuation.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  module Client
+    # A high level client library for the PriceHubble Valuation API.
+    class Valuation < Base
+      # Perform a full-fledged valuation request.
+      #
+      # @param request [PriceHubble::ValuationRequest] the valuation request
+      # @param args [Hash{Symbol => Mixed}] the authentication credentials
+      # @return [Array<PriceHubble::Valuation>, nil] the valuation results,
+      #   or +nil+ on error
+      #
+      # rubocop:disable Metrics/MethodLength because of the request handling
+      def property_value(request, **args)
+        data = request.attributes(true)
+        res = connection.post do |req|
+          req.path = '/api/v1/valuation/property_value'
+          req.body = data
+          use_default_context(req, :property_value)
+          use_authentication(req)
+        end
+        decision(bang: args.fetch(:bang, false)) do |result|
+          result.bang(&bang_entity(request, res, data))
+          result.good(&assign_valuations(res.body.valuations, request))
+          successful?(res)
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Map and assign the valuation response to our local
+      # +PriceHubble::Valuation+ representation. While taking care of the
+      # multi-dimensional array structure which is reflected from the request
+      # data. You get back a lambda which you need to call to get the results
+      # (for use in a decision). The return values is a
+      # +Array<PriceHubble::Valuation>+.
+      #
+      # @param data [Array<Array<RecursiveOpenStruct>>] the raw response
+      #   valuations data
+      # @param request [PriceHubble::ValuationRequest] the original request
+      # @return [Proc] the valuation mapping code
+      #
+      # rubocop:disable Metrics/MethodLength because of the request
+      #   to response mapping
+      def assign_valuations(data, request)
+        lambda do
+          # valuations[i][j] contains the valuation for property i on date j
+          data.each_with_index.map do |valuations, property_idx|
+            valuations.each_with_index.map do |valuation, date_idx|
+              # Fetch the request data for this valuation and
+              # extend the raw data to build a local representation
+              valuation.property = request.properties[property_idx]
+              valuation.valuation_date = request.valuation_dates[date_idx]
+              valuation.deal_type = request.deal_type
+              valuation.country_code = request.country_code
+              # Build the local representation from the raw data
+              PriceHubble::Valuation.new(valuation)
+            end
+          end.flatten
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Generate bang method variants
+      bangers :property_value
+    end
+  end
+end