ecoportal-api 0.10.10 → 0.10.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 26fb7bdc3007d89987bd3e23d59c7ea0f3290b46bbd6e188c7746f92e9b329c4
-  data.tar.gz: 9b7b5f874fb7d8bd2e20dfe75064b1632815b30e29fe47276b5f9b29a0e9e1a0
+  metadata.gz: 1c2232426e0251d1242aba6d7a0aa65c545b1bf07f273d23403b0daab0ae57d1
+  data.tar.gz: e155ec14f82fa569df5eeb4adcb89eb3848b21c902f01009ab4d5644b42b73c4
 SHA512:
-  metadata.gz: 7a06edd0dca6647c2eb312ad104026f86ee1b2688c3ddc4a2b43aee1ecfc282e50ca5a4893cee98f03c88d0e27f264f762210e688eb70ea20cb25ffd98832dbf
-  data.tar.gz: d6434f2b2549a6d9101a88ba88f5ffd25390b80123dcc214c4600f7e458887fce92230357b44c8ba934e87b11c2777f50e1f91433432ffacd6928cb4e08d7776
+  metadata.gz: 41297931b543449d223f06cb64f46108d96d16141ab8b2a54f10a5bf782d241e8c37060a43807dd4e63d34288f1919c0a716db4a554e5ef4f3da54e42a574561
+  data.tar.gz: d0d7c16a92811f06df6611ae85fe0e93a62abd950ac478a8be0a6dca7c59fe4e064ca06849d974b913c370c65d79a68593c194324984f7cb3045fe0d5476be62

data/.gitignore

@@ -21,3 +21,5 @@ scratch.rb
 
 #byebug
 .byebug_history
+
+.solargraph.yml

data/CHANGELOG.md

@@ -2,14 +2,28 @@
 
 All notable changes to this project will be documented in this file.
 
-## [0.10.11] - 2025-04-xx
+## [0.10.12] - 2025-05-xx
 
 ### Added
 
+- `Client#post` **added** named argument `params` (for the **url** arguments)
+
 ### Changed
 
 ### Fixed
 
+## [0.10.11] - 2025-05-15
+
+### Changed
+
+- `MAX_START_DELAY` to be `120` (it was `60`).
+
+### Fixed
+
+- `PersonDetails#changed?`: `ref` wasn't being used.
+- `Ecoportal::API::V1::Job::Awaiter`
+  - First timer relay should use `ldelay` of 1 second if it's first loop.
+
 ## [0.10.10] - 2025-04-04
 
 ### Fixed

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

@@ -4,9 +4,10 @@ module Ecoportal
     module Common
       class BaseModel
         class UnlinkedModel < StandardError
-          def initialize(msg = 'Something went wrong when linking the document.', from: nil, key: nil)
-            msg << " From: #{from}." if from
-            msg << " key: #{key}."   if key
+          def initialize(msg = nil, from: nil, key: nil)
+            msg ||= 'Something went wrong when linking the document.'
+            msg  << " From: #{from}." if from
+            msg  << " key: #{key}."   if key
             super(msg)
           end
         end

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

@@ -40,6 +40,9 @@ module Ecoportal
             throughput.eta_for(to_count(count), **kargs)
           end
 
+          # @todo introduce `min_wait`
+          #   - The reason is because small batches have still an associated lag
+          #     before the jobs start to run.
           def timeout_for(count, waited: 0, max_wait: nil, approach: :conservative)
             (waited + eta_for(count, approach: approach)).then do |time|
               next time unless max_wait

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

@@ -27,7 +27,8 @@ module Ecoportal
         include WithRetry
         include RateThrottling
 
-        DEFAULT_HOST = 'live.ecoportal.com'.freeze
+        DEFAULT_HOST   = 'live.ecoportal.com'.freeze
+        MAIN_END_POINT = 'api'.freeze
 
         attr_accessor :logger
         attr_reader :host
@@ -47,9 +48,9 @@ module Ecoportal
           @deep_logging = deep_logging
 
           if host.match(/^localhost|^127\.0\.0\.1/)
-            @base_uri = "http://#{host}/api/"
+            @base_uri = "http://#{host}/#{main_end_point}/"
           else
-            @base_uri = "https://#{host}/api/"
+            @base_uri = "https://#{host}/#{main_end_point}/"
           end
 
           if deep_logging?
