ecoportal-api 0.8.2 → 0.8.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ba5ffaf73f0c065f6aa6572b5ac82132af9ee19f61692f80605ee156b29d24ee
-  data.tar.gz: d82d89d09d4ae1edb88a3dc01f613478e7bd5ab38184dadb7c507e53e65bae54
+  metadata.gz: 4364abf59cd6460788d315eb5012df5e8ad254a208e8af7314a766463eb35ed0
+  data.tar.gz: d71fe7e38402e827aea0f95c6a0c379e191e525d597ab8b225990f48c6879764
 SHA512:
-  metadata.gz: f3b637bd2bc2970b7f46eb8d92edc6b83a38ef4489d6d185e4cea47d8a5e6cd774d9bf9e8712bd0d76aa9a52c770e89207f0c7af283fcb85bc1cb481d31fca10
-  data.tar.gz: 6a5dd4dd6fd2691971c526e79d2278a84351484a0d9ffdd93e3604392f4b59e21515255001c51016835a37506496d1d292f33c4dc69d4db7042e9c3d521721c3
+  metadata.gz: e055587b4aafbfabf25996cf4e67d85b0a0d9be936d4b0bdae194b431e4f2bb12b09fc99562d594cf355767aae3081a1fbea70d10a48dc204ce839284bbf0256
+  data.tar.gz: 5cd7284e455af271f1642775844636fd0ea11b590c0036d3b4a43868a9ffd6ece97ceebb9a3d6dfcdae7891dd65dedd0df9dac5944578cb18484b07342640c3e

data/CHANGELOG.md

@@ -1,7 +1,92 @@
 # Change Log
 All notable changes to this project will be documented in this file.
 
-## [0.8.2] - 2021-02-xx
+## [0.8.5] - 2022-02-28
+
+### Added
+  - `Ecoportal::API::V1::PersonDetails#[]` to raise a specific error type to allow handling
+  - `Ecoportal::API::V1::PersonDetails.key?` to allow to check if a field exists
+  - `Ecoportal::API::Internal::Account#force_send_invites` support for back-end new method
+
+### Fixed
+  - `Ecoportal::API::V1::People#get` fixed typo
+  - `Ecoportal::API::Common::BaseModel` `#original_doc` and `#initial_doc` maybe empty for the parent object
+
+### Changed
+  - `Ecoportal::API::V1::People#each` limited the `GET` retries to `5`
+  - `Ecoportal::API::Internal::Account#default_tag=`
+    - Controls input type to be `String` or `nil`
+    - Inherent `upcase`
+
+## [0.8.4] - 2021-11-05
+
+### Added
+  - `Ecoportal::API::Internal::Permissions` added abilities
+    - `visitor_management`, `cross_register_reporting` and `broadcast_notifications`
+  - Some yardocs too
+    - Some callbacks are done in a non-obvious way and the returned object type was not documented
+    - For this reason, some yardocs have been added to some of the parts that have been worked on.
+
+### Fixed
+  - `Ecoportal::API::V1::People#create_job`
+    - **Removed** call to `BatchOperation#process_response`
+      - The method was is already called by `job_result`
+      - As a consequence there was a double up of `callbacks`
+    - **Fixed** line in wrong position
+  - `Ecoportal::API::V1::People#batch`
+  - `Ecoportal::API::Common::ElasticApmIntegration#unexpected_server_error?`
+    - No code or code lesser than 100 is a server error as well
+
+### Changed
+  - `Ecoportal::API::Common::Client`: changed
+    - Logging the **response** of batches or batch jobs can be handy when debugging the back-end
+    - **removed** method `#without_response_logging`
+      - This change entailed to remove dependencies in `Ecoportal::API::V1::People`
+        - Specifically in methods `#batch`, `#job_result` and `#create_job`
+    - `@response_logging_enabled` to be set in initialization stage (added parameter for `.new`)
+
+## [0.8.3] - 2021-05-24
+
+### Added
+  - `Ecoportal::API::Errors` namespace
+    - `Ecoportal::API::Errors::Base` base error class.
+    - `Ecoportal::API::Errors::TimeOut` error when an api request fails with time out.
+      - This serves the purpose to allow a client script to re-start the process where it stopped by capturing this specific Error
+  - `Ecoportal::API::Common::BaseModel::UnlinkedModel` added more description to track down the source of the error.
+  - `Ecoportal::API::Common::BaseModel#reset!` added parameter `key`, which should try to recover `doc[key]` from `original_doc[key]`
+    - Thanks to this, you are supposed to be able to do things like:
+      - `person.account = nil && person.reset!("account")`
+      - `person.name    = nil && person.reset!("name")`
+  - `Ecoportal::API::V1::People#job` methods to provide more information on failure.
+  - Specific changes due to eP **release `1.5.9.70`** (_Policy Group Abilities_)
+    - `Ecoportal::API::Internal::Account#permissions_merged`
+    - `Ecoportal::API::Internal::Permissions#person_abilities` (new ability)
+    - `Ecoportal::API::Internal::Account#user_id`
+
+### Fixed
+  - `Ecoportal::API::Internal::Account`: consistency in setting arrays (`uniq!` & `compact`)
+    - `#policy_group_ids=`, `#login_provider_ids=`, `#starred_ids=`
+  - `Ecoportal::API::Common::HashDiff.diff` was including empty `{}` objects
+    - This change sacrifices the case `account: {}` (which will be also removed from `as_update`), but it should be fine.
+
+### Changed
+  - `Ecoportal::API::V1::People#job` to raise specific error on time out `API::Errors::TimeOut`
+  - Specific changes due to eP **release `1.5.9.70`** (_Policy Group Abilities_)
+    - `Ecoportal::API::Internal::Account` **removed** methods: `#permissions_preset`, `#preset` and `#preset=`
+    - `Ecoportal::API::Internal::Person#account=` added support for `user_id` which should remain unchanged when existing
+  - **remove** from `as_update` **read-only** data
+    - `Ecoportal::API::Common::HashDiff.diff` added parameter `:ignore` (`Array`)
+    - `Ecoportal::API::Common::BaseModel#as_update` added parameter `:ignore`
+    - `Ecoportal::API::V1::Person#as_update` added method, which ignores `subordinates`
+    - `Ecoportal::API::Internal::Person#as_update` added method, which ignores `user_id`, `permissions_merged` and `prefilter`
+    - `Ecoportal::API::Internal::Account#as_update` added method, which ignores `user_id`, `permissions_merged` and `prefilter`
+    - `Ecoportal::API::Common::Client` native support for `elastic-apm`
+      - Via new module `Ecoportal::API::Common::ElasticApmIntegration` with method `log_unexpected_server_error`, which will only log an `UnexpectedServerError` to _ElasticAPM_ if
+        1. There's a correct configuration: environmental variables `ELASTIC_APM_KEY` and `ELASTIC_APM_ACCOUNT_ID` are defined
+        2. The `Response` from the server gave `code` in the range `5xx` (which are those under server responsibility)
+    - `Ecoportal::API::Common::Client` added retry logics when `response.status == 5xx`
+
+## [0.8.2] - 2021-02-24
 
 ### Added
 

