ecoportal-api-graphql 1.3.4 → 1.3.9

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

@@ -7,8 +7,8 @@ module Ecoportal
   end
 end
 
-require 'ecoportal/api/common/graphql/http_client'
 require 'ecoportal/api/common/graphql/auth_service'
+require 'ecoportal/api/common/graphql/http_client'
 require 'ecoportal/api/common/graphql/client'
 require 'ecoportal/api/common/graphql/class_helpers'
 require 'ecoportal/api/common/graphql/hash_helpers'

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

@@ -0,0 +1,37 @@
+# graphql (gem root)
+
+The entry point for the gem: `Ecoportal::API::GraphQL` is the top-level class consumers instantiate; it holds the `client`, wires the `HttpClient`, and exposes builder/compat entry points.
+
+## Contents
+
+| File / class | Purpose |
+|---|---|
+| `graphql.rb` / `GraphQL` | Main entry class — `initialize` builds `Client` + `HttpClient`, exposes `pages`, `registers`, `page`, `action`, `contractorEntity`, `locationStructure`, `currentOrganization` |
+| `graphql_version.rb` | Gem `VERSION` constant |
+| `base/` | Data-only model base classes (no resolvers, no `client`); see `base/CLAUDE.md` |
+| `builder/` | Facade builders that group related mutations under one object |
+| `compat/` | v2-compatible API layer for eco-helpers scripts |
+| `concerns/` | Shared Ruby mixins (`PageCompat`, `DataFieldAccess`, `SnakeCamelAccess`, `FragmentDefinitions`) |
+| `connection/` | `Logic::Connection` subclasses — typed pagination wrappers per entity |
+| `error/` | Domain error classes (`ValidationErrors`, `LocationsError`, `LocationsValidationError`) |
+| `fragment/` | GraphQL fragment heredoc strings + `Fragment.assemble(*syms)` |
+| `helpers/` | Utility modules (`LocationsTree`) |
+| `input/` | Mutation input serialisers; `SearchConf` is a chainable value object |
+| `interface/` | Abstract base models shared by `Base::` and `Model::` (e.g. `BasePage`, `LocationStructure`) |
+| `logic/` | Abstract base classes for queries, mutations, connections — no domain code |
+| `model/` | Concrete domain models with `class_resolver` wiring; subclass their `Base::` counterparts |
+| `mutation/` | Concrete mutation execution classes |
+| `payload/` | Mutation response payload wrappers |
+| `query/` | Concrete query execution classes |
+
+## Conventions
+
+- Load order in `graphql.rb` matters: `logic/base_model` → `error` → `interface` → `base` → `model` → rest.
+- `#pages` returns `Compat::Pages` (v2-compatible); `#page` returns `Builder::Page` (raw mutation facade).
+- `#currentOrganization` returns `Model::Organization` class (not instance) with `client` set — query methods are class-level.
+- `GraphQL` (not `GraphQL`) is the namespace: use `Ecoportal::API::Graphql` alias only for legacy references; internal code uses `GraphQL`.
+
+## Related
+
+- `../../common/graphql/` — HTTP client, auth, and base model infrastructure
+- Downstream: `eco-helpers` calls `.pages` and `.registers` exclusively via `Compat::*`

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

