pricehubble 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 88b0e4aa5870b598e3ee8746eadbbe89ad9467f232573bd50c2380053cc0f8b8
-  data.tar.gz: 8b2906d87ffef7e4eae172f521b792787a0071c018de6eb2090ab4623cb2e78f
+  metadata.gz: 9288520abf1c7458b0963010c2ad43859d866ec986008aceb8a070a7dd24c91c
+  data.tar.gz: a09346c0774d4dff01634ec7229543993192ed265a2d5fd73313fffc959df61f
 SHA512:
-  metadata.gz: '039e27591727c291f4c11644c1b18ea6c8017a5f6313154a6c2c89dcb3883304148c50c37934079a50bf2c5192706907f0b6ad966d21a9eb84a817c24741017f'
-  data.tar.gz: 991dfca00b532685474147a2d3c3d325560bd18699646e7dedbbd3678135908ba2821014032ba8c0c54b1e854c562053ed2ab39373e91b80e559136bf47eac99
+  metadata.gz: d267670a719b5a34cb21be278f91f36a9662651856db82991cc6d7c396aef57e7e9191ab0bffa93f75e67c281692dfd09c9c5bf9489bbfab921b412e561733ae
+  data.tar.gz: 2b836e045349d8e55d43f9ba8999b27e8ae63a9e27aaf18fc5c444936230f8f9279720593770cb03a95f2c50269f154fad88e12b7e192c31ae81d0da889cac8f

data/CHANGELOG.md

