eco-helpers 3.0.21 → 3.0.22

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a7764e6e3e78228f59b9a5f5baf2aa8602c627882905a23270007b4fe1a09c9f
-  data.tar.gz: aca94b571b1c70c000e0d88f09182f2339a306187c5f9651968e9692981d79d9
+  metadata.gz: c24fea5e80af03052ddec1ce701651a61e7575d812161ff4f62f8f70c29da1d1
+  data.tar.gz: 2c72186bf780afd1b706eb0fbf44669cd68ac1239e0ba95f923462190a08d85d
 SHA512:
-  metadata.gz: bcef313643bc67ba9d90755e3ce8a3a3a39c1973404b2dcd35292b76c67d158ad3e9c666414e2f6254776eeb800f4d07fc2ab10953a15e9e2b293d2b8f15303e
-  data.tar.gz: 3d12155562df35e9ecadea021a758f922f35ab68d689592e4a319e41232b4865a87e22c0e333b1083e42340418f57388f24139748246d08652142ef52f1a041d
+  metadata.gz: 4bf253ab9cc07090b25ffcec1ff853422e292ce4fe1dcddab026bead5ef48d5a4710d55f79b4a16477c6671d764296938374c6f18521e27ac808529eb1435fa7
+  data.tar.gz: 28da9eaed628e6e37c22b5dc3c703867c9941eac6ea2d364142823ffa3e00e86ed54d45648b75231b4e93f86aff666f5a69892cc9255260af4c2c6953b6483bd

data/.idea/.gitignore

@@ -0,0 +1,10 @@
+# Default ignored files
+/shelf/
+/workspace.xml
+# Editor-based HTTP Client requests
+/httpRequests/
+# Datasource local storage ignored files
+/dataSources/
+/dataSources.local.xml
+# jetbrains IDE
+.idea

data/CHANGELOG.md

@@ -2,6 +2,40 @@
 
 All notable changes to this project will be documented in this file.
 
+## [3.0.22] - 2024-12-xx
+
+### Added
+
+- `Eco::Data::Mapper`
+  - Ability to pair in lower case
+  - `#internal?` and `#external?` would evaluate `true` for a lower case check.
+- `:model` named argument to use cases
+  - To diversify use cases
+- `Contractors` namespace (skeleton) onto `Eco::API::UseCases::GraphQL` within:
+  - `Helpers`
+  - `Samples`
+- Decoupled `Eco::API::Session::Batch::Feedback` into mulitple **modules**
+- Moved `Eco::API::Session::Batch::RequestStats` to be
+  - `Eco::API::Session::Batch::Feedback::RequestStats`
+
+### Changed
+
+- Moved `Cli` class methods out of `Eco::API::Common::Loaders::UseCase` (to `CliIdentify`)
+- Moved `Eco::API::Organization::PeopleSimilarity` to `Eco::API::Organization::People::Similarity`
+- **IMPORTANT** refactor to base UseCase and IO related classes on `data` (rather than `people`).
+  - This change aims for re-usability of existing use case logic.
+  - The changes have had impact on the workflow definitions.
+  - There is a **todo** list in the default_cli workflow implementation.
+- **Refactor** of `MicroCases` to be based on data model.
+- Upgrade dependencies:
+  - `ecoportal-api` gem upgrade.
+  - `ecoportal-api-v2` gem upgrade.
+  - `ecoportal-api-graphql` gem upgrade.
+
+### Fixed
+
+- Workflow should raise exception when referring to an unknown stage
+
 ## [3.0.21] - 2024-12-16
 
 ### Added
@@ -180,8 +214,6 @@ All notable changes to this project will be documented in this file.
 
 ## [3.0.6] - 2024-08-26
 
-### Added
-
 ### Changed
 
 - `Eco::API::Microcases#people_search`

data/eco-helpers.gemspec

@@ -40,9 +40,9 @@ Gem::Specification.new do |spec|
   spec.add_dependency 'bcrypt_pbkdf',  '~> 1.0'
   spec.add_dependency 'docx',          '>= 0.8.0', '< 0.9'
   spec.add_dependency 'dotenv',        '~> 3'
