eco-helpers 1.5.1 → 1.5.6

data/lib/eco/api/common/people/person_entry_attribute_mapper.rb

@@ -23,7 +23,7 @@ module Eco
           #   - if `data` is a `Person` object, its behaviour is `serialise`.
           #   - if `data` is **not** a `Person` object, it does a `parse`.
           #   - currently **in rework**, so there may be subtle differences that make it temporarily unstable (yet it is reliable).
-          # @param data [Hash, Person] `Person` object to be serialized or hashed entry (note: `CSV::Row` is accepted).
+          # @param data [Hash, Ecoportal::API::V1::Person] `Person` object to be serialized or hashed entry to be parsed (note: `CSV::Row` is accepted).
           # @param person_parser [Common::People::PersonParser]  parser/serializer of person attributes (it contains a set of attribute parsers).
           # @param attr_map [Eco::Data::Mapper] mapper to translate attribute names from _external_ to _internal_ names and _vice versa_.
           # @param logger [Common::Session::Logger, ::Logger] object to manage logs.
@@ -42,6 +42,7 @@ module Eco
             else  # SERIALIZING
               @person          = data
               @internal_attrs  = @person_parser.all_attrs
+              @aliased_attrs   = @attr_map.list(:internal)
             end
 
             @core_attrs    = @person_parser.target_attrs_core(@internal_attrs)
@@ -53,7 +54,7 @@ module Eco
           # To know if currently the object is in parse or serialize mode.
           # @return [Boolean] returns `true` if we are **parsing**, `false` otherwise.
           def parsing?
-            !@source.is_a?(Ecoportal::API::Internal::Person)
+            !@source.is_a?(Ecoportal::API::V1::Person)
           end
 
           # To know if currently the object is in parse or serialize mode.

data/lib/eco/api/common/people/person_parser.rb

@@ -9,6 +9,10 @@ module Eco
         # @attr_reader details_attrs [Array<String>] internal names of schema details attributes.
         # @attr_reader all_attrs [Array<String>] all the internal name attributes, including _core_, _account_ and _details_.
         class PersonParser
+          extend  Eco::API::Common::ClassAutoLoader
+          autoloads_children_of     "Eco::API::Common::Loaders::Parser"
+          autoload_namespace_ignore "Eco::API"
+
           CORE_ATTRS    = ["id", "external_id", "email", "name", "supervisor_id", "filter_tags", "freemium"]
           ACCOUNT_ATTRS = ["policy_group_ids", "default_tag", "send_invites", "landing_page_id", "login_provider_ids"]
           TYPE          = [:select, :text, :date, :number, :phone_number, :boolean, :multiple]
@@ -43,12 +47,19 @@ module Eco
             end
 
             @all_attrs = CORE_ATTRS + ACCOUNT_ATTRS + @details_attrs
+            self.class.autoload_children(self)
           end
 
           def patched!
             @patch_version += 1
           end
 
+          def new(schema: nil)
+            self.class.new(schema: schema || self.schema).merge(self)
+          end
+
+          # @!group Scopping attributes (identifying, presence & active)
+
           # Scopes `source_attrs` using the _**core** attributes_.
           # @note use this helper to know which among your attributes are **core** ones.
           # @param source_attrs [Array<String>]
@@ -78,9 +89,9 @@ module Eco
 
           # Lists all defined attributes, types and formats.
           # @return [Array<String>] the list of defined parsers/serializers.
-          #def list_defined
-          #  @parsers.keys
-          #end
+          def defined_list
+            @parsers.keys
+          end
 
           # Returns a list of all the internal attributes of the model that have a parser defined.
           # @note
@@ -94,10 +105,19 @@ module Eco
           end
 
           # Returns a list of all the internal attributes of the model that have a parser defined & that should be active.
-          # @param [Hash, Array<String>]
-          # @return [Array<String>] list of all attribute defined parsers that should be active.
-          def active_attrs(source_data)
-            defined_attrs.select {|attr| @parsers[attr].parser_active?(source_data)}
+          # @param source_data [Hash, Array<String>] the data that we scope for parsing
+          # @param phase [Symbol] the phase when the attr parser is expected to be called.
+          # Can be [:internal, :final, :person]
+          # @param process [Symbol] either `:parse` or `:serialize`, depending if we want to parse or serialize the `attr`.
+          # @return [Array<String>] list of all attribute defined parsers that should be active for the given `source_data`.
+          def active_attrs(source_data, phase = :any, process: :parse)
+            defined_attrs.select do |attr|
+              if process == :serialize
+                @parsers[attr].serializer_active?(phase)
+              else
+                @parsers[attr].parser_active?(source_data, phase)
+              end
+            end
           end
 
           # Returns a list of all the internal attributes of the model that do **not** have a parser defined.
