ecoportal-api-graphql 1.3.5 → 1.3.9

data/lib/ecoportal/api/graphql/input/page/archive.rb

@@ -0,0 +1,14 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class Page
+          class Archive < Logic::Input
+            passkey :id
+            passthrough :patchVer
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/page/build_from_template.rb

@@ -0,0 +1,13 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class Page
+          class BuildFromTemplate < Logic::Input
+            passthrough :templateId, :showHiddenData, :clientMutationId
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/page/create_draft.rb

@@ -0,0 +1,13 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class Page
+          class CreateDraft < Logic::Input
+            passthrough :templateId
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/page/create_from_template.rb

@@ -0,0 +1,18 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class Page
+          # Maps CreateFromTemplateInput.
+          # dataFields.updates is passed as a raw array — typed support is Phase E.
+          class CreateFromTemplate < Logic::Input
+            passthrough :templateId, :showHiddenData, :stageId, :submit, :attach, :draft
+            passthrough :clientMutationId
+            passthrough :dataFields # raw: { updates: [...typed field hashes...] }
+            embeds_one  :page, klass: 'Ecoportal::API::GraphQL::Input::Page'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/page/delete_draft.rb

@@ -0,0 +1,13 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class Page
+          class DeleteDraft < Logic::Input
+            passkey :id
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/page/publish_draft.rb

@@ -0,0 +1,13 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class Page
+          class PublishDraft < Logic::Input
+            passkey :id
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/page/review_task.rb

@@ -0,0 +1,14 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class Page
+          class ReviewTask < Logic::Input
+            passkey :id
+            passthrough :stageId, :comment
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/page/unarchive.rb

@@ -0,0 +1,14 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class Page
+          class Unarchive < Logic::Input
+            passkey :id
+            passthrough :patchVer
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/page/update.rb

