ecoportal-api-graphql 2.0.0 → 2.2.0

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

@@ -2,7 +2,88 @@ module Ecoportal
   module API
     module Common
       module GraphQL
-        class ResponseError < StandardError; end
+        # Raised when a 200 response carries a top-level `errors[]` array.
+        #
+        # ★ Carries the RAW error entries, so `extensions` survives. Before this, the
+        # class collapsed the response into the joined `message` text and threw the rest
+        # away — which made it impossible for Ruby tooling to tell a permission problem
+        # from a request problem, the exact diagnosis we tell customers to perform.
+        # Tracked as Q-27 in `docs/open-questions.md`.
+        #
+        # The backend's error contract (`app/graphql/eco_portal_schema.rb`, verified
+        # 2026-09-01) puts these keys under `extensions`:
+        #
+        # | key            | when                     | shape |
+        # |----------------|--------------------------|-------|
+        # | `code`         | always                   | string: `unauthorized`, `document_not_found`, `unprocessable_entity`, `write_conflict`, `internal_server_error`, … |
+        # | `fullMessages` | `unauthorized`           | array of human strings (`exp.result.reasons.full_messages`) |
+        # | `details`      | `unauthorized`           | ActionPolicy `reasons.details` — usually a Hash whose **key names the failing policy** and whose value lists the rules |
+        # | `problems`     | validation, and only when the server runs with `SHOW_GRAPHQL_EXCEPTION` | record errors |
+        #
+        # ⚠ `details` is NOT reliably a Hash. Two call sites emit an Array instead
+        # (`mutations/pages/send_as_email.rb` sends inaccessible ids;
+        # `queries/pages/templates/fetcher.rb` sends `[msg]`). Accessors here therefore
+        # return whatever the server sent, unwrapped but uncoerced — callers must not
+        # assume a shape.
+        class ResponseError < StandardError
+          # @return [Array<Hash>] the raw `errors[]` entries, exactly as received.
+          attr_reader :errors
+
+          # @param msg [String, nil] explicit message; defaults to the joined error messages.
+          # @param errors [Array<Hash>] raw top-level `errors[]` entries.
+          def initialize(msg = nil, errors: [])
+            @errors = Array(errors)
+            super(msg || build_message)
+          end
+
+          # @return [Array<Hash>] the `extensions` object of each error that carried one.
+          def extensions
+            errors.filter_map { |err| err['extensions'] }
+          end
+
+          # @return [Array<String>] every `extensions.code` present, in order.
+          def codes
+            extensions.filter_map { |ext| ext['code'] }
+          end
+
+          # ★ The fastest way to tell a permission problem from a request problem.
+          # @return [Array] every `extensions.details` present. Shape is the server's —
+          #   typically a Hash keyed by the failing policy, but sometimes an Array.
+          def details
+            extensions.filter_map { |ext| ext['details'] }
+          end
+
+          # @return [Array<String>] flattened `extensions.fullMessages`.
+          def full_messages
+            extensions.flat_map { |ext| Array(ext['fullMessages']) }
+          end
+
+          # @return [Boolean] whether ANY error was an authorization refusal. Use this to
+          #   branch on "you cannot" vs "that request was wrong" — do not pattern-match
+          #   the message text, which is prose and drifts.
+          def unauthorized?
+            codes.include?('unauthorized')
+          end
+
+          private
+
+          # The joined messages stay FIRST and unchanged, so existing callers matching on
+          # the message text keep working; the diagnosis is appended after them.
+          def build_message
+            base = errors.filter_map { |err| err['message'] }.join('; ')
+            base = 'GraphQL request failed' if base.empty?
+            [base, diagnosis].compact.join(' | ')
+          end
+
+          def diagnosis
+            parts = []
+            parts << "code: #{codes.uniq.join(', ')}" if codes.any?
+            parts << "details: #{details.inspect}"    if details.any?
+            return if parts.empty?
+
+            parts.join(' | ')
+          end
+        end
 
         class HttpClient < Common::Client
           class << self
@@ -184,7 +265,9 @@ module Ecoportal
 
             parsed = response.body
             errors = parsed && parsed['errors']
-            raise ResponseError, errors.map { |e| e['message'] }.join('; ') if errors&.any?
+            # Pass the raw entries through: `extensions` (and therefore the failing
+            # policy under `extensions.details`) is the whole point — see Q-27.
+            raise ResponseError.new(errors: errors) if errors&.any?
 
             parsed
           end

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

