ecoportal-api-graphql 2.2.1 → 3.0.0

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

@@ -5,12 +5,45 @@ module Ecoportal
         # Concrete counterparts of `Base::Template::*` (see there for the page-vs-Template
         # type asymmetry). `Information` and `RelatedPages` need no extra wiring — both are
         # flat, read-only models; `ChangeLogEntry` adds the `owner` embed.
+        #
+        # This module ALSO carries the mutable, editable template model
+        # (the repo's internal docs) — "the three
+        # lines":
+        #
+        #   template = Ecoportal::API::GraphQL::Model::Template.load(api, id: page_id)
+        #   template.fields.each { |f| f.label = "#{f.label} (reviewed)" }
+        #   template.save!(api)
+        #
+        # `Instance` is the class `.load` returns; `.load` is the ergonomic module-level entry
+        # point so callers never have to spell `Instance` themselves.
         module Template
           class Information < Base::Template::Information; end
 
           class RelatedPages < Base::Template::RelatedPages; end
 
           require_relative 'template/change_log_entry'
+
+          require_relative 'template/node'
+          require_relative 'template/option'
+          require_relative 'template/binding'
+          require_relative 'template/helper'
+          require_relative 'template/field'
+          require_relative 'template/section'
+          require_relative 'template/force'
+          require_relative 'template/stage'
+          require_relative 'template/read'
+          require_relative 'template/command_synthesis'
+          require_relative 'template/command_normalizer'
+          require_relative 'template/command_grouper'
+          require_relative 'template/staged_executor'
+          require_relative 'template/instance'
+
+          # @param client [Ecoportal::API::GraphQL] the top-level gem client.
+          # @param id [String] the template's page id.
+          # @return [Instance]
+          def self.load(client, id:)
+            Instance.load(client, id: id)
+          end
         end
       end
     end

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

@@ -14,6 +14,7 @@ require_relative 'model/user'
 require_relative 'model/person_member'
 require_relative 'model/file_attachment'
 require_relative 'model/file_container'
+require_relative 'model/temp_image'
 require_relative 'model/field'
 require_relative 'model/page'
 require_relative 'model/page_union'

data/lib/ecoportal/api/graphql/mutation/file_container/upload.rb

@@ -31,16 +31,23 @@ module Ecoportal
             # @param other_tags [Array<String>, nil] tags — the only supported way to tag a
             #   container (there is no separate tag mutation; confirmed 2026-07-30).
             # @param container_id [String, nil] add a new VERSION to an existing container.
-            def query(filename:, filetype:, filesize:, url:, location_ids: nil, other_tags: nil, container_id: nil, **kargs, &block)
+            # @param client_mutation_id [String, nil] optional correlation/tracing id --
+            #   `UploadInput`'s own `clientMutationId` (confirmed in this file's own header,
+            #   `UploadInput { clientMutationId filename filetype filesize locationIds
+            #   otherTags url containerId }`). Omitted entirely when not given, so every
+            #   existing caller's input shape is byte-identical to before.
+            def query(filename:, filetype:, filesize:, url:, location_ids: nil, other_tags: nil,
+                      container_id: nil, client_mutation_id: nil, **kargs, &block)
               input = {
                 filename: filename,
                 filetype: filetype,
                 filesize: filesize.to_s,
                 url:      url
               }
-              input[:locationIds] = Array(location_ids) if location_ids
-              input[:otherTags]   = Array(other_tags)   if other_tags
-              input[:containerId] = container_id        if container_id
+              input[:locationIds]      = Array(location_ids) if location_ids
+              input[:otherTags]        = Array(other_tags)   if other_tags
+              input[:containerId]      = container_id        if container_id
+              input[:clientMutationId] = client_mutation_id  unless client_mutation_id.nil?
 
               super(input: input, **kargs, &block)
             end

data/lib/ecoportal/api/graphql/mutation/image/upload.rb

