eco-helpers 3.0.20 → 3.0.22

data/lib/eco/api/microcases/people/integrity/fix_filter_tags.rb

@@ -0,0 +1,55 @@
+module Eco
+  module API
+    class MicroCases
+      module People
+        module Integrity
+          module FixFilterTags
+            # Helper that makes sure the **custom `tags`** are preserved.
+            # @note
+            #   - this feature is essential to preserve custom `tags` in users that have register tags.
+            #   - for this to work out, it requires a `tagtree` to be defined.
+            # @param person [Ecoportal::API::V1::Person] the person we want to update, carrying the changes already done.
+            # @param options [Hash] the options.
+            # @option options [Hash<Symbol, Object>] :filter_tags options around `filter_tags`.
+            #   * `:preserve_custom` (Boolean) [true] indicates if original tags that are not in the tree should be added/preserved.
+            #   * `:add_custom` (Boolean) [true] indicates if target tags that are not in the tree should be really added.
+            def fix_filter_tags(person, options)
+              return unless session.tagtree
+
+              filter_tags_excluded =
+                options.dig(:exclude, :core) ||
+                options.dig(:exclude, :filter_tags)
+
+              return if !person.new? && filter_tags_excluded
+
+              person.filter_tags = session.tagtree.user_tags(
+                initial:         person.original_doc['filter_tags'] || [],
+                final:           person.filter_tags,
+                preserve_custom: _fix_filter_tags_preserve_custom?(options),
+                add_custom:      _fix_filter_tags_add_custom?(options)
+              )
+            end
+
+            private
+
+            # default `true`
+            def _fix_filter_tags_preserve_custom?(options)
+              key_defined = options.key?(:filter_tags) && options[:filter_tags].key?(:preserve_custom)
+              return true unless key_defined
+
+              options.dig(:filter_tags, :preserve_custom)
+            end
+
+            # default `true`
+            def _fix_filter_tags_add_custom?(options)
+              key_defined = options.key?(:filter_tags) && options[:filter_tags].key?(:add_custom)
+              return true unless key_defined
+
+              options.dig(:filter_tags, :add_custom)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/integrity/refresh_default_tag.rb

@@ -0,0 +1,32 @@
+module Eco
+  module API
+    class MicroCases
+      module People
+        module Integrity
+          module RefreshDefaultTag
+            # When the input data, or `entry`, does not provide the `default_tag`,
+            # it sets the `default_tag` of the user following some criteria
+            # @note it assumes `default_tag` has been already set to `person.account`
+            # @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 refresh_default_tag(entry, person, options)
+              return unless person.account
+              return if options.dig(:exclude, :account)
+              return if options.dig(:exclude, :filter_tags)
+              return if options.dig(:exclude, :default_tag)
+              return if entry&.default_tag?
+
+              if session.tagtree
+                person.account.default_tag = session.tagtree.default_tag(*person.filter_tags)
+              else
+                tags = person.filter_tags || []
+                person.account.default_tag = tags.first unless tags.length > 1
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/integrity.rb

@@ -0,0 +1,17 @@
+require_relative 'integrity/refresh_default_tag'
+require_relative 'integrity/fix_filter_tags'
+require_relative 'integrity/fix_default_group'
+
+module Eco
+  module API
+    class MicroCases
+      module People
+        module Integrity
+          include RefreshDefaultTag
+          include FixFilterTags
+          include FixDefaultGroup
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/macro/take_email.rb

