ecoportal-api-oozes 0.5.5

data/lib/ecoportal/api/common/content/class_helpers.rb

@@ -0,0 +1,111 @@
+module Ecoportal
+  module API
+    module Common
+      module Content
+        module ClassHelpers
+          include Common::BaseClass
+          NOT_USED = "no_used!"
+
+          # Class resolver
+          # @note it caches the resolved `klass`es
+          # @raise [Exception] when could not resolve if `exception` is `true`
+          # @param klass [Class, String, Symbol] the class to resolve
+          # @param exception [Boolean] if it should raise exception when could not resolve
+          # @return [Class] the `Class` constant
+          def resolve_class(klass, exception: true)
+            @resolved ||= {}
+            @resolved[klass] ||=
+              case klass
+                when Class
+                  klass
+                when String
+                  begin
+                    Kernel.const_get(klass)
+                  rescue NameError => e
+                    raise if exception
+                  end
+                when Symbol
+                  resolve_class(self.send(klass))
+                else
+                  raise "Unknown class: #{klass}" if exception
+              end
+          end
+
+          # Helper to normalize `key` into a correct `ruby` **constant name**
+          # @param key [String, Symbol] to be normalized
+          # @return [String] a correct constant name
+          def to_constant(key)
+            str_name = key.to_s.strip.split(/[\-\_ ]/i).compact.map do |str|
+              str.slice(0).upcase + str.slice(1..-1).downcase
+            end.join("")
+          end
+
+          # Helper to create an instance variable `name`
+          # @param [String, Symbol] the name of the variable
+          # @reutrn [String] the name of the created instance variable
+          def instance_variable_name(name)
+            str = name.to_s
+            str = "@#{str}" unless str.start_with?("@")
+            str
+          end
+
+          # If the class for `name` exists, it returns it. Otherwise it generates it.
+          # @param name [String, Symbol] the name of the new class
+          # @param inherits [Class] the parent class to _inherit_ from
+          # @yield [child_class] configure the new class
+          # @yieldparam child_class [Class] the new class
+          # @return [Class] the new generated class
+          def new_class(name, inherits:)
+            name            = name.to_sym.freeze
+            class_name      = to_constant(name)
+            full_class_name = "#{inherits}::#{class_name}"
+
+            unless target_class = resolve_class(full_class_name, exception: false)
+              target_class = Class.new(inherits)
+              self.const_set class_name, target_class
+            end
+
+            target_class.tap do |klass|
+              yield(klass) if block_given?
+            end
+          end
+
+          # Helper to parse a value into a `Time` object.
+          # @raise [Exception] if `exception` is `true` and could not convert
+          # @param value [String, Date] the value to convert to `Time`
+          # @param exception [Boolean] if should raise `Exception` when could not convert
+          # @return
+          def to_time(value, exception: true)
+            case value
+            when NilClass
+              value
+            when String
+              begin
+                Time.parse(value)
+              rescue ArgumentArgument => e
+                raise if exception
+                nil
+              end
+            when Date
+              Time.parse(value.to_s)
+            when Time
+              value
+            else
+              to_time(value.to_s) if value.respond_to?(:to_s)
+            end
+          end
+
+          # Helper to determine if a paramter has been used
+          # @note to effectivelly use this helper, you should initialize your target
+          #  paramters with the constant `NOT_USED`
+          # @param val [] the value of the paramter
+          # @return [Boolean] `true` if value other than `NOT_USED`, `false` otherwise
+          def used_param?(val)
+            val != NOT_USED
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/common/content/client.rb

