ecoportal-api-graphql 1.3.5 → 1.3.16

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

@@ -1,24 +1,37 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Base
-      end
-    end
-  end
-end
-
-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/organization'
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+      end
+    end
+  end
+end
+
+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'
+
+require_relative 'base/template'

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

@@ -1,41 +1,41 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Builder
-        class ContractorEntity
-          attr_reader :client
-
-          def initialize(client)
-            @client = client
-          end
-
-          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
-
-          private
-
-          def createMutation
-            Mutation::ContractorEntity::Create.new(client)
-          end
-
-          def updateMutation
-            Mutation::ContractorEntity::Update.new(client)
-          end
-
-          def destroyMutation
-            Mutation::ContractorEntity::Destroy.new(client)
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Builder
+        class ContractorEntity
+          attr_reader :client
+
+          def initialize(client)
+            @client = client
+          end
+
+          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
+
+          private
+
+          def createMutation
+            Mutation::ContractorEntity::Create.new(client)
+          end
+
+          def updateMutation
+            Mutation::ContractorEntity::Update.new(client)
+          end
+
+          def destroyMutation
+            Mutation::ContractorEntity::Destroy.new(client)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -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,4 +1,4 @@
-module Ecoportal
+module Ecoportal
   module API
     class GraphQL
       module Builder
@@ -9,33 +9,41 @@ module Ecoportal
             @client = client
           end
 
-          # def archive(**kargs, &block)
-          #   archiveMutation.query(**kargs, &block)
-          # end
+          # Register CRUD
+          def create(**kargs, &block)
+            createMutation.query(**kargs, &block)
+          end
 
-          # def update(**kargs, &block)
-          #   updateMutation.query(**kargs, &block)
-          # end
+          def update(**kargs, &block)
+            updateMutation.query(**kargs, &block)
+          end
 
-          # def create(**kargs, &block)
-          #   createMutation.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 archiveMutation
-          #   Mutation::Register::Archive.new(client)
-          # end
+          def createMutation
+            Mutation::Register::Create.new(client)
+          end
 
-          # def updateMutation
-          #   Mutation::Register::Update.new(client)
-          # end
+          def updateMutation
+            Mutation::Register::Update.new(client)
+          end
 
-          # def createMutation
-          #   Mutation::Register::Create.new(client)
-          # end
+          def destroyMutation
+            Mutation::Register::Destroy.new(client)
+          end
         end
       end
     end
   end
 end
+
+require_relative 'register/preset_view'