-  spec.add_dependency 'ecoportal-api',         '~> 0.10', '>= 0.10.7'
-  spec.add_dependency 'ecoportal-api-graphql', '~> 0.4',  '>= 0.4.3'
-  spec.add_dependency 'ecoportal-api-v2',      '~> 2.0',  '>= 2.0.12'
+  spec.add_dependency 'ecoportal-api',         '~> 0.10', '>= 0.10.8'
+  spec.add_dependency 'ecoportal-api-graphql', '~> 0.4',  '>= 0.4.4'
+  spec.add_dependency 'ecoportal-api-v2',      '~> 2.0',  '>= 2.0.15'
   spec.add_dependency 'ed25519',       '~> 1.2'
   spec.add_dependency 'fast_excel',    '>= 0.5.0',  '< 0.6'
   spec.add_dependency 'fuzzy_match',   '>= 2.1.0',  '< 2.2'

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

@@ -15,7 +15,7 @@ module Eco
 
         # @return [Array<String>] the `keys` of the current class' `model`
         def model_attrs
-          (model && model.keys) || []
+          model&.keys || []
         end
 
         # Thanks to this step the format on the declaration of the model is flexible
@@ -24,24 +24,21 @@ module Eco
         def parse_model(model)
           case model
           when String
-            return parse_model(model.to_sym)
+            parse_model(model.to_sym)
           when Symbol
-            return {model => nil}
+            {model => nil}
           when Hash
-            return model.each_with_object({}) do |(k,v), hash|
-              hash[k.to_sym] = v
-            end
+            model.transform_keys(&:to_sym)
           when Enumerable
-            return model.each_with_object({}) do |sub, hash|
+            model.each_with_object({}) do |sub, hash|
               hash.merge!(parse_model(sub))
             end
           when NilClass
-            return nil
+            nil
           else
             raise "Incorrect model declaration, allowed String, Symbol, Hash and Enumerable. Given: #{model.class}"
           end
         end
-
       end
     end
   end

data/lib/eco/api/common/loaders/case_base.rb

@@ -6,17 +6,25 @@ module Eco
           class << self
             attr_writer :name, :type
 
+            alias_method :original_name, :name
+
             # The name that this case, policy or error handler will have.
             def name(value = nil)
-              name_only_once! if value
-              set_created_at!
-              return @name ||= to_s unless value
+              name_only_once!      if value
+              set_created_at!      unless @name
+              return original_name unless @name || value
+              return @name         unless value
+
               @name = value
             end
 
             # Prevent the same class to be re-opened/re-named
             def name_only_once!
-              raise "You have already declared #{self} or you are trying to give it a name twice" if @name
+              return unless @name
+
+              msg  = "You have already declared #{self} "
+              msg << "or you are trying to give it a name twice"
+              raise msg if @name
             end
           end
 

data/lib/eco/api/common/loaders/config/workflow/cases_extension.rb

@@ -0,0 +1,53 @@
+class Eco::API::Common::Loaders::Workflow
+  module CasesExtension
+    private
+
+    def cli_usecases
+      cli.config.usecases
+    end
+
+    def cli_active_cases(io)
+      cli_usecases.active(io: io)
+    end
+
+    def cli_update_cases(io)
+      cli_active_cases(io).select do |usecase, _data|
+        %i[transform sync].any? { |type| usecase.type == type }
+      end
+    end
+
+    def cli_other_cases(io)
+      cli_active_cases(io).select do |usecase, _data|
+        %i[other].any? { |type| usecase.type == type }
+      end
+    end
+
+    def cli_input_cases(io)
+      cli_active_cases(io).select do |usecase, _data|
+        io.class.input_required?(usecase.type)
+      end
+    end
+
+    def cli_data_cases(io)
+      cli_active_cases(io).select do |usecase, _data|
+        io.class.data_required?(usecase.type)
+      end
+    end
+
+    def some_update_case?(io)
+      cli_update_cases(io).any?
+    end
+
+    def some_other_case?(io)
+      cli_other_cases(io).any?
+    end
+
+    def some_input_case?(io)
+      cli_input_cases(io).any?
+    end
+
+    def some_data_case?(io)
+      cli_data_cases(io).any?
+    end
+  end
+end

data/lib/eco/api/common/loaders/config/workflow/mailer.rb

@@ -19,7 +19,7 @@ class Eco::API::Common::Loaders::Workflow::Mailer < Eco::API::Common::Loaders::W
       next unless session.config.run_mode_remote?
 
       # temporary contingency: maybe_error_or_tree_updates?
-      next unless some_update?(io) || maybe_error_pages_or_tree_updates?(io)
+      next unless some_update_case?(io) || maybe_error_pages_or_tree_updates?(io)
 
       subject = base_subject
 
@@ -57,25 +57,13 @@ class Eco::API::Common::Loaders::Workflow::Mailer < Eco::API::Common::Loaders::W
       "#{active_enviro}#{space_desc}"
     end
 
