eco-helpers 1.4.0 → 1.5.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 28d9f5ad6037a8160ea1d39873a0b1c6769be63865267d159dd6fa71ae329d60
-  data.tar.gz: ba968ce7525e5fb289ff5b210f3c79692b05dfc74ae6af6cf8c729640bb1cf4a
+  metadata.gz: afef384678f171e737391056ca300ac9d9c813240d32422445ad1e256911be31
+  data.tar.gz: 82f7b611239cc9e5d58778d1db9ffaef7cef748360fd82abeba3df710c56ac60
 SHA512:
-  metadata.gz: 2a7bda8f0a427b7a93d42230c32226c578b4ae4aab9b2974bf1095d1f77d368faa8c409e41375cf5d378ed4a915b359ce12e74559c7f963a2a9d791a165f3232
-  data.tar.gz: ba9adb7220623345536d5080e658a524daebd914f3c64d94f83652e3d42fbdb240da9a08367ee42dde196adfc2152553b4133bd330d3a007052bba42b156aed5
+  metadata.gz: 6516df10c5fbf6d48f8fa5bfdb993320a15043fecdcbe84c2927c6c84ab9fd817d298f9ae0806a6e43476d2342e862fbecb55ed14fc532bc4cf007f32a9ff7e6
+  data.tar.gz: 13763cf62b5d0741d0d23837f66480fcf678ac317d6ac726cdea0fbd12cb4ce048b57e3278053536c214661f9aa591a90a22e06b5a24720bba087459c6536d72

data/CHANGELOG.md

