ecoportal-api-graphql 1.3.16 → 2.0.0

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

@@ -0,0 +1,38 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        # A single "System Access Log" entry, returned by
+        # `currentOrganization.activityLogs` (ActivityLogUnionConnection). Read-only.
+        #
+        # `ActivityLogUnion` is a UNION over 9 members:
+        #   DashboardAccess, DashboardCreate, DashboardDelete, DashboardUpdate,
+        #   DeniedDashboardAccess, DeniedPageAccess, FileDownload, PageAccess,
+        #   ScimIntegrationAccess.
+        # This models the field set COMMON to ALL members and passes the concrete
+        # `__typename` through. The Dashboard* members additionally expose
+        # `parentResource*` + `resource` (see Model::ActivityLog); page/file/scim
+        # members do not, so those live on the Model subclass as nullable embeds.
+        #
+        # Enum-valued fields are exposed as plain strings:
+        # - resourceType: ResourceTypesEnum
+        class ActivityLog < Logic::BaseModel
+          read_only!
+
+          passkey :id
+          # Concrete member type (e.g. 'DashboardAccess', 'PageAccess', 'FileDownload').
+          passthrough :__typename
+          passthrough :activityType
+          passthrough :source
+          passthrough :userType
+          passthrough :accountStatus
+          passthrough :becomingEmail
+          # content: Hash! — free-form activity payload; passed through as a Hash.
+          passthrough :content
+          passthrough :resourceId, :resourceName, :resourceType
+          embeds_one :createdAt, klass: Base::DateTime
+        end
+      end
+    end
+  end
+end

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

@@ -2,14 +2,19 @@
   module API
     class GraphQL
       module Base
-        # Represents one generation version of an AiSummary field.
-        # Returned by generateAiSummary — tracks the prompt, output, token usage, and status.
+        # One generation version of an AI page summary — the `item` of `generatePageSummary`.
+        #
+        # ★ Corrected 2026-07-30 against the live schema. The previous declarations (`prompt`,
+        # `inputTokens`, `outputTokens`, `totalTokens`, `resourceType`, `ratings`) do not exist on
+        # `AiSummaryVersion` and always read nil. The real fields are: aiSummary, alreadyRated,
+        # createdAt, dataFieldLogs, generationErrors, id, pagePatchVer, status.
+        #
+        # `dataFieldLogs` / `generationErrors` / `createdAt` are left unmodelled until their own
+        # shapes are verified — select and model them deliberately rather than by assumption.
         class AiSummaryVersion < Logic::BaseModel
-          passkey :id
-          passthrough :aiSummary, :status, :prompt
-          passthrough :inputTokens, :outputTokens, :totalTokens
-          passthrough :resourceType # "field" | "stage" | "page"
-          passarray :ratings        # [[user_id, score], ...]
+          passkey     :id
+          passthrough :aiSummary, :status, :pagePatchVer
+          passboolean :alreadyRated
         end
       end
     end

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

@@ -0,0 +1,24 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        # System access log entry (SCIM / security auditing), returned by
+        # `Organization.authLogs`. Read-only.
+        #
+        # Enum-valued fields are exposed as plain strings:
+        # - event: 'LOGIN' | 'LOGOUT' | 'PASSWORD_CHANGE' | 'PASSWORD_RESET_REQUEST'
+        # - loginMethod: 'PASSWORD' | 'SAML' | 'MAGIC_LINK' | 'REDIRECT' | 'OAUTH'
+        # - source: 'WEB' | 'MOBILE'
+        class AuthLog < Logic::BaseModel
+          read_only!
+
+          passkey :id
+          passthrough :event, :source
+          passthrough :loginMethod
+          passthrough :host, :ipAddress, :referrer, :userAgent
+          embeds_one :createdAt, klass: Base::DateTime
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        # AuthorizationResult — the result of a permission / ability check (a `canXXX` field).
+        #   value:   Boolean!  — whether the action is allowed
+        #   message: String    — human-readable reason when denied
+        #   reasons: FailureReasons — structured reasons (not modelled here; omitted from the
+        #                         :AuthorizationResult fragment to avoid pulling that subtree).
+        # Reusable node type behind the schema's many `canXXX: AuthorizationResult` fields.
+        class AuthorizationResult < Logic::BaseModel
+          read_only!
+
+          passboolean :value
+          passthrough :message
+        end
+      end
+    end
+  end
+end

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

@@ -3,7 +3,13 @@ module Ecoportal
     class GraphQL
       module Base
         class ContractorEntity
