ecoportal-api-graphql 1.3.17 → 2.0.0

data/lib/ecoportal/api/graphql/builder/register/preset_view.rb

@@ -1,84 +1,84 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Builder
-        class Register
-          # Sub-builder for preset view operations within a register context.
-          # Access via: api.register.preset_view
-          #
-          # Usage:
-          #   pv = api.register.preset_view
-          #
-          #   # List preset views for a register (find IDs for presetViewId in searches)
-          #   views = pv.list('REG_ID')
-          #   views.map { |v| "#{v.name} (#{v.id}) global=#{v.global?}" }
-          #
-          #   # Create a preset view
-          #   pv.create(input: {
-          #     registerId:     'REG_ID',
-          #     name:           'Active Pages',
-          #     customPresetView: true,
-          #     fieldConfigs:   [{ key: 'name', weight: 0 }, { key: 'state', weight: 1 }],
-          #     sorter:         { key: 'created_at', direction: 'desc' }
-          #   })
-          #
-          #   # Share with a user (view access)
-          #   pv.permission(input: {
-          #     id:          'VIEW_ID',
-          #     permissions: [{ level: 'view', to: { userId: 'USER_ID' } }]
-          #   })
-          class PresetView
-            attr_reader :client
-
-            def initialize(client)
-              @client = client
-            end
-
-            # List all preset views for a register. Returns an array of PresetView objects.
-            def list(register_id, search_conf: nil, &block)
-              Query::RegisterPresetViews.new(client).query(
-                registerId: register_id,
-                searchConf: search_conf,
-                &block
-              ).nodes
-            end
-
-            def create(**kargs, &block)
-              createMutation.query(**kargs, &block)
-            end
-
-            def update(**kargs, &block)
-              updateMutation.query(**kargs, &block)
-            end
-
-            def permission(**kargs, &block)
-              permissionMutation.query(**kargs, &block)
-            end
-
-            def destroy(**kargs, &block)
-              destroyMutation.query(**kargs, &block)
-            end
-
-            private
-
-            def createMutation
-              Mutation::PresetView::Create.new(client)
-            end
-
-            def updateMutation
-              Mutation::PresetView::Update.new(client)
-            end
-
-            def permissionMutation
-              Mutation::PresetView::Permission.new(client)
-            end
-
-            def destroyMutation
-              Mutation::PresetView::Destroy.new(client)
-            end
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Builder
+        class Register
+          # Sub-builder for preset view operations within a register context.
+          # Access via: api.register.preset_view
+          #
+          # Usage:
+          #   pv = api.register.preset_view
+          #
+          #   # List preset views for a register (find IDs for presetViewId in searches)
+          #   views = pv.list('REG_ID')
+          #   views.map { |v| "#{v.name} (#{v.id}) global=#{v.global?}" }
+          #
+          #   # Create a preset view
+          #   pv.create(input: {
+          #     registerId:     'REG_ID',
+          #     name:           'Active Pages',
+          #     customPresetView: true,
+          #     fieldConfigs:   [{ key: 'name', weight: 0 }, { key: 'state', weight: 1 }],
+          #     sorter:         { key: 'created_at', direction: 'desc' }
+          #   })
+          #
+          #   # Share with a user (view access)
+          #   pv.permission(input: {
+          #     id:          'VIEW_ID',
+          #     permissions: [{ level: 'view', to: { userId: 'USER_ID' } }]
+          #   })
+          class PresetView
+            attr_reader :client
+
+            def initialize(client)
+              @client = client
+            end
+
+            # List all preset views for a register. Returns an array of PresetView objects.
+            def list(register_id, search_conf: nil, &block)
+              Query::RegisterPresetViews.new(client).query(
+                registerId: register_id,
+                searchConf: search_conf,
+                &block
+              ).nodes
+            end
+
+            def create(**kargs, &block)
+              createMutation.query(**kargs, &block)
+            end
+
+            def update(**kargs, &block)
+              updateMutation.query(**kargs, &block)
+            end
+
+            def permission(**kargs, &block)
+              permissionMutation.query(**kargs, &block)
+            end
+
+            def destroy(**kargs, &block)
+              destroyMutation.query(**kargs, &block)
+            end
+
+            private
+
+            def createMutation
+              Mutation::PresetView::Create.new(client)
+            end
+
+            def updateMutation
+              Mutation::PresetView::Update.new(client)
+            end
+
+            def permissionMutation
+              Mutation::PresetView::Permission.new(client)
+            end
+
+            def destroyMutation
+              Mutation::PresetView::Destroy.new(client)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/builder/register.rb

