ecoportal-api-graphql 1.3.5 → 1.3.16

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

@@ -1,54 +1,54 @@
-module Ecoportal
-  module API
-    module Common
-      module GraphQL
-        class Model
-          module Diffable
-            require_relative 'diffable/hash_diff_nesting'
-            require_relative 'diffable/classic_diff_service'
-            require_relative 'diffable/diff_service'
-
-            DIFF_CLASS = DiffService
-
-            # INSTANCE METHODS
-
-            # @note **cascaded callbacks**
-            #   1. Can **skip** rooted objects (where `root?` is `true`).
-            #     This is because nested rooted objects are usually look-ups
-            #     (not really part of the target model).
-            #   2. Allow to redefine `as_update` on each model.
-            # @param flat [Boolean] whether it should NOT perform a cascaded callback
-            #   througout all the instance objects of the model hierarchy (nested).
-            # @param ignored [Array<String>] the keys that should be ignored, not part
-            #   of the result of `as_update`
-            # @return [nil, Hash] the patch `Hash` model including only
-            #   the changes between `original_doc` and `doc`.
-            def as_update(**kargs)
-              diff_class.new(
-                self,
-                **kargs
-              ).diff
-            end
-
-            # @note `cascaded` will be more accurate in a `GraphQL` scenario.
-            # @return [Boolean] stating if there are changes.
-            def dirty?(...)
-              au = as_update(...)
-
-              return false if au.nil?
-              return false if au == {}
-
-              true
-            end
-
-            private
-
-            def diff_class
-              self.class::DIFF_CLASS
-            end
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    module Common
+      module GraphQL
+        class Model
+          module Diffable
+            require_relative 'diffable/hash_diff_nesting'
+            require_relative 'diffable/classic_diff_service'
+            require_relative 'diffable/diff_service'
+
+            DIFF_CLASS = DiffService
+
+            # INSTANCE METHODS
+
+            # @note **cascaded callbacks**
+            #   1. Can **skip** rooted objects (where `root?` is `true`).
+            #     This is because nested rooted objects are usually look-ups
+            #     (not really part of the target model).
+            #   2. Allow to redefine `as_update` on each model.
+            # @param flat [Boolean] whether it should NOT perform a cascaded callback
+            #   througout all the instance objects of the model hierarchy (nested).
+            # @param ignored [Array<String>] the keys that should be ignored, not part
+            #   of the result of `as_update`
+            # @return [nil, Hash] the patch `Hash` model including only
+            #   the changes between `original_doc` and `doc`.
+            def as_update(**kargs)
+              diff_class.new(
+                self,
+                **kargs
+              ).diff
+            end
+
+            # @note `cascaded` will be more accurate in a `GraphQL` scenario.
+            # @return [Boolean] stating if there are changes.
+            def dirty?(...)
+              au = as_update(...)
+
+              return false if au.nil?
+              return false if au == {}
+
+              true
+            end
+
+            private
+
+            def diff_class
+              self.class::DIFF_CLASS
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,43 +1,43 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Base
-        class Action < Logic::BaseModel
-          root!
-
-          passkey :id
-          passthrough :altId
-          passthrough :name, :description
-          passthrough :age
-
-          passarray :locationIds
-
-          passthrough :status, :relativeStatus
-          passboolean :archived, :attached, :standaloneAction
-          passthrough :actionCategoryId
-
-          passarray :fileContainerIds
-
-          passarray :assignedPersonMemberIds
-          passthrough :creatorId, :creatorUserId
-          passthrough :updaterId, :updaterUserId
-          passthrough :completerId
-
-          passthrough :timeZone
-          embeds_one :dueDate, klass: Base::DateTime
-          embeds_one :reminderDate, klass: Base::DateTime
-          embeds_one :createdAt, klass: Base::DateTime
-          embeds_one :updatedAt, klass: Base::DateTime
-          embeds_one :completedAt, klass: Base::DateTime
-          embeds_one :openededAt, klass: Base::DateTime
-          embeds_one :closedAt, klass: Base::DateTime
-          embeds_one :dueOrClosedDate, klass: Base::DateTime
-
-          passboolean :completed
-          passthrough :closeDetail
-          #passthrough :dueIn # only for templates
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        class Action < Logic::BaseModel
+          root!
+
+          passkey :id
+          passthrough :altId
+          passthrough :name, :description
+          passthrough :age
+
+          passarray :locationIds
+
+          passthrough :status, :relativeStatus
+          passboolean :archived, :attached, :standaloneAction
+          passthrough :actionCategoryId
+
+          passarray :fileContainerIds
+
+          passarray :assignedPersonMemberIds
+          passthrough :creatorId, :creatorUserId
+          passthrough :updaterId, :updaterUserId
+          passthrough :completerId
+
+          passthrough :timeZone
+          embeds_one :dueDate, klass: Base::DateTime
+          embeds_one :reminderDate, klass: Base::DateTime
+          embeds_one :createdAt, klass: Base::DateTime
+          embeds_one :updatedAt, klass: Base::DateTime
+          embeds_one :completedAt, klass: Base::DateTime
+          embeds_one :openededAt, klass: Base::DateTime
+          embeds_one :closedAt, klass: Base::DateTime
+          embeds_one :dueOrClosedDate, klass: Base::DateTime
+
+          passboolean :completed
+          passthrough :closeDetail
+          #passthrough :dueIn # only for templates
+        end
+      end
+    end
+  end
+end

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