+          # Convenience mutators over the read-model `associatedPeopleIds` / `leadContractorIds`
+          # arrays. They push/delete plain ids so that `Input::ContractorEntity::Update.from_model`
+          # can later emit the IdDiff (additions/removals) against `original_doc`.
           module MemberChanges
+            # Associates one or more people. When `lead: true`, also marks them as leads.
+            # @param values [Array<String, Hash, Person, Enumerable>] ids (or things resolvable to ids).
+            # @param lead [Boolean] whether the associated people are also lead contractors.
             def associate(*values, lead: false)
               ids = to_person_ids(*values)
 
@@ -15,7 +21,9 @@ module Ecoportal
               end
             end
 
-            def dissassociate(*values)
+            # Disassociates one or more people (also removing them as leads).
+            # @param values [Array<String, Hash, Person, Enumerable>] ids (or resolvable to ids).
+            def disassociate(*values)
               ids = to_person_ids(*values)
 
               associatedPeopleIds.tap do |associated|
@@ -23,7 +31,10 @@ module Ecoportal
                 associated.delete!(*ids)
               end
             end
+            # @deprecated Backwards-compatible alias for the original misspelling.
+            alias_method :dissassociate, :disassociate
 
+            # Marks one or more people as lead contractors (associating them if not already).
             def lead!(*values)
               ids = to_person_ids(*values)
 
@@ -33,6 +44,7 @@ module Ecoportal
               end
             end
 
+            # Removes one or more people from the lead contractors list.
             def unlead!(*values)
               ids = to_person_ids(*values)
 
@@ -44,7 +56,7 @@ module Ecoportal
             private
 
             def to_person_ids(*values)
-              to_person_id(values.flatten)
+              Array(to_person_id(values.flatten)).flatten.compact
             end
 
             def to_person_id(value)
@@ -54,9 +66,9 @@ module Ecoportal
               when Ecoportal::API::V1::Person
                 value.id
               when Hash
-                to_person_id(['id'])
-              when Enumarable
-                value.map {|val| to_person_id(val)}.compact
+                value['id'] || value[:id]
+              when Enumerable
+                value.map { |val| to_person_id(val) }.compact
               end
             end
           end

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

@@ -2,11 +2,19 @@ module Ecoportal
   module API
     class GraphQL
       module Base
+        # Verified against the live schema 2026-07-30: activeFileAttachment, activeName,
+        # activeVersion, archive, canDownload, canShow, draft, fileAttachments, fileSize, id,
+        # locations, name, otherTags, tags, token.
+        #
+        # ★ `activeVersionId` was declared here and does NOT exist on the type (it is
+        # `activeVersion`) — it always read nil. `otherTags` was missing, which matters because
+        # `UploadInput.otherTags` is the only way to tag a container.
         class FileContainer < Logic::BaseModel
-          passkey :id
-          passthrough :name, :activeName
-          passthrough :fileSize, :token, :activeVersionId
-          passarray :tags
+          passkey     :id
+          passthrough :name, :activeName, :activeVersion
+          passthrough :fileSize, :token
+          passboolean :draft
+          passarray   :tags, :otherTags
         end
       end
     end

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

@@ -8,6 +8,8 @@ module Ecoportal
           passkey :id
           passthrough :name
           passboolean :active
+          # Whether this classification was AI-generated (2026-07 schema).
+          passboolean :aiGenerated, read_only: true
         end
       end
     end

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

@@ -11,6 +11,9 @@ module Ecoportal
           passkey :id
           passthrough :name, :weight
           passboolean :archived, :published, :visitorManagementEnabled
+          # AI-generated structure support (2026-07 schema).
+          passthrough :aiPrompt, read_only: true
+          passboolean :generating, read_only: true
           embeds_one :updatedAt, klass: Base::DateTime
 
           embeds_many :drafts, klass: :draft_class, order_key: :createdAt

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

@@ -0,0 +1,25 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        # Lightweight dashboard descriptor returned by the `dashboardSearch` connection.
+        # Read-only. For the full dashboard (components, filters, permissions) the
+        # `Dashboard` type is not yet modelled — see docs/worklog.md.
+        #
+        # Enum-valued fields are exposed as plain strings:
+        # - permissionType: 'GLOBAL' | 'RESTRICTED' | 'PRIVATE'
+        # - parentResourceType: DashboardParentResource (REGISTER, REPORTING, TASKS, ...)
+        class MinimalDashboard < Logic::BaseModel
+          read_only!
+
+          passkey :id
+          passthrough :name
+          passthrough :parentResource, :parentResourceId, :parentResourceType
+          passthrough :permissionType
+          passthrough :weight
+          passboolean :global
+        end
+      end
+    end
+  end
+end

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

