ecoportal-api-graphql 1.3.16 → 2.0.0

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

@@ -1,189 +1,248 @@
-require 'net/http'
+require 'net/http'
 require 'uri'
 require 'json'
+require 'base64'
+require 'securerandom'
 require 'mime/types'
 
 module Ecoportal
   module API
     class GraphQL
       module FileUpload
-        # Orchestrates the full file upload workflow:
+        # Uploads local files to the org file manager, natively.
         #
-        #   Step 1 — Get S3 pre-signed credentials via GraphQL
-        #   Step 2 — Upload file directly to S3 (multipart form POST)
-        #   Step 3 — Register the upload with EcoPortal (REST POST /v2/s3/files)
-        #   Step 4 — Poll until the FileContainer is created
+        # ★ Rewritten 2026-07-30 from a CAPTURED web upload (see the `har-scrub` skill). The
+        # real flow is three steps, all GraphQL except the storage POST:
         #
-        # Returns a fileContainerId string on success, suitable for use in
-        # DataField::FileField#file_container_ids= or DataField::ImageGallery#file_container_ids=
+        #   1. `FileSignature` (GraphQL) -> presigned policy + credentials
+        #   2. multipart POST  (S3)      -> 204; fields, in order: key, AWSAccessKeyId, policy,
+        #                                   signature, content-type,
+        #                                   x-amz-server-side-encryption, file
+        #   3. `uploadFile`    (GraphQL) -> the FileContainer; its `id` is what page mutations want
         #
-        # Usage:
-        #   container_id = api.file_upload.upload('/path/to/report.pdf')
-        #   page.components.get_by_name('Attachment').file_container_ids = [container_id]
-        #   api.pages.update(page)
+        # The previous implementation was a port of `ecoportal-api-v2`'s REST S3 code and did
+        # `POST /api/v2/<org>/s3/files` + polling. **The platform does not use those endpoints
+        # for this flow** — no register-over-REST, no poll. That is also why no
+        # `X-ECOPORTAL-API-KEY` is needed here: every ecoPortal call is GraphQL, on the session
+        # token this client already holds.
         #
-        # Step 1 (GraphQL) authenticates via the gem's email/pass OAuth bearer token.
-        # Steps 3-4 (REST v2 `/s3/files`) require the gem to ALSO have been initialised
-        # with `api_key:` — `Ecoportal::API::GraphQL.new(email:, pass:, api_key:)` — since
-        # those endpoints authenticate via `X-ECOPORTAL-API-KEY`, not the GraphQL bearer
-        # token (mirrors `Ecoportal::API::Common::Content::Client#base_request` in
-        # ecoportal-api-v2).
+        # Single file:
+        #   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):
+        #   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:
+        #   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}" }
         class Client
-          POLL_INTERVAL = 2      # seconds between poll attempts
-          POLL_MAX_WAIT = 120    # seconds before giving up
+          include Ecoportal::API::GraphQL::Concerns::Threadable
+
+          class Error < StandardError; end
+          class MissingLocalFile < Error; end
+          class StorageUploadFailed < Error; end
+          class RegistrationFailed < Error; end
+
+          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
+
+          # One entry per input file. Mirrors `ecoportal-api-v2`'s
+          # `S3::Files::BatchUpload::FileResult` so batch code reads the same in both stacks.
+          Result = Struct.new(:file) do
+            attr_accessor :key, :payload, :error
+
+            def error?
+              !error.nil?
+            end
+
+            def success?
+              !error? && !container_id.nil?
+            end
+
+            def file_container
+              payload&.item
+            end
+
+            def container_id
+              file_container&.id
+            end
+          end
 
           def initialize(graphql_client)
-            @graphql_client  = graphql_client
-            @http_client     = graphql_client.client.http_client
-            @org_id          = @http_client.org_id
-            @host            = @http_client.host
+            @graphql = graphql_client
+            @hooks   = {}
           end
 
