ecoportal-api-graphql 2.0.0 → 2.2.0

data/lib/ecoportal/api/graphql/query/page_delta.rb

@@ -1,47 +1,47 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Query
-        # Cache-invalidation query: given a list of (id, deltaAt) pairs, returns
-        # which pages have been UPDATED since that timestamp, are NOT_FOUND (deleted/
-        # inaccessible), or are NEW (id not recognised by the server).
-        #
-        # Usage:
-        #   Query::PageDelta.new(client).query(
-        #     deltaInput: [
-        #       { id: 'abc', deltaAt: '2026-01-01T00:00:00Z' },
-        #       { id: 'def', deltaAt: '2026-03-15T12:00:00Z' }
-        #     ]
-        #   )
-        #   # => [DeltaResult(id: 'abc', delta: 'UPDATED'), ...]
-        class PageDelta < Logic::QueryArray
-          field_name :pageDelta
-
-          accepted_params :deltaInput, :searchConf
-
-          class_resolver :item_class, 'Ecoportal::API::GraphQL::Base::DeltaResult'
-
-          private
-
-          def basic_block(&block)
-            item_block = block || default_block
-            proc {
-              query(deltaInput: :'[DeltaInput!]!', searchConf: :Search) {
-                currentOrganization {
-                  pageDelta(deltaInput: :deltaInput, searchConf: :searchConf, &item_block)
-                }
-              }
-            }
-          end
-
-          def default_block
-            proc {
-              id
-              delta
-            }
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Query
+        # Cache-invalidation query: given a list of (id, deltaAt) pairs, returns
+        # which pages have been UPDATED since that timestamp, are NOT_FOUND (deleted/
+        # inaccessible), or are NEW (id not recognised by the server).
+        #
+        # Usage:
+        #   Query::PageDelta.new(client).query(
+        #     deltaInput: [
+        #       { id: 'abc', deltaAt: '2026-01-01T00:00:00Z' },
+        #       { id: 'def', deltaAt: '2026-03-15T12:00:00Z' }
+        #     ]
+        #   )
+        #   # => [DeltaResult(id: 'abc', delta: 'UPDATED'), ...]
+        class PageDelta < Logic::QueryArray
+          field_name :pageDelta
+
+          accepted_params :deltaInput, :searchConf
+
+          class_resolver :item_class, 'Ecoportal::API::GraphQL::Base::DeltaResult'
+
+          private
+
+          def basic_block(&block)
+            item_block = block || default_block
+            proc {
+              query(deltaInput: :'[DeltaInput!]!', searchConf: :Search) {
+                currentOrganization {
+                  pageDelta(deltaInput: :deltaInput, searchConf: :searchConf, &item_block)
+                }
+              }
+            }
+          end
+
+          def default_block
+            proc {
+              id
+              delta
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/query/pages.rb

@@ -1,59 +1,59 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Query
-        # DB-backed full-data org search — returns PageUnion nodes with patchVer and field IDs.
-        # Required pre-update fetch: always use this (not RegisterPreviewPages) before updatePage.
-        # See .ai-assistance/code/search_filters.md — "The Required Pattern: Find Before Mutate".
-        class Pages < Logic::QueryConnection
-          field_name :pages
-          # Response nests under currentOrganization.pages; needed when instantiated
-          # directly (e.g. Compat::Pages#each) rather than via the currentOrganization proxy.
-          base_path 'currentOrganization'
-
-          class_resolver :item_class, 'Ecoportal::API::GraphQL::Model::PageUnion'
-          class_resolver :connection_class, 'Ecoportal::API::GraphQL::Connection::Page'
-
-          private
-
-          def basic_block(&block)
-            connection_block = block || default_connection_block
-            proc {
-              query(
-                searchConf: :Search,
-                after:      :string,
-                before:     :string,
-                first:      :int,
-                last:       :int
-              ) {
-                currentOrganization {
-                  pages(
-                    searchConf: :searchConf,
-                    after:      :after,
-                    before:     :before,
-                    first:      :first,
-                    last:       :last,
-                    &connection_block
-                  )
-                }
-              }
-            }
-          end
-
-          def default_connection_block
-            proc {
-              totalCount
-              pageInfo {
-                endCursor
-                hasNextPage
-              }
-              nodes {
-                spread :PageFields
-              }
-            }
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Query
+        # DB-backed full-data org search — returns PageUnion nodes with patchVer and field IDs.
+        # Required pre-update fetch: always use this (not RegisterPreviewPages) before updatePage.
+        # See .ai-assistance/code/search_filters.md — "The Required Pattern: Find Before Mutate".
+        class Pages < Logic::QueryConnection
+          field_name :pages
+          # Response nests under currentOrganization.pages; needed when instantiated
+          # directly (e.g. Compat::Pages#each) rather than via the currentOrganization proxy.
+          base_path 'currentOrganization'
+
+          class_resolver :item_class, 'Ecoportal::API::GraphQL::Model::PageUnion'
+          class_resolver :connection_class, 'Ecoportal::API::GraphQL::Connection::Page'
+
+          private
+
+          def basic_block(&block)
+            connection_block = block || default_connection_block
+            proc {
+              query(
+                searchConf: :Search,
+                after:      :string,
+                before:     :string,
+                first:      :int,
+                last:       :int
+              ) {
+                currentOrganization {
+                  pages(
+                    searchConf: :searchConf,
+                    after:      :after,
+                    before:     :before,
+                    first:      :first,
+                    last:       :last,
+                    &connection_block
+                  )
+                }
+              }
+            }
+          end
+
+          def default_connection_block
+            proc {
+              totalCount
+              pageInfo {
+                endCursor
+                hasNextPage
+              }
+              nodes {
+                spread :PageFields
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/query/person_members.rb

@@ -0,0 +1,76 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Query
+        # Lists +PersonMember+ nodes for the current organization via the
+        # GraphQL-native +organization.personMembers+ connection.
+        #
+        # This is the GraphQL-native people-directory path. It is INDEPENDENTLY
+        # USEFUL (it fills the long-standing gap flagged in
+        # +model/organization.rb+) but note: it is NOT the SCIM-sourced People
+        # replacement that customer integrations are migrating to before the
+        # APIv0 retirement, whose deadline has passed. That port is scoped in
+        # the +ecoportal-scim+ gem, project +apiv0-people-adapter+ -- not here.
+        #
+        # The default node selection intentionally inlines the fields declared on
+        # +Base::PersonMember+ rather than a +spread :PersonMember+, because no
+        # +PersonMember+ fragment is registered yet (a spread of an unregistered
+        # fragment raises at render time).
+        class PersonMembers < Logic::QueryConnection
+          field_name :personMembers
+
+          class_resolver :item_class, Model::PersonMember
+          class_resolver :connection_class, Connection::PersonMemberConnection
+
+          private
+
+          def basic_block(&block)
+            connection_block = block || default_connection_block
+            proc {
+              query(
+                searchConf:      :Search,
+                includeArchived: :boolean,
+                after:           :string,
+                before:          :string,
+                first:           :int,
+                last:            :int
+              ) {
+                currentOrganization {
+                  personMembers(
+                    searchConf:      :searchConf,
+                    includeArchived: :includeArchived,
+                    after:           :after,
+                    before:          :before,
+                    first:           :first,
+                    last:            :last,
+                    &connection_block
+                  )
+                }
+              }
+            }
+          end
+
+          def default_connection_block
+            proc {
+              totalCount
+              pageInfo {
+                endCursor
+                hasNextPage
+              }
+              nodes {
+                id
+                name
+                email
+                personSchemaId
+                contractorOrganizationId
+                userId
+                tagRestrict
+                userGroupIds
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/query/register_preset_views.rb

@@ -1,4 +1,4 @@
-module Ecoportal
+module Ecoportal
   module API
     class GraphQL
       module Query

data/lib/ecoportal/api/graphql/query/register_preview_pages.rb

@@ -1,83 +1,83 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Query
-        # Elasticsearch-backed fast search within a register.
-        # Returns PreviewPage nodes — no field IDs, no patchVer.
-        # Use for metadata lookup (find by externalId, state, location, date).
-        # Switch to Query::Pages (org search) for full data before mutations.
-        #
-        # Supports includeArchived: Boolean (default false).
-        # Supports presetViewId: ID to apply a register PageView preset.
-        class RegisterPreviewPages < Logic::QueryConnection
-          field_name :previewPages
-
-          accepted_params :registerId, :after, :before, :first, :last,
-                          :searchConf, :includeArchived, :presetViewId
-
-          class_resolver :item_class,       'Ecoportal::API::GraphQL::Model::PreviewPage'
-          class_resolver :connection_class, 'Ecoportal::API::GraphQL::Connection::PreviewPage'
-
-          def path
-            %w[currentOrganization register previewPages]
-          end
-
-          private
-
-          def basic_block(&block)
-            connection_block = block || default_connection_block
-            proc {
-              query(
-                registerId:      :id!,
-                after:           :string,
-                before:          :string,
-                first:           :int,
-                last:            :int,
-                searchConf:      :Search,
-                includeArchived: :boolean,
-                presetViewId:    :id
-              ) {
-                currentOrganization {
-                  register(id: :registerId) {
-                    previewPages(
-                      after:           :after,
-                      before:          :before,
-                      first:           :first,
-                      last:            :last,
-                      searchConf:      :searchConf,
-                      includeArchived: :includeArchived,
-                      presetViewId:    :presetViewId,
-                      &connection_block
-                    )
-                  }
-                }
-              }
-            }
-          end
-
-          def default_connection_block
-            proc {
-              totalCount
-              pageInfo {
-                endCursor
-                hasNextPage
-              }
-              nodes {
-                id
-                uid
-                name
-                state
-                archived
-                externalId
-                creatorName
-                createdAt { dateTime timeZone }
-                updatedAt { dateTime timeZone }
-                locations { id name }
-              }
-            }
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Query
+        # Elasticsearch-backed fast search within a register.
+        # Returns PreviewPage nodes — no field IDs, no patchVer.
+        # Use for metadata lookup (find by externalId, state, location, date).
+        # Switch to Query::Pages (org search) for full data before mutations.
+        #
+        # Supports includeArchived: Boolean (default false).
+        # Supports presetViewId: ID to apply a register PageView preset.
+        class RegisterPreviewPages < Logic::QueryConnection
+          field_name :previewPages
+
+          accepted_params :registerId, :after, :before, :first, :last,
+                          :searchConf, :includeArchived, :presetViewId
+
+          class_resolver :item_class,       'Ecoportal::API::GraphQL::Model::PreviewPage'
+          class_resolver :connection_class, 'Ecoportal::API::GraphQL::Connection::PreviewPage'
+
+          def path
+            %w[currentOrganization register previewPages]
+          end
+
+          private
+
+          def basic_block(&block)
+            connection_block = block || default_connection_block
+            proc {
+              query(
+                registerId:      :id!,
+                after:           :string,
+                before:          :string,
+                first:           :int,
+                last:            :int,
+                searchConf:      :Search,
+                includeArchived: :boolean,
+                presetViewId:    :id
+              ) {
+                currentOrganization {
+                  register(id: :registerId) {
+                    previewPages(
+                      after:           :after,
+                      before:          :before,
+                      first:           :first,
+                      last:            :last,
+                      searchConf:      :searchConf,
+                      includeArchived: :includeArchived,
+                      presetViewId:    :presetViewId,
+                      &connection_block
+                    )
+                  }
+                }
+              }
+            }
+          end
+
+          def default_connection_block
+            proc {
+              totalCount
+              pageInfo {
+                endCursor
+                hasNextPage
+              }
+              nodes {
+                id
+                uid
+                name
+                state
+                archived
+                externalId
+                creatorName
+                createdAt { dateTime timeZone }
+                updatedAt { dateTime timeZone }
+                locations { id name }
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/query/template_change_log.rb

@@ -0,0 +1,118 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Query
+        # TEMPLATE CHANGE LOG — "for template X, who changed what, and when", newest first,
+        # paginated.
+        #
+        # Read path (verified in the Rails backend on 2026-08-19):
+        #   currentOrganization.page(id:) → template → commands
+        # There is NO top-level query for the narrow `Template` type. `template` is declared on
+        # `app/graphql/types/pages/interfaces/base_page_interface.rb:27`, so it is reachable on
+        # any page — and a template IS a page in this platform, so pass the TEMPLATE's page id.
+        #
+        # `currentOrganization.page(id:)` returns a `PageUnion`, so `template` has to be selected
+        # through a type condition on `BasePageInterface` — selecting directly on a union is
+        # invalid GraphQL under any schema (this is the class of bug the `validate-queries` CI
+        # gate hard-fails on). The type condition does not change the response shape, so `#path`
+        # still digs currentOrganization → page → template → commands.
+        #
+        # ★ Access caveats and the forces watermark blind spot are documented on
+        # `Base::Template::ChangeLogEntry`. In short: a nil `commands` connection means the caller
+        # lacks `Pages::TemplatePolicy#update_information?`, NOT that nothing changed; and only
+        # TEMPLATE_BUILDER-sourced commands appear here (workflow-builder ones live on
+        # `Query::PagesWorkflowCommands`).
+        #
+        # Usage:
+        #   q = Query::TemplateChangeLog.new(client)
+        #   conn = q.query(id: template_page_id, first: 50)
+        #   conn.nodes.each { |e| puts "#{e.createdAt.dateTime} #{e.owner&.name} #{e.commandAction}" }
+        #
+        #   # auto-paginating enumerator (Logic::QueryConnection#each)
+        #   q.each(id: template_page_id, first: 100) { |entry| ... }
+        #
+        # Also reachable as `api.template.change_log(id:, first:)` — see `Builder::Template`.
+        #
+        # ★ For WHAT CHANGED (field/from/to, change messages) pass `detail: true` to the builder,
+        # or `&Query::TemplateChangeLog.detail_block` here. The default selection deliberately
+        # omits it so the common "who and when" read stays cheap.
+        class TemplateChangeLog < Logic::QueryConnection
+          SCHEMA_VERSION = '20260819'.freeze
+
+          field_name :commands
+
+          accepted_params :id, :after, :before, :first, :last
+
+          class_resolver :item_class,       'Ecoportal::API::GraphQL::Model::Template::ChangeLogEntry'
+          class_resolver :connection_class, 'Ecoportal::API::GraphQL::Connection::TemplateChangeLog'
+
+          # Absolute — the connection is nested three levels deep, so it is not expressible as
+          # `base_path + field_name`.
+          def path
+            %w[currentOrganization page template commands]
+          end
+
+          # Connection block that selects FIELD-LEVEL DETAIL as well -- what changed, not just
+          # who/when/which-resource. Opt-in, because it adds three inline fragments and their
+          # sub-selections to every node.
+          #
+          #   q = Query::TemplateChangeLog.new(client)
+          #   conn = q.query(id: template_page_id, first: 50, &described_class.detail_block)
+          #   conn.nodes.each do |e|
+          #     case e.detail_kind
+          #     when :changes         then e.changes.each { |c| puts "#{c['field']}: #{c['from']} -> #{c['to']}" }
+          #     when :change_messages then puts e.changeMessages.join('; ')
+          #     when :es_changes      then puts "filter changed: #{e.changes.map { |c| c['field'] }.join(', ')}"
+          #     end
+          #   end
+          #
+          # Or simply `api.template.change_log(id:, first:, detail: true)`.
+          def self.detail_block
+            proc {
+              totalCount
+              pageInfo {
+                endCursor
+                hasNextPage
+              }
+              nodes {
+                spread :TemplateChangeLogEntryDetail
+              }
+            }
+          end
+
+          private
+
+          def basic_block(&block)
+            connection_block = block || default_connection_block
+            proc {
+              query(id: :id!, after: :string, before: :string, first: :int, last: :int) {
+                currentOrganization {
+                  page(id: :id) {
+                    spread on: :BasePageInterface do
+                      template {
+                        commands(after: :after, before: :before, first: :first, last: :last, &connection_block)
+                      }
+                    end
+                  }
+                }
+              }
+            }
+          end
+
+          def default_connection_block
+            proc {
+              totalCount
+              pageInfo {
+                endCursor
+                hasNextPage
+              }
+              nodes {
+                spread :TemplateChangeLogEntry
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end