ecoportal-api-graphql 2.0.0 → 3.0.0

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

@@ -9,12 +9,17 @@ module Ecoportal
             @client = client
           end
 
-          def create(commands:, &block)
-            createMutation.query(commands: commands, &block)
+          # @param register_id [String, nil] bind the new template to this register. Optional in
+          #   the schema, but in practice REQUIRED for the create to be authorized at all — see
+          #   the WHY in {Mutation::Template::Create}. Omitted when nil.
+          def create(commands:, register_id: nil, &block)
+            createMutation.query(commands: commands, register_id: register_id, &block)
           end
 
-          def update(model, commands:, patch_ver: model.patchVer, &block)
-            updateMutation.query(id: model.id, patch_ver: patch_ver, commands: commands, &block)
+          def update(model, commands:, patch_ver: model.patchVer, client_mutation_id: nil, &block)
+            kwargs = { id: model.id, patch_ver: patch_ver, commands: commands }
+            kwargs[:client_mutation_id] = client_mutation_id unless client_mutation_id.nil?
+            updateMutation.query(**kwargs, &block)
           end
 
           def publish(id:, &block)
@@ -58,6 +63,30 @@ module Ecoportal
             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
@@ -91,6 +120,10 @@ module Ecoportal
           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/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 .ai-assistance/code/search_filters.md.
+        # Operation/param shapes per the repo's internal docs
         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/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/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'