@@ -0,0 +1,88 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Mutation
+        module Image
+          # Registers an object already uploaded to S3 as a `TempImage` -- the upload-staging
+          # model behind Image Gallery (and other, non-gallery) image uploads.
+          #
+          # ★ Sibling to `Mutation::FileContainer::Upload`, NOT a variant of it: an Image
+          # Gallery image is explicitly NOT a `FileContainer`. Verified against the live
+          # ecoPortal server source (read-only, /tmp/work/ecoPortal):
+          #   * `app/graphql/mutations/images/upload.rb:1-23` -- the mutation builds an
+          #     `Enzyme::ImageReference::TempImage`, not `uploadFile`/`FileContainer`.
+          #   * `app/graphql/types/mutation_type.rb:224` -- schema field `uploadImage`
+          #     (`field :upload_image, mutation: Mutations::Images::Upload`).
+          #   * `app/graphql/types/enums/files/image_upload_type_enum.rb` -- `type:` is a
+          #     live enum (`image_gallery`, `policy_group`, `theme`, `user`, `organization`,
+          #     `brand`); `"image_gallery"` is the one `Base::Page::DataField::ImageGallery`
+          #     consumes.
+          #
+          # The SIGNATURE and S3-POST steps upstream of this call are IDENTICAL to the
+          # `uploadFile` flow (same `fileUploadSignature`, same multipart POST) -- see
+          # `FileUpload::Client#upload_image`, which shares its presign+store step with
+          # `#upload` and only diverges here, at registration.
+          #
+          # Verified against the live schema:
+          #   uploadImage(input: ImagesUploadInput!) -> ImagesUploadPayload
+          #     { clientMutationId errors item: TempImage }
+          #   ImagesUploadInput { clientMutationId key type id import }
+          class Upload < Logic::Mutation
+            field_name :uploadImage
+
+            class_resolver :payload_class, 'Ecoportal::API::GraphQL::Payload::ImagesUpload'
+
+            # @param key [String] the S3 object key produced by the S3 POST step.
+            # @param type [String, Symbol] live enum value -- `FileUpload::Client` always
+            #   passes `'image_gallery'` today; any other value is sent verbatim for a future
+            #   caller.
+            # @param id [String, nil] a target id the image is being uploaded FOR, in
+            #   contexts that need one (e.g. an existing brand/policy_group/user). Unused by
+            #   the Image Gallery context -- that attach happens later, via `updatePage`, not
+            #   here.
+            # @param import [Boolean] matches the live schema's own default (`true`).
+            # @param client_mutation_id [String, nil] optional correlation/tracing id --
+            #   `ImagesUploadInput`'s own `clientMutationId` (confirmed in this file's own
+            #   header, `ImagesUploadInput { clientMutationId key type id import }`). Omitted
+            #   entirely when not given, so every existing caller's input shape is
+            #   byte-identical to before.
+            def query(key:, type:, id: nil, import: true, client_mutation_id: nil, **kargs, &block)
+              super(input: build_input(key: key, type: type, id: id, import: import,
+                                       client_mutation_id: client_mutation_id), **kargs, &block)
+            end
+
+            private
+
+            def build_input(key:, type:, id:, import:, client_mutation_id: nil)
+              input = {key: key, type: type.to_s, import: import}
+              input[:id] = id if id
+              input[:clientMutationId] = client_mutation_id unless client_mutation_id.nil?
+              input
+            end
+
+            def basic_block(&block)
+              payload_block = block || default_payload_block
+              proc {
+                mutation(input: :ImagesUploadInput!) {
+                  uploadImage(input: :input, &payload_block)
+                }
+              }
+            end
+
+            def default_payload_block
+              proc {
+                errors { details fullMessages }
+                item {
+                  id
+                  s3Key
+                  complete
+                  error
+                }
+              }
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/mutation/image.rb

@@ -0,0 +1,14 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Mutation
+        # Namespaced `Image` (matches the schema's own `TempImageType`/`ImagesUploadInput`
+        # naming) -- sibling to `Mutation::FileContainer`, NOT a variant of it.
+        module Image
+        end
+      end
+    end
+  end
+end
+
+require_relative 'image/upload'

data/lib/ecoportal/api/graphql/mutation/template/create.rb

@@ -3,15 +3,47 @@ module Ecoportal
     class GraphQL
       module Mutation
         module Template
