ecoportal-api-graphql 1.3.5 → 1.3.17

data/lib/ecoportal/api/graphql/builder.rb

@@ -1,14 +1,17 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Builder
-      end
-    end
-  end
-end
-
-require_relative 'builder/location_structure'
-require_relative 'builder/action'
-require_relative 'builder/contractor_entity'
-require_relative 'builder/register'
-require_relative 'builder/page'
+module Ecoportal
+  module API
+    class GraphQL
+      module Builder
+      end
+    end
+  end
+end
+
+require_relative 'builder/location_structure'
+require_relative 'builder/action'
+require_relative 'builder/contractor_entity'
+require_relative 'builder/register'
+require_relative 'builder/page'
+require_relative 'builder/kickstand'
+require_relative 'builder/template'
+require_relative 'builder/template_builder'

data/lib/ecoportal/api/graphql/compat/filter_translator.rb

@@ -0,0 +1,142 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Compat
+        # Translates v2-style filter hashes to GraphQL-compatible filter hashes.
+        # Extracted from Compat::Registers so any part of the compat layer can use it.
+        #
+        # SearchConf filter objects (respond_to :to_h, not a Hash) are passed through —
+        # callers may also pass already-translated hashes or SearchConf instances directly.
+        #
+        # v2 → GraphQL translation table:
+        #   date_filter     lbound/ubound → gte/lte; Date FIELD (key 'date.zXXXX') →
+        #                   range_date_filter + membranes.date path; system date → date_filter
+        #   text_filter     {query, key} → match_filter {key, value} (partial text)
+        #   options_filter  Select FIELD (key 'select_str.zXXXX') → has_any_filter
+        #                   {key, path, field_key: 'selected', values} (doesnt_have_any_filter to
+        #                   exclude); system option key → one_of_filter/none_of_filter {key, values}
+        #   tag_filter      passed through (same ES backend, same format)
+        #   register_filter passed through
+        #   and_filter / or_filter  passed through
+        # Operation/param shapes per the repo's internal docs.
+        class FilterTranslator
+          class << self
+            def to_graphql(filter)
+              return filter if filter.respond_to?(:to_h) && !filter.is_a?(Hash)
+              return filter unless filter.is_a?(Hash)
+
+              case filter['type'] || filter[:type]
+              when 'date_filter'
+                translate_date_filter(filter)
+              when 'text_filter'
+                translate_text_filter(filter)
+              when 'exact_filter', 'is_filter'
+                translate_exact_filter(filter)
+              when 'options_filter'
+                translate_options_filter(filter)
+              else
+                filter
+              end
+            end
+
+            private
+
+            # v2 exact_filter {query/value, key} → GraphQL is_filter (whole-value equality).
+            # For a register/page field there is NO `exact_filter` operation — `is_filter` is the
+            # exact one: it matches the field's `.exact` keyword subfield (backend
+            # NewEp::Es::Filters::Pages::IsFilter → ExactFilter on `membranes.<type>.exact`),
+            # whereas match_filter/contains_filter hit the analyzed `.value` and miss exact SKUs.
+            # A register FIELD key ('plain_text.zXXXX') needs the nested membranes.<type> path;
+            # a SYSTEM key (external_id/id/state/creator_id/source) must NOT carry a path — the
+            # backend routes it to Global::ExactFilter which joins [@path,@key] into the term key,
+            # so a spurious 'membranes.external_id' yields term 'membranes.external_id.external_id'
+            # → 0 results (proof: pages/is_filter.rb:36-55 passes path: @path to Global::ExactFilter;
+            # global/exact_filter.rb:18 builds the term as [@path, @key].compact.join(".")).
+            # CAVEAT: case-insensitive and only the first 64 chars are significant (values are
+            # lowercased + truncated at index time). No case-sensitive/>64-char exact exists.
+            def translate_exact_filter(filter)
+              key   = filter['key']   || filter[:key]
+              path  = filter['path']  || filter[:path]
+              path  ||= membrane_path_for(key) if membrane_field?(key)
+              value = filter['value'] || filter[:value] || filter['query'] || filter[:query]
+              { operation: 'is_filter', params: { key: key, path: path, value: value }.compact }
+            end
+
+            # Derive the ES nested path from a field key: `plain_text.zXXXX` → `membranes.plain_text`.
+            def membrane_path_for(key)
+              prefix = key.to_s.split('.').first
+              prefix.empty? ? nil : "membranes.#{prefix}"
+            end
+
+            # A register FIELD key carries a `<type>.<hash>` shape (e.g. 'date.zab1bddc3',
+            # 'select_str.z223beb6d'); system/top-level keys (created_at, id, external_id) have
+            # no field-type prefix. Field filters need the nested membranes.<type> path (and,
+            # for options, a field_key), which system filters do not.
+            def membrane_field?(key)
+              key.to_s.include?('.')
+            end
+
+            # v2 text_filter {query, key} → GraphQL match_filter (partial/full-text on key).
+            def translate_text_filter(filter)
+              {
+                operation: 'match_filter',
+                params:    {
+                  key:   filter['key'] || filter[:key],
+                  value: filter['query'] || filter[:query] || filter['value'] || filter[:value]
+                }
+              }
+            end
+
+            # v2 options_filter {chosen, key, mode} → GraphQL.
+            # A register Select FIELD (key like 'select_str.zXXXX') filters via
+            # has_any_filter / doesnt_have_any_filter over its nested path
+            # (membranes.select_str) with field_key 'selected' and the chosen option ids as
+            # `values` (backend NewEp::Es::Filters::Pages::*::HasAnyFilter). A system/top-level
+            # option key (e.g. 'id') keeps one_of_filter / none_of_filter with {key, values}.
+            def translate_options_filter(filter)
+              key     = filter['key'] || filter[:key]
+              values  = Array(filter['chosen'] || filter[:chosen])
+              exclude = exclude_mode?(filter)
+
+              unless membrane_field?(key)
+                op = exclude ? 'none_of_filter' : 'one_of_filter'
+                return { operation: op, params: { key: key, values: values } }
+              end
+
+              op        = exclude ? 'doesnt_have_any_filter' : 'has_any_filter'
+              path      = filter['path']      || filter[:path]      || membrane_path_for(key)
+              field_key = filter['field_key'] || filter[:field_key] || 'selected'
+              { operation: op, params: { key: key, path: path, field_key: field_key, values: values } }
+            end
+
+            # v2 date_filter → GraphQL. A register Date FIELD (key like 'date.zXXXX') filters
+            # via range_date_filter on its nested path (membranes.date); a system/top-level date
+            # (created_at/updated_at) uses date_filter. Both share range params (gte/lte/time_zone)
+            # — range_date_filter additionally carries `path` (backend BaseRangeDateFilter < DateFilter).
+            def translate_date_filter(filter)
+              key   = filter['key'] || filter[:key]
+              field = membrane_field?(key)
+              path  = filter['path'] || filter[:path]
+              path  ||= membrane_path_for(key) if field
+
+              params = { key: key, time_zone: filter['time_zone'] || filter[:time_zone] || 'UTC' }
+              params[:path] = path if path
+              lbound = filter['lbound'] || filter[:lbound]
+              ubound = filter['ubound'] || filter[:ubound]
+              params[:gte] = lbound if lbound
+              params[:lte] = ubound if ubound
+
+              { operation: field ? 'range_date_filter' : 'date_filter', params: params }
+            end
+
+            # "exclude" style modes map to the negative filter operation.
+            def exclude_mode?(filter)
+              mode = (filter['mode'] || filter[:mode]).to_s.downcase
+              %w[none exclude not not_in].include?(mode)
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/compat/page_reference.rb