@@ -0,0 +1,141 @@
+# rubocop:disable Metrics/BlockNesting, Layout/LineLength
+module Eco
+  module API
+    class MicroCases
+      module People
+        module Macro
+          module TakeEmail
+            # Frees up `target_email` from an account not present in this org.
+            #   Allows to force `target_email` on the current user's account.
+            #   - If the person does not have account, this case will not do anything.
+            #   - If `original_doc['account']` is `nil` (no account on server side), this case will not do anything.
+            #   - If the `target_email` and the `current_email` are the same or empty, this case will not do anything.
+            # @note
+            #   - **It does not do the final update to the server to the `target_email`**.
+            #     You will need to do this part yourself.
+            #   - You would call this function only when you got an error of `email already taken`.
+            #   - If the `target_email` is associated to a user in the same org, this will fail.
+            # @param person [Ecoportal::API::V1::Person] the person we want to update,
+            #   carrying the changes to be done.
+            # @param dest_email [String, Proc] the email that we will move the other account to,
+            #   when we free up `target_email`.
+            # @param target_email [String] the email that we want to free up from another account and bring to ours.
+            #   If it's empty, the `person.email` will be used instead.
+            # @param options [Hash] the options.
+            # @param current_email [String] the email that the person's account is currently linked.
+            #   As the current email should be associated with this person's account on server side,
+            #   we use `original_doc['email']`.
+            # @param context [String] main core part of logs. Provides context to the logs.
+            def take_email_from_account( # rubocop:disable Metrics/AbcSize
+              person,
+              dest_email:,
+              target_email: nil,
+              options:      {},
+              context:      'Session'
+            )
+              return false if options.dig(:exclude, :account)
+              return false unless (account     = person.account)
+              return false unless (had_account = person.original_doc['account']) # rubocop:disable Lint/UselessAssignment
+
+              target_email  ||= person.email
+              account_email   = person.original_doc['email']
+
+              return false unless target_email != account_email
+              return false if account_email.to_s.strip.empty?
+              return false if target_email.to_s.strip.empty?
+
+              if dest_email.is_a?(String)
+                return false unless target_email != dest_email
+                return false unless dest_email   != account_email
+                return false if dest_email.to_s.strip.empty?
+              end
+
+              account_json = _take_email_account_json(account)
+              person.email = account_email
+
+              if (success = _take_email_remove_account!(person, context: context))
+                if (success = _take_email_acquire_account!(person, target_email, account: {}, context: context))
+                  if (success = _take_email_email_free_up!(person, dest_email: dest_email, context: context))
+                    if (success = _take_email_remove_account!(person, context: context))
+                      # Bring back the original account
+                      if (success = _take_email_acquire_account!(person, account_email, account: account_json, context: context)) # rubocop:disable Style/SoleNestedConditional
+                        success      = true
+                        person.email = target_email
+                      end
+                    end
+                  else # free up target email
+                    # restore
+                    reverted = false
+                    if reverted ||= _take_email_remove_account!(person, context: context)
+                      reverted ||= _take_email_acquire_account!(person, account_email, account: account_json, context: context)
+                    end
+
+                    unless reverted
+                      msg = "Could not revert back to the original account #{person.identify}"
+                      log(:debug) { msg }
+                      puts msg
+                    end
+
+                    success = false
+                  end
+                else # aquire other account
+                  # restore
+                  unless _take_email_acquire_account!(person, account_email, account: account_json, context: context)
+                    msg = 'Could not bring back the original account that '
+                    msg << "we want to update the email to '#{target_email}' #{person.identify}"
+                    log(:debug) { msg }
+                    puts msg
+                  end
+
+                  success = false
+                end
+              end
+
+              success
+            end
+
+            private
+
+            def _take_email_account_json(account)
+              JSON.parse(account.to_json).tap do |hash|
+                hash.delete('user_id')
+                hash.delete('permissions_merged')
+                hash.delete('permissions_preset')
+                hash.delete('prefilter')
+
+                if (pref = hash['preferences'])
+                  hash['preferences'] = pref.reject do |attr, _value|
+                    attr.start_with?('kiosk')
+                  end
+                end
+              end
+            end
+
+            # Bring the account of the `target_email` taken, so we can change the email of this account
+            def _take_email_acquire_account!(person, target_email, account: {}, context: 'Session')
+              person.account = account
+              person.account.send_invites = false
+              person.email = target_email
+              micro.person_update!(person, reason: "bring account with email '#{target_email}'", context: context)
+            end
+
+            # Free up the email (`target_email`) of the account that has it taken to `dest_email`
+            def _take_email_email_free_up!(person, dest_email:, target_email: nil, context: 'Session')
+              target_email ||= person.email
+              person.email   = dest_email.is_a?(Proc)? dest_email.call(target_email) : dest_email
+              reason = "free up email '#{target_email}', by moving account to '#{person.email}'"
+              micro.person_update!(person, reason: reason, context: context)
+            end
+
+            def _take_email_remove_account!(person, context: 'Session')
+              person.account = nil
+              micro.person_update!(person, reason: 'remove account', context: context)
+            end
+          end
+        end
+      end
+    end
+  end
+end
+
+# rubocop:enable Metrics/BlockNesting, Layout/LineLength