@@ -0,0 +1,40 @@
+module Ecoportal
+  module API
+    module Common
+      module Content
+        # @see Ecoportal::API::Common::Client
+        class Client < Common::Client
+          attr_accessor :logger
+
+          # @note the `api_key` will be automatically added as parameter `X-ECOPORTAL-API-KEY` in the header of the http requests.
+          def initialize(api_key:, version: "v2", host: "live.ecoportal.com", logger: nil)
+            super(api_key: api_key, version: "v2", host: host, logger: logger)
+          end
+
+          def delete(path)
+            raise "DELETE operation does not have integration for api #{@version}"
+          end
+
+          # @see Ecoportal::API::Common::Client#post
+          # @param params [Hash] the header paramters of the http request (not including the api key).
+          # @option params [String] :template_id original template.
+          def post(path, data:, params: {})
+            instrument("POST", path, params) do
+              request do |http|
+                http.post(url_for(path), json: data, params: params)
+              end
+            end
+          end
+
+          # Creates a HTTP object adding the `X-ECOPORTAL-API-KEY` param to the header.
+          # @note It configures HTTP so it only allows body data in json format.
+          # @return [HTTP] HTTP object.
+          def base_request
+            @base_request ||= HTTP.headers("X-ECOPORTAL-API-KEY" => @api_key).accept(:json)
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/common/content/collection_model.rb