data/ecoportal-api.gemspec

@@ -22,7 +22,7 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_development_dependency "bundler",   ">= 2.2.11",  "< 2.3"
+  spec.add_development_dependency "bundler",   ">= 2.2.17",  "< 2.3"
   spec.add_development_dependency "rspec",     ">= 3.10.0", "< 3.11"
   spec.add_development_dependency "rake",      ">= 13.0.3", "< 13.1"
   spec.add_development_dependency "yard",      ">= 0.9.26", "< 0.10"
@@ -30,5 +30,7 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency "pry"      , "~> 0.14"
 
   spec.add_dependency 'http',          '~> 4.4.1', "< 5"
+  spec.add_dependency 'dotenv',        '>= 2.7.6', "< 2.8"
+  spec.add_dependency 'elastic-apm',   '>= 4.0.0', "< 4.1"
   spec.add_dependency 'hash-polyfill', '~> 0'
 end

data/lib/ecoportal/api/common/base_model.rb

@@ -3,7 +3,9 @@ module Ecoportal
     module Common
       class BaseModel
         class UnlinkedModel < Exception
-          def initialize (msg = "Something went wrong when linking the document.")
+          def initialize (msg = "Something went wrong when linking the document.", from: nil, key: nil)
+            msg += " From: #{from}." if from
+            msg += " key: #{key}."   if key
             super(msg)
           end
         end
@@ -28,7 +30,12 @@ module Ecoportal
             var    = "@#{method}".freeze
             key    = key.to_s.freeze
             define_method(method) do
-              return instance_variable_get(var) if instance_variable_defined?(var)
+              if instance_variable_defined?(var)
+                value = instance_variable_get(var)
+                return value unless nullable
+                return value if (value && doc[key]) || (!value && !doc[key])
+                remove_instance_variable(var)
+              end
               doc[key] ||= {} unless nullable
               return instance_variable_set(var, nil) unless doc[key]
 
@@ -53,21 +60,21 @@ module Ecoportal
         end
 
         def doc
-          raise UnlinkedModel.new  unless linked?
+          raise UnlinkedModel.new(from: "#{self.class}#doc", key: _key)  unless linked?
           return @doc if is_root?
           _parent.doc.dig(*[_key].flatten)
         end
 
         def original_doc
-          raise UnlinkedModel.new  unless linked?
+          raise UnlinkedModel.new(from: "#{self.class}#original_doc", key: _key)  unless linked?
           return @original_doc if is_root?
-          _parent.original_doc.dig(*[_key].flatten)
+          _parent.original_doc&.dig(*[_key].flatten)
         end
 
         def initial_doc
-          raise UnlinkedModel.new  unless linked?
+          raise UnlinkedModel.new(from: "#{self.class}#initial_doc", key: _key)  unless linked?
           return @initial_doc if is_root?
-          _parent.initial_doc.dig(*[_key].flatten)
+          _parent.initial_doc&.dig(*[_key].flatten)
         end
 
         def as_json
@@ -78,18 +85,19 @@ module Ecoportal
           doc.to_json(*args)
         end
 
-        def as_update(ref = :last)
+        def as_update(ref = :last, ignore: [])
           new_doc = as_json
           ref_doc = ref == :total ? initial_doc : original_doc
