eco-helpers 1.5.1 → 1.5.6

data/lib/eco/api/session/batch/status.rb

@@ -30,7 +30,7 @@ module Eco
           # @param e [Eco::API::Common::Session::Environment] requires a session environment, as any child of `Eco::API::Common::Session::BaseSession`
           # @param queue  [Array<Hash>, Array<Ecoportal::API::V1::Person>, Array<Ecoportal::API::Internal::Person>] the `source_queue`
           # @param method [Symbol] the type of `batch operation`
-          # @param mode [Symbol] the mode of `batch operation` (search)
+          # @param mode [Symbol] the mode of `batch operation`. It can be `:search` or `:exact`
           def initialize(e, queue:, method:, mode: :exact)
             super(e)
             fatal("In batch operations you must batch an Enumerable. Received: #{queue}")  unless queue && queue.is_a?(Enumerable)
@@ -96,6 +96,39 @@ module Eco
             @responses[to_index(key)] = response
           end
 
+          # Has the _entry_ `key` been queried to the server?
+          # @param key [Integer, Hash, Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person]
+          # @return [Boolean] `true` if input entry `key` has an associated `Ecoportal::API::Common::BatchResponse`
+          def received?(key)
+            !!self[key]
+          end
+
+          # Has the _entry_ `key` 's query to the server been successful
+          # @param key [Integer, Hash, Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person]
+          # @return [Boolean] `true` if input entry `key` has not had a server Error during the query
+          def success?(key)
+            self[key]&.success?
+          end
+
+          # Helper to transform any `key` to an `Integer` index
+          # @param key [Integer, Hash, Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person]
+          # @return [Integer] the index that `key` has in the final `queue`
+          def to_index(key)
+            key.is_a?(Integer) ? valid_index(index: key) : valid_index(entry: key)
+          end
+
+          # _Index_ validator to make this object reliable
+          # @return [Integer] the actual `index`
+          def valid_index(index: nil, entry: nil)
+            index ||= @hash[entry]
+            unless index && index < @queue.length
+              fatal "You must provide either the index on the final 'queue' or the original entry object of the batch"
+            end
+            index
+          end
+
+          # @!group Get-specific helpers
+
           # The _person_ we got from the Server wrapped to the `Person` object for the input entry object `key`
           # @note it only makes sense when the used batch method was `get`
           # @param key [Integer, Hash, Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person]
@@ -129,20 +162,6 @@ module Eco
             @people_match[to_index(key)] = people
           end
 
-          # Has the _entry_ `key` been queried to the server?
-          # @param key [Integer, Hash, Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person]
-          # @return [Boolean] `true` if input entry `key` has an associated `Ecoportal::API::Common::BatchResponse`
-          def received?(key)
-            !!self[key]
-          end
-
-          # Has the _entry_ `key` 's query to the server been successful
-          # @param key [Integer, Hash, Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person]
-          # @return [Boolean] `true` if input entry `key` has not had a server Error during the query
-          def success?(key)
-            self[key]&.success?
-          end
-
           # When the batch _method_ has been `get`, it gathers into an `Array` the people found.
           # @note here is where the used `mode` gets relevance:
           #   - while `:exact` mode will keep the order of found people as per order of final `queue`
@@ -167,22 +186,7 @@ module Eco
             end
             out
           end
-
-          # Helper to transform any `key` to an `Integer` index
-          # @param key [Integer, Hash, Ecoportal::API::V1::Person, Ecoportal::API::Internal::Person]
-          # @return [Integer] the index that `key` has in the final `queue`
-          def to_index(key)
-            key.is_a?(Integer) ? valid_index(index: key) : valid_index(entry: key)
-          end
-
-          # _Index_ validator to make this object reliable
-          def valid_index(index: nil, entry: nil)
-            index ||= @hash[entry]
-            unless index && index < @queue.length
-              fatal "You must provide either the index on the final 'queue' or the original entry object of the batch"
-            end
-            index
-          end
+          # @!endgroup
 
         end
       end

data/lib/eco/api/session/config.rb

@@ -10,6 +10,8 @@ module Eco
           self["org"] = {}
         end
 
