ecoportal-api-graphql 2.0.0 → 3.0.0

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

@@ -1,3 +1,5 @@
+require 'securerandom'
+
 module Ecoportal
   module API
     class GraphQL
@@ -15,7 +17,19 @@ module Ecoportal
               # patchVer is always included when present (required for concurrency control).
               #
               # Options:
-              #   stage_id:           ID      — target a specific stage (required for stage submit/close-out)
+              #   stage_id:           ID      — target a specific stage. Optional even for a
+              #                                 PHASED page: when omitted, it is DERIVED from
+              #                                 the owning stage of the data fields being
+              #                                 updated in this same call (see #derive_stage_id)
+              #                                 — a PHASED `updatePage` has been observed to 500
+              #                                 without a `stageId` on an Image Gallery / File
+              #                                 field write (live-diagnosed, page
+              #                                 a customer's phased page), and sending it
+              #                                 whenever derivable is always safe even where it
+              #                                 turns out not to be strictly required. Pass this
+              #                                 explicitly to override the derivation, or to
+              #                                 target a stage submit/close-out when no field on
+              #                                 that stage is dirty yet.
               #   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
@@ -37,17 +51,31 @@ module Ecoportal
               #   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
+              #   client_mutation_id: String  — correlation id for tracing this call in logs /
+              #                                 the server's own activity trail. Defaults to a
+              #                                 fresh `SecureRandom.uuid` PER CALL — every
+              #                                 mutation this input builds is now traceable by
+              #                                 default, not just the ones a caller remembered
+              #                                 to tag. Pass an explicit id to correlate several
+              #                                 calls under one value, or `''`/`nil` to omit the
+              #                                 key entirely. NOTE: this is for CORRELATION only
+              #                                 — the server does NOT dedupe mutations on it, so
+              #                                 it buys no idempotency; a retried call with the
+              #                                 same clientMutationId still re-applies the write.
+              #                                 Any idempotency has to be client-side (e.g. this
+              #                                 gem's own dirty-tracking not re-sending a field
+              #                                 that already round-tripped).
               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)
+                             location_ids: nil, client_mutation_id: SecureRandom.uuid, **_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)
+                stage_id  ||= derive_stage_id(model, data_fields)
+                require_stage!(stage_id, submit, task)
 
                 no_changes = page_input.empty? && data_fields.empty?
                 no_op      = publish.nil? && submit.nil? && stage_id.nil? && task.nil?
@@ -66,13 +94,88 @@ module Ecoportal
 
               private
 