-          Common::HashDiff.diff(new_doc, ref_doc)
+          Common::HashDiff.diff(new_doc, ref_doc, ignore: ignore)
         end
 
         def dirty?
           as_update != {}
         end
 
+        # It consolidates all the changes carried by `doc` by setting it as `original_doc`.
         def consolidate!
-          raise UnlinkedModel.new  unless linked?
+          raise UnlinkedModel.new(from: "#{self.class}#consolidate!", key: _key)  unless linked?
           new_doc = JSON.parse(doc.to_json)
           if is_root?
             @original_doc = new_doc
@@ -98,13 +106,32 @@ module Ecoportal
           end
         end
 
-        def reset!
-          raise UnlinkedModel.new  unless linked?
-          new_doc = JSON.parse(original_doc.to_json)
-          if is_root?
-            @doc = new_doc
+        # It removes all the changes carried by `doc` by restoring `original_doc` into `doc`.
+        # @note
+        #   1. When there are nullable properties, it may be required to apply `reset!` from the parent
+        #    i.e. `parent.reset!("child")` # when parent.child is `nil`
+        #   2. In such a case, only immediate childs are allowed to be reset
+        # @param key [String, Array<String>, nil] if given, it only resets the specified property
+        def reset!(key = nil)
+          raise "'key' should be a String. Given #{key}" unless !key || key.is_a?(String)
+          raise UnlinkedModel.new(from: "#{self.class}#reset!", key: _key)  unless linked?
+
+          if key
+            if self.respond_to?(key) && child = self.send(key) && child.is_a?(Ecoportal::API::Common::BaseModel)
+              child.reset!
+            else
+              new_doc = original_doc && original_doc[key]
+              dig_set(doc, [key], new_doc && JSON.parse(new_doc.to_json))
+              # regenerate object if new_doc is null
+              self.send(key) if !new_doc && self.respond_to?(key)
+            end
           else
-            dig_set(_parent.doc, [_key].flatten, new_doc)
+            new_doc = JSON.parse(original_doc.to_json)
+            if is_root?
+              @doc = new_doc
+            else
+              dig_set(_parent.doc, [_key].flatten, new_doc)
+            end
           end
         end
 
@@ -133,6 +160,17 @@ module Ecoportal
           end
         end
 
+        def set_uniq_array_keep_order(key, value)
+          unless value.is_a?(Array)
+            raise "#{key}= needs to be passed an Array, got #{value.class}"
+          end
+          ini_vals = (original_doc && original_doc[key]) || []
+
+          value    = value.uniq
+          # preserve original order to avoid false updates
+          doc[key] = ((ini_vals & value) + (value - ini_vals)).compact
+        end
+
       end
     end
   end

data/lib/ecoportal/api/common/client.rb

@@ -10,6 +10,9 @@ module Ecoportal
       #     - to return `HTTP::Response` ([response.rb](https://github.com/httprb/http/blob/master/lib/http/response.rb))
       # @attr_reader logger [Logger] the logger.
       class Client
+        include Common::ElasticApmIntegration
+        DELAY_REQUEST_RETRY = 5
+
         attr_accessor :logger
 
         # @note the `api_key` will be automatically added as parameter `X-ApiKey` in the header of the http requests.
@@ -17,11 +20,14 @@ module Ecoportal
         # @param version [String] it is part of the base url and will determine the api version we query against.
         # @param host [String] api server domain.
         # @param logger [Logger] an object with `Logger` interface to generate logs.
+        # @param response_logging [Boolean] whether or not batch responses should be logged
         # @return [Client] an object that holds the configuration of the api connection.
-        def initialize(api_key:, version: "v1", host: "live.ecoportal.com", logger: nil)
+        def initialize(api_key:, version: "v1", host: "live.ecoportal.com", logger: nil, response_logging: false)
           @version  = version
           @api_key  = api_key
           @logger   = logger
+          @host     = host
+          @response_logging_enabled = response_logging
           if host.match(/^localhost|^127\.0\.0\.1/)
             @base_uri = "http://#{host}/api/"
           else
@@ -31,7 +37,6 @@ module Ecoportal
           if @api_key.nil? || @api_key.match(/\A\W*\z/)
             log(:error) { "Api-key missing!" }
           end
-          @response_logging_enabled = true
         end
 
         # Logger interface.
@@ -106,7 +111,7 @@ module Ecoportal
         # basic HTTP connection to the block.
         # @yield [http] launch specific http request.
         # @yieldparam http [HTTP] the http connection.
-        # @yieldreturn [Common::Response] the basic custom reponse object.
+        # @yieldreturn [Common::Response] the basic custom response object.
         # @return [Common::Reponse] the basic custom response object.
         def request
           wrap_response yield(base_request)
@@ -140,22 +145,15 @@ module Ecoportal
           @base_uri+@version+path
         end
 
-        def without_response_logging(&block)
-          begin
-            @response_logging_enabled = false
-            yield self
-          ensure
-            @response_logging_enabled = true
-          end
-        end
-
         private
 
-        def instrument(method, path, data = nil)
+        def instrument(method, path, data = nil, &block)
+          raise "Expected block" unless block
           start_time = Time.now.to_f