-    def some_update?(io)
-      cli.config.usecases.active(io: io).any? do |usecase, _data|
-        %i[transform sync].any? { |type| usecase.type == type }
-      end
-    end
-
-    def other_case?(io)
-      cli.config.usecases.active(io: io).any? do |usecase, _data|
-        %i[other].any? { |type| usecase.type == type }
-      end
-    end
-
     def error?
       !!error
     end
 
     # @note at some stage, tree cases should have their own case type
     def maybe_error_pages_or_tree_updates?(io)
-      other_case?(io) && error?
+      some_other_case?(io) && error?
     end
 
     def errors_n_warnings(io)

data/lib/eco/api/common/loaders/config/workflow.rb

@@ -1,10 +1,14 @@
 class Eco::API::Common::Loaders::Workflow < Eco::API::Common::Loaders::Config
+  require_relative 'workflow/cases_extension'
+
   class << self
     def workflow
       config.workflow
     end
   end
 
+  extend CasesExtension
+
   delegate_missing_to :workflow
 end
 

data/lib/eco/api/common/loaders/error_handler.rb

@@ -25,12 +25,13 @@ module Eco
             handlers.on(error, &method(:main))
           end
 
-          # @param people [Eco::API::Organization::People] the people in the queue of the current `job`
+          # @param data [Variant]
+          #   - people [Eco::API::Organization::People] the people in the queue of the current `job`
           # @param session [Eco::API::Session] the current session where the usecase kicks in.
           # @param options [Hash] the options that modify the case behaviour or bring some dependencies.
           # @param handler [Eco::API::Error::Hanlder] the `error handler` instance object.
           # @param job [Eco::API::Session::Batch::Job] the `Batch::Job` made on purpose for this handler.
-          def main(people, session, options, handler, job) # rubocop:disable Lint/UnusedMethodArgument
+          def main(data, session, options, handler, job) # rubocop:disable Lint/UnusedMethodArgument
             raise "You should implement this method"
           end
 

data/lib/eco/api/common/loaders/policy.rb

@@ -10,12 +10,13 @@ module Eco
             policies.define(name, &method(:main))
           end
 
-          # @param people [Eco::API::Organization::People] the people in the queue of the current `job`
+          # @param data [Variant]
+          #   - people [Eco::API::Organization::People] the people in the queue of the current `job`
           # @param session [Eco::API::Session] the current session where the usecase kicks in.
           # @param options [Hash] the options that modify the case behaviour or bring some dependencies.
           # @param policy [Eco::API::Policies::Policy] the `policy` instance object.
           # @param job [Eco::API::Session::Batch::Job] the `Batch::Job` that these `people` belong to the queue thereof.
-          def main(people, session, options, policy, job) # rubocop:disable Lint/UnusedMethodArgument
+          def main(data, session, options, policy, job = nil) # rubocop:disable Lint/UnusedMethodArgument
             raise "You should implement this method"
           end
         end

data/lib/eco/api/common/loaders/use_case/cli_identify.rb

@@ -0,0 +1,28 @@
+class Eco::API::Common::Loaders::UseCase
+  module CliIdentify
+    def cli!
+      cli&.apply!
+    end
+
+    def cli(cli_class = nil)
+      if cli_class.is_a?(Class)
+        msg = 'cli_class should inherit from Eco::API::UseCases::Cli'
+        raise ArgumentError, msg unless cli_class < Eco::API::UseCases::Cli
+
+        @cli = cli_class
+      elsif cli_class.nil?
+        return @cli if instance_variable_defined?(:@cli) && !@cli.nil?
+
+        # try to see if it's namespaced after the use case it provisions cli integration
+        begin
+          try_class = [to_s, 'Cli'].join('::')
+          @cli = Kernel.const_get(try_class)
+        rescue NameError
+          nil
+        end
+      else
+        raise ArgumentError, "Expecting a class. Given: #{cli_class.class} object"
+      end
+    end
+  end
+end

data/lib/eco/api/common/loaders/use_case/target_model.rb

@@ -0,0 +1,25 @@
+class Eco::API::Common::Loaders::UseCase
+  module TargetModel
+    class << self
+      def included(base)
+        super
+
+        base.extend(ClassMethods)
+      end
+    end
+
+    module ClassMethods
+      #@note it inherently defaults to `:people` (out of backwards compatibility)
+      # @return [String] the `target_model`
+      def target_model(value = nil)
+        return @target_model = value if value
+
+        @target_model                if @target_model
+      end
+    end
+
+    def target_model
+      self.class.target_model
+    end
+  end
+end