@@ -1,8 +1,12 @@
+### 0.4.0
+
+* Added initial dossier handling (create, delete, sharing link) (#3)
+
 ### 0.3.0
 
-* Dropped support for Rails <5.2
-* Dropped support for Ruby <2.5
-* Updated the faraday gem spec to `~> 1.0` (#)
+* Dropped support for Rails <5.2 (#2)
+* Dropped support for Ruby <2.5 (#2)
+* Updated the faraday gem spec to `~> 1.0` (#2)
 
 ### 0.2.0
 

data/README.md

@@ -25,6 +25,7 @@ so feel free to send a pull request.
     - [Use the PriceHubble::Valuation representation](#use-the-pricehubblevaluation-representation)
     - [Error Handling](#error-handling-1)
     - [Advanced Request Examples](#advanced-request-examples)
+  - [Dossiers](#dossiers)
 - [Development](#development)
 - [Contributing](#contributing)
 
@@ -370,6 +371,56 @@ end
 # => +-----------+---------------+-------------+-------------+-------------+
 ```
 
+### Dossiers
+
+The pricehubble gem allows you to create and delete dossiers for properties.
+The required property data is equal to the valuation request. Additionally the
+pricehubble gem allows you to create sharing links (permalinks) which will link
+to the dossier dashboard application for customers.
+
+**Gotcha!** The API allows to update and search for dossiers. Additionally the
+API supports images and logos for dossiers. The pricehubble gem does not
+support this yet.
+
+```ruby
+# The property to create a dossier for
+apartment = {
+  location: {
+    address: {
+      post_code: '22769',
+      city: 'Hamburg',
+      street: 'Stresemannstr.',
+      house_number: '29'
+    }
+  },
+  property_type: { code: :apartment },
+  building_year: 1990,
+  living_area: 200
+}
+
+dossier = PriceHubble::Dossier.new(
+  title: 'Customer Dossier for Stresemannstr. 29',
+  description: 'Best apartment in the city',
+  deal_type: :sale,
+  property: apartment,
+  country_code: 'DE',
+  asking_sale_price: 600_000 # the minimum price the seller is willing to agree
+  # valuation_override_sale_price: '', # overwrite the PH value
+  # valuation_override_rent_net: '', # overwrite the PH value
+  # valuation_override_rent_gross: '', # overwrite the PH value
+  # valuation_override_reason_freetext: '' # explain the visitor why
+)
+
+# Save the new dossier
+pp dossier.save!
+pp dossier.id
+# => "25de5429-244e-4584-b58e-b0d7428a2377"
+
+# Generate a sharing link for the dossier
+pp dossier.link
+# => "https://dash.pricehubble.com/shared/dossier/eyJ0eXAiOiJ..."
+```
+
 ## Development
 
 After checking out the repo, run `bin/setup` to install dependencies. Then, run

data/doc/examples/dossiers.rb

@@ -0,0 +1,41 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative './config'
+
+# The property to create a dossier for
+apartment = {
+  location: {
+    address: {
+      post_code: '22769',
+      city: 'Hamburg',
+      street: 'Stresemannstr.',
+      house_number: '29'
+    }
+  },
+  property_type: { code: :apartment },
+  building_year: 1990,
+  living_area: 200
+}
+
+dossier = PriceHubble::Dossier.new(
+  title: 'Customer Dossier for Stresemannstr. 29',
+  description: 'Best apartment in the city',
+  deal_type: :sale,
+  property: apartment,
+  country_code: 'DE',
+  asking_sale_price: 600_000 # the minimum price the seller is willing to agree
+  # valuation_override_sale_price: '', # overwrite the PH value
+  # valuation_override_rent_net: '', # overwrite the PH value
+  # valuation_override_rent_gross: '', # overwrite the PH value
+  # valuation_override_reason_freetext: '' # explain the visitor why
+)
+
+# Save the new dossier
+pp dossier.save!
+pp dossier.id
+# => "25de5429-244e-4584-b58e-b0d7428a2377"
+
+# Generate a sharing link for the dossier
+pp dossier.link
+# => "https://dash.pricehubble.com/shared/dossier/eyJ0eXAiOiJ..."

data/lib/pricehubble.rb

@@ -40,6 +40,7 @@ module PriceHubble
   autoload :Location, 'pricehubble/entity/location'
   autoload :Address, 'pricehubble/entity/address'
   autoload :Coordinates, 'pricehubble/entity/coordinates'
+  autoload :Dossier, 'pricehubble/entity/dossier'
 
   # Some general purpose utilities
   module Utils
@@ -77,6 +78,7 @@ module PriceHubble
     autoload :Base, 'pricehubble/client/base'
     autoload :Authentication, 'pricehubble/client/authentication'
     autoload :Valuation, 'pricehubble/client/valuation'
+    autoload :Dossiers, 'pricehubble/client/dossiers'
   end
 
   # Separated features of an entity instance
@@ -85,6 +87,7 @@ module PriceHubble
     autoload :Attributes, 'pricehubble/entity/concern/attributes'
     autoload :Associations, 'pricehubble/entity/concern/associations'
     autoload :Client, 'pricehubble/entity/concern/client'
+    autoload :Persistence, 'pricehubble/entity/concern/persistence'
 
     # Some custom typed attribute helpers
     module Attributes

data/lib/pricehubble/client/dossiers.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  module Client
+    # A high level client library for the PriceHubble Dossiers API.
+    class Dossiers < Base
+      # Create a new dossier.
+      #
+      # @param entity [PriceHubble::Dossier] the entity to use
+      # @param args [Hash{Symbol => Mixed}] additional arguments
+      # @return [PriceHubble::Dossier, nil] the PriceHubble dossier,
+      #   or +nil+ on error
+      #
+      # rubocop:disable Metrics/MethodLength because thats the bare minimum
+      #  handling is quite complex
+      def create_dossier(entity, **args)
+        res = connection.post do |req|
+          req.path = '/api/v1/dossiers'
+          req.body = entity.attributes.compact
+          use_default_context(req, :create_dossier)
+          use_authentication(req)
+        end
+        decision(bang: args.fetch(:bang, false)) do |result|
+          result.bang(&bang_entity(entity, res, {}))
+          result.good(&assign_entity(entity, res))
+          successful?(res)
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      # Generates a permalink for the specified dossier which will expire after
+      # the set number of days.
+      #
+      # @param entity [PriceHubble::Dossier] the entity to use
+      # @param ttl [ActiveSupport::Duration] the time to live for the new link
+      # @param locale [String] the user frontend locale
+      # @param args [Hash{Symbol => Mixed}] additional arguments
+      #
+      # rubocop:disable Metrics/MethodLength because thats the bare minimum
+      # rubocop:disable Metrics/AbcSize because the decission
+      #  handling is quite complex
+      def share_dossier(entity, ttl:, locale:, **args)
+        res = connection.post do |req|
+          req.path = '/api/v1/dossiers/links'
+          req.body = {
+            dossier_id: entity.id,
+            days_to_live: ttl.fdiv(1.day.to_i).ceil,
+            country_code: entity.country_code,
+            locale: locale
+          }
+          use_default_context(req, :share_dossier)
+          use_authentication(req)
+        end
+        decision(bang: args.fetch(:bang, false)) do |result|
+          result.bang(&bang_entity(entity, res, id: entity.try(:id)))
+          result.good { res.body.url }
+          successful?(res)
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+      # rubocop:enable Metrics/AbcSize
+
+      # Delete a dossier entity.
+      #
+      # @param entity [PriceHubble::Dossier] the entity to delete
+      # @param args [Hash{Symbol => Mixed}] additional arguments
+      #
+      # rubocop:disable Metrics/MethodLength because thats the bare minimum
+      # rubocop:disable Metrics/AbcSize because the decission
+      #  handling is quite complex
+      def delete_dossier(entity, **args)
+        res = connection.delete do |req|
+          req.path = "/api/v1/dossiers/#{entity.id}"
+          use_default_context(req, :delete_dossier)
+          use_authentication(req)
+        end
+        decision(bang: args.fetch(:bang, false)) do |result|
+          result.bang(&bang_entity(entity, res, id: entity.id))
+          result.good(&assign_entity(entity, res) do |assigned_entity|
+            assigned_entity.mark_as_destroyed.freeze
+          end)
+          successful?(res)
+        end
+      end
+      # rubocop:enable Metrics/MethodLength
+      # rubocop:enable Metrics/AbcSize
+
+      # Update a dossier entity.
+      #
+      # TODO: Implement this.
+      #
+      # @param entity [PriceHubble::Dossier] the entity to update
+      # @param args [Hash{Symbol => Mixed}] additional arguments
+      # @return [PriceHubble::Dossier, nil] the entity, or +nil+ on error
+      def update_dossier(*)
+        # PUT dossiers/<dossier_id>
+        raise NotImplementedError
+      end
+
+      # Search for dossier entities.
+      #
+      # TODO: Implement this.
+      #
+      # @param criteria [Mixed] the search criteria
+      # @param args [Hash{Symbol => Mixed}] additional arguments
+      # @return [Array<PriceHubble::Dossier>, nil] the entity,
+      #   or +nil+ on error
+      def search_dossiers(*)
+        # POST dossiers/search
+        raise NotImplementedError
+      end
+
+      # Generate bang method variants
+      bangers :create_dossier, :update_dossier, :delete_dossier,
+              :share_dossier, :search_dossiers
+    end
+  end
+end

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

@@ -18,7 +18,7 @@ module PriceHubble
 
             # By definition empty responses (HTTP status 204)
             # or actual empty bodies should be an empty hash
-            body = {} if res[:status] == 204 || res[:body].empty?
+            body = {} if res[:status] == 204 || res[:body].blank?
 
             # Looks like we have some actual data we can wrap
             res[:body] = \

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

@@ -4,6 +4,8 @@ module PriceHubble
   module Client
     module Utils
       # Some helpers to work with responses in a general way.
+      #
+      # rubocop:disable Metrics/BlockLength because of ActiveSupport::Concern
       module Response
         extend ActiveSupport::Concern
 
@@ -53,8 +55,33 @@ module PriceHubble
               PriceHubble::RequestError.new(nil, res)
             end
           end
+
+          # Perform the assignment of the response to the given entity. This
+          # allows a clean usage of the decision flow control for successful
+          # requests. Here comes an example:
+          #
+          #   decision do |result|
+          #     result.good(&assign_entity(entity, res))
+          #   end
+          #
+          # @param entity [Hausgold::BaseEntity] the entity instance to handle
+          # @param res [Faraday::Response] the response object
+          # @return [Proc] the proc which performs the entity handling
+          def assign_entity(entity, res, &block)
+            lambda do
+              entity.assign_attributes(res.body.to_h)
+              entity.send(:changes_applied)
+              # We need to call +#changed?+ - the +@mutations_from_database+ is
+              # unset and this causes issues on subsequent calls to +#changed?+
+              # after a freeze (eg. when deleted)
+              entity.changed?
+              yield(entity) if block
+              entity
+            end
+          end
         end
       end
+      # rubocop:enable Metrics/BlockLength
     end
   end
 end

data/lib/pricehubble/entity/base_entity.rb

@@ -17,6 +17,7 @@ module PriceHubble
     include PriceHubble::EntityConcern::Attributes
     include PriceHubble::EntityConcern::Associations
     include PriceHubble::EntityConcern::Client
+    include PriceHubble::EntityConcern::Persistence
 
     # We collect all unknown attributes instead of raising while creating a new
     # instance. The unknown attributes are wrapped inside a

data/lib/pricehubble/entity/concern/persistence.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  module EntityConcern
+    # Map some of the ActiveRecord::Persistence API methods for an entity
+    # instance for good compatibility. See: http://bit.ly/2W1rjfF and
+    # http://bit.ly/2ARRFYB
+    module Persistence
+      extend ActiveSupport::Concern
+
+      included do
+        # A simple method to query for the state of the entity instance.
+        # Returns +false+ whenever the entity or the changes of it were not yet
+        # persisted on the remote application. This is helpful for creating new
+        # entities from scratch or checking for persisted updates.
+        #
+        # @return [Boolean] whenever persisted or not
+        def persisted?
+          return (new_record? ? false : !changed?) \
+            if respond_to? :id
+
+          false
+        end
+
+        # A simple method to query for the state of the entity instance.
+        # Returns +false+ whenever the entity is not yet created on the remote
+        # application. This is helpful for creating new entities from scratch.
+        #
+        # @return [Boolean] whenever persisted or not
+        def new_record?
+          return id.nil? if respond_to? :id
+
+          true
+        end
+
+        # Mark the entity instance as destroyed.
+        #
+        # @return [Hausgold::BaseEntity] the instance itself for method chaining
+        def mark_as_destroyed
+          @destroyed = true
+          self
+        end
+
+        # Returns true if this object has been destroyed, otherwise returns
+        # false.
+        #
+        # @return [Boolean] whenever the entity was destroyed or not
+        def destroyed?
+          @destroyed == true
+        end
+      end
+    end
+  end
+end

data/lib/pricehubble/entity/dossier.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  # The PriceHubble dossier for a single property.
+  #
+  # @see https://docs.pricehubble.com/#international-dossier-creation
+  class Dossier < BaseEntity
+    # Configure the client to use
+    client :dossiers
+
+    # Mapped and tracked attributes
+    tracked_attr :id, :deal_type, :property, :country_code,
+                 :title, :description, :asking_sale_price,
+                 :valuation_override_sale_price, :valuation_override_rent_net,
+                 :valuation_override_rent_gross,
+                 :valuation_override_reason_freetext, :logo, :images
+
+    # Define attribute types for casting
+    typed_attr :deal_type, :enum, values: %i[sale rent]
+    typed_attr :country_code, :string_inquirer
+
+    # Associations
+    has_one :property, persist: true, initialize: true
+
+    # Set some defaults when initialized
+    after_initialize do
+      self.deal_type ||= :sale
+      self.country_code ||= 'DE'
+    end
+
+    # Save the dossier.
+    #
+    # @param args [Hash{Symbol => Mixed}] additional options
+    # @return [Boolean] the result state
+    def save(**args)
+      # When the current entity is already persisted, we send an update
+      if id.present?
+        # Skip making requests when the current entity is not dirty
+        return true unless changed?
+
+        # The current entity is dirty, so send an update request
+        return client.update_dossier(self, **args)
+      end
+
+      # Otherwise we send a new creation request
+      client.create_dossier(self, **args) && true
+    end
+
+    # Deletes the instance at the remote application and freezes this
+    # instance to reflect that no changes should be made (since they can't
+    # be persisted).
+    #
+    # @param args [Hash{Symbol => Mixed}] addition settings
+    # @return [PriceHubble::Dossier, false] whenever the deletion
+    #   was successful
+    def delete(**args)
+      client.delete_dossier(self, **args) || false
+    end
+    alias destroy delete
+
+    # Create a new dossier share link.
+    #
+    # @param ttl [ActiveSupport::Duration] the time to live for the new link
+    # @param locale [String] the user frontend locale
+    # @param args [Hash{Symbol => Mixed}] additional options
+    # @return [String] the new dossier frontend link
+    def link(ttl: 365.days, locale: 'de_CH', lang: 'de', **args)
+      # Make sure the current dossier is saved before we try to generate a link
+      return unless save(**args)
+
+      # Send a "share dossier" request to the service
+      url = client.share_dossier(self, ttl: ttl, locale: locale, **args)
+      url += "?lang=#{lang}" if url
+      url
+    end
+
+    # Generate bang method variants
+    bangers :save, :link, :delete, :destroy
+  end
+end

data/lib/pricehubble/version.rb

@@ -2,5 +2,5 @@
 
 module PriceHubble
   # The version of the +price-hubble+ gem
-  VERSION = '0.3.0'
+  VERSION = '0.4.0'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: pricehubble
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Hermann Mayer
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-09-09 00:00:00.000000000 Z
+date: 2020-12-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activemodel
@@ -357,6 +357,7 @@ files:
 - doc/examples/authentication.rb
 - doc/examples/complex_property_valuations.rb
 - doc/examples/config.rb
+- doc/examples/dossiers.rb
 - doc/examples/property_valuations_errors.rb
 - doc/examples/simple_property_valuations.rb
 - docker-compose.yml
@@ -367,6 +368,7 @@ files:
 - lib/pricehubble/client.rb
 - lib/pricehubble/client/authentication.rb
 - lib/pricehubble/client/base.rb
+- lib/pricehubble/client/dossiers.rb
 - lib/pricehubble/client/request/data_sanitization.rb
 - lib/pricehubble/client/request/default_headers.rb
 - lib/pricehubble/client/response/data_sanitization.rb
@@ -388,7 +390,9 @@ files:
 - lib/pricehubble/entity/concern/attributes/string_inquirer.rb
 - lib/pricehubble/entity/concern/callbacks.rb
 - lib/pricehubble/entity/concern/client.rb
+- lib/pricehubble/entity/concern/persistence.rb
 - lib/pricehubble/entity/coordinates.rb
+- lib/pricehubble/entity/dossier.rb
 - lib/pricehubble/entity/location.rb
 - lib/pricehubble/entity/property.rb
 - lib/pricehubble/entity/property_conditions.rb