immoscout 1.3.2 → 1.5.0

data/immoscout.gemspec

@@ -5,55 +5,56 @@ $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'immoscout/version'
 
 Gem::Specification.new do |spec|
-  spec.name          = 'immoscout'
-  spec.version       = Immoscout::VERSION
-  spec.authors       = ['Marcus Geissler']
-  spec.email         = ['marcus.geissler@hanseventures.com']
-
-  spec.summary       = 'Ruby client for the Immobilienscout24 REST API'
-  spec.homepage      = 'https://github.com/hausgold/immoscout'
-  spec.license       = 'MIT'
-
-  spec.required_ruby_version = '~> 2.5'
-
-  # Prevent pushing this gem to RubyGems.org.
-  # To allow pushes either set the 'allowed_push_host'
-  # to allow pushing to a single host or delete this
-  # section to allow pushing to any host.
-  if spec.respond_to?(:metadata)
-    spec.metadata['allowed_push_host'] = 'https://rubygems.org'
-  else
-    raise 'RubyGems 2.0 or newer is required to protect against ' \
-      'public gem pushes.'
-  end
+  spec.name = 'immoscout'
+  spec.version = Immoscout::VERSION
+  spec.authors = ['Marcus Geissler']
+  spec.email = ['marcus3006@gmail.com']
+
+  spec.license = 'MIT'
+  spec.summary = 'Ruby client for the Immobilienscout24 REST API'
+
+  base_uri = "https://github.com/hausgold/#{spec.name}"
+  spec.metadata = {
+    'homepage_uri' => base_uri,
+    'source_code_uri' => base_uri,
+    'changelog_uri' => "#{base_uri}/blob/master/CHANGELOG.md",
+    'bug_tracker_uri' => "#{base_uri}/issues",
+    'documentation_uri' => "https://www.rubydoc.info/gems/#{spec.name}"
+  }
 
   spec.files = `git ls-files -z`.split("\x0").reject do |f|
     f.match(%r{^(test|spec|features)/})
   end
-  spec.bindir        = 'exe'
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ['lib']
-  spec.add_dependency 'activesupport', '>= 5.2.0'
-  spec.add_dependency 'faraday', '~> 1.0'
-  spec.add_dependency 'faraday_middleware', '~> 1.0'
+
+  spec.required_ruby_version = '>= 2.5'
+
+  spec.add_dependency 'activesupport', '>= 5.2'
+  spec.add_dependency 'faraday', '~> 1.10'
+  spec.add_dependency 'faraday_middleware', '~> 1.2'
   spec.add_dependency 'simple_oauth', '>= 0.3'
 
-  spec.add_development_dependency 'appraisal'
-  spec.add_development_dependency 'bundler', '>= 1.16', '< 3'
-  spec.add_development_dependency 'factory_bot', '~> 4.11'
-  spec.add_development_dependency 'railties', '>= 4.2.0', '< 6.1'
-  spec.add_development_dependency 'rake', '~> 10.0'
-  spec.add_development_dependency 'rdoc', '~> 6.1'
-  spec.add_development_dependency 'redcarpet', '~> 3.4'
-  spec.add_development_dependency 'rspec', '~> 3.0'
-  spec.add_development_dependency 'rspec-json_expectations', '~> 1.4'
-  spec.add_development_dependency 'rubocop', '~> 0.63.1'
-  spec.add_development_dependency 'rubocop-rspec', '~> 1.31'
-  spec.add_development_dependency 'simplecov', '< 0.18'
-  spec.add_development_dependency 'terminal-table', '~> 1.8'
-  spec.add_development_dependency 'timecop', '~> 0.9.1'
-  spec.add_development_dependency 'vcr', '~> 3.0'
-  spec.add_development_dependency 'webmock', '~> 3.5'
-  spec.add_development_dependency 'yard', '~> 0.9.18'
-  spec.add_development_dependency 'yard-activesupport-concern', '~> 0.0.1'
+  spec.add_development_dependency 'appraisal', '~> 2.4'
+  spec.add_development_dependency 'bundler', '~> 2.3'
+  spec.add_development_dependency 'countless', '~> 1.1'
+  spec.add_development_dependency 'factory_bot', '~> 6.2'
+  spec.add_development_dependency 'guard-rspec', '~> 4.7'
+  spec.add_development_dependency 'railties', '>= 5.2'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'redcarpet', '~> 3.5'
+  spec.add_development_dependency 'rspec', '~> 3.12'
+  spec.add_development_dependency 'rspec-json_expectations', '~> 2.2'
+  spec.add_development_dependency 'rubocop', '~> 1.28'
+  spec.add_development_dependency 'rubocop-rails', '~> 2.14'
+  spec.add_development_dependency 'rubocop-rspec', '~> 2.10'
+  spec.add_development_dependency 'simplecov', '>= 0.22'
+  spec.add_development_dependency 'terminal-table', '~> 3.0'
+  spec.add_development_dependency 'timecop', '>= 0.9.6'
+  spec.add_development_dependency 'vcr', '~> 6.0'
+  spec.add_development_dependency 'webmock', '~> 3.18'
+  spec.add_development_dependency 'yard', '>= 0.9.28'
+  spec.add_development_dependency 'yard-activesupport-concern', '>= 0.0.1'
 end

