ecoportal-api-graphql 1.3.4 → 1.3.9

data/lib/ecoportal/api/graphql/base/preview_page.rb

@@ -0,0 +1,23 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        # Elasticsearch-backed preview of a page, returned by register.previewPages.
+        # Read-only. No patchVer, no typed data field models, no field IDs.
+        # Use for fast metadata lookup only — switch to org search (pages) for full data.
+        class PreviewPage < Logic::BaseModel
+          read_only!
+
+          passkey :id
+          passthrough :uid, :name, :state, :archived
+          passthrough :creatorName, :externalId
+          passdate :createdAt, :updatedAt
+
+          # locations, dataFields, stages returned as raw arrays — typed access not needed
+          # for a read-only ES-backed preview model. Use org search for typed field access.
+          passarray :locations, :dataFields, :stages, :tags
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        class Register < Logic::BaseModel
+          passkey :id
+          passthrough :name, :iconName, :moduleType, :registerStatus
+          passthrough :descriptionText, :descriptionImageUrl
+          passboolean :shown, :creatable, :attachable, :permissioned
+          passboolean :contentShareable, :enableEmailOut, :isMobile
+          passboolean :restrictTemplatesAmount
+          passthrough :restrictedAmountOfTemplates
+          passarray   :filterTags
+        end
+      end
+    end
+  end
+end

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

@@ -7,18 +7,29 @@ module Ecoportal
   end
 end
 
-require 'ecoportal/api/graphql/base/date_time'
-require 'ecoportal/api/graphql/base/page_info'
-require 'ecoportal/api/graphql/base/location_classification_type'
-require 'ecoportal/api/graphql/base/location_node'
-require 'ecoportal/api/graphql/base/location_structure'
-require 'ecoportal/api/graphql/base/person_member'
-require 'ecoportal/api/graphql/base/file_attachment'
-require 'ecoportal/api/graphql/base/file_container'
-require 'ecoportal/api/graphql/base/field'
-require 'ecoportal/api/graphql/base/page'
-require 'ecoportal/api/graphql/base/resource'
-require 'ecoportal/api/graphql/base/action_category'
-require 'ecoportal/api/graphql/base/action'
-require 'ecoportal/api/graphql/base/contractor_entity'
-require 'ecoportal/api/graphql/base/organization'
+require_relative 'base/date_time'
+require_relative 'base/page_info'
+require_relative 'base/location_classification_type'
+require_relative 'base/location_node'
+require_relative 'base/location_structure'
+require_relative 'base/person_member'
+require_relative 'base/file_attachment'
+require_relative 'base/file_container'
+require_relative 'base/field'
+require_relative 'base/page'
+require_relative 'base/resource'
+require_relative 'base/action_category'
+require_relative 'base/action'
+require_relative 'base/contractor_entity'
+require_relative 'base/preview_page'
+require_relative 'base/delta_result'
+require_relative 'base/organization'
+
+require_relative 'base/register'
+require_relative 'base/preset_view'
+
+require_relative 'base/ai_summary_version'
+
+require_relative 'base/force'
+require_relative 'base/pages_workflow'
+require_relative 'base/kickstand'

data/lib/ecoportal/api/graphql/builder/CLAUDE.md