@@ -0,0 +1,50 @@
+# base
+
+Data-only model base classes — these declare fields and structure but hold no `client`, no query resolvers, and no business logic.
+
+## Contents
+
+| File / class | Purpose |
+|---|---|
+| `action.rb` / `Base::Action` | Action fields (id, name, status, dates, assignee IDs); declared `root!` so excluded from cascaded diffs |
+| `action_category.rb` / `Base::ActionCategory` | Action category fields |
+| `contractor_entity.rb` / `Base::ContractorEntity` | Contractor entity fields |
+| `contractor_entity/member_changes.rb` | Nested member-changes sub-model |
+| `date_time.rb` / `Base::DateTime` | Wraps `{ dateTime:, timeZone: }` response objects |
+| `delta_result.rb` / `Base::DeltaResult` | `pageDelta` result item: `id` + `delta` enum (UPDATED/NOT_FOUND/NEW) |
+| `field.rb` / `Base::Field` | Generic field model |
+| `file_attachment.rb` / `Base::FileAttachment` | File attachment metadata |
+| `file_container.rb` / `Base::FileContainer` | File container wrapper |
+| `location_classification_type.rb` | Classification type (name) |
+| `location_node.rb` / `Base::LocationNode` | Location node with ancestors and classifications |
+| `location_structure.rb` / `Base::LocationStructure` | Location structure tree model |
+| `location_structure/draft.rb` | Draft structure model |
+| `location_structure/draft/structure.rb` | Nested draft structure detail |
+| `organization.rb` / `Base::Organization` | Thin organization base (id, name) |
+| `page.rb` | Namespace module; requires `basic`, `data_field`, `section`, `section_collection`, `phased` |
+| `page/basic.rb` / `Base::Page::Basic` | BasicPage — inherits `Interface::BasePage`; no extra fields |
+| `page/phased.rb` / `Base::Page::Phased` | PhasedPage — inherits `Interface::BasePage`; `embeds_many :stages` |
+| `page/phased/stage.rb` / `Base::Page::Phased::Stage` | Single stage: id, name, ordering, state, sections, components |
+| `page/section.rb` / `Base::Page::Section` | Section wrapper (ContentSection or SplitSection); merges left/right dataFields into `components` |
+| `page/section_collection.rb` / `Base::Page::SectionCollection` | Enumerable wrapper over sections; provides `get_by_type`, `get_by_heading`, `components` |
+| `page/data_field.rb` / `Base::Page::DataField` | Base data field class; `TYPE_MAP` dispatches `from_doc` to typed subclasses |
+| `page/data_field/` | 10 typed subclasses (PlainText, RichText, DateField, Number, Gauge, People, Select, Checklist, TagField, Geo) + `Collection` |
+| `page_info.rb` / `Base::PageInfo` | Cursor pagination info (endCursor, hasNextPage) |
+| `person_member.rb` / `Base::PersonMember` | Person member (name, email, id) |
+| `preview_page.rb` / `Base::PreviewPage` | Lightweight page preview (no field data) |
+| `resource.rb` / `Base::Resource` | Resource model (inherits `Logic::BaseModel` directly) |
+| `pages_workflow.rb` / `Base::PagesWorkflow` | PagesWorkflow top-level model: `autoPageCreationEnabled`, `fields` (RegisterField), `stages`; sub-files under `pages_workflow/` cover RegisterField, CallbackType, OperationInterface, TriggerInterface, and supporting types |
+
+## Conventions
+
+- `Base::` classes are data-only: `passkey`, `passthrough`, `passboolean`, `passarray`, `embeds_one`, `embeds_many` only — no business methods, no resolvers.
+- `Model::` subclasses in `../model/` add `class_resolver` wiring and may add behaviour (e.g. `Model::Page::Phased#stages` wraps the array in `Compat::StageCollection`).
+- `Interface::BasePage` is the shared parent of both `Basic` and `Phased`; field declarations that apply to both page types live there.
+- `Base::Action` declares `root!` — this marks it as an independent server entity, excluded from cascaded `as_update` diffs.
+- When adding a new field to a page type, add it to `Interface::BasePage` if it applies to both, or to the appropriate `Base::Page::*` class.
+
+## Related
+
+- `../interface/base_page.rb` — common parent for Basic + Phased page base classes
+- `../model/` — concrete models that subclass these bases
+- `../model/page_union.rb` — factory that dispatches `__typename` to `Model::Page::Basic` or `Model::Page::Phased`

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