+          # `createPageTemplate(input: CreatePageTemplateInput!)` — creates a template page from
+          # a `WorkflowCommand` batch.
+          #
+          # ★ `registerId` IS NOT COSMETIC — it is what makes the create AUTHORIZABLE.
+          #
+          # The backend resolves a page's registers BY TAG
+          # (`NewEp::Pages::AssociatedRegisters`: org registers whose `filter_tags` are a subset
+          # of the page's `combined_tags`), and `RegisterTemplatePermissionChecker` returns
+          # `false` outright when that set is EMPTY. A template created without `registerId`
+          # carries no `base_tags`, so it is associated with ZERO registers, so the check fails
+          # regardless of what the account is granted — surfacing as the misleading
+          # `You are not authorized to perform: edit_template_basic_settings`.
+          # `Pages::Templates::CreateForm#bind_register!` is what closes that hole: given
+          # `register_id` it sets `page.base_tags = register.filter_tags` BEFORE the commands run.
+          #
+          # SHAPE (verified against the LIVE eu.live SDL, 2026-09-04): `registerId: ID` is an
+          # INPUT FIELD of `CreatePageTemplateInput`, not a sibling argument of the mutation —
+          # the backend mutation declares `argument :register_id, ID, required: false` next to
+          # `argument :commands`, but `Mutations::BaseMutation < GraphQL::Schema::RelayClassicMutation`
+          # folds every argument into the generated input object. So it travels inside `input:`,
+          # exactly like `commands`.
           class Create < Logic::Mutation
-            SCHEMA_VERSION = '20260605'.freeze
+            SCHEMA_VERSION = '20260904'.freeze
 
             field_name :createPageTemplate
 
             class_resolver :payload_class, 'Ecoportal::API::GraphQL::Payload::Template::Create'
 
-            def query(commands:, **kargs, &block)
-              super(input: { commands: commands }, **kargs, &block)
+            # @param commands [Array<Hash>] the `WorkflowCommand` batch.
+            # @param register_id [String, nil] the register to bind the new template to. Omitted
+            #   when nil — never sent as an explicit null, so existing call sites keep producing
+            #   the byte-identical input they produced before this key existed.
+            def query(commands:, register_id: nil, **kargs, &block)
+              super(input: self.class.build_input(commands: commands, register_id: register_id), **kargs, &block)
+            end
+
+            # Extracted so the omit-nil rule is testable without a client or a network stub.
+            def self.build_input(commands:, register_id: nil)
+              {commands: commands}.tap do |input|
+                input[:registerId] = register_id unless register_id.nil?
+              end
             end
 
             private

data/lib/ecoportal/api/graphql/mutation/template/update.rb

@@ -10,9 +10,11 @@ module Ecoportal
 
             class_resolver :payload_class, 'Ecoportal::API::GraphQL::Payload::Template::Update'
 
-            def query(id:, patch_ver:, commands:, **kargs, &block)
+            def query(id:, patch_ver:, commands:, client_mutation_id: nil, **kargs, &block)
+              input = { id: id, patchVer: patch_ver, commands: commands }
+              input[:clientMutationId] = client_mutation_id unless client_mutation_id.nil?
               super(
-                input: { id: id, patchVer: patch_ver, commands: commands },
+                input: input,
                 **kargs,
                 &block
               )

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

@@ -18,3 +18,4 @@ require_relative 'mutation/ai_summary'
 require_relative 'mutation/kickstand'
 require_relative 'mutation/template'
 require_relative 'mutation/file_container'
+require_relative 'mutation/image'

data/lib/ecoportal/api/graphql/payload/images_upload.rb

@@ -0,0 +1,14 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Payload
+        # `uploadImage` -> `ImagesUploadPayload { clientMutationId errors item: TempImage }`.
+        # Sibling to `Payload::Upload` (`uploadFile` -> `FileContainer`) -- NOT a variant of
+        # it. See `Base::TempImage`'s header for why the item type differs.
+        class ImagesUpload < Logic::Payload
+          class_resolver :item_class, 'Ecoportal::API::GraphQL::Model::TempImage'
+        end
+      end
+    end
+  end
+end

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

@@ -22,3 +22,4 @@ require_relative 'payload/execute_workflow_commands'
 require_relative 'payload/kickstand'
 require_relative 'payload/template'
 require_relative 'payload/upload'
+require_relative 'payload/images_upload'

data/lib/ecoportal/api/graphql_version.rb

@@ -1,5 +1,5 @@
 module Ecoportal
   module API
-    GRAPQL_VERSION = '2.2.1'.freeze
+    GRAPQL_VERSION = '3.0.0'.freeze
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ecoportal-api-graphql
 version: !ruby/object:Gem::Version