data/lib/eco/api/common/loaders/use_case/type.rb

@@ -0,0 +1,37 @@
+class Eco::API::Common::Loaders::UseCase
+  module Type
+    class << self
+      def included(base)
+        super
+
+        base.extend(ClassMethods)
+      end
+    end
+
+    module ClassMethods
+      # @return [Symbol] the `type` of usecase (i.e. `:sync`, `:transform`, `:import`, `:other`)
+      def type(value = nil)
+        return @type = value if value
+        return @type         if @type
+
+        types_sym_str = available_types.map do |tp|
+          ":#{tp}"
+        end.join(', ')
+
+        msg  = "You should specify a type of case "
+        msg << "[#{types_sym_str}] for #{self}"
+        raise msg
+      end
+
+      private
+
+      def available_types
+        Eco::API::UseCases::BaseCase.types
+      end
+    end
+
+    def type
+      self.class.type
+    end
+  end
+end

data/lib/eco/api/common/loaders/use_case.rb

@@ -3,66 +3,39 @@ module Eco
     module Common
       module Loaders
         class UseCase < Eco::API::Common::Loaders::CaseBase
-          class << self
-            # @return [Symbol] the `type` of usecase (i.e. `:sync`, `:transform`, `:import`, `:other`)
-            def type(value = nil)
-              unless value
-                msg  = "You should specify a type of case "
-                msg << "[:sync, :transform, :import, :other] for #{self}"
-                return @type || (raise msg)
-              end
-              @type = value
-            end
+          require_relative 'use_case/type'
+          require_relative 'use_case/target_model'
+          require_relative 'use_case/cli_identify'
 
-            def cli!
-              cli&.apply!
-            end
+          include Type
+          include TargetModel
+          extend CliIdentify
 
-            def cli(cli_class = nil)
-              if cli_class.is_a?(Class)
-                msg = "cli_class should inherit from Eco::API::UseCases::Cli"
-                raise ArgumentError, msg unless cli_class < Eco::API::UseCases::Cli
-
-                @cli = cli_class
-              elsif cli_class.nil?
-                return @cli if instance_variable_defined?(:@cli) && !@cli.nil?
-
-                # try to see if it's namespaced after the use case it provisions cli integration
-                begin
-                  try_class = [to_s, 'Cli'].join('::')
-                  @cli = Kernel.const_get(try_class)
-                rescue NameError
-                  nil
-                end
-              else
-                raise ArgumentError, "Expecting a class. Given: #{cli_class.class} object"
-              end
-            end
-          end
-
-          inheritable_class_vars :type, :cli
+          inheritable_class_vars :cli, :type, :target_model
 
           def initialize(usecases) # rubocop:disable Lint/MissingSuper
             msg = "Expected Eco::API::UseCases. Given #{usecases.class}"
             raise msg unless usecases.is_a?(Eco::API::UseCases)
 
-            usecases.define(name, type: type, &method(:main))
+            usecases.define(
+              name,
+              type:  type,
+              model: target_model,
+              &method(:main)
+            )
           end
 
           # The parameters of this method will depend on the `type` of usecase.
           # @param entries [Eco::API::Common::People::Entries] the input entries with the data.
-          # @param people [Eco::API::Organization::People] the people in the queue of the current `job`
+          # @param data [Variant]
+          #   - people [Eco::API::Organization::People] the people in the queue of the current `job`
           # @param session [Eco::API::Session] the current session where the usecase kicks in.
           # @param options [Hash] the options that modify the case behaviour or bring some dependencies.
           # @param usecase [Eco::API::Policies::Policy] the `usecase` instance object.
-          def main(entries, people, session, options, usecase) # rubocop:disable Lint/UnusedMethodArgument
+          def main(*_args)
             raise "You should implement this method"
           end
 
-          def type
-            self.class.type
-          end
-
           def cli_apply!
             self.class.cli!
           end

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

@@ -2,17 +2,19 @@ module Eco
   module API
     class Error
       class Handler < Eco::API::UseCases::UseCase
-        @types = [:error_handler]
+        TYPES = [:error_handler].freeze
 
         def initialize(name, type: :error_handler, root:, &block)
-          super(name, type: type, root: root, &block)
+          super
         end
 
         def root=(value)
-          raise "Root should be a Eco::API::Error::Handlers object. Given: #{value}" if !value.is_a?(Eco::API::Error::Handlers)
+          msg = "Root should be a Eco::API::Error::Handlers object. "
+          msg << "Given: #{value.class}"
+          raise ArgumentError, msg unless value.is_a?(Eco::API::Error::Handlers)
+
           @root = value
         end
