ecoportal-api-graphql 1.3.14 → 1.3.15

data/lib/ecoportal/api/graphql/query/register_preset_views.rb

@@ -1,78 +1,78 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Query
-        # Lists preset views for a register.
-        # Returns an array of PresetView objects — not paginated (server returns all at once).
-        # Use the returned IDs as `presetViewId` in RegisterPreviewPages queries.
-        #
-        # Usage:
-        #   views = Query::RegisterPresetViews.new(client).query(registerId: 'REG_ID')
-        #   views.map { |v| { id: v.id, name: v.name, global: v.global? } }
-        class RegisterPresetViews < Logic::Query
-          field_name :presetViews
-
-          accepted_params :registerId, :searchConf
-
-          class_resolver :item_class, 'Ecoportal::API::GraphQL::Model::PresetView'
-
-          def path
-            %w[currentOrganization register presetViews]
-          end
-
-          def response_class
-            # presetViews returns an array — wrap in a simple array-like response
-            ArrayResponse
-          end
-
-          # Minimal array wrapper so callers can iterate results with .each / .map
-          class ArrayResponse
-            include Enumerable
-
-            def initialize(raw)
-              klass = Ecoportal::API::GraphQL::Model::PresetView
-              @items = Array(raw).map { |d| klass.new(d) }
-            end
-
-            def each(&block)
-              @items.each(&block)
-            end
-
-            def nodes
-              @items
-            end
-          end
-
-          private
-
-          def basic_block(&block)
-            view_block = block || default_block
-            proc {
-              query(
-                registerId: :id!,
-                searchConf: :Search
-              ) {
-                currentOrganization {
-                  register(id: :registerId) {
-                    presetViews(searchConf: :searchConf, &view_block)
-                  }
-                }
-              }
-            }
-          end
-
-          def default_block
-            proc {
-              id
-              name
-              global
-              registerId
-              sorter { key direction missing }
-              fieldConfigurations { id key name weight }
-            }
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Query
+        # Lists preset views for a register.
+        # Returns an array of PresetView objects — not paginated (server returns all at once).
+        # Use the returned IDs as `presetViewId` in RegisterPreviewPages queries.
+        #
+        # Usage:
+        #   views = Query::RegisterPresetViews.new(client).query(registerId: 'REG_ID')
+        #   views.map { |v| { id: v.id, name: v.name, global: v.global? } }
+        class RegisterPresetViews < Logic::Query
+          field_name :presetViews
+
+          accepted_params :registerId, :searchConf
+
+          class_resolver :item_class, 'Ecoportal::API::GraphQL::Model::PresetView'
+
+          def path
+            %w[currentOrganization register presetViews]
+          end
+
+          def response_class
+            # presetViews returns an array — wrap in a simple array-like response
+            ArrayResponse
+          end
+
+          # Minimal array wrapper so callers can iterate results with .each / .map
+          class ArrayResponse
+            include Enumerable
+
+            def initialize(raw)
+              klass = Ecoportal::API::GraphQL::Model::PresetView
+              @items = Array(raw).map { |d| klass.new(d) }
+            end
+
+            def each(&block)
+              @items.each(&block)
+            end
+
+            def nodes
+              @items
+            end
+          end
+
+          private
+
+          def basic_block(&block)
+            view_block = block || default_block
+            proc {
+              query(
+                registerId: :id!,
+                searchConf: :Search
+              ) {
+                currentOrganization {
+                  register(id: :registerId) {
+                    presetViews(searchConf: :searchConf, &view_block)
+                  }
+                }
+              }
+            }
+          end
+
+          def default_block
+            proc {
+              id
+              name
+              global
+              registerId
+              sorter { key direction missing }
+              fieldConfigurations { spread :FieldConfiguration }
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql.rb

@@ -13,7 +13,10 @@ module Ecoportal
       # @param org_id [String] the id of the target organization.
       #    It defaults to the environmental variable `ORGANIZATION_ID`, if defined
       # @param logger [Logger] an object with `Logger` interface to generate logs.
-      def initialize(email: nil, pass: nil, org_id: nil, host: "live.ecoportal.com")
+      # @param api_key [String] optional `X-ECOPORTAL-API-KEY`, required only for the v2 REST
+      #    endpoints `FileUpload::Client` calls to register/poll an uploaded file — the GraphQL
+      #    endpoint itself always authenticates via the email/pass OAuth bearer token.
+      def initialize(email: nil, pass: nil, org_id: nil, host: "live.ecoportal.com", api_key: nil)
         kargs = {
           email:     email,
           pass:      pass,
@@ -24,10 +27,11 @@ module Ecoportal
 
         @client = client_class.new(**kargs)
         @client.http_client = Ecoportal::API::Common::GraphQL::HttpClient.new(
-          email:  email,
-          pass:   pass,
-          org_id: org_id,
-          host:   host
+          email:   email,
+          pass:    pass,
+          org_id:  org_id,
+          host:    host,
+          api_key: api_key
         )
         @fragments = Ecoportal::API::GraphQL::Fragment.new(client)
       end

data/lib/ecoportal/api/graphql_version.rb

@@ -1,5 +1,5 @@
 module Ecoportal
   module API
-    GRAPQL_VERSION = '1.3.14'.freeze
+    GRAPQL_VERSION = '1.3.15'.freeze
   end
 end

data/tests/dump_schema.rb

@@ -0,0 +1,88 @@
+require 'ecoportal/api-graphql'
+require 'graphql'
+require 'json'
+require 'fileutils'
+
+# Dump a FRESH GraphQL introspection schema (JSON) from a live ecoPortal endpoint.
+#
+# Why this exists: `tests/validate_queries.rb` (and the `graphql-schema-diff` skill) need an
+# introspection snapshot, and a COMMITTED dump goes stale — a stale schema turns real findings
+# into noise ("field doesn't exist") and hides new ones. The 6.3MB dump is therefore NOT
+# committed; CI introspects at pipeline time instead (see the `validate-queries` job in
+# `.gitlab-ci.yml`).
+#
+# Equivalent to eco-helpers' `-graphql-schema -format json` usecase (`graphql.client.schema.to_json`),
+# but self-contained in this gem: it POSTs the introspection query through the gem's OWN
+# `HttpClient#execute`, so it inherits the retry / rate-throttle pipeline and the OAuth bearer auth.
+#
+# Usage (run under bundler — the graphlient fork is a git dependency):
+#   SERVER=<host> ORGANIZATION_ID=<org> USER_EMAIL=<email> USER_PASS=<pass> \
+#     bundle exec ruby tests/dump_schema.rb [OUT_PATH]
+#
+# OUT_PATH defaults to `.ai-assistance/tmp/<stamp>_<enviro>_ep_graphql_schema.graphql.json`
+# (that folder is gitignored — matches the naming the schema-diff skill parses stamps from).
+#
+# `SERVER` is REQUIRED on purpose: the gem's own default host is PRODUCTION, and an implicit
+# prod connection is a footgun even for a read-only query.
+#
+# Exit codes: 0 ok · 2 configuration error (missing env) · 1 introspection failed / unusable dump
+
+REQUIRED_ENV = %w[SERVER ORGANIZATION_ID USER_EMAIL USER_PASS].freeze
+
+missing = REQUIRED_ENV.reject { |name| ENV[name].to_s.match?(/\S/) }
+unless missing.empty?
+  warn "Missing required ENV: #{missing.join(', ')}"
+  warn "Usage: #{REQUIRED_ENV.map { |n| "#{n}=..." }.join(' ')} bundle exec ruby #{$PROGRAM_NAME} [OUT_PATH]"
+  exit 2
+end
+
+host   = ENV.fetch('SERVER')
+org_id = ENV.fetch('ORGANIZATION_ID')
+
+def out_path(host)
+  enviro = host.split('.').first.to_s.gsub('-', '_')
+  stamp  = Time.now.strftime('%Y%m%dT%H%M%S')
+  File.expand_path("../.ai-assistance/tmp/#{stamp}_#{enviro}_ep_graphql_schema.graphql.json", __dir__)
+end
+
+out = ARGV[0] || out_path(host)
+FileUtils.mkdir_p(File.dirname(out))
+
+api = Ecoportal::API::GraphQL.new(
+  email:  ENV.fetch('USER_EMAIL'),
+  pass:   ENV.fetch('USER_PASS'),
+  org_id: org_id,
+  host:   host
+)
+
+# `GraphQL::Introspection::INTROSPECTION_QUERY` is the CONSERVATIVE query in graphql-ruby 2.6
+# (verified: identical to `GraphQL::Introspection.query` with every `include_*` flag false — it
+# does NOT ask for `isRepeatable` / `specifiedByURL` / `isOneOf` / deprecated-arg flags). That is
+# what we want: no client/server version skew over introspection extras.
+result =
+  begin
+    puts "Introspecting #{host} (org #{org_id})..."
+    api.client.http_client.execute(GraphQL::Introspection::INTROSPECTION_QUERY)
+  rescue Ecoportal::API::Common::GraphQL::ResponseError => e
+    warn "Introspection rejected by the server: #{e.message}"
+    nil
+  end
+
+unless result&.dig('data', '__schema')
+  warn 'Introspection failed — no data.__schema in the response.'
+  exit 1
+end
+
+# Fail here rather than downstream: prove the dump is loadable by the same call
+# `validate_queries.rb` and the schema-diff skill make.
+begin
+  GraphQL::Schema.from_introspection(result)
+rescue StandardError => e
+  warn "Dump is not a usable introspection result: #{e.class}: #{e.message}"
+  exit 1
+end
+
+File.write(out, JSON.generate(result))
+
+types = result.dig('data', '__schema', 'types')&.size
+puts "Wrote #{out} (#{File.size(out) / 1024}KB, #{types} types)"

data/tests/validate_queries.rb

@@ -3,8 +3,9 @@ require 'json'
 require 'graphql'
 
 # Validate EVERY gem query against a GraphQL schema, offline — catches the whole class of
-# "field must have selections" (object field selected bare) and "selections can't be made on
-# scalars" (scalar over-selected) bugs before they reach a client runner.
+# "field must have selections" (object field selected bare), "selections can't be made on
+# scalars" (scalar over-selected) and "selections can't be made directly on unions" (union
+# selected without a type condition) bugs before they reach a client runner.
 #
 # This is how the 2026-07-03 LocationStructure `updatedAt` prod failure (and a sibling
 # `createdAt` over-selection in the LocationDraft fragment) were found. Those queries had no
@@ -16,17 +17,38 @@ require 'graphql'
 # Usage (run under bundler so the graphlient fork's #to_query_string is available):
 #   bundle exec ruby tests/validate_queries.rb [PATH_TO_SCHEMA_INTROSPECTION_JSON]
 #
-# Get a fresh schema JSON via an introspection query against the org's endpoint; the default
-# below points at the last captured dump. Prefer a fresh dump — a stale one yields false
-# "field doesn't exist" noise (harmless: this script only *fails* on the two structural classes).
+# With no argument it picks the NEWEST dump in `.ai-assistance/tmp/` (gitignored — dumps are never
+# committed, they go stale). Get a fresh one with `tests/dump_schema.rb`. Prefer a fresh dump — a
+# stale one yields false "field doesn't exist" noise (harmless: this script only *fails* on the two
+# structural classes and on render failures).
+#
+# Wired into CI as the blocking `validate-queries` job (see `.gitlab-ci.yml`), which dumps a fresh
+# schema first.
+
+SCHEMA_GLOB = File.expand_path('../.ai-assistance/tmp/*_ep_graphql_schema*.json', __dir__)
 
-DEFAULT_SCHEMA = File.expand_path('../.ai-assistance/tmp/20260605T101224_live_ep_graphql_schema.graphql.json', __dir__)
-STRUCTURAL = ['must have selections', "can't be made on scalars"].freeze
+# Message fragments that are ALWAYS a real client-side bug, never schema staleness — so they can
+# safely fail the build. `directly on unions` was added 2026-07-29: the 3 union findings triaged on
+# 2026-07-03 (PageWithForces / PagesWorkflowCommands / RegisterPresetViews) sat in the advisory
+# "OTHER" bucket and needed a human to spot them, which is exactly what this gate is meant to
+# remove. Selecting on a union without a type condition is invalid GraphQL under any schema.
+# `can't be spread inside` was added 2026-07-30 for the same reason as unions: the 7 invalid
+# `PageFields` spreads (review tasks → TaskInterface, related pages → RelatedPages, template
+# information → Template) sat in the advisory bucket until a human read the first live CI run.
+# A fragment whose type condition cannot overlap its spread location is invalid under any schema.
+STRUCTURAL = [
+  'must have selections',
+  "can't be made on scalars",
+  "can't be made directly on unions",
+  "can't be spread inside"
+].freeze
 
-schema_path = ARGV[0] || DEFAULT_SCHEMA
-unless File.exist?(schema_path)
-  warn "Schema introspection JSON not found: #{schema_path}"
-  warn 'Pass a path: bundle exec ruby tests/validate_queries.rb <schema.json>'
+schema_path = ARGV[0] || Dir[SCHEMA_GLOB].max
+unless schema_path && File.exist?(schema_path)
+  warn "Schema introspection JSON not found (looked for the newest #{SCHEMA_GLOB})"
+  warn 'Get a fresh one:  SERVER=... ORGANIZATION_ID=... USER_EMAIL=... USER_PASS=... \\'
+  warn '                    bundle exec ruby tests/dump_schema.rb'
+  warn 'Or pass a path:   bundle exec ruby tests/validate_queries.rb <schema.json>'
   exit 2
 end
 
@@ -105,7 +127,7 @@ else
   render_failures.each { |name, msgs| puts "  #{name}\n    - #{msgs.join("\n    - ")}" }
 end
 
-puts "\n## STRUCTURAL BUGS (fail the build — bare object / over-selected scalar):"
+puts "\n## STRUCTURAL BUGS (fail the build — bare object / over-selected scalar / union without type condition):"
 if structural_bugs.empty?
   puts '  none ✅'
 else

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ecoportal-api-graphql
 version: !ruby/object:Gem::Version
-  version: 1.3.14
+  version: 1.3.15
 platform: ruby
 authors:
 - Oscar Segura
@@ -356,6 +356,7 @@ files:
 - bin/console
 - bin/setup
 - bin/setup.ps1
+- changelog.d/fixed-mr51-payload-item-mismatches.md
 - docs/self-docs/ARCHITECTURE.md
 - docs/self-docs/CHANGES.jsonl
 - docs/self-docs/COMPLIANCE.md
@@ -442,6 +443,7 @@ files:
 - lib/ecoportal/api/graphql/base/page/phased/stage.rb
 - lib/ecoportal/api/graphql/base/page/section.rb
 - lib/ecoportal/api/graphql/base/page/section_collection.rb
+- lib/ecoportal/api/graphql/base/page/task.rb
 - lib/ecoportal/api/graphql/base/page_info.rb
 - lib/ecoportal/api/graphql/base/pages_workflow.rb
 - lib/ecoportal/api/graphql/base/pages_workflow/action_type_selection.rb
@@ -471,6 +473,7 @@ files:
 - lib/ecoportal/api/graphql/base/preview_page.rb
 - lib/ecoportal/api/graphql/base/register.rb
 - lib/ecoportal/api/graphql/base/resource.rb
+- lib/ecoportal/api/graphql/base/template.rb
 - lib/ecoportal/api/graphql/builder.rb
 - lib/ecoportal/api/graphql/builder/CLAUDE.md
 - lib/ecoportal/api/graphql/builder/action.rb
@@ -530,15 +533,18 @@ files:
 - lib/ecoportal/api/graphql/fragment/action.rb
 - lib/ecoportal/api/graphql/fragment/action_category.rb
 - lib/ecoportal/api/graphql/fragment/contractor_entity.rb
+- lib/ecoportal/api/graphql/fragment/field_configuration.rb
 - lib/ecoportal/api/graphql/fragment/force.rb
 - lib/ecoportal/api/graphql/fragment/location_draft.rb
 - lib/ecoportal/api/graphql/fragment/location_node.rb
 - lib/ecoportal/api/graphql/fragment/locations_error.rb
 - lib/ecoportal/api/graphql/fragment/page.rb
+- lib/ecoportal/api/graphql/fragment/page_task.rb
 - lib/ecoportal/api/graphql/fragment/pages.rb
 - lib/ecoportal/api/graphql/fragment/pages/common_page_union.rb
 - lib/ecoportal/api/graphql/fragment/pages_workflow.rb
 - lib/ecoportal/api/graphql/fragment/pagination.rb
+- lib/ecoportal/api/graphql/fragment/template.rb
 - lib/ecoportal/api/graphql/helpers.rb
 - lib/ecoportal/api/graphql/helpers/locations_tree.rb
 - lib/ecoportal/api/graphql/input.rb
@@ -728,6 +734,7 @@ files:
 - lib/ecoportal/api/graphql/model/page/phased.rb
 - lib/ecoportal/api/graphql/model/page/phased/stage.rb
 - lib/ecoportal/api/graphql/model/page/section.rb
+- lib/ecoportal/api/graphql/model/page/task.rb
 - lib/ecoportal/api/graphql/model/page_union.rb
 - lib/ecoportal/api/graphql/model/pages_workflow.rb
 - lib/ecoportal/api/graphql/model/person_member.rb
@@ -735,6 +742,7 @@ files:
 - lib/ecoportal/api/graphql/model/preview_page.rb
 - lib/ecoportal/api/graphql/model/register.rb
 - lib/ecoportal/api/graphql/model/resource.rb
+- lib/ecoportal/api/graphql/model/template.rb
 - lib/ecoportal/api/graphql/model/user.rb
 - lib/ecoportal/api/graphql/mutation.rb
 - lib/ecoportal/api/graphql/mutation/action.rb
@@ -834,6 +842,7 @@ files:
 - lib/ecoportal/api/graphql/payload/page/create_from_template.rb
 - lib/ecoportal/api/graphql/payload/page/draft.rb
 - lib/ecoportal/api/graphql/payload/page/review_task.rb
+- lib/ecoportal/api/graphql/payload/page/review_task_batch.rb
 - lib/ecoportal/api/graphql/payload/page/unarchive.rb
 - lib/ecoportal/api/graphql/payload/page/update.rb
 - lib/ecoportal/api/graphql/payload/page/update_variable_bindings.rb
@@ -872,6 +881,7 @@ files:
 - tests/contractor_entity_create.rb
 - tests/contractor_entity_udpate.rb
 - tests/dump_page_model.rb
+- tests/dump_schema.rb
 - tests/dump_template_model.rb
 - tests/loc_structure_get.rb
 - tests/loc_structure_update.rb