data/lib/immoscout/api/client.rb

@@ -6,6 +6,7 @@ require_relative 'request'
 
 module Immoscout
   module Api
+    # The immoscout API client object.
     class Client
       include Singleton
       include Immoscout::Api::Connection

data/lib/immoscout/api/connection.rb

@@ -5,22 +5,21 @@ require 'faraday_middleware'
 
 module Immoscout
   module Api
+    # A connection builder/handler for reusable connections.
     module Connection
-      # :reek:FeatureEnvy
       def connection
         @connection ||= Faraday::Connection.new(url: url) do |builder|
           configure_oauth(builder)
-          builder.request   :multipart
-          builder.request   :url_encoded
-          builder.request   :json
-          builder.response  :follow_redirects
-          builder.response  :json, content_type: /\bjson$/
-          builder.adapter   :net_http
+          builder.request :multipart
+          builder.request :url_encoded
+          builder.request :json
+          builder.response :follow_redirects
+          builder.response :json, content_type: /\bjson$/
+          builder.adapter :net_http
         end
-        @connection
       end
 
-      private
+      protected
 
       def configure_oauth(builder)
         builder.request(

data/lib/immoscout/api/request.rb

@@ -2,6 +2,7 @@
 
 module Immoscout
   module Api
+    # An abstract HTTP/API request.
     module Request
       def get(path, payload = nil, multipart = nil)
         request(:get, path, payload, multipart)
@@ -25,12 +26,12 @@ module Immoscout
           if multipart
             request.headers['Content-Type'] = 'multipart/form-data'
           else
-            request.body                    = payload if payload
+            request.body = payload if payload
             request.headers['Content-Type'] = 'application/json;charset=UTF-8'
           end
           request.headers['Accept'] = 'application/json'
           request.headers['User-Agent'] = \
-            "HausgoldImmoscout/#{Immoscout::VERSION}"
+            "RubyImmoscout/#{Immoscout::VERSION}"
         end
       end
       # rubocop:enable Metrics/MethodLength

data/lib/immoscout/configuration.rb

@@ -1,13 +1,19 @@
 # frozen_string_literal: true
 
 module Immoscout
+  # The configuration object of the +immoscout+ gem.
   class Configuration
     include ActiveSupport::Configurable
-    config_accessor(:consumer_key) { ENV['IMMOSCOUT_CONSUMER_KEY'] }
-    config_accessor(:consumer_secret) { ENV['IMMOSCOUT_CONSUMER_SECRET'] }
 
-    config_accessor(:oauth_token) { ENV['IMMOSCOUT_OAUTH_TOKEN'] }
-    config_accessor(:oauth_token_secret) { ENV['IMMOSCOUT_OAUTH_TOKEN_SECRET'] }
+    config_accessor(:consumer_key) { ENV.fetch('IMMOSCOUT_CONSUMER_KEY', nil) }
+    config_accessor(:consumer_secret) do
+      ENV.fetch('IMMOSCOUT_CONSUMER_SECRET', nil)
+    end
+
+    config_accessor(:oauth_token) { ENV.fetch('IMMOSCOUT_OAUTH_TOKEN', nil) }
+    config_accessor(:oauth_token_secret) do
+      ENV.fetch('IMMOSCOUT_OAUTH_TOKEN_SECRET', nil)
+    end
 
     config_accessor(:use_sandbox) { false }
 
@@ -17,11 +23,11 @@ module Immoscout
 
     config_accessor(:api_url_live) do
       'https://rest.immobilienscout24.de/' \
-      "restapi/api/offer/#{api_version}"
+        "restapi/api/offer/#{api_version}"
     end
     config_accessor(:api_url_sandbox) do
       'https://rest.sandbox-immobilienscout24.de/' \
-      "restapi/api/offer/#{api_version}"
+        "restapi/api/offer/#{api_version}"
     end
   end
 end

data/lib/immoscout/errors/failed.rb

@@ -2,6 +2,7 @@
 
 module Immoscout
   module Errors
+    # Representation of a failed API request/response.
     class Failed < StandardError
       def initialize(response)
         @status = response.status

data/lib/immoscout/models/actions/attachment.rb

@@ -8,6 +8,7 @@ require_relative '../concerns/modelable'
 module Immoscout
   module Models
     module Actions
+      # Actions to work with attachments.
       module Attachment
         extend ActiveSupport::Concern
 
@@ -54,7 +55,7 @@ module Immoscout
             self
           end
 
-          private
+          protected
 
           def file_extension
             File.extname(file_name)
@@ -80,7 +81,6 @@ module Immoscout
             }.fetch(ext)
           end
 