@@ -1,54 +1,54 @@
-module Ecoportal
-  module API
-    module Common
-      module GraphQL
-        class Model
-          # @todo
-          #   1. `#as_input` vs `#to_input` **or** named argument `klass`
-          #     One gets the `input` to be already used in a mutation query.
-          #     The other gets the `Input` class object out of the `Base/Model`.
-          #     - To figure out when `as_update` should be called.
-          #   2. Each Base/Model should have its `Input` class counterpart.
-          #     This could be auto-inflected (via namespace constant lookup)
-          #     at some point.
-          #   3. Think if a service class can be used to this purpose
-          #     (i.e. decorator of DiffService).
-          module AsInput
-            class << self
-              def included(base)
-                super
-
-                base.send(:include, Model::Diffable)
-                base.extend ClassMethods
-              end
-            end
-
-            module ClassMethods
-              def as_input(hash, clientMutationId: '')
-                hash_input = Ecoportal::API::Common::GraphQL::HashHelpers.
-                  keys_to_sym_deep(hash)
-
-                hash_input.merge!(clientMutationId: clientMutationId)
-
-                Ecoportal::API::Common::GraphQL::HashHelpers.
-                  remove_nil_keys_deep(hash_input, target: :id)
-              end
-            end
-
-            # INSTANCE METHODS
-
-            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
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    module Common
+      module GraphQL
+        class Model
+          # @todo
+          #   1. `#as_input` vs `#to_input` **or** named argument `klass`
+          #     One gets the `input` to be already used in a mutation query.
+          #     The other gets the `Input` class object out of the `Base/Model`.
+          #     - To figure out when `as_update` should be called.
+          #   2. Each Base/Model should have its `Input` class counterpart.
+          #     This could be auto-inflected (via namespace constant lookup)
+          #     at some point.
+          #   3. Think if a service class can be used to this purpose
+          #     (i.e. decorator of DiffService).
+          module AsInput
+            class << self
+              def included(base)
+                super
+
+                base.send(:include, Model::Diffable)
+                base.extend ClassMethods
+              end
+            end
+
+            module ClassMethods
+              def as_input(hash, clientMutationId: '')
+                hash_input = Ecoportal::API::Common::GraphQL::HashHelpers.
+                  keys_to_sym_deep(hash)
+
+                hash_input.merge!(clientMutationId: clientMutationId)
+
+                Ecoportal::API::Common::GraphQL::HashHelpers.
+                  remove_nil_keys_deep(hash_input, target: :id)
+              end
+            end
+
+            # INSTANCE METHODS
+
+            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
+      end
+    end
+  end
+end

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

@@ -1,49 +1,49 @@
-module Ecoportal::API::Common::GraphQL::Model::Diffable
-  class ClassicDiffService
-    include Ecoportal::API::Common::GraphQL::Model::Diffable::HashDiffNesting
-
-    attr_reader :subject
-
-    def initialize(subject, ignore: [])
-      msg  = 'Expecting Ecoportal::API::Common::Content::DoubleModel. '
-      msg << "Given: #{subject.class}"
-      raise ArgumentError, msg unless subject.is_a?(Ecoportal::API::Common::Content::DoubleModel)
-
-      @subject  = subject
-      @ignored  = to_a(ignore)
-    end
-
-    def diff(ignore: [])
-      classic_diff(ignore: ignore)
-    end
-
-    protected
-
-    def classic_diff(ignore: [])
-      change_diff(
-        curr_doc,
-        prev_doc,
-        ignore: to_a(ignored, ignore)
-      )
-    end
-
-    private
-
-    attr_reader :ignored
-
-    def curr_doc(target = subject)
-      return target.as_json if target.respond_to?(:as_json)
-      return target.doc     if target.respond_to?(:doc)
-
-      raise "Can't fetch underlying document for instance of #{target.class}."
-    end
-
-    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
+module Ecoportal::API::Common::GraphQL::Model::Diffable
+  class ClassicDiffService
+    include Ecoportal::API::Common::GraphQL::Model::Diffable::HashDiffNesting
+
+    attr_reader :subject
+
+    def initialize(subject, ignore: [])
+      msg  = 'Expecting Ecoportal::API::Common::Content::DoubleModel. '
+      msg << "Given: #{subject.class}"
+      raise ArgumentError, msg unless subject.is_a?(Ecoportal::API::Common::Content::DoubleModel)
+
+      @subject  = subject
+      @ignored  = to_a(ignore)
+    end
+
+    def diff(ignore: [])
+      classic_diff(ignore: ignore)
+    end
+
+    protected
+
+    def classic_diff(ignore: [])
+      change_diff(
+        curr_doc,
+        prev_doc,
+        ignore: to_a(ignored, ignore)
+      )
+    end
+
+    private
+
+    attr_reader :ignored
+
+    def curr_doc(target = subject)
+      return target.as_json if target.respond_to?(:as_json)
+      return target.doc     if target.respond_to?(:doc)
+
+      raise "Can't fetch underlying document for instance of #{target.class}."
+    end
+
+    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