@@ -0,0 +1,140 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class Page
+          class Update < Logic::Input
+            passkey :id
+            passthrough :patchVer, :publish, :clientMutationId
+
+            PAGE_FIELD_KEYS = Input::Page::PAGE_FIELD_KEYS
+
+            class << self
+              # Builds UpdatePageInput from a page model.
+              # Returns nil when there are no changes and no operation is requested.
+              # patchVer is always included when present (required for concurrency control).
+              #
+              # Options:
+              #   stage_id:           ID      — target a specific stage (required for stage submit/close-out)
+              #   submit:             Boolean — submit the stage (triggers task transitions server-side)
+              #   publish:            Boolean — publish a draft page
+              #   show_hidden_data:   Boolean — include hidden data in the mutation response
+              #   task:               Hash    — raw page-task command, passed through verbatim. Variants:
+              #                                   { completePageTask: { forcedComplete:, signOff:, notes: } } — complete the page task
+              #                                   { reviewPageTask: { signOff:, notes: } }  — sign off / annotate a review task
+              #   complete_page_task: Boolean|Hash — sugar for task: { completePageTask: ... }.
+              #                                   true → { completePageTask: {} } (bare submit, no inline review).
+              #                                   Hash → inline CompletePageInput fields (snake_case keys):
+              #                                     { sign_off:, forced_complete:, notes: } →
+              #                                     { completePageTask: { signOff:, forcedComplete:, notes: } }.
+              #                                   Use { sign_off: true } to submit AND sign-off in ONE call —
+              #                                   this advances a stage whose config has a review task (the
+              #                                   server auto-approves the review inline). Distinct from the
+              #                                   sign_off:/review_notes: sugar below, which targets reviewPageTask
+              #                                   (the separate review-approval path).
+              #   sign_off:           Boolean — sugar: task: { reviewPageTask: { signOff: ... } }
+              #   review_notes:       String  — sugar: adds notes: to the reviewPageTask
+              #   location_ids:       [ID]    — set page locations (PageInput.locations); the
+              #                                 model's locations embed is read_only, so this is
+              #                                 the way to write them
+              #   client_mutation_id: String
+              def from_model(model, stage_id: nil, submit: nil, publish: nil, show_hidden_data: nil,
+                             task: nil, complete_page_task: false, sign_off: nil, review_notes: nil,
+                             location_ids: nil, client_mutation_id: '', **_kargs)
+                task = resolve_task(task, complete_page_task, sign_off, review_notes)
+                require_stage!(stage_id, submit, task)
+                page_input = (model.as_update || {}).slice(*PAGE_FIELD_KEYS)
+                # Page locations are read_only on the model (excluded from the as_update diff),
+                # so set them explicitly here → PageInput.locations = [LocationInput{ id }].
+                page_input = page_input.merge(locations: Array(location_ids).map { |lid| { id: lid } }) unless location_ids.nil?
+                data_fields = build_data_fields(model)
+
+                no_changes = page_input.empty? && data_fields.empty?
+                no_op      = publish.nil? && submit.nil? && stage_id.nil? && task.nil?
+                return nil if no_changes && no_op
+
+                operation = {
+                  stageId:          stage_id,
+                  submit:           submit,
+                  publish:          publish,
+                  showHiddenData:   show_hidden_data,
+                  task:             task,
+                  clientMutationId: (client_mutation_id.to_s.empty? ? nil : client_mutation_id)
+                }
+                build_input(model, page_input, data_fields, operation)
+              end
+
+              private
+
+              # Platform invariant: a stage submit / sign-off MUST target a specific stage.
+              # Page tasks (and the people-field permissions scoped to them) apply to ONE
+              # stage; without a stageId the server cannot route the submit to the stage the
+              # work was done on. Fail loudly here rather than silently omit stageId (the
+              # nil-guard in build_input would otherwise drop it — the exact bug that let an
+              # act-gov TOOCS submit go out stage-less). A plain field update or publish
+              # needs no stage and is unaffected.
+              def require_stage!(stage_id, submit, task)
+                return unless stage_id.nil?
+                return unless submit || task
+
+                raise ArgumentError,
+                      'stageId is required to submit or complete a stage task (people-field ' \
+                      'permissions are stage-scoped). Pass stage_id:, or operate via a stage ' \
+                      'view (Compat::Pages#get(id, stage_id:) / OozeRedirect#stage) so the ' \
+                      'submit targets the stage the work was done on.'
+              end
+
+              # Resolves the `task` command from an explicit hash or the convenience flags.
+              # An explicit `task:` always wins; otherwise complete_page_task / sign_off build it.
+              def resolve_task(task, complete_page_task, sign_off, review_notes)
+                return task unless task.nil?
+                return build_complete_page_task(complete_page_task) if complete_page_task
+                return nil if sign_off.nil? && review_notes.nil?
+
+                review = {}
+                review[:signOff] = sign_off     unless sign_off.nil?
+                review[:notes]   = review_notes unless review_notes.nil?
+                { reviewPageTask: review }
+              end
+
+              # completePageTask command. `flag` is either `true` (bare completion) or a Hash of
+              # inline CompletePageInput options with snake_case keys (sign_off:, forced_complete:,
+              # notes:). Inline signOff advances a stage whose config has a review task — the server
+              # auto-approves the review in the same updatePage call.
+              def build_complete_page_task(flag)
+                return { completePageTask: {} } unless flag.is_a?(Hash)
+
+                inner = {}
+                inner[:forcedComplete] = flag[:forced_complete] unless flag[:forced_complete].nil?
+                inner[:signOff]        = flag[:sign_off]        unless flag[:sign_off].nil?
+                inner[:notes]          = flag[:notes]           unless flag[:notes].nil?
+                { completePageTask: inner }
+              end
+
+              def build_input(model, page_input, data_fields, operation)
+                { id: model.id }.tap do |input|
+                  input[:patchVer] = model.patchVer if model.respond_to?(:patchVer) && !model.patchVer.nil?
+                  input[:page]     = page_input unless page_input.empty?
+                  operation.each { |key, value| input[key] = value unless value.nil? }
+                  input[:dataFields] = data_fields unless data_fields.empty?
+                end
+              end
+
+              def build_data_fields(model)
+                updates   = model.respond_to?(:data_fields_updates)   ? model.data_fields_updates   : []
+                additions = model.respond_to?(:data_fields_additions) ? model.data_fields_additions : []
+                deletions = model.respond_to?(:data_fields_deletions) ? model.data_fields_deletions : []
+
+                {}.tap do |h|
+                  h[:updates]   = updates   unless updates.empty?
+                  h[:additions] = additions unless additions.empty?
+                  h[:deletions] = deletions unless deletions.empty?
+                end
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/page.rb