+        # @!group Config instance pure methods
+
         def clone(name)
           keys.each_with_object(self.class.new(name)) do |key, cnf|
             begin
@@ -23,40 +25,36 @@ module Eco
         def reopen
           yield(self)
         end
+        # @!endgroup
 
-        def apis
-          self["apis"]       ||= Eco::API::Session::Config::Apis.new(config: self)
-        end
+        # @!group Additional resources
 
+        # Helper to manage `SFTP` files and folders.
+        # @return [Eco::API::Session::Config::SFTP]
         def sftp
           self["sftp"]       ||= Eco::API::Session::Config::SFTP.new(config: self)
         end
 
-        def logger
-          self["logger"]     ||= Eco::API::Session::Config::Logger.new(config: self)
-        end
-
+        # Helper to upload files and folders to `S3`.
+        # @return [Eco::API::Session::Config::S3Storage]
         def s3storage
           self["s3_storage"] ||= Eco::API::Session::Config::S3Storage.new(config: self)
         end
 
-        def files
-          self["files"]      ||= Eco::API::Session::Config::Files.new(config: self)
-        end
-
+        # Helper to send emails.
+        # @return [Eco::API::Session::Config::Mailer]
         def mailer
           self["mailer"]     ||= Eco::API::Session::Config::Mailer.new(config: self)
         end
+        # @!endgroup
 
-        def org
-          self["org"]
-        end
+        # @!group Logger
 
-        def people
-          self["people"]     ||= Eco::API::Session::Config::People.new(config: self)
+        # @return [Eco::API::Session::Config::Logger]
+        def logger
+          self["logger"]     ||= Eco::API::Session::Config::Logger.new(config: self)
         end
 
-        # LOGGER
         def log_console_level=(value)
           logger.console_level= value
         end
@@ -76,51 +74,86 @@ module Eco
         def log_connection=(value)
           logger.log_connection = value
         end
+        # @!endgroup
 
-        # API
-        def dry_run!
-          self["dry-run"] = true
-        end
+        # @!group Session and API
 
-        def dry_run?
-          self["dry-run"]
-        end
-
-        def run_mode=(mode)
-          apis.active_api.mode = mode
-        end
-
-        def run_mode_local?
-          apis.active_api.local?
+        # @return [Eco::API::Session] the `session` linked to this `config`
+        def session
+          @session     ||= Eco::API::Session.new(self)
         end
 
-        def run_mode_remote?
-          apis.active_api.remote?
+        # @return [Eco::API::Session::Config::Apis]
+        def apis
+          self["apis"] ||= Eco::API::Session::Config::Apis.new(config: self)
         end
 
+        # @return [Boolean] `true` if there is any api configuration defined, `false` otherwise
         def apis?
           apis.apis?
         end
 
+        # @param (see Eco::API::Session::Config::Apis#add)
+        # @return [Eco::API::Session::Config] this configuration
         def add_api(name, **kargs)
           apis.add(name, **kargs)
           self
         end
 
+        # Set the active api by `name`
+        # @see Eco::API::Session::Config::Apis#active_api=
+        # @return [Eco::API::Session::Config] this configuration
         def active_api(name)
           apis.active_name = name
           self
         end
 
+        # @see Eco::API::Session::Config::Apis#active_root_name
         def active_enviro
           apis.active_root_name
         end
 
+        # @see Eco::API::Session::Config::Apis#api
         def api(logger = ::Logger.new(IO::NULL), version: nil)
           apis.api(logger, version: version)
         end
 
