ecoportal-api-graphql 1.3.5 → 1.3.17

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

@@ -1,41 +1,210 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Builder
-        class Page
-          attr_reader :client
-
-          def initialize(client)
-            @client = client
-          end
-
-          # def archive(**kargs, &block)
-          #   archiveMutation.query(**kargs, &block)
-          # end
-
-          # def update(**kargs, &block)
-          #   updateMutation.query(**kargs, &block)
-          # end
-
-          # def create(**kargs, &block)
-          #   createMutation.query(**kargs, &block)
-          # end
-
-          private
-
-          # def archiveMutation
-          #   Mutation::Page::Archive.new(client)
-          # end
-
-          # def updateMutation
-          #   Mutation::Page::Update.new(client)
-          # end
-
-          # def createMutation
-          #   Mutation::Page::Create.new(client)
-          # end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Builder
+        class Page
+          attr_reader :client
+
+          def initialize(client)
+            @client = client
+          end
+
+          def update(**kargs, &block)
+            updateMutation.query(**kargs, &block)
+          end
+
+          # Archive a page. With `clear_external_id: true`, first BLANKS the page's externalId
+          # (a separate updatePage) before archiving, so the freed id can be reused. Use this
+          # ONLY when archiving a failed / duplicate creation. Default false: a genuine
+          # historical archive KEEPS its externalId — the integration pairing key, unique per
+          # org per model (see ecoPortal_architecture/02_data_model.md).
+          #
+          # Implemented as two serial mutations (blank-then-archive) reusing the existing
+          # update/archive mutations. (The equivalent atomic single-document composite —
+          # `updatePage(page:{externalId:null}) @include(if:$blank) archivePage` — is a possible
+          # future refinement if blank-then-archive atomicity is ever required.)
+          def archive(clear_external_id: false, **kargs, &block)
+            blank_external_id(kargs) if clear_external_id
+            archiveMutation.query(**kargs, &block)
+          end
+
+          def unarchive(**kargs, &block)
+            unarchiveMutation.query(**kargs, &block)
+          end
+
+          def build_from_template(**kargs, &block)
+            buildFromTemplateMutation.query(**kargs, &block)
+          end
+
+          def create_from_template(**kargs, &block)
+            createFromTemplateMutation.query(**kargs, &block)
+          end
+
+          def create_draft(**kargs, &block)
+            createDraftMutation.query(**kargs, &block)
+          end
+
+          def delete_draft(**kargs, &block)
+            deleteDraftMutation.query(**kargs, &block)
+          end
+
+          def publish_draft(**kargs, &block)
+            publishDraftMutation.query(**kargs, &block)
+          end
+
+          def approve_review_task(**kargs, &block)
+            approveReviewTaskMutation.query(**kargs, &block)
+          end
+
+          def reject_review_task(**kargs, &block)
+            rejectReviewTaskMutation.query(**kargs, &block)
+          end
+
+          def restart_review_task(**kargs, &block)
+            restartReviewTaskMutation.query(**kargs, &block)
+          end
+
+          def undo_review_task(**kargs, &block)
+            undoReviewTaskMutation.query(**kargs, &block)
+          end
+
+          def batch_update_review_task(**kargs, &block)
+            batchUpdateReviewTaskMutation.query(**kargs, &block)
+          end
+
+          # Executes workflow commands against a page or template.
+          # @param model [Base::Page::*] the page/template (must have id and patchVer)
+          # @param commands [Array<Hash>] array of WorkflowCommandInput hashes
+          # @param patch_ver [Integer] override patchVer (defaults to model.patchVer)
+          def execute_workflow_commands(model, commands:, patch_ver: model.patchVer, &block)
+            executeWorkflowCommandsMutation.query(
+              id:        model.id,
+              patch_ver: patch_ver,
+              commands:  commands,
+              &block
+            )
+          end
+
+          # @deprecated Use execute_workflow_commands instead.
+          def execute_force_commands(id:, patch_ver:, commands:, &block)
+            Concerns::Deprecation.warn_once(:execute_force_commands,
+                                            'Use execute_workflow_commands(model, commands: [...]) instead')
+            executeForceMutation.query(id: id, patch_ver: patch_ver, commands: commands, &block)
+          end
+
+          def update_variable_bindings(**kargs, &block)
+            updateVariableBindingsMutation.query(**kargs, &block)
+          end
+
+          # AI field mutations
+          def generate_ai_summary(**kargs, &block)
+            generateAiSummaryMutation.query(**kargs, &block)
+          end
+
+          def submit_ai_summary_feedback(**kargs, &block)
+            submitAiSummaryFeedbackMutation.query(**kargs, &block)
+          end
+
+          def generate_smart_fill(**kargs, &block)
+            generateSmartFillMutation.query(**kargs, &block)
+          end
+
+          def submit_smart_fill_feedback(**kargs, &block)
+            submitSmartFillFeedbackMutation.query(**kargs, &block)
+          end
+
+          private
+
+          # Blank the page's externalId via updatePage (no patchVer needed — cleanup path).
+          # Reads the id from the archive kargs (input: { id: }).
+          def blank_external_id(kargs)
+            id = kargs.dig(:input, :id) || kargs[:id]
+            return unless id
+
+            updateMutation.query(input: { id: id, page: { externalId: nil } })
+          end
+
+          def updateMutation
+            Mutation::Page::Update.new(client)
+          end
+
+          def archiveMutation
+            Mutation::Page::Archive.new(client)
+          end
+
+          def unarchiveMutation
+            Mutation::Page::Unarchive.new(client)
+          end
+
+          def buildFromTemplateMutation
+            Mutation::Page::BuildFromTemplate.new(client)
+          end
+
+          def createFromTemplateMutation
+            Mutation::Page::CreateFromTemplate.new(client)
+          end
+
+          def createDraftMutation
+            Mutation::Page::CreateDraft.new(client)
+          end
+
+          def deleteDraftMutation
+            Mutation::Page::DeleteDraft.new(client)
+          end
+
+          def publishDraftMutation
+            Mutation::Page::PublishDraft.new(client)
+          end
+
+          def approveReviewTaskMutation
+            Mutation::Page::ApproveReviewTask.new(client)
+          end
+
+          def rejectReviewTaskMutation
+            Mutation::Page::RejectReviewTask.new(client)
+          end
+
+          def restartReviewTaskMutation
+            Mutation::Page::RestartReviewTask.new(client)
+          end
+
+          def undoReviewTaskMutation
+            Mutation::Page::UndoReviewTask.new(client)
+          end
+
+          def batchUpdateReviewTaskMutation
+            Mutation::Page::BatchUpdateReviewTask.new(client)
+          end
+
+          def generateAiSummaryMutation
+            Mutation::AiSummary::Generate.new(client)
+          end
+
+          def submitAiSummaryFeedbackMutation
+            Mutation::AiSummary::SubmitFeedback.new(client)
+          end
+
+          def generateSmartFillMutation
+            Mutation::SmartFill::Generate.new(client)
+          end
+
+          def submitSmartFillFeedbackMutation
+            Mutation::SmartFill::SubmitFeedback.new(client)
+          end
+
+          def executeWorkflowCommandsMutation
+            Mutation::Page::ExecuteWorkflowCommands.new(client)
+          end
+
+          def executeForceMutation
+            Mutation::Page::ExecuteForceCommands.new(client)
+          end
+
+          def updateVariableBindingsMutation
+            Mutation::Page::UpdateVariableBindings.new(client)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +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

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