@@ -8,6 +8,8 @@ module Ecoportal
           passkey :id
           passthrough :name, :companyName
           passthrough :logoUrl, read_only: true
+          # Whether contractor admins may add other contractor admins (2026-07 schema).
+          passboolean :allowContractorAdminsToAddAdmins, read_only: true
         end
       end
     end

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

@@ -1,12 +1,15 @@
-module Ecoportal::API::GraphQL::Base::Page
+module Ecoportal::API::GraphQL::Base::Page
   class DataField
     # Contractor entity selector field.
     # Stores references to ContractorEntity records.
     class ContractorEntities < DataField
-      passarray :contractors # each: { id:, name: }
+      passarray :contractors # staged writes; the READ response uses `contractorEntities`
 
+      # Current contractor-entity ids. The GraphQL response carries them under
+      # `contractorEntities` (CommonPageUnion's contractorEntitiesField), NOT `contractors`
+      # — so read from there. After a contractor_entity_ids= write, prefer the staged value.
       def contractor_entity_ids
-        Array(contractors).map { |c| c.is_a?(Hash) ? c['id'] : c }.compact
+        contractor_ids_from(doc)
       end
 
       def contractor_entity_ids=(ids)
@@ -18,11 +21,31 @@
         self.contractor_entity_ids = ids
       end
 
+      # Dirty only when the effective id SET actually changed — same phantom-dirty class as
+      # CrossReference (READ one key, WRITE another): the default leaf diff flags the field
+      # the moment the `contractors` key appears, even for a no-op restatement or a clear on
+      # an already-empty field.
+      def dirty?
+        contractor_ids_from(doc).sort != contractor_ids_from(original_doc).sort
+      end
+
       def as_input
         return nil unless dirty?
 
         { contractorEntities: { id: id, contractorEntityIds: contractor_entity_ids } }
       end
+
+      private
+
+      # Prefer the staged `contractors` (write shape), fall back to `contractorEntities`
+      # (read shape). Shape-agnostic for both `doc` and `original_doc`, so the comparison
+      # stays correct after `consolidate!` copies the staged shape into the baseline.
+      def contractor_ids_from(source_doc)
+        return [] unless source_doc
+
+        src = source_doc.key?('contractors') ? source_doc['contractors'] : source_doc['contractorEntities']
+        Array(src).map { |c| c.is_a?(Hash) ? c['id'] : c }.compact
+      end
     end
   end
 end

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

@@ -1,24 +1,63 @@
-module Ecoportal::API::GraphQL::Base::Page
+module Ecoportal::API::GraphQL::Base::Page
   class DataField
     # File attachment field.
-    # Writing requires a prior file upload to the REST upload endpoint
-    # to obtain fileContainerIds — see the file-upload TODO in projects/TODO.md.
-    # The file_container_ids= setter can be used once IDs are available.
+    # READ: the fragment selects `items { id fileContainer { id ... } }` — the container id
+    # lives at items[].fileContainer.id, NOT in a `fileContainers` array (live-verified;
+    # the previous reader keyed on a doc key the API never returns).
+    # WRITE: live `FileInput` accepts `items: [ItemInput]` ({id, fileContainerId, position}),
+    # NOT `fileContainerIds`. The backend applies `items` as FULL-REPLACE — any existing item
+    # whose id is not echoed back is destroyed — so `as_input` sends kept items as `{id:}`
+    # and new containers as `{fileContainerId:}`.
+    # `items` is deliberately a plain doc reader, not `passarray`: materialising an ArrayModel
+    # writes `items: []` into the doc of a field read without $content, and a phantom-dirty
+    # empty `items` here doesn't no-op — it DELETES every attachment on the next update.
+    # Container ids come from a prior upload — see FileUpload::Client#upload_all.
     class FileField < DataField
-      passarray :fileContainers # each: { id:, fileName:, ... }
+      # each: { 'id' =>, 'fileContainer' => { 'id' =>, 'activeFileAttachment' => {...} } }
+      def items
+        Array(doc['items'])
+      end
 
       def file_container_ids
-        Array(fileContainers).map { |c| c.is_a?(Hash) ? c['id'] : c }.compact
+        items.map do |item|
+          item.is_a?(Hash) ? item.dig('fileContainer', 'id') : item
+        end.compact
       end
 