-          # Upload a file and return the fileContainerId.
-          # Raises RuntimeError on failure.
-          def upload(file_path)
-            raise ArgumentError, "File not found: #{file_path}" unless File.exist?(file_path)
+          # 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).
+          # @param stage [:signature, :storage, :register]
+          def on(stage, &block)
+            stage = stage.to_sym
+            raise ArgumentError, "unknown stage #{stage.inspect}; expected one of #{STAGES.join(', ')}" unless STAGES.include?(stage)
 
-            creds    = fetch_s3_credentials
-            s3_key   = direct_upload_to_storage(file_path, creds)
-            poll_id  = register_upload(file_path, s3_key)
-            poll_for_container_id(poll_id)
+            mutex(:hooks).synchronize { (@hooks[stage] ||= []) << block }
+            self
           end
 
-          private
+          # @return [String] the file container id.
+          # @raise [Error] on any failure — use {#upload_all} for non-raising per-file isolation.
+          def upload(file_path, **kargs)
+            result = upload_one(file_path, **kargs)
+            raise result.error if result.error?
 
-          # Step 1: GraphQL query → S3 presigned credentials
-          def fetch_s3_credentials
-            Query::FileUploadSignature.new(@graphql_client.client).query
+            result.container_id
           end
 
-          # Step 2: Direct multipart POST to S3
-          def direct_upload_to_storage(file_path, creds)
-            filename  = File.basename(file_path)
-            s3_key    = "#{creds.upload_prefix}#{filename}"
-            mime_type = detect_mime_type(file_path)
-            endpoint  = URI(creds.endpoint)
-
-            File.open(file_path, 'rb') do |file|
-              Net::HTTP.start(endpoint.host, endpoint.port,
-                              use_ssl: endpoint.scheme == 'https') do |http|
-                boundary = "EcoPortalUpload#{SecureRandom.hex(8)}"
-                body     = build_multipart(boundary, {
-                  s3_key: s3_key, access_key: creds.access_key,
-                  policy: creds.policy, signature: creds.signature,
-                  mime_type: mime_type, filename: filename
-                }, file)
-                request = Net::HTTP::Post.new(endpoint.path.empty? ? '/' : endpoint.path)
-                request['Content-Type'] = "multipart/form-data; boundary=#{boundary}"
-                request.body = body
-                response = http.request(request)
-                raise "S3 upload failed (#{response.code}): #{response.body}" unless response.code.to_i < 300
+          # 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
 
-            s3_key
+            spawned.each(&:join)
+            results
           end
 
-          # Step 3: Register with EcoPortal backend (REST v2)
-          def register_upload(file_path, s3_key)
-            filename  = File.basename(file_path)
-            mime_type = detect_mime_type(file_path)
-            filesize  = File.size(file_path)
-
-            body     = { filename: filename, filetype: mime_type, filesize: filesize, path: s3_key }
-            response = upload_post('/s3/files', body)
-            raise "File registration failed: #{response.body}" unless response.code.to_i < 300
-
-            JSON.parse(response.body)['id']
+          # Force the next upload to presign again (e.g. after a policy expiry).
+          def refresh_credentials!
+            mutex(:credentials).synchronize { @credentials = nil }
+            self
           end
 
-          # Step 4: Poll until FileContainer is created; return fileContainerId
-          def poll_for_container_id(poll_id)
-            deadline = Time.now + POLL_MAX_WAIT
-            loop do
-              raise 'File upload timed out' if Time.now > deadline
-
-              response = upload_get("/s3/files/poll/#{poll_id}")
-              raise "Poll failed: #{response.body}" unless response.code.to_i < 300
-
-              data   = JSON.parse(response.body)
-              status = data['status'] || data.dig('file', 'status')
-
-              return data.dig('file', 'file_container_id') if data['status'] == 'success'
-              raise "File upload failed: #{data.inspect}"  if status == 'failed'
+          private
 
-              sleep POLL_INTERVAL
+          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)
+              result.payload = register(
+                file_path, result.key,
+                location_ids: location_ids, tags: tags, container_id: container_id
+              )
+            rescue StandardError => e
+              result.error = e
             end
           end
 