data/lib/eco/api/microcases/people/macro.rb

@@ -0,0 +1,13 @@
+require_relative 'macro/take_email'
+
+module Eco
+  module API
+    class MicroCases
+      module People
+        module Macro
+          include TakeEmail
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/manage/cache.rb

@@ -0,0 +1,36 @@
+module Eco
+  module API
+    class MicroCases
+      module People
+        module Manage
+          module Cache
+            # Helper to locally cache the people manager.
+            # @param filename [String] the name of the file where the data should be cached.
+            # @return [Eco::API::Organization::People] the `People` object with the data.
+            def people_cache(filename = enviro.config.people.cache)
+              log(:info) { 'Going to get all the people via API' }
+
+              start   = Time.now
+              people  = session.batch.get_people
+              secs    = (Time.now - start).round(3)
+              cnt     = people.count
+              per_sec = (cnt.to_f / secs).round(2)
+
+              log(:info) {
+                "Loaded #{cnt} people in #{secs} seconds (#{per_sec} people/sec)"
+              }
+
+              file = file_manager.save_json(people, filename, :timestamp)
+
+              log(:info) {
+                "#{people.length} people loaded and saved locally to #{file}."
+              }
+
+              Eco::API::Organization::People.new(people)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/manage/load.rb

@@ -0,0 +1,90 @@
+module Eco
+  module API
+    class MicroCases
+      module People
+        module Manage
+          module Load
+            # Helper to load `People` that works in different phases:
+            #   1. first tries to get the newest cached file that follows `filename` pattern
+            #     - if not the newest, it tries to find the specific filename
+            #   2. if it succeeds to identify a cached file, it loads it
+            #     - if it fails, it tries to get people from the server
+            # @note
+            #  - `filename` will be relative to the working directory (the one of the session `enviro` set by the user).
+            # @param filename [String] the name of the file where the cached data is to be found.
+            # @param modifier [Array<Symbol>] modifiers to specify how this function should proceed:
+            #   - `:newest` if it should try to find the newest file (pattern alike).
+            #   - `:api` if it should try to get people from the server in case there's no cache.
+            #   - `:file` if it is supposed to load people from a file.
+            #   - `:save` if it is supposed to cache/save the data locally once obtained people from the server (`:api`)
+            # @return [Eco::API::Organization::People] the `People` object with the data.
+            def people_load(filename = enviro.config.people.cache, modifier: %i[newest api]) # rubocop:disable Metrics/AbcSize
+              modifier  = [modifier].flatten
+              load_file = %i[file newest].any? {|flag| modifier.include?(flag)}
+
+              case
+              when filename && load_file
+                file = people_load_filename(filename, newest: modifier.include?(:newest))
+
+                if file
+                  file_manager.load_json(file).tap do |people|
+                    next unless people.is_a?(Array)
+
+                    log(:info) {
+                      "#{people&.length} people loaded from file #{file}"
+                    }
+                  end
+                else
+                  log(:error) {
+                    "could not find the file #{file_manager.dir.file(filename)}"
+                  }
+
+                  exit unless modifier.include?(:api)
+
+                  people_load(modifier: modifier - %i[newest file])
+                end
+              when modifier.include?(:api)
+                log(:info) { 'Going to get all the people via API (load)' }
+
+                start = Time.now
+                session.batch.get_people.tap do |people|
+                  secs    = (Time.now - start).round(3)
+                  cnt     = people.count
+                  per_sec = (cnt.to_f / secs).round(2)
+
+                  log(:info) {
+                    "Loaded #{cnt} people in #{secs} seconds (#{per_sec} people/sec)"
+                  }
+
+                  if modifier.include?(:save) && people && people.length.positive?
+                    file = file_manager.save_json(people, filename, :timestamp)
+                    log(:info) { "#{people.length} people saved to file #{file}." }
+                  end
+                end
+              end.then do |people|
+                Eco::API::Organization::People.new(people)
+              end
+            end
+
+            private
+
+            def people_load_filename(filename, newest: false)
+              if newest
+                # search input file based on pattern (in case the name has a timestamp)
+                file_manager.dir.newest_file(file: filename).tap do |file|
+                  next unless file
+
+                  log(:info) {
+                    "previous file found: #{file}"
+                  }
+                end
+              else
+                file_manager.dir.file(filename, should_exist: true)
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/manage/refresh.rb

