ecoportal-api-graphql 1.3.5 → 1.3.10

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

@@ -0,0 +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

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

@@ -0,0 +1,43 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Query
+        # Fetches a single page by ID, including its full forces array.
+        # Used by OozeRedirect::ForceCompat instead of the standard Query::Page
+        # so that `page.forces.get_by_name(name)` returns populated data.
+        #
+        # Usage (via ForceCompat — not typically called directly):
+        #   page = Query::PageWithForces.new(client).query(id: page_id)
+        #   force = page.forces.get_by_name('Workflow (S1)').first
+        class PageWithForces < Logic::Query
+          field_name :page
+
+          accepted_params :id
+          class_resolver :item_class, 'Ecoportal::API::GraphQL::Model::PageUnion'
+
+          private
+
+          def basic_block(&block)
+            page_block = block || default_block
+            proc {
+              query(id: :id!) {
+                currentOrganization {
+                  page(id: :id, &page_block)
+                }
+              }
+            }
+          end
+
+          def default_block
+            proc {
+              spread :PageFields
+              forces {
+                spread :ForceFields
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +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

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

@@ -0,0 +1,59 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Query
+        # Paginated command log for a page's PagesWorkflow.
+        # Returns PagesWorkflowCommandInterface nodes — each command applied to
+        # the workflow builder (change, changeMessage, esChange concrete types).
+        #
+        # Usage:
+        #   q = Query::PagesWorkflowCommands.new(client)
+        #   q.each(id: page.id, first: 50) { |cmd| puts cmd.doc['commandAction'] }
+        class PagesWorkflowCommands < Logic::QueryConnection
+          SCHEMA_VERSION = '20260605'.freeze
+
+          field_name :commands
+
+          accepted_params :id, :after, :before, :first, :last
+
+          class_resolver :item_class,       'Ecoportal::API::GraphQL::Base::PagesWorkflow::CommandInterface'
+          class_resolver :connection_class, 'Ecoportal::API::GraphQL::Connection::PagesWorkflowCommand'
+
+          def path
+            %w[currentOrganization page workflow commands]
+          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) {
+                    workflow {
+                      commands(after: :after, before: :before, first: :first, last: :last, &connection_block)
+                    }
+                  }
+                }
+              }
+            }
+          end
+
+          def default_connection_block
+            proc {
+              totalCount
+              pageInfo {
+                endCursor
+                hasNextPage
+              }
+              nodes {
+                spread :PagesWorkflowCommandFields
+              }
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Query
+        # Lists preset views for a register.
+        # Returns an array of PresetView objects — not paginated (server returns all at once).
+        # Use the returned IDs as `presetViewId` in RegisterPreviewPages queries.
+        #
+        # Usage:
+        #   views = Query::RegisterPresetViews.new(client).query(registerId: 'REG_ID')
+        #   views.map { |v| { id: v.id, name: v.name, global: v.global? } }
+        class RegisterPresetViews < Logic::Query
+          field_name :presetViews
+
+          accepted_params :registerId, :searchConf
+
+          class_resolver :item_class, 'Ecoportal::API::GraphQL::Model::PresetView'
+
+          def path
+            %w[currentOrganization register presetViews]
+          end
+
+          def response_class
+            # presetViews returns an array — wrap in a simple array-like response
+            ArrayResponse
+          end
+
+          # Minimal array wrapper so callers can iterate results with .each / .map
+          class ArrayResponse
+            include Enumerable
+
+            def initialize(raw)
+              klass = Ecoportal::API::GraphQL::Model::PresetView
+              @items = Array(raw).map { |d| klass.new(d) }
+            end
+
+            def each(&block)
+              @items.each(&block)
+            end
+
+            def nodes
+              @items
+            end
+          end
+
+          private
+
+          def basic_block(&block)
+            view_block = block || default_block
+            proc {
+              query(
+                registerId: :id!,
+                searchConf: :Search
+              ) {
+                currentOrganization {
+                  register(id: :registerId) {
+                    presetViews(searchConf: :searchConf, &view_block)
+                  }
+                }
+              }
+            }
+          end
+
+          def default_block
+            proc {
+              id
+              name
+              global
+              registerId
+              sorter { key direction missing }
+              fieldConfigurations { id key name weight }
+            }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +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

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

@@ -0,0 +1,53 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Query
+        class Templates < Logic::QueryConnection
+          field_name :templates
+
+          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 {
+                  templates(
+                    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.rb

@@ -14,3 +14,14 @@ require_relative 'query/action_categories'
 require_relative 'query/action'
 require_relative 'query/actions'
 require_relative 'query/contractor_entities'
+require_relative 'query/page'
+require_relative 'query/pages'
+require_relative 'query/templates'
+require_relative 'query/register_preview_pages'
+require_relative 'query/page_delta'
+require_relative 'query/register_preset_views'
+
+require_relative 'query/file_upload_signature'
+
+require_relative 'query/page_with_forces'
+require_relative 'query/pages_workflow_commands'

data/lib/ecoportal/api/graphql.rb

@@ -1,80 +1,138 @@
-module Ecoportal
-  module API
-    # @attr_reader client [Common::GraphQL::Client] a client object that holds the configuration of the api connection.
-    # @attr_reader logger [Logger] the logger.
-    class GraphQL
-      include Ecoportal::API::Common::GraphQL::ClassHelpers
-
-      class_resolver :client_class, Ecoportal::API::Common::GraphQL::Client
-
-      attr_reader :client, :fragments
-
-      # Creates a `GraphQL` object to interact with the ecoPortal `GraphQL API`.
-      # @param org_id [String] the id of the target organization.
-      #    It defaults to the environmental variable `ORGANIZATION_ID`, if defined
-      # @param logger [Logger] an object with `Logger` interface to generate logs.
-      def initialize(email: nil, pass: nil, org_id: nil, host: "live.ecoportal.com")
-        kargs    = {
-          email:     email,
-          pass:      pass,
-          host:      host,
-          org_id:    org_id,
-          no_schema: true
-        }
-
-        @client    = client_class.new(**kargs)
-        @fragments = Ecoportal::API::GraphQL::Fragment.new(client)
-      end
-
-      def currentOrganizationClass
-        API::GraphQL::Model::Organization.tap do |org_class|
-          org_class.client = client
-        end
-      end
-
-      def currentOrganization
-        currentOrganizationClass
-      end
-
-      def createContractorEntity(input:, &block)
-        createContractorEntityMutation.query(input: input, &block)
-      end
-
-      def contractorEntity
-        Ecoportal::API::GraphQL::Builder::ContractorEntity.new(client)
-      end
-
-      # Gives a builder to use different options to modify a reporting structure
-      def locationStructure
-        Ecoportal::API::GraphQL::Builder::LocationStructure.new(client)
-      end
-
-      # Gives a builder to use different options to play with action
-      def action
-        Ecoportal::API::GraphQL::Builder::Action.new(client)
-      end
-
-      private
-
-      def createContractorEntityMutation
-        Ecoportal::API::GraphQL::Mutation::ContractorEntity::Create.new(client)
-      end
-    end
-  end
-end
-
-require_relative 'graphql/helpers'
-require_relative 'graphql/concerns'
-require_relative 'graphql/logic/base_model'
-require_relative 'graphql/error'
-require_relative 'graphql/interface'
-require_relative 'graphql/base'
-require_relative 'graphql/model'
-require_relative 'graphql/logic'
-require_relative 'graphql/connection'
-require_relative 'graphql/payload'
-require_relative 'graphql/input'
-require_relative 'graphql/fragment'
-require_relative 'graphql/query'
-require_relative 'graphql/mutation'
-require_relative 'graphql/builder'
+module Ecoportal
+  module API
+    # @attr_reader client [Common::GraphQL::Client] a client object that holds the configuration of the api connection.
+    # @attr_reader logger [Logger] the logger.
+    class GraphQL
+      include Ecoportal::API::Common::GraphQL::ClassHelpers
+
+      class_resolver :client_class, Ecoportal::API::Common::GraphQL::Client
+
+      attr_reader :client, :fragments
+
+      # Creates a `GraphQL` object to interact with the ecoPortal `GraphQL API`.
+      # @param org_id [String] the id of the target organization.
+      #    It defaults to the environmental variable `ORGANIZATION_ID`, if defined
+      # @param logger [Logger] an object with `Logger` interface to generate logs.
+      def initialize(email: nil, pass: nil, org_id: nil, host: "live.ecoportal.com")
+        kargs = {
+          email:     email,
+          pass:      pass,
+          host:      host,
+          org_id:    org_id,
+          no_schema: true
+        }
+
+        @client = client_class.new(**kargs)
+        @client.http_client = Ecoportal::API::Common::GraphQL::HttpClient.new(
+          email:  email,
+          pass:   pass,
+          org_id: org_id,
+          host:   host
+        )
+        @fragments = Ecoportal::API::GraphQL::Fragment.new(client)
+      end
+
+      def currentOrganizationClass
+        API::GraphQL::Model::Organization.tap do |org_class|
+          org_class.client = client
+        end
+      end
+
+      def currentOrganization
+        currentOrganizationClass
+      end
+
+      def createContractorEntity(input:, &block)
+        createContractorEntityMutation.query(input: input, &block)
+      end
+
+      def contractorEntity
+        Ecoportal::API::GraphQL::Builder::ContractorEntity.new(client)
+      end
+
+      # Gives a builder to use different options to modify a reporting structure
+      def locationStructure
+        Ecoportal::API::GraphQL::Builder::LocationStructure.new(client)
+      end
+
+      # Gives a builder to use different options to play with action
+      def action
+        Ecoportal::API::GraphQL::Builder::Action.new(client)
+      end
+
+      # Gives a builder to use different options to work with pages
+      def page
+        Ecoportal::API::GraphQL::Builder::Page.new(client)
+      end
+
+      # v2-compatible pages API — exposes get/get_new/create/update/get_body
+      # matching the interface eco-helpers scripts use against ecoportal-api-v2.
+      def pages
+        Compat::Pages.new(client)
+      end
+
+      # v2-compatible registers API — exposes search with cursor pagination.
+      def registers
+        Compat::Registers.new(client)
+      end
+
+      # Mutation builder for register CRUD + preset view management.
+      # Distinct from #registers (compat search layer).
+      #
+      # Usage:
+      #   api.register.create(input: { name: 'Safety', moduleType: 'form', filterTags: [] })
+      #   api.register.preset_view.list('REG_ID')
+      #   api.register.preset_view.create(input: { registerId: 'R', name: 'Active', fieldConfigs: [] })
+      def register
+        Ecoportal::API::GraphQL::Builder::Register.new(client)
+      end
+
+      # Kickstand workflow engine controls — start/stop/fail individual workflows
+      # or bulk-update a set. Internal back-end automation; not for customer scripts.
+      def kickstand
+        Builder::Kickstand.new(client)
+      end
+
+      # Template management — create/update/publish/unpublish templates and manage
+      # template information and related pages.
+      def template
+        Builder::Template.new(client)
+      end
+
+      # File upload orchestrator — get S3 credentials, upload to S3, register, poll.
+      # Returns a fileContainerId string usable in FileField/ImageGallery mutations.
+      #
+      # Usage:
+      #   id = api.file_upload.upload('/path/to/report.pdf')
+      #   page.components.get_by_name('Report').file_container_ids = [id]
+      #   api.pages.update(page)
+      def file_upload
+        Ecoportal::API::GraphQL::FileUpload::Client.new(self)
+      end
+
+      private
+
+      def createContractorEntityMutation
+        Ecoportal::API::GraphQL::Mutation::ContractorEntity::Create.new(client)
+      end
+    end
+  end
+end
+
+require_relative 'graphql/helpers'
+require_relative 'graphql/concerns'
+require_relative 'graphql/logic/base_model'
+require_relative 'graphql/error'
+require_relative 'graphql/interface'
+require_relative 'graphql/base'
+require_relative 'graphql/model'
+require_relative 'graphql/logic'
+require_relative 'graphql/connection'
+require_relative 'graphql/payload'
+require_relative 'graphql/input'
+require_relative 'graphql/fragment'
+require_relative 'graphql/query'
+require_relative 'graphql/mutation'
+require_relative 'graphql/builder'
+require_relative 'graphql/compat'
+require_relative 'graphql/file_upload'

data/lib/ecoportal/api/graphql_version.rb

@@ -1,5 +1,5 @@
-module Ecoportal
-  module API
-    GRAPQL_VERSION = '1.3.5'.freeze
-  end
-end
+module Ecoportal
+  module API
+    GRAPQL_VERSION = '1.3.10'.freeze
+  end
+end