pricehubble 0.1.0

data/README.md

@@ -0,0 +1,385 @@
+![PriceHubble](doc/assets/project.svg)
+
+[![Build Status](https://travis-ci.com/hausgold/pricehubble.svg?token=4XcyqxxmkyBSSV3wWRt7&branch=master)](https://travis-ci.com/hausgold/pricehubble)
+[![Gem Version](https://badge.fury.io/rb/pricehubble.svg)](https://badge.fury.io/rb/pricehubble)
+[![Maintainability](https://api.codeclimate.com/v1/badges/cd15f59fc84566e4b200/maintainability)](https://codeclimate.com/repos/5da572bd60163201b800c255/maintainability)
+[![Test Coverage](https://api.codeclimate.com/v1/badges/cd15f59fc84566e4b200/test_coverage)](https://codeclimate.com/repos/5da572bd60163201b800c255/test_coverage)
+[![API docs](https://img.shields.io/badge/docs-API-blue.svg)](https://www.rubydoc.info/gems/pricehubble)
+
+This project is dedicated to build a client/API wrapper around the
+[PriceHubble](https://pricehubble.com) REST API. It follows strictly the
+[version 1 of the API specification](https://docs.pricehubble.com). Furthermore
+this gem allows you to easily interact with common PriceHubble operations like
+fetching property valuations. At the time of writing it supports not the full
+API specification, but it should be easy to enhance the client functionality,
+so feel free to send a pull request.
+
+- [Installation](#installation)
+- [Usage](#usage)
+  - [Configuration](#configuration)
+    - [Available environment variables](#available-environment-variables)
+  - [Authentication](#authentication)
+  - [Error Handling](#error-handling)
+  - [Property Valuations](#property-valuations)
+    - [Bare Minimum Request Example](#bare-minimum-request-example)
+    - [Use the PriceHubble::Valuation representation](#use-the-pricehubblevaluation-representation)
+    - [Error Handling](#error-handling-1)
+    - [Advanced Request Examples](#advanced-request-examples)
+- [Development](#development)
+- [Contributing](#contributing)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'pricehubble'
+```
+
+And then execute:
+
+```bash
+$ bundle
+```
+
+Or install it yourself as:
+
+```bash
+$ gem install pricehubble
+```
+
+## Usage
+
+### Configuration
+
+You can configure the pricehubble gem via an Rails initializer, by environment
+variables or on demand. Here we show a common Rails initializer example:
+
+```ruby
+PriceHubble.configure do |conf|
+  # Configure the API authentication credentials
+  conf.username = 'your-username'
+  conf.password = 'your-password'
+
+  # The base URL of the API (there is no staging/canary
+  # endpoint we know about)
+  conf.base_url = 'https://api.pricehubble.com'
+
+  # Writes to stdout by default
+  conf.logger = Logger.new(IO::NULL)
+end
+```
+
+The pricehubble gem comes with sensitive defaults as you can see. For most
+users an extra configuration, beside the authorization credentials, is not
+needed.
+
+#### Available environment variables
+
+The pricehubble gem can be configured hardly with its configuration code block
+like shown before. Respecting the [twelve-factor app](https://12factor.net/)
+concerns, the gem allows you to set almost all configurations (just the
+relevant ones for runtime) via environment variables. Here comes a list of
+available configuration options:
+
+* **PRICEHUBBLE_USERNAME**: The API username to use for authentication.
+* **PRICEHUBBLE_PASSWORD**: The API password to use for authentication.
+* **PRICEHUBBLE_BASE_URL**: The base URL of the API. Defaults to the production one.
+
+### Authentication
+
+After configuring the pricehubble gem you can directly fetch an
+authentication which is valid for two hours. All operational requests
+require an authentication to be present and unexpired. But now comes
+the good part: you don't ever need to take care about this, because
+the gem handles the refreshing of the authentication transparently for
+you and also takes care of passing the authentication to each request
+you can do with the gem.
+
+```ruby
+# Fetch the authentication/identity for the first time, subsequent calls
+# to this method will return the cached authentication instance until it
+# is expired (or near expiration, 5 minutes leeway) then a new
+# authentication is fetched transparently
+PriceHubble.identity
+# => #<PriceHubble::Authentication access_token="...", ...>
+
+# Check the expiration state (transparently always unexpired)
+PriceHubble.identity.expired?
+# => false
+
+# Get the current authentication expiration date/time
+PriceHubble.identity.expires_at
+# => 2019-10-17 08:01:23 +0000
+```
+
+### Error Handling
+
+The pricehubble gem allows you to decide how to react on errors on a
+per-request basis. (except the transparent authentication) All request
+performing methods are shiped in a bang and non-bang variant.
+
+The bang variants (eg. `PriceHubble::ValuationRequest#perform!`, mind
+the exclamation mark at the end) will raise an child instance of the
+`PriceHubble::RequestError` or `PriceHubble::EntityError` class ([see
+errors for more details](lib/pricehubble/errors.rb)) when errors
+occur. This comes in handy on asynchronous jobs which are retried on
+exceptions.
+
+The non-bang variants (eg. `PriceHubble::ValuationRequest#perform`,
+without the exclamation mark) wont raise and just return empty results
+(eg. `false` or `[]`). This might me comfortable in complex control
+flows or when you do not care if one out of 100 times the data is
+missing. But watch out for bad/invalid requests you might mask with
+this behaviour.
+
+It's up to you to choose the correct flavor for your usecase.
+
+### Property Valuations
+
+The pricehubble gem allows you to request property valuations easily.
+You can formulate your request elegantly with in-place attribute sets
+or already built instances the same way. Furthermore the gem ships
+some sensible defaults which makes it even more easy to get an
+valuation for a property.
+
+The `PriceHubble::ValuationRequest` allows to fetch valuations for one
+or more (bulk) properties at once for one or several dates. The upper
+limit for this is `properties.count * dates.count <= 50` from API
+side.
+
+**Gotcha!** The API allows to fetch property valuations with
+per-property independent time series. The pricehubble gem does not
+support this for the sake of ease.
+
+#### Bare Minimum Request Example
+
+```ruby
+# 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}}
+```
+
+#### Use the PriceHubble::Valuation representation
+
+The [`PriceHubble::Valuation`](lib/pricehubble/entity/valuation.rb)
+representation ships a lot utilities and helpers to process the data.
+Here are some examples:
+
+```ruby
+# Fetch the valuations
+valuations = PriceHubble::ValuationRequest.new(...).perform!
+# 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)
+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.
+valuation.value_range
+# => 1180800..1386100
+
+# Query the valuation confidence in an elegant way
+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.
+valuation.property.property_type.apartment?
+# => true
+```
+
+#### Error Handling
+
+The property valuation API is able to perform bulk operations which
+may result in non-bang situations, even when you use the bang variant.
+This is quite smart as a single property valuation might not break
+others on the very same request. Watch for the
+`PriceHubble::Valuation#status` hash, when it is not nil, then you got
+an error for this valuation.
+
+In case you request just one property valuation, then the API will
+respond an error which is mapped when you use the bang variants.
+
+```ruby
+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.
+  e.message
+  # => "buildingYear: Must be between 1850 and 2022."
+end
+```
+
+#### Advanced Request Examples
+
+Here comes a more complex example of a property valuations request
+with multiple properties, for several valuations dates.
+
+**Gotcha!** The API does not allow you to mix and match the deal type
+per property. Therefore you need to set it once for the whole request.
+
+```ruby
+# 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
+# => +-----------+---------------+-------------+-------------+-------------+
+# => | Deal Type | Property Type | 2018        | 2019        | 2020        |
+# => +-----------+---------------+-------------+-------------+-------------+
+# => | sale      | apartment     | 1282100 EUR | 1373100 EUR | 1420100 EUR |
+# => | sale      | house         | 1824800 EUR | 1950900 EUR | 2016000 EUR |
+# => +-----------+---------------+-------------+-------------+-------------+
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`bundle exec rake spec` to run the tests. You can also run `bin/console` for an
+interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To
+release a new version, update the version number in `version.rb`, and then run
+`bundle exec rake release`, which will create a git tag for the version, push
+git commits and tags, and push the `.gem` file to
+[rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at
+https://github.com/hausgold/pricehubble.

data/Rakefile

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+require 'rails/code_statistics'
+require 'pp'
+
+RSpec::Core::RakeTask.new(:spec)
+
+task default: :spec
+
+# Load some railties tasks
+load 'rails/tasks/statistics.rake'
+load 'rails/tasks/annotations.rake'
+
+# Clear the default statistics directory constant
+#
+# rubocop:disable Style/MutableConstant because we define it
+Object.send(:remove_const, :STATS_DIRECTORIES)
+::STATS_DIRECTORIES = []
+# rubocop:enable Style/MutableConstant
+
+# Monkey patch the Rails +CodeStatistics+ class to support configurable
+# patterns per path. This is reuqired to support top-level only file matches.
+class CodeStatistics
+  DEFAULT_PATTERN = /^(?!\.).*?\.(rb|js|coffee|rake)$/.freeze
+
+  # Pass the possible +pattern+ argument down to the
+  # +calculate_directory_statistics+ method call.
+  def calculate_statistics
+    Hash[@pairs.map do |pair|
+      [pair.first, calculate_directory_statistics(*pair[1..-1])]
+    end]
+  end
+
+  # Match the pattern against the individual file name and the relative file
+  # path. This allows top-level only matches.
+  def calculate_directory_statistics(directory, pattern = DEFAULT_PATTERN)
+    stats = CodeStatisticsCalculator.new
+
+    Dir.foreach(directory) do |file_name|
+      path = "#{directory}/#{file_name}"
+
+      if File.directory?(path) && (/^\./ !~ file_name)
+        stats.add(calculate_directory_statistics(path, pattern))
+      elsif file_name =~ pattern || path =~ pattern
+        stats.add_by_file_path(path)
+      end
+    end
+
+    stats
+  end
+end
+
+# Configure all code statistics directories
+vendors = [
+  [:unshift, 'Clients', 'lib/pricehubble/client'],
+  [:unshift, 'Entities', 'lib/pricehubble/entity'],
+  [:unshift, 'Utilities', 'lib/pricehubble/utils'],
+  [:unshift, 'Top-levels', 'lib', %r{lib(/pricehubble)?/[^/]+\.rb$}],
+
+  [:unshift, 'Clients specs', 'spec/client'],
+  [:unshift, 'Entities specs', 'spec/entity'],
+  [:unshift, 'Utilities specs', 'spec/utils'],
+  [:unshift, 'Top-levels specs', 'spec',
+   %r{spec/pricehubble(_spec\.rb|/[^/]+\.rb$)}]
+].reverse
+
+vendors.each do |method, type, dir, pattern|
+  ::STATS_DIRECTORIES.send(method, [type, dir, pattern].compact)
+  ::CodeStatistics::TEST_TYPES << type if type.include? 'specs'
+end
+
+# Setup annotations
+ENV['SOURCE_ANNOTATION_DIRECTORIES'] = 'spec,doc'
+
+desc 'Enumerate all annotations'
+task :notes do
+  SourceAnnotationExtractor.enumerate '@?OPTIMIZE|@?FIXME|@?TODO', tag: true
+end

data/bin/console

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'price-hubble'
+require 'pp'
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require 'irb'
+IRB.start(__FILE__)

data/bin/run

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require 'bundler/setup'
+require 'price-hubble'
+require 'pp'
+
+$stdout.sync = true
+
+exit 1 if ARGV.empty?
+
+ARGV.each { |cmd| eval(cmd); $stdout.flush }

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/config/docker/.bash_profile

@@ -0,0 +1,3 @@
+if [ -f ~/.bashrc ]; then
+  . ~/.bashrc
+fi

data/config/docker/.bashrc

@@ -0,0 +1,48 @@
+# ~/.bashrc: executed by bash(1) for non-login shells.
+# see /usr/share/doc/bash/examples/startup-files (in the package bash-doc)
+# for examples
+
+_GEM_PATHS=$(ls -d1 ${HOME}/.gem/ruby/*/bin 2>/dev/null | paste -sd ':')
+_APP_PATHS=$(ls -d1 /app/vendor/bundle/ruby/*/bin 2>/dev/null | paste -sd ':')
+
+export PATH="${_GEM_PATHS}:${_APP_PATHS}:${PATH}"
+export PATH="/app/node_modules/.bin:${HOME}/.bin:/app/bin:${PATH}"
+export MAKE_ENV=baremetal
+
+# Disable the autostart of all supervisord units
+sudo sed -i 's/autostart=.*/autostart=false/g' /etc/supervisor/conf.d/*
+
+# Start the supervisord (empty, no units)
+sudo supervisord >/dev/null 2>&1 &
+
+# Wait for supervisord
+while ! supervisorctl status >/dev/null 2>&1; do sleep 1; done
+
+# Boot the mDNS stack
+echo '# Start the mDNS stack'
+sudo supervisorctl start dbus avahi
+echo
+
+function watch-make-test()
+{
+  while [ 1 ]; do
+    inotifywait --quiet -r `pwd` -e close_write --format '%e -> %w%f'
+    make test
+  done
+}
+
+function watch-make()
+{
+  while [ 1 ]; do
+    inotifywait --quiet -r `pwd` -e close_write --format '%e -> %w%f'
+    make $@
+  done
+}
+
+function watch-run()
+{
+  while [ 1 ]; do
+    inotifywait --quiet -r `pwd` -e close_write --format '%e -> %w%f'
+    bash -c "$@"
+  done
+}

data/config/docker/.inputrc

@@ -0,0 +1,17 @@
+# mappings for Ctrl-left-arrow and Ctrl-right-arrow for word moving
+"\e[1;5C": forward-word
+"\e[1;5D": backward-word
+"\e[5C": forward-word
+"\e[5D": backward-word
+"\e\e[C": forward-word
+"\e\e[D": backward-word
+
+# handle common Home/End escape codes
+"\e[1~": beginning-of-line
+"\e[4~": end-of-line
+"\e[7~": beginning-of-line
+"\e[8~": end-of-line
+"\eOH": beginning-of-line
+"\eOF": end-of-line
+"\e[H": beginning-of-line
+"\e[F": end-of-line

data/doc/assets/project.svg

@@ -0,0 +1,68 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<svg
+   xmlns:dc="http://purl.org/dc/elements/1.1/"
+   xmlns:cc="http://creativecommons.org/ns#"
+   xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
+   xmlns:svg="http://www.w3.org/2000/svg"
+   xmlns="http://www.w3.org/2000/svg"
+   version="1.1"
+   id="Ebene_1"
+   x="0px"
+   y="0px"
+   viewBox="0 0 800 200"
+   xml:space="preserve"
+   width="800"
+   height="200"><metadata
+   id="metadata33"><rdf:RDF><cc:Work
+       rdf:about=""><dc:format>image/svg+xml</dc:format><dc:type
+         rdf:resource="http://purl.org/dc/dcmitype/StillImage" /><dc:title></dc:title></cc:Work></rdf:RDF></metadata><defs
+   id="defs31" />
+<style
+   type="text/css"
+   id="style2">
+    .st0{fill-rule:evenodd;clip-rule:evenodd;fill:#E73E11;}
+    .st1{fill-rule:evenodd;clip-rule:evenodd;fill:#0371B9;}
+    .st2{fill:#132E48;}
+    .st3{font-family:'OpenSans-Bold';}
+    .st4{font-size:29.5168px;}
+    .st5{fill-rule:evenodd;clip-rule:evenodd;fill:none;}
+    .st6{opacity:0.5;fill:#132E48;}
+    .st7{font-family:'OpenSans';}
+    .st8{font-size:12px;}
+</style>
+<g
+   transform="translate(0,1.53584)"
+   id="g828"><g
+   transform="translate(35.93985,35.66416)"
+   id="g8">
+    <path
+   style="clip-rule:evenodd;fill:#e73e11;fill-rule:evenodd"
+   id="path4"
+   d="m -0.1,124.4 c 0,0 33.7,-123.2 66.7,-123.2 12.8,0 26.9,21.9 38.8,47.2 -23.6,27.9 -66.6,59.7 -94,76 -7.1,0 -11.5,0 -11.5,0 z"
+   class="st0" />
+    <path
+   style="clip-rule:evenodd;fill:#0371b9;fill-rule:evenodd"
+   id="path6"
+   d="m 88.1,101.8 c 13.5,-10.4 18.4,-16.2 27.1,-25.4 10,25.7 16.7,48 16.7,48 0,0 -41.4,0 -78,0 14.6,-7.9 18.7,-10.7 34.2,-22.6 z"
+   class="st1" />
+</g><text
+   y="106.40316"
+   x="192.43155"
+   style="font-style:normal;font-variant:normal;font-weight:bold;font-stretch:normal;font-size:29.51733398px;font-family:'Open Sans', sans-serif;-inkscape-font-specification:'OpenSans-Bold, Bold';font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;text-align:start;writing-mode:lr-tb;text-anchor:start;fill:#132e48"
+   id="text10"
+   class="st2 st3 st4">PriceHubble</text>
+<rect
+   style="clip-rule:evenodd;fill:none;fill-rule:evenodd"
+   id="rect12"
+   height="24"
+   width="314.5"
+   class="st5"
+   y="118.06416"
+   x="194.23985" /><text
+   y="127.22146"
+   x="194.21715"
+   style="font-size:12px;font-family:'Open Sans', sans-serif;opacity:0.5;fill:#132e48;-inkscape-font-specification:'Open Sans, sans-serif, Normal';font-weight:normal;font-style:normal;font-stretch:normal;font-variant:normal;text-anchor:start;text-align:start;writing-mode:lr;font-variant-ligatures:normal;font-variant-caps:normal;font-variant-numeric:normal;font-feature-settings:normal;"
+   id="text14"
+   class="st6 st7 st8">Ruby client for the PriceHubble REST API</text>
+</g>
+</svg>

data/doc/examples/authentication.rb

@@ -0,0 +1,19 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative './config'
+
+# Fetch the authentication/identity for the first time, subsequent calls
+# to this method will return the cached authentication instance until it
+# is expired (or near expiration, 5 minutes leeway) then a new
+# authentication is fetched transparently
+pp PriceHubble.identity
+# => #<PriceHubble::Authentication access_token="...", ...>
+
+# Check the expiration state (transparently always unexpired)
+pp PriceHubble.identity.expired?
+# => false
+
+# Get the current authentication expiration date/time
+pp PriceHubble.identity.expires_at
+# => 2019-10-17 08:01:23 +0000