pricehubble 0.1.0

data/lib/pricehubble/client.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  # A bunch of top-level client helpers.
+  module Client
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Get a low level client for the requested application. This returns an
+      # already instanciated client object, ready to use.
+      #
+      # @param name [Symbol, String] the client name
+      # @return [PriceHubble::Client::Base] a compatible client instance
+      def client(name)
+        name
+          .to_s
+          .underscore
+          .camelize
+          .prepend('PriceHubble::Client::')
+          .constantize
+          .new
+      end
+    end
+  end
+end

data/lib/pricehubble/configuration.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  # The configuration for the pricehubble gem.
+  class Configuration
+    include ActiveSupport::Configurable
+
+    # Configure the API authentication credentials
+    config_accessor(:username) { ENV.fetch('PRICEHUBBLE_USERNAME', nil) }
+    config_accessor(:password) { ENV.fetch('PRICEHUBBLE_PASSWORD', nil) }
+
+    # The base URL of the API (there is no staging/canary
+    # endpoint we know about)
+    config_accessor(:base_url) do
+      val = ENV.fetch('PRICEHUBBLE_BASE_URL', 'https://api.pricehubble.com')
+      val.strip.chomp('/')
+    end
+
+    # The logger instance to use (when available we use the +Rails.logger+)
+    config_accessor(:logger) do
+      next(Rails.logger) if defined? Rails
+
+      Logger.new($stdout)
+    end
+  end
+end

data/lib/pricehubble/configuration_handling.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  # The top-level configuration handling.
+  #
+  # rubocop:disable Style/ClassVars because we split module code
+  module ConfigurationHandling
+    extend ActiveSupport::Concern
+
+    class_methods do
+      # Retrieve the current configuration object.
+      #
+      # @return [Configuration] the current configuration object
+      def configuration
+        @@configuration ||= Configuration.new
+      end
+
+      # Configure the concern by providing a block which takes
+      # care of this task. Example:
+      #
+      #   FactoryBot::Instrumentation.configure do |conf|
+      #     # conf.xyz = [..]
+      #   end
+      def configure
+        yield(configuration)
+      end
+
+      # Reset the current configuration with the default one.
+      def reset_configuration!
+        @@configuration = Configuration.new
+      end
+
+      # Get back the credentials bundle for an authentication.
+      #
+      # @return [Hash{Symbol => String}] the identity bundle
+      def identity_params
+        {
+          username: configuration.username,
+          password: configuration.password
+        }
+      end
+
+      # Retrieve the current configured logger instance.
+      #
+      # @return [Logger] the logger instance
+      delegate :logger, to: :configuration
+    end
+  end
+  # rubocop:enable Style/ClassVars
+end

data/lib/pricehubble/core_ext/hash.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+# All our Ruby core extensions for the +Hash+ class.
+class Hash
+  # Perform the regular +Hash#compact+ method on the object but takes care of
+  # deeply nested hashs.
+  #
+  # @return [Hash]
+  def deep_compact
+    deep_compact_in_object(self)
+  end
+
+  # Perform a deep key transformation on the hash,
+  # so all keys are in camelcase.
+  #
+  # @return [Hash]
+  def deep_camelize_keys
+    deep_transform_keys { |key| key.to_s.camelize(:lower) }
+  end
+
+  # Perform a deep key transformation on the hash,
+  # so all keys are in snakecase/underscored.
+  #
+  # @return [Hash]
+  def deep_underscore_keys
+    deep_transform_keys { |key| key.to_s.underscore }
+  end
+
+  private
+
+  # A supporting helper to allow deep hash compaction.
+  #
+  # @param object [Mixed] the object to compact
+  # @return [Mixed] the compacted object
+  #
+  # rubocop:disable Metrics/MethodLength because of the extra empty
+  #   hash compaction logic
+  def deep_compact_in_object(object)
+    case object
+    when Hash
+      object = object.compact.each_with_object({}) do |(key, value), result|
+        result[key] = deep_compact_in_object(value)
+      end
+      object.empty? ? nil : object.compact
+    when Array
+      object.map { |item| deep_compact_in_object(item) }
+    else
+      object
+    end
+  end
+  # rubocop:enable Metrics/MethodLength
+end

data/lib/pricehubble/entity/address.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  # The common PriceHubble address object.
+  #
+  # @see https://docs.pricehubble.com/#types-address
+  class Address < BaseEntity
+    # Mapped and tracked attributes
+    tracked_attr :post_code, :city, :street, :house_number
+  end
+end