@@ -0,0 +1,65 @@
+# builder
+
+Façade classes that group related mutations (and occasional queries) under a single object.
+Consumers interact with builders rather than instantiating `Logic::Mutation` / `Logic::Query`
+subclasses directly.
+
+## Contents
+
+| File / class | Exposed from `GraphQL` as | Purpose |
+|---|---|---|
+| `action.rb` / `Builder::Action` | `GraphQL#action` | `create`, `update`, `archive` — wraps `Mutation::Action::*` |
+| `contractor_entity.rb` / `Builder::ContractorEntity` | `GraphQL#contractorEntity` | `create`, `update`, `destroy` — wraps `Mutation::ContractorEntity::*` |
+| `location_structure.rb` / `Builder::LocationStructure` | `GraphQL#locationStructure` | `nodeClassifications` (query), `applyCommandsInput`, `applyCommands`, `draft` sub-builder |
+| `location_structure/draft.rb` / `Builder::LocationStructure::Draft` | via `locationStructure.draft` | Location structure draft mutations |
+| `page.rb` / `Builder::Page` | `GraphQL#page` | Full page lifecycle: `update`, `archive`, `unarchive`, `build_from_template`, `create_from_template`, `create_draft`, `delete_draft`, `publish_draft`, `approve/reject/restart/undo/batch_update_review_task`, `execute_workflow_commands` (new), `execute_force_commands` (deprecated) |
+| `register.rb` / `Builder::Register` | *(not yet exposed)* | **Stub** — all methods commented out. No `Mutation::Register::*` classes exist yet. See TODO below. |
+
+## How builders are exposed
+
+All active builders are wired in `lib/ecoportal/api/graphql.rb` as instance methods:
+
+```ruby
+def page
+  Builder::Page.new(client)
+end
+def action
+  Builder::Action.new(client)
+end
+# etc.
+```
+
+`registers` (note: plural, lowercase) returns `Compat::Registers`, **not** `Builder::Register`.
+`Builder::Register` is a stub and is not yet wired into the top-level class.
+
+## Builder::Register — TODO
+
+`builder/register.rb` contains a stub class with all methods commented out.
+Before it can be implemented:
+
+1. Research which Register mutations exist in the schema (`createRegister`,
+   `updateRegister`, `archiveRegister`, etc.) — none are currently documented
+   in `.ai-assistance/code/ecoportal_schema_reference.md`.
+2. Create `Mutation::Register::*` + `Input::Register::*` + `Payload::Register::*`
+   following the pattern of `Mutation::Page::*`.
+3. Expose `Builder::Register` from `GraphQL#register` (distinct from `#registers`
+   which is the compat search layer).
+
+Until then, register mutation callers must instantiate `Mutation::Register::*` directly
+(none exist yet), or use `Compat::Registers` for search.
+
+## Conventions
+
+- One builder per domain entity. Sub-builders (e.g. `LocationStructure::Draft`) are
+  nested under their parent builder's folder and exposed via a method on the parent.
+- Builder methods are snake_case public API; private helper methods are camelCase
+  (matching the existing convention: `updateMutation`, `archiveMutation`, etc.).
+- Builders never hold state — each method instantiates a fresh mutation/query object.
+- Builders do not implement pagination; callers use `QueryConnection#each` for that.
+
+## Related
+
+- `../mutation/` — concrete mutation classes that builders delegate to
+- `../query/` — concrete query classes (some builders also expose query shortcuts)
+- `../compat/` — v2-compatible layer (`Compat::Pages`, `Compat::Registers`) that
+  wraps builders + queries with an eco-helpers-compatible interface

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

@@ -0,0 +1,73 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Builder
+        class Kickstand
+          attr_reader :client
+
+          def initialize(client)
+            @client = client
+          end
+
+          def start(id:, &block)
+            startMutation.query(id: id, &block)
+          end
+
+          def stop(id:, &block)
+            stopMutation.query(id: id, &block)
+          end
+
+          def fail(id:, &block)
+            failMutation.query(id: id, &block)
+          end
+
+          def bulk_update(ids:, start: false, stop: false, failure: false, &block)
+            bulkUpdateMutation.query(ids: ids, start: start, stop: stop, failure: failure, &block)
+          end
+
+          def start_job(id:, &block)
+            startJobMutation.query(id: id, &block)
+          end
+
+          def fail_job(id:, &block)
+            failJobMutation.query(id: id, &block)
+          end
+
+          def bulk_update_jobs(ids:, start: false, failure: false, &block)
+            bulkUpdateJobsMutation.query(ids: ids, start: start, failure: failure, &block)
+          end
+
+          private
+
+          def startMutation
+            Mutation::Kickstand::StartWorkflow.new(client)
+          end
+
+          def stopMutation
+            Mutation::Kickstand::StopWorkflow.new(client)
+          end
+
+          def failMutation
+            Mutation::Kickstand::FailWorkflow.new(client)
+          end
+
+          def bulkUpdateMutation
+            Mutation::Kickstand::BulkUpdateWorkflows.new(client)
+          end
+
+          def startJobMutation
+            Mutation::Kickstand::StartJob.new(client)
+          end
+
+          def failJobMutation
+            Mutation::Kickstand::FailJob.new(client)
+          end
+
+          def bulkUpdateJobsMutation
+            Mutation::Kickstand::BulkUpdateJobs.new(client)
+          end
+        end
+      end
+    end
+  end
+end

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

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

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

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.rb

@@ -7,6 +7,10 @@ module Ecoportal
   end
 end
 
-require 'ecoportal/api/graphql/builder/location_structure'
-require 'ecoportal/api/graphql/builder/action'
-require 'ecoportal/api/graphql/builder/contractor_entity'
+require_relative 'builder/location_structure'
+require_relative 'builder/action'
+require_relative 'builder/contractor_entity'
+require_relative 'builder/register'
+require_relative 'builder/page'
+require_relative 'builder/kickstand'
+require_relative 'builder/template'