+              # Derives the default `stageId` for a PHASED page update from the STAGE(S) that
+              # own the data fields being changed in THIS call (updates/additions/deletions).
+              #
+              # Platform fact, live-diagnosed against a customer's phased page (the
+              # org's own service account): `updatePage` on a PHASED page 500s when `stageId`
+              # is missing on an Image Gallery / File field write. The live-verified
+              # a customer collection's integration guide (§5) documents a related but
+              # narrower nuance — omitting `stageId` is judged against the ROOT page's
+              # `PagePolicy#update?` rather than being an unconditional failure, so it is
+              # "optional but preferable" for an account whose edit right arrives through
+              # page-level administration rather than a stage. Sending it whenever it CAN be
+              # derived is correct either way: never wrong for an account that did not need
+              # it, and fixes the account/field combination that does. A `BasicPage` has no
+              # `#stages` at all — returns `nil` (stageId OMITTED from the input entirely,
+              # never sent as an explicit `null`; `build_input`'s nil-guard already drops a
+              # nil operation key).
+              #
+              # Multi-stage calls: if the fields being updated in this ONE call span MORE
+              # THAN ONE stage, this raises rather than guessing which stage's id to send (a
+              # single `updatePage` input can only carry one `stageId`). The caller must split
+              # such a change into one `from_model`/mutation call PER STAGE, in stage order,
+              # threading the model's (fresh, server-returned) `patchVer` from each response
+              # into the next call — the same pattern the org-side reference implementation
+              # (a downstream script repo's `-file-attach` case, `persist_file_updates`/
+              # `persist_gallery`) already uses at the call-site level, re-fetching the page
+              # between groups. Pass `stage_id:` explicitly to bypass this derivation for any
+              # other need (e.g. targeting a stage submit with no dirty field on it yet).
+              def derive_stage_id(model, data_fields)
+                return nil unless model.respond_to?(:stages)
+
+                field_ids = changed_field_ids(data_fields)
+                return nil if field_ids.empty?
+
+                owning_stage_ids = Array(model.stages).filter_map do |stage|
+                  stage.id if Array(stage.stage_field_ids).intersect?(field_ids)
+                end.uniq
+
+                case owning_stage_ids.size
+                when 0 then nil
+                when 1 then owning_stage_ids.first
+                else
+                  raise ArgumentError,
+                        "This update's data fields span #{owning_stage_ids.size} different " \
+                        "stages (#{owning_stage_ids.join(', ')}) — a single updatePage call " \
+                        'can only target one stageId. Split into one from_model/mutation call ' \
+                        "per stage, in stage order, re-fetching the page (fresh patchVer) " \
+                        'between calls, or pass stage_id: explicitly to target just one.'
+                end
+              end
+
+              # Every field id touched by this call's dataFields command (updates, additions,
+              # deletions) — the raw DataFieldInput hashes are `{ typeKey: { id:, ... } }`, so
+              # `id` is read generically off the first (only) value, regardless of field type.
+              def changed_field_ids(data_fields)
+                ids = Array(data_fields[:updates]).filter_map { |cmd| field_id_from_command(cmd) }
+                ids.concat(Array(data_fields[:additions]).filter_map { |cmd| field_id_from_command(cmd) })
+                ids.concat(Array(data_fields[:deletions]))
+                ids.compact.uniq
+              end
+
+              def field_id_from_command(command)
+                return nil unless command.is_a?(Hash)
+
+                inner = command.values.first
+                inner.is_a?(Hash) ? inner[:id] : nil
+              end
+
               # 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.
+              # some customer submissions go out stage-less).
+              #
+              # CORRECTED comment (this used to say "a plain field update ... needs no stage
+              # and is unaffected" — wrong for a PHASED page: `updatePage` 500s there without
+              # a `stageId` on ANY write, plain field update included; see `#derive_stage_id`,
+              # which is called BEFORE this guard and already fills it in from the fields
+              # being changed whenever it can). This guard now only fires for the case
+              # `#derive_stage_id` genuinely cannot resolve — no dirty field to derive from
+              # (a stage-submit-only call) or a `BasicPage` (no stages at all, where a submit
+              # makes no sense anyway) — same platform invariant, just reached less often now.
               def require_stage!(stage_id, submit, task)
                 return unless stage_id.nil?
                 return unless submit || task

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

@@ -1,26 +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'
+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

@@ -1,18 +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
+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

@@ -1,16 +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
+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

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

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

@@ -1,14 +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'
+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

@@ -1,18 +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
+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

@@ -1,15 +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
+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

@@ -1,13 +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'
+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.rb

@@ -1,13 +1,13 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Input
-        class Search < Logic::BaseModel
-          embeds_many :filters, enum_class: "Ecoportal::API::GraphQL::Input::SearchFilter"
-          passthrough :query
-          embeds_many :sorters, enum_class: "Ecoportal::API::GraphQL::Input::SearchSorter"
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Input
+        class Search < Logic::BaseModel
+          embeds_many :filters, enum_class: "Ecoportal::API::GraphQL::Input::SearchFilter"
+          passthrough :query
+          embeds_many :sorters, enum_class: "Ecoportal::API::GraphQL::Input::SearchSorter"
+        end
+      end
+    end
+  end
+end