@@ -0,0 +1,223 @@
+module Ecoportal
+  module API
+    module Common
+      module Content
+        class CollectionModel < Content::DoubleModel
+
+          class << self
+            attr_writer   :klass
+            attr_accessor :order_matters, :order_key
+
+            def items_key
+              @items_key ||= "id"
+            end
+
+            def items_key=(value)
+              @items_key = value && value.to_s.freeze
+            end
+
+            # Resolves to the nuclear `Class` of the elements
+            # @note
+            #   - use block to define `klass` callback
+            # @param value [Hash] base `doc` (raw object) to create the object with
+            # @yield [doc] identifies the target `class` of the raw object
+            # @yieldparam doc [Hash]
+            # @yieldreturn [Klass] the target `class`
+            # @return [Klass] the target `class`
+            def klass(value = NOT_USED, &block)
+              if block
+                @klass = block
+                block.call(value) if value != NOT_USED
+              elsif used_param?(value)
+                if @klass.is_a?(Proc)
+                  @klass.call(value)
+                else
+                  resolve_class(@klass, exception: false)
+                end
+              else
+                resolve_class(@klass, exception: false)
+              end
+            end
+
+            # Generates a new object of the target class
+            # @note
+            #   - use block to define `new_item` callback, which will prevail over `klass`
+            #   - if `new_item` callback was **not** defined, it is required to defnie `klass`
+            # @param doc [Hash] doc to parse
+            # @note if block is given, it ignores `doc`
+            # @yield [doc, parent, key] creates an object instance of the target `klass`
+            # @yieldparam doc [Hash]
+            # @yieldreturn [Klass] instance object of the target `klass`
+            # @return [Klass] instance object of the target `klass`
+            def new_item(doc = NOT_USED, parent: nil, key: nil, &block)
+              if block
+                @new_item = block
+              elsif used_param?(doc)
+                raise "You should define either a 'klass' or a 'new_item' callback first" unless klass?
+                if @new_item
+                  @new_item.call(doc, parent, key)
+                else
+                  if target_class = self.klass(doc)
+                    doc.is_a?(target_class) ? doc : target_class.new(doc, parent: parent, key: key)
+                  else
+                    raise "Could not find a class for: #{doc}"
+                  end
+                end
+              else
+                raise "To define the 'new_item' callback (factory), you need to use a block"
+              end
+            end
+
+            # @return [Boolean] are there the factory logics to build item objects defined?
+            def klass?
+              @klass || @new_item
+            end
+
+            def doc_class(name)
+              dim_class = new_class(name, inherits: Common::Content::ArrayModel) do |klass|
+                klass.order_matters = order_matters
+                klass.uniq          = uniq
+              end
+            end
+
+          end
+
+          include Enumerable
+
+          def initialize(ini_doc = [], parent: self, key: nil)
+            unless self.class.klass?
+              raise "Undefined base 'klass' or 'new_item' callback for #{self.class}"
+            end
+
+            ini_doc = case ini_doc
+                      when Array
+                        ini_doc
+                      when Enumerable
+                        ini_doc.to_a
+                      else
+                        []
+                      end
+
+            super(ini_doc, parent: parent, key: key)
+          end
+
+          # Transforms `value` into the actual `key` to access the object in the doc `Array`
+          def _doc_key(value)
+            #print "*(#{value.class})"
+            return super(value) unless value.is_a?(Hash) || value.is_a?(Content::DoubleModel)
+            if id = get_key(value)
+              #print "^"
+              _doc_items.index {|item| get_key(item) == id}.tap do |p|
+                #print "{{#{p}}}"
+              end
+            else
+              raise UnlinkedModel.new("Can't find child: #{value}")
+            end
+          end
+
+          def length;   count;      end
+          def empty?;   count == 0; end
+          def present?; count > 0;  end
+
+          def each(&block)
+            return to_enum(:each) unless block
+            _items.each(&block)
+          end
+
+          def _items
+            return @_items if @_items
+            [].tap do |elements|
+              variable_set(:@_items, elements)
+              _doc_items.each do |item_doc|
+                elements << new_item(item_doc)
+              end
+            end
+          end
+
+          def [](value)
+            items_by_key[get_key(value)]
+          end
+
+          def values_at(*keys)
+            keys.map {|key| self[key]}
+          end
+
+          # Tries to find the element `value`, if it exists, it updates it
+          # Otherwise it pushes it to the end
+          # @return the element
+          def upsert!(value)
+            unless value.is_a?(Hash) || value.is_a?(Content::DoubleModel)
+              raise "'Content::DoubleModel' or 'Hash' doc required"
+            end
+            item_doc = value.is_a?(Content::DoubleModel)? value.doc : value
+            if item = self[value]
+              item.replace_doc(JSON.parse(item_doc.to_json))
+            else
+              item = new_item(item_doc)
+              _doc_items << item.doc
+            end
+            item
+          end
+
+          protected
+
+          def order_matters?; self.class.order_matters; end
+          def uniq?;          self.class.uniq;          end
+          def items_key;      self.class.items_key;     end
+
+          # Gets the `key` of the object
+          def get_key(value)
+            case value
+            when Content::DoubleModel
+              value.key
+            when Hash
+              value[items_key]
+            when String
+              value
+            end
+          end
+
+          def _doc_items
+            replace_doc([]) unless doc.is_a?(Array)
+            doc
+          end
+
+          # @note it does not support a change of `id` on an existing item
+          def items_by_key
+            return @items_by_key if @indexed
+            {}.tap do |hash|
+              variable_set(:@items_by_key, hash)
+              _items.each {|item| hash[item.key] = item}
+              @indexed = true
+            end
+          end
+
+          private
+
+          def new_item(value)
+            self.class.new_item(value, parent: self)
+          end
+
+          private
+
+          # Helper to remove tracked down instance variables
+          def variable_remove!(key)
+            if (k = get_key(key)) && (item = @items_by_key[k])
+              _items.delete(item) if _items.include?(item)
+              @items_by_key.delete(k)
+            else
+              super(key)
+            end
+          end
+
+          # Removes all the persistent variables
+          def variables_remove!
+            @indexed = false
+            super
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/common/content/doc_helpers.rb