@@ -0,0 +1,23 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Compat
+        # Returned by Compat::Pages#create — mirrors the v2 reference object.
+        # Scripts access .page_id and .active_stage_id after page creation.
+        class PageReference
+          attr_reader :page_id, :active_stage_id, :page
+
+          def initialize(page)
+            @page            = page
+            @page_id         = page.id
+            @active_stage_id = page.respond_to?(:current_stage_id) ? page.current_stage_id : nil
+          end
+
+          def success?
+            !@page_id.nil?
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,212 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Compat
+        # v2-compatible pages API backed by GraphQL.
+        # Exposes the same interface as ecoportal-api-v2's pages object so that
+        # existing eco-helpers scripts work without modification.
+        #
+        # Key difference from v2:
+        #   - get_new / create is a 2-step GraphQL workflow (build then create)
+        #   - update requires patchVer — must always fetch the page first
+        #   - search is via the GraphQL org search (register_filter + searchConf)
+        class Pages
+          def initialize(client)
+            @client = client
+          end
+
+          # Fetch a page by ID with full data — metadata, stages, sections, data fields.
+          # When stage_id is provided, wraps the result in a StageView that filters
+          # sections and components to that stage only — matching v2 per-stage behaviour.
+          def get(id, stage_id: nil)
+            page = Query::Page.new(@client).query(id: id) do
+              spread :CommonPageUnion
+            end
+            stage_id ? StageView.new(page, stage_id) : page
+          end
+
+          # Build a draft page from a template.
+          # Returns the built PageUnion with server-assigned field IDs and structure.
+          # This is step (a) of the 2-step creation sequence:
+          #   (a) get_new → inspect/modify field values → (b) create
+          def get_new(template_id)
+            mutation = Mutation::Page::BuildFromTemplate.new(@client)
+            payload  = mutation.query(input: { templateId: template_id, showHiddenData: true }) do
+              clientMutationId
+              errors {
+                details
+                fullMessages
+              }
+              item { spread :CommonPageUnion }
+            end
+            # Record the source template on the built draft: the read fragment does not fetch
+            # sourceTemplateId, and a built draft carries a (real) patchVer, so without this
+            # marker the dry-run can neither detect the draft nor recover its templateId — it
+            # would mis-preview a CREATE as an UPDATE. See #new_draft? / #create_body.
+            payload.item&.tap do |draft|
+              draft._compat_source_template_id = template_id if draft.respond_to?(:_compat_source_template_id=)
+            end
+          end
+
+          # Create a page from a filled draft.
+          # Serialises any modified data fields from the draft into dataFields.updates.
+          # Returns a PageReference with .page_id and .active_stage_id.
+          def create(page, from: nil)
+            template_id   = source_template_id(page, from)
+            field_updates = page.respond_to?(:data_fields_updates) ? page.data_fields_updates : []
+
+            # dataFields is a required (non-null) field on CreateFromTemplateInput — always
+            # send it, with an empty updates list when the draft has no field changes.
+            input = { templateId: template_id, showHiddenData: true, dataFields: { updates: field_updates } }
+
+            mutation = Mutation::Page::CreateFromTemplate.new(@client)
+            payload  = mutation.query(input: input)
+            resp     = Response.new(payload)
+            return PageReference.new(payload.item) if resp.success?
+
+            resp
+          end
+
+          # Update a page. Builds the mutation input from the page model diff.
+          # Returns a Compat::Response with .success? and .status.
+          # Returns nil (no-op) if there are no changes.
+          #
+          # When called with no explicit operation (the base eco-helpers update_ooze path does
+          # `pages.update(page)`), any captured submit!/sign_off! intent on the page is folded in
+          # so the SINGLE updatePage carries both the dirty fields and the submit.
+          def update(page, **kargs)
+            kargs = compat_submit_kargs(page) if kargs.empty?
+            input = Input::Page::Update.from_model(page, **kargs)
+            return nil if input.nil?
+
+            payload = Builder::Page.new(@client).update(input: input)
+            Response.new(payload)
+          end
+
+          # Returns the pending changes on a page wrapped under the 'page' key.
+          # v2 equivalent: DocHelpers#get_body(doc, level: 'page') → { 'page' => {...} }.
+          # eco-helpers' OozeBaseCase reads patch_doc(ooze)['page'] (display_patch /
+          # backup_patch! / dirty?), so the body must be wrapped to match the v2 contract —
+          # otherwise ['page'] is always nil → diff never prints and "No changes to update"
+          # misfires.
+          #
+          # CRITICAL: the body is the SAME input #update/#create would send — NOT page.as_update.
+          # On a phased page, as_update only carries page-SCALAR changes; data-field edits
+          # (the bulk of what scripts do — set/select/add-reference) live in data_fields_updates
+          # and are invisible to as_update. Reading as_update here made the dry-run blind to
+          # every field change: toocs coded a Breakdown Agency reference yet the preview showed
+          # "No changes to update", while a real run (made dirty by submit!) DID patch it. Build
+          # the faithful body via the Input serialisers so the dry-run shows exactly what will be
+          # written. nil when there is genuinely nothing to send (and no submit/sign-off pending).
+          def get_body(page)
+            { 'page' => patch_body(page) }
+          end
+
+          # Cursor-paginated iteration over pages matching searchConf.
+          # Yields full PageUnion objects (with patchVer and field IDs).
+          # Required for update workflows — register search returns PreviewPage only.
+          #
+          # Usage:
+          #   api.pages.each(searchConf: SearchConf[:state].is(:active).to_h, first: 50) do |page|
+          #     # page is a Model::Page::Basic or Model::Page::Phased
+          #   end
+          def each(search_conf: {}, first: 50, &block)
+            Query::Pages.new(@client).each(searchConf: search_conf, first: first, &block)
+          end
+
+          private
+
+          # The faithful "what will be sent" body for dry-run display / backup / dirty checks.
+          #   - update path: the full UpdatePageInput (folds any captured submit!/sign_off!),
+          #     which — unlike page.as_update — INCLUDES dataFields.updates (field edits).
+          #   - create path: a never-saved draft has no patchVer; preview the
+          #     CreateFromTemplateInput instead (matches #create's payload).
+          # Returns nil when there is nothing to send and no operation is pending.
+          def patch_body(page)
+            return create_body(page) if new_draft?(page)
+
+            Input::Page::Update.from_model(page, **compat_submit_kargs(page))
+          end
+
+          # Is this a never-saved CREATE draft (vs a persisted page to UPDATE)?
+          # A draft built via get_new/buildPageFromTemplate is marked with
+          # _compat_source_template_id — the authoritative signal, because such a draft DOES
+          # carry a server-assigned patchVer (so patchVer-nil alone misclassifies it as an
+          # update, the cans-upsert dry-run mislabel). patchVer-nil remains a fallback for any
+          # other unsaved model.
+          def new_draft?(page)
+            return true if page.respond_to?(:_compat_source_template_id) && page._compat_source_template_id
+
+            !page.respond_to?(:patchVer) || page.patchVer.nil?
+          end
+
+          # CreateFromTemplateInput preview — mirrors #create's payload (templateId + the
+          # field updates serialised from the draft). Uses the SAME templateId resolution as
+          # the live #create, so the dry-run can't diverge from what gets sent.
+          def create_body(page, from: nil)
+            template_id = source_template_id(page, from)
+            updates     = page.respond_to?(:data_fields_updates) ? page.data_fields_updates : []
+            return nil if updates.empty? && template_id.nil?
+
+            { templateId: template_id, dataFields: { updates: updates } }
+          end
+
+          # Resolve the source template id for a create, most-explicit first:
+          #   1. explicit `from:` (the caller passed it)
+          #   2. the get_new marker `_compat_source_template_id` — the read fragment does NOT
+          #      fetch sourceTemplateId, and eco-helpers' Creatable passes `draft.template_id`
+          #      which is nil on a GraphQL draft, so this marker is what actually carries it
+          #   3. a doc-provided `sourceTemplateId` (if the page happens to have one)
+          # Shared by the live #create AND the dry-run #create_body so they cannot diverge —
+          # they DID: the preview showed the marker's id while #create sent nil, and the server
+          # rejected `templateId: null` on a live cans-upsert create.
+          def source_template_id(page, from = nil)
+            return from if from
+            return page._compat_source_template_id if page.respond_to?(:_compat_source_template_id) && page._compat_source_template_id
+
+            page.respond_to?(:sourceTemplateId) ? page.sourceTemplateId : nil
+          end
+
+          # Translates a page's captured submit!/sign_off! intent (flags set by eco-helpers'
+          # OozeRedirect::FieldPatches) into update kwargs. Returns {} when nothing is pending.
+          # sign_off implies submit (a not-yet-submitted stage submits + approves inline);
+          # submit!(force: true) maps to forcedComplete (admin/superuser: skips required-field check).
+          def compat_submit_kargs(page)
+            if compat_flag(page, :_compat_sign_off?)
+              { submit: true, stage_id: compat_stage_id(page, :_compat_sign_off_stage_id),
+                complete_page_task: { sign_off: true } }
+            elsif compat_flag(page, :_compat_submit?)
+              force = compat_flag(page, :_compat_submit_force?)
+              { submit: true, stage_id: compat_stage_id(page, :_compat_submit_stage_id),
+                complete_page_task: force ? { forced_complete: true } : true }
+            else
+              {}
+            end
+          end
+
+          def compat_flag(page, name)
+            page.respond_to?(name) && page.public_send(name)
+          end
+
+          # Resolve the target stage for a submit/sign-off, most-explicit first:
+          #   1. pinned   — the script passed submit!(stage_id:)/sign_off!(stage_id:)
+          #   2. active   — the stage last viewed via a StageView (the stage the work was
+          #                 done on; set by Compat::StageView). This is the reliable source
+          #                 for the OozeSamples path, where the queued object is the full page.
+          #   3. current  — server-state inference (state=='inprogress'/active==true). Last
+          #                 resort only: it guesses, and on a multi-stage page may name the
+          #                 WRONG stage — so the from_model guard still rejects a nil result.
+          def compat_stage_id(page, pinned_name)
+            pinned = compat_flag(page, pinned_name)
+            return pinned if pinned
+
+            active = compat_flag(page, :_compat_active_stage_id)
+            return active if active
+
+            page.respond_to?(:current_stage_id) ? page.current_stage_id : nil
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/compat/registers.rb