+      # Full-replace: containers already on the field keep their item identity;
+      # ids not present in `ids` are removed server-side by omission.
       def file_container_ids=(ids)
-        doc['fileContainers'] = Array(ids).map { |id_val| { 'id' => id_val } }
+        kept = {}
+        items.each do |item|
+          next unless item.is_a?(Hash) && (fc_id = item.dig('fileContainer', 'id'))
+
+          kept[fc_id] ||= item['id']
+        end
+        doc['items'] = Array(ids).map do |fc_id|
+          new_item = { 'fileContainer' => { 'id' => fc_id } }
+          new_item['id'] = kept[fc_id] if kept[fc_id]
+          new_item
+        end
       end
 
       def as_input
         return nil unless dirty?
 
-        { file: { id: id, fileContainerIds: file_container_ids } }
+        { file: { id: id, items: items_input } }
+      end
+
+      private
+
+      def items_input
+        items.map do |item|
+          next unless item.is_a?(Hash)
+
+          if (item_id = item['id'])
+            { id: item_id }
+          else
+            { fileContainerId: item.dig('fileContainer', 'id') }
+          end
+        end.compact
       end
     end
   end

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

@@ -1,8 +1,11 @@
 module Ecoportal::API::GraphQL::Base::Page
   class DataField
     # Image gallery field.
-    # Writing requires a prior file upload to the REST upload endpoint
-    # to obtain fileContainerIds — see the file-upload TODO in projects/TODO.md.
+    # ★ 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`.
     class ImageGallery < DataField
       passarray :fileContainers # each: { id:, fileName:, url:, ... }
 

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

@@ -4,20 +4,16 @@ module Ecoportal::API::GraphQL::Base::Page
       passarray :peopleIds
 
       def people_ids
-        ids = Array(peopleIds)
-        return ids unless ids.empty?
-
-        # Fallback: the read fragment populates `peopleIds`, but if a response ever returns it
-        # null/empty while the expanded `people { id }` nodes ARE present (a partial / non-
-        # $content read), seed from the nodes. The backend write replaces peopleIds wholesale,
-        # so a `people_ids << x` append must start from the existing set or it would WIPE the
-        # field. Mirrors CrossReference's references.nodes fallback. Read key == write key
-        # (peopleIds), so this only widens the read; it never creates phantom-dirty.
-        Array(doc['people']).map { |p| p.is_a?(Hash) ? p['id'] : p }.compact
+        people_ids_from(doc)
       end
 
       def people_ids=(ids)
-        doc['peopleIds'] = Array(ids).compact
+        # An explicit write makes `peopleIds` authoritative for THIS instance: without the
+        # flag, a deliberate clear (`people_ids = []`) on a `peopleIds: null` baseline would
+        # fall back to the `people` nodes on the doc side too, compare equal, and be silently
+        # dropped. The flag confines the fallback to un-written docs.
+        @people_ids_written  = true
+        doc['peopleIds']     = Array(ids).compact
       end
 
       # v2 compat: scripts may set via people_ids= or direct assignment
@@ -25,10 +21,52 @@ module Ecoportal::API::GraphQL::Base::Page
         self.people_ids = ids
       end
 
+      # Dirty only when the effective people-id SET actually changed.
+      #
+      # The read response can carry `peopleIds: null` while still populating the expanded
+      # `people { id }` (and `cachedPeople`) nodes (a partial / non-$content read). The
+      # default key-level leaf diff baselines on `original_doc['peopleIds']` (null), so
+      # writing the SAME id set as already attached looks like a brand-new key and flags
+      # a change — a phantom-dirty update that sends `peopleIds` for a no-op. Compare id
+      # SETS (falling back to `people[].id` on both sides) instead. Mirrors CrossReference's
+      # `references.nodes` fallback / `dirty?` override for the identical disease.
+      def dirty?
+        effective_people_ids.sort != people_ids_from(original_doc).sort
+      end
+
       def as_input
         return nil unless dirty?
 
