ecoportal-api-graphql 1.3.5 → 1.3.16

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/client.rb

@@ -6,7 +6,7 @@ module Ecoportal
         class Client < ::Graphlient::Client
           ENDPOINT_PATH = 'external/graphql'.freeze
 
-          attr_accessor :host
+          attr_accessor :host, :http_client
 
           READ_TIMEOUT  = 90
           WRITE_TIMEOUT = 90

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

@@ -1,145 +1,195 @@
-module Ecoportal
-  module API
-    module Common
-      module GraphQL
-        class HttpClient < Common::Client
-          class << self
-            def base_url(host)
-              "#{protocol(host)}://#{host}"
-            end
-
-            def protocol(host)
-              host.match(/^localhost|^127\.0\.0\.1/)? 'http' : 'https'
-            end
-          end
-
-          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:      'graphql',
-            host:         'live.ecoportal.com',
-            logger:       ::Logger.new(IO::NULL),
-            deep_logging: false,
-            no_schema:    true
-          )
-            @org_id      = org_id
-            @user_email  = email
-            @user_pass   = pass
-            @no_schema   = no_schema
-            @version     = version
-
-            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.
-          # @note It configures HTTP so it only allows body data in json format.
-          # @return [HTTP] HTTP object.
-          def base_request
-            @base_request ||=
-              case @version
-              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}")
-              end.then do |request|
-                request.accept(:json).timeout(
-                  read:  READ_TIMEOUT,
-                  write: WRITE_TIMEOUT
-                )
-              end
-          end
-
-          def org_id
-            @org_id || fetch_env_required('ORGANIZATION_ID')
-          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)
-            "#{api_url}#{path}"
-          end
-
-          private
-
-          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 api_url
-            base_url.then do |url|
-              next "#{url}/api/#{version}"        if v1_0? || v2_3?
-              next "#{url}/api/#{org_id}/graphql" if graphql?
-
-              url
-            end
-          end
-
-          def base_url
-            @base_url ||= self.class.base_url(host)
-          end
-
-          def protocol
-            @protocol ||= self.class.protocol(host)
-          end
-
-          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
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    module Common
+      module GraphQL
+        class ResponseError < StandardError; end
+
+        class HttpClient < Common::Client
+          class << self
+            def base_url(host)
+              "#{protocol(host)}://#{host}"
+            end
+
+            def protocol(host)
+              host.match(/^localhost|^127\.0\.0\.1/)? 'http' : 'https'
+            end
+          end
+
+          ENDPOINT_PATH = 'external/graphql'.freeze
+          READ_TIMEOUT  = 90
+          WRITE_TIMEOUT = 90
+
+          attr_reader :host, :version
+
+          # Publicly exposes the configured api_key (inherited as `private` from
+          # `Common::Client`) — `FileUpload::Client` needs it directly to authenticate
+          # against the v2 REST endpoints, independent of this client's own `@version`
+          # (which stays `'graphql'` and therefore always builds a Bearer `key_token`).
+          public :api_key
+
+          include Ecoportal::API::Common::GraphQL::AuthService
+
+          def initialize(
+            email:        nil,
+            pass:         nil,
+            org_id:       nil,
+            api_key:      nil,
+            version:      'graphql',
+            host:         'live.ecoportal.com',
+            logger:       ::Logger.new(IO::NULL),
+            deep_logging: false,
+            no_schema:    true
+          )
+            @org_id      = org_id
+            @user_email  = email
+            @user_pass   = pass
+            @no_schema   = no_schema
+            @version     = version
+
+            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.
+          # @note It configures HTTP so it only allows body data in json format.
+          # @return [HTTP] HTTP object.
+          def base_request
+            @base_request ||=
+              case @version
+              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 #{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
+
+            # Route through the inherited `Common::Client` pipeline
+            # (`instrument` -> `with_retry` { `rate_throttling` }) so GraphQL requests
+            # inherit the SAME battle-tested contingencies as the REST clients:
+            # rate-limit backoff (429 / Cloudflare 1015), 5xx + connection-error retries,
+            # timeouts, and instrumentation. Do NOT re-issue the request raw here — that
+            # bypasses all of the above and is what let live runs die on the first 429.
+            response = instrument('POST', ENDPOINT_PATH, body) do
+              request { |http| http.post(url_for(''), json: body) }
+            end
+
+            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)
+            "#{api_url}#{path}"
+          end
+
+          private
+
+          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 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 protocol
+            @protocol ||= self.class.protocol(host)
+          end
+
+          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
+
+          # @param response [Ecoportal::API::Common::Response] the wrapped response
+          #   produced by the inherited pipeline (body already JSON-parsed).
+          def handle_http_response(response)
+            unless response.success?
+              raise Ecoportal::API::Common::Client::Error::UnexpectedServerError.new(
+                response.src_body, code: response.status.code
+              )
+            end
+
+            parsed = response.body
+            errors = parsed && parsed['errors']
+            raise ResponseError, errors.map { |e| e['message'] }.join('; ') if errors&.any?
+
+            parsed
+          end
+        end
+      end
+    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