ecoportal-api-graphql 2.0.0 → 3.0.0

data/lib/ecoportal/api/graphql/error/locations_error.rb

@@ -1,28 +1,28 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Error
-        class LocationsError < Logic::BaseModel
-          read_only!
-
-          passthrough :type, :message
-          passarray :conflictingIds
-          embeds_many :validationErrors, klass: LocationsValidationError
-
-          def empty?
-            return false unless conflictingIds.empty?
-
-            validationErrors.empty?
-          end
-
-          def any?
-            !empty?
-          end
-        end
-      end
-    end
-  end
-end
-
-
-require_relative 'locations_error/fetch_nested'
+module Ecoportal
+  module API
+    class GraphQL
+      module Error
+        class LocationsError < Logic::BaseModel
+          read_only!
+
+          passthrough :type, :message
+          passarray :conflictingIds
+          embeds_many :validationErrors, klass: LocationsValidationError
+
+          def empty?
+            return false unless conflictingIds.empty?
+
+            validationErrors.empty?
+          end
+
+          def any?
+            !empty?
+          end
+        end
+      end
+    end
+  end
+end
+
+
+require_relative 'locations_error/fetch_nested'

data/lib/ecoportal/api/graphql/error/locations_validation_error.rb

@@ -1,20 +1,20 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Error
-        class LocationsValidationError < Logic::BaseModel
-          read_only!
-
-          passthrough :error, :message, :property
-
-          def empty?
-            return false unless error.nil?
-            return false unless message.nil?
-
-            property.nil?
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Error
+        class LocationsValidationError < Logic::BaseModel
+          read_only!
+
+          passthrough :error, :message, :property
+
+          def empty?
+            return false unless error.nil?
+            return false unless message.nil?
+
+            property.nil?
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/error/validation_errors.rb

@@ -1,28 +1,28 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Error
-        class ValidationErrors < Logic::BaseModel
-          include Enumerable
-
-          passthrough :details
-          passarray :fullMessages
-
-          def empty?
-            count < 1
-          end
-
-          def any?
-            !empty?
-          end
-
-          def each(&block)
-            return to_enum(:each) unless block
-
-            fullMessages.each(&block)
-          end
-        end
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      module Error
+        class ValidationErrors < Logic::BaseModel
+          include Enumerable
+
+          passthrough :details
+          passarray :fullMessages
+
+          def empty?
+            count < 1
+          end
+
+          def any?
+            !empty?
+          end
+
+          def each(&block)
+            return to_enum(:each) unless block
+
+            fullMessages.each(&block)
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -1,12 +1,12 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module Error
-      end
-    end
-  end
-end
-
-require_relative 'error/locations_validation_error'
-require_relative 'error/validation_errors'
-require_relative 'error/locations_error'
+module Ecoportal
+  module API
+    class GraphQL
+      module Error
+      end
+    end
+  end
+end
+
+require_relative 'error/locations_validation_error'
+require_relative 'error/validation_errors'
+require_relative 'error/locations_error'

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

@@ -26,21 +26,38 @@ module Ecoportal
         # `X-ECOPORTAL-API-KEY` is needed here: every ecoPortal call is GraphQL, on the session
         # token this client already holds.
         #
-        # Single file:
+        # ★ Extended 2026-09 with `#upload_image`/`#upload_all_images` — steps 1-2 above (the
+        # presign + S3 POST) are IDENTICAL for an Image Gallery image; only step 3 differs
+        # (`uploadImage` -> a `TempImage`, not `uploadFile` -> a `FileContainer`). Confirmed
+        # against the live ecoPortal server source (read-only, /tmp/work/ecoPortal) that an
+        # Image Gallery image is genuinely NOT a `FileContainer` — see
+        # `Mutation::Image::Upload`'s and `Base::Page::DataField::ImageGallery`'s own headers
+        # for the full evidence trail. `#presign_and_store!` is the shared internal path both
+        # `#upload_one` and `#upload_one_image` call; `#run_batch` is the shared batch-with-
+        # progress-callback loop both `#upload_all` and `#upload_all_images` call.
+        #
+        # Single file, FileContainer (File-type fields):
         #   id = api.file_upload.upload('/path/report.pdf')
         #   page.components.get_by_name('Report').file_container_ids = [id]
         #