@@ -0,0 +1,59 @@
+module Eco
+  module API
+    class MicroCases
+      module People
+        module Manage
+          module Refresh
+            # Helper to obtain all the elements of `people` anew from the _People Manager_.
+            # @note
+            #   1. This helper is normally used to run consecutive usecases, where data needs refresh.
+            #   2. It only includes new people if they are not dirty (they do not have pending updates)
+            #     - This contingency wouldn't be necessary if the server worked perfectly.
+            # @param people [Eco::API::Organization::People] the people that needs refresh.
+            # @param include_created [Boolean] include people created during this session? (will check `:create` batch jobs).
+            # @return [Eco::API::Organization::People] the `People` object with the data.
+            def people_refresh(people:, include_created: true) # rubocop:disable Metrics/AbcSize
+              people = people.newFrom people.select do |person|
+                !person.new? || !person.dirty?
+              end
+
+              ini = people.length
+
+              if include_created
+                session.job_groups.find_jobs(type: :create).map do |job|
+                  to_add = job.people.reject(&:dirty?)
+                  people = people.merge(to_add)
+                end
+              end
+
+              created = people.length - ini
+              msg    = "Going to refresh #{people.length} people with server data"
+              msg   << " (including #{created} that were created)" if created.positive?
+              log(:info) { msg }
+
+              start   = Time.now
+              entries = session.batch.get_people(people, silent: true)
+              secs    = (Time.now - start).round(3)
+              cnt     = entries.count
+              per_sec = (cnt.to_f / secs).round(2)
+
+              log(:info) {
+                "Re-loaded #{cnt} people (out of #{people.length}) in #{secs} seconds (#{per_sec} people/sec)"
+              }
+
+              missing = people.length - entries.length
+
+              if missing.positive?
+                log(:error) {
+                  "Missed to obtain #{missing} people during the refresh"
+                }
+              end
+
+              Eco::API::Organization::People.new(entries)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/manage/search.rb