data/lib/pricehubble/entity/authentication.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  # The PriceHubble ecosystem is built around the authentication on each
+  # request. This entity provides a simple to use interface for it.
+  #
+  # @see https://docs.pricehubble.com/#introduction-authentication
+  class Authentication < BaseEntity
+    # The expiration leeway to substract to guarantee
+    # acceptance on remote application calls
+    EXPIRATION_LEEWAY = 5.minutes
+
+    # Mapped and tracked attributes
+    tracked_attr :access_token, :expires_in
+
+    # Add some runtime attributes
+    attr_reader :created_at, :expires_at
+
+    # Register the time of initializing as base for the expiration
+    after_initialize do
+      @created_at = Time.current
+      @expires_at = created_at + (expires_in || 1.hour.to_i) - EXPIRATION_LEEWAY
+    end
+
+    # Allow to query whenever the current authentication instance is expired or
+    # not. This includes also a small leeway to ensure the acceptance is
+    # guaranteed.
+    #
+    # @return [Boolean] whenever the authentication instance is expired or not
+    def expired?
+      Time.current >= expires_at
+    end
+  end
+end

data/lib/pricehubble/entity/base_entity.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  # The base entity, with a lot of known ActiveRecord/ActiveModel features.
+  class BaseEntity
+    include ActiveModel::Model
+    include ActiveModel::Dirty
+
+    include PriceHubble::Utils::Bangers
+
+    # Additional singleton class functionalities
+    class << self
+      include PriceHubble::Utils::Bangers
+    end
+
+    include PriceHubble::EntityConcern::Callbacks
+    include PriceHubble::EntityConcern::Attributes
+    include PriceHubble::EntityConcern::Associations
+    include PriceHubble::EntityConcern::Client
+
+    # We collect all unknown attributes instead of raising while creating a new
+    # instance. The unknown attributes are wrapped inside a
+    # +RecursiveOpenStruct+ to ease the accessibility. This also allows us to
+    # handle responses in a forward-compatible way.
+    attr_accessor :_unmapped
+
+    # Create a new instance of an entity with a lot of known
+    # ActiveRecord/ActiveModel features.
+    #
+    # @param struct [Hash{Mixed => Mixed}, RecursiveOpenStruct] the initial data
+    # @return [PriceHubble::BaseEntity] a compatible instance
+    # @yield [PriceHubble::BaseEntity] the entity itself in the end
+    def initialize(struct = {})
+      # Set the initial unmapped struct
+      self._unmapped = RecursiveOpenStruct.new
+      # Build a RecursiveOpenStruct and a simple hash from the given data
+      struct, hash = sanitize_data(struct)
+      # Initialize associations and map them accordingly
+      struct, hash = initialize_associations(struct, hash)
+      # Initialize attributes and map unknown ones and pass back the known
+      known = initialize_attributes(struct, hash)
+      # Mass assign the known attributes via ActiveModel
+      super(known)
+      # Follow the ActiveRecord API
+      yield self if block_given?
+      # Run the initializer callbacks
+      _run_initialize_callbacks
+    end
+
+    class << self
+      # Initialize the class we were inherited to. We trigger all our methods
+      # which start with +inherited_setup_+ to allow per-concern/feature based
+      # initialization after BaseEntity inheritance.
+      #
+      # @param child_class [Class] the child class which inherits us
+      def inherited(child_class)
+        match = ->(sym) { sym.to_s.start_with? 'inherited_setup_' }
+        trigger = ->(sym) { send(sym, child_class) }
+        methods.select(&match).each(&trigger)
+      end
+    end
+  end
+end

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

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  module EntityConcern
+    # Allow simple association mappings like ActiveRecord supports (eg.
+    # +has_one+, +has_many+).
+    module Associations
+      extend ActiveSupport::Concern
+
+      included do
+        # Collect all the registed association configurations
+        class_attribute :associations
+
+        private
+
+        # Map the registered associations to the actual instance.
+        #
+        # @param struct [RecursiveOpenStruct] all the data as struct
+        # @param hash [Hash{Symbol => Mixed}] all the data as hash
+        # @return [Array<RecursiveOpenStruct, Hash{Symbol => Mixed}>] the
+        #   left over data
+        def initialize_associations(struct, hash)
+          # Walk through the configured associations and set them up
+          associations.each_with_object([struct, hash]) do |cur, memo|
+            opts = cur.last
+            send("map_#{opts[:type]}_association", cur.first, opts, *memo)
+          end
+        end
+
+        # Map an simple has_one association to the resulting entity attribute.
+        # The source key is stripped off according to the association
+        # definition.
+        #
+        # @param attribute [Symbol] the name of the destination attribute
+        # @param opts [Hash{Symbol => Mixed}] the association definition
+        # @param struct [RecursiveOpenStruct] all the data as struct
+        # @param hash [Hash{Symbol => Mixed}] all the data as hash
+        # @return [Array<RecursiveOpenStruct, Hash{Symbol => Mixed}>] the
+        #   left over data
+        #
+        # rubocop:disable Metrics/AbcSize because of the complex logic
+        # rubocop:disable Metrics/MethodLength because of the complex logic
+        def map_has_one_association(attribute, opts, struct, hash)
+          # Early exit when the source key is missing on the given data
+          key = opts[:from]
+
+          # Initialize an object on the association, even without data
+          if opts[:initialize] && send(attribute).nil?
+            hash[key] = {} unless hash.key? key
+          end
+
+          return [struct, hash] unless hash.key? key
+
+          # Instantiate a new entity from the association
+          val = hash[key]
+          val = opts[:class_name].new(val) unless val.is_a? opts[:class_name]
+          send("#{attribute}=", val)
+
+          # Strip off the source key, because we mapped it
+          struct.delete_field(key)
+          hash = hash.delete(key)
+          # Pass back the new data
+          [struct, hash]
+        end
+        # rubocop:enable Metrics/AbcSize
+        # rubocop:enable Metrics/MethodLength
+
+        # Map an simple has_many association to the resulting entity attribute.
+        # The source key is stripped off according to the association
+        # definition. Each element from the source attribute is instantiated
+        # separate and is added to the destination collection.
+        #
+        # @param attribute [Symbol] the name of the destination attribute
+        # @param opts [Hash{Symbol => Mixed}] the association definition
+        # @param struct [RecursiveOpenStruct] all the data as struct
+        # @param hash [Hash{Symbol => Mixed}] all the data as hash
+        # @return [Array<RecursiveOpenStruct, Hash{Symbol => Mixed}>] the
+        #   left over data
+        #
+        # rubocop:disable Metrics/AbcSize because of the complex logic
+        # rubocop:disable Metrics/CyclomaticComplexity because of the
+        #   complex logic
+        # rubocop:disable Metrics/PerceivedComplexity because of the
+        #   complex logic
+        # rubocop:disable Metrics/MethodLength because of the complex logic
+        def map_has_many_association(attribute, opts, struct, hash)
+          # Early exit when the source key is missing on the given data
+          key = opts[:from]
+
+          # When a singular appender was configured, we allow to use it as
+          # attribute source if the regular source is not available
+          key = opts[:fallback_from] if opts[:fallback_from] && !hash.key?(key)
+
+          # Initialize an empty array on the association
+          if opts[:initialize] && send(attribute).nil?
+            hash[key] = [] unless hash.key? key
+          end
+
+          return [struct, hash] unless hash.key? key
+
+          # Instantiate a new entity from each association element
+          hash[key] = [hash[key]] unless hash[key].is_a? Array
+          collection = hash[key].map do |elem|
+            next elem if elem.is_a? opts[:class_name]
+
+            opts[:class_name].new(elem)
+          end
+          send("#{attribute}=", collection)
+
+          # Strip off the source key, because we mapped it
+          struct.delete_field(key)
+          hash = hash.delete(key)
+
+          # Pass back the new data
+          [struct, hash]
+        end
+        # rubocop:enable Metrics/AbcSize
+        # rubocop:enable Metrics/CyclomaticComplexity
+        # rubocop:enable Metrics/PerceivedComplexity
+        # rubocop:enable Metrics/MethodLength
+      end
+
+      # rubocop:disable Naming/PredicateName because we follow
+      #   known naming conventions
+      class_methods do
+        # Initialize the associations structures on an inherited class.
+        #
+        # @param child_class [Class] the child class which inherits us
+        def inherited_setup_associations(child_class)
+          child_class.associations = {}
+        end
+
+        # Define a simple +has_one+ association.
+        #
+        # Options
+        # * +:class_name+ - the entity class to use, otherwise it is guessed
+        # * +:from+ - take the data from this attribute
+        # * +:persist+ - whenever to send the association
+        #                attributes (default: false)
+        # * +:initialize+ - whenever to initialize an empty object
+        #
+        # @param entity [String, Symbol] the attribute/entity name
+        # @param args [Hash{Symbol => Mixed}] additional options
+        def has_one(entity, **args)
+          # Sanitize options
+          entity = entity.to_sym
+          opts = { class_name: nil, from: entity, persist: false } \
+                 .merge(args).merge(type: :has_one)
+          # Resolve the given entity to a class name, when no explicit class
+          # name was given via options
+          if opts[:class_name].nil?
+            opts[:class_name] = \
+              entity.to_s.camelcase.prepend('PriceHubble::').constantize
+          end
+          # Register the association
+          associations[entity] = opts
+          # Generate getters and setters
+          attr_accessor entity
+          # Add the entity to the tracked attributes if it should be persisted
+          tracked_attr entity if opts[:persist]
+        end
+
+        # Define a simple +has_many+ association.
+        #
+        # Options
+        # * +:class_name+ - the entity class to use, otherwise it is guessed
+        # * +:from+ - take the data from this attribute
+        # * +:fallback_from+ - otherwise take the data from the fallback
+        # * +:persist+ - whenever to send the association
+        #                attributes (default: false)
+        # * +:initialize+ - whenever to initialize an empty array
+        #
+        # @param entity [String, Symbol] the attribute/entity name
+        # @param args [Hash{Symbol => Mixed}] additional options
+        def has_many(entity, **args)
+          # Sanitize options
+          entity = entity.to_sym
+          opts = { class_name: nil, from: entity, persist: false } \
+                 .merge(args).merge(type: :has_many)
+          # Resolve the given entity to a class name, when no explicit class
+          # name was given via options
+          if opts[:class_name].nil?
+            opts[:class_name] = entity.to_s.singularize.camelcase
+                                      .prepend('PriceHubble::').constantize
+          end
+          # Register the association
+          associations[entity] = opts
+          # Generate getters and setters
+          attr_accessor entity
+          # Add the entity to the tracked attributes if it should be persisted
+          tracked_attr entity if opts[:persist]
+        end
+      end
+      # rubocop:enable Naming/PredicateName
+    end
+  end
+end