@@ -112,6 +132,9 @@ module Eco
           def defined?(attr)
             @parsers.key?(attr)
           end
+          # @!endgroup
+
+          # @!group Defining attributes
 
           # Helper to **merge** a set of parsers of another `PersonParser` into the current object.
           # @note if there are parsers with same name, it **overrides** the ones of the current object with them.
@@ -120,12 +143,11 @@ module Eco
           def merge(parser)
             return self if !parser
             raise "Expected a PersonParser object. Given #{parser}" if !parser.is_a?(PersonParser)
-            @parsers.merge!(parser.hash)
+            to_h.merge!(parser.to_h)
             patched!
             self
           end
 
-
           # Helper to define and associate a parser/serializer to a type or attribute.
           # @raise [Exception] if trying to define a parser/serializer for:
           #   - an unkown attribute (`String`)
@@ -136,7 +158,7 @@ module Eco
           # @yieldparam parser [Eco::Language::Models::ParserSerializer] parser to define.
           # @return [Eco::API::Common::People::PersonParser] the current object (to ease chainig).
           def define_attribute(attr, dependencies: {}, &definition)
-            if !valid?(attr)
+            unless valid?(attr)
               msg = "The attribute '#{attr_to_str(attr)}' is not part of core, account or target schema, or does not match any type: #{@details_attrs}"
               raise msg
             end
@@ -147,6 +169,9 @@ module Eco
             patched!
             self
           end
+          # @!endgroup
+
+          # @!group Launching parser/serializer
 
           # Call to parser `source` value of attribute or type `attr` into an internal valid value.
           # @note dependencies introduced on `parse` call will be merged with those defined during the
@@ -154,11 +179,13 @@ module Eco
           # @raise [Exception] if there is **no** parser for attribute or type `attr`.
           # @param attr [String] target attribute or type to **parse**.
           # @param source [Any] source value to be parsed.
+          # @param phase [Symbol] the phase when the attr parser is expected to be called.
+          #   Must be [:internal, :final]
           # @param deps [Hash] key-value pairs of call dependencies.
           # @return [Any] a valid internal value.
-          def parse(attr, source, deps: {})
+          def parse(attr, source, phase = :internal, deps: {})
             raise "There is no parser for attribute '#{attr}'" if !self.defined?(attr)
-            @parsers[attr].parse(source, dependencies: deps)
+            @parsers[attr].parse(source, phase, dependencies: deps)
           end
 
           # Call to serialise `object` value of attribute or type `attr` into an external valid value.
@@ -167,26 +194,32 @@ module Eco
           # @raise [Exception] if there is **no** serialiser for attribute or type `attr`.
           # @param attr [String] target attribute or type to **serialize**.
           # @param object [Any] object value to be serialized.
+          # @param phase [Symbol] the phase when the attr serializer is expected to be called.
+          #   Must be [:internal, :final, :person]
           # @param deps [Hash] key-value pairs of call dependencies.
           # @return a valid external value.
-          def serialize(attr, object, deps: {})
+          def serialize(attr, object, phase = :person, deps: {})
             raise "There is no parser for attribute '#{attr}'" if !self.defined?(attr)
-            @parsers[attr].serialize(object, dependencies: deps)
+            @parsers[attr].serialize(object, phase, dependencies: deps)
           end
+          # @!endgroup
 
           protected
 
           # @return [Hash] attr-parser pairs with all the defined type and attribute parsers/serializers.
-          def hash
+          def to_h
+            self.class.autoload_children(self)
             @parsers
           end
 
           private
 
+          # Some attribute parsers are **inactive**, and therefore out of scope
+          # @param source_attrs [Array<String>] the attrs we want to filter from to only those in scope.
+          # @param section_attrs [Array<String>] the attrs of reference to scope `source_attrs`.
+          # @return [Array<String>] the `source_attrs` in `section_attrs` + the `section_attrs` with active parser
           def scoped_attrs(source_attrs, section_attrs)
