immoscout 1.3.1 → 1.4.0

data/lib/immoscout/api/request.rb

@@ -1,5 +1,8 @@
+# frozen_string_literal: true
+
 module Immoscout
   module Api
+    # An abstract HTTP/API request.
     module Request
       def get(path, payload = nil, multipart = nil)
         request(:get, path, payload, multipart)
@@ -17,19 +20,21 @@ module Immoscout
         request(:delete, path, payload, multipart)
       end
 
+      # rubocop:disable Metrics/MethodLength because of the header handling
       def request(method, path, payload = nil, multipart = nil)
         connection.send(method, path, multipart) do |request|
           if multipart
-            request.headers['Content-Type'] = "multipart/form-data"
+            request.headers['Content-Type'] = 'multipart/form-data'
           else
-            request.body                    = payload if payload
-            request.headers['Content-Type'] = "application/json;charset=UTF-8"
+            request.body = payload if payload
+            request.headers['Content-Type'] = 'application/json;charset=UTF-8'
           end
-          request.headers['Accept'] = "application/json"
+          request.headers['Accept'] = 'application/json'
           request.headers['User-Agent'] = \
-            "HausgoldImmoscout/#{Immoscout::VERSION}"
+            "RubyImmoscout/#{Immoscout::VERSION}"
         end
       end
+      # rubocop:enable Metrics/MethodLength
     end
   end
 end

data/lib/immoscout/configuration.rb

@@ -1,27 +1,33 @@
 # 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 }
 
-    config_accessor(:api_version) { "v1.0" }
+    config_accessor(:api_version) { 'v1.0' }
 
     config_accessor(:user_name) { 'me' }
 
     config_accessor(:api_url_live) do
-      "https://rest.immobilienscout24.de/" \
-      "restapi/api/offer/#{api_version}"
+      'https://rest.immobilienscout24.de/' \
+        "restapi/api/offer/#{api_version}"
     end
     config_accessor(:api_url_sandbox) do
-      "https://rest.sandbox-immobilienscout24.de/" \
-      "restapi/api/offer/#{api_version}"
+      'https://rest.sandbox-immobilienscout24.de/' \
+        "restapi/api/offer/#{api_version}"
     end
   end
 end

data/lib/immoscout/errors/failed.rb

@@ -1,5 +1,8 @@
+# frozen_string_literal: true
+
 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

@@ -1,9 +1,14 @@
+# frozen_string_literal: true
+
 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 attachments.
       module Attachment
         extend ActiveSupport::Concern
 
@@ -12,11 +17,14 @@ module Immoscout
 
           self.unpack_collection = proc do |hash|
             hash
-              .fetch("common.attachments")
+              .fetch('common.attachments')
               .first
-              .fetch("attachment")
+              .fetch('attachment')
           end
 
+          # rubocop:disable Metrics/AbcSize because this is the
+          #   bare minimum logic
+          # rubocop:disable Metrics/MethodLength dito
           def save
             attachable_id = attachable.try(:id) || attachable
             response = api.post(
@@ -33,17 +41,21 @@ module Immoscout
             self.id = id_from_response(response)
             self
           end
+          # rubocop:enable Metrics/AbcSize
+          # rubocop:enable Metrics/MethodLength
 
           def destroy
             attachable_id = attachable.try(:id) || attachable
             response = api.delete(
-              "user/#{api.user_name}/realestate/#{attachable_id}/attachment/#{id}",
+              "user/#{api.user_name}/" \
+              "realestate/#{attachable_id}/" \
+              "attachment/#{id}"
             )
             handle_response(response)
             self
           end
 
-          private
+          protected
 
           def file_extension
             File.extname(file_name)
@@ -61,11 +73,11 @@ module Immoscout
         class_methods do
           def content_type_from_extension(ext)
             {
-              ".jpg"  => "image/jpeg",
-              ".jpeg" => "image/jpeg",
-              ".gif"  => "image/gif",
-              ".png"  => "image/png",
-              ".pdf"  => "application/pdf"
+              '.jpg' => 'image/jpeg',
+              '.jpeg' => 'image/jpeg',
+              '.gif' => 'image/gif',
+              '.png' => 'image/png',
+              '.pdf' => 'application/pdf'
             }.fetch(ext)
           end
 
@@ -84,3 +96,4 @@ module Immoscout
     end
   end
 end
+# rubocop:enable Metrics/BlockLength

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

@@ -1,9 +1,12 @@
+# frozen_string_literal: true
+
 require 'json'
 require_relative '../concerns/modelable'
 
 module Immoscout
   module Models
     module Actions
+      # Actions to work with contacts.
       module Contact
         extend ActiveSupport::Concern
 
@@ -12,8 +15,8 @@ module Immoscout
 
           self.unpack_collection = proc do |hash|
             hash
-              .fetch("common.realtorContactDetailsList", {})
-              .fetch("realtorContactDetails", nil)
+              .fetch('common.realtorContactDetailsList', {})
+              .fetch('realtorContactDetails', nil)
           end
 
           def save
@@ -54,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)

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

@@ -1,9 +1,12 @@
+# frozen_string_literal: true
+
 require 'json'
 require_relative '../concerns/modelable'
 
 module Immoscout
   module Models
     module Actions