-          # --- REST helpers (v2 endpoints, X-ECOPORTAL-API-KEY auth) ---
-
-          def api_key
-            @api_key ||= @http_client.api_key.tap do |key|
-              if key.nil? || key.to_s.strip.empty?
-                raise 'File upload requires an api_key: Ecoportal::API::GraphQL.new(email:, pass:, api_key:). ' \
-                      'The v2 REST endpoints used to register/poll an upload authenticate via ' \
-                      'X-ECOPORTAL-API-KEY, not the GraphQL OAuth bearer token.'
+          # Memoised behind a mutex so a batch presigns once, not once per thread.
+          def credentials
+            mutex(:credentials).synchronize do
+              @credentials ||= Query::FileUploadSignature.new(@graphql.client).query.tap do |creds|
+                fire(:signature, creds)
               end
             end
           end
 
-          def upload_base_url
-            "https://#{@host}/api/v2/#{@org_id}"
+          # `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.
+          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)}"
           end
 
-          def upload_get(path)
-            uri     = URI("#{upload_base_url}#{path}")
-            request = Net::HTTP::Get.new(uri)
-            request['X-ECOPORTAL-API-KEY'] = api_key
-            request['Accept']              = 'application/json'
-            Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
+          def store!(creds, key, file_path)
+            uri  = URI.parse(creds.endpoint)
+            type = mime_type(file_path)
+
+            ::File.open(file_path, 'rb') do |io|
+              req = Net::HTTP::Post.new(uri)
+              # Field ORDER matches the browser's form. `set_form` builds the multipart body
+              # (as ecoportal-api-v2 does) rather than hand-rolling boundaries.
+              req.set_form(
+                [
+                  ['key',                           key],
+                  ['AWSAccessKeyId',                creds.access_key],
+                  ['policy',                        creds.policy],
+                  ['signature',                     creds.signature],
+                  ['content-type',                  type],
+                  ['x-amz-server-side-encryption',  encryption(creds)],
+                  ['file', io, {filename: ::File.basename(file_path), content_type: type}]
+                ],
+                'multipart/form-data'
+              )
+
+              response = Net::HTTP.start(uri.hostname, uri.port, use_ssl: uri.scheme == 'https') do |http|
+                http.request(req)
+              end
+
+              fire(:storage, key, response)
+              return response if response.is_a?(Net::HTTPSuccess)
+
+              raise StorageUploadFailed,
+                    "storage rejected #{::File.basename(file_path)}: #{response.code} #{response.body.to_s[0, 300]}"
+            end
           end
 
-          def upload_post(path, body)
-            uri     = URI("#{upload_base_url}#{path}")
-            request = Net::HTTP::Post.new(uri)
-            request['X-ECOPORTAL-API-KEY'] = api_key
-            request['Content-Type']        = 'application/json'
-            request['Accept']              = 'application/json'
-            request.body                   = JSON.generate(body)
-            Net::HTTP.start(uri.host, uri.port, use_ssl: true) { |http| http.request(request) }
+          def register(file_path, key, location_ids:, tags:, container_id:)
+            payload = Mutation::FileContainer::Upload.new(@graphql.client).query(
+              filename:     ::File.basename(file_path),
+              filetype:     mime_type(file_path),
+              filesize:     ::File.size(file_path),
+              url:          key,
+              location_ids: location_ids,
+              other_tags:   tags,
+              container_id: container_id
+            )
+            fire(:register, payload)
+
+            raise RegistrationFailed, "uploadFile failed for #{::File.basename(file_path)}: #{payload.error_doc}" if payload.error?
+            raise RegistrationFailed, "uploadFile returned no container for #{::File.basename(file_path)}" unless payload.item&.id
+
+            payload
           end
 