@@ -0,0 +1,118 @@
+module Eco
+  module API
+    class MicroCases
+      module People
+        module Manage
+          module Search
+            # Helper to search/obtain people from `data` against the server (_People Manager_).
+            # @note
+            #   - this helper is normally used to **get partial** part of the people manager.
+            #   - therefore, normally used with _**delta** input files_ (files with only the differences).
+            # @param data [Eco::API::Organization::People, Enumerable<Person>, Enumerable<Hash>]
+            #   `People` to search against the server.
+            # @param options [Hash] the options.
+            # @param silent [Boolean] `false` if low level search messages should be shown.
+            # @return [Eco::API::Organization::People] the `People` object with the found persons.
+            def people_search(data, options: {}, silent: false) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+              log(:info) { "Going to api get #{data.length} entries..." }
+
+              silent &&= data.count <= 500
+
+              start = Time.now
+              people = session.batch.search(data, silent: silent).then do |status|
+                secs = (Time.now - start).round(3)
+
+                Eco::API::Organization::People.new(status.people).tap do |people| # rubocop:disable Lint/ShadowingOuterLocalVariable
+                  cnt     = people.count
+                  per_sec = (cnt.to_f / secs).round(2)
+
+                  msg     = "... could get #{cnt} people "
+                  msg    << "(out of #{data.length} entries) in #{secs} seconds (#{per_sec} people/sec)"
+
+                  log(:info) { msg }
+                end
+              end
+
+              # get the supervisors of found people (current supervisors)
+              supers = people_search_prepare_supers_request(people)
+              if supers.length.positive?
+                log(:info) {
+                  "  Going to api get #{supers.length} current supervisors..."
+                }
+
+                start = Time.now
+                people = session.batch.search(supers, silent: silent).then do |status|
+                  secs    = (Time.now - start).round(3)
+                  found   = status.people
+                  cnt     = found.count
+                  per_sec = (cnt.to_f / secs).round(2)
+
+                  msg     = "... could find #{cnt} current supers "
+                  msg    << "(out of #{supers.length}) in #{secs} seconds (#{per_sec} people/sec)"
+                  log(:info) { msg }
+
+                  people.merge(found, strict: micro.strict_search?(options))
+                end
+              end
+
+              # get the supervisors referred in the input data (future supervisors)
+              supers = people_search_prepare_supers_request(data, people)
+              if supers.length.positive?
+                log(:info) {
+                  "  Going to api get #{supers.length} supervisors as per input entries..."
+                }
+
+                start = Time.now
+                people = session.batch.search(supers, silent: silent).then do |status|
+                  secs    = (Time.now - start).round(3)
+                  found   = status.people
+                  cnt     = found.count
+                  per_sec = (cnt.to_f / secs).round(2)
+
+                  msg     = "... could find #{cnt} input supers "
+                  msg    << "(out of #{supers.length}) in #{secs} seconds (#{per_sec} people/sec)"
+                  log(:info) { msg }
+
+                  people.merge(found, strict: micro.strict_search?(options))
+                end
+              end
+
+              log(:info) {
+                "Finally got #{people.length} people (out of #{data.length} entries)"
+              }
+
+              people
+            end
+
+            private
+
+            # Prepares a unique request with only the supervisor ids missing in `people`
+            def people_search_prepare_supers_request(data, people = data)
+              data.each_with_object([]) do |entry, request|
+                spr = {'id' => (sup_id = people_search_super_id(entry))}
+                next if !sup_id || request.include?(spr)
+
+                micro.with_supervisor(sup_id, people) do |supervisor|
+                  request.push(spr) unless supervisor
+                end
+              end
+            end
+
+            # Gets the `supervisor_id` from `value`
+            def people_search_super_id(value)
+              sup_id =
+                if value.respond_to?(:supervisor_id)
+                  value.supervisor_id
+                elsif value.is_a?(Hash) && value.key('supervisor_id')
+                  value['supervisor_id']
+                end
+
+              sup_id = nil if sup_id.to_s.strip.empty?
+              sup_id
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/manage.rb

@@ -0,0 +1,19 @@
+require_relative 'manage/cache'
+require_relative 'manage/load'
+require_relative 'manage/search'
+require_relative 'manage/refresh'
+
+module Eco
+  module API
+    class MicroCases
+      module People
+        module Manage
+          include Cache
+          include Load
+          include Search
+          include Refresh
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/preserve/default_tag.rb

@@ -0,0 +1,29 @@
+module Eco
+  module API
+    class MicroCases
+      module People
+        module Preserve
+          module DefaultTag
+            # Helper to preserve the original `default_tag`.
+            # @note
+            #   1. It only works if the original value of `default_tag` was **not** empty
+            # @param person [Ecoportal::API::V1::Person] the person we want to update, carrying the changes to be done.
+            # @param options [Hash] the options.
+            # @return [String] the final value of `default_tag`.
+            def preserve_default_tag(person, _options)
+              return unless (account = person.account)
+
+              account.default_tag.tap do
+                next unless account.as_update.key?('default_tag')
+                next unless (original = person.original_doc.dig('account', 'default_tag'))
+
+                person.account.default_tag = original
+                return original
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/microcases/people/preserve/filter_tags.rb

@@ -0,0 +1,34 @@
+module Eco
+  module API
+    class MicroCases
+      module People
+        module Preserve
+          module FilterTags
+            # Helper to preserve the original filter tags.
+            # @note
+            #   1. It only works if the original value of `filter_tags` was **not** empty
+            # @param person [Ecoportal::API::V1::Person] the person we want to update, carrying the changes to be done.
+            # @param options [Hash] the options.
+            # @param keep_new [Boolean] tells if it should keep the new tags or get rid of them.
+            # @return [Array<String>] the final value of `filter_tags`.
+            def preserve_filter_tags(person, _options, keep_new: false)
+              person.filter_tags.tap do
+                next unless person.as_update.key?('filter_tags')
+                next unless (original = person.original_doc['filter_tags'])
+                next if original.empty?
+
+                if keep_new
+                  person.filter_tags += original
+                else
+                  person.filter_tags  = original
+                end
+
+                return person.filter_tags
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end