@@ -0,0 +1,67 @@
+module Ecoportal
+  module API
+    module Common
+      module Content
+        module DocHelpers
+
+          # Helper used to build the `body` of an HTTP request
+          # @param doc [Page, Hash] hashable object
+          # @return [Hash, nil] the `patch` formated `data` ready to include as `body` of a HTTP request
+          def get_body(doc, level: "page")
+            {}.tap do |body|
+              body["#{level}"] = case
+                when doc.respond_to?(:as_update)
+                  doc.as_update
+                when doc.respond_to?(:as_json)
+                  Common::Content::HashPatchDiff.patch_diff(doc.as_json)
+                when doc.is_a?(Hash)
+                  Common::Content::HashPatchDiff.patch_diff(doc)
+                else
+                  raise "Could not get body for doc: #{doc}"
+                end
+            end
+          end
+
+          # Helper used to **identify** the `id` of the target object
+          # @param doc [Page, Hash] hashable object
+          # @param exception [Boolean] states if `id` **must** be present
+          # @return [Hash, nil] the `patch` formated `data` ready to include as `body` of a HTTP request
+          def get_id(doc, exception: true)
+            id = nil
+            id ||= doc.id if doc.respond_to?(:id)
+            id ||= doc["id"] if doc.is_a?(Hash)
+            id ||= doc if doc.is_a?(String)
+            raise "No ID has been given!" unless id || !exception
+            id
+          end
+
+          # Helper used to **identify** the `id` s of objects contained in an `Array`
+          # @param doc [Array] the source Array
+          # @return [Array<String>] the `id` s thereof
+          def array_ids(arr)
+            return [] if !arr.is_a?(Array) || arr.empty?
+            arr.map {|item| get_id(item, exception: false)}
+          end
+
+          # Helper used to **identify** in an Array the `position` of an object with certain `id`
+          # @param doc [Array] the source Array
+          # @return [Integer] the `position` thereof
+          def array_id_index(arr, id)
+            return unless arr.is_a?(Array)
+            arr.index {|item| get_id(item, exception: false) == id}
+          end
+
+          # Helper used to **get** in an Array and `object` item with certain `id`
+          # @param doc [Array] the source Array
+          # @return [Integer] the `object` with that `id`
+          def array_id_item(arr, id)
+            if idx = array_id_index(arr, id)
+              arr[idx]
+            end
+          end
+
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/common/content/double_model.rb