@@ -1,7 +1,148 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
-## [1.4.0] - 2020-07-xx
+## [1.5.2] - 2020-10-29
+
+### Added
+  - **custom** usecases, policies and error handlers can now be **declared within its own class**
+    * helper classes to inherit from: `Eco::API::Custom::UseCase`, `Eco::API::Custom::Policy`, `Eco::API::Custom::ErrorHandler` and `Eco::API::Custom::Parser`
+    * please, notice that you should create new classes under the following namespaces
+      - `Custom::UseCase`: custom use cases
+      - `Custom::Policy`: custom policy
+      - `Custom::ErrorHandler`: custom error handler
+      - `Custom::Parser`: custom parser
+    * this also allows to inherit from existing defaults and models (models to come)
+  - implemented first **microcases** (evaluation stage): to be able to centralize common code between use cases
+    - see `Eco::API::MicroCases` class
+  - **command line** added `--help` to list all `usecases`, `options` and `filters`
+    * `--help -options` will print a documented overview of options
+    * `--help -filters` will print a documented overview of people filters
+    * `--help -input-filters` will print a documented overview of input data filters
+    * `--help -usecases` will print a documented overview of the usecases
+  - **command line** filters for `filter_tags` on:
+    * input data:  `-input-filter-tags-all`, `input-filter-tags-any`, `input-filter-tags-tree`
+    * people data: `-filter-tags-all`, `-filter-tags-any`, `-filter-tags-tree`
+  - **batch stats** & **batch policy**
+    * `Eco::API::Session::Batch::RequestStats`: included additional guide on what has been **blanked**.
+      - now on you should see how many have been blanked, i.e.: `blanked_email`, `blanked_filter_tags`, `blanked_policy_group_ids`, `blanked_supervisor_id`
+    * Moreover, the new `blanked_*` properties are available for `config.batch_policies` provided that you can limit the `max` and/or `min` expected on each batch **type**
+  - **csv** generation (`-people-to-csv` and `-people-to-csv -detailed`):
+     * now includes `"Has Account?"` new column
+     * removed the useless `send_invites` column
+  - **errors** improved error message when setting values to a `person` from an `entry`:
+    * it now shows the **row number**
+    * it now gives the specific value that failed in case of `Exception`
+  - `Eco::API::Common::DefaultPasers::LoginProvidersParser`: made native
+  - `Eco::API::UseCases::DefaultUsecases::TransferAccountCase`: added `-transer-account-from` usecase
+    * to allow actually transfer an account/user from one person to another in the org
+  - `Ecoportal::API::V1::Person#entry`: method to be able to have a reference to the update/creation input data entry.
+  - new filter methods for `Eco::API::Common::People::Entries` and `Eco::API::Organization::People`
+    * `#filter_tags_any` & `#filter_tags_all`: those that have any or all the target tags
+    * `#policy_group_ids_any` & `#policy_groups_all`: those that have any or all the target policy groups
+
+### Changed
+  - updated dependency on `ecoportal-api` gem
+  - **command line** some changes:
+    - renamed `-refresh-presets` to `-refresh-abilities`
+    - renamed `-recover-db` to `restore-db`
+  - removed `Eco::API::Session::Tasks`: all the helpers have been moved and documented as part of `Eco::API::MicroCases` (some have been renamed)
+    - as a consequence, removed method `Eco::API::Session#do`
+  - `Eco::API::Common::People::PersonEntry#to_hash` has been removed
+    - now you should use the more explicit `Eco::API::Common::People::PersonEntry#external_entry`
+  - **internal refactor** of `Eco::API::UseCases::DefaultCases`:
+    * made so they inherit from `Eco::API::Common::Loaders::UseCase` and cases are autoloaded during run-time
+  - **internal refactor** of input entries processing:
+    * `Eco::API::Common::People::PersonEntry` internal refactor
+      - need to make the code clearer and make the `parsing` and `serializing` symmetrical
+        - the `serializers` were expecting an `Ecoportal::API::V1::Person`, which was at a different to that of when the `parsers` kicked in.
+        - now it has been introduced the possibility to launch the serializer in a different stage of the process
+      - to keep backwards compatibility, now it is possible to define at which `phase` of the parsing/serializing each parser and each serializer should kick in, which entailed changes in other classes and a new parameter in some methods thereof...
+    * `Eco::Language::Models::ParserSerializer` offers `category` parameter so you can have multiple parsers and serializers per each parser/serializer (one per category).
+    * `Eco::API::Common::People::PersonParser` uses `category` to define a `phase` when the `parser` or the `serializer` should be active => the expected object in the parser `callback` will be different depending on at which phase it is active and therefore called
+      - for `parser` valid **phases** are `:internal` (default) and `:final`
+      - for `serializer` valid **phases** are `:person` (default), `:final` and `:internal`
+      - the expected output of such **callbacks** is the same as before: either the single `value` to return or a `Hash` with pair key/values of virtually-generated or existing-modified attributes of the source/input data passed to the parser
+
+### Fixed
+  - **command line**
+    * `-search-soft` was being ignored in orgs with org config `session.config.people.strict_search = true`
+    * Log connection information (**enabled**): it was not printing where the connection was being made
+    * enabled chaining between usecases: they will be processed in the order they hold in the command line
+  - Removed error double backtrace (now it should only show one)
+  - `Eco::API::Common::People::EntryFactory#entries` was not using `encoding` parameter properly.
+  - `Eco::API::Common::People::DefaultParsers::CSVParser` does at `strip` (trim) of the header names.
+  - `Eco::API::Organization::PresetsFactory#merge` was including abilities that were not included in the custom presets
+    - fix: it will include only those that are defined, provided that using it will not override account abilities that should not be targeted, such as `tasks`
+    - this new behavior will preserve account abilities that should be preserved; not targeted by the custom presets
+  - some use cases where giving incorrect row number, fixed so they do:
+    - `Eco::API::Common::People::EntryFactory#entries` adds `idx` key to each `entry`
+  - `Eco::API::Common::People::PersonEntry`: serialization process has been normalized (previously there were missing fields)
+    - this fix makes the `csv` with the complete set of fields that should be exported
+  - `Ecoportal::API::Internal::Person#account_added` fixed typo
+  - `Ecoportal::API::Session::Batch#get_people` should return `Array<Person>` invariably
+
+## [1.5.1] - 2020-10-08
+
+### Added
+  - `presets_values.json`: added the new ability `tasks` (eP release `1.5.3`)
+  - `Ecoportal::API::Internal::Person` patch helper methods:
+    * `new?`: to know if this person is new in the people manager as a result of the current launch
+    * `account_added?`: to know if this person did not have account but they will have it after the current launch
+  - `Eco::API::Session#new_job`: to shorten code
+  - `Eco::API::Common::DefaultPasers::PolicyGroupsParser`: made native, as it is a very common parser
+  - `Eco::API::Common::DefaultPasers::FreemiumParser` to parse/serialise boolean
+  - `Eco::API::Common::People::PersonParser`: added `freemium` as core attribute
+  - `Eco::API::UserCases::DefaultCases::RecoverDBCase`: recovers also `freemium`
+  - scoping **microcases** : to be able to centralize common code between use cases
+    - at its early stage (currently not available for usage)
+  - dependency on `ecoportal-api-oozes` gem
+    - added basic support for **api** `v2`
+    - you can use `session.api(:oozes)` to obtain an api `v2`
+    - you can manage your keys directly on the apis configuration
+      - added `external_key:`, `user_key:` and `apis.default_user_key`
+
+  ```ruby
+  ASSETS.config do |config|
+    config.apis.default_user_key = 'your-user-key-here'
+
+    config.add_api("org-environment", {
+      host: 'pre.dev.ecoportal.com',
+      key:  'an-internal-org-api-key',
+      version: :internal,
+      external_key: 'an-external-org-api-key',
+      user_key: 'org-user-key-for-activity-stream',
+      mode:    :local
+    })
+  end
+  ```
+### Changed
+  - internally: load `Eco::API::Common::Session` before `Eco::API::Common::People`
+  - `Eco::API::Common::People::EntryFactory`: made child of `Eco::API::Common::Session::BaseSession`
+  - refactored all the `api` connection creation for simplicity and to support multi api version
+  - delegated `Eco::API::Session::Batch#get` to `Ecoportal::API::V1::People#get_all`
+
+### Fixed
+  - correct `.gemspec` dependency version restrictions
+
+## [1.5.0] - 2020-09-11
+
+### Added
+  - `Eco::Data::Files#file_empty?` to prevent error when checking encoding
+### Changed
+  - change abilities to align with ecoPortal release `1.5.2`
+### Fixed
+  - `Eco::CSV#parse` and `Eco::CSV#read` should use the proper `encoding` when it's `bom`
+    * apparently, this can only be achieved by passing an argument such as `rb:bom|utf-8`
+    * best reference found: https://stackoverflow.com/a/60794851/4352306
+
+## [1.4.2] - 2020-07-23
+
+### Added
+### Changed
+### Fixed
+  - preserve backtrace on logging
+
+## [1.4.0] - 2020-07-14
 
 ### Added
 ### Changed