data/lib/pricehubble/entity/concern/attributes/date_array.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  module EntityConcern
+    module Attributes
+      # A separated date array typed attribute helper.
+      module DateArray
+        extend ActiveSupport::Concern
+
+        class_methods do
+          # Register a date array attribute (only sanitization).
+          #
+          # @param name [Symbol, String] the name of the attribute
+          # @param _args [Hash{Symbol => Mixed}] additional options
+          def typed_attr_date_array(name, **_args)
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def sanitize_attr_#{name}
+                return if @#{name}.nil?
+                @#{name}.map do |date|
+                  date.strftime('%Y-%m-%d')
+                end
+              end
+            RUBY
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pricehubble/entity/concern/attributes/enum.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  module EntityConcern
+    module Attributes
+      # A separated enum typed attribute helper.
+      module Enum
+        extend ActiveSupport::Concern
+
+        class_methods do
+          # Register a fixed enum attribute.
+          #
+          # @param name [Symbol, String] the name of the attribute
+          # @param values [Array<String, Symbol>] the allowed values
+          # @param _args [Hash{Symbol => Mixed}] additional options
+          #
+          # rubocop:disable Metrics/MethodLength because of the inline
+          #   meta method definitions
+          def typed_attr_enum(name, values:, **_args)
+            values = values.map(&:to_sym)
+            const_values = "ATTR_#{name.to_s.upcase}"
+
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              # Define the constant for all valid values
+              #{const_values} = #{values}.freeze
+
+              def #{name}=(value)
+                #{name}_will_change!
+                value = value.to_sym
+
+                unless #{const_values}.include? value
+                  raise ArgumentError, "'\#{value}' is not a valid #{name} " \
+                    "(values: \#{#{const_values}})"
+                end
+
+                @#{name} = value
+              end
+            RUBY
+
+            values.each do |value|
+              class_eval <<-RUBY, __FILE__, __LINE__ + 1
+                def #{value}!
+                  self.#{name} = :#{value}
+                end
+
+                def #{value}?
+                  self.#{name} == :#{value}
+                end
+              RUBY
+            end
+          end
+          # rubocop:enable Metrics/MethodLength
+        end
+      end
+    end
+  end
+end