-        { people: { id: id, peopleIds: Array(peopleIds) } }
+        { people: { id: id, peopleIds: effective_people_ids } }
+      end
+
+      private
+
+      # The id set the client currently means: after an explicit `people_ids=` write the raw
+      # `peopleIds` doc key is authoritative (so `[]` means CLEAR, no fallback); before any
+      # write it is the shape-agnostic read (fallback to `people[].id` nodes). Keeping
+      # `as_input` on the same source as `dirty?` also prevents an explicit clear from
+      # re-serialising fallback-seeded node ids.
+      def effective_people_ids
+        return Array(doc['peopleIds']).compact if @people_ids_written
+
+        people_ids_from(doc)
+      end
+
+      # Extract the people id set from a doc snapshot. `original_doc` is the server baseline
+      # (the diff prev_doc — see Diffable::ClassicDiffService), `doc` carries client changes.
+      # Prefer `peopleIds` when it is present and non-empty (the write shape, and the normal
+      # read shape); fall back to the expanded `people[].id` nodes (the read-only lookup
+      # shape) when `peopleIds` is absent/null/empty — so the comparison is shape-agnostic on
+      # both sides and stays correct after `consolidate!` copies `doc` into `original_doc`.
+      # `people` nodes are a lookup only, never written.
+      def people_ids_from(source_doc)
+        return [] unless source_doc
+
+        ids = Array(source_doc['peopleIds']).compact
+        return ids unless ids.empty?
+
+        Array(source_doc['people']).map { |p| p.is_a?(Hash) ? p['id'] : p }.compact
       end
     end
   end

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

@@ -10,24 +10,12 @@ module Ecoportal
             #
             # A DataField's array attributes (`options`, `peopleIds`, `contractors`,
             # `pages`, `fileContainers`, `items`, ...) are declared with `passarray`,
-            # which registers them as *cascaded* attributes. The default `DiffService`
-            # strips cascaded keys from the flat classic diff (`doc_with_non_cascaded_attributes`)
-            # on the assumption that a later `diff_reduce` pass re-adds them by cascading
-            # into nested `GraphQL::Model` children. DataField arrays are plain hashes /
-            # strings, not `GraphQL::Model` objects, so that re-add never happens and the
-            # array change becomes invisible to the diff (scalar `passthrough` fields are
-            # unaffected). For a leaf model we want every doc key diffed inline, so this
-            # service keeps cascaded keys in place.
-            class LeafDiffService < Ecoportal::API::Common::GraphQL::Model::Diffable::DiffService
-              private
-
-              # Keep all doc keys: leaf-field arrays are data, not nested models.
-              def doc_with_non_cascaded_attributes(json)
-                json
-              end
-            end
-
-            DIFF_CLASS = LeafDiffService
+            # which registers them as *cascaded* attributes invisible to the default
+            # `DiffService` (see `Diffable::LeafDiffService` for the full explanation).
+            # A DataField is a pure leaf model (no nested `GraphQL::Model` children), so
+            # it diffs `flat: true` — the promoted shared `LeafDiffService` keeps the
+            # array doc keys inline.
+            DIFF_CLASS = Ecoportal::API::Common::GraphQL::Model::Diffable::LeafDiffService
             # Map GraphQL __typename values to subclass names.
             TYPE_MAP = {
               'PlainText'          => 'PlainText',
@@ -55,6 +43,12 @@ module Ecoportal
 
             passkey :id
             passthrough :label, :deindex, :genomeSignature
+            # `read_only: true` is load-bearing, not documentation: `description` is readable on
+            # `DataFieldsInterface` but ABSENT from `DataFieldInput` and every per-type member of
+            # it, so a writable accessor would make the field dirty and push a key `updatePage`
+            # cannot accept. The only writer is the `editFieldConfiguration` workflow command
+            # (`Input::WorkflowCommand::EditFieldConfiguration`).
+            passthrough :description, read_only: true
             # __typename is stored under the 'type' key after mapping
             passthrough :type
 

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

@@ -0,0 +1,15 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        # Permissions ? the org-level ability set (Organization.permissions).
+        # Every field is a `canXXX: AuthorizationResult!` permission check. Read-only.
+        # The concrete embeds_one declarations live on Model::Permissions (they reference
+        # Model::AuthorizationResult).
+        class Permissions < Logic::BaseModel
+          read_only!
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,23 @@
+module Ecoportal
+  module API
+    class GraphQL
+      module Base
+        # A single audit entry in a person member's changelog history, returned by
+        # `PersonMember.changelogs` / `Organization.personMemberChangelogs`. Read-only.
+        #
+        # Enum-valued fields are exposed as plain strings:
+        # - operation / accountOperation: 'CREATE' | 'UPDATE' | 'DESTROY'
+        class PersonMemberChangelog < Logic::BaseModel
+          read_only!
+
+          passkey :id
+          passthrough :operation, :accountOperation
+          passthrough :personMemberId, :apiKeyPrefix
+          passboolean :changedByApi
+          passarray :humanReadableDifferences
+          embeds_one :createdAt, klass: Base::DateTime
+        end
+      end
+    end
+  end
+end