-          # rubocop:disable Metrics/AbcSize because of the mapping logic
           def all(real_estate_id)
             response = api.get(
               "user/#{api.user_name}/realestate/#{real_estate_id}/attachment"
@@ -91,7 +91,6 @@ module Immoscout
               .map { |object| new(object) }
               .select { |object| object.type =~ /#{name.demodulize}/i }
           end
-          # rubocop:enable Metrics/AbcSize
         end
       end
     end

data/lib/immoscout/models/actions/contact.rb

@@ -3,11 +3,10 @@
 require 'json'
 require_relative '../concerns/modelable'
 
-# rubocop:disable Metrics/BlockLength because this is how an ActiveSupport
-#   concern looks like
 module Immoscout
   module Models
     module Actions
+      # Actions to work with contacts.
       module Contact
         extend ActiveSupport::Concern
 
@@ -20,8 +19,6 @@ module Immoscout
               .fetch('realtorContactDetails', nil)
           end
 
-          # rubocop:disable Metrics/AbcSize because this is the
-          #   bare minimum logic
           def save
             response = \
               if id
@@ -34,7 +31,6 @@ module Immoscout
             self.id = id_from_response(response) unless id
             self
           end
-          # rubocop:enable Metrics/AbcSize
 
           def destroy
             response = api.delete("user/#{api.user_name}/contact/#{id}")
@@ -61,14 +57,8 @@ module Immoscout
             objects = unpack_collection.call(response.body)
             objects.map { |object| new(object) }
           end
-
-          def first
-            all.first
-          end
-
-          def last
-            all.last
-          end
+          delegate :first, to: :all
+          delegate :last, to: :all
 
           def create(hash)
             instance = new(hash)
@@ -80,4 +70,3 @@ module Immoscout
     end
   end
 end
-# rubocop:enable Metrics/BlockLength

data/lib/immoscout/models/actions/publish.rb

@@ -6,6 +6,7 @@ require_relative '../concerns/modelable'
 module Immoscout
   module Models
     module Actions
+      # Actions to publish a Real Estate.
       module Publish
         extend ActiveSupport::Concern
 
@@ -26,9 +27,6 @@ module Immoscout
             self
           end
         end
-
-        class_methods do
-        end
       end
     end
   end

data/lib/immoscout/models/actions/real_estate.rb

@@ -8,6 +8,7 @@ require_relative '../concerns/modelable'
 module Immoscout
   module Models
     module Actions
+      # Actions to work with real estate objects.
       module RealEstate
         extend ActiveSupport::Concern
 
@@ -21,8 +22,6 @@ module Immoscout
               .fetch('realEstateElement', nil)
           end
 
-          # rubocop:disable Metrics/AbcSize because this is the
-          #   bare minimum logic
           def save
             response = \
               if id
@@ -35,7 +34,6 @@ module Immoscout
             self.id = id_from_response(response) unless id
             self
           end
-          # rubocop:enable Metrics/AbcSize
 
           def destroy
             response = api.delete("user/#{api.user_name}/realestate/#{id}")
@@ -79,7 +77,7 @@ module Immoscout
             self
           end
 
-          private
+          protected
 
           def check_placement_type(type)
             raise ArgumentError, "Unknown placement type '#{type}'" unless %w[
@@ -100,7 +98,6 @@ module Immoscout
             find("ext-#{external_id}")
           end
 
-          # rubocop:disable Metrics/AbcSize because of the mapping logic
           def all
             response = api.get("user/#{api.user_name}/realestate")
             handle_response(response)
@@ -109,15 +106,8 @@ module Immoscout
               .map { |object| new(object) }
               .select { |object| object.type =~ /#{name.demodulize}/i }
           end
-          # rubocop:enable Metrics/AbcSize
-
-          def first
-            all.first
-          end
-
-          def last
-            all.last
-          end
+          delegate :first, to: :all
+          delegate :last, to: :all
 
           def create(hash)
             instance = new(hash)

data/lib/immoscout/models/apartment_buy.rb

@@ -12,6 +12,9 @@ require_relative 'parts/energy_source'
 
 module Immoscout
   module Models
+    # Real Estate. (selling an apartment)
+    # See: https://bit.ly/3iH3DNL
+    # See: https://bit.ly/3H7mQkY
     class ApartmentBuy < Base
       include Immoscout::Models::Concerns::Renderable
       include Immoscout::Models::Concerns::Propertiable

data/lib/immoscout/models/base.rb

@@ -2,6 +2,7 @@
 
 module Immoscout
   module Models
+    # The base/abstract model.
     class Base
       attr_reader :base
 
@@ -10,7 +11,7 @@ module Immoscout
         set_properties
       end
 
-      private
+      protected
 
       def prepared_hash
         base

data/lib/immoscout/models/concerns/modelable.rb

@@ -5,6 +5,8 @@ require 'json'
 module Immoscout
   module Models
     module Concerns
+      # Provides base functionality to reference/map/(de)serialize
+      # models against the immoscout API.
       module Modelable
         extend ActiveSupport::Concern
 

data/lib/immoscout/models/concerns/propertiable.rb

@@ -3,6 +3,8 @@
 module Immoscout
   module Models
     module Concerns
+      # Includes functionality to access and modify
+      # model attributes transparently.
       module Propertiable
         extend ActiveSupport::Concern
 
@@ -14,7 +16,7 @@ module Immoscout
           # :reek:ControlParameter - standard stuff, reek!
           # :reek:TooManyStatements
           def method_missing(method_name, *arguments, &block)
-            if method_name =~ /build\_(\w+)/
+            if method_name =~ /build_(\w+)/
               match         = Regexp.last_match(1).intern
               properties    = self.class.properties
               coerce_klass  = properties.fetch(match).fetch(:coerce, nil)
@@ -39,6 +41,7 @@ module Immoscout
         class_methods do
           def property(name, **opts)
             attr_accessor(name)
+
             alias_name = opts.fetch(:alias, false)
             if alias_name
               alias_method alias_name, name

data/lib/immoscout/models/concerns/renderable.rb

@@ -7,6 +7,7 @@ require 'json'
 module Immoscout
   module Models
     module Concerns
+      # Includes functionality to serialize a Ruby model properly.
       module Renderable
         extend ActiveSupport::Concern
 
@@ -15,12 +16,12 @@ module Immoscout
             wrapped? ? to_json_wrapped : to_json_unwrapped
           end
 
-          def to_json
+          def to_json(*)
             as_json.to_json
           end
           alias_method :to_s, :to_json
 
-          private
+          protected
 
           def wrapped?
             self.class.try(:json_wrapper)
@@ -30,6 +31,7 @@ module Immoscout
           #   bare minimum logic
           # rubocop:disable Metrics/MethodLength dito
           # rubocop:disable Metrics/CyclomaticComplexity dito
+          # rubocop:disable Metrics/AbcSize dito
           def to_h
             self.class.properties.each_with_object({}) do |(key, value), memo|
               # skip if it's readonly and should not be exposed in #as_json
@@ -54,6 +56,7 @@ module Immoscout
           # rubocop:enable Metrics/PerceivedComplexity
           # rubocop:enable Metrics/MethodLength
           # rubocop:enable Metrics/CyclomaticComplexity
+          # rubocop:enable Metrics/AbcSize
 
           def to_json_wrapped
             { self.class.try(:json_wrapper) => to_json_unwrapped }
@@ -66,9 +69,6 @@ module Immoscout
               .deep_transform_keys { |key| key.camelize :lower }
           end
         end
-
-        class_methods do
-        end
       end
     end
   end

data/lib/immoscout/models/contact.rb

@@ -7,6 +7,8 @@ require_relative 'parts/address'
 
 module Immoscout
   module Models
+    # A contact.
+    # See: https://bit.ly/3WcYquD
     class Contact < Base
       include Immoscout::Models::Concerns::Renderable
       include Immoscout::Models::Concerns::Propertiable

data/lib/immoscout/models/document.rb

@@ -6,6 +6,8 @@ require_relative 'actions/attachment'
 
 module Immoscout
   module Models
+    # Attachment (document) of a Real Estate.
+    # See: https://bit.ly/3Xx32gj
     class Document < Base
       include Immoscout::Models::Concerns::Renderable
       include Immoscout::Models::Concerns::Propertiable

data/lib/immoscout/models/house_buy.rb

@@ -14,6 +14,9 @@ require_relative 'parts/firing_type'
 
 module Immoscout
   module Models
+    # Real Estate. (selling a house)
+    # See: https://bit.ly/3iH3DNL
+    # See: https://bit.ly/3CSGnmN
     class HouseBuy < Base
       include Immoscout::Models::Concerns::Renderable
       include Immoscout::Models::Concerns::Propertiable

data/lib/immoscout/models/parts/address.rb

@@ -10,9 +10,12 @@ require_relative '../concerns/renderable'
 module Immoscout
   module Models
     module Parts
+      # Shared address-related property definitions.
+      # See: https://bit.ly/3CSGnmN
       class Address < Base
         include Immoscout::Models::Concerns::Renderable
         include Immoscout::Models::Concerns::Propertiable
+
         property :street
         property :house_number
         property :postcode

data/lib/immoscout/models/parts/api_search_data.rb

@@ -7,9 +7,12 @@ require_relative '../concerns/renderable'
 module Immoscout
   module Models
     module Parts
+      # Shared search-related property definitions.
+      # See: https://bit.ly/3CSGnmN
       class ApiSearchData < Base
         include Immoscout::Models::Concerns::Renderable
         include Immoscout::Models::Concerns::Propertiable
+
         property :search_field1
         property :search_field2
         property :search_field3

data/lib/immoscout/models/parts/contact.rb

@@ -7,9 +7,12 @@ require_relative '../concerns/renderable'
 module Immoscout
   module Models
     module Parts
+      # Shared contact-related property definitions.
+      # See: https://bit.ly/3CSGnmN
       class Contact < Base
         include Immoscout::Models::Concerns::Renderable
         include Immoscout::Models::Concerns::Propertiable
+
         property :id, alias: :@id
         property :external_id, alias: :@external_id
       end

data/lib/immoscout/models/parts/coordinate.rb

@@ -7,9 +7,12 @@ require_relative '../concerns/renderable'
 module Immoscout
   module Models
     module Parts
+      # Shared coordinates-related property definitions.
+      # See: https://bit.ly/3CSGnmN
       class Coordinate < Base
         include Immoscout::Models::Concerns::Renderable
         include Immoscout::Models::Concerns::Propertiable
+
         property :latitude
         property :longitude
       end

data/lib/immoscout/models/parts/courtage.rb

@@ -7,9 +7,12 @@ require_relative '../concerns/renderable'
 module Immoscout
   module Models
     module Parts
+      # Shared courtage-related property definitions.
+      # See: https://bit.ly/3CSGnmN
       class Courtage < Base
         include Immoscout::Models::Concerns::Renderable
         include Immoscout::Models::Concerns::Propertiable
+
         property :has_courtage
         property :courtage
         property :courtage_note

data/lib/immoscout/models/parts/energy_certificate.rb

@@ -7,9 +7,12 @@ require_relative '../concerns/renderable'
 module Immoscout
   module Models
     module Parts
+      # Shared energy-certificate-related property definitions.
+      # See: https://bit.ly/3CSGnmN
       class EnergyCertificate < Base
         include Immoscout::Models::Concerns::Renderable
         include Immoscout::Models::Concerns::Propertiable
+
         property :energy_certificate_availability
         property :energy_certificate_creation_date
         property :energy_efficiency_class

data/lib/immoscout/models/parts/energy_source.rb

@@ -7,9 +7,12 @@ require_relative '../concerns/renderable'
 module Immoscout
   module Models
     module Parts
+      # Shared energy-source-related property definitions.
+      # See: https://bit.ly/3CSGnmN
       class EnergySource < Base
         include Immoscout::Models::Concerns::Renderable
         include Immoscout::Models::Concerns::Propertiable
+
         property :energy_source_enev2014
       end
     end

data/lib/immoscout/models/parts/firing_type.rb

@@ -7,9 +7,12 @@ require_relative '../concerns/renderable'
 module Immoscout
   module Models
     module Parts
+      # Shared firing-type-related property definitions.
+      # See: https://bit.ly/3CSGnmN
       class FiringType < Base
         include Immoscout::Models::Concerns::Renderable
         include Immoscout::Models::Concerns::Propertiable
+
         property :firing_type
       end
     end

data/lib/immoscout/models/parts/geo_code.rb

@@ -7,9 +7,12 @@ require_relative '../concerns/renderable'
 module Immoscout
   module Models
     module Parts
+      # Shared geo-coding-related property definitions.
+      # See: https://bit.ly/3CSGnmN
       class GeoCode < Base
         include Immoscout::Models::Concerns::Renderable
         include Immoscout::Models::Concerns::Propertiable
+
         property :geo_code_id
         property :full_geo_code_id
       end

data/lib/immoscout/models/parts/geo_hierarchy.rb

@@ -8,9 +8,12 @@ require_relative 'geo_code'
 module Immoscout
   module Models
     module Parts
+      # Shared geo-hierarchy-related property definitions.
+      # See: https://bit.ly/3CSGnmN
       class GeoHierarchy < Base
         include Immoscout::Models::Concerns::Renderable
         include Immoscout::Models::Concerns::Propertiable
+
         property :continent, coerce: Immoscout::Models::Parts::GeoCode
         property :country, coerce: Immoscout::Models::Parts::GeoCode
         property :region, coerce: Immoscout::Models::Parts::GeoCode