-            direct_attrs = source_attrs & section_attrs
-            parsed_attrs = active_attrs(source_attrs) & section_attrs
-            (source_attrs + parsed_attrs) & (direct_attrs + parsed_attrs)
+            (source_attrs | active_attrs(source_attrs)) & section_attrs
           end
 
           def attr_to_str(attr)

data/lib/eco/api/common/session/logger.rb

@@ -28,6 +28,10 @@ module Eco
             end
           end
 
+          def level=(value)
+            @console_logger.level = value
+          end
+
           def debug(*args, &block)
             log(:debug, *args, &block)
           end

data/lib/eco/api/common/version_patches.rb

@@ -7,6 +7,7 @@ module Eco
   end
 end
 
+require_relative 'version_patches/object'
 require_relative 'version_patches/exception'
 require_relative 'version_patches/hash'
 require_relative 'version_patches/ecoportal_api'

data/lib/eco/api/common/version_patches/ecoportal_api/external_person.rb

@@ -1,7 +1,9 @@
 module Ecoportal
   module API
     class V1
+      # @attr entry [Eco::API::Common::People::PersonEntry, Hash] the input entry plain hash data used to update/create this person.
       class Person
+        attr_accessor :entry
 
         def reset_details!
           doc["details"] = JSON.parse(original_doc["details"])

data/lib/eco/api/common/version_patches/ecoportal_api/internal_person.rb

@@ -16,7 +16,7 @@ module Ecoportal
         end
 
         def account_added?
-          person.account && !initial_doc["account"]
+          account && !initial_doc["account"]
         end
 
       end

data/lib/eco/api/common/version_patches/exception.rb

@@ -6,3 +6,25 @@ class ::Exception
     msg.join("\n")
   end
 end
+
+# To extend an exception message preserving same exception object
+# @see https://stackoverflow.com/a/30133010/4352306
+Exception.class_eval do
+  def prepend_message(message)
+    mod = Module.new do
+      define_method :to_s do
+        String(message) + super()
+      end
+    end
+    self.extend mod
+  end
+
+  def append_message(message)
+    mod = Module.new do
+      define_method :to_s do
+        super() + String(message)
+      end
+    end
+    self.extend mod
+  end
+end

data/lib/eco/api/common/version_patches/object.rb

@@ -0,0 +1,10 @@
+Object.class_eval do
+  unless method_defined?(:yield_self)
+    define_method(:yield_self) do |&block|
+      return block.call(self) if block
+      out = self
+      out = [self] unless self.is_a?(Enumerable)
+      out.each
+    end
+  end
+end

data/lib/eco/api/custom.rb

@@ -0,0 +1,13 @@
+module Eco
+  module API
+    # Set of helper classes to boost configuration easiness
+    module Custom
+    end
+  end
+end
+
+require_relative 'custom/namespace'
+require_relative 'custom/use_case'
+require_relative 'custom/policy'
+require_relative 'custom/error_handler'
+require_relative 'custom/parser'

data/lib/eco/api/custom/error_handler.rb

@@ -0,0 +1,20 @@
+# Helper class to create a custom `ErrorHandler`
+# @example Example of usage:
+#  class Custom::ErrorHandler::EmailTaken < Eco::API::Custom::ErrorHandler
+#    error Eco::API::Error::EmailTaken
+#
+#    def main(people, session, options, handler, job)
+#      people.each do |person|
+#        prev_email = person.initial_doc["email"]
+#        if person.email != prev_email
+#          person.email = prev_email
+#        else
+#          person.account = nil
+#        end
+#        job.add(person)
+#      end
+#    end
+#  end
+#
+class Eco::API::Custom::ErrorHandler < Eco::API::Common::Loaders::ErrorHandler
+end

data/lib/eco/api/custom/namespace.rb

@@ -0,0 +1,7 @@
+# Provides a namespace to declare custom policies, usecases and handlers
+module Custom
+  module UseCase; end
+  module Policy; end
+  module ErrorHandler; end
+  module Parser; end
+end

data/lib/eco/api/custom/parser.rb