@@ -0,0 +1,84 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Compat
+        # v2-compatible registers API backed by GraphQL register search.
+        # Scripts call: apiv2.registers.search(register_id, options) { |result| ... }
+        #
+        # With a block: yields each PreviewPage result (cursor-paginated).
+        # Without a block (or only_first: true): returns a SearchResults object
+        #   with .total and .total_before_filtering.
+        #
+        # Filter translation:
+        #   v2 date_filter { lbound:, ubound: } → GraphQL date_filter { gte:, lte: }
+        #   v2 tag_filter  { tags:, mode: }     → passed through (same ES backend)
+        #   SearchConf filter objects            → passed through directly
+        class Registers
+          def initialize(client)
+            @client = client
+          end
+
+          # Options:
+          #   sort:             'created_at' | 'updated_at'
+          #   dir:              'asc' | 'desc'
+          #   query:            String (full-text search)
+          #   filters:          Array of filter objects or v2 filter hashes
+          #   batch_size:       Integer (results per request, default 20)
+          #   include_archived: Boolean (default false)
+          #   only_first:       Boolean — return after first page (no block needed)
+          def search(register_id, options = {}, &block)
+            conf  = build_search_conf(options)
+            first = options.fetch(:batch_size, 20)
+            query = Query::RegisterPreviewPages.new(@client)
+
+            args = {
+              registerId:      register_id,
+              searchConf:      conf.to_h,
+              includeArchived: options.fetch(:include_archived, false),
+              first:           first
+            }
+
+            if block || !options[:only_first]
+              # Block mode: yield each result, stop if only_first
+              query.each(**args) do |result|
+                block&.call(result)
+                break if options[:only_first]
+              end
+            else
+              # No-block mode: return SearchResults with .total etc.
+              raw = query.query(**args)
+              SearchResults.new(raw)
+            end
+          end
+
+          private
+
+          def build_search_conf(options)
+            conf = Input::SearchConf.new
+
+            if (sort_key = options[:sort])
+              direction = options.fetch(:dir, 'desc').to_sym
+              conf.sort(sort_key.to_sym, direction)
+            end
+
+            conf.query(options[:query]) if options[:query]
+
+            Array(options[:filters]).compact.each do |filter|
+              conf.filter(translate_filter(filter))
+            end
+
+            conf
+          end
+
+          # Translates a v2-style filter hash to a GraphQL-compatible filter hash.
+          # SearchConf filter objects (respond to to_h and are not Hash) pass through.
+          # v2 date_filter: lbound/ubound → gte/lte
+          # Other v2 types (tag_filter etc.): passed through — same ES backend.
+          def translate_filter(filter)
+            FilterTranslator.to_graphql(filter)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/compat/response.rb

