immoscout 1.3.2 → 1.4.0

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

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

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

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

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

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

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

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

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

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

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

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

@@ -8,9 +8,12 @@ require_relative 'url'
 module Immoscout
   module Models
     module Parts
+      # Shared URLs-related property definitions.
+      # See: https://bit.ly/3CSGnmN
       class Urls < Base
         include Immoscout::Models::Concerns::Renderable
         include Immoscout::Models::Concerns::Propertiable
+
         property :url, coerce: Immoscout::Models::Parts::Url, array: true
       end
     end

data/lib/immoscout/models/picture.rb

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

data/lib/immoscout/models/publish.rb

@@ -8,6 +8,8 @@ require_relative 'parts/publish_channel'
 
 module Immoscout
   module Models
+    # The Publish (object) of a Real Estate.
+    # See: https://bit.ly/3ZFoYYI
     class Publish < Base
       include Immoscout::Models::Concerns::Renderable
       include Immoscout::Models::Concerns::Propertiable

data/lib/immoscout/models.rb

@@ -2,7 +2,6 @@
 
 require_relative 'errors/failed'
 require_relative 'api/client'
-# renderable models
 require_relative 'models/house_buy'
 require_relative 'models/apartment_buy'
 require_relative 'models/contact'

data/lib/immoscout/version.rb

@@ -1,5 +1,23 @@
 # frozen_string_literal: true
 
+# The gem version details.
 module Immoscout
-  VERSION = '1.3.2'
+  # The version of the +immoscout+ gem
+  VERSION = '1.4.0'
+
+  class << self
+    # Returns the version of gem as a string.
+    #
+    # @return [String] the gem version as string
+    def version
+      VERSION
+    end
+
+    # Returns the version of the gem as a +Gem::Version+.
+    #
+    # @return [Gem::Version] the gem version as object
+    def gem_version
+      Gem::Version.new VERSION
+    end
+  end
 end

data/lib/immoscout.rb

@@ -8,6 +8,7 @@ require 'immoscout/version'
 require 'immoscout/configuration'
 require 'immoscout/models'
 
+# The top-namespace of the +immoscout+ gem.
 module Immoscout
   class << self
     attr_writer :configuration