-  version: 2.2.1
+  version: 3.0.0
 platform: ruby
 authors:
 - Oscar Segura
@@ -9,6 +9,20 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: json-canonicalization
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -199,7 +213,7 @@ extra_rdoc_files: []
 files:
 - CHANGELOG.md
 - LICENSE
-- README.md
+- README.gem.md
 - lib/ecoportal/api-graphql.rb
 - lib/ecoportal/api/common.graphql.rb
 - lib/ecoportal/api/common/graphql.rb
@@ -311,6 +325,7 @@ files:
 - lib/ecoportal/api/graphql/base/preview_page.rb
 - lib/ecoportal/api/graphql/base/register.rb
 - lib/ecoportal/api/graphql/base/resource.rb
+- lib/ecoportal/api/graphql/base/temp_image.rb
 - lib/ecoportal/api/graphql/base/template.rb
 - lib/ecoportal/api/graphql/base/template/change_log_entry.rb
 - lib/ecoportal/api/graphql/builder.rb
@@ -625,8 +640,23 @@ files:
 - lib/ecoportal/api/graphql/model/preview_page.rb
 - lib/ecoportal/api/graphql/model/register.rb
 - lib/ecoportal/api/graphql/model/resource.rb
+- lib/ecoportal/api/graphql/model/temp_image.rb
 - lib/ecoportal/api/graphql/model/template.rb
+- lib/ecoportal/api/graphql/model/template/binding.rb
 - lib/ecoportal/api/graphql/model/template/change_log_entry.rb
+- lib/ecoportal/api/graphql/model/template/command_grouper.rb
+- lib/ecoportal/api/graphql/model/template/command_normalizer.rb
+- lib/ecoportal/api/graphql/model/template/command_synthesis.rb
+- lib/ecoportal/api/graphql/model/template/field.rb
+- lib/ecoportal/api/graphql/model/template/force.rb
+- lib/ecoportal/api/graphql/model/template/helper.rb
+- lib/ecoportal/api/graphql/model/template/instance.rb
+- lib/ecoportal/api/graphql/model/template/node.rb
+- lib/ecoportal/api/graphql/model/template/option.rb
+- lib/ecoportal/api/graphql/model/template/read.rb
+- lib/ecoportal/api/graphql/model/template/section.rb
+- lib/ecoportal/api/graphql/model/template/stage.rb
+- lib/ecoportal/api/graphql/model/template/staged_executor.rb
 - lib/ecoportal/api/graphql/model/user.rb
 - lib/ecoportal/api/graphql/mutation.rb
 - lib/ecoportal/api/graphql/mutation/action.rb
@@ -643,6 +673,8 @@ files:
 - lib/ecoportal/api/graphql/mutation/contractor_entity/update_manager_settings.rb
 - lib/ecoportal/api/graphql/mutation/file_container.rb
 - lib/ecoportal/api/graphql/mutation/file_container/upload.rb
+- lib/ecoportal/api/graphql/mutation/image.rb
+- lib/ecoportal/api/graphql/mutation/image/upload.rb
 - lib/ecoportal/api/graphql/mutation/kickstand.rb
 - lib/ecoportal/api/graphql/mutation/kickstand/bulk_update_jobs.rb
 - lib/ecoportal/api/graphql/mutation/kickstand/bulk_update_workflows.rb
@@ -707,6 +739,7 @@ files:
 - lib/ecoportal/api/graphql/payload/contractor_entity/update.rb
 - lib/ecoportal/api/graphql/payload/execute_workflow_commands.rb
 - lib/ecoportal/api/graphql/payload/force_commands.rb
+- lib/ecoportal/api/graphql/payload/images_upload.rb
 - lib/ecoportal/api/graphql/payload/kickstand.rb
 - lib/ecoportal/api/graphql/payload/kickstand/bulk_update_jobs.rb
 - lib/ecoportal/api/graphql/payload/kickstand/bulk_update_workflows.rb

data/README.md

@@ -1,24 +0,0 @@
-# Ecoportal::API::GraphQL
-
-This is a basic collection of helpers that can be used to interact with the
-[ecoPortal](https://www.ecoportal.com) `GraphQL` API
-
-## Installation
-
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'ecoportal-api-graphql', require: %w[ecoportal/api-graphql]
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install ecoportal-api-graphql
-
-## Changelog
-
-See {file:CHANGELOG.md} for a list of changes.