data/lib/pricehubble/entity/concern/attributes/range.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  module EntityConcern
+    module Attributes
+      # A separated range typed attribute helper.
+      module Range
+        extend ActiveSupport::Concern
+
+        class_methods do
+          # Register a range attribute.
+          #
+          # @param name [Symbol, String] the name of the attribute
+          # @param _args [Hash{Symbol => Mixed}] additional options
+          def typed_attr_range(name, **_args)
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def #{name}
+                # We cannot handle nil values
+                return unless @#{name}
+
+                # Otherwise we assume the hash contains a +lower+ and +upper+
+                # key from which we assemble the range
+                hash = @#{name}
+                hash[:lower]..hash[:upper]
+              end
+            RUBY
+          end
+        end
+      end
+    end
+  end
+end

data/lib/pricehubble/entity/concern/attributes/string_inquirer.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module PriceHubble
+  module EntityConcern
+    module Attributes
+      # A separated string inquirer typed attribute helper.
+      module StringInquirer
+        extend ActiveSupport::Concern
+
+        class_methods do
+          # Register a casted string inquirer attribute.
+          #
+          # @param name [Symbol, String] the name of the attribute
+          # @param _args [Hash{Symbol => Mixed}] additional options
+          def typed_attr_string_inquirer(name, **_args)
+            class_eval <<-RUBY, __FILE__, __LINE__ + 1
+              def #{name}=(value)
+                #{name}_will_change!
+                @#{name} = ActiveSupport::StringInquirer.new(value.to_s)
+              end
+            RUBY
+          end
+        end
+      end
+    end
+  end
+end