@@ -0,0 +1,17 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        # Represents one generation version of an AiSummary field.
+        # Returned by generateAiSummary — tracks the prompt, output, token usage, and status.
+        class AiSummaryVersion < Logic::BaseModel
+          passkey :id
+          passthrough :aiSummary, :status, :prompt
+          passthrough :inputTokens, :outputTokens, :totalTokens
+          passthrough :resourceType # "field" | "stage" | "page"
+          passarray :ratings        # [[user_id, score], ...]
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,16 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        # Result of a pageDelta query for a single page ID.
+        # delta: 'UPDATED' | 'NOT_FOUND' | 'NEW'
+        class DeltaResult < Logic::BaseModel
+          read_only!
+
+          passkey :id
+          passthrough :delta
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,19 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        class Force
+          # A single force binding — links a Force to a data field or section by referenceId.
+          class Binding < Logic::BaseModel
+            passkey     :id
+            passthrough :name, :referenceId
+
+            def reference_id
+              referenceId
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,62 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        class Force
+          # Wraps the bindings array of a Force.  Supports the v2 scripting interface:
+          #   force.bindings.get_by_name(name)   → [Binding, ...]
+          #   force.bindings.add(field, name:)   → queues addBinding command
+          #   force.bindings.delete!(binding)    → queues removeBinding command
+          class BindingCollection
+            include Enumerable
+
+            def initialize(raw, force:)
+              @force    = force
+              @bindings = Array(raw).map { |b| Force::Binding.new(b) }
+            end
+
+            # Filter bindings by name (case-insensitive).
+            def get_by_name(name)
+              target = name.to_s.downcase
+              @bindings.select { |b| b.name.to_s.downcase == target }
+            end
+
+            # Queue an addBinding command.  `field` may be a GraphQL DataField object
+            # (uses field.id as referenceId) or a raw ID string.
+            def add(field, name:, type: 'field')
+              ref_id = field.respond_to?(:id) ? field.id : field.to_s
+              @force.queue_command(
+                addBinding: {
+                  forceId:     @force.id,
+                  name:        name.to_s,
+                  referenceId: ref_id,
+                  type:        type
+                }
+              )
+              self
+            end
+
+            # Queue a removeBinding command.  Accepts a Binding object or an ID string.
+            def delete!(binding_or_id)
+              bid = binding_or_id.respond_to?(:id) ? binding_or_id.id : binding_or_id.to_s
+              @force.queue_command(removeBinding: { id: bid })
+              self
+            end
+
+            def each(&block)
+              @bindings.each(&block)
+            end
+
+            def size
+              @bindings.size
+            end
+
+            def empty?
+              @bindings.empty?
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,47 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        class Force
+          # Wraps a page's forces array.  Provides the v2 scripting interface:
+          #   page.forces.get_by_name(name)  → [Force, ...]
+          class Collection
+            include Enumerable
+
+            def initialize(raw)
+              @forces = Array(raw).map { |f| Force.new(f) }
+            end
+
+            # Filter forces by name (case-insensitive).
+            def get_by_name(name)
+              target = name.to_s.downcase
+              @forces.select { |f| f.name.to_s.downcase == target }
+            end
+
+            # True if any force has uncommitted script changes or pending binding commands.
+            def dirty?
+              @forces.any?(&:dirty?)
+            end
+
+            # All pending commands across all forces (editForce, addBinding, removeBinding).
+            def pending_commands
+              @forces.flat_map(&:all_pending_commands)
+            end
+
+            def each(&block)
+              @forces.each(&block)
+            end
+
+            def size
+              @forces.size
+            end
+
+            def empty?
+              @forces.empty?
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,65 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        # Represents a Force — a AngularJS/LISP snippet that implements conditional
+        # field behaviour on a page stage.  Forces are queried as part of a page
+        # when forces are explicitly included in the query fragment.
+        #
+        # Read access is via the page's force collection:
+        #   force = page.forces.get_by_name('Workflow (S1)').first
+        #   force.custom_script          # → current LISP script
+        #   force.bindings.get_by_name('top-txt')  # → [Binding, ...]
+        #
+        # Write access queues workflow commands executed after process_ooze:
+        #   force.custom_script = new_script  # → queues editForce command
+        #   force.bindings.add(field, name: 'bind-name')   # → queues addBinding
+        #   force.bindings.delete!(binding)                 # → queues removeBinding
+        class Force < Logic::BaseModel
+          passkey     :id
+          passthrough :name, :script, :customScript, :weight, :url
+          passarray   :globalBindingIds
+
+          require_relative 'force/binding'
+          require_relative 'force/binding_collection'
+          require_relative 'force/collection'
+
+          def bindings
+            @bindings ||= Force::BindingCollection.new(doc['bindings'] || [], force: self)
+          end
+
+          # v2 compat: scripts read and write custom_script directly.
+          # Writing queues an editForce workflow command consumed by ForceCompat.
+          def custom_script=(new_script)
+            return if doc['customScript'] == new_script
+
+            doc['customScript'] = new_script
+            @_custom_script_dirty = true
+          end
+
+          def dirty?
+            @_custom_script_dirty || pending_commands.any?
+          end
+
+          # Accumulate workflow commands (editForce, addBinding, removeBinding).
+          def queue_command(command_hash)
+            pending_commands << command_hash
+          end
+
+          # All pending commands for this force (editForce if script changed + binding ops).
+          def pending_commands
+            @pending_commands ||= []
+          end
+
+          # Collect all commands including the script edit if dirty.
+          def all_pending_commands
+            cmds = []
+            cmds << { editForce: { id: id, customScript: doc['customScript'] } } if @_custom_script_dirty
+            cmds.concat(pending_commands)
+            cmds
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,17 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        module Kickstand
+          class Job < Logic::BaseModel
+            SCHEMA_VERSION = '20260605'.freeze
+
+            passkey :id
+            passthrough :status
+            passthrough :createdAt, :updatedAt
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,18 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        module Kickstand
+          class Workflow < Logic::BaseModel
+            SCHEMA_VERSION = '20260605'.freeze
+
+            passkey :id
+            passthrough :name, :status
+            passthrough :createdAt, :updatedAt
+            passthrough :startedAt, :stoppedAt, :failedAt, :finishedAt
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,13 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        module Kickstand
+        end
+      end
+    end
+  end
+end
+
+require_relative 'kickstand/workflow'
+require_relative 'kickstand/job'

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