-          log(:info) { "#{method} #{url_for(path)}" }
+          log(:info)  { "#{method} #{url_for(path)}" }
           log(:debug) { "Data: #{JSON.pretty_generate(data)}" }
-          yield.tap do |result|
+
+          with_retry(&block).tap do |result|
             end_time = Time.now.to_f
             log(result.success?? :info : :warn) do
               "Took %.2fs, Status #{result.status}" % (end_time - start_time)
@@ -165,6 +163,33 @@ module Ecoportal
             end if @response_logging_enabled
           end
         end
+
+        # Helper to ensure unexpected server errors do not bring client scripts immediately down
+        def with_retry(attempts = 3, delay = DELAY_REQUEST_RETRY, error_safe: true, &block)
+          response = nil
+          attempts.times do |i|
+            remaining = attempts - i - 1
+            begin
+              response = block.call
+            rescue HTTP::ConnectionError => e
+              raise unless error_safe && remaining > 0
+              log(:error) { "Got connection error: #{e.message}" }
+              response = with_retry(remaining, error_safe: error_safe, &block)
+            rescue IOError => e
+              raise unless error_safe && remaining > 0
+              log(:error) { "Got IO error: #{e.message}" }
+              response = with_retry(remaining, error_safe: error_safe, &block)
+            end
+            return response unless unexpected_server_error?(response.status)
+            log_unexpected_server_error(response)
+            msg  = "Got server error (#{response.status}): #{response.body}\n"
+            msg += "Going to retry (#{i} out of #{attempts})"
+            log(:error) { msg }
+            sleep(delay) if i < attempts
+          end
+          response
+        end
+
       end
     end
   end

data/lib/ecoportal/api/common/elastic_apm_integration.rb

@@ -0,0 +1,112 @@
+require 'elastic-apm'
+module Ecoportal
+  module API
+    module Common
+      module ElasticApmIntegration
+
+        class UnexpectedServerError < StandardError
+          def initialize(code, msg)
+            super("Code: #{code} -- Error: #{msg}")
+          end
+        end
+
+        APM_SERVICE_NAME = 'ecoportal-api-gem'
+
+        # Log only errors that are only server's responsibility
+        def log_unexpected_server_error(response)
+          raise "Expecting Ecoportal::API::Common::Response. Given: #{response.class}" unless response.is_a?(Common::Response)
+          return nil unless elastic_apm_service
+          return nil unless unexpected_server_error?(response.status)
+          if ElasticAPM.running?
+            ElasticAPM.report(UnexpectedServerError.new(response.status, response.body))
+          end
+        end
+
+        private
+
+        def unexpected_server_error?(code)
+          !code || ((code >= 500) && (code <= 599)) || (code <= 99)
+        end
+
+        # finalizer to stop the agent
+        close_elastic_apm = Proc.new do |id|
+          begin
+            if ElasticAPM.running?
+              puts "Stopping ElasticAPM service"
+              ElasticAPM.stop
+            end
+          rescue StandardError => e
+            # Silent
+          end
+        end
+        ObjectSpace.define_finalizer("ElasticAPM", close_elastic_apm)
+
+        def elastic_apm_service
+          return false if @disable_apm
+          begin
+            ElasticAPM.start(**elastic_apm_options) unless ElasticAPM.running?
+          rescue StandardError => e
+            @disable_apm = true
+            puts "ElasticAPM services not available: #{e}"
+          end
+        end
+
+        def elastic_apm_options
+          {
+            service_name: APM_SERVICE_NAME,
+            server_url:   elastic_apm_url,
+            secret_token: elastic_apm_key,
+            environment:  environment,
+            #http_compression: false,
+            transaction_sample_rate:  0.1,
+            transaction_max_spans:    100,
+            span_frames_min_duration: "5ms"
+          }.tap do |options|
+            options.merge!({
+              log_level: Logger::DEBUG,
+              log_path:  File.join(__dir__, "elastic_apm.log")
+            }) if false
+          end
+        end
+
+        def elastic_apm_url
+          @elastic_apm_url ||= "https://".tap do |url|
+            url << "#{elastic_apm_account_id}"
+            url << ".#{elastic_apm_base_url}"
+            url << ":#{elastic_apm_port}"
+          end
+        end
+
+        def elastic_apm_key
+          @elastic_apm_key ||= ENV['ELASTIC_APM_KEY']
+        end
+
+        def elastic_apm_account_id
+          @elastic_apm_account_id ||= ENV['ELASTIC_APM_ACCOUNT_ID']
+        end
+
+        def elastic_apm_base_url
+          @elastic_apm_base_url ||= "apm.#{elastic_apm_region}.aws.cloud.es.io"
+        end
+
+        def elastic_apm_region
+          @elastic_apm_region ||= ENV['ELASTIC_APM_REGION'] || "ap-southeast-2"
+        end
+
+
+        def elastic_apm_port
+          @elastic_apm_port ||= ENV['ELASTIC_APM_PORT'] || "443"
+        end
+
+        def environment
+          @environment ||= "unknown".tap do |value|
+            if instance_variable_defined?(:@host) && env = @host.gsub(".ecoportal.com", '')
+              value.clear << env
+            end
+          end
+        end
+
+      end
+    end
+  end
+end