-        # Many files, concurrently, with per-file error isolation (nothing raises out):
+        # Single file, TempImage (Image Gallery fields):
+        #   source_id = api.file_upload.upload_image('/path/photo.jpg')
+        #   page.components.get_by_name('Site Photos').add_source_images([{source_id: source_id, file_name: 'photo.jpg'}])
+        #
+        # Many files, concurrently, with per-file error isolation (nothing raises out) — same
+        # shape for both flows:
         #   results = api.file_upload.upload_all(paths, threads: 4) do |r|
         #     puts r.success? ? "#{r.file} -> #{r.container_id}" : "#{r.file} FAILED: #{r.error}"
         #   end
         #   results.select(&:error?)
         #
-        # Instrumentation / middleware — hooks fire per stage, per file:
+        # Instrumentation / middleware — hooks fire per stage, per file, for EITHER flow (the
+        # stage names are shared: `:register` fires once whether the registration mutation was
+        # `uploadFile` or `uploadImage`):
         #   client = api.file_upload
         #   client.on(:signature) { |creds|         logger.info "presigned #{creds.endpoint}" }
         #   client.on(:storage)   { |key, response| logger.info "S3 #{response.code} #{key}" }
-        #   client.on(:register)  { |payload|       logger.info "container #{payload.item&.id}" }
+        #   client.on(:register)  { |payload|       logger.info "registered #{payload.item&.id}" }
         class Client
           include Ecoportal::API::GraphQL::Concerns::Threadable
 
@@ -51,9 +68,10 @@ module Ecoportal
 
           STAGES = %i[signature storage register].freeze
           # Fallback only — the real value is a condition inside the returned policy.
-          DEFAULT_ENCRYPTION = 'AES256'.freeze
-          DEFAULT_MIME       = 'application/octet-stream'.freeze
-          MAX_THREADS        = 8
+          DEFAULT_ENCRYPTION  = 'AES256'.freeze
+          DEFAULT_MIME        = 'application/octet-stream'.freeze
+          DEFAULT_IMAGE_TYPE  = 'image_gallery'.freeze
+          MAX_THREADS         = 8
 
           # One entry per input file. Mirrors `ecoportal-api-v2`'s
           # `S3::Files::BatchUpload::FileResult` so batch code reads the same in both stacks.
@@ -77,13 +95,36 @@ module Ecoportal
             end
           end
 
+          # Sibling to {Result} for the image-upload pipeline — same shape, different item
+          # (a `TempImage`, not a `FileContainer`).
+          ImageResult = Struct.new(:file) do
+            attr_accessor :key, :payload, :error
+
+            def error?
+              !error.nil?
+            end
+
+            def success?
+              !error? && !temp_image_id.nil?
+            end
+
+            def temp_image
+              payload&.item
+            end
+
+            def temp_image_id
+              temp_image&.id
+            end
+          end
+
           def initialize(graphql_client)
             @graphql = graphql_client
             @hooks   = {}
           end
 
           # Register a stage hook. Called for every file, in that file's own thread — keep it
-          # thread-safe (or wrap it in your own mutex).
+          # thread-safe (or wrap it in your own mutex). Fires identically for {#upload} and
+          # {#upload_image} — the STAGE names are shared between both flows.
           # @param stage [:signature, :storage, :register]
           def on(stage, &block)
             stage = stage.to_sym
@@ -102,33 +143,32 @@ module Ecoportal
             result.container_id
           end
 
+          # @return [String] the new `TempImage` id (the `sourceId` an Image Gallery
+          #   `ImageInput` write needs — see `Base::Page::DataField::ImageGallery#
+          #   add_source_images`).
+          # @raise [Error] on any failure — use {#upload_all_images} for non-raising per-file
+          #   isolation.
+          def upload_image(file_path, **kargs)
+            result = upload_one_image(file_path, **kargs)
+            raise result.error if result.error?
+
+            result.temp_image_id
+          end
+
           # Uploads many files with bounded concurrency. Never raises for a single file: each
           # {Result} carries its own error, and the block is called as each finishes.
           #
           # @param threads [Integer] max concurrent uploads (`1` = inline, deterministic).
           # @return [Array<Result>] one per input file; order is not guaranteed when threaded.
           def upload_all(file_paths, threads: 4, **kargs, &block)
-            files   = Array(file_paths).flatten.compact
-            max     = threads.to_i.clamp(1, MAX_THREADS)
-            results = []
-            spawned = []
-
-            # Presign ONCE for the batch (the policy is time-boxed but reusable) and warm it
-            # here so N threads don't race for the first one.
-            credentials
-
-            with_preserved_thread_globals do
-              files.each do |file|
-                new_thread(spawned, max: max) do
-                  result = upload_one(file, **kargs)
-                  mutex(:results).synchronize { results << result }
-                  block&.call(result)
-                end
-              end
-            end
+            run_batch(file_paths, threads: threads, on_result: block) { |file| upload_one(file, **kargs) }
+          end
 