@@ -0,0 +1,334 @@
+module Ecoportal
+  module API
+    module Common
+      module Content
+        # Basic model class, to **build _get_ / _set_ `methods`** for a given property
+        # which differs of `attr_*` ruby native class methods because `pass*`
+        # completelly **links** the methods **to a subjacent `Hash` model**
+        class DoubleModel < Common::BaseModel
+          NOT_USED = Common::Content::ClassHelpers::NOT_USED
+          extend Common::Content::ClassHelpers
+
+          class UnlinkedModel < Exception
+            def initialize (msg = "Something went wrong when linking the document.", from: nil, key: nil)
+              msg += " From: #{from}." if from
+              msg += " key: #{key}."   if key
+              super(msg)
+            end
+          end
+
+          class << self
+            attr_reader :key
+
+            def key?
+              !!key
+            end
+
+            def key=(value)
+              @key = value.to_s.freeze
+            end
+
+            # Same as `attr_reader` but links to a subjacent `Hash` model property
+            # @note it does **not** create an _instance variable_
+            def pass_reader(*methods)
+              methods.each do |method|
+                method = method.to_s.freeze
+
+                define_method method do
+                  value = send(:doc)[method]
+                  value = yield(value) if block_given?
+                  value
+                end
+              end
+              self
+            end
+
+            # Same as `attr_writer` but links to a subjacent `Hash` model property
+            # @note it does **not** create an _instance variable_
+            def pass_writer(*methods)
+              methods.each do |method|
+                method = method.to_s.freeze
+
+                define_method "#{method}=" do |value|
+                  value = yield(value) if block_given?
+                  send(:doc)[method] = value
+                end
+              end
+              self
+            end
+
+            # This method is essential to give stability to the model
+            # @note `Content::CollectionModel` needs to find elements in the doc `Array`.
+            #  The only way to do it is via the access key (i.e. `id`). However, there is
+            #  no chance you can avoid invinite loop for `get_key` without setting an
+            #  instance variable key at the moment of the object creation, when the
+            #  `doc` is firstly received
+            def passkey(method)
+              method   = method.to_s.freeze
+              var      = instance_variable_name(method)
+              self.key = method
+
+              define_method method do
+                return instance_variable_get(var) if instance_variable_defined?(var)
+                value = send(:doc)[method]
+                value = yield(value) if block_given?
+                value
+              end
+
+              define_method "#{method}=" do |value|
+                variable_set(var, value)
+                value = yield(value) if block_given?
+                send(:doc)[method] = value
+              end
+
+              self
+            end
+
+            # Same as `attr_accessor` but links to a subjacent `Hash` model property
+            # @param read_only [Boolean] should it only define the reader?
+            def passthrough(*methods, read_only: false)
+              pass_reader *methods
+              pass_writer *methods unless read_only
+              self
+            end
+
+            # To link as a `Time` date to a subjacent `Hash` model property
+            # @see Ecoportal::API::Common::Content::DoubleModel#passthrough
+            # @param read_only [Boolean] should it only define the reader?
+            def passdate(*methods, read_only: false)
+              pass_reader(*methods) {|value| to_time(value)}
+              unless read_only
+                pass_writer(*methods) {|value| to_time(value)&.iso8601}
+              end
+              self
+            end
+
+            # To link as plain `Array` to a subjacent `Hash` model property
+            # @param order_matters [Boolean] does the order matter
+            # @param uniq [Boolean] should it contain unique elements
+            def passarray(*methods, order_matters: true, uniq: true)
+              methods.each do |method|
+                method = method.to_s.freeze
+                var    = instance_variable_name(method)
+
+                dim_class = new_class(method, inherits: Common::Content::ArrayModel) do |klass|
+                  klass.order_matters = order_matters
+                  klass.uniq          = uniq
+                end
+
+                define_method method do
+                  return instance_variable_get(var) if instance_variable_defined?(var)
+                  new_obj = dim_class.new(parent: self, key: method)
+                  variable_set(var, new_obj)
+                end
+              end
+            end
+
+            # Helper to embed one nested object under one property
+            def embeds_one(method, key: method, nullable: false, multiple: false, klass:)
+              method = method.to_s.freeze
+              var    = instance_variable_name(method).freeze
+              k      = key.to_s.freeze
+
+              # retrieving method (getter)
+              define_method(method) do
+                return instance_variable_get(var) if instance_variable_defined?(var)
+                unless nullable
+                  doc[k] ||= multiple ? [] : {}
+                end
+                return variable_set(var, nil) unless doc[k]
+
+                self.class.resolve_class(klass).new(
+                  doc[k], parent: self, key: k
+                ).tap {|obj| variable_set(var, obj)}
+              end
+            end
+
+            def embeds_multiple(method, key: method, order_matters: false, order_key: nil, klass:)
+              dim_class = new_class(method, inherits: Common::Content::CollectionModel) do |dklass|
+                dklass.klass         = klass
+                dklass.order_matters = order_matters
+                dklass.order_key     = order_key
+              end
+
+              embeds_one(method, key: key, multiple: true, klass: dim_class)
+            end
+          end
+
+          attr_reader :_parent, :_key
+
+          def initialize(doc = {}, parent: self, key: nil)
+            @_dim_vars = []
+            @_parent   = parent || self
+            @_key      = key    || self
+
+            if _parent == self
+              @doc          = doc
+              @original_doc = JSON.parse(@doc.to_json)
+            end
+
+            if key_method? && doc && doc.is_a?(Hash)
+              self.key = doc[key_method]
+              #puts "\n$(#{self.key}<=>#{self.class})"
+            end
+          end
+
+          def root
+            return self if is_root?
+            _parent.root
+          end
+
+          def key
+            raise "No key_method defined for #{self.class}" unless key_method?
+            self.method(key_method).call
+          end
+
+          def key=(value)
+            raise "No key_method defined for #{self.class}" unless key_method?
+            method = "#{key_method}="
+            self.method(method).call(value)
+          end
+
+          # Offers a method for child classes to transform the key,
+          # provided that the child's `doc` can be accessed
+          def _doc_key(value)
+            if value.is_a?(Content::DoubleModel) && !value.is_root?
+              #print "?(#{value.class}<=#{value._parent.class})"
+              value._parent._doc_key(value)
+            else
+              #print "!(#{value}<=#{self.class})"
+              value
+            end
+          end
+
+          def doc
+            raise UnlinkedModel.new(from: "#{self.class}#doc", key: _key) unless linked?
+            return @doc if is_root?
+            _parent.doc.dig(*[_doc_key(_key)].flatten)
+          end
+
+          def original_doc
+            raise UnlinkedModel.new(from: "#{self.class}#original_doc", key: _key) unless linked?
+            return @original_doc if is_root?
+            _parent.original_doc.dig(*[_doc_key(_key)].flatten)
+          end
+
+          def as_json
+            doc
+          end
+
+          def to_json(*args)
+            doc.to_json(*args)
+          end
+
+          def as_update
+            new_doc = as_json
+            Common::Content::HashDiffPatch.patch_diff(new_doc, original_doc)
+          end
+
+          def dirty?
+            as_update != {}
+          end
+
+          def consolidate!
+            replace_original_doc(JSON.parse(doc.to_json))
+          end
+
+          def reset!(key = nil)
+            if key
+              keys    = [].push(key).compact
+              odoc    = original_doc.dig(*keys)
+              dig_set(doc, key, odoc && JSON.parse(odoc.to_json))
+
+            else
+              replace_doc(JSON.parse(original_doc.to_json))
+            end
+          end
+
+          #def print
+          #  puts JSON.pretty_generate(as_json)
+          #  self
+          #end
+
+          protected
+
+          def is_root?
+            _parent == self && !!defined?(@doc)
+          end
+
+          def linked?
+            is_root? || !!_parent.doc
+          end
+
+          def replace_doc(new_doc)
+            raise UnlinkedModel.new(from: "#{self.class}#replace_doc", key: _key) unless linked?
+            if is_root?
+              @doc = new_doc
+            else
+              dig_set(_parent.doc, [_doc_key(_key)].flatten, new_doc)
+              _parent.variable_remove!(_key)
+              variables_remove!
+            end
+          end
+
+          def replace_original_doc(new_doc)
+            raise UnlinkedModel.new(from: "#{self.class}#replace_original_doc", key: _key) unless linked?
+            if is_root?
+              @orginal_doc = new_doc
+            else
+              dig_set(_parent.orginal_doc, [_doc_key(_key)].flatten, new_doc)
+            end
+          end
+
+          # Helper to track down persistent variables
+          def variable_set(key, value)
+            var = instance_variable_name(key)
+            @_dim_vars.push(var).uniq!
+            instance_variable_set(var, value)
+          end
+
+          # Helper to remove tracked down instance variables
+          def variable_remove!(key)
+            var = instance_variable_name(key)
+            unless !@_dim_vars.include?(var)
+              @_dim_vars.delete(var)
+              remove_instance_variable(var)
+            end
+          end
+
+          # Removes all the persistent variables
+          def variables_remove!
+            @_dim_vars.map {|k| variable_remove!(k)}
+          end
+
+          private
+
+          def instance_variable_name(key)
+            self.class.instance_variable_name(key)
+          end
+
+          def dig_set(obj, keys, value)
+            if keys.length == 1
+              obj[keys.first] = value
+            else
+              dig_set(obj[keys.first], keys.slice(1..-1), value)
+            end
+          end
+
+          def used_param?(val)
+            self.class.used_param?(val)
+          end
+
+          def key_method?
+            self.class.key?
+          end
+
+          def key_method
+            self.class.key
+          end
+
+        end
+      end
+    end
+  end
+end