ecoportal-api-v2 0.8.4

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,279 @@
+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
+
+          # @return [Class] the class of the elements of the Collection
+          def items_class
+            self.class.klass
+          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
+
+          # Get an element usign the `key`.
+          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, pos: NOT_USED, before: NOT_USED, after: NOT_USED)
+            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
+            item_doc = JSON.parse(item_doc.to_json)
+            if item = self[value]
+              item.replace_doc(item_doc)
+            else
+              _doc_upsert(item_doc, pos: pos, before: before, after: after)
+            end
+            (item || self[item_doc]).tap do |item|
+              yield(item) if block_given?
+            end
+          end
+
+          def delete!(value)
+            unless value.is_a?(Hash) || value.is_a?(Content::DoubleModel)
+              raise "'Content::DoubleModel' or 'Hash' doc required"
+            end
+            if item = self[value]
+              _doc_delete(item.doc)
+            end
+          end
+
+          protected
+
+          def order_matters?; self.class.order_matters; end
+          def uniq?;          self.class.uniq;          end
+          def items_key;      self.class.items_key;     end
+
+          def on_change
+            variables_remove!
+          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
+
+          # Helper to remove tracked down instance variables
+          def variable_remove!(key)
+            if @items_by_key && (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
+
+          def _doc_delete(value)
+            if current_pos = _doc_key(value)
+              _doc_items.delete_at(current_pos)
+              on_change
+            end
+          end
+
+          def _doc_upsert(value, pos: NOT_USED, before: NOT_USED, after: NOT_USED)
+            current_pos = _doc_key(value)
+            pos = case
+              when used_param?(pos)
+                pos
+              when used_param?(before)
+                _doc_key(before)
+              when used_param?(after)
+                #puts "to add after #{after.id}"
+                if i = _doc_key(after)
+                  i + 1
+                end
+              end
+
+            pos ||= current_pos
+
+            if current_pos && pos
+              _doc_items.delete_at(current_pos)
+              pos = (pos <= current_pos)? pos : pos - 1
+            end
+
+            pos = (pos && pos < _doc_items.length)? pos : _doc_items.length
+
+            pos.tap do |i|
+              _doc_items.insert(pos, value)
+              on_change
+            end
+
+          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,356 @@
+require 'securerandom'
+
+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
+
+            def new_uuid(length: 12)
+              SecureRandom.hex(length)
+            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, klass:)
+              embed(method, key: key, nullable: nullable, multiple: false, klass: klass)
+            end
+
+            # @note
+            #   - if you have a dedicated `Enumerable` class to manage `many`, you should use `:enum_class`
+            #   - otherwise, just indicate the child class in `:klass` and it will auto generate the class
+            # @param
+            def embeds_many(method, key: method, order_matters: false, order_key: nil, klass: nil, enum_class: nil)
+              if enum_class
+                eclass = enum_class
+              elsif klass
+                eclass = new_class(method, inherits: Common::Content::CollectionModel) do |dim_class|
+                  dim_class.klass         = klass
+                  dim_class.order_matters = order_matters
+                  dim_class.order_key     = order_key
+                end
+              else
+                raise "You should either specify the 'klass' of the elements or the 'enum_class'"
+              end
+              embed(method, key: key, multiple: true, klass: eclass)              
+            end
+
+            private
+
+            def embed(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
+
+          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_pretty
+            puts JSON.pretty_generate(as_json)
+            self
+          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
+
+          protected
+
+          def is_root?
+            _parent == self && !!defined?(@doc)
+          end
+
+          def linked?
+            is_root? || !!_parent.doc
+          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.dup.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