@@ -0,0 +1,26 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class Page < Logic::Input
+          # Fields that belong in PageInput (the nested sub-object of UpdatePageInput).
+          # Referenced by Input::Page::Update.from_model to extract the right keys from the diff.
+          PAGE_FIELD_KEYS = %i[name state taskPriority timeZone externalId locations otherTags].freeze
+
+          passthrough :name, :state, :taskPriority, :timeZone, :externalId
+          passarray :locations, :otherTags
+        end
+      end
+    end
+  end
+end
+
+require_relative 'page/update'
+require_relative 'page/archive'
+require_relative 'page/unarchive'
+require_relative 'page/build_from_template'
+require_relative 'page/create_from_template'
+require_relative 'page/create_draft'
+require_relative 'page/delete_draft'
+require_relative 'page/publish_draft'
+require_relative 'page/review_task'

data/lib/ecoportal/api/graphql/input/preset_view/create.rb

@@ -0,0 +1,18 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class PresetView
+          # fieldConfigs: array of FieldConfigurationInput hashes
+          # { id:, key:, name:, weight:, type:, ... }
+          # sorter: { key:, direction:, missing: }
+          class Create < Logic::Input
+            passthrough :registerId, :name, :sorter
+            passboolean :customPresetView, :preview
+            passarray   :fieldConfigs
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/preset_view/permission.rb

@@ -0,0 +1,16 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class PresetView
+          # permissions: array of PresetViewPermissionInput hashes
+          # Each: { id:, level: "view"|"edit", to: { userId: } | { userGroupId: }, destroy: }
+          class Permission < Logic::Input
+            passkey   :id
+            passarray :permissions
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/preset_view/update.rb

@@ -0,0 +1,16 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class PresetView
+          class Update < Logic::Input
+            passkey     :id
+            passthrough :name, :sorter
+            passboolean :preview
+            passarray   :fieldConfigs
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/preset_view.rb

@@ -0,0 +1,14 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class PresetView < Logic::Input
+        end
+      end
+    end
+  end
+end
+
+require_relative 'preset_view/create'
+require_relative 'preset_view/update'
+require_relative 'preset_view/permission'

data/lib/ecoportal/api/graphql/input/register/create.rb

@@ -0,0 +1,18 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class Register
+          class Create < Logic::Input
+            passthrough :name, :iconName, :descriptionText, :moduleType, :registerStatus
+            passthrough :restrictedAmountOfTemplates
+            passboolean :shown, :creatable, :attachable, :permissioned
+            passboolean :contentShareable, :enableEmailOut, :isMobile
+            passboolean :restrictTemplatesAmount
+            passarray   :filterTags, :userPermissions, :userGroupPermissions
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/register/update.rb

@@ -0,0 +1,15 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class Register
+          class Update < Create
+            passkey      :id
+            passthrough  :defaultDashboardId
+            passarray    :visibleTargetFields
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/input/register.rb

@@ -0,0 +1,13 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class Register < Logic::Input
+        end
+      end
+    end
+  end
+end
+
+require_relative 'register/create'
+require_relative 'register/update'

data/lib/ecoportal/api/graphql/input/search_conf/ai_generator.rb