data/lib/ecoportal/api/common/hash_diff.rb

@@ -5,15 +5,16 @@ module Ecoportal
         ID_KEYS = %w[id]
 
         class << self
-          def diff(a, b)
-            return a if a.class != b.class
+
+          def diff(a, b, ignore: [])
             case a
             when Hash
               {}.tap do |diffed|
                 a.each do |key, a_value|
-                  b_value = b[key]
-                  next if a_value == b_value && !ID_KEYS.include?(key)
-                  diffed[key] = diff(a_value, b_value)
+                  b_value    = b && b[key]
+                  no_changes = (a_value == b_value) || ignore.include?(key)
+                  next if !ID_KEYS.include?(key) && no_changes
+                  diffed[key] = diff(a_value, b_value, ignore: ignore)
                   diffed.delete(key) if diffed[key] == {}
                 end
                 # All keys are IDs, so it's actually blank
@@ -22,10 +23,10 @@ module Ecoportal
                 end
               end
             when Array
-              return a unless a.length == b.length
+              return a unless b.is_a?(Array) && a.length == b.length
               a.map.with_index do |a_value, idx|
                 b_value = b[idx]
-                diff(a_value, b_value)
+                diff(a_value, b_value, ignore: ignore)
               end.reject do |el|
                 el == {}
               end

data/lib/ecoportal/api/common.rb

@@ -10,6 +10,7 @@ require 'ecoportal/api/common/hash_diff'
 require 'ecoportal/api/common/base_model'
 require 'ecoportal/api/common/doc_helpers'
 require 'ecoportal/api/common/logging'
+require 'ecoportal/api/common/elastic_apm_integration'
 require 'ecoportal/api/common/client'
 require 'ecoportal/api/common/response'
 require 'ecoportal/api/common/wrapped_response'

data/lib/ecoportal/api/errors/base.rb

@@ -0,0 +1,8 @@
+module Ecoportal
+  module API
+    module Errors
+      class Base < StandardError
+      end
+    end
+  end
+end

data/lib/ecoportal/api/errors/time_out.rb

@@ -0,0 +1,8 @@
+module Ecoportal
+  module API
+    module Errors
+      class TimeOut < Errors::Base
+      end
+    end
+  end
+end

data/lib/ecoportal/api/errors.rb

@@ -0,0 +1,9 @@
+module Ecoportal
+  module API
+    module Errors
+    end
+  end
+end
+
+require 'ecoportal/api/errors/base'
+require 'ecoportal/api/errors/time_out'

data/lib/ecoportal/api/internal/account.rb

@@ -2,29 +2,43 @@ module Ecoportal
   module API
     class Internal
       class Account < Common::BaseModel
-        passthrough :policy_group_ids, :landing_page_id, :permissions_preset, :permissions_custom,
-          :preferences, :prefilter, :login_provider_ids, :starred_ids, :accept_eula,
-          :send_invites, :default_tag
+        PROPERTIES = [
+          "user_id", "policy_group_ids", "default_tag", "prefilter",
+          "permissions_custom", "permissions_merged", "preferences",
+          "login_provider_ids", "starred_ids", "landing_page_id",
+          "accept_eula", "send_invites", "force_send_invites"
+        ]
+        passthrough *PROPERTIES.map(&:to_sym)
 
         class_resolver :preferences_class, "Ecoportal::API::Internal::Preferences"
         class_resolver :permissions_class, "Ecoportal::API::Internal::Permissions"
 
         embeds_one  :permissions, key: "permissions_custom", klass: :permissions_class
+        embeds_one  :perms_merged, key: "permissions_merged", klass: :permissions_class
         embeds_one  :preferences, klass: :preferences_class
 
+        # Sets the `default_tag` of the user
+        # @note it upcases the value
+        # @param value [String, nil] the tag
+        # @return [String, nil] the value set in `default_tag`
+        def default_tag=(value)
+          unless !value || value.is_a?(String)
+            raise ArgumentError.new("default_tag= needs to be passed a String or nil, got #{value.class}")
+          end
+          if value
+            unless value.match(Ecoportal::API::V1::Person::VALID_TAG_REGEX)
+              raise ArgumentError.new("Invalid default tag #{value.inspect}")
+            end
+            value = value.upcase
+          end
+          doc["default_tag"] = value
+        end
+
         # Sets the `policy_group_ids`
         # @note it preserves the original order
         # @param value [Array<String>] the policy group ids to be set.
         def policy_group_ids=(value)
-          unless value.is_a?(Array)
-            raise "policy_group_ids= needs to be passed an Array, got #{value.class}"
-          end
-
-          value.uniq!
-          ini_ids = (original_doc && original_doc["policy_group_ids"]) || []
-          # preserve original order to avoid false updates
-          doc["policy_group_ids"] = (ini_ids & value) + (value - ini_ids)
-          doc["policy_group_ids"].compact
+          set_uniq_array_keep_order("policy_group_ids", value)
         end
 
         # @return [Array<String>] the policy group ids of this user.
@@ -34,10 +48,7 @@ module Ecoportal
 
         # Sets the `login_provider_ids`
         def login_provider_ids=(value)