@@ -0,0 +1,35 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Compat
+        # Wraps a GraphQL mutation payload to expose the v2-compatible response interface.
+        # Scripts check .success? and .status after update/create operations.
+        class Response
+          def initialize(payload)
+            @payload = payload
+          end
+
+          def success?
+            @payload.success?
+          end
+
+          def error?
+            @payload.error?
+          end
+
+          def status
+            @payload.error? ? :error : :ok
+          end
+
+          def body
+            @payload.error_doc
+          end
+
+          def item
+            @payload.item
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/compat/search_results.rb

@@ -0,0 +1,33 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Compat
+        # Wraps a GraphQL connection object to expose the v2-compatible search
+        # result interface. eco-helpers scripts access:
+        #   search_results.total                  — filtered count
+        #   search_results.total_before_filtering — pre-filter count (approximated)
+        #   (also Enumerable for iteration)
+        class SearchResults
+          include Enumerable
+
+          attr_reader :total, :total_before_filtering
+
+          def initialize(connection)
+            @total                  = connection.totalCount
+            # GraphQL does not expose a pre-filter count — use the same value.
+            @total_before_filtering = connection.totalCount
+            @nodes                  = connection.nodes
+          end
+
+          def each(&block)
+            @nodes.each(&block)
+          end
+
+          def empty?
+            @nodes.empty?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/compat/stage_collection.rb

