ecoportal-api-graphql 1.3.16 → 2.2.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,10 +40,48 @@ 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
 
+          # TEMPLATE CHANGE LOG — who changed this template, what, and when. Newest first
+          # (server-side `_id: :desc`), paginated.
+          #
+          #   api.template.change_log(id: template_page_id, first: 50)   # => Connection
+          #   api.template.change_log.each(id: template_page_id) { |e| ... }  # auto-paginates
+          #
+          # ★ Two caveats, both silent — read `Base::Template::ChangeLogEntry` before relying on
+          # this: the connection is nil (not empty) unless the caller satisfies
+          # `Pages::TemplatePolicy#update_information?`, and only TEMPLATE_BUILDER-sourced
+          # commands appear (workflow-builder ones are on `Query::PagesWorkflowCommands`).
+          #
+          # Called with no arguments it returns the query object itself, so `#each` /`#map` and
+          # the rest of Enumerable are available — same idiom as the QueryIntegration queries on
+          # `Model::Organization`.
+          # @param detail [Boolean] when true, also select FIELD-LEVEL detail (what changed).
+          #   Ignored when an explicit block is given -- the block wins, since it is the more
+          #   specific instruction. Off by default so the common who/when read stays cheap.
+          def change_log(detail: false, **kargs, &block)
+            selection = block || (detail ? Query::TemplateChangeLog.detail_block : nil)
+            return changeLogQuery if kargs.empty? && !selection
+
+            changeLogQuery.query(**kargs, &selection)
+          end
+
           private
 
           def createMutation
@@ -70,9 +108,17 @@ module Ecoportal
             Mutation::Template::CreateRelatedPage.new(client)
           end
 
+          def updateRelatedPageMutation
+            Mutation::Template::UpdateRelatedPage.new(client)
+          end
+
           def destroyRelatedPageMutation
             Mutation::Template::DestroyRelatedPage.new(client)
           end
+
+          def changeLogQuery
+            Query::TemplateChangeLog.new(client)
+          end
         end
       end
     end

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

@@ -24,7 +24,12 @@ module Ecoportal
         #           { field_type: 'PlainText', label: 'Description', column: 0,
         #             description: 'ID:token' },   # addField (+ editFieldConfiguration for description)
         #           { field_type: 'Select', label: 'Severity',
-        #             options: [ { label: 'Low', weight: 0 }, ... ],                # addSelectFieldOption
+        #             options: [ { label: 'Low', weight: 0, value: 'low' },
+        #                        { label: 'High', weight: 10, value: 'high' } ], # addSelectFieldOption
+        #             # `value:` is REQUIRED per option (backend: AddSelectFieldOptionInput,
+        #             # required: true) — it is the option's unique key (duplicate values within one
+        #             # field are rejected), always sent as a String even for numeric select fields
+        #             # (stored as an Integer server-side). A missing `value` raises ArgumentError.
         #             config: { select: { multiple: false } } },                   # editFieldConfiguration(byType:)
         #           { field_type: 'Gauge', label: 'Risk',
         #             stops: [ { threshold: 0, color: '#0f0' }, ... ],              # addGaugeFieldStop
@@ -125,9 +130,23 @@ module Ecoportal
             add(:editFieldConfiguration, data_field_id: field_ph, description: description)
           end
 
+          # addSelectFieldOption requires `value` (backend: AddSelectFieldOptionInput, required: true
+          # — a real field distinct from label/weight, cast to a number server-side for numeric
+          # select fields). The DSL has no natural default for it (unlike label/weight, it is
+          # business data this builder cannot infer), so it MUST be supplied per option in the spec;
+          # a missing one raises rather than silently falling back to the label/weight (which would
+          # risk persisting the wrong stored value for a scored/numeric select field).
           def emit_options(field, field_ph)
             Array(field[:options]).each do |opt|
-              add(:addSelectFieldOption, data_field_id: field_ph, label: opt[:label], weight: opt[:weight])
+              value = opt[:value]
+              if value.nil?
+                raise ArgumentError,
+                      "TemplateBuilder: option '#{opt[:label]}' on field '#{field[:label]}' is " \
+                      'missing `value` (addSelectFieldOption requires it) — supply ' \
+                      'options: [{ label:, weight:, value: }, ...] in the spec'
+              end
+
+              add(:addSelectFieldOption, data_field_id: field_ph, label: opt[:label], value: value, weight: opt[:weight])
             end
           end
 

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