ecoportal-api-graphql 2.2.0 → 3.0.0

data/README.gem.md

@@ -0,0 +1,53 @@
+# ecoportal-api-graphql
+
+A Ruby client for the ecoPortal GraphQL API: typed models for pages, templates, data fields and
+registers, query and mutation helpers, and the workflow command bus for granular template edits.
+
+This is the README shipped inside the published gem. The source repository keeps its own
+developer README.
+
+## Install
+
+```ruby
+gem 'ecoportal-api-graphql', require: %w[ecoportal/api-graphql]
+```
+
+```
+$ bundle
+# or: $ gem install ecoportal-api-graphql
+```
+
+## Requirements
+
+| | version |
+|---|---|
+| Ruby | `>= 3.2.2` |
+| `ecoportal-api` | `~> 0.10, >= 0.10.17` |
+| `ecoportal-api-v2` | `~> 3.3, >= 3.3.5` |
+| `graphlient` | `>= 0.9.0, < 0.10` |
+
+## Example: load and edit a template
+
+```ruby
+api      = Ecoportal::API::GraphQL.new(email: ..., pass: ..., org_id: ...)
+template = Ecoportal::API::GraphQL::Model::Template.load(api, id: template_page_id)
+template.fields.each { |f| f.label = "#{f.label} (reviewed)" }
+template.save!(api, simulate: false)   # simulate: true is the default -- inspect first
+```
+
+`save!` simulates by default: it reports the commands it would send without writing anything.
+Pass `simulate: false` to apply them.
+
+## Optional extensions
+
+Some capabilities are distributed separately as optional extensions and are not part of this
+gem. The gem works fully without them; when an extension is installed, it is picked up
+automatically.
+
+## Changes
+
+See `CHANGELOG.md`, shipped alongside this file.
+
+## Licence
+
+MIT -- see `LICENSE`.

data/lib/ecoportal/api/common/graphql/auth_service.rb

@@ -25,7 +25,7 @@ module Ecoportal
             def session_token_renewed(host: server, refresh_token: nil)
               unless refresh_token
                 return unless (body = session_token_data(host: host))