-            spawned.each(&:join)
-            results
+          # Sibling to {#upload_all} for the image-upload pipeline — identical concurrency,
+          # isolation and progress-callback semantics.
+          # @return [Array<ImageResult>]
+          def upload_all_images(file_paths, threads: 4, **kargs, &block)
+            run_batch(file_paths, threads: threads, on_result: block) { |file| upload_one_image(file, **kargs) }
           end
 
           # Force the next upload to presign again (e.g. after a policy expiry).
@@ -141,13 +181,10 @@ module Ecoportal
 
           def upload_one(file_path, location_ids: nil, tags: nil, container_id: nil)
             Result.new(file_path).tap do |result|
-              raise MissingLocalFile, "no such file: #{file_path}" unless ::File.file?(file_path)
-
-              creds      = credentials
-              result.key = storage_key(creds, file_path)
-              store!(creds, result.key, file_path)
+              _creds, key = presign_and_store!(file_path)
+              result.key     = key
               result.payload = register(
-                file_path, result.key,
+                file_path, key,
                 location_ids: location_ids, tags: tags, container_id: container_id
               )
             rescue StandardError => e
@@ -155,6 +192,61 @@ module Ecoportal
             end
           end
 
+          def upload_one_image(file_path, type: DEFAULT_IMAGE_TYPE, id: nil, import: true)
+            ImageResult.new(file_path).tap do |result|
+              _creds, key = presign_and_store!(file_path)
+              result.key     = key
+              result.payload = register_image(file_path, key, type: type, id: id, import: import)
+            rescue StandardError => e
+              result.error = e
+            end
+          end
+
+          # Shared by BOTH flows: presign (memoised per batch), build a collision-proof S3
+          # key, and the multipart POST itself. Only the THIRD step (the registration
+          # mutation — `uploadFile` vs `uploadImage`) differs between {#upload_one} and
+          # {#upload_one_image}.
+          # @return [Array(Query::FileUploadSignature::SignatureResponse, String)] the
+          #   credentials used and the S3 key the file was stored under.
+          def presign_and_store!(file_path)
+            raise MissingLocalFile, "no such file: #{file_path}" unless ::File.file?(file_path)
+
+            creds = credentials
+            key   = storage_key(creds, file_path)
+            store!(creds, key, file_path)
+            [creds, key]
+          end
+
+          # Shared by {#upload_all}/{#upload_all_images}: bounded-concurrency loop, presign-
+          # once-per-batch, per-file error isolation, and a progress callback fired as each
+          # result lands (not deferred to the end). `upload_one` (the block) is the only thing
+          # that differs between the two callers.
+          # @yieldparam file_path [String]
+          # @yieldreturn [Result, ImageResult]
+          def run_batch(file_paths, threads:, on_result: nil)
+            files   = Array(file_paths).flatten.compact
+            max     = threads.to_i.clamp(1, MAX_THREADS)
+            results = []
+            spawned = []
+
+            # Presign ONCE for the batch (the policy is time-boxed but reusable) and warm it
+            # here so N threads don't race for the first one.
+            credentials
+
+            with_preserved_thread_globals do
+              files.each do |file|
+                new_thread(spawned, max: max) do
+                  result = yield(file)
+                  mutex(:results).synchronize { results << result }
+                  on_result&.call(result)
+                end
+              end
+            end
+
+            spawned.each(&:join)
+            results
+          end
+
           # Memoised behind a mutex so a batch presigns once, not once per thread.
           def credentials
             mutex(:credentials).synchronize do
@@ -167,7 +259,8 @@ module Ecoportal
           # `uploads/<userId>/<epoch-ms>-<token>-/<basename>` — the shape the web client uses.
           # That stamp+token segment is what stops same-named files colliding: the previous
           # implementation concatenated `upload_prefix + filename`, so two uploads of
-          # `report.pdf` overwrote each other in the bucket.
+          # `report.pdf` overwrote each other in the bucket. Shared by BOTH flows — an image
+          # upload needs the identical collision-proofing.
           def storage_key(creds, file_path)
             stamp = (Time.now.to_f * 1000).to_i
             "#{creds.upload_prefix}#{stamp}-#{SecureRandom.alphanumeric(20)}-/#{::File.basename(file_path)}"
@@ -224,6 +317,18 @@ module Ecoportal
             payload
           end
 