-          unless value.is_a?(Array)
-            raise "login_provider_ids= needs to be passed an Array, got #{value.class}"
-          end
-          doc["login_provider_ids"] = value.compact
+          set_uniq_array_keep_order("login_provider_ids", value)
         end
 
         # @return [Array<String>] the login provider ids of this user.
@@ -47,10 +58,7 @@ module Ecoportal
 
         # Sets the `starred_ids`
         def starred_ids=(value)
-          unless value.is_a?(Array)
-            raise "starred_ids= needs to be passed an Array, got #{value.class}"
-          end
-          doc["starred_ids"] = value.compact
+          set_uniq_array_keep_order("starred_ids", value)
         end
 
         # @return [Array<String>] the starred page ids of this user.
@@ -58,20 +66,6 @@ module Ecoportal
           doc["starred_ids"] ||= []
         end
 
-        # Sets the `permissions_preset`.
-        # @note basically the same as `permissions_preset=` but when `"custom"`, it's changed to `nil`
-        # @param value [nil, String] preset name.
-        def preset=(value)
-          self.permissions_preset = value == "custom" ? nil : value
-        end
-
-        # Gets the `permissions_preset`.
-        # @note basically the same as `permissions_preset` but when 'nil', it returns `"custom"` instead
-        # @return [nil, String] preset name.
-        def preset
-          self.permissions_preset.nil? ? "custom" : self.permissions_preset
-        end
-
         # It preserves the values of keys that are not defined in `value`.
         # @param value [Hash] the abilities that you want to update.
         def permissions_custom=(value)
@@ -88,15 +82,16 @@ module Ecoportal
 
         def as_json
           super.tap do |hash|
-            if preset == "custom"
-              hash["permissions_custom"] = permissions.as_json
-            else
-              hash.delete "permissions_custom"
-            end
+            hash["permissions_custom"] = permissions.as_json
+            hash["permissions_merged"] = perms_merged.as_json
             hash["preferences"] = preferences.as_json
           end
         end
 
+        def as_update(ref = :last, ignore: [])
+          super(ref, ignore: ignore | ["user_id", "permissions_merged", "prefilter"])
+        end
+
       end
     end
   end

data/lib/ecoportal/api/internal/permissions.rb

@@ -3,9 +3,10 @@ module Ecoportal
     class Internal
       class Permissions < Common::BaseModel
         passthrough :files, :data, :reports
-        passthrough :organization, :person_core, :person_core_create, :person_core_edit
-        passthrough :person_account, :person_details
-        passthrough :pages, :page_editor, :registers, :tasks
+        passthrough :organization, :pages, :page_editor, :registers, :tasks
+        passthrough :person_core, :person_core_create, :person_core_edit
+        passthrough :person_details, :person_account, :person_abilities
+        passthrough :visitor_management, :broadcast_notifications, :cross_register_reporting
       end
     end
   end

data/lib/ecoportal/api/internal/person.rb

@@ -11,10 +11,14 @@ module Ecoportal
           super.update("account" => account&.as_json)
         end
 
+        def as_update(ref = :last, ignore: [])
+          super(ref, ignore: ignore | ["user_id", "permissions_merged", "prefilter"])
+        end
+
         # Sets the Account to the person, depending on the paramter received:
         #  - `nil`: blanks the account.
         #  - `Account`: sets a copy of the object param as account.
-        #  - `Hash`: slices the properties of `Account`.
+        #  - `Hash`: slices the properties of `Account` (keeping the value of `user_id` if there was already account).
         # @note this method does not make dirty the account (meaning that `as_json` will be an empty hash `{}`)
         # @param value [nil, Account, Hash] value to be set.
         # @return [nil, Account] the resulting `Account` set to the person.
@@ -25,7 +29,9 @@ module Ecoportal
           when Internal::Account
             doc["account"] = JSON.parse(value.to_json)
           when Hash
-            doc["account"] = value.slice(*%w[policy_group_ids default_tag landing_page_id permissions_preset permissions_custom preferences prefilter login_provider_ids starred_ids])
+            user_id = account.user_id if account
+            doc["account"] = value.slice(*Internal::Account::PROPERTIES)
+            doc["account"]["user_id"] = user_id if user_id
           else
             # TODO
             raise "Invalid set on account: Need nil, Account or Hash; got #{value.class}"

data/lib/ecoportal/api/v1/people.rb

@@ -36,8 +36,15 @@ module Ecoportal
           puts "\n" unless silent
           loop do
             params.update(cursor_id: cursor_id) if cursor_id
-            response = client.get("/people", params: params)
-            body     = body_data(response.body)
+            body = nil; response = nil; count = 5
+            loop do
+              response = client.get("/people", params: params)
+              body     = response && body_data(response.body)
+              break if response.success? || count <= 0
+              puts "Request failed - Status #{response.status}: #{body}"
+              count -= 1
+              sleep(0.5)
+            end
             raise "Request failed - Status #{response.status}: #{body}" unless response.success?
 
             unless silent || (total = body["total_results"]) == 0
@@ -77,7 +84,7 @@ module Ecoportal
           response = client.get("/people/"+CGI.escape(id))
           body     = body_data(response.body)
           return person_class.new(body) if response.success?