-        # FILES
+        # Sets the `mode` of the active api
+        # @see Eco::API::Session::Config::Api#mode
+        # @param (see Eco::API::Session::Config::Api#mode)
+        def run_mode=(mode)
+          apis.active_api.mode = mode
+        end
+
+        def run_mode_local?
+          apis.active_api.local?
+        end
+
+        def run_mode_remote?
+          apis.active_api.remote?
+        end
+
+        # @deprecated old helper to fix the dry-run mode
+        # @note this is now done via `options[:dry_run]`, parsed as an option
+        def dry_run!
+          self["dry-run"] = true
+        end
+
+        # @deprecated old helper to check if we are in dry-run mode
+        # @note this is now done via `options[:dry_run]`, which is parsed as an option
+        def dry_run?
+          self["dry-run"]
+        end
+        # @!endgroup
+
+        # @!group Files
+
+        # @return [Eco::API::Session::Config::Files]
+        def files
+          self["files"]      ||= Eco::API::Session::Config::Files.new(config: self)
+        end
+
+        # Defines in the base folder from where files are expected to be found when relative paths are used
         def working_directory=(path)
           files.working_directory = path
         end
@@ -158,8 +191,12 @@ module Eco
             require_relative "#{File.expand_path(file_manager.dir.file(file))}"
           end
         end
+        # @!endgroup
 
-        # ORG
+        # @!group Organization related shortcuts
+        def org
+          self["org"]
+        end
 
         def location_codes=(file)
           org["location_codes"] = file
@@ -179,6 +216,7 @@ module Eco
           org["tagtree"] = file
         end
 
+        # @return [Eco::API::Organization::TagTree]
         def tagtree(enviro: nil)
           return @tagtree if instance_variable_defined?(:@tagtree) && @tagtree.enviro == enviro
           if tree_file = org["tagtree"]
@@ -188,68 +226,87 @@ module Eco
           end
         end
 
+        # @return [Eco::API::Organization::PolicyGroups]
         def policy_groups
           return @policy_groups if instance_variable_defined?(:@policy_groups)
           pgs            = api&.policy_groups.to_a
           @policy_groups = Eco::API::Organization::PolicyGroups.new(pgs)
         end
 
+        # @return pEco::API::Organization::PersonSchemas
         def schemas
           return @schemas if instance_variable_defined?(:@schemas)
           schs     = api&.person_schemas.to_a
           @schemas = Eco::API::Organization::PersonSchemas.new(schs)
         end
 
+        # @return [Eco::API::Organization::LoginProviders]
         def login_providers
           return @login_providers if instance_variable_defined?(:@login_providers)
           provs            = api&.login_providers.to_a
           @login_providers = Eco::API::Organization::LoginProviders.new(provs)
         end
 
-        def session
-          @session ||= Eco::API::Session.new(self)
+        # @!endgroup
+
+        # @!group People shortcuts
+
+        # @return [Eco::API::Session::Config::People]
+        def people
+          self["people"]     ||= Eco::API::Session::Config::People.new(config: self)
         end
 
-        # PEOPLE
+        # Define the default usergroup that should be given to people with no usergroups.
         def default_usergroup=(value)
           people.default_usergroup = value
         end
 
+        # Specify the file that holds the `csv` with people to be excluded from `API` updates.
         def discarded_people_file=(value)
           people.discarded_file = value
         end
 
+        # Set the base folder/name.ext name of the fieles where people will be cached.
         def people_cache=(file)
           people.cache = file
         end
 
+        # Set the base folder name where requests launched to the server will be saved for future reference.
         def requests_backup_folder=(folder)
           people.requests_folder = folder
         end
 
-        # PERSON FIELDS MAPPER
+        # Specify the `.json` file name with the mappings [`DataInputColumnName`, `internal-name`].
         def person_fields_mapper=(file)
           people.fields_mapper = file
         end
 
+        # Set the **default schema** this `api` org configuration should work on.
         def default_schema=(name)
           people.default_schema = name
         end
 
-        # ACCOUNT PRESETS
+        # Specify the file with the account custom abilities presets
         def presets_custom=(file)
           people.presets_custom = file
         end
 
+        # Specify the file with the usergroup to custom presets mapping
         def presets_map=(file)
           people.presets_map = file
         end
 
-        # CUSTOM PERSON PARSERS
+        # @see Eco::API::Session::Config::People
+        # @param (see Eco::API::Session::Config::People)
+        # @return [Eco::API::Common::People::PersonParser] parser/serializer for the defined `format`.
         def person_parser(format: :csv, &block)
           people.parser(format: format, &block)
         end
+        # @!endgroup
 