-                return unless (refresh_token = body['resfresh_token'])
+                return unless (refresh_token = body['refresh_token'])
               end
 
               session_refresh_token_data(

data/lib/ecoportal/api/common/graphql/client.rb

@@ -56,12 +56,50 @@ module Ecoportal
             @org_id || fetch_env_required('ORGANIZATION_ID')
           end
 
+          # Graphlient/graphql-client build the client-side schema from the server's raw
+          # introspection JSON (GraphQL::Schema.from_introspection -> GraphQL::Schema::Loader).
+          # That loader defines one GraphQL::Schema::InputObject subclass per INPUT_OBJECT type,
+          # but it never calls `has_no_arguments(true)` on the ones whose `inputFields` came back
+          # empty. graphql-ruby then warns (and, in a future version, raises) the first time
+          # anything asks such a type for its arguments -- which happens whenever this schema is
+          # re-serialized (e.g. `schema.to_json`/`to_definition`, as the `-graphql-schema` use
+          # case in eco-helpers does). The live server never emits this warning because its own
+          # schema classes are defined directly in Ruby with real argument lists (or with
+          # `has_no_arguments(true)` already set) -- it is only the client-side schema, rebuilt
+          # purely from introspection data, that loses that annotation.
+          #
+          # Patching the built classes here (rather than pre-processing the introspection JSON)
+          # keeps the schema's shape untouched and uses graphql-ruby's own documented escape
+          # hatch for this exact situation.
+          def schema
+            mark_argumentless_input_objects!(super)
+          end
+
           private
 
           def url
             base_url = Ecoportal::API::Common::GraphQL::HttpClient.base_url(host)
             "#{base_url}/api/#{org_id}/#{ENDPOINT_PATH}"
           end
+
+          def mark_argumentless_input_objects!(loaded_schema)
+            return loaded_schema if @argumentless_input_objects_marked
+
+            graphql_schema_types(loaded_schema).each_value do |type|
+              next unless type.respond_to?(:kind) && type.kind.input_object?
+              next unless type.respond_to?(:has_no_arguments) && type.respond_to?(:any_arguments?)
+
+              type.has_no_arguments(true) unless type.any_arguments?
+            end
+            @argumentless_input_objects_marked = true
+
+            loaded_schema
+          end
+
+          def graphql_schema_types(loaded_schema)
+            target = loaded_schema.respond_to?(:graphql_schema) ? loaded_schema.graphql_schema : loaded_schema
+            target.types
+          end
         end
       end
     end

data/lib/ecoportal/api/common/graphql/http_client.rb

@@ -96,9 +96,11 @@ module Ecoportal
             end
           end
 
-          ENDPOINT_PATH = 'external/graphql'.freeze
-          READ_TIMEOUT  = 90
-          WRITE_TIMEOUT = 90
+          ENDPOINT_PATH      = 'external/graphql'.freeze
+          CONNECT_TIMEOUT    = 30
+          READ_TIMEOUT       = 90
+          WRITE_TIMEOUT      = 90
+          KEEP_ALIVE_TIMEOUT = 5
 
           attr_reader :host, :version
 
@@ -137,6 +139,36 @@ module Ecoportal
 
           # Creates a HTTP object adding the `X-ApiKey` or `X-ECOPORTAL-API-KEY` param to the header, depending on the API version.
           # @note It configures HTTP so it only allows body data in json format.
+          # @note This is the ONLY place in the gem's dependency chain that talks to the
+          #   server via http.rb (`require 'http'`, pulled in by `Ecoportal::API::Common::Client`
+          #   from the `ecoportal-api` gem) -- every live GraphQL query goes through `#execute`
+          #   below, called from `Logic::BaseQuery#graphql_query` via `client.http_client.execute`,
+          #   and `AuthService#auth_http_client` (`version: 'http'`) reuses this same
+          #   `base_request` for the OAuth token POST. `Common::GraphQL::Client` (graphlient) is a
+          #   separate, unrelated path: it never reaches http.rb at all.
+          #
+          #   Without an explicit `connect:`, http.rb's `HTTP::Timeout::PerOperation` falls back
+          #   to its own default of 0.25s for CONNECT even though read/write were already given
+          #   explicitly (per_operation.rb: `options.fetch(:connect_timeout, CONNECT_TIMEOUT)`,
+          #   `CONNECT_TIMEOUT = 0.25`). `connect_ssl` (`http/timeout/per_operation.rb`) uses
+          #   that same `@connect_timeout` for the TLS handshake via `rescue_readable`/
+          #   `rescue_writable` (`http/timeout/null.rb`) -- whose error text is unconditionally
+          #   "Read timed out after #{@read_timeout} seconds", so a slow TLS handshake on the EU
+          #   instance surfaced as `HTTP::TimeoutError: Read timed out after 0.25 seconds`
+          #   even though `@read_timeout` itself was correctly 90 the whole time. Live-confirmed
+          #   2026-09-08 via backtrace: `connect_ssl` -> `start_tls` (`http/connection.rb`) ->
+          #   `Common::Client#post` -> `AuthService#session_token_data` ->
+          #   `Common::GraphQL::Client#initialize`. Read/write were never the problem; only
+          #   connect was missing.
+          # @note The client is made PERSISTENT (`HTTP.persistent`) to `base_url`, not a
+          #   plain one-shot client. Confirmed live 2026-09-08: eu.live.ecoportal.com
+          #   closes an HTTP/1.1 request carrying `Connection: close` -- what a
+          #   non-persistent http.rb client always sends -- without ever responding. A
+          #   persistent client sends `Connection: keep-alive` and reuses the TCP/TLS
+          #   connection instead, which the SAME Ruby stack proved fine against EU. This
+          #   also matches Cloudflare keep-alive hygiene; Sydney is fine either way. One
+          #   `HttpClient` is bound to one `host`, so `HTTP::StateError` (raised only on a
+          #   cross-origin request against a persistent client) cannot occur here.
           # @return [HTTP] HTTP object.
           def base_request
             @base_request ||=
@@ -151,9 +183,10 @@ module Ecoportal
                 HTTP.headers('Authorization' => "Bearer #{session_token(host: host)}")
               end.then do |request|
                 request ||= HTTP
-                request.accept(:json).timeout(
-                  read:  READ_TIMEOUT,
-                  write: WRITE_TIMEOUT
+                request.persistent(base_url, timeout: KEEP_ALIVE_TIMEOUT).accept(:json).timeout(
+                  connect: CONNECT_TIMEOUT,
+                  read:    READ_TIMEOUT,
+                  write:   WRITE_TIMEOUT
                 )
               end
           end

data/lib/ecoportal/api/common/graphql/model/diffable/leaf_diff_service.rb

@@ -15,7 +15,7 @@ module Ecoportal::API::Common::GraphQL::Model::Diffable
   # `CollectionModel` — neither is a `GraphQL::Model`, so the re-add never happens and
   # the array change becomes **invisible to `as_update`** (scalar `passthrough` fields
   # are unaffected). This is the systemic "array/leaf fields don't diff" root cause
-  # (see `.ai-assistance/code/model_input_mapping/SYNTHESIS.md` §3.1).
+  # (see the repo's internal docs §3.1).
   #
   # This service fixes it for leaf models by:
   #   1. keeping cascaded keys in the flat classic diff (`doc_with_non_cascaded_attributes`

data/lib/ecoportal/api/graphql/base/page/data_field/collection.rb

@@ -31,7 +31,7 @@ module Ecoportal::API::GraphQL::Base::Page
 
       # Find first field matching label (case-insensitive). Optional type: restricts to
       # that field type first (v2 compat: components.get_by_name(name, type:) — used by
-      # the farmers cutover use case which calls it directly, not via OozeRedirect).
+      # a customer cutover use case which calls it directly, not via OozeRedirect).
       def get_by_name(label, type: nil)
         pool = type ? get_by_type(type) : @fields
         pool.find { |f| f.label.to_s.downcase == label.to_s.downcase }

data/lib/ecoportal/api/graphql/base/page/data_field/image_gallery.rb

@@ -1,26 +1,174 @@
 module Ecoportal::API::GraphQL::Base::Page
   class DataField
     # Image gallery field.
-    # ★ WRITE PATH BROKEN (schema-invalid, live-verified 2026-08): `ImageGalleryInput` has no
-    # `fileContainerIds` — it takes `images: [ImageInput]`, attaching via `sourceId`, which is
-    # an `Enzyme::ImageReference::TempImage` (a DIFFERENT upload pipeline than file containers).
-    # Fixing this needs its own design — see the DataField shape-asymmetry review project.
-    # The reader is equally stale: live responses carry `images`, not `fileContainers`.
+    #
+    # ★ FIXED 2026-09 (previously broken -- see `spec/.../image_gallery_characterization_spec.rb`
+    # git history for the prior "WRITE PATH BROKEN" documentation of this defect). Confirmed
+    # against the LIVE ecoPortal server source (read-only, /tmp/work/ecoPortal) that a
+    # gallery image is genuinely NOT a `FileContainer`:
+    #   * `app/graphql/types/fill_in_page/inputs/data_fields/image_gallery_input.rb:5-11` --
+    #     `ImageGalleryInput` has NO `fileContainerIds`; it takes `images: [ImageInput]`.
+    #   * `.../image_galleries/image_input.rb:6-15` -- `ImageInput` takes `sourceId` (a
+    #     `TempImage` id, from the SEPARATE `uploadImage` mutation -- see
+    #     `Mutation::Image::Upload` / `FileUpload::Client#upload_image`), never
+    #     `fileContainerId`.
+    #   * `app/services/new_ep/pages/assign_attributes_service.rb:152-176`
+    #     (`set_image_gallery_attrs`) -- full-replace-by-omission, the SAME trap as
+    #     `FileField`: any current image whose `id` is not echoed back in the write is
+    #     destroyed (`format_removed_ids`).
+    #   * `app/graphql/types/pages/data_fields/image_galleries/image_type.rb` -- `fileName`/
+    #     `fileSize` are NULLABLE even on a successful upload -- a documented upstream bug
+    #     ("images are successfully uploaded but the file name and size are not set in the
+    #     database", per the live schema's own field comment). Any comparison built on these
+    #     two fields must treat a nil on either side as "not a confident match", never a
+    #     positive one.
+    #
+    # READ: `images { id weight downloadUrl caption fileName fileSize uploadId }`
+    # (`imageGalleryField` fragment, `fragment/pages/common_page_union.rb` -- `id`/`weight`
+    # were ADDED alongside this fix; the fragment previously omitted both, which is why no
+    # correct reader was possible before now).
+    #
+    # WRITE: `ImageGalleryInput { id images: [ImageInput] }`; `ImageInput { id weight
+    # sourceId caption fileName sensitiveContent inaccurateDescription
+    # inaccurateExtractedText }`. `as_input` sends every KEPT image back with its FULL
+    # `ImageInput` field set (`#kept_image_input`) -- NOT a bare `{id:}` -- and every NEW one
+    # as `{sourceId:, weight:, fileName:}` -- see `#add_source_images`, the merge-safe writer
+    # (mirrors `FileField#file_container_ids=`'s kept-vs-new split).
+    #
+    # ★ CORRECTED 2026-09 (pre-release, MR !278 unreleased): the bare `{id:}` echo for a kept
+    # image, above, silently dropped every OTHER attribute on that image on the NEXT write
+    # server-side -- `assign_attributes_service.rb#set_image_gallery_attrs` applies `images`
+    # as a FULL REPLACE (see the class header above), so a bare `{id:}` is indistinguishable
+    # from "clear caption/sensitiveContent/etc back to their defaults" for that image, not
+    # "leave it as it is". Matches the org-side reference implementation (a downstream script repo,
+    # commit 482db9c) and the live schema's own `ImageInput` argument list -- the shipped
+    # `ep-api-collections` sample only demonstrates the NEW-image shape (no existing images to
+    # keep), so this shape is pinned to server source + that proven reference, not a captured
+    # kept-echo payload (see EVIDENCE PRECEDENCE note on `#kept_image_input`).
+    #
+    # `images` is deliberately a PLAIN doc reader, not `passarray` -- same reasoning as
+    # `FileField#items` (see that class's header): materialising an ArrayModel writes
+    # `images: []` into the doc of a field read without `$content`, and a phantom-dirty empty
+    # `images` here doesn't always no-op (only the empty-vs-missing-key case is neutralised
+    # by `Diffable::LeafDiffService`'s array-diff fix, MR !106) -- it can still synthesise an
+    # unwanted write for a non-empty phantom read. A plain reader has no such hazard.
     class ImageGallery < DataField
-      passarray :fileContainers # each: { id:, fileName:, url:, ... }
+      # each: { 'id' =>, 'weight' =>, 'downloadUrl' =>, 'caption' =>, 'fileName' =>,
+      #         'fileSize' =>, 'uploadId' => }
+      def images
+        Array(doc['images'])
+      end
+
+      # @return [Array<String>] every image's own item id (its server-assigned id, NOT the
+      #   `uploadId`/`TempImage` id it was created from).
+      def image_ids
+        images.filter_map { |image| image['id'] if image.is_a?(Hash) }
+      end
 
-      def file_container_ids
-        Array(fileContainers).map { |c| c.is_a?(Hash) ? c['id'] : c }.compact
+      # @return [Integer] one past the highest `weight` currently on the field (`0` if the
+      #   field is empty). There is no server-side auto-increment for `weight` (a plain
+      #   Integer field, default `0`) -- callers that want sequential ordering for several new
+      #   images in one write should still call this ONCE and increment locally
+      #   (`#add_source_images` already does).
+      def next_weight
+        return 0 if images.empty?
+
+        images.map { |image| image.is_a?(Hash) ? image['weight'].to_i : 0 }.max + 1
       end
 
-      def file_container_ids=(ids)
-        doc['fileContainers'] = Array(ids).map { |id_val| { 'id' => id_val } }
+      # Merge-safe write: adds NEW images (each referenced by `source_id`, the `TempImage`
+      # id from `FileUpload::Client#upload_image`) while KEEPING every image already loaded
+      # on this field. `images` on `ImageGalleryInput` is a FULL REPLACE server-side -- any
+      # current image whose `id` is not echoed back is destroyed -- so this always keeps
+      # every currently-loaded image's FULL doc entry (untouched -- `#images_input` picks the
+      # `ImageInput`-writable subset out of it later; kept HERE in full so that subset still
+      # has every field to read, rather than collapsing to a bare `{'id' => ...}` that would
+      # throw the other attributes away before `#as_input` ever runs) and appends the new
+      # ones after it, at sequential weights starting at `#next_weight`. Marks the field dirty
+      # (same underlying mechanism as `FileField#file_container_ids=` -- a raw `doc` mutation,
+      # picked up by the generic diff regardless of the `passarray`/plain-reader choice above).
+      #
+      # @param sources [Array<Hash>] one entry per NEW image. Accepts either key style:
+      #   `{source_id:, file_name:}` or `{'sourceId' =>, 'fileName' =>}`. `weight` is assigned
+      #   here, not read from the input -- the caller does not need to compute it.
+      # @return [Array<Hash>] the full resulting `images` doc (kept + added), same value now
+      #   readable via `#images`.
+      def add_source_images(sources)
+        kept  = images.select { |image| image.is_a?(Hash) && image['id'] }
+        start = next_weight
+        added = Array(sources).each_with_index.map do |source, index|
+          {
+            'sourceId' => fetch_key(source, :source_id, 'sourceId'),
+            'weight'   => start + index,
+            'fileName' => fetch_key(source, :file_name, 'fileName')
+          }.compact
+        end
+        doc['images'] = kept + added
       end
 
       def as_input
         return nil unless dirty?
 
-        { imageGallery: { id: id, fileContainerIds: file_container_ids } }
+        {imageGallery: {id: id, images: images_input}}
+      end
+
+      private
+
+      # `images` holds the write shape for a NEW item (`{'sourceId' =>, 'weight' =>,
+      # 'fileName' =>}`, from `#add_source_images`) as-is, and the FULL read doc for a KEPT
+      # item (untouched since the last read) -- `#kept_image_input` narrows the latter down to
+      # exactly what `ImageInput` accepts.
+      def images_input
+        images.filter_map do |image|
+          next unless image.is_a?(Hash)
+
+          if image['sourceId']
+            {sourceId: image['sourceId'], weight: image['weight'], fileName: image['fileName']}.compact
+          elsif image['id']
+            kept_image_input(image)
+          end
+        end
+      end
+
+      # Full-field echo for a KEPT (currently-existing, untouched) image -- REQUIRED because
+      # `ImageGalleryInput.images` is a full replace server-side (`assign_attributes_service.
+      # rb#set_image_gallery_attrs` -> `format_removed_ids`): a bare `{id:}` is read by the
+      # server as "clear every other attribute", not "leave this image as it is".
+      #
+      # EVIDENCE PRECEDENCE (shipped sample -> server source -> gem model): the shipped
+      # a customer collection's "Attach Image to Gallery Field"
+      # sample only demonstrates a BRAND-NEW image (`sourceId`/`weight`/`fileName`, no
+      # existing images on the field to keep) -- it does not capture a kept-image echo. This
+      # shape is therefore pinned to the next level down: the live schema's own `ImageInput`
+      # argument list (`app/graphql/types/fill_in_page/inputs/data_fields/image_galleries/
+      # image_input.rb`: `id weight sourceId caption fileName sensitiveContent
+      # inaccurateDescription inaccurateExtractedText`) plus the org-side reference
+      # implementation already built against those same server facts and merged
+      # (a downstream script repo, commit 482db9c, `#kept_gallery_image_input`) -- not an inference
+      # from this gem's own prior (incorrect) behaviour.
+      #
+      # `sourceId` here is read back from the CURRENT read's `uploadId` -- the read-side name
+      # for the same identifier (a customer collection's integration guide
+      # section 7: "the id changes name between reading and writing"). Every key is sent as
+      # read (never `.compact`-ed away) -- this is an ECHO of the field's current state, so a
+      # nil here means "this attribute is genuinely unset", which is exactly what should be
+      # (re-)written to preserve it unset, not omitted and misread as "clear it".
+      def kept_image_input(image)
+        {
+          id:                      image['id'],
+          sourceId:                image['uploadId'],
+          weight:                  image['weight'],
+          caption:                 image['caption'],
+          fileName:                image['fileName'],
+          sensitiveContent:        image['sensitiveContent'],
+          inaccurateDescription:   image['inaccurateDescription'],
+          inaccurateExtractedText: image['inaccurateExtractedText']
+        }
+      end
+
+      def fetch_key(hash, *keys)
+        keys.each { |k| return hash[k] if hash.is_a?(Hash) && hash.key?(k) }
+        nil
       end
     end
   end

data/lib/ecoportal/api/graphql/base/temp_image.rb

@@ -0,0 +1,28 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        # The upload-staging model behind `uploadImage` -- explicitly NOT a `FileContainer`.
+        # Verified against the live ecoPortal server schema (read-only,
+        # /tmp/work/ecoPortal): `Types::Files::TempImageType` (`app/graphql/types/files/
+        # temp_image_type.rb`) declares exactly `id s3Key error complete`, backed by
+        # `Enzyme::ImageReference::TempImage` (`app/models/enzyme/image_reference.rb`), a
+        # separate upload-staging Mongoid model from `FileContainer`.
+        #
+        # `complete` starts `false` immediately after `uploadImage` returns and is filled in
+        # later by background processing. A consumer does NOT need to wait for it: confirmed
+        # server-side (`app/services/new_ep/pages/assign_attributes_service.rb`'s
+        # `set_image_gallery_attrs`) that attaching a `TempImage` to an Image Gallery field via
+        # `ImageInput.sourceId` succeeds whether or not `complete?`/`error?` is true yet -- an
+        # incomplete image is accepted and filled in on the record later.
+        class TempImage < Logic::BaseModel
+          read_only!
+
+          passkey     :id
+          passthrough :s3Key, :error
+          passboolean :complete
+        end
+      end
+    end
+  end
+end

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

@@ -15,6 +15,7 @@ require_relative 'base/location_structure'
 require_relative 'base/person_member'
 require_relative 'base/file_attachment'
 require_relative 'base/file_container'
+require_relative 'base/temp_image'
 require_relative 'base/field'
 require_relative 'base/page'
 require_relative 'base/resource'

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

@@ -9,12 +9,17 @@ module Ecoportal
             @client = client
           end
 
-          def create(commands:, &block)
-            createMutation.query(commands: commands, &block)
+          # @param register_id [String, nil] bind the new template to this register. Optional in
+          #   the schema, but in practice REQUIRED for the create to be authorized at all — see
+          #   the WHY in {Mutation::Template::Create}. Omitted when nil.
+          def create(commands:, register_id: nil, &block)
+            createMutation.query(commands: commands, register_id: register_id, &block)
           end
 
-          def update(model, commands:, patch_ver: model.patchVer, &block)
-            updateMutation.query(id: model.id, patch_ver: patch_ver, commands: commands, &block)
+          def update(model, commands:, patch_ver: model.patchVer, client_mutation_id: nil, &block)
+            kwargs = { id: model.id, patch_ver: patch_ver, commands: commands }
+            kwargs[:client_mutation_id] = client_mutation_id unless client_mutation_id.nil?
+            updateMutation.query(**kwargs, &block)
           end
 
           def publish(id:, &block)

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

@@ -18,7 +18,7 @@ module Ecoportal
         #   tag_filter      passed through (same ES backend, same format)
         #   register_filter passed through
         #   and_filter / or_filter  passed through
-        # Operation/param shapes per .ai-assistance/code/search_filters.md.
+        # Operation/param shapes per the repo's internal docs
         class FilterTranslator
           class << self
             def to_graphql(filter)