@@ -0,0 +1,50 @@
+# Helper class to create a custom `Parser`
+# @example Example of usage:
+#  class Custom::Parser::LoginProviders < Eco::API::Custom::Parser
+#    attribute "login_provider_ids"
+#
+#    active_when_any "some-field1", "some-field2" # optional
+#    parsing_phase     :final # optional, default is  (default :internal)
+#    serializing_phase :final # optional, it will be    (default :person)
+#
+#    def parser(hash, deps)
+#      get_values(hash).map do |name|
+#        login_providers.to_id(name&.downcase.strip)
+#      end.compact
+#    end
+#
+#    def serializer(hash, deps)
+#      if ids = hash["login_provider_ids"]
+#        login_providers.to_name(ids)
+#      else
+#        []
+#      end
+#    end
+#
+#    private
+#
+#    def get_values(hash)
+#      value, field1, field2 = hash.values_at("login_provider_ids", "some-field1", "some-field2")
+#      return value if value # at the :final parsing phase, login_provider_ids is already an Array
+#      some_logics(field1, field2)
+#    end
+#
+#    def some_logics(a, b)
+#      case a
+#      when "staff"
+#        ["Company SSO"]
+#      when "contractor"
+#        ["Password"]
+#      elsif b
+#        return ["Password"] if b.end_with?("Owner")
+#        ["Password", "Company SSO 2"]
+#      end
+#    end
+#
+#    def login_providers
+#      @login_providers ||= ASSETS.config.login_providers
+#    end
+#
+#  end
+class Eco::API::Custom::Parser < Eco::API::Common::Loaders::Parser
+end

data/lib/eco/api/custom/policy.rb

@@ -0,0 +1,28 @@
+# Helper class to create a custom `Policy`
+# @example Example of usage:
+#  class Custom::Policy::StartersNLeavers < Eco::API::Custom::Policy
+#    name "starters'n'leavers"
+#
+#    INACTIVE = "Non active"
+#
+#    def main(people, session, options, policy, job)
+#      people.each do |person|
+#        next unless details = person.details
+#        # starters
+#        if person.new?
+#          details["status"]       = "Active"
+#          details["hris-managed"] = true unless options.dig(:include, :excluded)
+#        end
+#
+#        # leavers: native job queue to remove account
+#        if job.name == "leavers"
+#          details["status"]    = INACTIVE
+#          person.external_id   = person.name
+#          details["staff-id"]  = person.name
+#        end
+#      end
+#    end
+#
+#  end
+class Eco::API::Custom::Policy < Eco::API::Common::Loaders::Policy
+end

data/lib/eco/api/custom/use_case.rb

@@ -0,0 +1,16 @@
+# Helper class to create a custom `UseCase`
+# @example Example of usage:
+#  class Custom::UseCase::Sync < Eco::API::Custom::UseCase
+#    name "custom-case"
+#    type :sync
+#
+#    def main(entries, people, session, options, usecase)
+#      update   = session.new_job("main", "update", :update, usecase)
+#      session.micro.with_each(entries, people, options) do |entry, person|
+#        # update some data in person using data from entry
+#      end
+#    end
+#
+#  end
+class Eco::API::Custom::UseCase < Eco::API::Common::Loaders::UseCase
+end

data/lib/eco/api/error.rb

@@ -13,6 +13,7 @@ module Eco
       @match  = /.*/
       #RxValidId = /[a-f0-9]{24}/
 
+
       class Unclassified < Eco::API::Error
         @str_error = "Unclassified error message"
         @match     = /.*/

data/lib/eco/api/error/handlers.rb

@@ -2,12 +2,14 @@ module Eco
   module API
     class Error
       class Handlers < Eco::API::UseCases
+        autoloads_children_of "Eco::API::Common::Loaders::ErrorHandler"
+        autoload_namespace_ignore "Eco::API"
 
-        def add(handler)
-          raise "Expected Eco::API::Error::Handler object. Given: #{policy}" unless handler.is_a?(Eco::API::Error::Handler)
-          super(handler)
+        def define(*args)
+          raise "Missusage. You should use 'on' method instead"
         end
 
+        # @param klass_err [Eco::API::Error] the specific error class that triggers this handler.
         def on(klass_err, type: :error_handler, retry: true, &block)
           Eco::API::Error.validate_err_class(klass_err)
           raise "Expected block but not given" unless block
@@ -16,6 +18,11 @@ module Eco
           end
         end
 
+        def add(handler)
+          raise "Expected Eco::API::Error::Handler object. Given: #{policy}" unless handler.is_a?(Eco::API::Error::Handler)
+          super(handler)
+        end
+
       end
     end
   end