+      # Actions to publish a Real Estate.
       module Publish
         extend ActiveSupport::Concern
 
@@ -11,7 +14,7 @@ module Immoscout
           include Immoscout::Models::Concerns::Modelable
 
           def save
-            response = api.post("publish", as_json)
+            response = api.post('publish', as_json)
             handle_response(response)
             self
           end
@@ -24,9 +27,6 @@ module Immoscout
             self
           end
         end
-
-        class_methods do
-        end
       end
     end
   end

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

@@ -1,9 +1,14 @@
+# frozen_string_literal: true
+
 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 real estate objects.
       module RealEstate
         extend ActiveSupport::Concern
 
@@ -12,9 +17,9 @@ module Immoscout
 
           self.unpack_collection = proc do |hash|
             hash
-              .fetch("realestates.realEstates", {})
-              .fetch("realEstateList", {})
-              .fetch("realEstateElement", nil)
+              .fetch('realestates.realEstates', {})
+              .fetch('realEstateList', {})
+              .fetch('realEstateElement', nil)
           end
 
           def save
@@ -72,7 +77,7 @@ module Immoscout
             self
           end
 
-          private
+          protected
 
           def check_placement_type(type)
             raise ArgumentError, "Unknown placement type '#{type}'" unless %w[
@@ -101,14 +106,8 @@ module Immoscout
               .map { |object| new(object) }
               .select { |object| object.type =~ /#{name.demodulize}/i }
           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)
@@ -120,3 +119,4 @@ module Immoscout
     end
   end
 end
+# rubocop:enable Metrics/BlockLength

data/lib/immoscout/models/apartment_buy.rb

@@ -12,12 +12,15 @@ 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
       include Immoscout::Models::Actions::RealEstate
 
-      self.json_wrapper = "realestates.apartmentBuy"
+      self.json_wrapper = 'realestates.apartmentBuy'
 
       property :id, alias: :@id
       property :external_id

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
@@ -27,6 +28,7 @@ module Immoscout
             # puts "#{self.class.name} - missing property '#{key}'"
             next
           end
+
           set_property(property, key, value)
         end
       end

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

@@ -1,8 +1,12 @@
+# frozen_string_literal: true
+
 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
 
@@ -37,16 +41,17 @@ module Immoscout
 
           def handle_response(response)
             return response if response.success?
+
             raise Immoscout::Errors::Failed, response
           end
 
           def id_from_response(response)
             response
               .body
-              .fetch("common.messages")
+              .fetch('common.messages')
               .first
-              .fetch("message", {})
-              .fetch("id", nil)
+              .fetch('message', {})
+              .fetch('id', nil)
           end
         end
       end

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

@@ -1,6 +1,10 @@
+# frozen_string_literal: true
+
 module Immoscout
   module Models
     module Concerns
+      # Includes functionality to access and modify
+      # model attributes transparently.
       module Propertiable
         extend ActiveSupport::Concern
 
@@ -12,11 +16,12 @@ 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)
-              return super if !properties.keys.include?(match) || !coerce_klass
+              return super if !properties.key?(match) || !coerce_klass
+
               send("#{match}=", coerce_klass.new)
             else
               super
@@ -36,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

@@ -1,8 +1,13 @@
+# frozen_string_literal: true
+
 require 'json'
 
+# rubocop:disable Metrics/BlockLength because this is how an ActiveSupport
+#   concern looks like
 module Immoscout
   module Models
     module Concerns
+      # Includes functionality to serialize a Ruby model properly.
       module Renderable
         extend ActiveSupport::Concern
 
@@ -11,22 +16,28 @@ 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)
           end
 
+          # rubocop:disable Metrics/PerceivedComplexity because this is the
+          #   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
               readonly = value.fetch(:readonly, false)
               next if readonly.try(:call, self) || readonly == true
+
               # use :alias instead of key as json-key
               property = value.fetch(:alias, key)
               # use :default if present AND value is nil
@@ -42,6 +53,10 @@ module Immoscout
               memo
             end
           end
+          # 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 }
@@ -54,10 +69,8 @@ module Immoscout
               .deep_transform_keys { |key| key.camelize :lower }
           end
         end
-
-        class_methods do
-        end
       end
     end
   end
 end
+# rubocop:enable Metrics/BlockLength

data/lib/immoscout/models/contact.rb

@@ -7,12 +7,14 @@ 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
       include Immoscout::Models::Actions::Contact
 
-      self.json_wrapper = "common.realtorContactDetail"
+      self.json_wrapper = 'common.realtorContactDetail'
 
       property :id, alias: :@id
       property :email

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
@@ -13,7 +15,7 @@ module Immoscout
 
       attr_accessor :attachable, :file
 
-      self.json_wrapper = "common.attachment"
+      self.json_wrapper = 'common.attachment'
 
       property :id, alias: :@id
       property :type, alias: :'@xsi.type'

data/lib/immoscout/models/house_buy.rb

@@ -14,12 +14,15 @@ 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
       include Immoscout::Models::Actions::RealEstate
 
-      self.json_wrapper = "realestates.houseBuy"
+      self.json_wrapper = 'realestates.houseBuy'
 
       property :id, alias: :@id
       property :external_id

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