@@ -1,49 +1,49 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Builder
-        class Register
-          attr_reader :client
-
-          def initialize(client)
-            @client = client
-          end
-
-          # Register CRUD
-          def create(**kargs, &block)
-            createMutation.query(**kargs, &block)
-          end
-
-          def update(**kargs, &block)
-            updateMutation.query(**kargs, &block)
-          end
-
-          def destroy(**kargs, &block)
-            destroyMutation.query(**kargs, &block)
-          end
-
-          # Preset view sub-builder — list, create, update, permission, destroy
-          def preset_view
-            Register::PresetView.new(client)
-          end
-
-          private
-
-          def createMutation
-            Mutation::Register::Create.new(client)
-          end
-
-          def updateMutation
-            Mutation::Register::Update.new(client)
-          end
-
-          def destroyMutation
-            Mutation::Register::Destroy.new(client)
-          end
-        end
-      end
-    end
-  end
-end
-
-require_relative 'register/preset_view'
+module Ecoportal
+  module API
+    class GraphQL
+      module Builder
+        class Register
+          attr_reader :client
+
+          def initialize(client)
+            @client = client
+          end
+
+          # Register CRUD
+          def create(**kargs, &block)
+            createMutation.query(**kargs, &block)
+          end
+
+          def update(**kargs, &block)
+            updateMutation.query(**kargs, &block)
+          end
+
+          def destroy(**kargs, &block)
+            destroyMutation.query(**kargs, &block)
+          end
+
+          # Preset view sub-builder — list, create, update, permission, destroy
+          def preset_view
+            Register::PresetView.new(client)
+          end
+
+          private
+
+          def createMutation
+            Mutation::Register::Create.new(client)
+          end
+
+          def updateMutation
+            Mutation::Register::Update.new(client)
+          end
+
+          def destroyMutation
+            Mutation::Register::Destroy.new(client)
+          end
+        end
+      end
+    end
+  end
+end
+
+require_relative 'register/preset_view'

data/lib/ecoportal/api/graphql/builder/template.rb

@@ -40,6 +40,20 @@ module Ecoportal
             )
           end
 
+          # Edits an existing related-pages entry. Only the keys you pass are sent — absent keys
+          # are left alone server-side, so this is a partial update, not a replace.
+          def update_related_page(template_id:, id:, patch_ver:, title: nil, register_id: nil, filters: nil, &block)
+            updateRelatedPageMutation.query(
+              template_id: template_id,
+              id:          id,
+              patch_ver:   patch_ver,
+              title:       title,
+              register_id: register_id,
+              filters:     filters,
+              &block
+            )
+          end
+
           def destroy_related_page(template_id:, id:, patch_ver:, &block)
             destroyRelatedPageMutation.query(template_id: template_id, id: id, patch_ver: patch_ver, &block)
           end
@@ -70,6 +84,10 @@ module Ecoportal
             Mutation::Template::CreateRelatedPage.new(client)
           end
 
+          def updateRelatedPageMutation
+            Mutation::Template::UpdateRelatedPage.new(client)
+          end
+
           def destroyRelatedPageMutation
             Mutation::Template::DestroyRelatedPage.new(client)
           end

data/lib/ecoportal/api/graphql/compat/filter_translator.rb

@@ -18,7 +18,7 @@ module Ecoportal
         #   tag_filter      passed through (same ES backend, same format)
         #   register_filter passed through
         #   and_filter / or_filter  passed through
-        # Operation/param shapes per the repo's internal docs.
+        # Operation/param shapes per .ai-assistance/code/search_filters.md.
         class FilterTranslator
           class << self
             def to_graphql(filter)

data/lib/ecoportal/api/graphql/compat/page_reference.rb

@@ -1,23 +1,23 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Compat
-        # Returned by Compat::Pages#create — mirrors the v2 reference object.
-        # Scripts access .page_id and .active_stage_id after page creation.
-        class PageReference
-          attr_reader :page_id, :active_stage_id, :page
-
-          def initialize(page)
-            @page            = page
-            @page_id         = page.id
-            @active_stage_id = page.respond_to?(:current_stage_id) ? page.current_stage_id : nil
-          end
-
-          def success?
-            !@page_id.nil?
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Compat
+        # Returned by Compat::Pages#create — mirrors the v2 reference object.
+        # Scripts access .page_id and .active_stage_id after page creation.
+        class PageReference
+          attr_reader :page_id, :active_stage_id, :page
+
+          def initialize(page)
+            @page            = page
+            @page_id         = page.id
+            @active_stage_id = page.respond_to?(:current_stage_id) ? page.current_stage_id : nil
+          end
+
+          def success?
+            !@page_id.nil?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/compat/pages.rb

@@ -18,8 +18,13 @@ module Ecoportal
           # Fetch a page by ID with full data — metadata, stages, sections, data fields.
           # When stage_id is provided, wraps the result in a StageView that filters
           # sections and components to that stage only — matching v2 per-stage behaviour.