@@ -0,0 +1,70 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Compat
+        # Wraps the stages array from a PhasedPage to expose the v2-compatible
+        # access patterns eco-helpers scripts rely on.
+        #
+        # Accepts either an array of Base::Page::Phased::Stage objects (the normal
+        # path via embeds_many) or raw stage hash docs (for direct construction in
+        # specs and legacy callers).
+        #
+        # v2 patterns supported:
+        #   page.stages[id_or_name]       — find stage by ID or name
+        #   page.stages.get_by_name(name) — find stage by name
+        #   page.stages.ordered           — stages sorted by ordering
+        #   page.stages.ordered.map(&:id) — map sorted stages to IDs
+        #   page.stages.any?              — whether the page has stages
+        #   page.stages.each { |s| ... }  — iterate stages
+        class StageCollection
+          include Enumerable
+
+          def initialize(stages_array)
+            @stages = Array(stages_array).map { |s| coerce_stage(s) }
+          end
+
+          # Find a stage by ID or name (hash-style access matching v2 pattern).
+          def [](id_or_name)
+            return nil unless id_or_name
+
+            @stages.find { |s| s.id == id_or_name.to_s || s.name == id_or_name.to_s }
+          end
+
+          # Find a stage by name (explicit v2 method).
+          def get_by_name(name)
+            return nil unless name
+
+            @stages.find { |s| s.name == name.to_s }
+          end
+
+          # Stages sorted by ordering (ascending).
+          def ordered
+            @stages.sort_by { |s| s.ordering.to_i }
+          end
+
+          def each(&block)
+            @stages.each(&block)
+          end
+
+          def empty?
+            @stages.empty?
+          end
+
+          def length
+            @stages.length
+          end
+
+          alias_method :size, :length
+
+          private
+
+          # Accept Base::Page::Phased::Stage model objects (from embeds_many) directly.
+          # Wrap raw hashes in a Stage model for backwards-compatible direct construction.
+          def coerce_stage(stage)
+            stage.is_a?(Hash) ? Base::Page::Phased::Stage.new(stage) : stage
+          end
+        end
+      end
+    end
+  end
+end