-          # --- Multipart builder ---
-
-          def build_multipart(boundary, opts, file_io)
-            parts = {
-              'key'                          => opts[:s3_key],
-              'AWSAccessKeyId'               => opts[:access_key],
-              'policy'                       => opts[:policy],
-              'signature'                    => opts[:signature],
-              'x-amz-server-side-encryption' => 'AES256',
-              'Content-Type'                 => opts[:mime_type]
-            }
-            filename  = opts[:filename]
-            mime_type = opts[:mime_type]
-
-            body = +''
-            parts.each do |name, value|
-              body << "--#{boundary}\r\n"
-              body << "Content-Disposition: form-data; name=\"#{name}\"\r\n\r\n"
-              body << "#{value}\r\n"
-            end
-            # File field last
-            body << "--#{boundary}\r\n"
-            body << "Content-Disposition: form-data; name=\"file\"; filename=\"#{filename}\"\r\n"
-            body << "Content-Type: #{mime_type}\r\n\r\n"
-            body << file_io.read
-            body << "\r\n--#{boundary}--\r\n"
-            body
+          # 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)
+            @encryption ||=
+              begin
+                conditions = JSON.parse(Base64.decode64(creds.policy.to_s))['conditions'] || []
+                conditions.grep(Hash).filter_map { |c| c['x-amz-server-side-encryption'] }.first || DEFAULT_ENCRYPTION
+              rescue JSON::ParserError, TypeError
+                DEFAULT_ENCRYPTION
+              end
+          end
+
+          def fire(stage, *args)
+            hooks = mutex(:hooks).synchronize { @hooks[stage]&.dup }
+            (hooks || []).each { |hook| hook.call(*args) }
           end
 
-          def detect_mime_type(file_path)
-            types = MIME::Types.type_for(file_path)
-            types.first&.to_s || 'application/octet-stream'
-          rescue StandardError
-            'application/octet-stream'
+          def mime_type(file_path)
+            MIME::Types.type_for(file_path).first&.content_type || DEFAULT_MIME
           end
         end
       end

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

@@ -0,0 +1,84 @@
+module Ecoportal
+  module API
+    class GraphQL
+      class Fragment
+        # Common fields of the `ActivityInterface` (page history feed). Selecting on
+        # the interface returns these for every one of the ~61 concrete activity
+        # types; `__typename` lets callers dispatch. We deliberately do NOT pull in
+        # per-type fields (kept to the interface surface + a __typename passthrough,
+        # so any unmodelled activity type still resolves cleanly as Model::Activity).
+        fragment :Activity, <<~GRAPHQL
+          fragment Activity on ActivityInterface {
+            __typename
+            id
+            priority
+            system
+            fromPublicTemplate
+            stageId
+            timeZone
+            categories
+            subkey
+            sourceId
+            sourceName
+            userId
+            userEmail
+            userName
+            createdAt {
+              dateTime
+              timeZone
+            }
+            updatedAt {
+              dateTime
+              timeZone
+            }
+            personMember {
+              id
+              name
+              email
+            }
+            user {
+              id
+              email
+              name
+            }
+          }
+        GRAPHQL
+
+        # `Organization.page(id:)` returns a PageUnion (BasicPage | PhasedPage), so the
+        # `activities` connection can only be selected inside inline fragments per member.
+        # This fragment wraps the ActivityInterfaceConnection selection for both page
+        # types; it references the operation variables ($searchConf/$after/$before/
+        # $first/$last), which are declared by Query::PageActivities.
+        fragment :PageActivities, <<~GRAPHQL
+          fragment PageActivities on PageUnion {
+            __typename
+            ... on BasicPage {
+              activities(searchConf: $searchConf, after: $after, before: $before, first: $first, last: $last) {
+                ...ActivityConnection
+              }
+            }
+            ... on PhasedPage {
+              activities(searchConf: $searchConf, after: $after, before: $before, first: $first, last: $last) {
+                ...ActivityConnection
+              }
+            }
+          }
+        GRAPHQL
+
+        # The ActivityInterfaceConnection selection reused by both page types above.
+        fragment :ActivityConnection, <<~GRAPHQL
+          fragment ActivityConnection on ActivityInterfaceConnection {
+            totalCount
+            pageInfo {
+              endCursor
+              hasNextPage
+            }
+            nodes {
+              ...Activity
+            }
+          }
+        GRAPHQL
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+module Ecoportal
+  module API
+    class GraphQL
+      class Fragment
+        # System Access Log entry — `currentOrganization.activityLogs` returns an
+        # `ActivityLogUnion` (a UNION), so fields cannot be selected on the union
+        # directly (only `__typename`): every field must live in an inline fragment
+        # per member. The 9 members share a common field set; the Dashboard* members
+        # additionally expose `parentResource*` + `resource { isVisible }`.
+        #
+        # To avoid repeating the shared selection 9 times we spread two helper
+        # fragments (:ActivityLogCommon on each member, :ActivityLogResource for the
+        # Dashboard members). Model::ActivityLog maps every member uniformly via its
+        # `__typename` passthrough, so an unmodelled/new member still resolves.
+        fragment :ActivityLog, <<~GRAPHQL
+          fragment ActivityLog on ActivityLogUnion {
+            __typename
+            ... on DashboardAccess { ...ActivityLogCommon ...ActivityLogResource }
+            ... on DashboardCreate { ...ActivityLogCommon ...ActivityLogResource }
+            ... on DashboardDelete { ...ActivityLogCommon ...ActivityLogResource }
+            ... on DashboardUpdate { ...ActivityLogCommon ...ActivityLogResource }
+            ... on DeniedDashboardAccess { ...ActivityLogCommon ...ActivityLogResource }
+            ... on DeniedPageAccess { ...ActivityLogCommon }
+            ... on PageAccess { ...ActivityLogCommon }
+            ... on FileDownload { ...ActivityLogCommon }
+            ... on ScimIntegrationAccess { ...ActivityLogCommon }
+          }
+        GRAPHQL
+
+        # Fields common to ALL ActivityLogUnion members. Spread inside each member's
+        # inline fragment. `__fragment_type` is intentionally omitted; the union-level
+        # `__typename` is selected in :ActivityLog above.
+        fragment :ActivityLogCommon, <<~GRAPHQL
+          fragment ActivityLogCommon on BaseActivityLogInterface {
+            id
+            activityType
+            source
+            userType
+            accountStatus
+            becomingEmail
+            content
+            resourceId
+            resourceName
+            resourceType
+            createdAt {
+              dateTime
+              timeZone
+            }
+            user {
+              id
+              email
+              name
+            }
+          }
+        GRAPHQL
+
+        # Dashboard-member-only fields (parent + visibility of the dashboard resource).
+        fragment :ActivityLogResource, <<~GRAPHQL
+          fragment ActivityLogResource on BaseDashboardActivityLogInterface {
+            parentResourceId
+            parentResourceName
+            parentResourceType
+            resource {
+              __typename
+              isVisible {
+                value
+                message
+              }
+            }
+          }
+        GRAPHQL
+      end
+    end
+  end
+end

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