-          def get(id, stage_id: nil)
-            page = Query::Page.new(@client).query(id: id) do
+          # @param variables [Hash] optional CommonPageUnion document-variable overrides
+          #   (`showHiddenData:`, `content:`, `only_content:`, `fields:`). `content: false`
+          #   skips field values AND `attachedFiles` — the one selection preauthorized on the
+          #   `files: download` ability — so structure-only readers (e.g. template tooling on a
+          #   least-privilege account) can read pages without that grant.
+          def get(id, stage_id: nil, **variables)
+            page = Query::Page.new(@client).query(id: id, **variables) do
               spread :CommonPageUnion
             end
             stage_id ? StageView.new(page, stage_id) : page

data/lib/ecoportal/api/graphql/compat/registers.rb

@@ -1,84 +1,84 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Compat
-        # v2-compatible registers API backed by GraphQL register search.
-        # Scripts call: apiv2.registers.search(register_id, options) { |result| ... }
-        #
-        # With a block: yields each PreviewPage result (cursor-paginated).
-        # Without a block (or only_first: true): returns a SearchResults object
-        #   with .total and .total_before_filtering.
-        #
-        # Filter translation:
-        #   v2 date_filter { lbound:, ubound: } → GraphQL date_filter { gte:, lte: }
-        #   v2 tag_filter  { tags:, mode: }     → passed through (same ES backend)
-        #   SearchConf filter objects            → passed through directly
-        class Registers
-          def initialize(client)
-            @client = client
-          end
-
-          # Options:
-          #   sort:             'created_at' | 'updated_at'
-          #   dir:              'asc' | 'desc'
-          #   query:            String (full-text search)
-          #   filters:          Array of filter objects or v2 filter hashes
-          #   batch_size:       Integer (results per request, default 20)
-          #   include_archived: Boolean (default false)
-          #   only_first:       Boolean — return after first page (no block needed)
-          def search(register_id, options = {}, &block)
-            conf  = build_search_conf(options)
-            first = options.fetch(:batch_size, 20)
-            query = Query::RegisterPreviewPages.new(@client)
-
-            args = {
-              registerId:      register_id,
-              searchConf:      conf.to_h,
-              includeArchived: options.fetch(:include_archived, false),
-              first:           first
-            }
-
-            if block || !options[:only_first]
-              # Block mode: yield each result, stop if only_first
-              query.each(**args) do |result|
-                block&.call(result)
-                break if options[:only_first]
-              end
-            else
-              # No-block mode: return SearchResults with .total etc.
-              raw = query.query(**args)
-              SearchResults.new(raw)
-            end
-          end
-
-          private
-
-          def build_search_conf(options)
-            conf = Input::SearchConf.new
-
-            if (sort_key = options[:sort])
-              direction = options.fetch(:dir, 'desc').to_sym
-              conf.sort(sort_key.to_sym, direction)
-            end
-
-            conf.query(options[:query]) if options[:query]
-
-            Array(options[:filters]).compact.each do |filter|
-              conf.filter(translate_filter(filter))
-            end
-
-            conf
-          end
-
-          # Translates a v2-style filter hash to a GraphQL-compatible filter hash.
-          # SearchConf filter objects (respond to to_h and are not Hash) pass through.
-          # v2 date_filter: lbound/ubound → gte/lte
-          # Other v2 types (tag_filter etc.): passed through — same ES backend.
-          def translate_filter(filter)
-            FilterTranslator.to_graphql(filter)
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Compat
+        # v2-compatible registers API backed by GraphQL register search.
+        # Scripts call: apiv2.registers.search(register_id, options) { |result| ... }
+        #
+        # With a block: yields each PreviewPage result (cursor-paginated).
+        # Without a block (or only_first: true): returns a SearchResults object
+        #   with .total and .total_before_filtering.
+        #
+        # Filter translation:
+        #   v2 date_filter { lbound:, ubound: } → GraphQL date_filter { gte:, lte: }
+        #   v2 tag_filter  { tags:, mode: }     → passed through (same ES backend)
+        #   SearchConf filter objects            → passed through directly
+        class Registers
+          def initialize(client)
+            @client = client
+          end
+
+          # Options:
+          #   sort:             'created_at' | 'updated_at'
+          #   dir:              'asc' | 'desc'
+          #   query:            String (full-text search)
+          #   filters:          Array of filter objects or v2 filter hashes
+          #   batch_size:       Integer (results per request, default 20)
+          #   include_archived: Boolean (default false)
+          #   only_first:       Boolean — return after first page (no block needed)
+          def search(register_id, options = {}, &block)
+            conf  = build_search_conf(options)
+            first = options.fetch(:batch_size, 20)
+            query = Query::RegisterPreviewPages.new(@client)
+
+            args = {
+              registerId:      register_id,
+              searchConf:      conf.to_h,
+              includeArchived: options.fetch(:include_archived, false),
+              first:           first
+            }
+
+            if block || !options[:only_first]
+              # Block mode: yield each result, stop if only_first
+              query.each(**args) do |result|
+                block&.call(result)
+                break if options[:only_first]
+              end
+            else
+              # No-block mode: return SearchResults with .total etc.
+              raw = query.query(**args)
+              SearchResults.new(raw)
+            end
+          end
+
+          private
+
+          def build_search_conf(options)
+            conf = Input::SearchConf.new
+
+            if (sort_key = options[:sort])
+              direction = options.fetch(:dir, 'desc').to_sym
+              conf.sort(sort_key.to_sym, direction)
+            end
+
+            conf.query(options[:query]) if options[:query]
+
+            Array(options[:filters]).compact.each do |filter|
+              conf.filter(translate_filter(filter))
+            end
+
+            conf
+          end
+
+          # Translates a v2-style filter hash to a GraphQL-compatible filter hash.
+          # SearchConf filter objects (respond to to_h and are not Hash) pass through.
+          # v2 date_filter: lbound/ubound → gte/lte
+          # Other v2 types (tag_filter etc.): passed through — same ES backend.
+          def translate_filter(filter)
+            FilterTranslator.to_graphql(filter)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/compat/response.rb

