ecoportal-api-graphql 1.3.5 → 1.3.9

data/ecoportal-api-graphql.gemspec

@@ -1,40 +1,40 @@
-# rubocop:disable Gemspec/DevelopmentDependencies
-lib = File.expand_path('lib', __dir__)
-$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'ecoportal/api/graphql_version'
-
-Gem::Specification.new do |spec|
-  spec.name          = 'ecoportal-api-graphql'
-  spec.version       = Ecoportal::API::GRAPQL_VERSION
-  spec.authors       = ['Oscar Segura']
-  spec.email         = ['oscar@ecoportal.co.nz']
-
-  spec.summary       = 'A collection of helpers for interacting with the ecoPortal GraphQL API'
-  spec.homepage      = 'https://www.ecoportal.com'
-  spec.licenses      = %w[MIT]
-
-  spec.metadata['rubygems_mfa_required'] = 'true'
-
-  spec.required_ruby_version = '>= 3.2.2'
-
-  spec.files = `git ls-files -z`.split("\x0").reject do |f|
-    f.match(%r{^(test|spec|features)/})
-  end
-  spec.bindir        = 'exe'
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
-  spec.require_paths = ['lib']
-
-  spec.add_development_dependency 'pry',          '>= 0.14'
-  spec.add_development_dependency 'rake',         '>= 13.0.3', '< 14'
-  spec.add_development_dependency 'redcarpet',    '>= 3.6.0',  '< 4'
-  spec.add_development_dependency 'rspec',        '>= 3.12.0', '< 4'
-  spec.add_development_dependency 'rubocop',      '~> 1'
-  spec.add_development_dependency 'rubocop-rake', '~> 0'
-  spec.add_development_dependency 'yard',         '>= 0.9.34', '< 1'
-
-  spec.add_dependency 'ecoportal-api',    '~> 0.10',  '>= 0.10.15'
-  spec.add_dependency 'ecoportal-api-v2', '~> 3.3',   '>= 3.3.1'
-  spec.add_dependency 'graphlient',       '>= 0.8.0', '< 0.9'
-end
-
-# rubocop:enable Gemspec/DevelopmentDependencies
+# rubocop:disable Gemspec/DevelopmentDependencies
+lib = File.expand_path('lib', __dir__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ecoportal/api/graphql_version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'ecoportal-api-graphql'
+  spec.version       = Ecoportal::API::GRAPQL_VERSION
+  spec.authors       = ['Oscar Segura']
+  spec.email         = ['oscar@ecoportal.co.nz']
+
+  spec.summary       = 'A collection of helpers for interacting with the ecoPortal GraphQL API'
+  spec.homepage      = 'https://www.ecoportal.com'
+  spec.licenses      = %w[MIT]
+
+  spec.metadata['rubygems_mfa_required'] = 'true'
+
+  spec.required_ruby_version = '>= 3.2.2'
+
+  spec.files = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(/^(test|spec|features)\//)
+  end
+  spec.bindir        = 'exe'
+  spec.executables   = spec.files.grep(/^exe\//) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_development_dependency 'pry',          '>= 0.14'
+  spec.add_development_dependency 'rake',         '>= 13.0.3', '< 14'
+  spec.add_development_dependency 'redcarpet',    '>= 3.6.0',  '< 4'
+  spec.add_development_dependency 'rspec',        '>= 3.12.0', '< 4'
+  spec.add_development_dependency 'rubocop',      '~> 1'
+  spec.add_development_dependency 'rubocop-rake', '~> 0'
+  spec.add_development_dependency 'yard',         '>= 0.9.34', '< 1'
+
+  spec.add_dependency 'ecoportal-api',    '~> 0.10',  '>= 0.10.16'
+  spec.add_dependency 'ecoportal-api-v2', '~> 3.3',   '>= 3.3.2'
+  spec.add_dependency 'graphlient',       '>= 0.8.0', '< 0.9'
+end
+
+# rubocop:enable Gemspec/DevelopmentDependencies

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

@@ -0,0 +1,36 @@
+# common/graphql
+
+Shared HTTP transport, authentication, and base model infrastructure used by the gem — nothing here is EcoPortal-domain-specific.
+
+## Contents
+
+| File / class | Purpose |
+|---|---|
+| `auth_service.rb` / `AuthService` | OAuth2 password + refresh-token flow; included in both client classes |
+| `client.rb` / `Client` | Graphlient-based GraphQL client (builds bearer-token headers, constructs endpoint URL) |
+| `http_client.rb` / `HttpClient` | Raw HTTP client (extends `Common::Client`); `execute` sends query strings + variables; supports v0–v3 + graphql API version modes |
+| `class_helpers.rb` / `ClassHelpers` | `becomes(klass)` instance casting + `const?` class helper |
+| `hash_helpers.rb` / `HashHelpers` | Deep key transforms (`keys_to_sym_deep`, `deep_dup`, `remove_nil_keys_deep`) — used by diff and input serialisation |
+| `query_integration.rb` / `QueryIntegration` | Class macro `query(:method, query_klass:)` that wires a named query method on `Model::Organization` |
+| `model.rb` / `Model` | Base model class: `DoubleModel` + `Diffable` + `AsInput`; all GraphQL models ultimately inherit this |
+| `patches.rb` | Reserved placeholder (empty) |
+| `model/diffable.rb` | `as_update` / `dirty?` — delegates to `DiffService` |
+| `model/as_input.rb` | `as_input` (instance) and `as_input(hash)` (class method) — converts diff to GraphQL mutation variables |
+| `model/diffable/diff_service.rb` | Main diff engine: flat classic diff + cascaded reduce through nested `GraphQL::Model` objects |
+| `model/diffable/classic_diff_service.rb` | Low-level change-data extraction (compares `curr_doc` vs `prev_doc`) |
+| `model/diffable/hash_diff.rb` | Hash equality / change detection helpers |
+| `model/diffable/hash_diff_nesting.rb` | Nested key path helpers (`dig_set!`, `dig_delete!`, `dig_path?`) |
+
+## Conventions
+
+- `Client` is graphlient-based and used for schema introspection; `HttpClient` is the actual request sender used in production (set as `client.http_client`).
+- `HashHelpers` is used as both a module mixin (include) and directly via `HashHelpers.keys_to_sym_deep(...)`.
+- `DiffService` handles the `flat:` flag: `flat: true` does a single-level diff; `flat: false` (default) cascades through nested `GraphQL::Model` objects.
+- Root-class objects (`root!` declared) are excluded from cascaded diffs — they represent independent server entities.
+- `AsInput#as_input(target_class:)` delegates to `Input::X.from_model(self)` when a target class is given.
+
+## Related
+
+- `../graphql/logic/base_model.rb` — adds `SnakeCamelAccess` on top of `Common::GraphQL::Model`
+- `../graphql/logic/input.rb` — `Logic::Input` base class built on top of `Model`
+- `../graphql/logic/base_query.rb` — consumes `HttpClient#execute` and `HashHelpers`

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

@@ -6,7 +6,7 @@ module Ecoportal
         class Client < ::Graphlient::Client
           ENDPOINT_PATH = 'external/graphql'.freeze
 
-          attr_accessor :host
+          attr_accessor :host, :http_client
 
           READ_TIMEOUT  = 90
           WRITE_TIMEOUT = 90

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

@@ -2,6 +2,8 @@ module Ecoportal
   module API
     module Common
       module GraphQL
+        class ResponseError < StandardError; end
+
         class HttpClient < Common::Client
           class << self
             def base_url(host)
@@ -13,6 +15,7 @@ module Ecoportal
             end
           end
 
+          ENDPOINT_PATH = 'external/graphql'.freeze
           READ_TIMEOUT  = 90
           WRITE_TIMEOUT = 90
 
@@ -58,8 +61,9 @@ module Ecoportal
               when 'v2', 'v3'
                 HTTP.headers('X-ECOPORTAL-API-KEY' => key_token)
               when 'graphql'
-                HTTP.headers('Authorization' => "Bearer #{key_token}")
+                HTTP.headers('Authorization' => "Bearer #{session_token(host: host)}")
               end.then do |request|
+                request ||= HTTP
                 request.accept(:json).timeout(
                   read:  READ_TIMEOUT,
                   write: WRITE_TIMEOUT
@@ -71,6 +75,20 @@ module Ecoportal
             @org_id || fetch_env_required('ORGANIZATION_ID')
           end
 
+          # Executes a GraphQL query or mutation over HTTP.
+          # @param query_string [String] full GraphQL query document.
+          # @param variables [Hash] variable values to pass to the operation.
+          # @param operation_name [String, nil] when the document has multiple operations.
+          # @return [Hash] parsed response body (string-keyed, includes 'data' and optionally 'errors').
+          # @raise [Ecoportal::API::Common::Client::Error::UnexpectedServerError] on non-2xx HTTP status.
+          # @raise [Ecoportal::API::Common::GraphQL::ResponseError] when the response body contains GraphQL errors.
+          def execute(query_string, variables: {}, operation_name: nil)
+            body = { query: query_string, variables: variables }
+            body[:operationName] = operation_name if operation_name
+            response = base_request.post(url_for(''), json: body)
+            handle_http_response(response)
+          end
+
           # Full URl builder of the request
           # @param path [String] the tail that completes the url of the request.
           # @return [String] the final url.
@@ -91,8 +109,8 @@ module Ecoportal
 
           def api_url
             base_url.then do |url|
-              next "#{url}/api/#{version}"        if v1_0? || v2_3?
-              next "#{url}/api/#{org_id}/graphql" if graphql?
+              next "#{url}/api/#{version}"                 if v1_0? || v2_3?
+              next "#{url}/api/#{org_id}/#{ENDPOINT_PATH}" if graphql?
 
               url
             end
@@ -138,6 +156,20 @@ module Ecoportal
           def graphql?
             @version == 'graphql'
           end
+
+          def handle_http_response(response)
+            unless response.status.success?
+              raise Ecoportal::API::Common::Client::Error::UnexpectedServerError.new(
+                response.body.to_s, code: response.status.code
+              )
+            end
+
+            parsed = response.parse(:json)
+            errors = parsed['errors']
+            raise ResponseError, errors.map { |e| e['message'] }.join('; ') if errors&.any?
+
+            parsed
+          end
         end
       end
     end

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

@@ -0,0 +1,28 @@
+# common/graphql/model
+
+Concerns that add dirty-tracking diff (`Diffable`) and mutation-input serialisation (`AsInput`) to the base `Common::GraphQL::Model`.
+
+## Contents
+
+| File / class | Purpose |
+|---|---|
+| `diffable.rb` / `Model::Diffable` | Provides `as_update` (returns changed-field hash or nil) and `dirty?`; delegates to `DIFF_CLASS` (defaults to `DiffService`) |
+| `as_input.rb` / `Model::AsInput` | Instance `as_input` (wraps diff as mutation variables) + class-level `as_input(hash)` (key-sym + nil-id cleanup) |
+| `diffable/diff_service.rb` / `DiffService` | Primary diff engine: flat classic diff then cascaded reduce over nested `GraphQL::Model` children |
+| `diffable/classic_diff_service.rb` / `ClassicDiffService` | Low-level diff: compares `curr_doc` vs `prev_doc`, returns `{ id:, changed_field: new_value }` or nil |
+| `diffable/hash_diff.rb` / `HashDiff` | Primitive equality helpers used by `ClassicDiffService` |
+| `diffable/hash_diff_nesting.rb` / `HashDiffNesting` | Nested path helpers: `dig_set!`, `dig_delete!`, `dig_path?` used when building cascaded diff results |
+
+## Conventions
+
+- `DIFF_CLASS = DiffService` is a constant on `Diffable` — subclasses can override it to swap diff strategies.
+- `DiffService` `flat: true` produces a single-level diff (current model only); `flat: false` (default) recurses via `cascaded_reduce` through nested `GraphQL::Model` objects.
+- Objects declared with `root!` in their class are skipped during cascaded diff — they are independent server entities (look-ups only).
+- `as_input` on a model calls `as_update` first; returns `nil` when nothing has changed so callers can skip the mutation.
+- `as_input(target_class:)` is the preferred path when a corresponding `Input::X` class exists — delegates to `target_class.from_model(self)`.
+
+## Related
+
+- `../hash_helpers.rb` — `HashHelpers` used inside `DiffService` for key transforms
+- `../../graphql/logic/input.rb` — `Logic::Input.from_model` is the canonical consumer of `as_update`
+- `../../graphql/logic/base_model.rb` — all concrete models inherit this chain

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

@@ -37,11 +37,14 @@ module Ecoportal
 
             # INSTANCE METHODS
 
-            def as_input(clientMutationId: '')
-              self.class.as_input(
-                as_update,
-                clientMutationId: clientMutationId
-              )
+            def as_input(target_class: nil, clientMutationId: '')
+              return target_class.from_model(self, client_mutation_id: clientMutationId) if target_class
+
+              diff = as_update
+              return nil if diff.nil?
+
+              diff[:patchVer] = patchVer if respond_to?(:patchVer) && !patchVer.nil?
+              self.class.as_input(diff, clientMutationId: clientMutationId)
             end
           end
         end

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

@@ -38,10 +38,12 @@ module Ecoportal::API::Common::GraphQL::Model::Diffable
       raise "Can't fetch underlying document for instance of #{target.class}."
     end
 
-    def prev_doc(target = subject, flat: flat?)
+    def prev_doc(target = subject)
       return target.original_doc if target.respond_to?(:original_doc)
 
       raise "Can't fetch original underlying model for instance of #{target.class}."
+    rescue NoMethodError
+      nil
     end
   end
 end

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

@@ -34,12 +34,17 @@ module Ecoportal::API::Common::GraphQL::Model::Diffable
 
     protected
 
+    # Override: GraphQL mutations expect flat changed-prop values, not patch-op wrappers.
+    # Returns { id: ..., changed_field: new_value, ... } or nil when nothing changed.
     def classic_diff(flat: flat?, ignore: [])
-      change_diff(
-        curr_doc(flat: flat),
-        prev_doc(flat: flat),
-        ignore: to_a(ignored, ignore)
-      )
+      curr = keys_to_sym_deep(curr_doc(flat: flat) || {})
+      prev = keys_to_sym_deep(prev_doc(flat: flat) || {})
+
+      data = change_data(curr, prev, ignore: to_a(ignored, ignore))
+      return nil if data == NO_CHANGES
+
+      id = get_id(curr, exception: false)
+      id ? { id: id }.merge(data) : data
     end
 
     # @note it calls `as_update` for nested / cascaded attributes, which in turn
@@ -49,26 +54,28 @@ module Ecoportal::API::Common::GraphQL::Model::Diffable
     #       `#as_update` and `DiffService#diff`.
     #     - The `result` object regards, therefore, to the **current level** alone.
     #       With the aim of building it up (accumulating through the call chain).
-    def diff_reduce(init = {}, ignore: [])
+    def diff_reduce(init, ignore: [])
       subject.cascaded_reduce(init, recurs: false) do |result, obj, _key, key_path, _trace|
-        next result if key_path.empty? # first iteration already done
-        next result if obj == subject  # first call had done it (same as above: path relative)
+        next result if key_path.empty?
+        next result if obj == subject
 
-        dig_delete!(result, key_path) if dig_path?(result, key_path)
+        sym_path = key_path.map(&:to_sym)
 
-        # discard rooted (i.e. read_only) objects from the diff.
+        # Remove any flat-diff placeholder for this key before deciding its fate.
+        dig_delete!(result, sym_path) if result && dig_path?(result, sym_path)
+
+        # Discard root-class objects — they are independent entities, not mutation payload.
         next result if root?(obj)
-        next result unless dig_path?(result, key_path)
-        next result unless obj.respond_to?(:as_update)
+        # Only cascade-diff GraphQL model objects; ecoportal-api-v2 DoubleModel
+        # subclasses (ArrayModel, etc.) have a different as_update signature.
+        next result unless obj.is_a?(Ecoportal::API::Common::GraphQL::Model)
 
         value = obj.as_update(ignore: ignore)
+        next result if value.nil?
 
-        dig_set!(
-          result,
-          key_path,
-          value
-        )
-
+        result      ||= {}
+        result[:id] ||= get_id(keys_to_sym_deep(curr_doc(flat: true) || {}), exception: false)
+        dig_set!(result, sym_path, value)
         result
       end
     end
@@ -147,9 +154,10 @@ module Ecoportal::API::Common::GraphQL::Model::Diffable
     attr_reader :ignored
 
     def root?(obj)
-      return false unless obj.respond_to?(:root?)
-
-      obj.root?
+      # root? is a CLASS method (via Rootable::ClassMethods). The instance root?
+      # is protected and checks parent position, not the class declaration.
+      # Check the ancestor chain for any class that declared root!.
+      obj.class.ancestors.any? { |k| k.respond_to?(:root?) && k.root? }
     end
 
     def curr_doc(target = subject, flat: flat?)
@@ -171,8 +179,8 @@ module Ecoportal::API::Common::GraphQL::Model::Diffable
 
     # Remove from `json` doc all the nested properties.
     def doc_with_non_cascaded_attributes(json)
-      return json unless subject.respond_to?(:_cascaded_doc_keys)
-      return json unless (excluded = subject._cascaded_doc_keys)
+      return json unless subject.class.respond_to?(:_cascaded_doc_keys)
+      return json if (excluded = subject.class._cascaded_doc_keys).empty?
 
       except_keys(json, *excluded)
     end

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

@@ -192,7 +192,7 @@ module Ecoportal::API::Common::GraphQL::Model::Diffable
       end
 
       def any_array?(a, b)
-        [a, b].any? {|item| item.is_a?(Array)}
+        [a, b].any?(Array)
       end
 
       def get_id(doc, exception: true)
@@ -207,6 +207,30 @@ module Ecoportal::API::Common::GraphQL::Model::Diffable
         id
       end
 
+      # @param arr [Array] the source Array of id-bearing items
+      # @return [Array<String>] the `id`s thereof
+      def array_ids(arr)
+        return [] if !arr.is_a?(Array) || arr.empty?
+
+        arr.map {|item| get_id(item, exception: false)}
+      end
+
+      # @param arr [Array] the source Array
+      # @return [Integer, nil] the position of the item with the given `id`
+      def array_id_index(arr, id)
+        return unless arr.is_a?(Array)
+
+        arr.index {|item| get_id(item, exception: false) == id}
+      end
+
+      # @param arr [Array] the source Array
+      # @return [Object, nil] the item with the given `id`
+      def array_id_item(arr, id)
+        return unless (idx = array_id_index(arr, id))
+
+        arr[idx]
+      end
+
       def meta_keys
         return self::META_KEYS if respond_to?(:const_get)
 
@@ -233,6 +257,35 @@ module Ecoportal::API::Common::GraphQL::Model::Diffable
       def to_a(*values)
         [values].flatten.compact.uniq
       end
+
+      # Hash path helpers — used by DiffService#diff_reduce to navigate
+      # and modify nested result hashes during cascaded diffing.
+
+      def dig_path?(obj, keys)
+        return false unless obj.is_a?(Hash)
+        return obj.key?(keys.first) if keys.length == 1
+        return false unless obj.key?(keys.first)
+
+        dig_path?(obj[keys.first], keys[1..])
+      end
+
+      def dig_set!(obj, keys, value)
+        if keys.length == 1
+          obj[keys.first] = value
+        else
+          dig_set!(obj[keys.first], keys[1..], value)
+        end
+      end
+
+      def dig_delete!(obj, keys)
+        if keys.length == 1
+          return unless obj.respond_to?(:delete)
+
+          obj.delete(keys.first)
+        else
+          dig_delete!(obj[keys.first], keys[1..])
+        end
+      end
     end
 
     extend InstanceMethods

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