ecoportal-api-graphql 1.3.4 → 1.3.9

data/ecoportal-api-graphql.gemspec

@@ -1,40 +1,40 @@
-# rubocop:disable Gemspec/DevelopmentDependencies
-lib = File.expand_path('lib', __dir__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'ecoportal/api/graphql_version'
-
-Gem::Specification.new do |spec|
-  spec.name          = 'ecoportal-api-graphql'
-  spec.version       = Ecoportal::API::GRAPQL_VERSION
-  spec.authors       = ['Oscar Segura']
-  spec.email         = ['oscar@ecoportal.co.nz']
-
-  spec.summary       = 'A collection of helpers for interacting with the ecoPortal GraphQL API'
-  spec.homepage      = 'https://www.ecoportal.com'
-  spec.licenses      = %w[MIT]
-
-  spec.metadata['rubygems_mfa_required'] = 'true'
-
-  spec.required_ruby_version = '>= 3.2.2'
-
-  spec.files = `git ls-files -z`.split("\x0").reject do |f|
-    f.match(%r{^(test|spec|features)/})
-  end
-  spec.bindir        = 'exe'
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ['lib']
-
-  spec.add_development_dependency 'pry',          '>= 0.14'
-  spec.add_development_dependency 'rake',         '>= 13.0.3', '< 14'
-  spec.add_development_dependency 'redcarpet',    '>= 3.6.0',  '< 4'
-  spec.add_development_dependency 'rspec',        '>= 3.12.0', '< 4'
-  spec.add_development_dependency 'rubocop',      '~> 1'
-  spec.add_development_dependency 'rubocop-rake', '~> 0'
-  spec.add_development_dependency 'yard',         '>= 0.9.34', '< 1'
-
-  spec.add_dependency 'ecoportal-api',    '~> 0.10',  '>= 0.10.14'
-  spec.add_dependency 'ecoportal-api-v2', '~> 3.3',   '>= 3.3.1'
-  spec.add_dependency 'graphlient',       '>= 0.8.0', '< 0.9'
-end
-
-# rubocop:enable Gemspec/DevelopmentDependencies
+# rubocop:disable Gemspec/DevelopmentDependencies
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ecoportal/api/graphql_version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'ecoportal-api-graphql'
+  spec.version       = Ecoportal::API::GRAPQL_VERSION
+  spec.authors       = ['Oscar Segura']
+  spec.email         = ['oscar@ecoportal.co.nz']
+
+  spec.summary       = 'A collection of helpers for interacting with the ecoPortal GraphQL API'
+  spec.homepage      = 'https://www.ecoportal.com'
+  spec.licenses      = %w[MIT]
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.required_ruby_version = '>= 3.2.2'
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(/^(test|spec|features)\//)
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(/^exe\//) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'pry',          '>= 0.14'
+  spec.add_development_dependency 'rake',         '>= 13.0.3', '< 14'
+  spec.add_development_dependency 'redcarpet',    '>= 3.6.0',  '< 4'
+  spec.add_development_dependency 'rspec',        '>= 3.12.0', '< 4'
+  spec.add_development_dependency 'rubocop',      '~> 1'
+  spec.add_development_dependency 'rubocop-rake', '~> 0'
+  spec.add_development_dependency 'yard',         '>= 0.9.34', '< 1'
+
+  spec.add_dependency 'ecoportal-api',    '~> 0.10',  '>= 0.10.16'
+  spec.add_dependency 'ecoportal-api-v2', '~> 3.3',   '>= 3.3.2'
+  spec.add_dependency 'graphlient',       '>= 0.8.0', '< 0.9'
+end
+
+# rubocop:enable Gemspec/DevelopmentDependencies

data/lib/ecoportal/api/common/graphql/CLAUDE.md

@@ -0,0 +1,36 @@
+# common/graphql
+
+Shared HTTP transport, authentication, and base model infrastructure used by the gem — nothing here is EcoPortal-domain-specific.
+
+## Contents
+
+| File / class | Purpose |
+|---|---|
+| `auth_service.rb` / `AuthService` | OAuth2 password + refresh-token flow; included in both client classes |
+| `client.rb` / `Client` | Graphlient-based GraphQL client (builds bearer-token headers, constructs endpoint URL) |
+| `http_client.rb` / `HttpClient` | Raw HTTP client (extends `Common::Client`); `execute` sends query strings + variables; supports v0–v3 + graphql API version modes |
+| `class_helpers.rb` / `ClassHelpers` | `becomes(klass)` instance casting + `const?` class helper |
+| `hash_helpers.rb` / `HashHelpers` | Deep key transforms (`keys_to_sym_deep`, `deep_dup`, `remove_nil_keys_deep`) — used by diff and input serialisation |
+| `query_integration.rb` / `QueryIntegration` | Class macro `query(:method, query_klass:)` that wires a named query method on `Model::Organization` |
+| `model.rb` / `Model` | Base model class: `DoubleModel` + `Diffable` + `AsInput`; all GraphQL models ultimately inherit this |
+| `patches.rb` | Reserved placeholder (empty) |
+| `model/diffable.rb` | `as_update` / `dirty?` — delegates to `DiffService` |
+| `model/as_input.rb` | `as_input` (instance) and `as_input(hash)` (class method) — converts diff to GraphQL mutation variables |
+| `model/diffable/diff_service.rb` | Main diff engine: flat classic diff + cascaded reduce through nested `GraphQL::Model` objects |
+| `model/diffable/classic_diff_service.rb` | Low-level change-data extraction (compares `curr_doc` vs `prev_doc`) |
+| `model/diffable/hash_diff.rb` | Hash equality / change detection helpers |
+| `model/diffable/hash_diff_nesting.rb` | Nested key path helpers (`dig_set!`, `dig_delete!`, `dig_path?`) |
+
+## Conventions
+
+- `Client` is graphlient-based and used for schema introspection; `HttpClient` is the actual request sender used in production (set as `client.http_client`).
+- `HashHelpers` is used as both a module mixin (include) and directly via `HashHelpers.keys_to_sym_deep(...)`.
+- `DiffService` handles the `flat:` flag: `flat: true` does a single-level diff; `flat: false` (default) cascades through nested `GraphQL::Model` objects.
+- Root-class objects (`root!` declared) are excluded from cascaded diffs — they represent independent server entities.
+- `AsInput#as_input(target_class:)` delegates to `Input::X.from_model(self)` when a target class is given.
+
+## Related
+
+- `../graphql/logic/base_model.rb` — adds `SnakeCamelAccess` on top of `Common::GraphQL::Model`
+- `../graphql/logic/input.rb` — `Logic::Input` base class built on top of `Model`
+- `../graphql/logic/base_query.rb` — consumes `HttpClient#execute` and `HashHelpers`

data/lib/ecoportal/api/common/graphql/auth_service.rb

@@ -7,14 +7,13 @@ module Ecoportal
           TOKEN_AUTORENEW = 90 # minutes
 
           module InstanceMethods
-            def session_token(host: server, version: nil, auto_renew: true)
-              session_token_data(host: host, version: version).then do |body|
+            def session_token(host: server, auto_renew: true)
+              session_token_data(host: host).then do |body|
                 next unless body
 
                 if auto_renew && token_renew?(body['expires_in'])
                   session_token_renewed(
                     host:          host,
-                    version:       version,
                     refresh_token: body['refresh_token']
                   )
                 else
@@ -23,15 +22,14 @@ module Ecoportal
               end
             end
 
-            def session_token_renewed(host: server, version: nil, refresh_token: nil)
+            def session_token_renewed(host: server, refresh_token: nil)
               unless refresh_token
-                return unless (body = session_token_data(host: host, version: version))
+                return unless (body = session_token_data(host: host))
                 return unless (refresh_token = body['resfresh_token'])
               end
 
               session_refresh_token_data(
                 host:          host,
-                version:       version,
                 refresh_token: refresh_token
               ).then do |bdy|
                 bdy['access_token'] if bdy
@@ -40,8 +38,8 @@ module Ecoportal
 
             private
 
-            def session_token_data(host: server, version: nil)
-              http_client(host: host, version: version).post(
+            def session_token_data(host: server)
+              auth_http_client(host: host).post(
                 '/oauth/token',
                 data: {
                   'grant_type' => 'password',
@@ -53,8 +51,8 @@ module Ecoportal
               end
             end
 
-            def session_refresh_token_data(refresh_token:, host: server, version: nil)
-              http_client(host: host, version: version).post(
+            def session_refresh_token_data(refresh_token:, host: server)
+              auth_http_client(host: host).post(
                 '/oauth/token',
                 data: {
                   'grant_type'    => 'refresh_token',
@@ -69,10 +67,10 @@ module Ecoportal
               (TOKEN_AUTORENEW * 60) > seconds
             end
 
-            def http_client(host: server, version: nil)
-              @http_client ||= Ecoportal::API::Common::GraphQL::HttpClient.new(
+            def auth_http_client(host: server)
+              @auth_http_client ||= Ecoportal::API::Common::GraphQL::HttpClient.new(
                 host:    host,
-                version: version
+                version: 'http'
               )
             end
 
@@ -89,7 +87,7 @@ module Ecoportal
             end
 
             def fetch_env_required(name)
-              abort("Missing ENV '#{name}'") unless ENV.key?(name)
+              raise "Missing ENV '#{name}'" unless ENV.key?(name)
               ENV[name]
             end
 

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

@@ -4,7 +4,9 @@ module Ecoportal
     module Common
       module GraphQL
         class Client < ::Graphlient::Client
-          attr_accessor :host
+          ENDPOINT_PATH = 'external/graphql'.freeze
+
+          attr_accessor :host, :http_client
 
           READ_TIMEOUT  = 90
           WRITE_TIMEOUT = 90
@@ -42,7 +44,12 @@ module Ecoportal
           end
 
           def new(org_id: self.org_id, host: self.host, schema_path: host, no_schema: @no_schema)
-            self.class.new(org_id: org_id, host: host, schema_path: schema_path, no_schema: no_schema)
+            self.class.new(
+              org_id:      org_id,
+              host:        host,
+              schema_path: schema_path,
+              no_schema:   no_schema
+            )
           end
 
           def org_id
@@ -52,7 +59,8 @@ module Ecoportal
           private
 
           def url
-            "#{Ecoportal::API::Common::GraphQL::HttpClient.base_url(host)}/api/#{org_id}/graphql"
+            base_url = Ecoportal::API::Common::GraphQL::HttpClient.base_url(host)
+            "#{base_url}/api/#{org_id}/#{ENDPOINT_PATH}"
           end
         end
       end

data/lib/ecoportal/api/common/graphql/http_client.rb

@@ -2,6 +2,8 @@ module Ecoportal
   module API
     module Common
       module GraphQL
+        class ResponseError < StandardError; end
+
         class HttpClient < Common::Client
           class << self
             def base_url(host)
@@ -13,20 +15,37 @@ module Ecoportal
             end
           end
 
+          ENDPOINT_PATH = 'external/graphql'.freeze
+          READ_TIMEOUT  = 90
+          WRITE_TIMEOUT = 90
+
           attr_reader :host, :version
 
+          include Ecoportal::API::Common::GraphQL::AuthService
+
           def initialize(
+            email:        nil,
+            pass:         nil,
+            org_id:       nil,
             api_key:      nil,
-            version:      nil,
+            version:      'graphql',
             host:         'live.ecoportal.com',
             logger:       ::Logger.new(IO::NULL),
-            deep_logging: false
+            deep_logging: false,
+            no_schema:    true
           )
-            super
-          end
+            @org_id      = org_id
+            @user_email  = email
+            @user_pass   = pass
+            @no_schema   = no_schema
+            @version     = version
 
-          def refresh_key(value)
-            @api_key = value
+            super(
+              api_key:      api_key,
+              host:         host,
+              logger:       logger,
+              deep_logging: deep_logging
+            )
           end
 
           # Creates a HTTP object adding the `X-ApiKey` or `X-ECOPORTAL-API-KEY` param to the header, depending on the API version.
@@ -35,52 +54,121 @@ module Ecoportal
           def base_request
             @base_request ||=
               case @version
-              when NilClass
-                HTTP.accept(:json)
-              when 'v2'
-                HTTP.headers('X-ECOPORTAL-API-KEY' => key_token).accept(:json)
+              when NilClass, 'http'
+                HTTP
+              when 'v1', 'v0'
+                HTTP.headers('X-ApiKey' => key_token)
+              when 'v2', 'v3'
+                HTTP.headers('X-ECOPORTAL-API-KEY' => key_token)
               when 'graphql'
-                HTTP.headers('Authorization' => "Bearer #{key_token}").accept(:json)
-              else
-                HTTP.headers('X-ApiKey' => key_token).accept(:json)
+                HTTP.headers('Authorization' => "Bearer #{session_token(host: host)}")
+              end.then do |request|
+                request ||= HTTP
+                request.accept(:json).timeout(
+                  read:  READ_TIMEOUT,
+                  write: WRITE_TIMEOUT
+                )
               end
           end
 
+          def org_id
+            @org_id || fetch_env_required('ORGANIZATION_ID')
+          end
+
+          # Executes a GraphQL query or mutation over HTTP.
+          # @param query_string [String] full GraphQL query document.
+          # @param variables [Hash] variable values to pass to the operation.
+          # @param operation_name [String, nil] when the document has multiple operations.
+          # @return [Hash] parsed response body (string-keyed, includes 'data' and optionally 'errors').
+          # @raise [Ecoportal::API::Common::Client::Error::UnexpectedServerError] on non-2xx HTTP status.
+          # @raise [Ecoportal::API::Common::GraphQL::ResponseError] when the response body contains GraphQL errors.
+          def execute(query_string, variables: {}, operation_name: nil)
+            body = { query: query_string, variables: variables }
+            body[:operationName] = operation_name if operation_name
+            response = base_request.post(url_for(''), json: body)
+            handle_http_response(response)
+          end
+
           # Full URl builder of the request
           # @param path [String] the tail that completes the url of the request.
           # @return [String] the final url.
           def url_for(path)
-            version? ? "#{base_url_api}#{path}" : "#{base_url}#{path}"
+            "#{api_url}#{path}"
           end
 
           private
 
-          def version?
-            !!@version
+          def key_token
+            return                           if http?
+            return session_token(host: host) if graphql?
+            return @api_key                  if api_key?
+            return ENV['ORG_INT_KEY']        if v0?
+
+            puts 'Api-key missing!'
           end
 
-          def protocol
-            @protocol ||= self.class.protocol(host)
+          def api_url
+            base_url.then do |url|
+              next "#{url}/api/#{version}"                 if v1_0? || v2_3?
+              next "#{url}/api/#{org_id}/#{ENDPOINT_PATH}" if graphql?
+
+              url
+            end
           end
 
           def base_url
             @base_url ||= self.class.base_url(host)
           end
 
-          def base_url_api
-            @base_url_api ||= "#{base_url}/api/#{version}"
+          def protocol
+            @protocol ||= self.class.protocol(host)
           end
 
-          def key_token
-            if @api_key.nil? || @api_key.match(/\A\W*\z/)
-              if (version == 'v0') && (key = ENV['ORG_INT_KEY'])
-                key
-              elsif !version.nil?
-                puts 'Api-key missing!'
-              end
-            else
-              @api_key
+          def http?
+            return true if @version.nil?
+
+            @version == 'http'
+          end
+
+          def api_key?
+            @api_key && !@api_key.match(/\A\W*\z/)
+          end
+
+          def v1_0?
+            v1? || v0?
+          end
+
+          def v1?
+            @version == 'v1'
+          end
+
+          def v0?
+            @version == 'v0'
+          end
+
+          def v2_3?
+            return true if @version == 'v2'
+            return true if @version == 'v3'
+
+            false
+          end
+
+          def graphql?
+            @version == 'graphql'
+          end
+
+          def handle_http_response(response)
+            unless response.status.success?
+              raise Ecoportal::API::Common::Client::Error::UnexpectedServerError.new(
+                response.body.to_s, code: response.status.code
+              )
             end
+
+            parsed = response.parse(:json)
+            errors = parsed['errors']
+            raise ResponseError, errors.map { |e| e['message'] }.join('; ') if errors&.any?
+
+            parsed
           end
         end
       end

data/lib/ecoportal/api/common/graphql/model/CLAUDE.md

@@ -0,0 +1,28 @@
+# common/graphql/model
+
+Concerns that add dirty-tracking diff (`Diffable`) and mutation-input serialisation (`AsInput`) to the base `Common::GraphQL::Model`.
+
+## Contents
+
+| File / class | Purpose |
+|---|---|
+| `diffable.rb` / `Model::Diffable` | Provides `as_update` (returns changed-field hash or nil) and `dirty?`; delegates to `DIFF_CLASS` (defaults to `DiffService`) |
+| `as_input.rb` / `Model::AsInput` | Instance `as_input` (wraps diff as mutation variables) + class-level `as_input(hash)` (key-sym + nil-id cleanup) |
+| `diffable/diff_service.rb` / `DiffService` | Primary diff engine: flat classic diff then cascaded reduce over nested `GraphQL::Model` children |
+| `diffable/classic_diff_service.rb` / `ClassicDiffService` | Low-level diff: compares `curr_doc` vs `prev_doc`, returns `{ id:, changed_field: new_value }` or nil |
+| `diffable/hash_diff.rb` / `HashDiff` | Primitive equality helpers used by `ClassicDiffService` |
+| `diffable/hash_diff_nesting.rb` / `HashDiffNesting` | Nested path helpers: `dig_set!`, `dig_delete!`, `dig_path?` used when building cascaded diff results |
+
+## Conventions
+
+- `DIFF_CLASS = DiffService` is a constant on `Diffable` — subclasses can override it to swap diff strategies.
+- `DiffService` `flat: true` produces a single-level diff (current model only); `flat: false` (default) recurses via `cascaded_reduce` through nested `GraphQL::Model` objects.
+- Objects declared with `root!` in their class are skipped during cascaded diff — they are independent server entities (look-ups only).
+- `as_input` on a model calls `as_update` first; returns `nil` when nothing has changed so callers can skip the mutation.
+- `as_input(target_class:)` is the preferred path when a corresponding `Input::X` class exists — delegates to `target_class.from_model(self)`.
+
+## Related
+
+- `../hash_helpers.rb` — `HashHelpers` used inside `DiffService` for key transforms
+- `../../graphql/logic/input.rb` — `Logic::Input.from_model` is the canonical consumer of `as_update`
+- `../../graphql/logic/base_model.rb` — all concrete models inherit this chain

data/lib/ecoportal/api/common/graphql/model/as_input.rb

@@ -37,11 +37,14 @@ module Ecoportal
 
             # INSTANCE METHODS
 
-            def as_input(clientMutationId: '')
-              self.class.as_input(
-                as_update,
-                clientMutationId: clientMutationId
-              )
+            def as_input(target_class: nil, clientMutationId: '')
+              return target_class.from_model(self, client_mutation_id: clientMutationId) if target_class
+
+              diff = as_update
+              return nil if diff.nil?
+
+              diff[:patchVer] = patchVer if respond_to?(:patchVer) && !patchVer.nil?
+              self.class.as_input(diff, clientMutationId: clientMutationId)
             end
           end
         end

data/lib/ecoportal/api/common/graphql/model/diffable/classic_diff_service.rb

@@ -38,10 +38,12 @@ module Ecoportal::API::Common::GraphQL::Model::Diffable
       raise "Can't fetch underlying document for instance of #{target.class}."
     end
 
-    def prev_doc(target = subject, flat: flat?)
+    def prev_doc(target = subject)
       return target.original_doc if target.respond_to?(:original_doc)
 
       raise "Can't fetch original underlying model for instance of #{target.class}."
+    rescue NoMethodError
+      nil
     end
   end
 end

data/lib/ecoportal/api/common/graphql/model/diffable/diff_service.rb

@@ -34,12 +34,17 @@ module Ecoportal::API::Common::GraphQL::Model::Diffable
 
     protected
 
+    # Override: GraphQL mutations expect flat changed-prop values, not patch-op wrappers.
+    # Returns { id: ..., changed_field: new_value, ... } or nil when nothing changed.
     def classic_diff(flat: flat?, ignore: [])
-      change_diff(
-        curr_doc(flat: flat),
-        prev_doc(flat: flat),
-        ignore: to_a(ignored, ignore)
-      )
+      curr = keys_to_sym_deep(curr_doc(flat: flat) || {})
+      prev = keys_to_sym_deep(prev_doc(flat: flat) || {})
+
+      data = change_data(curr, prev, ignore: to_a(ignored, ignore))
+      return nil if data == NO_CHANGES
+
+      id = get_id(curr, exception: false)
+      id ? { id: id }.merge(data) : data
     end
 
     # @note it calls `as_update` for nested / cascaded attributes, which in turn
@@ -49,26 +54,28 @@ module Ecoportal::API::Common::GraphQL::Model::Diffable
     #       `#as_update` and `DiffService#diff`.
     #     - The `result` object regards, therefore, to the **current level** alone.
     #       With the aim of building it up (accumulating through the call chain).
-    def diff_reduce(init = {}, ignore: [])
+    def diff_reduce(init, ignore: [])
       subject.cascaded_reduce(init, recurs: false) do |result, obj, _key, key_path, _trace|
-        next result if key_path.empty? # first iteration already done
-        next result if obj == subject  # first call had done it (same as above: path relative)
+        next result if key_path.empty?
+        next result if obj == subject
 
-        dig_delete!(result, key_path) if dig_path?(result, key_path)
+        sym_path = key_path.map(&:to_sym)
 
-        # discard rooted (i.e. read_only) objects from the diff.
+        # Remove any flat-diff placeholder for this key before deciding its fate.
+        dig_delete!(result, sym_path) if result && dig_path?(result, sym_path)
+
+        # Discard root-class objects — they are independent entities, not mutation payload.
         next result if root?(obj)
-        next result unless dig_path?(result, key_path)
-        next result unless obj.respond_to?(:as_update)
+        # Only cascade-diff GraphQL model objects; ecoportal-api-v2 DoubleModel
+        # subclasses (ArrayModel, etc.) have a different as_update signature.
+        next result unless obj.is_a?(Ecoportal::API::Common::GraphQL::Model)
 
         value = obj.as_update(ignore: ignore)
+        next result if value.nil?
 
-        dig_set!(
-          result,
-          key_path,
-          value
-        )
-
+        result      ||= {}
+        result[:id] ||= get_id(keys_to_sym_deep(curr_doc(flat: true) || {}), exception: false)
+        dig_set!(result, sym_path, value)
         result
       end
     end
@@ -147,9 +154,10 @@ module Ecoportal::API::Common::GraphQL::Model::Diffable
     attr_reader :ignored
 
     def root?(obj)
-      return false unless obj.respond_to?(:root?)
-
-      obj.root?
+      # root? is a CLASS method (via Rootable::ClassMethods). The instance root?
+      # is protected and checks parent position, not the class declaration.
+      # Check the ancestor chain for any class that declared root!.
+      obj.class.ancestors.any? { |k| k.respond_to?(:root?) && k.root? }
     end
 
     def curr_doc(target = subject, flat: flat?)
@@ -171,8 +179,8 @@ module Ecoportal::API::Common::GraphQL::Model::Diffable
 
     # Remove from `json` doc all the nested properties.
     def doc_with_non_cascaded_attributes(json)
-      return json unless subject.respond_to?(:_cascaded_doc_keys)
-      return json unless (excluded = subject._cascaded_doc_keys)
+      return json unless subject.class.respond_to?(:_cascaded_doc_keys)
+      return json if (excluded = subject.class._cascaded_doc_keys).empty?
 
       except_keys(json, *excluded)
     end

data/lib/ecoportal/api/common/graphql/model/diffable/hash_diff_nesting.rb

@@ -192,7 +192,7 @@ module Ecoportal::API::Common::GraphQL::Model::Diffable
       end
 
       def any_array?(a, b)
-        [a, b].any? {|item| item.is_a?(Array)}
+        [a, b].any?(Array)
       end
 
       def get_id(doc, exception: true)
@@ -207,6 +207,30 @@ module Ecoportal::API::Common::GraphQL::Model::Diffable
         id
       end
 
+      # @param arr [Array] the source Array of id-bearing items
+      # @return [Array<String>] the `id`s thereof
+      def array_ids(arr)
+        return [] if !arr.is_a?(Array) || arr.empty?
+
+        arr.map {|item| get_id(item, exception: false)}
+      end
+
+      # @param arr [Array] the source Array
+      # @return [Integer, nil] the position of the item with the given `id`
+      def array_id_index(arr, id)
+        return unless arr.is_a?(Array)
+
+        arr.index {|item| get_id(item, exception: false) == id}
+      end
+
+      # @param arr [Array] the source Array
+      # @return [Object, nil] the item with the given `id`
+      def array_id_item(arr, id)
+        return unless (idx = array_id_index(arr, id))
+
+        arr[idx]
+      end
+
       def meta_keys
         return self::META_KEYS if respond_to?(:const_get)
 
@@ -233,6 +257,35 @@ module Ecoportal::API::Common::GraphQL::Model::Diffable
       def to_a(*values)
         [values].flatten.compact.uniq
       end
+
+      # Hash path helpers — used by DiffService#diff_reduce to navigate
+      # and modify nested result hashes during cascaded diffing.
+
+      def dig_path?(obj, keys)
+        return false unless obj.is_a?(Hash)
+        return obj.key?(keys.first) if keys.length == 1
+        return false unless obj.key?(keys.first)
+
+        dig_path?(obj[keys.first], keys[1..])
+      end
+
+      def dig_set!(obj, keys, value)
+        if keys.length == 1
+          obj[keys.first] = value
+        else
+          dig_set!(obj[keys.first], keys[1..], value)
+        end
+      end
+
+      def dig_delete!(obj, keys)
+        if keys.length == 1
+          return unless obj.respond_to?(:delete)
+
+          obj.delete(keys.first)
+        else
+          dig_delete!(obj[keys.first], keys[1..])
+        end
+      end
     end
 
     extend InstanceMethods