@@ -58,7 +59,7 @@ module Ecoportal
             }
           end
 
-          return unless @api_key.nil? || @api_key.match(/\A\W*\z/)
+          return unless api_key.nil? || api_key.match(/\A\W*\z/)
           return unless version
 
           log(:error) { 'Api-key missing!' }
@@ -85,11 +86,17 @@ module Ecoportal
         # @note it automatically adds the http header param `Content-Type` as `application/json`
         # @param path [String] the tail that completes the url of the request.
         # @param data [String] the body of the query in json format.
+        # @param params [Hash] the header paramters of the http request (not including the api key).
+        # @option params [String] URL params; will depend on he API being used.
         # @return [Common::Reponse] the basic custom response object.
-        def post(path, data:)
-          instrument('POST', path, data) do
+        def post(path, data:, params: {})
+          instrument('POST', path, params) do
             request do |http|
-              http.post(url_for(path), json: data)
+              http.post(
+                url_for(path),
+                json:   data,
+                params: params
+              )
             end
           end
         end
@@ -144,9 +151,9 @@ module Ecoportal
           @base_request ||=
             case @version
             when 'v2'
-              HTTP.headers('X-ECOPORTAL-API-KEY' => @api_key).accept(:json)
+              HTTP.headers('X-ECOPORTAL-API-KEY' => api_key).accept(:json)
             else
-              HTTP.headers('X-ApiKey' => @api_key).accept(:json)
+              HTTP.headers('X-ApiKey' => api_key).accept(:json)
             end
         end
 
@@ -159,6 +166,8 @@ module Ecoportal
 
         private
 
+        attr_reader :api_key
+
         def instrument(method, path, data = nil, &block)
           raise 'Expected block' unless block_given?
 
@@ -203,6 +212,10 @@ module Ecoportal
           puts "(#{level}) #{yield}"
           logger&.send(level, &block)
         end
+
+        def main_end_point
+          self.class::MAIN_END_POINT
+        end
       end
     end
   end

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

@@ -11,7 +11,7 @@ module Ecoportal
             when Hash
               {}.tap do |diffed|
                 a.each do |key, a_value|
-                  b_value    = b && b[key]
+                  b_value    = b[key] if b
                   no_changes = (a_value == b_value) || ignore.include?(key)
                   next if !ID_KEYS.include?(key) && no_changes
 

data/lib/ecoportal/api/v1/job/awaiter/timer.rb

@@ -11,7 +11,7 @@ module Ecoportal
 
           # The class
           Timer = Struct.new(*TIMER_ARGS) do
-            self::MAX_START_DELAY = 60
+            self::MAX_START_DELAY = 120
 
             attr_reader :timestamp
 
@@ -22,17 +22,24 @@ module Ecoportal
             end
 
             alias_method :original_start, :start
+            # Previous start or current timestamp.
+            # @note in practice this translates into the very first
+            #   timestamp (so it's an absolute start)
             def start
               original_start || timestamp
             end
 
             alias_method :original_last, :last
+            # Previous timestamp.
             def last
               original_last || start
             end
 
             def new(**kargs, &block)
-              self.class.new(**new_kargs.merge(kargs), &block)
+              self.class.new(
+                **new_kargs.merge(kargs),
+                &block
+              )
             end
 
             def job_id
@@ -40,10 +47,14 @@ module Ecoportal
             end
 
             def complete?
+              return false unless status
+
               status.complete?(total)
             end
 
             def started?
+              return false unless status
+
               status.started?
             end
 
@@ -59,14 +70,17 @@ module Ecoportal
               status.progress_increase(lstatus)
             end
 
+            # Total time waited (absolute).
             def waited
               timestamp - start
             end
 
+            # Time waited since last timestamp (relative).
             def lwaited
               timestamp - last
             end
 
+            # Absolute wait minus half of the last sleep.
             def net_waited
               last_delay = ldelay || 0
               waited - (last_delay / 2)
@@ -76,22 +90,26 @@ module Ecoportal
               (timeout_in - waited).round(2)
             end
 
+            # Time left before timing out job started
+            # or job finished.
+            def timeout_in
+              return time_left_total if started?
+
+              time_left_to_start
+            end
+
+            # Total time left before timing out.
             def time_left_total
               (timeout - waited).round(2)
             end
 