+        # @!group Session workflow and batch job launces
+
+        # @return [Eco::API::UseCases]
         def usecases
           @usecases = self["usecases"] ||= Eco::API::UseCases.new
           if block_given?
@@ -260,10 +317,12 @@ module Eco
           end
         end
 
+        # @return [Eco::API::Session::Config::PostLaunch]
         def post_launch
           self["post_launch"] ||= Eco::API::Session::Config::PostLaunch.new(config: self)
         end
 
+        # @return [Eco::API::Policies]
         def policies
           @policies = self["policies"] ||= Eco::API::Policies.new
           if block_given?
@@ -274,6 +333,7 @@ module Eco
           end
         end
 
+        # @return [Eco::API::Session::Batch::Policies]
         def batch_policies
           @batch_policies = self["batch_policies"] ||= Eco::API::Session::Batch::Policies.new("batch_policy")
           if block_given?
@@ -284,6 +344,7 @@ module Eco
           end
         end
 
+        # @return [Eco::API::Error::Handlers]
         def error_handlers
           @error_handlers = self["error_handlers"] ||= Eco::API::Error::Handlers.new
           if block_given?
@@ -294,13 +355,14 @@ module Eco
           end
         end
 
+        # @return [Eco::API::Session::Config::Workflow]
         def workflow
           @workflow = self["workflow"]  ||= Eco::API::Session::Config::Workflow.new(config: self)
           @workflow.tap do |wf|
             yield(wf) if block_given?
           end
         end
-
+        # @!endgroup
 
       end
     end

data/lib/eco/api/session/config/api.rb

@@ -44,15 +44,21 @@ module Eco
             self["external_key"] = external_key
           end
 
+          # @return [Eco::API::Session::Config] the `root` config
           def config
             @root.config
           end
 
+          # Obtain an `API` object of a specific `version`.
+          # @param version [Symbol] any of the available `API` versions [`:v0`, `:v1`, `:v2`].
+          # @param logger [Logger] the logger that will be used with this api instance.
+          # @return [Ecoportal::API::Internal, Ecoportal::API::V2, Ecoportal::API::V1]
           def api(version: nil, logger: nil)
-            version = version ? version : self.version
-            @logger = logger if logger
+            version       = version ? version : self.version
+            switch_logger = (logger != @logger)
+            @logger       = logger if logger
 
-            if (current = get(version)) && self.logger.class == current.logger.class
+            if (current = get(version)) && !switch_logger
               return current
             end
 
@@ -97,10 +103,12 @@ module Eco
             self["host"]
           end
 
+          # @param mode [Symbol] to define if running on `:remote` or `:local`
           def mode=(mode)
             self["mode"] = (mode == :remote)? :remote : :local
           end
 
+          # @return [Symbol] if running on `:remote` or `:local`
           def mode
             self["mode"]
           end
@@ -117,6 +125,7 @@ module Eco
             self.class.to_version(value || self["version"])
           end
 
+          # if no low level connection messages: use `IO::NULL`
           def logger
             @logger ||= ::Logger.new(IO::NULL)
             log_connection? ? @logger : ::Logger.new(IO::NULL)
@@ -124,6 +133,7 @@ module Eco
 
           private
 
+          # Generates a **new** `API` object of version `version`.
           def new_api(version)
             klass = self.class.api_class(version)
             case self.version(version)
@@ -133,14 +143,15 @@ module Eco
               klass.new(external_key, host: host, logger: logger)
             when :v2
               klass.new(user_key: user_key, org_key: external_key, logger: logger)
-            end.tap do |pi|
-              unless log_connection? || !pi
+            end.tap do |api|
+              unless !api || log_connection?
                 @logger.info("Created api#{self.version(version)} connection on '#{name}' enviro, pointing to '#{host}' in '#{mode}' mode")
-                pi.logger.level = ::Logger::UNKNOWN
+                api.logger.level = ::Logger::UNKNOWN
               end
             end
           end
 
+          # Checks if the necessary parameters for a specific `API` version are available.
           def api_params?(version)
             case self.class.to_version(version)
             when :v0