+          def register_image(file_path, key, type:, id:, import:)
+            payload = Mutation::Image::Upload.new(@graphql.client).query(
+              key: key, type: type, id: id, import: import
+            )
+            fire(:register, payload)
+
+            raise RegistrationFailed, "uploadImage failed for #{::File.basename(file_path)}: #{payload.error_doc}" if payload.error?
+            raise RegistrationFailed, "uploadImage returned no item for #{::File.basename(file_path)}" unless payload.item&.id
+
+            payload
+          end
+
           # The bucket policy dictates the encryption header, so echo it instead of assuming:
           # the policy is base64 JSON whose `conditions` carry `x-amz-server-side-encryption`.
           def encryption(creds)

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

@@ -1,10 +1,10 @@
-module Ecoportal
-  module API
-    class GraphQL
-      module FileUpload
-      end
-    end
-  end
-end
-
-require_relative 'file_upload/client'
+module Ecoportal
+  module API
+    class GraphQL
+      module FileUpload
+      end
+    end
+  end
+end
+
+require_relative 'file_upload/client'

data/lib/ecoportal/api/graphql/fragment/action.rb

@@ -1,65 +1,65 @@
-module Ecoportal
-  module API
-    class GraphQL
-      class Fragment
-        fragment :Action, <<~GRAPHQL
-          fragment Action on Action {
-            id
-            altId
-            actionCategory {
-              name
-              value
-            }
-            actionCategoryId
-            standaloneAction
-            status
-            relativeStatus
-            archived
-            locations {
-              id
-              name
-              objectId
-            }
-            name
-            description
-            assignedTo {
-              id
-              name
-              email
-            }
-            createdAt {
-              dateTime
-              timeZone
-            }
-            updatedAt {
-              dateTime
-              timeZone
-            }
-            dueDate {
-              dateTime
-              timeZone
-            }
-            completedAt {
-              dateTime
-              timeZone
-            }
-            completer {
-              name
-              email
-            }
-            linkedResources {
-              id
-              page {
-                ... on BasePageInterface {
-                  id
-                  name
-                  uid
-                }
-              }
-            }
-          }
-        GRAPHQL
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      class Fragment
+        fragment :Action, <<~GRAPHQL
+          fragment Action on Action {
+            id
+            altId
+            actionCategory {
+              name
+              value
+            }
+            actionCategoryId
+            standaloneAction
+            status
+            relativeStatus
+            archived
+            locations {
+              id
+              name
+              objectId
+            }
+            name
+            description
+            assignedTo {
+              id
+              name
+              email
+            }
+            createdAt {
+              dateTime
+              timeZone
+            }
+            updatedAt {
+              dateTime
+              timeZone
+            }
+            dueDate {
+              dateTime
+              timeZone
+            }
+            completedAt {
+              dateTime
+              timeZone
+            }
+            completer {
+              name
+              email
+            }
+            linkedResources {
+              id
+              page {
+                ... on BasePageInterface {
+                  id
+                  name
+                  uid
+                }
+              }
+            }
+          }
+        GRAPHQL
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/fragment/action_category.rb

@@ -1,17 +1,17 @@
-module Ecoportal
-  module API
-    class GraphQL
-      class Fragment
-        fragment :ActionCategory, <<~GRAPHQL
-          fragment ActionCategory on Category {
-            id
-            name
-            value
-            archived
-            weight
-          }
-        GRAPHQL
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      class Fragment
+        fragment :ActionCategory, <<~GRAPHQL
+          fragment ActionCategory on Category {
+            id
+            name
+            value
+            archived
+            weight
+          }
+        GRAPHQL
+      end
+    end
+  end
+end

data/lib/ecoportal/api/graphql/fragment/contractor_entity.rb

@@ -1,20 +1,20 @@
-module Ecoportal
-  module API
-    class GraphQL
-      class Fragment
-        fragment :ContractorEntity, <<~GRAPHQL
-          fragment ContractorEntity on ContractorEntity {
-            id
-            externalId
-            name
-            schemaId
-            active
-            approved
-            associatedPeopleIds
-            leadContractorIds
-          }
-        GRAPHQL
-      end
-    end
-  end
-end
+module Ecoportal
+  module API
+    class GraphQL
+      class Fragment
+        fragment :ContractorEntity, <<~GRAPHQL
+          fragment ContractorEntity on ContractorEntity {
+            id
+            externalId
+            name
+            schemaId
+            active
+            approved
+            associatedPeopleIds
+            leadContractorIds
+          }
+        GRAPHQL
+      end
+    end
+  end
+end