@@ -11,6 +152,13 @@ All notable changes to this project will be documented in this file.
 ### Fixed
   - `Eco::CSV#parse` and `Eco::CSV#read` should use the proper `:encoding` when it's `bom`
 
+## [1.3.19] - 2020-07-23
+
+### Added
+### Changed
+### Fixed
+  - preserve backtrace on logging
+
 ## [1.3.18] - 2020-07-08
 
 ### Added
@@ -63,7 +211,7 @@ All notable changes to this project will be documented in this file.
   - `Eco::API::Organization::TagTree#tag?` to accept `nil` by returning `false`
   - `Eco::API::Common::People::DefaultParsers::DateParser` will parse to `Date` class
     * it was parsing to `Time` class, while the native gem `ecoportal-api` parses as `Date` ([reference](https://gitlab.com/ecoPortal/ecoportal-api/-/blob/master/lib/ecoportal/api/v1/schema_field.rb))
-## [1.3.11] - 2020-05-19
+## [1.3.12] - 2020-05-19
 
 ### Added
 ### Changed

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 ecoPortal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/eco-helpers.gemspec

@@ -22,16 +22,17 @@ Gem::Specification.new do |s|
   #s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
-  s.add_development_dependency "bundler",   "~> 2.1", ">= 2.1.3"
-  s.add_development_dependency "rspec",     "~> 3",   ">= 3.9"
-  s.add_development_dependency "rake",      "~> 12.3.0"
-  s.add_development_dependency "yard",      "~> 0.9", ">= 0.9.18"
-  s.add_development_dependency "redcarpet", "~> 3.5", ">= 3.5.0"
+  s.add_development_dependency "bundler",   ">= 2.1.3",  "< 2.2"
+  s.add_development_dependency "rspec",     ">= 3.9",    "< 4"
+  s.add_development_dependency "rake",      ">= 12.3.0", "< 13"
+  s.add_development_dependency "yard",      ">= 0.9.18", "< 0.10"
+  s.add_development_dependency "redcarpet", ">= 3.5.0",  "< 3.6"
 
-  s.add_dependency 'ecoportal-api', '~> 0.5',  '>= 0.5.9'
-  s.add_dependency 'aws-sdk-s3',    '~> 1',    '>= 1.64.0'
-  s.add_dependency 'aws-sdk-ses',   '~> 1',    '>= 1.29.0'
-  s.add_dependency 'dotenv',        '~> 2.7',  '>= 2.7.0'
-  s.add_dependency 'net-sftp',      '~> 2.1',  '>= 2.1.2'
+  s.add_dependency 'ecoportal-api', '>= 0.7.2', '< 0.8'
+  s.add_dependency 'ecoportal-api-oozes', '>= 0.7.2', '< 0.8'
+  s.add_dependency 'aws-sdk-s3',    '>= 1.64.0', '< 2'
+  s.add_dependency 'aws-sdk-ses',   '>= 1.29.0', '< 2'
+  s.add_dependency 'dotenv',        '>= 2.7.0', '< 2.8'
+  s.add_dependency 'net-sftp',      '>= 2.1.2', '< 2.2'
 
 end

data/lib/eco/api.rb

@@ -1,4 +1,5 @@
 require 'ecoportal/api'
+require 'ecoportal/api-oozes'
 
 module Eco
   module API
@@ -6,7 +7,9 @@ module Eco
 end
 
 require_relative 'api/common'
+require_relative 'api/custom'
 require_relative 'api/usecases'
+require_relative 'api/microcases'
 require_relative 'api/policies'
 require_relative 'api/error'
 require_relative 'api/organization'

data/lib/eco/api/common.rb

@@ -7,6 +7,10 @@ end
 
 require_relative 'common/version_patches'
 require_relative 'common/class_helpers'
+require_relative 'common/class_auto_loader'
 require_relative 'common/class_hierarchy'
-require_relative 'common/people'
+require_relative 'common/class_meta_basics'
+require_relative 'common/base_loader'
+require_relative 'common/loaders'
 require_relative 'common/session'
+require_relative 'common/people'

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

@@ -0,0 +1,54 @@
+module Eco
+  module API
+    module Common
+      class BaseLoader
+        extend Eco::API::Common::ClassHelpers
+
+        class << self
+          attr_writer :name, :type
+
+          # 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 ||= self.to_s unless value
+            @name = value
+          end
+
+          # Sort order
+          def <=>(other)
+            created_at <=> other.created_at
+          end
+
+          # If still not set, it sets the `created_at` class timestamp.
+          def set_created_at!
+            @created_at = Time.now unless @created_at
+          end
+
+          # Class creation timestamp, to be able to load them in the order they were declared.
+          def created_at
+            @created_at ||= Time.now
+          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
+          end
+
+        end
+
+        # This method will be called when the BaseLoader is created
+        # @note
+        #   - this method should implement the loading logics for the given `Children` class.
+        def initialize
+          raise "You should implement this method"
+        end
+
+        def name
+          self.class.name
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,109 @@
+module Eco
+  module API
+    module Common
+      # Helpers for dynamic object loading based on class declaration
+      # @note
+      #   - this helpers aim to boost the usage of the ruby language in complex api configurations.
+      module ClassAutoLoader
+        include Eco::API::Common::ClassHelpers
+
+        # To enable the class autoloader, you should use this  method
+        def autoloads_children_of(klass)
+          class_resolver :autoloader_class, klass
+          @autoloaded_class = klass
+        end
+
+        # Resolves the class `autoloader_class` if it has been defined via `autoloads_children_of`
+        def autoloaded_class
+          return nil unless @autoloaded_class
+          autoloader_class
+        end
+
+        # To which restricted namespaces this class autoloads from
+        def autoloaded_namespaces(type = :include)
+          @autoloaded_namespaces       ||= {}
+          @autoloaded_namespaces[type] ||= []
+        end
+
+        # To restrict which namespaces it is allowed to load from
+        def autoload_namespace(*namespaces)
+          _autoload_namespace(:include, *namespaces)
+        end
+
+        # To ignore certain namespaces this class should not autoload from
+        def autoload_namespace_ignore(*namespaces)
+          _autoload_namespace(:ignore, *namespaces)
+        end
+
+        def _autoload_namespace(type, *namespaces)
+          autoloaded_namespaces(type).concat(namespaces) unless namespaces.empty?
+        end
+
+        # @param constant [Class, String] a class or namespace we want to check auto-load entitlement thereof.
+        # @return [Boolean] determines if a given namespace is entitled for autoloading
+        def autoload_class?(constant)
+          constants = "#{constant}".split("::").compact
+          autoload = true
+          unless autoloaded_namespaces(:include).empty?
+            autoload = autoloaded_namespaces(:include).any? do |ns|
+              "#{ns}".split("::").compact.zip(constants).all? {|(r, c)| r == c}
+            end
+          end
+          unless autoloaded_namespaces(:ignore).empty?
+            autoload &&= autoloaded_namespaces(:ignore).none? do |ns|
+              "#{ns}".split("::").compact.zip(constants).all? {|(r, c)| r == c}
+            end
+          end
+          autoload
+        end
+
+        # As children are loaded as they are declared, we should not load twice same children.
+        def autoloaded_children
+          @auto_loaded_children ||= []
+        end
+
+        # Children classes of `autoloader_class` that have not been created an instance of.
+        def unloaded_children
+          return [] unless autoloaded_class
+          new_detected = new_classes
+          known_class!(*new_detected)
+          descendants(parent_class: autoloaded_class, scope: new_detected).select do |child_class|
+            !autoloaded_children.include?(child_class) && autoload_class?(child_class)
+          end.sort
+        end
+
+        # It loads/creates a new instance of children classes pending to be loaded.
+        # @return [Boolean] `true` if there were children loaded, `false` otherwise.
+        def autoload_children(object)
+          return false if !autoloaded_class || @loading_children
+          pending_children = unloaded_children
+          return false if pending_children.empty?
+          @loading_children = true
+          pending_children.each do |klass|
+            @child = klass.new(object)
+            autoloaded_children.push(klass)
+          end
+          @loading_children = false
+          true
+        end
+
+        # Known namespaces serves the purpose to discover recently added namespaces
+        #   provided that the namespace discovery is optimized
+        def known_classes
+          @known_classes ||= []
+        end
+
+        # Add to known namespaces
+        def known_class!(*classes)
+          known_classes.concat(classes)
+        end
+
+        # List all new namespaces
+        def new_classes
+          ObjectSpace.each_object(::Class).to_a - known_classes
+        end
+
+      end
+    end
+  end
+end

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

@@ -3,11 +3,14 @@ module Eco
     module Common
       module ClassHelpers
 
+        # Creates an class and instance object methods with name `name` to resolve `klass` name
         def class_resolver(name, klass)
           define_singleton_method(name) { resolve_class(klass) }
           define_method(name) { self.class.resolve_class(klass) }
         end
 
+        # With given a `klass` name it resolves to an actual `Class`
+        # @return [Class] the class that was being searched by name `klass`.
         def resolve_class(klass, exception: true)
           @resolved ||= {}
           @resolved[klass] ||=
@@ -59,6 +62,36 @@ module Eco
           end
         end
 
+        # Finds all child classes of the current class.
+        # @param parent_class [Class] the parent class we want to find children of.
+        # @param direct [Boolean] it will only include direct child classes.
+        # @param scope [nil, Array] to only look for descendants among the ones in `scope`.
+        # @return [Arrary<Class>] the child classes in hierarchy order.
+        def descendants(parent_class: self, direct: false, scope: nil)
+          scope ||= ObjectSpace.each_object(::Class)
+          return [] if scope.empty?
+          scope.select do |klass|
+            klass < parent_class
+          end.sort do |k1, k2|
+            next -1 if k2 < k1
+            next  1 if k1 < k2
+            0
+          end.tap do |siblings|
+            if direct
+              siblings.reject! do |si|
+                siblings.any? {|s| si < s}
+              end
+            end
+          end
+        end
+
+        # @param parent_class [Class] the parent class we want to find children of.
+        # @param direct [Boolean] it will only include direct child classes.
+        # @return [Boolean] `true` if the current class has child classes, and `false` otherwise.
+        def descendants?(parent_class: self, direct: false)
+          descendants(parent_class: parent_class, direct: direct).length > 0
+        end
+
       end
     end
   end