@@ -5,7 +5,21 @@ module Ecoportal
         # Wraps a GraphQL mutation payload to expose the v2-compatible response interface.
         # Scripts check .success? and .status after update/create operations.
         class Response
+          # The payload contract this wrapper delegates to. Guarded at construction so a
+          # payload of the wrong shape fails LOUD here, instead of silently downstream.
+          # This is the class of drift behind the eco-helpers 3.2.19 KPI-counter
+          # regression, where a Compat::Response (duck-typed, not a Common::Response)
+          # slipped through an `is_a?` check and every GraphQL update went uncounted.
+          PAYLOAD_CONTRACT = %i[success? error? error_doc item].freeze
+
           def initialize(payload)
+            missing = PAYLOAD_CONTRACT.reject { |meth| payload.respond_to?(meth) }
+            unless missing.empty?
+              raise ArgumentError,
+                    "Compat::Response payload #{payload.class} does not honour the expected " \
+                    "response contract; missing: #{missing.join(', ')}"
+            end
+
             @payload = payload
           end
 

data/lib/ecoportal/api/graphql/compat/search_results.rb

@@ -1,33 +1,33 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Compat
-        # Wraps a GraphQL connection object to expose the v2-compatible search
-        # result interface. eco-helpers scripts access:
-        #   search_results.total                  — filtered count
-        #   search_results.total_before_filtering — pre-filter count (approximated)
-        #   (also Enumerable for iteration)
-        class SearchResults
-          include Enumerable
-
-          attr_reader :total, :total_before_filtering
-
-          def initialize(connection)
-            @total                  = connection.totalCount
-            # GraphQL does not expose a pre-filter count — use the same value.
-            @total_before_filtering = connection.totalCount
-            @nodes                  = connection.nodes
-          end
-
-          def each(&block)
-            @nodes.each(&block)
-          end
-
-          def empty?
-            @nodes.empty?
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Compat
+        # Wraps a GraphQL connection object to expose the v2-compatible search
+        # result interface. eco-helpers scripts access:
+        #   search_results.total                  — filtered count
+        #   search_results.total_before_filtering — pre-filter count (approximated)
+        #   (also Enumerable for iteration)
+        class SearchResults
+          include Enumerable
+
+          attr_reader :total, :total_before_filtering
+
+          def initialize(connection)
+            @total                  = connection.totalCount
+            # GraphQL does not expose a pre-filter count — use the same value.
+            @total_before_filtering = connection.totalCount
+            @nodes                  = connection.nodes
+          end
+
+          def each(&block)
+            @nodes.each(&block)
+          end
+
+          def empty?
+            @nodes.empty?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/compat.rb

@@ -1,17 +1,17 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Compat
-      end
-    end
-  end
-end
-
-require_relative 'compat/filter_translator'
-require_relative 'compat/stage_collection'
-require_relative 'compat/search_results'
-require_relative 'compat/page_reference'
-require_relative 'compat/response'
-require_relative 'compat/stage_view'
-require_relative 'compat/pages'
-require_relative 'compat/registers'
+module Ecoportal
+  module API
+    class GraphQL
+      module Compat
+      end
+    end
+  end
+end
+
+require_relative 'compat/filter_translator'
+require_relative 'compat/stage_collection'
+require_relative 'compat/search_results'
+require_relative 'compat/page_reference'
+require_relative 'compat/response'
+require_relative 'compat/stage_view'
+require_relative 'compat/pages'
+require_relative 'compat/registers'