@@ -0,0 +1,38 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        module Page
+          class Basic < Interface::BasePage
+            private
+
+            # v2-compat read flatten: a basic page's fields live nested under
+            # sections (CommonPageUnion fetches `sections { ...sectionUnion }` with the
+            # data fields inside each section — it does NOT select a top-level
+            # `dataFields`). v2 exposed fields flat at the page (page.components), so
+            # gather them from sections here, mirroring Model::Page::Phased#raw_data_fields.
+            # Field docs are shared by reference, so mutations forward to the section doc.
+            #
+            # `raw_sections` keeps the DataFieldAccess default (doc['sections']) — basic
+            # pages already store sections at the page root.
+            def raw_data_fields
+              from_sections = raw_sections.flat_map { |section| field_docs_in(section) }.compact.uniq { |fld| fld['id'] }
+              return from_sections unless from_sections.empty?
+
+              # Create/flat path: fields may be supplied at the page root (top-level
+              # `dataFields`, no sections) — fall back to the DataFieldAccess default
+              # so create input + flat-built basic pages still expose their fields.
+              doc['dataFields'] || []
+            end
+
+            def field_docs_in(section)
+              (section['dataFields'] || []) +
+                (section['leftDataFields'] || []) +
+                (section['rightDataFields'] || [])
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/page/data_field/actions_list.rb

@@ -0,0 +1,9 @@
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    # Actions list field — embedded action items linked to this page.
+    # Actions are managed through Mutation::Action::*; not via DataFieldInput.
+    class ActionsList < DataField
+      passarray :actions # each: { id:, name:, status: }
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/page/data_field/ai_summary.rb

@@ -0,0 +1,18 @@
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    # AI-generated summary field.
+    # Content is generated server-side via generateAiSummary mutation (Bedrock Claude).
+    # Not settable via DataFieldInput — use the dedicated mutation instead.
+    #
+    # instructions: the AI prompt configured on this field in the template.
+    # trigger: "submitted" | "approved" — when generation fires.
+    # trigger_stage_ids: stages that trigger generation (empty = all stages).
+    # text_format: "simple_text" | "bullet_points" | "numbered_list" | "headings"
+    class AiSummary < DataField
+      passthrough :aiSummary, :generatedAt, :instructions
+      passthrough :trigger, :textFormat
+      passarray   :triggerStageIds, :fieldConfigurations
+      passboolean :alreadyRated
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/page/data_field/checklist.rb

@@ -0,0 +1,29 @@
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    class Checklist < DataField
+      passarray :items # each: { id:, label:, checked: }
+      passthrough :complete
+
+      # Check/uncheck an item by label or id.
+      def check(label_or_id, checked: true)
+        item = (doc['items'] || []).find { |i| i['label'] == label_or_id.to_s || i['id'] == label_or_id.to_s }
+        return unless item
+
+        item['checked'] = checked
+      end
+
+      def as_input
+        return nil unless dirty?
+
+        {
+          checklist: {
+            id:    id,
+            # rubocop:disable Style/DoubleNegation
+            items: (doc['items'] || []).map { |i| { id: i['id'], checked: !!i['checked'] } }
+            # rubocop:enable Style/DoubleNegation
+          }
+        }
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/page/data_field/collection.rb

