eco-helpers 1.4.0 → 1.5.2

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.
@@ -72,6 +73,8 @@ module Eco
           # @param value [String, Array<String>] value(s) to be translated into internal names.
           # @return [String, nil, Array<String] the internal name(s) of `value`.
           def to_internal(value)
+            # TODO: check PersonEntry#to_internal and #to_external in init_attr_trackers
+            # => when attr_map is avoided, it doesn't work as it should
             return value if !@attr_map
             attr = value
             case value

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

@@ -9,7 +9,11 @@ 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
-          CORE_ATTRS    = ["id", "external_id", "email", "name", "supervisor_id", "filter_tags"]
+          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]
           FORMAT        = [:csv, :xml, :json]
@@ -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/base_session.rb

@@ -3,9 +3,6 @@ module Eco
     module Common
       module Session
         class BaseSession
-
-          include Common::People
-
           attr_accessor :session
           attr_accessor :environment, :config
           alias_method :enviro, :environment
@@ -32,8 +29,8 @@ module Eco
             enviro.config
           end
 
-          def api
-            enviro.api
+          def api(version: nil)
+            enviro.api(version: version)
           end
 
           def file_manager
@@ -47,7 +44,7 @@ module Eco
           def mailer?
             enviro.mailer?
           end
-          
+
           def sftp
             enviro.sftp
           end

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

@@ -3,11 +3,7 @@ module Eco
     module Common
       module Session
         class Environment
-
-          include Common::People
-
           attr_reader :config, :session
-          attr_reader :api #, :host, :version
           attr_reader :file_manager, :logger
           attr_reader :mailer, :sftp, :s3uploader
 
@@ -57,25 +53,8 @@ module Eco
             config.s3storage.configured?
           end
 
-          def api
-            @api || new_api
-          end
-
-          def new_api
-            return nil unless config.apis.active_api
-
-            log_connection = config.logger.log_connection?
-            logg = log_connection ? logger : ::Logger.new(IO::NULL)
-
-            api = config.api(logg)
-
-            unless log_connection
-              logger.info("Created connection pointing to '#{config.apis.active_api.host}' in '#{config.apis.active_api.mode}' mode")
-              api.logger.level = ::Logger::UNKNOWN
-            end
-
-            @api = api
-            api
+          def api(version: nil)
+            config.api(logger, version: version)
           end
 
         end

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/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

@@ -2,7 +2,7 @@ module Ecoportal
   module API
     class Internal
       class Person
-        
+
         def reset_account!
           doc["account"] = JSON.parse(original_doc["account"])
         end
@@ -11,6 +11,14 @@ module Ecoportal
           original_doc["account"] = JSON.parse(doc["account"])
         end
 
+        def new?
+          !initial_doc["details"] && !initial_doc["account"]
+        end
+
+        def account_added?
+          account && !initial_doc["account"]
+        end
+
       end
     end
   end

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

@@ -1,8 +1,30 @@
 class ::Exception
   def patch_full_message
     msg = []
-    msg << "#{backtrace.shift} #{message} (#{self.class.to_s})"
-    backtrace.each {|bt| msg << "#{" "*8}from #{bt}"}
+    msg << "\n#{backtrace.first} \n#{message} (#{self.class.to_s})"
+    backtrace[1..-1].each_with_index {|bt, i| msg << "#{" "*8}#{i+1}: from #{bt}"}
     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/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