@@ -1,41 +1,49 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Builder
-        class Register
-          attr_reader :client
-
-          def initialize(client)
-            @client = client
-          end
-
-          # def archive(**kargs, &block)
-          #   archiveMutation.query(**kargs, &block)
-          # end
-
-          # def update(**kargs, &block)
-          #   updateMutation.query(**kargs, &block)
-          # end
-
-          # def create(**kargs, &block)
-          #   createMutation.query(**kargs, &block)
-          # end
-
-          private
-
-          # def archiveMutation
-          #   Mutation::Register::Archive.new(client)
-          # end
-
-          # def updateMutation
-          #   Mutation::Register::Update.new(client)
-          # end
-
-          # def createMutation
-          #   Mutation::Register::Create.new(client)
-          # end
-        end
-      end
-    end
-  end
-end
+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

@@ -0,0 +1,80 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Builder
+        class Template
+          attr_reader :client
+
+          def initialize(client)
+            @client = client
+          end
+
+          def create(commands:, &block)
+            createMutation.query(commands: commands, &block)
+          end
+
+          def update(model, commands:, patch_ver: model.patchVer, &block)
+            updateMutation.query(id: model.id, patch_ver: patch_ver, commands: commands, &block)
+          end
+
+          def publish(id:, &block)
+            publishMutation.query(id: id, &block)
+          end
+
+          def unpublish(id:, &block)
+            unpublishMutation.query(id: id, &block)
+          end
+
+          def update_information(id:, **kargs, &block)
+            updateInformationMutation.query(id: id, **kargs, &block)
+          end
+
+          def create_related_page(template_id:, title:, register_id:, patch_ver:, filters: nil, &block)
+            createRelatedPageMutation.query(
+              template_id: template_id,
+              title:       title,
+              register_id: register_id,
+              patch_ver:   patch_ver,
+              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
+
+          private
+
+          def createMutation
+            Mutation::Template::Create.new(client)
+          end
+
+          def updateMutation
+            Mutation::Template::Update.new(client)
+          end
+
+          def publishMutation
+            Mutation::Template::Publish.new(client)
+          end
+
+          def unpublishMutation
+            Mutation::Template::Unpublish.new(client)
+          end
+
+          def updateInformationMutation
+            Mutation::Template::UpdateInformation.new(client)
+          end
+
+          def createRelatedPageMutation
+            Mutation::Template::CreateRelatedPage.new(client)
+          end
+
+          def destroyRelatedPageMutation
+            Mutation::Template::DestroyRelatedPage.new(client)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,174 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Builder
+        # Build-from-scratch emitter for a template/workflow: turns a DECLARATIVE spec
+        # (stages -> sections -> fields -> options / config / gauge-stops) into an ordered batch of
+        # built `WorkflowCommand` hashes, ready for `Builder::Template#create(commands:)` /
+        # `#update(model, commands:)` (which wrap `executeWorkflowCommands`).
+        #
+        # This is the gem-level, reusable BUILD emitter (previously a one-off in eco-helpers samples).
+        # It shares ONE emission layer with the DIFF-DEPLOY pipeline: both produce an ordered
+        # `WorkflowCommand` batch, and both use the SAME `placeholderId` id-threading primitive that
+        # `Diff::CommandSynthesizer` uses — a newly-created node is addressed by a client-chosen
+        # `placeholderId`, and every later command in the same batch that references it substitutes
+        # that placeholder (the server has not assigned real ids yet). Here every node is brand new,
+        # so the whole batch is threaded through placeholders.
+        #
+        # SPEC SHAPE (all keys optional unless noted; only VALID command inputs are emitted):
+        #
+        #   {
+        #     stages: [
+        #       { name: 'Report', ordering: 0, sections: [        # addStage(name, ordering)
+        #         { layout: 'ONE_COLUMN', fields: [               # addSection(layout) + addStageSection
+        #           { 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
+        #             config: { select: { multiple: false } } },                   # editFieldConfiguration(byType:)
+        #           { field_type: 'Gauge', label: 'Risk',
+        #             stops: [ { threshold: 0, color: '#0f0' }, ... ],              # addGaugeFieldStop
+        #             config: { gauge: { max: 100.0 } } }
+        #         ] }
+        #       ] }
+        #     ]
+        #   }
+        #
+        # ORDER — addStage -> addSection -> addStageSection -> addField -> (addSelectFieldOption |
+        # addGaugeFieldStop | editFieldConfiguration). This is the dependency-safe order the workflow
+        # command bus expects; placeholderId resolution makes the intra-batch references valid.
+        #
+        # SAFETY — only keys present in each command input's VALID_KEYS are emitted (the input classes
+        # slice + compact). A spec key with no corresponding command input is dropped, not fabricated.
+        # `field_type` shape and per-type config (`byType`) are NOT invented: config is passed through
+        # under its byType sub-hash exactly as given (the caller supplies confirmed byType keys), and
+        # is emitted only for a field that carries one.
+        class TemplateBuilder
+          # @param spec [Hash] the declarative template spec (see class doc). String or symbol keys.
+          def initialize(spec)
+            @spec         = symbolize(spec || {})
+            @commands     = []
+            @counter      = 0
+            @built        = false
+          end
+
+          # Ordered Array of built command hashes ({ commandKey => input }), placeholder-threaded.
+          def commands
+            return @commands if @built
+
+            @built = true
+            build_all
+          end
+
+          # Ready to hand to `Builder::Template#create(commands: builder.to_commands)`.
+          alias_method :to_commands, :commands
+
+          def to_h
+            { commands: commands }
+          end
+
+          private
+
+          def build_all
+            Array(@spec[:stages]).each_with_index { |stage, idx| emit_stage(stage, idx) }
+            @commands
+          end
+
+          def emit_stage(stage, index)
+            stage_ph = placeholder(:stg)
+            add(:addStage, name: stage[:name], ordering: stage.fetch(:ordering, index), placeholderId: stage_ph)
+            Array(stage[:sections]).each { |section| emit_section(section, stage_ph) }
+          end
+
+          def emit_section(section, stage_ph)
+            section_ph = placeholder(:sec)
+            add(:addSection, layout: section[:layout], placeholderId: section_ph)
+            # Attach the freshly-created section to its (freshly-created) stage.
+            add(:addStageSection, stageId: stage_ph, sectionId: section_ph)
+            emit_section_heading(section, section_ph)
+            Array(section[:fields]).each { |field| emit_field(field, stage_ph, section_ph) }
+          end
+
+          # A section's heading is not an addSection input; set it via editSectionHeader after create.
+          def emit_section_heading(section, section_ph)
+            heading = section[:heading]
+            return if heading.nil?
+
+            add(:editSectionHeader, sectionId: section_ph, header: heading)
+          end
+
+          def emit_field(field, stage_ph, section_ph)
+            field_ph = placeholder(:fld)
+            add(:addField,
+                fieldType:     field[:field_type] || field[:fieldType],
+                label:         field[:label],
+                stageId:       stage_ph,
+                sectionId:     section_ph,
+                column:        field[:column],
+                placeholderId: field_ph)
+            emit_description(field, field_ph)
+            emit_options(field, field_ph)
+            emit_stops(field, field_ph)
+            emit_config(field, field_ph)
+          end
+
+          # A field's `description` is NOT an addField input (the schema's WorkflowAddFieldInput has
+          # no `description` key — VERIFIED against the 20260605 dump). It is a top-level key of
+          # editFieldConfiguration, so we persist it with a follow-up editFieldConfiguration
+          # addressed to the freshly-created field placeholder. Emitted only when supplied. This is
+          # the seam the CSV/hidden-field identity token rides on. NOTE: `required` has no schema
+          # input key at all, so it is intentionally NOT emitted (a spec `required:` is ignored).
+          def emit_description(field, field_ph)
+            description = field[:description]
+            return if description.nil?
+
+            add(:editFieldConfiguration, data_field_id: field_ph, description: description)
+          end
+
+          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])
+            end
+          end
+
+          def emit_stops(field, field_ph)
+            Array(field[:stops]).each do |stop|
+              add(:addGaugeFieldStop, data_field_id: field_ph, threshold: stop[:threshold], color: stop[:color])
+            end
+          end
+
+          # Per-type field configuration passed through under its byType sub-hash exactly as supplied
+          # (e.g. { select: { multiple: true } }, { gauge: { max: 100.0 } }). Emitted only when
+          # present; keys are validated/sliced by the EditFieldConfiguration input, never fabricated.
+          def emit_config(field, field_ph)
+            config = field[:config]
+            return if config.nil? || config.empty?
+
+            add(:editFieldConfiguration, data_field_id: field_ph, byType: symbolize(config))
+          end
+
+          # Build one command and append it. Reuses the SAME builder the diff synthesizer uses, so
+          # BUILD and DIFF-DEPLOY emit through one layer.
+          def add(command_key, **kwargs)
+            @commands << Ecoportal::API::GraphQL::Input::WorkflowCommand.build(command_key, **kwargs)
+          end
+
+          # A deterministic client-chosen placeholderId — the id-threading primitive shared with the
+          # diff synthesizer. Prefix marks the node kind for readability of the emitted batch.
+          def placeholder(prefix)
+            @counter += 1
+            "ph_#{prefix}_#{@counter}"
+          end
+
+          def symbolize(value)
+            case value
+            when Hash  then value.each_with_object({}) { |(k, v), h| h[k.to_sym] = symbolize(v) }
+            when Array then value.map { |e| symbolize(e) }
+            else value
+            end
+          end
+        end
+      end
+    end
+  end
+end