@@ -0,0 +1,29 @@
+module Ecoportal
+  module API
+    class GraphQL
+      class Fragment
+        fragment :AuthLog, <<~GRAPHQL
+          fragment AuthLog on AuthLog {
+            id
+            event
+            source
+            loginMethod
+            host
+            ipAddress
+            referrer
+            userAgent
+            createdAt {
+              dateTime
+              timeZone
+            }
+            targetUser {
+              id
+              email
+              name
+            }
+          }
+        GRAPHQL
+      end
+    end
+  end
+end

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

@@ -0,0 +1,14 @@
+module Ecoportal
+  module API
+    class GraphQL
+      class Fragment
+        fragment :AuthorizationResult, <<~GRAPHQL
+          fragment AuthorizationResult on AuthorizationResult {
+            value
+            message
+          }
+        GRAPHQL
+      end
+    end
+  end
+end

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

@@ -17,6 +17,7 @@ module Ecoportal
               active
               id
               name
+              aiGenerated
             }
           }
         GRAPHQL

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

@@ -0,0 +1,31 @@
+module Ecoportal
+  module API
+    class GraphQL
+      class Fragment
+        fragment :MinimalDashboard, <<~GRAPHQL
+          fragment MinimalDashboard on MinimalDashboard {
+            id
+            name
+            global
+            weight
+            parentResource
+            parentResourceId
+            parentResourceType
+            permissionType
+            owner {
+              id
+              email
+              name
+            }
+            register {
+              id
+              name
+              iconName
+              filterTags
+            }
+          }
+        GRAPHQL
+      end
+    end
+  end
+end