@@ -0,0 +1,234 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class SearchConf
+          # AI-assisted filter generation — builds a SearchConf from a natural-language
+          # description using Claude (Anthropic API) with structured tool use output.
+          #
+          # Requires the `anthropic` gem to be available in the caller's environment.
+          # No hard dependency is added to ecoportal-api-graphql's gemspec.
+          #
+          # Usage:
+          #   require 'anthropic'
+          #
+          #   conf = SearchConf.from_description(
+          #     "find active pages in the Safety register updated in the last month",
+          #     api_key:     ENV['ANTHROPIC_API_KEY'],
+          #     register_id: 'REG_SAFETY_123'
+          #   )
+          #   # => #<SearchConf filters=[...] sorters=...>
+          #
+          #   # Then use it:
+          #   org.pages(searchConf: conf.to_h, first: 50)
+          #
+          # Options:
+          #   api_key:      Anthropic API key (default: ENV['ANTHROPIC_API_KEY'])
+          #   model:        Claude model ID (default: 'claude-sonnet-4-6')
+          #   register_id:  Scope results to this register (adds register_filter)
+          #   context:      Hash of extra context passed to the prompt (e.g. available states)
+          #   validate:     Boolean — if true, raises on ambiguous/empty result (default: false)
+          module AIGenerator
+            TOOL_NAME     = 'build_search_conf'.freeze
+            DEFAULT_MODEL = 'claude-sonnet-4-6'.freeze
+
+            SYSTEM_PROMPT = <<~PROMPT.freeze
+              You are a search query translator for the EcoPortal GraphQL API.
+              Convert natural-language descriptions into structured searchConf filter specifications.
+
+              ## Available filter operations (snake_case strings — case-sensitive)
+
+              | operation           | params                                      | notes                          |
+              |---------------------|---------------------------------------------|--------------------------------|
+              | exact_filter        | key, value                                  | equality match                 |
+              | one_of_filter       | key, values (array)                         | any of N values                |
+              | none_of_filter      | key, values (array)                         | exclude all values             |
+              | date_filter         | key, gte, lte, time_zone (UTC default)      | ISO8601 or mode                |
+              | date_filter (mode)  | key, mode, time_zone                        | modes: last_month, last_week, current_year, past, future, etc. |
+              | register_filter     | ids (array)                                 | scope to register(s)           |
+              | has_any_filter      | key                                         | field has any non-empty value  |
+              | match_filter        | key, value                                  | partial text match             |
+              | and_filter          | filters (array of filter objects)           | explicit AND group             |
+              | or_filter           | filters (array of filter objects)           | OR group                       |
+              | boolean_filter      | key, value (true/false)                     | boolean field                  |
+              | numeric_range_filter| key, gte, lte                               | numeric bounds                 |
+              | isnt_exact_filter   | key, value                                  | negated equality               |
+
+              ## Common page field names (key values)
+
+              | fieldName       | type    | common values                          |
+              |-----------------|---------|----------------------------------------|
+              | state           | string  | "active", "inactive", "complete"       |
+              | external_id     | string  | unique identifier                      |
+              | name            | string  | page name (use match_filter for partial)|
+              | creator_id      | string  | PersonMember ID                        |
+              | created_at      | date    | ISO8601 datetime                       |
+              | updated_at      | date    | ISO8601 datetime                       |
+              | all_location_ids| string  | location node ID (includes ancestors)  |
+              | location_id     | string  | exact location node ID                 |
+              | other_tags      | string  | tag string values                      |
+              | archived        | boolean | true/false                             |
+              | draft           | boolean | true/false                             |
+
+              ## Rules
+              - Top-level filters array is implicitly AND — no need to wrap in and_filter unless nesting inside or_filter
+              - Use register_filter when a specific register is mentioned or provided in context
+              - Use date_filter with mode (e.g. "last_month") for relative dates; ISO8601 for absolute dates
+              - Default sort is created_at desc unless the user specifies otherwise
+              - If the description is too vague to produce a useful filter, produce an empty filters array and explain in the reasoning field
+              - snake_case operation names are MANDATORY — CamelCase returns no results silently
+
+              Call the build_search_conf tool with your result.
+            PROMPT
+
+            module_function
+
+            # Build a SearchConf from a natural-language description via Claude API.
+            def from_description(text, api_key: nil, model: DEFAULT_MODEL,
+                                 register_id: nil, context: {}, validate: false)
+              require_anthropic!
+
+              client = ::Anthropic::Client.new(api_key: api_key || ENV.fetch('ANTHROPIC_API_KEY'))
+
+              user_message = build_user_message(text, register_id: register_id, context: context)
+              response     = client.messages.create(
+                model:      model,
+                max_tokens: 1024,
+                system:     SYSTEM_PROMPT,
+                tools:      [SEARCH_CONF_TOOL],
+                messages:   [{ role: 'user', content: user_message }]
+              )
+
+              result = extract_tool_result(response)
+              conf   = build_search_conf(result, register_id: register_id)
+
+              if validate && conf.to_h.empty?
+                raise ArgumentError, "AI could not produce filters for: #{text.inspect}. " \
+                                     "Reasoning: #{result['reasoning']}"
+              end
+
+              conf
+            end
+
+            def require_anthropic!
+              require 'anthropic'
+            rescue LoadError
+              raise LoadError,
+                    "SearchConf.from_description requires the 'anthropic' gem. " \
+                    "Add `gem 'anthropic'` to your Gemfile and run `bundle install`."
+            end
+
+            def build_user_message(text, register_id:, context:)
+              parts = ["Convert this description to a searchConf filter: #{text.inspect}"]
+              parts << "Register ID to scope results: #{register_id}" if register_id
+              context.each { |k, v| parts << "Context — #{k}: #{v}" }
+              parts.join("\n")
+            end
+
+            def extract_tool_result(response)
+              tool_use = response.content.find { |b| b.type == 'tool_use' && b.name == TOOL_NAME }
+              raise "AI did not call #{TOOL_NAME} — response: #{response.content.map(&:type)}" unless tool_use
+
+              tool_use.input
+            end
+
+            def build_search_conf(result, register_id:)
+              conf = SearchConf.new
+              conf = apply_register(conf, result, register_id)
+              conf = apply_filters(conf, result['filters'])
+              conf = apply_sorters(conf, result['sorters'])
+              apply_query(conf, result['query'])
+            end
+
+            def apply_register(conf, result, register_id)
+              ids = result['register_ids']&.compact&.reject(&:empty?)
+              if ids && !ids.empty?
+                conf.filter(SearchConf::Register.new(*ids))
+              elsif register_id
+                conf.filter(SearchConf::Register.new(register_id))
+              else
+                conf
+              end
+            end
+
+            def apply_filters(conf, filters)
+              Array(filters).reduce(conf) do |c, f|
+                c.filter(SearchConf::RawFilter.new(f['operation'], **symbolize(f['params'] || {})))
+              end
+            end
+
+            def apply_sorters(conf, sorters)
+              Array(sorters).reduce(conf) do |c, s|
+                c.sort(s['key'].to_sym, s['direction']&.to_sym || :desc)
+              end
+            end
+
+            def apply_query(conf, query)
+              return conf unless query && !query.strip.empty?
+
+              conf.query(query)
+            end
+
+            def symbolize(hash)
+              hash.each_with_object({}) { |(k, v), h| h[k.to_sym] = v }
+            end
+
+            # JSON Schema for the tool — Claude must call this with the filter spec.
+            SEARCH_CONF_TOOL = {
+              name:         TOOL_NAME,
+              description:  'Output a structured searchConf filter specification',
+              input_schema: {
+                type:       'object',
+                required:   %w[filters],
+                properties: {
+                  reasoning:    {
+                    type:        'string',
+                    description: 'Brief explanation of the chosen filters'
+                  },
+                  register_ids: {
+                    type:        'array',
+                    description: 'Register IDs to scope the search (leave empty for org-wide)',
+                    items:       { type: 'string' }
+                  },
+                  filters:      {
+                    type:        'array',
+                    description: 'Array of filter objects (top-level is implicit AND)',
+                    items:       {
+                      type:       'object',
+                      required:   %w[operation params],
+                      properties: {
+                        operation: {
+                          type:        'string',
+                          description: 'Filter operation name (snake_case)'
+                        },
+                        params:    {
+                          type:        'object',
+                          description: 'Operation parameters (key, value, ids, filters, gte, lte, etc.)'
+                        }
+                      }
+                    }
+                  },
+                  sorters:      {
+                    type:  'array',
+                    items: {
+                      type:       'object',
+                      required:   %w[key direction],
+                      properties: {
+                        key:       { type: 'string' },
+                        direction: { type: 'string', enum: %w[asc desc] }
+                      }
+                    }
+                  },
+                  query:        {
+                    type:        'string',
+                    description: 'Full-text search string (optional)'
+                  }
+                }
+              }
+            }.freeze
+          end
+        end
+      end
+    end
+  end
+end