@@ -0,0 +1,112 @@
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    # Wraps an array of raw data field docs as typed DataField objects.
+    # Provides v2-compatible access patterns used in eco-helpers scripts:
+    #   components.get_by_type(:plain_text)     — filter by field type
+    #   components.get_by_name('FieldLabel')    — find by label
+    #   components.doc                          — raw doc array
+    #   components.dirty_inputs                 — changed field hashes for mutation
+    class Collection
+      include Enumerable
+
+      # Accepts raw field docs (→ built via from_doc) OR already-built DataField objects
+      # (kept as-is). Preserving existing objects lets a phased page's Stage#components share
+      # the SAME field objects as the page's canonical field_collection (so stage-level
+      # mutations land in the page's data_fields_updates — phased write-path identity).
+      def initialize(fields)
+        @fields = Array(fields).map { |f| f.is_a?(DataField) ? f : DataField.from_doc(f) }
+      end
+
+      # Build from a raw docs array.
+      def self.from_doc(raw_array)
+        new(Array(raw_array))
+      end
+
+      # Filter by field type. Accepts symbol (:plain_text), string ('PlainText'), or
+      # the GraphQL __typename directly. Matching is case-insensitive.
+      def get_by_type(type_key)
+        target = normalise_type(type_key)
+        @fields.select { |f| normalise_type(f.type) == target }
+      end
+
+      # Find first field matching label (case-insensitive). Optional type: restricts to
+      # that field type first (v2 compat: components.get_by_name(name, type:) — used by
+      # the farmers cutover use case which calls it directly, not via OozeRedirect).
+      def get_by_name(label, type: nil)
+        pool = type ? get_by_type(type) : @fields
+        pool.find { |f| f.label.to_s.downcase == label.to_s.downcase }
+      end
+
+      # Raw doc array (v2 compat — scripts iterate secs_doc / flds_doc).
+      def doc
+        @fields.map(&:doc)
+      end
+
+      # Add a new field to this collection (v2 compat: components.add).
+      # The field must reference an existing server-side ID (from buildFromTemplate).
+      # Yields the new field object to the block for configuration.
+      # Returns the field object.
+      #
+      # Usage:
+      #   components.add(doc: raw_doc) { |f| f.value = 'X' }
+      #   components.add(id: 'f1', label: 'Name', type: 'PlainText') { |f| f.value = 'X' }
+      def add(doc: nil, id: nil, label: nil, type: nil, **opts)
+        raw = doc || opts.merge('id' => id, 'label' => label, '__typename' => type.to_s).compact
+        field = DataField.from_doc(raw)
+        @additions ||= []
+        @additions << field
+        yield field if block_given?
+        field
+      end
+
+      # Mark a field for deletion by field ID or field object.
+      # The field ID is sent in dataFields.deletions on the next update.
+      def mark_for_deletion(id_or_field)
+        field_id = id_or_field.respond_to?(:id) ? id_or_field.id : id_or_field.to_s
+        @deletions ||= []
+        @deletions |= [field_id]
+      end
+
+      # Returns DataFieldInput hashes for fields modified via value setters.
+      def dirty_inputs
+        @fields.filter_map(&:as_input)
+      end
+
+      # Returns DataFieldInput hashes for fields added via #add.
+      def dirty_additions
+        (@additions || []).filter_map(&:as_input)
+      end
+
+      # Returns field IDs queued for deletion via #mark_for_deletion.
+      def dirty_deletions
+        @deletions || []
+      end
+
+      def dirty?
+        @fields.any?(&:dirty?) ||
+          (@additions || []).any?(&:dirty?) ||
+          !dirty_deletions.empty?
+      end
+
+      def each(&block)
+        @fields.each(&block)
+      end
+
+      def empty?
+        @fields.empty?
+      end
+
+      def length
+        @fields.length
+      end
+
+      private
+
+      # Normalise type key to lowercase no-underscore string for comparison.
+      # :plain_text → 'plaintext', 'PlainText' → 'plaintext'
+      def normalise_type(type_key)
+        type_key.to_s.downcase.delete('_') if type_key
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/base/page/data_field/contractor_entities.rb

@@ -0,0 +1,28 @@
+module Ecoportal::API::GraphQL::Base::Page
+  class DataField
+    # Contractor entity selector field.
+    # Stores references to ContractorEntity records.
+    class ContractorEntities < DataField
+      passarray :contractors # each: { id:, name: }
+
+      def contractor_entity_ids
+        Array(contractors).map { |c| c.is_a?(Hash) ? c['id'] : c }.compact
+      end
+
+      def contractor_entity_ids=(ids)
+        doc['contractors'] = Array(ids).map { |id_val| { 'id' => id_val } }
+      end
+
+      # v2 compat alias
+      def value=(ids)
+        self.contractor_entity_ids = ids
+      end
+
+      def as_input
+        return nil unless dirty?
+
+        { contractorEntities: { id: id, contractorEntityIds: contractor_entity_ids } }
+      end
+    end
+  end
+end