-          raise "Could not get person #{id} - Error #{reponse.status}: #{body}"
+          raise "Could not get person #{id} - Error #{response.status}: #{body}"
         end
 
         # Requests an update of a person via api.
@@ -117,29 +124,30 @@ module Ecoportal
         # Creates a `BatchOperation` and yields it to the given bock.
         # @yield [batch_op] adds multiple api requests for the current batch.
         # @yieldparam batch_op [BatchOperation]
+        # @param job_mode [Boolean] whether or not it should use batch jobs
+        # @return [Ecoportal::API::Common::Response] the results of the batch
         def batch(job_mode: true, &block)
           return job(&block) if job_mode
           operation = Common::BatchOperation.new("/people", person_class, logger: client.logger)
           yield operation
           # The batch operation is responsible for logging the output
-          client.without_response_logging do
-            client.post("/people/batch", data: operation.as_json).tap do |response|
-              operation.process_response(response)
-            end
+          client.post("/people/batch", data: operation.as_json).tap do |response|
+            operation.process_response(response)
           end
         end
 
+        # @return [Ecoportal::API::Common::Response] the results of the batch job
         def job
           operation = Common::BatchOperation.new("/people", person_class, logger: client.logger)
           yield operation
-          # The batch operation is responsible for logging the output
           job_id = create_job(operation)
           status = wait_for_job_completion(job_id)
 
           if status&.complete?
-            operation.process_response job_result(job_id, operation)
+            job_result(job_id, operation)
           else
-            raise "Job `#{job_id}` not complete. Probably timeout after #{JOB_TIMEOUT} seconds. Current status: #{status}"
+            msg = "Job `#{job_id}` not complete. Probably timeout after #{JOB_TIMEOUT} seconds. Current status: #{status}"
+            raise API::Errors::TimeOut.new msg
           end
         end
 
@@ -154,8 +162,8 @@ module Ecoportal
         JobStatus = Struct.new(:id, :complete?, :errored?, :progress)
         def job_status(job_id)
           response = client.get("/people/job/#{CGI.escape(job_id)}/status")
-          body     = body_data(response.body)
-          raise "Status error" unless response.success?
+          body     = response && body_data(response.body)
+          raise "Status error (#{response.status}) - Errors: #{body}" unless response.success?
           JobStatus.new(
             body["id"],
             body["complete"],
@@ -164,12 +172,10 @@ module Ecoportal
           )
         end
 
+        # @return [Ecoportal::API::Common::Response] the results of the batch job
         def job_result(job_id, operation)
-          # The batch operation is responsible for logging the output
-          client.without_response_logging do
-            client.get("/people/job/#{CGI.escape(job_id)}").tap do |response|
-              operation.process_response(response)
-            end
+          client.get("/people/job/#{CGI.escape(job_id)}").tap do |response|
+            operation.process_response(response)
           end
         end
 
@@ -186,12 +192,12 @@ module Ecoportal
           end
         end
 
+        # @return [String] the `id` of the created batch job
         def create_job(operation)
           job_id = nil
-          client.without_response_logging do
-            client.post("/people/job", data: operation.as_json).tap do |response|
-              job_id = body_data(response.body)["id"]
-            end
+          client.post("/people/job", data: operation.as_json).tap do |response|
+            job_id = body_data(response.body)["id"] if response.success?
+            raise "Could not create job - Error (#{response.status}): #{body_data(response.body)}" unless job_id
           end
           job_id
         end

data/lib/ecoportal/api/v1/person.rb

@@ -64,12 +64,8 @@ module Ecoportal
               raise "Invalid filter tag #{tag.inspect}"
             end
             tag.upcase
-          end.uniq
-
-          ini_tags = (original_doc && original_doc["filter_tags"]) || []
-          # preserve original order to avoid false updates
-          doc["filter_tags"] = (ini_tags & end_tags) + (end_tags - ini_tags)
-          doc["filter_tags"].compact
+          end
+          set_uniq_array_keep_order("filter_tags", end_tags)
         end
 
         # @return [Array<String>] the filter tags of this person.
@@ -81,6 +77,10 @@ module Ecoportal
           super.merge "details" => details&.as_json
         end
 
+        def as_update(ref = :last, ignore: [])
+          super(ignore: ignore | ["subordinates"])
+        end
+
         # Sets the PersonDetails to the person, depending on the paramter received:
         #  - `nil`: blanks the details.
         #  - `PersonDetails`: sets a copy of the object param as details.

data/lib/ecoportal/api/v1/person_details.rb

@@ -2,6 +2,9 @@ module Ecoportal
   module API
     class V1
       class PersonDetails < Common::BaseModel
+        class MissingId < StandardError
+        end
+
         passthrough :schema_id
 
         class_resolver :schema_field_value_class, "Ecoportal::API::V1::SchemaFieldValue"
@@ -43,16 +46,24 @@ module Ecoportal
         end
 
         # Sets the value to one specific field of the PersonDetails.
+        # @raise MisssingId if the `id` or `alt_id` is missing.
         # @param id [String] the `id` or the `alt_id` of the target field.
         # @return [void]
         def []=(id, value)
           if field = get_field(id)
             field.value = value
           else