@@ -1,67 +1,67 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Base
-        class ContractorEntity
-          module MemberChanges
-            def associate(*values, lead: false)
-              ids = to_person_ids(*values)
-
-              associatedPeopleIds.tap do |associated|
-                associated.push!(*ids)
-                next unless lead
-
-                lead!(*ids)
-              end
-            end
-
-            def dissassociate(*values)
-              ids = to_person_ids(*values)
-
-              associatedPeopleIds.tap do |associated|
-                unlead!(*ids)
-                associated.delete!(*ids)
-              end
-            end
-
-            def lead!(*values)
-              ids = to_person_ids(*values)
-
-              leadContractorIds.tap do |leads|
-                associate(*ids)
-                leads.push!(*ids)
-              end
-            end
-
-            def unlead!(*values)
-              ids = to_person_ids(*values)
-
-              leadContractorIds.tap do |leads|
-                leads.delete!(*ids)
-              end
-            end
-
-            private
-
-            def to_person_ids(*values)
-              to_person_id(values.flatten)
-            end
-
-            def to_person_id(value)
-              case value
-              when String
-                value
-              when Ecoportal::API::V1::Person
-                value.id
-              when Hash
-                to_person_id(['id'])
-              when Enumarable
-                value.map {|val| to_person_id(val)}.compact
-              end
-            end
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        class ContractorEntity
+          module MemberChanges
+            def associate(*values, lead: false)
+              ids = to_person_ids(*values)
+
+              associatedPeopleIds.tap do |associated|
+                associated.push!(*ids)
+                next unless lead
+
+                lead!(*ids)
+              end
+            end
+
+            def dissassociate(*values)
+              ids = to_person_ids(*values)
+
+              associatedPeopleIds.tap do |associated|
+                unlead!(*ids)
+                associated.delete!(*ids)
+              end
+            end
+
+            def lead!(*values)
+              ids = to_person_ids(*values)
+
+              leadContractorIds.tap do |leads|
+                associate(*ids)
+                leads.push!(*ids)
+              end
+            end
+
+            def unlead!(*values)
+              ids = to_person_ids(*values)
+
+              leadContractorIds.tap do |leads|
+                leads.delete!(*ids)
+              end
+            end
+
+            private
+
+            def to_person_ids(*values)
+              to_person_id(values.flatten)
+            end
+
+            def to_person_id(value)
+              case value
+              when String
+                value
+              when Ecoportal::API::V1::Person
+                value.id
+              when Hash
+                to_person_id(['id'])
+              when Enumarable
+                value.map {|val| to_person_id(val)}.compact
+              end
+            end
+          end
+        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/file_container.rb

@@ -1,14 +1,14 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Base
-        class FileContainer < Logic::BaseModel
-          passkey :id
-          passthrough :name, :activeName
-          passthrough :fileSize, :token, :activeVersionId
-          passarray :tags
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        class FileContainer < Logic::BaseModel
+          passkey :id
+          passthrough :name, :activeName
+          passthrough :fileSize, :token, :activeVersionId
+          passarray :tags
+        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