+            # Time left before Job start times out.
             def time_left_to_start
               return max_start_delay if started?
 
               (max_start_delay - waited).round(2)
             end
 
-            def timeout_in
-              return time_left_total if started?
-
-              time_left_to_start
-            end
-
             # timeout library is evil. So we make poor-man timeout.
             # https://jvns.ca/blog/2015/11/27/why-rubys-timeout-is-dangerous-and-thread-dot-raise-is-terrifying/
             def timeout?
@@ -141,7 +159,7 @@ module Ecoportal
               %i[total timeout start].each_with_object({}) do |key, kargs|
                 kargs[key] = send(key)
               end.tap do |kargs|
-                kargs[:start]   = start
+                kargs[:start]   = start # @todo redundant
                 kargs[:last]    = timestamp
                 kargs[:lstatus] = status
               end
@@ -149,6 +167,7 @@ module Ecoportal
 
             private
 
+            # We would not wait more than this time for a Job to start.
             def max_start_delay
               self.class::MAX_START_DELAY
             end

data/lib/ecoportal/api/v1/job/awaiter.rb

@@ -9,8 +9,14 @@ module Ecoportal
           include Common::Client::TimeOut
           include StatusFrequency
 
-          TIMEOUT_APPROACH   = :min # :conservative # adaptative timeout
-          TIMEOUT_FALLBACK   = :min
+          # available approaches are:
+          #  - `:min` assumes always the `MIN_THROUGHPUT`.
+          #  - `:last` last seen throughput.
+          #  - `:conservative` the bigger of: min throughput seen or `MIN_THROUGHPUT`.
+          #  - `:optimistic` the smoller of: max throughput seen or `MAX_THROUGHPUT`.
+          #  - `:average` the accumulated avarage of througoutputs.
+          TIMEOUT_APPROACH   = :min
+          TIMEOUT_FALLBACK   = :min # on timeout swap to this approach.
 
           attr_reader :job_api, :job_id, :total
 
@@ -51,10 +57,11 @@ module Ecoportal
 
               timer = timer.new(
                 status: job_api.status(job_id),
-                ldelay: delay_status_check
+                ldelay: delay_status_check || 1
               )
 
               # ratio = throughput!(timer.net_waited, count: timer.progress)
+              # last throughput (rather than average as above)
               ratio = throughput!(timer.lwaited, count: timer.increased)
 
               break timer.status if timer.complete?

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

@@ -4,6 +4,7 @@ require 'ecoportal/api/v1/job/awaiter'
 module Ecoportal
   module API
     class V1
+      # @todo add `#relaunch` where only pending results are requested.
       class Job
         attr_reader :client, :person_class
 
@@ -15,7 +16,7 @@ module Ecoportal
           @created      = false
         end
 
-        # Allows to preserve the learned througoutput
+        # Allows to preserve the learned throughput
         def new
           self.class.new(client, person_class: person_class).tap do |out|
             out.awaiter = @awaiter

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

@@ -25,6 +25,7 @@ module Ecoportal
         # @return [Array<SchemaFieldValue>] the array of fields of the schema.
         def fields
           return @fields if defined?(@fields)
+
           @fields = (doc['fields'] || []).each_with_index.map do |field, i|
             schema_field_value_class.new(field, parent: self, key: ['fields', i])
           end
@@ -66,10 +67,10 @@ module Ecoportal
         end
 
         # @return [Boolean] `true` if `id` exists and `value` has changed, `false` otherwise
-        def changed?(id, doc = :original)
+        def changed?(id, ref = :last)
           return false unless (field = get_field(id))
 
-          field.as_update.key?('value')
+          field.as_update(ref).key?('value')
         end
 
         def original_value(id)

data/lib/ecoportal/api/version.rb

@@ -1,5 +1,5 @@
 module Ecoportal
   module API
-    VERSION = '0.10.10'.freeze
+    VERSION = '0.10.12'.freeze
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ecoportal-api
 version: !ruby/object:Gem::Version
-  version: 0.10.10
+  version: 0.10.12
 platform: ruby
 authors:
 - Tapio Saarinen
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2025-04-04 00:00:00.000000000 Z
+date: 2025-05-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: pry