-
       end
     end
   end

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

@@ -5,7 +5,7 @@ module Eco
         autoloads_children_of "Eco::API::Common::Loaders::ErrorHandler"
         autoload_namespace_ignore "Eco::API"
 
-        def define(*args)
+        def define(*_args)
           raise "Missusage. You should use 'on' method instead"
         end
 
@@ -13,16 +13,23 @@ module Eco
         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
-          Eco::API::Error::Handler.new(klass_err, type: type, root: self, &block).tap do |handler|
+
+          Eco::API::Error::Handler.new(
+            klass_err,
+            type: type,
+            root: self,
+            &block
+          ).tap do |handler|
             add(handler)
           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
+          msg = "Expected Eco::API::Error::Handler object. Given: #{handler.class}"
+          raise ArgumentError, msg unless handler.is_a?(Eco::API::Error::Handler)
 
+          super
+        end
       end
     end
   end

data/lib/eco/api/microcases/people/apply_changes/set_account/account_excluded.rb

@@ -0,0 +1,34 @@
+module Eco
+  module API
+    class MicroCases
+      module People
+        module ApplyChanges
+          module SetAccount
+            module AccountExcluded
+              # @param person [Ecoportal::API::V1::Person] the person we want to update, carrying the changes to be done.
+              # @param options [Hash] the options.
+              # @return [Array<String>] the account parameters that should not be included.
+              def account_excluded(person, options)
+                [].tap do |account_excluded|
+                  next if person.new?
+
+                  if options.dig(:exclude, :policy_groups)
+                    account_excluded.push('policy_group_ids')
+                  end
+
+                  if options.dig(:exclude, :default_tag)
+                    account_excluded.push('default_tag')
+                  end
+
+                  if options.dig(:exclude, :login_providers)
+                    account_excluded.push('login_provider_ids')
+                  end
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/apply_changes/set_account.rb

@@ -0,0 +1,28 @@
+require_relative 'set_account/account_excluded'
+
+module Eco
+  module API
+    class MicroCases
+      module People
+        module ApplyChanges
+          module SetAccount
+            include AccountExcluded
+
+            # @param entry [PersonEntry] the input entry with the data we should set on person.
+            # @param person [Ecoportal::API::V1::Person] the person we want to update, carrying the changes to be done.
+            # @param options [Hash] the options.
+            def set_account(entry, person, options)
+              return if options.dig(:exclude, :account)
+
+              entry.set_account(person, exclude: micro.account_excluded(person, options))
+
+              person.account.send_invites = options[:send_invites] if options.key?(:send_invites)
+              micro.refresh_default_tag(entry, person, options)
+              micro.fix_default_group(entry, person, options)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/apply_changes/set_core/core_excluded.rb

@@ -0,0 +1,28 @@
+module Eco
+  module API
+    class MicroCases
+      module People
+        module ApplyChanges
+          module SetCore
+            module CoreExcluded
+              # @note by default `supervisor_id` is always excluded.
+              # @param person [Ecoportal::API::V1::Person] the person we want to update, carrying the changes to be done.
+              # @param options [Hash] the options.
+              # @return [Array<String>] the core parameters that should not be included.
+              def core_excluded(person, options)
+                ['supervisor_id'].tap do |core_excluded|
+                  can_exclude = person.new?? ['filter_tags'] : %w[name external_id email filter_tags]
+
+                  exclusions  = can_exclude.select do |attr|
+                    options.dig(:exclude, attr.to_sym)
+                  end
+                  core_excluded.concat(exclusions)
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/apply_changes/set_core.rb

@@ -0,0 +1,27 @@
+require_relative 'set_core/core_excluded'
+
+module Eco
+  module API
+    class MicroCases
+      module People
+        module ApplyChanges
+          module SetCore
+            include CoreExcluded
+
+            # Sets all the core details, but the supervisor.
+            # @note `supervisor_id` requires a special treatment, and therefore is always excluded.
+            # @param entry [PersonEntry] the input entry with the data we should set on person.
+            # @param person [Ecoportal::API::V1::Person] the person we want to update, carrying the changes to be done.
+            # @param options [Hash] the options
+            def set_core(entry, person, options)
+              return if options.dig(:exclude, :core) && !person.new?
+
+              entry.set_core(person, exclude: micro.core_excluded(person, options))
+              micro.fix_filter_tags(person, options)
+            end
+          end
+        end
+      end
+    end
+  end
+end