-            raise "details[#{id.inspect}] is missing. Did you forget to load the schema?"
+            raise MissingId.new("details[#{id.inspect}] is missing. Did you forget to load the schema?")
           end
         end
 
+        # Checks if an `id` or `alt_id` exists
+        # @param id [String] the `id` or the `alt_id` of the target field.
+        # @return [Boolean] `true` if it exists, `false` otherwise
+        def key?(id)
+          @fields_by_id.key?(id) || @fields_by_alt_id.key?(id)
+        end
+
         protected
 
         # Rebuilds the internal `id` and `alt_id` references to the fields.

data/lib/ecoportal/api/v1/schema_field_value.rb

@@ -6,25 +6,24 @@ module Ecoportal
         passthrough :id, :alt_id, :type, :name, :shared, :multiple
 
         def value
-          return @value if defined?(@value)
-          @value = case type
-                   when "text", "phone_number", "number", "boolean", "select"
-                     doc["value"]
-                   when "date"
-                     if doc["value"]
-                       maybe_multiple(doc["value"]) do |v|
-                         Date.iso8601(v)
-                       end
-                     end
-                   else
-                     raise "Unknown type #{type}"
-                   end
+          case type
+          when "text", "phone_number", "number", "boolean", "select"
+           doc["value"]
+          when "date"
+           if doc["value"]
+             maybe_multiple(doc["value"]) do |v|
+               Date.iso8601(v)
+             end
+           end
+          else
+           raise "Unknown type #{type}"
+          end
         end
 
         def value=(value)
           case type
           when "text", "phone_number", "select"
-            doc["value"] = @value = maybe_multiple(value) do |v|
+            doc["value"] = maybe_multiple(value) do |v|
               v&.to_s
             end
           when "number"
@@ -33,23 +32,21 @@ module Ecoportal
                 raise "Invalid number type #{v.class}"
               end
             end
-            doc["value"] = @value = value
+            doc["value"] = value
           when "boolean"
-            doc["value"] = @value = !!value
+            doc["value"] = !!value
           when "date"
             maybe_multiple(value) do |v|
               unless v.nil? || v.respond_to?(:to_date)
                 raise "Invalid date type #{v.class}"
               end
             end
-            @value       = value
-            doc["value"] = maybe_multiple(@value) do |v|
+            doc["value"] = maybe_multiple(value) do |v|
               v&.to_date&.to_s
             end
           else
             raise "Unknown type #{type}"
           end
-          @value
         end
 
         def maybe_multiple(value)

data/lib/ecoportal/api/version.rb

@@ -1,5 +1,5 @@
 module Ecoportal
   module API
-    VERSION = "0.8.2"
+    VERSION = "0.8.5"
   end
 end

data/lib/ecoportal/api.rb

@@ -2,6 +2,7 @@ require "cgi"
 require "logger"
 require "hash-polyfill"
 require "ecoportal/api/version"
+require "dotenv/load"
 
 module Ecoportal
   module API
@@ -10,5 +11,6 @@ end
 
 require "ecoportal/api/logger"
 require "ecoportal/api/common"
+require "ecoportal/api/errors"
 require "ecoportal/api/v1"
 require "ecoportal/api/internal"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ecoportal-api
 version: !ruby/object:Gem::Version
-  version: 0.8.2
+  version: 0.8.5
 platform: ruby
 authors:
 - Tapio Saarinen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-02-23 00:00:00.000000000 Z
+date: 2022-03-31 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -16,7 +16,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.2.11
+        version: 2.2.17
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.3'
@@ -26,7 +26,7 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 2.2.11
+        version: 2.2.17
     - - "<"
       - !ruby/object:Gem::Version
         version: '2.3'
@@ -144,6 +144,46 @@ dependencies:
     - - "<"
       - !ruby/object:Gem::Version
         version: '5'
+- !ruby/object:Gem::Dependency
+  name: dotenv
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.7.6
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 2.7.6
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+- !ruby/object:Gem::Dependency
+  name: elastic-apm
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.1'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.0.0
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '4.1'
 - !ruby/object:Gem::Dependency
   name: hash-polyfill
   requirement: !ruby/object:Gem::Requirement
@@ -189,10 +229,14 @@ files:
 - lib/ecoportal/api/common/batch_response.rb
 - lib/ecoportal/api/common/client.rb
 - lib/ecoportal/api/common/doc_helpers.rb
+- lib/ecoportal/api/common/elastic_apm_integration.rb
 - lib/ecoportal/api/common/hash_diff.rb
 - lib/ecoportal/api/common/logging.rb
 - lib/ecoportal/api/common/response.rb
 - lib/ecoportal/api/common/wrapped_response.rb
+- lib/ecoportal/api/errors.rb
+- lib/ecoportal/api/errors/base.rb
+- lib/ecoportal/api/errors/time_out.rb
 - lib/ecoportal/api/internal.rb
 - lib/ecoportal/api/internal/account.rb
 - lib/ecoportal/api/internal/login_provider.rb
@@ -237,7 +281,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.3.5
 signing_key: 
 specification_version: 4
 summary: A collection of helpers for interacting with the ecoPortal MS's various APIs